@segment/analytics-browser-actions-heap 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@segment/analytics-browser-actions-heap",
+  "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/actions-core": "^3.71.0",
+    "@segment/browser-destination-runtime": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": "*"
+  }
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,43 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import heapDestination, { destination } from '../index'
+import { HEAP_TEST_ENV_ID, mockHeapJsHttpRequest } from '../test-utilities'
+
+const subscriptions = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Track Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {}
+  }
+]
+
+describe('Heap', () => {
+  test('loading', async () => {
+    jest.spyOn(destination, 'initialize')
+
+    mockHeapJsHttpRequest()
+
+    const [event] = await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions })
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+    expect(window.heap.appid).toEqual(HEAP_TEST_ENV_ID)
+  })
+  test('loading with cdn', async () => {
+    jest.spyOn(destination, 'initialize')
+
+    mockHeapJsHttpRequest()
+
+    const [event] = await heapDestination({
+      appId: HEAP_TEST_ENV_ID,
+      subscriptions,
+      hostname: 'cdn.heapanalytics.com',
+      trackingServer: 'https://heapanalytics.com'
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+    expect(window.heap.appid).toEqual(HEAP_TEST_ENV_ID)
+  })
+})

package/src/constants.ts

@@ -0,0 +1 @@
+export const HEAP_SEGMENT_BROWSER_LIBRARY_NAME = 'browser-destination'

package/src/generated-types.ts

@@ -0,0 +1,28 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * The app ID of the environment to which you want to send data. You can find this ID on the [Projects](https://heapanalytics.com/app/manage/projects) page.
+   */
+  appId: string
+  /**
+   * Setting to true will redact all target text on your website. For more information visit the heap [docs page](https://developers.heap.io/docs/web#global-data-redaction-via-disabling-text-capture).
+   */
+  disableTextCapture?: boolean
+  /**
+   * This option is turned off by default to accommodate websites not served over HTTPS. If your application uses HTTPS, we recommend enabling secure cookies to prevent Heap cookies from being observed by unauthorized parties. For more information visit the heap [docs page](https://developers.heap.io/docs/web#securecookie).
+   */
+  secureCookie?: boolean
+  /**
+   * This is an optional setting. This is used to set up first-party data collection. For most cased this should not be set. For more information visit the heap [docs page](https://developers.heap.io/docs/set-up-first-party-data-collection-in-heap).
+   */
+  trackingServer?: string
+  /**
+   * This is an optional setting used to set the host that loads heap-js. This setting is used when heapJS is self-hosted. In most cased this should be left unset. The hostname should not contain https or app id it will be populated like so: https://${hostname}/js/heap-${appId}.js. For more information visit the heap [docs page](https://developers.heap.io/docs/self-hosting-heapjs).
+   */
+  hostname?: string
+  /**
+   * This is an optional setting. When set, nested array items will be sent in as new Heap events. Defaults to 0.
+   */
+  browserArrayLimit?: number
+}

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

@@ -0,0 +1,78 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import {
+  createMockedHeapJsSdk,
+  HEAP_TEST_ENV_ID,
+  identifyUserSubscription,
+  mockHeapJsHttpRequest
+} from '../../test-utilities'
+import heapDestination from '../../index'
+
+describe('#identify', () => {
+  it('should not call identify if user id is not provided and anonymous user id is provided', async () => {
+    mockHeapJsHttpRequest()
+    window.heap = createMockedHeapJsSdk()
+
+    const [identifyUser] = await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions: [identifyUserSubscription] })
+
+    await identifyUser.load(Context.system(), {} as Analytics)
+    const heapIdentifySpy = jest.spyOn(window.heap, 'identify')
+
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        anonymousId: 'anon',
+        traits: {
+          testProp: false
+        }
+      })
+    )
+
+    expect(heapIdentifySpy).not.toHaveBeenCalled()
+  })
+
+  it('should call identify if user id is provided', async () => {
+    mockHeapJsHttpRequest()
+    window.heap = createMockedHeapJsSdk()
+
+    const [identifyUser] = await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions: [identifyUserSubscription] })
+
+    await identifyUser.load(Context.system(), {} as Analytics)
+    const heapIdentifySpy = jest.spyOn(window.heap, 'identify')
+    const heapAddUserPropertiesSpy = jest.spyOn(window.heap, 'addUserProperties')
+
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        anonymousId: 'anon',
+        userId: 'user@example.com'
+      })
+    )
+
+    expect(heapIdentifySpy).toHaveBeenCalledWith('user@example.com')
+    expect(heapAddUserPropertiesSpy).not.toHaveBeenCalled()
+  })
+
+  it('should call addUserProprties if traits are provided', async () => {
+    mockHeapJsHttpRequest()
+    window.heap = createMockedHeapJsSdk()
+
+    const [identifyUser] = await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions: [identifyUserSubscription] })
+
+    await identifyUser.load(Context.system(), {} as Analytics)
+    const heapIdentifySpy = jest.spyOn(window.heap, 'identify')
+    const heapAddUserPropertiesSpy = jest.spyOn(window.heap, 'addUserProperties')
+
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        anonymousId: 'anon',
+        traits: {
+          testProp: false
+        }
+      })
+    )
+
+    expect(heapIdentifySpy).not.toHaveBeenCalled()
+    expect(heapAddUserPropertiesSpy).toHaveBeenCalledWith({ testProp: false })
+  })
+})

package/src/identifyUser/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The user's identity
+   */
+  userId?: string
+  /**
+   * The Segment traits to be forwarded to Heap
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/identifyUser/index.ts

@@ -0,0 +1,41 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { HeapApi } from '../types'
+
+const action: BrowserActionDefinition<Settings, HeapApi, Payload> = {
+  title: 'Identify User',
+  description: 'Sets user identity',
+  platform: 'web',
+  defaultSubscription: 'type = "identify"',
+  fields: {
+    userId: {
+      type: 'string',
+      required: false,
+      description: "The user's identity",
+      label: 'Identity',
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    traits: {
+      type: 'object',
+      required: false,
+      description: 'The Segment traits to be forwarded to Heap',
+      label: 'Traits',
+      default: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  perform: (heap, event) => {
+    if (event.payload.traits) {
+      heap.addUserProperties(event.payload.traits)
+    }
+    if (event.payload.userId) {
+      heap.identify(event.payload.userId)
+    }
+  }
+}
+
+export default action

package/src/index.ts

@@ -0,0 +1,118 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import { HeapApi, UserConfig } from './types'
+import { defaultValues } from '@segment/actions-core'
+import trackEvent from './trackEvent'
+import identifyUser from './identifyUser'
+import { isDefined } from './utils'
+
+declare global {
+  interface Window {
+    heap: HeapApi
+  }
+}
+
+// Switch from unknown to the partner SDK client types
+export const destination: BrowserDestinationDefinition<Settings, HeapApi> = {
+  name: 'Heap Web (Actions)',
+  slug: 'actions-heap-web',
+  mode: 'device',
+  presets: [
+    {
+      name: 'Track Event',
+      subscribe: 'type = "track"',
+      partnerAction: 'trackEvent',
+      mapping: defaultValues(trackEvent.fields)
+    },
+    {
+      name: 'Identify User',
+      subscribe: 'type = "identify"',
+      partnerAction: 'identifyUser',
+      mapping: defaultValues(identifyUser.fields)
+    }
+  ],
+  settings: {
+    // Add any Segment destination settings required here
+    appId: {
+      label: 'Heap app ID',
+      description:
+        'The app ID of the environment to which you want to send data. You can find this ID on the [Projects](https://heapanalytics.com/app/manage/projects) page.',
+      type: 'string',
+      required: true
+    },
+    disableTextCapture: {
+      label: 'Global data redaction via Disabling Text Capture',
+      description:
+        'Setting to true will redact all target text on your website. For more information visit the heap [docs page](https://developers.heap.io/docs/web#global-data-redaction-via-disabling-text-capture).',
+      type: 'boolean',
+      required: false
+    },
+    secureCookie: {
+      label: 'Secure Cookie',
+      description:
+        'This option is turned off by default to accommodate websites not served over HTTPS. If your application uses HTTPS, we recommend enabling secure cookies to prevent Heap cookies from being observed by unauthorized parties. For more information visit the heap [docs page](https://developers.heap.io/docs/web#securecookie).',
+      type: 'boolean',
+      required: false
+    },
+    trackingServer: {
+      label: 'Tracking Server',
+      description:
+        'This is an optional setting. This is used to set up first-party data collection. For most cased this should not be set. For more information visit the heap [docs page](https://developers.heap.io/docs/set-up-first-party-data-collection-in-heap).',
+      type: 'string',
+      required: false
+    },
+    hostname: {
+      label: 'Hostname',
+      description:
+        'This is an optional setting used to set the host that loads heap-js. This setting is used when heapJS is self-hosted. In most cased this should be left unset. The hostname should not contain https or app id it will be populated like so: https://${hostname}/js/heap-${appId}.js. For more information visit the heap [docs page](https://developers.heap.io/docs/self-hosting-heapjs).',
+      type: 'string',
+      required: false
+    },
+    browserArrayLimit: {
+      label: 'Browser Array Limit',
+      description:
+        'This is an optional setting. When set, nested array items will be sent in as new Heap events. Defaults to 0.',
+      type: 'number',
+      required: false
+    }
+  },
+
+  initialize: async ({ settings }, deps) => {
+    if (window.heap) {
+      return window.heap
+    }
+
+    const config: UserConfig = {
+      disableTextCapture: settings.disableTextCapture || false,
+      secureCookie: settings.secureCookie || false
+    }
+
+    if (settings.trackingServer) {
+      config.trackingServer = settings.trackingServer
+    }
+
+    // heap.appid and heap.config must be set before loading heap.js.
+    window.heap = window.heap || []
+    window.heap.appid = settings.appId
+    window.heap.config = config
+
+    if (isDefined(settings.hostname)) {
+      await deps.loadScript(`https://${settings.hostname}/js/heap-${settings.appId}.js`)
+    } else {
+      await deps.loadScript(`https://cdn.heapanalytics.com/js/heap-${settings.appId}.js`)
+    }
+
+    // Explained here: https://stackoverflow.com/questions/14859058/why-does-the-segment-io-loader-script-push-method-names-args-onto-a-queue-which
+    await deps.resolveWhen(() => Object.prototype.hasOwnProperty.call(window, 'heap'), 100)
+
+    return window.heap
+  },
+
+  actions: {
+    trackEvent,
+    identifyUser
+  }
+}
+
+export default browserDestination(destination)

package/src/test-utilities.ts

@@ -0,0 +1,64 @@
+import { HeapApi } from './types'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import nock from 'nock'
+
+export const HEAP_TEST_ENV_ID = '1'
+
+export const createMockedHeapJsSdk = (): HeapApi => {
+  return {
+    appid: HEAP_TEST_ENV_ID,
+    config: {
+      disableTextCapture: true,
+      secureCookie: true
+    },
+    load: jest.fn(),
+    track: jest.fn(),
+    identify: jest.fn(),
+    addUserProperties: jest.fn()
+  }
+}
+export const trackEventSubscription: Subscription = {
+  partnerAction: 'trackEvent',
+  name: 'Track Event',
+  enabled: true,
+  subscribe: 'type = "track"',
+  mapping: {
+    name: {
+      '@path': '$.name'
+    },
+    properties: {
+      '@path': '$.properties'
+    },
+    identity: {
+      '@path': '$.userId'
+    },
+    anonymousId: {
+      '@path': '$.anonymousId'
+    },
+    traits: {
+      '@path': '$.context.traits'
+    }
+  }
+}
+
+export const identifyUserSubscription: Subscription = {
+  partnerAction: 'identifyUser',
+  name: 'Identify User',
+  enabled: true,
+  subscribe: 'type = "identify"',
+  mapping: {
+    anonymousId: {
+      '@path': '$.anonymousId'
+    },
+    userId: {
+      '@path': '$.userId'
+    },
+    traits: {
+      '@path': '$.traits'
+    }
+  }
+}
+
+export const mockHeapJsHttpRequest = (): void => {
+  nock('https://cdn.heapanalytics.com').get(`/js/heap-${HEAP_TEST_ENV_ID}.js`).reply(200, {})
+}

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

@@ -0,0 +1,217 @@
+import { Analytics, Context, Plugin } from '@segment/analytics-next'
+import heapDestination from '../../index'
+import {
+  createMockedHeapJsSdk,
+  HEAP_TEST_ENV_ID,
+  mockHeapJsHttpRequest,
+  trackEventSubscription
+} from '../../test-utilities'
+import { HEAP_SEGMENT_BROWSER_LIBRARY_NAME } from '../../constants'
+
+describe('#trackEvent', () => {
+  let event: Plugin
+  let heapTrackSpy: jest.SpyInstance
+  let addUserPropertiesSpy: jest.SpyInstance
+  let identifySpy: jest.SpyInstance
+
+  beforeAll(async () => {
+    mockHeapJsHttpRequest()
+    window.heap = createMockedHeapJsSdk()
+
+    event = (
+      await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions: [trackEventSubscription], browserArrayLimit: 5 })
+    )[0]
+
+    await event.load(Context.system(), {} as Analytics)
+    heapTrackSpy = jest.spyOn(window.heap, 'track')
+    addUserPropertiesSpy = jest.spyOn(window.heap, 'addUserProperties')
+    identifySpy = jest.spyOn(window.heap, 'identify')
+  })
+
+  beforeEach(() => {
+    jest.resetAllMocks()
+  })
+
+  it('sends events to heap', async () => {
+    await event.track?.(
+      new Context({
+        type: 'track',
+        name: 'hello!',
+        properties: {
+          banana: '📞',
+          apple: [
+            {
+              carrot: 12,
+              broccoli: [
+                {
+                  onion: 'crisp',
+                  tomato: 'fruit'
+                }
+              ]
+            },
+            {
+              carrot: 21,
+              broccoli: [
+                {
+                  tomato: 'vegetable'
+                },
+                {
+                  tomato: 'fruit'
+                },
+                [
+                  {
+                    pickle: 'vinegar'
+                  },
+                  {
+                    pie: 3.1415
+                  }
+                ]
+              ]
+            }
+          ],
+          emptyArray: [],
+          float: 1.2345,
+          booleanTrue: true,
+          booleanFalse: false,
+          nullValue: null,
+          undefinedValue: undefined
+        }
+      })
+    )
+    expect(heapTrackSpy).toHaveBeenCalledTimes(3)
+    expect(heapTrackSpy).toHaveBeenNthCalledWith(1, 'hello! apple item', {
+      carrot: 12,
+      'broccoli.0.onion': 'crisp',
+      'broccoli.0.tomato': 'fruit',
+      segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME
+    })
+    expect(heapTrackSpy).toHaveBeenNthCalledWith(2, 'hello! apple item', {
+      carrot: 21,
+      'broccoli.0.tomato': 'vegetable',
+      'broccoli.1.tomato': 'fruit',
+      'broccoli.2.0.pickle': 'vinegar',
+      'broccoli.2.1.pie': '3.1415',
+      segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME
+    })
+    expect(heapTrackSpy).toHaveBeenNthCalledWith(3, 'hello!', {
+      banana: '📞',
+      float: 1.2345,
+      booleanTrue: true,
+      booleanFalse: false,
+      nullValue: null,
+      segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME,
+      'apple.0.broccoli.0.onion': 'crisp',
+      'apple.0.broccoli.0.tomato': 'fruit',
+      'apple.0.carrot': '12',
+      'apple.1.broccoli.0.tomato': 'vegetable',
+      'apple.1.broccoli.1.tomato': 'fruit',
+      'apple.1.broccoli.2.0.pickle': 'vinegar',
+      'apple.1.broccoli.2.1.pie': '3.1415',
+      'apple.1.carrot': '21'
+    })
+    expect(addUserPropertiesSpy).toHaveBeenCalledTimes(0)
+    expect(identifySpy).toHaveBeenCalledTimes(0)
+  })
+
+  it('limits number of properties in array', async () => {
+    await event.track?.(
+      new Context({
+        type: 'track',
+        name: 'hello!',
+        properties: {
+          testArray1: [{ val: 1 }, { val: 2 }, { val: 3 }],
+          testArray2: [{ val: 4 }, { val: 5 }, { val: 'N/A' }]
+        }
+      })
+    )
+    expect(heapTrackSpy).toHaveBeenCalledTimes(6)
+
+    for (let i = 1; i <= 3; i++) {
+      expect(heapTrackSpy).toHaveBeenNthCalledWith(i, 'hello! testArray1 item', {
+        val: i,
+        segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME
+      })
+    }
+    for (let i = 4; i <= 5; i++) {
+      expect(heapTrackSpy).toHaveBeenNthCalledWith(i, 'hello! testArray2 item', {
+        val: i,
+        segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME
+      })
+    }
+    expect(heapTrackSpy).toHaveBeenNthCalledWith(6, 'hello!', {
+      segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME,
+      'testArray1.0.val': '1',
+      'testArray1.1.val': '2',
+      'testArray1.2.val': '3',
+      'testArray2.0.val': '4',
+      'testArray2.1.val': '5',
+      'testArray2.2.val': 'N/A'
+    })
+  })
+
+  it('should send segment_library property if no other properties were provided', async () => {
+    await event.track?.(
+      new Context({
+        type: 'track',
+        name: 'hello!'
+      })
+    )
+
+    expect(heapTrackSpy).toHaveBeenCalledWith('hello!', {
+      segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME
+    })
+    expect(addUserPropertiesSpy).toHaveBeenCalledTimes(0)
+    expect(identifySpy).toHaveBeenCalledTimes(0)
+  })
+
+  it('should not override segment_library property value if provided by user', async () => {
+    const segmentLibraryValue = 'user-provided-value'
+    const userId = 'TEST_ID77'
+    await event.track?.(
+      new Context({
+        type: 'track',
+        name: 'hello!',
+        properties: {
+          segment_library: segmentLibraryValue
+        },
+        userId
+      })
+    )
+
+    expect(heapTrackSpy).toHaveBeenCalledWith('hello!', {
+      segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME
+    })
+    expect(identifySpy).toHaveBeenCalledWith(userId)
+    expect(addUserPropertiesSpy).toHaveBeenCalledTimes(0)
+  })
+
+  it('should add traits', async () => {
+    const segmentLibraryValue = 'test123'
+    const anonymous_id = 'ANON1'
+    const name = 'Grace Hopper'
+    await event.track?.(
+      new Context({
+        type: 'track',
+        name: 'hello!',
+        properties: {
+          segment_library: segmentLibraryValue
+        },
+        context: {
+          traits: {
+            name
+          }
+        },
+        anonymousId: anonymous_id
+      })
+    )
+
+    expect(heapTrackSpy).toHaveBeenCalledWith('hello!', {
+      segment_library: HEAP_SEGMENT_BROWSER_LIBRARY_NAME
+    })
+    expect(addUserPropertiesSpy).toHaveBeenCalledWith({
+      anonymous_id,
+      name
+    })
+    expect(identifySpy).toHaveBeenCalledTimes(0)
+  })
+})

package/src/trackEvent/generated-types.ts

@@ -0,0 +1,28 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The name of the event.
+   */
+  name: string
+  /**
+   * A JSON object containing additional information about the event that will be indexed by Heap.
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+  /**
+   * a string that uniquely identifies a user, such as an email, handle, or username. This means no two users in one environment may share the same identity. More on identify: https://developers.heap.io/docs/using-identify
+   */
+  identity?: string
+  /**
+   * The segment anonymous identifier for the user
+   */
+  anonymousId?: string
+  /**
+   * An object with key-value properties you want associated with the user. Each property must either be a number or string with fewer than 1024 characters.
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/trackEvent/index.ts

@@ -0,0 +1,123 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { HeapApi } from '../types'
+import { HEAP_SEGMENT_BROWSER_LIBRARY_NAME } from '../constants'
+import { isDefined, flat, flattenProperties } from '../utils'
+
+const action: BrowserActionDefinition<Settings, HeapApi, Payload> = {
+  title: 'Track Event',
+  description: 'Track events',
+  platform: 'web',
+  defaultSubscription: 'type = "track"',
+  fields: {
+    name: {
+      description: 'The name of the event.',
+      label: 'Name',
+      required: true,
+      type: 'string',
+      default: {
+        '@path': '$.event'
+      }
+    },
+    properties: {
+      description: 'A JSON object containing additional information about the event that will be indexed by Heap.',
+      label: 'Properties',
+      required: false,
+      type: 'object',
+      default: {
+        '@path': '$.properties'
+      }
+    },
+    identity: {
+      type: 'string',
+      required: false,
+      label: 'Identity',
+      description:
+        'a string that uniquely identifies a user, such as an email, handle, or username. This means no two users in one environment may share the same identity. More on identify: https://developers.heap.io/docs/using-identify'
+    },
+    anonymousId: {
+      type: 'string',
+      required: false,
+      description: 'The segment anonymous identifier for the user',
+      label: 'Anonymous ID',
+      default: {
+        '@path': '$.anonymousId'
+      }
+    },
+    traits: {
+      label: 'User Properties',
+      type: 'object',
+      description:
+        'An object with key-value properties you want associated with the user. Each property must either be a number or string with fewer than 1024 characters.',
+      default: {
+        '@path': '$.context.traits'
+      }
+    }
+  },
+  perform: (heap, event) => {
+    // Add user properties
+    if (event.payload.anonymousId || isDefined(event.payload?.traits)) {
+      const traits = flat(event.payload?.traits)
+      heap.addUserProperties({
+        ...(isDefined(event.payload.anonymousId) && { anonymous_id: event.payload.anonymousId }),
+        ...(isDefined(traits) && traits)
+      })
+    }
+
+    // Identify user
+    if (event.payload?.identity && isDefined(event.payload?.identity)) {
+      heap.identify(event.payload.identity)
+    }
+
+    // Track Events
+    let eventProperties = Object.assign({}, event.payload.properties)
+    const eventName = event.payload.name
+    const browserArrayLimit = event.settings.browserArrayLimit || 0
+    const browserArrayLimitSet = !!browserArrayLimit
+    let arrayEventsCount = 0
+
+    for (const [key, value] of Object.entries(eventProperties)) {
+      if (browserArrayLimitSet && arrayEventsCount >= browserArrayLimit) {
+        break
+      }
+
+      if (!Array.isArray(value)) {
+        continue
+      }
+
+      delete eventProperties[key]
+      eventProperties = { ...eventProperties, ...flat({ [key]: value }) }
+
+      const arrayLength = value.length
+      let arrayPropertyValues
+      // truncate in case there are multiple array properties
+      if (browserArrayLimitSet && arrayLength + arrayEventsCount > browserArrayLimit) {
+        arrayPropertyValues = value.splice(0, browserArrayLimit - arrayEventsCount)
+      } else {
+        arrayPropertyValues = value
+      }
+
+      arrayEventsCount += arrayLength
+
+      arrayPropertyValues.forEach((arrayPropertyValue) => {
+        const arrayProperties = flattenProperties(arrayPropertyValue)
+        heapTrack(heap, `${eventName} ${key} item`, arrayProperties)
+      })
+    }
+    heapTrack(heap, eventName, eventProperties)
+  }
+}
+
+const heapTrack = (
+  heap: HeapApi,
+  eventName: string,
+  properties: {
+    [k: string]: unknown
+  }
+) => {
+  properties.segment_library = HEAP_SEGMENT_BROWSER_LIBRARY_NAME
+  heap.track(eventName, properties)
+}
+
+export default action

package/src/types.ts

@@ -0,0 +1,22 @@
+export type UserConfig = {
+  trackingServer?: string
+  disableTextCapture: boolean
+  secureCookie: boolean
+}
+
+type UserProperties = {
+  [k: string]: unknown
+}
+
+type EventProperties = {
+  [key: string]: unknown
+}
+
+export type HeapApi = {
+  appid: string
+  track: (eventName: string, eventProperties: EventProperties, library?: string) => void
+  load: () => void
+  config: UserConfig
+  identify: (identity: string) => void
+  addUserProperties: (properties: UserProperties) => void
+}

package/src/utils.ts

@@ -0,0 +1,54 @@
+export function isDefined(value: string | undefined | null | number | object): boolean {
+  if (typeof value === 'object') {
+    return !!value && Object.keys(value).length !== 0
+  }
+  return !(value === undefined || value === null || value === '' || value === 0 || value === '0')
+}
+
+export type Properties = {
+  [k: string]: unknown
+}
+
+type FlattenProperties = object & {
+  [k: string]: string
+}
+
+export function flat(data?: Properties, prefix = ''): FlattenProperties | undefined {
+  if (!isDefined(data)) {
+    return undefined
+  }
+  let result: FlattenProperties = {}
+  for (const key in data) {
+    if (typeof data[key] == 'object' && data[key] !== null) {
+      const flatten = flat(data[key] as Properties, prefix + '.' + key)
+      result = { ...result, ...flatten }
+    } else {
+      const stringifiedValue = stringify(data[key])
+      result[(prefix + '.' + key).replace(/^\./, '')] = stringifiedValue
+    }
+  }
+  return result
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const flattenProperties = (arrayPropertyValue: any) => {
+  let arrayProperties = {}
+  for (const [key, value] of Object.entries(arrayPropertyValue)) {
+    if (typeof value == 'object' && value !== null) {
+      arrayProperties = { ...arrayProperties, ...flat({ [key]: value as Properties }) }
+    } else {
+      arrayProperties = Object.assign(arrayProperties, { [key]: value })
+    }
+  }
+  return arrayProperties
+}
+
+function stringify(value: unknown): string {
+  if (typeof value === 'string') {
+    return value
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return value.toString()
+  }
+  return JSON.stringify(value)
+}

package/tsconfig.json

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