@segment/analytics-browser-actions-utils 1.0.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@segment/analytics-browser-actions-utils",
+  "version": "1.0.0",
+  "license": "MIT",
+  "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.0.0"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": "*"
+  }
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,25 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import segmentUtilitiesDestination, { destination } from '../index'
+
+describe('Segment Utilities Web', () => {
+  test('loads the destination', async () => {
+    const [throttle] = await segmentUtilitiesDestination({
+      throttleWindow: 3000,
+      passThroughCount: 1,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    jest.spyOn(destination, 'initialize')
+
+    await throttle.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+  })
+})

package/src/generated-types.ts

@@ -0,0 +1,12 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * The window of time in milliseconds to throttle events.
+   */
+  throttleWindow?: number
+  /**
+   * Number of events to pass through while waiting for the throttle time to expire.
+   */
+  passThroughCount?: number
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+
+import throttle from './throttle'
+
+export type SegmentUtilitiesInstance = {
+  eventMap: Record<string, { windowStarted: number; receivedCount: number }>
+}
+
+// Switch from unknown to the partner SDK client types
+export const destination: BrowserDestinationDefinition<Settings, SegmentUtilitiesInstance> = {
+  name: 'Segment Utilities Web',
+  slug: 'actions-segment-utilities-web',
+  mode: 'device',
+
+  settings: {
+    throttleWindow: {
+      label: 'Throttle time',
+      description: 'The window of time in milliseconds to throttle events.',
+      type: 'number',
+      default: 3000
+    },
+    passThroughCount: {
+      label: 'Number of events to pass through',
+      description: 'Number of events to pass through while waiting for the throttle time to expire.',
+      type: 'number',
+      default: 1
+    }
+  },
+
+  initialize: async () => {
+    return {
+      eventMap: {}
+    }
+  },
+
+  actions: {
+    throttle
+  }
+}
+
+export default browserDestination(destination)

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

@@ -0,0 +1,379 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import segmentUtilities from '../../index'
+
+let ajs: Analytics
+
+describe('throttle', () => {
+  beforeEach(async () => {
+    ajs = new Analytics({
+      writeKey: 'shall_never_be_revealed'
+    })
+  })
+
+  test('throttles events', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 1,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+  })
+
+  test('does not throttle if no settings provided', async () => {
+    const [throttle] = await segmentUtilities({
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+  })
+
+  test('accept overrides', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 1,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {
+            passThroughCount: 2
+          }
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+  })
+
+  test('ignores invalid overrides', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 1,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {
+            passThroughCount: {
+              '@path': '$.event'
+            }
+          }
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+  })
+
+  test('does not allow any event to pass through if the pass through count is 0', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 0,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+  })
+
+  test('throttles multiple events names separately', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 1,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Stopped' }))
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Stopped' }))
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+  })
+
+  test('Allow n events to pass through during the window', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 3,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+    let passedThrough = 0
+    for (let i = 0; i < 10; i++) {
+      const ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+      if (ctx?.event.integrations?.['Segment.io'] !== false) {
+        passedThrough++
+      }
+    }
+
+    expect(passedThrough).toBe(3)
+
+    const [throttle2] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 8,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle2.load(Context.system(), ajs)
+    passedThrough = 0
+
+    for (let i = 0; i < 10; i++) {
+      const ctx = await throttle2.track?.(new Context({ type: 'track', event: 'Video Played' }))
+      if (ctx?.event.integrations?.['Segment.io'] !== false) {
+        passedThrough++
+      }
+    }
+
+    expect(passedThrough).toBe(8)
+  })
+
+  test('Preserves the integrations object while flipping the Segment destination to false', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 1,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    const integrations = {
+      All: false,
+      'Segment.io': true,
+      'Google Analytics': true,
+      'Customer.io': true,
+      Amplitude: {
+        sessionId: 12345
+      }
+    }
+
+    await throttle.load(Context.system(), ajs)
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played', integrations }))
+
+    expect(ctx?.event.integrations).toEqual(integrations)
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played', integrations }))
+    expect(ctx?.event.integrations).toEqual({ ...integrations, 'Segment.io': false })
+  })
+
+  test('Time-based throttling', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 1,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+
+    // Canada Day
+    jest.spyOn(global.Date, 'now').mockImplementationOnce(() => new Date('2022-07-01T00:00:00.000Z').valueOf())
+
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    // One second later, throttle this event
+    jest.spyOn(global.Date, 'now').mockImplementationOnce(() => new Date('2022-07-01T00:00:01.000Z').valueOf())
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+
+    // Three seconds later, let this event through
+    jest.spyOn(global.Date, 'now').mockImplementationOnce(() => new Date('2022-07-01T00:00:03.100Z').valueOf())
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+    expect(ctx?.event.integrations).not.toBeDefined()
+  })
+
+  test('Complex Time-based throttling', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 2,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+
+    // Canada Day
+    jest.spyOn(global.Date, 'now').mockImplementationOnce(() => new Date('2022-07-01T00:00:00.000Z').valueOf())
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    // One second later, still allowed because of the passThroughCount
+    jest.spyOn(global.Date, 'now').mockImplementationOnce(() => new Date('2022-07-01T00:00:01.000Z').valueOf())
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    // One second later, throttle this event
+    jest.spyOn(global.Date, 'now').mockImplementationOnce(() => new Date('2022-07-01T00:00:02.000Z').valueOf())
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+
+    // One second later, window expired, let this event through
+    jest.spyOn(global.Date, 'now').mockImplementationOnce(() => new Date('2022-07-01T00:00:03.100Z').valueOf())
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+    expect(ctx?.event.integrations).not.toBeDefined()
+  })
+
+  test('Only throttles the events that match the subscription', async () => {
+    const [throttle] = await segmentUtilities({
+      throttleWindow: 3000,
+      passThroughCount: 1,
+      subscriptions: [
+        {
+          partnerAction: 'throttle',
+          name: 'Throttle',
+          enabled: true,
+          subscribe: 'type = "track" and event = "Video Played"',
+          mapping: {}
+        }
+      ]
+    })
+
+    await throttle.load(Context.system(), ajs)
+    let ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Played' }))
+    expect(ctx?.event.integrations).toBeDefined()
+    expect(ctx?.event.integrations?.['Segment.io']).toEqual(false)
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Stopped' }))
+
+    expect(ctx?.event.integrations).not.toBeDefined()
+
+    ctx = await throttle.track?.(new Context({ type: 'track', event: 'Video Stopped' }))
+    expect(ctx?.event.integrations).not.toBeDefined()
+  })
+})

package/src/throttle/generated-types.ts

@@ -0,0 +1,12 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * Override the global pass through count.
+   */
+  passThroughCount?: number | null
+  /**
+   * Override the global throttle time.
+   */
+  throttleWindow?: number | null
+}

package/src/throttle/index.ts

@@ -0,0 +1,69 @@
+import { SegmentUtilitiesInstance } from '..'
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+
+const action: BrowserActionDefinition<Settings, SegmentUtilitiesInstance, Payload> = {
+  title: 'Throttle by event name',
+  description: 'Throttle events sent to Segment. Throttling is on a per event name basis.',
+  platform: 'web',
+  defaultSubscription: 'type = "track"',
+  fields: {
+    passThroughCount: {
+      label: 'Number of events to pass through',
+      description: 'Override the global pass through count.',
+      type: 'integer',
+      allowNull: true
+    },
+    throttleWindow: {
+      label: 'Throttle time',
+      description: 'Override the global throttle time.',
+      type: 'number',
+      allowNull: true
+    }
+  },
+  lifecycleHook: 'before',
+  perform: ({ eventMap }, data) => {
+    const { context, settings, payload } = data
+
+    const overridePassThroughCount = isNaN(Number(payload.passThroughCount))
+      ? undefined
+      : Number(payload.passThroughCount)
+    const overrideThrottleWindow = isNaN(Number(payload.throttleWindow)) ? undefined : Number(payload.throttleWindow)
+
+    const passThroughCount = overridePassThroughCount ?? settings.passThroughCount ?? 1
+    const throttleWindow = overrideThrottleWindow ?? settings.throttleWindow ?? 0
+    const event = context.event.event
+
+    if (!event) {
+      return
+    }
+
+    if (eventMap[event]) {
+      const { windowStarted } = eventMap[event]
+      const now = Date.now()
+      if (now - windowStarted < throttleWindow) {
+        // within the throttle window
+        eventMap[event].receivedCount++
+      } else {
+        eventMap[event] = {
+          // reset the window
+          windowStarted: Date.now(),
+          receivedCount: 1
+        }
+      }
+    } else {
+      // first time we've seen this event, start the window
+      eventMap[event] = {
+        windowStarted: Date.now(),
+        receivedCount: 1
+      }
+    }
+
+    if (eventMap[event].receivedCount > passThroughCount) {
+      context.updateEvent('integrations', { ...context.event.integrations, 'Segment.io': false })
+    }
+  }
+}
+
+export default action

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "baseUrl": "."
+  },
+  "include": ["src"],
+  "exclude": ["dist", "**/__tests__"]
+}