STRATCONN-6465 - [Appcues web] - new destination

packages/browser-destinations/destinations/appcues-web/README.md

@@ -0,0 +1,31 @@
+# @segment/analytics-browser-appcues-web-actions
+
+The Appcues Web browser action destination for use with @segment/analytics-next.
+
+## License
+
+MIT License
+
+Copyright (c) 2025 Segment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Contributing
+
+All third party contributors acknowledge that any contributions they provide will be made under the same open source license that the open source project is provided under.

packages/browser-destinations/destinations/appcues-web/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@segment/analytics-browser-appcues-web-actions",
+  "version": "1.0.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "main": "./dist/cjs",
+  "module": "./dist/esm",
+  "scripts": {
+    "build": "yarn build:esm && yarn build:cjs",
+    "build:cjs": "tsc --module commonjs --outDir ./dist/cjs",
+    "build:esm": "tsc --outDir ./dist/esm"
+  },
+  "typings": "./dist/esm",
+  "dependencies": {
+    "@segment/browser-destination-runtime": "^1.93.0"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": ">=1.55.0"
+  }
+}

packages/browser-destinations/destinations/appcues-web/src/__tests__/initialization.test.ts

@@ -0,0 +1,83 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import AppcuesDestination, { destination } from '../index'
+import { Appcues } from '../types'
+
+describe('Appcues Web initialization', () => {
+  const baseSettings = {
+    accountID: 'test-account-id',
+    region: 'US' as const,
+    enableURLDetection: true
+  }
+
+  const subscriptions = [
+    {
+      partnerAction: 'track',
+      name: 'Track',
+      enabled: true,
+      subscribe: 'type = "track"',
+      mapping: {
+        event: { '@path': '$.event' },
+        properties: { '@path': '$.properties' }
+      }
+    }
+  ]
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+    delete (window as any).Appcues
+    delete (window as any).AppcuesSettings
+  })
+
+  test('initialize loads script and resolves with Appcues instance', async () => {
+    const mockAppcuesInstance: Appcues = {
+      track: jest.fn(),
+      identify: jest.fn(),
+      group: jest.fn(),
+      page: jest.fn()
+    }
+
+    const mockLoadScript = jest.fn().mockResolvedValue(undefined)
+    const mockResolveWhen = jest.fn().mockResolvedValue(undefined)
+
+    jest.spyOn(destination, 'initialize').mockImplementation(async ({ settings }, deps) => {
+      await mockLoadScript()
+      ;(window as any).Appcues = mockAppcuesInstance
+      await mockResolveWhen()
+      return mockAppcuesInstance
+    })
+
+    const [event] = await AppcuesDestination({
+      ...baseSettings,
+      subscriptions
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    expect(destination.initialize).toHaveBeenCalled()
+  })
+
+  test('initialize sets AppcuesSettings with enableURLDetection', async () => {
+    const mockAppcuesInstance: Appcues = {
+      track: jest.fn(),
+      identify: jest.fn(),
+      group: jest.fn(),
+      page: jest.fn()
+    }
+
+    jest.spyOn(destination, 'initialize').mockImplementation(async ({ settings }) => {
+      ;(window as any).AppcuesSettings = { enableURLDetection: settings.enableURLDetection }
+      ;(window as any).Appcues = mockAppcuesInstance
+      return mockAppcuesInstance
+    })
+
+    const [event] = await AppcuesDestination({
+      ...baseSettings,
+      enableURLDetection: false,
+      subscriptions
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    expect((window as any).AppcuesSettings).toEqual({ enableURLDetection: false })
+  })
+})

packages/browser-destinations/destinations/appcues-web/src/constants.ts

@@ -0,0 +1,4 @@
+export const URL = {
+  US: "fast.appcues.com",
+  EU: "fast.eu.appcues.com"
+}

packages/browser-destinations/destinations/appcues-web/src/functions.ts

@@ -0,0 +1,8 @@
+import type { PropValue, Properties } from './types'
+
+export function flatten(input: { [k: string]: unknown }): Properties {
+  const result: Properties = {}
+  for (const [key, val] of Object.entries(input))
+    result[key] = Array.isArray(val) ? val.map(v => typeof v === 'object' ? JSON.stringify(v) : v).join(',') : val as PropValue
+  return result
+}

packages/browser-destinations/destinations/appcues-web/src/group/__tests__/index.test.ts

@@ -0,0 +1,119 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import AppcuesDestination, { destination } from '../../index'
+import { Appcues } from '../../types'
+
+describe('Appcues.group', () => {
+  const settings = {
+    accountID: 'test-account-id',
+    region: 'US' as const,
+    enableURLDetection: true
+  }
+
+  let mockAppcues: Appcues
+  let event: any
+
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockAppcues = {
+        track: jest.fn(),
+        identify: jest.fn(),
+        group: jest.fn(),
+        page: jest.fn()
+      }
+      return Promise.resolve(mockAppcues)
+    })
+  })
+
+  test('group() handled correctly', async () => {
+    const subscriptions: Subscription[] = [
+      {
+        partnerAction: 'group',
+        name: 'Group',
+        enabled: true,
+        subscribe: 'type = "group"',
+        mapping: {
+          groupId: { '@path': '$.groupId' },
+          traits: { '@path': '$.traits' }
+        }
+      }
+    ]
+
+    const context = new Context({
+      messageId: 'ajs-test-message-id',
+      type: 'group',
+      anonymousId: 'anonymous-id-123',
+      userId: 'user-123',
+      groupId: 'group-456',
+      traits: {
+        name: 'Acme Corp',
+        plan: 'enterprise',
+        employees: 100
+      }
+    })
+
+    const [groupEvent] = await AppcuesDestination({
+      ...settings,
+      subscriptions
+    })
+    event = groupEvent
+
+    await event.load(Context.system(), {} as Analytics)
+    await event.group?.(context)
+
+    expect(mockAppcues.group).toHaveBeenCalledWith('group-456', {
+      name: 'Acme Corp',
+      plan: 'enterprise',
+      employees: 100
+    })
+  })
+
+  test('group() flattens nested traits', async () => {
+    const subscriptions: Subscription[] = [
+      {
+        partnerAction: 'group',
+        name: 'Group',
+        enabled: true,
+        subscribe: 'type = "group"',
+        mapping: {
+          groupId: { '@path': '$.groupId' },
+          traits: { '@path': '$.traits' }
+        }
+      }
+    ]
+
+    const context = new Context({
+      messageId: 'ajs-test-message-id',
+      type: 'group',
+      userId: 'user-123',
+      groupId: 'group-456',
+      traits: {
+        name: 'Acme Corp',
+        address: {
+          city: 'New York',
+          country: 'USA'
+        },
+        industries: ['tech', 'finance']
+      }
+    })
+
+    const [groupEvent] = await AppcuesDestination({
+      ...settings,
+      subscriptions
+    })
+    event = groupEvent
+
+    await event.load(Context.system(), {} as Analytics)
+    await event.group?.(context)
+
+    expect(mockAppcues.group).toHaveBeenCalledWith('group-456', {
+      name: 'Acme Corp',
+      address: {
+        city: 'New York',
+        country: 'USA'
+      },
+      industries: 'tech,finance'
+    })
+  })
+})

packages/browser-destinations/destinations/appcues-web/src/group/index.ts

@@ -0,0 +1,34 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Appcues } from '../types'
+import { flatten } from '../functions'
+const action: BrowserActionDefinition<Settings, Appcues, Payload> = {
+  title: 'Group',
+  description: 'Send Segment group events to Appcues.',
+  platform: 'web',
+  fields: {
+    groupId: {
+      label: 'Group ID',
+      description: 'The ID of the group to identify in Appcues.',
+      required: true,
+      type: 'string',
+      default: { '@path': '$.groupId' }
+    },
+    traits: {
+      label: 'User traits',
+      description: 'Properties to associate with the group / account / company.',
+      required: false,
+      type: 'object',
+      default: { '@path': '$.traits' }
+    }
+  },
+  defaultSubscription: 'type = "group"',
+  perform: (appcues, { payload }) => {
+    const { groupId, traits } = payload
+    const traitsFlattened = flatten(traits || {})
+    appcues.group(groupId, traitsFlattened)
+  }
+}
+
+export default action