@segment/analytics-browser-actions-bucket 1.1.0

package/src/group/__tests__/index.test.ts

@@ -0,0 +1,186 @@
+import { Analytics, Context, User } from '@segment/analytics-next'
+import bucketWebDestination, { destination } from '../../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { JSONArray } from '@segment/actions-core/*'
+import { bucketTestHooks, getBucketCallLog } from '../../test-utils'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'group',
+    name: 'Identify Company',
+    enabled: true,
+    subscribe: 'type = "group"',
+    mapping: {
+      groupId: {
+        '@path': '$.groupId'
+      },
+      userId: {
+        '@path': '$.userId'
+      },
+      traits: {
+        '@path': '$.traits'
+      }
+    }
+  }
+]
+
+describe('Bucket.company', () => {
+  bucketTestHooks()
+
+  describe('when logged in', () => {
+    describe('from analytics.js previous session', () => {
+      it('maps parameters correctly to Bucket', async () => {
+        const [bucketPlugin] = await bucketWebDestination({
+          trackingKey: 'testTrackingKey',
+          subscriptions: subscriptions as unknown as JSONArray
+        })
+
+        const analyticsInstance = new Analytics({ writeKey: 'test-writekey' })
+        jest.spyOn(analyticsInstance, 'user').mockImplementation(
+          () =>
+            ({
+              id: () => 'user-id-1'
+            } as User)
+        )
+        await bucketPlugin.load(Context.system(), analyticsInstance)
+
+        jest.spyOn(destination.actions.group, 'perform')
+
+        await bucketPlugin.group?.(
+          new Context({
+            type: 'group',
+            userId: 'user-id-1',
+            groupId: 'group-id-1',
+            traits: {
+              name: 'ACME INC'
+            }
+          })
+        )
+
+        expect(destination.actions.group.perform).toHaveBeenCalledWith(
+          expect.anything(),
+          expect.objectContaining({
+            payload: {
+              userId: 'user-id-1',
+              groupId: 'group-id-1',
+              traits: {
+                name: 'ACME INC'
+              }
+            }
+          })
+        )
+
+        expect(getBucketCallLog()).toStrictEqual([
+          { method: 'init', args: ['testTrackingKey'] },
+          {
+            method: 'user',
+            args: ['user-id-1', {}, { active: false }]
+          },
+          {
+            method: 'company',
+            args: [
+              'group-id-1',
+              {
+                name: 'ACME INC'
+              },
+              'user-id-1'
+            ]
+          }
+        ])
+      })
+    })
+
+    describe('from am identify call', () => {
+      it('maps parameters correctly to Bucket', async () => {
+        const [bucketPlugin] = await bucketWebDestination({
+          trackingKey: 'testTrackingKey',
+          subscriptions: subscriptions as unknown as JSONArray
+        })
+
+        await bucketPlugin.load(Context.system(), new Analytics({ writeKey: 'test-writekey' }))
+
+        jest.spyOn(destination.actions.group, 'perform')
+
+        // Bucket rejects group calls without previous identify calls
+        await window.bucket.user('user-id-1')
+
+        await bucketPlugin.group?.(
+          new Context({
+            type: 'group',
+            userId: 'user-id-1',
+            groupId: 'group-id-1',
+            traits: {
+              name: 'ACME INC'
+            }
+          })
+        )
+
+        expect(destination.actions.group.perform).toHaveBeenCalledWith(
+          expect.anything(),
+          expect.objectContaining({
+            payload: {
+              userId: 'user-id-1',
+              groupId: 'group-id-1',
+              traits: {
+                name: 'ACME INC'
+              }
+            }
+          })
+        )
+
+        expect(getBucketCallLog()).toStrictEqual([
+          { method: 'init', args: ['testTrackingKey'] },
+          {
+            method: 'user',
+            args: ['user-id-1']
+          },
+          {
+            method: 'company',
+            args: [
+              'group-id-1',
+              {
+                name: 'ACME INC'
+              },
+              'user-id-1'
+            ]
+          }
+        ])
+      })
+    })
+  })
+
+  describe('when not logged in', () => {
+    it('should not call Bucket.group', async () => {
+      const [bucketPlugin] = await bucketWebDestination({
+        trackingKey: 'testTrackingKey',
+        subscriptions: subscriptions as unknown as JSONArray
+      })
+
+      const analyticsInstance = new Analytics({ writeKey: 'test-writekey' })
+      await bucketPlugin.load(Context.system(), analyticsInstance)
+
+      jest.spyOn(destination.actions.group, 'perform')
+
+      // Manually mimicking a group call without a userId.
+      // The analytics client will probably never do this if
+      // userId doesn't exist, since the subscription marks it as required
+      await bucketPlugin.group?.(
+        new Context({
+          type: 'group',
+          anonymousId: 'anonymous-id-1',
+          groupId: 'group-id-1',
+          traits: {
+            name: 'ACME INC'
+          }
+        })
+      )
+
+      // TODO: Ideally we should be able to assert that the destination action was never
+      // called, but couldn't figure out how to create an anlytics instance with the plugin
+      // and then trigger the full flow trhough analytics.group() with only an anonymous ID
+      // expect(destination.actions.group.perform).not.toHaveBeenCalled()
+
+      expect(getBucketCallLog()).toStrictEqual([{ method: 'init', args: ['testTrackingKey'] }])
+    })
+  })
+})

package/src/group/generated-types.ts

@@ -0,0 +1,18 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * Unique identifier for the company
+   */
+  groupId: string
+  /**
+   * Unique identifier for the user
+   */
+  userId: string
+  /**
+   * Additional information to associate with the Company in Bucket
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/group/index.ts

@@ -0,0 +1,49 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Bucket } from '../types'
+
+const action: BrowserActionDefinition<Settings, Bucket, Payload> = {
+  title: 'Identify Company',
+  description: 'Creates or updates a Company in Bucket and associates the user with it',
+  platform: 'web',
+  defaultSubscription: 'type = "group"',
+  fields: {
+    groupId: {
+      type: 'string',
+      required: true,
+      description: 'Unique identifier for the company',
+      label: 'Company ID',
+      default: {
+        '@path': '$.groupId'
+      }
+    },
+    userId: {
+      type: 'string',
+      required: true,
+      allowNull: false,
+      description: 'Unique identifier for the user',
+      label: 'User ID',
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    traits: {
+      type: 'object',
+      required: false,
+      description: 'Additional information to associate with the Company in Bucket',
+      label: 'Company Attributes',
+      default: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  perform: (bucket, { payload }) => {
+    // Ensure we never call Bucket.company() without a user ID
+    if (payload.userId) {
+      void bucket.company(payload.groupId, payload.traits, payload.userId)
+    }
+  }
+}
+
+export default action

package/src/identifyUser/__tests__/index.test.ts

@@ -0,0 +1,78 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import bucketWebDestination, { destination } from '../../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { JSONArray } from '@segment/actions-core/*'
+import { bucketTestHooks, getBucketCallLog } from '../../test-utils'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'identifyUser',
+    name: 'Identify User',
+    enabled: true,
+    subscribe: 'type = "identify"',
+    mapping: {
+      userId: {
+        '@path': '$.userId'
+      },
+      traits: {
+        '@path': '$.traits'
+      }
+    }
+  }
+]
+
+describe('Bucket.user', () => {
+  bucketTestHooks()
+
+  test('it maps event parameters correctly to bucket.user', async () => {
+    const [identifyEvent] = await bucketWebDestination({
+      trackingKey: 'testTrackingKey',
+      subscriptions: subscriptions as unknown as JSONArray
+    })
+
+    await identifyEvent.load(Context.system(), new Analytics({ writeKey: 'test-writekey' }))
+
+    jest.spyOn(destination.actions.identifyUser, 'perform')
+
+    await identifyEvent.identify?.(
+      new Context({
+        type: 'identify',
+        userId: 'user-id-1',
+        traits: {
+          name: 'John Doe',
+          email: 'test-email-2@gmail.com',
+          age: 42
+        }
+      })
+    )
+
+    expect(destination.actions.identifyUser.perform).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        payload: {
+          userId: 'user-id-1',
+          traits: {
+            name: 'John Doe',
+            email: 'test-email-2@gmail.com',
+            age: 42
+          }
+        }
+      })
+    )
+
+    expect(getBucketCallLog()).toStrictEqual([
+      { method: 'init', args: ['testTrackingKey'] },
+      {
+        method: 'user',
+        args: [
+          'user-id-1',
+          {
+            name: 'John Doe',
+            email: 'test-email-2@gmail.com',
+            age: 42
+          }
+        ]
+      }
+    ])
+  })
+})

package/src/identifyUser/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * Unique identifier for the User
+   */
+  userId: string
+  /**
+   * Additional information to associate with the User in Bucket
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/identifyUser/index.ts

@@ -0,0 +1,36 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Bucket } from '../types'
+
+const action: BrowserActionDefinition<Settings, Bucket, Payload> = {
+  title: 'Identify User',
+  description: 'Creates or updates a user profile in Bucket. Also initializes Live Satisfaction',
+  platform: 'web',
+  defaultSubscription: 'type = "identify"',
+  fields: {
+    userId: {
+      type: 'string',
+      required: true,
+      description: 'Unique identifier for the User',
+      label: 'User ID',
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    traits: {
+      type: 'object',
+      required: false,
+      description: 'Additional information to associate with the User in Bucket',
+      label: 'User Attributes',
+      default: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  perform: (bucket, { payload }) => {
+    void bucket.user(payload.userId, payload.traits)
+  }
+}
+
+export default action

package/src/index.ts

@@ -0,0 +1,85 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import { Bucket } from './types'
+import identifyUser from './identifyUser'
+import trackEvent from './trackEvent'
+import { defaultValues } from '@segment/actions-core'
+import group from './group'
+
+declare global {
+  interface Window {
+    bucket: Bucket
+  }
+}
+
+export const destination: BrowserDestinationDefinition<Settings, Bucket> = {
+  name: 'Bucket Web (Actions)',
+  description:
+    'Loads the Bucket browser SDK, maps identify(), group() and track() events and enables LiveSatisfaction connections',
+  slug: 'bucket-web',
+  mode: 'device',
+
+  presets: [
+    {
+      name: 'Identify User',
+      subscribe: 'type = "identify"',
+      partnerAction: 'identifyUser',
+      mapping: defaultValues(identifyUser.fields),
+      type: 'automatic'
+    },
+    {
+      name: 'Group',
+      subscribe: 'type = "group"',
+      partnerAction: 'group',
+      mapping: defaultValues(group.fields),
+      type: 'automatic'
+    },
+    {
+      name: 'Track Event',
+      subscribe: 'type = "track"',
+      partnerAction: 'trackEvent',
+      mapping: defaultValues(trackEvent.fields),
+      type: 'automatic'
+    }
+  ],
+
+  settings: {
+    trackingKey: {
+      description: 'Your Bucket App tracking key, found on the tracking page.',
+      label: 'Tracking Key',
+      type: 'string',
+      required: true
+    }
+  },
+
+  actions: {
+    identifyUser,
+    group,
+    trackEvent
+  },
+
+  initialize: async ({ settings, analytics }, deps) => {
+    await deps.loadScript('https://cdn.jsdelivr.net/npm/@bucketco/tracking-sdk@2')
+    await deps.resolveWhen(() => window.bucket != undefined, 100)
+
+    window.bucket.init(settings.trackingKey)
+
+    // If the analytics client already has a logged in user from a
+    // previous session or page, consider the user logged in.
+    // In this case we need to call `bucket.user()` to set the persisted
+    // user id in bucket and initialize Live Satisfaction
+    const segmentPersistedUserId = analytics.user().id()
+    if (segmentPersistedUserId) {
+      void window.bucket.user(segmentPersistedUserId, {}, { active: false })
+    }
+
+    analytics.on('reset', () => {
+      window.bucket.reset()
+    })
+
+    return window.bucket
+  }
+}
+
+export default browserDestination(destination)

package/src/test-utils.ts

@@ -0,0 +1,60 @@
+import nock from 'nock'
+import { Bucket } from 'src/types'
+
+const bucketTestMock = `
+(() => {
+  const noop = () => {};
+
+  const bucketTestInterface = {
+    init: noop,
+    user: noop,
+    company: noop,
+    track: noop,
+    reset: noop
+  };
+
+  const callLog = [];
+
+  window.bucket = new Proxy(bucketTestInterface, {
+    get(bucket, property) {
+      if (typeof bucket[property] === 'function') {
+        return (...args) => {
+          callLog.push({ method: property, args })
+          return bucket[property](...args)
+        }
+      }
+
+      if (property === 'callLog') {
+        return callLog;
+      }
+    }
+  });
+})();
+`
+
+export function bucketTestHooks() {
+  beforeAll(() => {
+    nock.disableNetConnect()
+  })
+
+  beforeEach(() => {
+    nock('https://cdn.jsdelivr.net').get('/npm/@bucketco/tracking-sdk@2').reply(200, bucketTestMock)
+  })
+
+  afterEach(function () {
+    if (!nock.isDone()) {
+      // @ts-expect-error no-unsafe-call
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      this.test.error(new Error('Not all nock interceptors were used!'))
+      nock.cleanAll()
+    }
+  })
+
+  afterAll(() => {
+    nock.enableNetConnect()
+  })
+}
+
+export function getBucketCallLog() {
+  return (window.bucket as unknown as { callLog: Array<{ method: keyof Bucket; args: Array<unknown> }> }).callLog
+}

package/src/trackEvent/__tests__/index.test.ts

@@ -0,0 +1,159 @@
+import { Analytics, Context, User } from '@segment/analytics-next'
+import bucketWebDestination, { destination } from '../../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { JSONArray } from '@segment/actions-core/*'
+import { bucketTestHooks, getBucketCallLog } from '../../test-utils'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Track Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      name: {
+        '@path': '$.name'
+      },
+      userId: {
+        '@path': '$.userId'
+      },
+      properties: {
+        '@path': '$.properties'
+      }
+    }
+  }
+]
+
+describe('trackEvent', () => {
+  bucketTestHooks()
+
+  describe('when logged in', () => {
+    describe('from analytics.js previous session', () => {
+      it('maps parameters correctly to Bucket', async () => {
+        const [bucketPlugin] = await bucketWebDestination({
+          trackingKey: 'testTrackingKey',
+          subscriptions: subscriptions as unknown as JSONArray
+        })
+
+        const analyticsInstance = new Analytics({ writeKey: 'test-writekey' })
+        jest.spyOn(analyticsInstance, 'user').mockImplementation(
+          () =>
+            ({
+              id: () => 'user-id-1'
+            } as User)
+        )
+        await bucketPlugin.load(Context.system(), analyticsInstance)
+
+        jest.spyOn(destination.actions.trackEvent, 'perform')
+
+        const properties = { property1: 'value1', property2: false }
+        await bucketPlugin.track?.(
+          new Context({
+            type: 'track',
+            name: 'Button Clicked',
+            userId: 'user-id-1',
+            properties
+          })
+        )
+
+        expect(destination.actions.trackEvent.perform).toHaveBeenCalledWith(
+          expect.anything(),
+          expect.objectContaining({
+            payload: { name: 'Button Clicked', userId: 'user-id-1', properties }
+          })
+        )
+
+        expect(getBucketCallLog()).toStrictEqual([
+          { method: 'init', args: ['testTrackingKey'] },
+          {
+            method: 'user',
+            args: ['user-id-1', {}, { active: false }]
+          },
+          {
+            method: 'track',
+            args: ['Button Clicked', properties, 'user-id-1']
+          }
+        ])
+      })
+    })
+
+    describe('from am identify call', () => {
+      it('maps parameters correctly to Bucket', async () => {
+        const [bucketPlugin] = await bucketWebDestination({
+          trackingKey: 'testTrackingKey',
+          subscriptions: subscriptions as unknown as JSONArray
+        })
+
+        await bucketPlugin.load(Context.system(), new Analytics({ writeKey: 'test-writekey' }))
+
+        jest.spyOn(destination.actions.trackEvent, 'perform')
+
+        // Bucket rejects group calls without previous identify calls
+        await window.bucket.user('user-id-1')
+
+        const properties = { property1: 'value1', property2: false }
+        await bucketPlugin.track?.(
+          new Context({
+            type: 'track',
+            name: 'Button Clicked',
+            userId: 'user-id-1',
+            properties
+          })
+        )
+
+        expect(destination.actions.trackEvent.perform).toHaveBeenCalledWith(
+          expect.anything(),
+          expect.objectContaining({
+            payload: { name: 'Button Clicked', userId: 'user-id-1', properties }
+          })
+        )
+
+        expect(getBucketCallLog()).toStrictEqual([
+          { method: 'init', args: ['testTrackingKey'] },
+          {
+            method: 'user',
+            args: ['user-id-1']
+          },
+          {
+            method: 'track',
+            args: ['Button Clicked', properties, 'user-id-1']
+          }
+        ])
+      })
+    })
+  })
+
+  describe('when not logged in', () => {
+    it('should not call Bucket.group', async () => {
+      const [bucketPlugin] = await bucketWebDestination({
+        trackingKey: 'testTrackingKey',
+        subscriptions: subscriptions as unknown as JSONArray
+      })
+
+      const analyticsInstance = new Analytics({ writeKey: 'test-writekey' })
+      await bucketPlugin.load(Context.system(), analyticsInstance)
+
+      jest.spyOn(destination.actions.trackEvent, 'perform')
+
+      // Manually mimicking a track call without a userId.
+      // The analytics client will probably never do this if
+      // userId doesn't exist, since the subscription marks it as required
+      const properties = { property1: 'value1', property2: false }
+      await bucketPlugin.track?.(
+        new Context({
+          type: 'track',
+          name: 'Button Clicked',
+          anonymousId: 'user-id-1',
+          properties
+        })
+      )
+
+      // TODO: Ideally we should be able to assert that the destination action was never
+      // called, but couldn't figure out how to create an anlytics instance with the plugin
+      // and then trigger the full flow trhough analytics.track() with only an anonymous ID
+      // expect(destination.actions.trackEvent.perform).not.toHaveBeenCalled()
+
+      expect(getBucketCallLog()).toStrictEqual([{ method: 'init', args: ['testTrackingKey'] }])
+    })
+  })
+})