@segment/analytics-browser-actions-commandbar 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@segment/analytics-browser-actions-commandbar",
+  "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,46 @@
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { Analytics, Context } from '@segment/analytics-next'
+import commandBarDestination, { destination } from '../index'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Show',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      event_name: {
+        '@path': '$.event'
+      },
+      event_metadata: {
+        '@path': '$.properties'
+      }
+    }
+  }
+]
+
+describe('CommandBar initialization', () => {
+  test('can load CommandBar with just orgId', async () => {
+    const [event] = await commandBarDestination({
+      orgId: '05f077f2',
+      subscriptions
+    })
+    jest.spyOn(destination, 'initialize')
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+
+    const scripts = window.document.querySelectorAll('script')
+    expect(scripts).toMatchInlineSnapshot(`
+      NodeList [
+        <script>
+          // the emptiness
+        </script>,
+        <script
+          src="https://api.commandbar.com/latest/05f077f2?version=2"
+          type="text/javascript"
+        />,
+      ]
+    `)
+  })
+})

package/src/generated-types.ts

@@ -0,0 +1,12 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * The ID of your CommandBar organization.
+   */
+  orgId: string
+  /**
+   * If enabled, CommandBar will be deployed to your site automatically and you can remove the snippet from your source code.
+   */
+  deploy?: boolean
+}

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

@@ -0,0 +1,153 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import commandBarDestination, { destination } from '../../index'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'identifyUser',
+    name: 'Identify User',
+    enabled: true,
+    subscribe: 'type = "identify"',
+    mapping: {
+      userId: {
+        '@path': '$.userId'
+      },
+      traits: {
+        '@path': '$.traits'
+      },
+      hmac: {
+        '@path': '$.context.CommandBar.hmac'
+      },
+      formFactor: {
+        '@path': '$.context.CommandBar.formFactor'
+      }
+    }
+  }
+]
+
+describe('CommandBar.boot when with deploy enabled', () => {
+  const settings = {
+    orgId: 'xxxxxxxx'
+  }
+  let mockCommandBarBoot: jest.Mock<any, any>
+  let mockCommandBarMetadataBatch: jest.Mock<any, any>
+
+  let identifyUser: any
+
+  beforeEach(async () => {
+    const [identifyUserPlugin] = await commandBarDestination({
+      ...settings,
+      subscriptions
+    })
+
+    identifyUser = identifyUserPlugin
+
+    mockCommandBarBoot = jest.fn()
+    mockCommandBarMetadataBatch = jest.fn()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      const mockedWithBoot = {
+        boot: mockCommandBarBoot,
+        addMetadataBatch: mockCommandBarMetadataBatch,
+        trackEvent: jest.fn()
+      }
+      return Promise.resolve(mockedWithBoot)
+    })
+    await identifyUser.load(Context.system(), {} as Analytics)
+  })
+
+  it('Can add metadata via identify', async () => {
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        userId: 'test-user',
+        traits: {
+          foo: 'bar'
+        }
+      })
+    )
+
+    expect(mockCommandBarMetadataBatch).toHaveBeenCalledWith({ foo: 'bar' }, true)
+    expect(mockCommandBarBoot).not.toHaveBeenCalled()
+  })
+})
+
+describe('CommandBar.addMetadataBatch with deploy disabled', () => {
+  const settings = {
+    orgId: 'xxxxxxxx',
+    deploy: true
+  }
+  let mockCommandBarBoot: jest.Mock<any, any>
+  let mockCommandBarMetadataBatch: jest.Mock<any, any>
+
+  let identifyUser: any
+
+  beforeEach(async () => {
+    const [identifyUserPlugin] = await commandBarDestination({
+      ...settings,
+      subscriptions
+    })
+
+    identifyUser = identifyUserPlugin
+
+    mockCommandBarBoot = jest.fn()
+    mockCommandBarMetadataBatch = jest.fn()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      const mockedWithBoot = {
+        boot: mockCommandBarBoot,
+        addMetadataBatch: mockCommandBarMetadataBatch,
+        trackEvent: jest.fn()
+      }
+      return Promise.resolve(mockedWithBoot)
+    })
+    await identifyUser.load(Context.system(), {} as Analytics)
+  })
+
+  it('Can boot via identify', async () => {
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        userId: 'test-user',
+        traits: {
+          foo: 'bar'
+        }
+      })
+    )
+
+    expect(mockCommandBarBoot).toHaveBeenCalledWith('test-user', { foo: 'bar' }, {})
+    expect(mockCommandBarMetadataBatch).not.toHaveBeenCalled()
+  })
+
+  it('Can pass instanceAttributes to boot', async () => {
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        userId: 'test-user',
+        traits: {
+          foo: 'bar'
+        },
+        context: {
+          CommandBar: {
+            hmac: 'x',
+            formFactor: {
+              type: 'inline',
+              rootElement: 'commandbar-inline-root'
+            }
+          }
+        }
+      })
+    )
+
+    expect(mockCommandBarBoot).toHaveBeenCalledWith(
+      'test-user',
+      { foo: 'bar' },
+      {
+        hmac: 'x',
+        formFactor: {
+          type: 'inline',
+          rootElement: 'commandbar-inline-root'
+        }
+      }
+    )
+    expect(mockCommandBarMetadataBatch).not.toHaveBeenCalled()
+  })
+})

package/src/identifyUser/generated-types.ts

@@ -0,0 +1,24 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The user's id
+   */
+  userId: string
+  /**
+   * Identify users with an HMAC of their user ID; this enables end user customizable shortcuts and other features. [Learn about identity verification](https://app.commandbar.com/identity-verification).
+   */
+  hmac?: string
+  /**
+   * Configures the way the bar is displayed. An 'inline' bar is always visible and hosted within an element on your page. A 'modal' bar will display in a modal dialog when open.
+   */
+  formFactor?: {
+    [k: string]: unknown
+  }
+  /**
+   * The Segment traits to be forwarded to CommandBar
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/identifyUser/index.ts

@@ -0,0 +1,66 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import { CommandBarClientSDK, FormFactorConfig } from '../types'
+import type { Payload } from './generated-types'
+
+const action: BrowserActionDefinition<Settings, CommandBarClientSDK, Payload> = {
+  title: 'Identify User',
+  description:
+    'Set attributes for the user in CommandBar. If "Deploy via Segment" is enabled, then also boot CommandBar for the user, which makes CommandBar available to the user.',
+  platform: 'web',
+  defaultSubscription: 'type = "identify"',
+  fields: {
+    userId: {
+      type: 'string',
+      required: true,
+      description: "The user's id",
+      label: 'User ID',
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    hmac: {
+      description:
+        'Identify users with an HMAC of their user ID; this enables end user customizable shortcuts and other features. [Learn about identity verification](https://app.commandbar.com/identity-verification).',
+      label: 'HMAC',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.context.CommandBar.hmac'
+      }
+    },
+    formFactor: {
+      description:
+        "Configures the way the bar is displayed. An 'inline' bar is always visible and hosted within an element on your page. A 'modal' bar will display in a modal dialog when open.",
+      label: 'Event Metadata',
+      type: 'object',
+      required: false,
+      default: {
+        '@path': '$.context.CommandBar.formFactor'
+      }
+    },
+    traits: {
+      type: 'object',
+      required: false,
+      description: 'The Segment traits to be forwarded to CommandBar',
+      label: 'Traits',
+      default: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  perform: (CommandBar, event) => {
+    const traits = event.payload.traits || {}
+
+    if (event.settings.deploy) {
+      void CommandBar.boot(event.payload.userId, traits, {
+        ...(!!event.payload.hmac && { hmac: event.payload.hmac }),
+        ...(!!event.payload.formFactor && { formFactor: event.payload.formFactor as FormFactorConfig })
+      })
+    } else {
+      CommandBar.addMetadataBatch(traits, true)
+    }
+  }
+}
+
+export default action

package/src/index.ts

@@ -0,0 +1,75 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import { initScript } from './init-script'
+import { CommandBarClientSDK } from './types'
+
+import identifyUser from './identifyUser'
+import { defaultValues } from '@segment/actions-core'
+
+import trackEvent from './trackEvent'
+
+declare global {
+  interface Window {
+    CommandBar: CommandBarClientSDK
+  }
+}
+
+export const destination: BrowserDestinationDefinition<Settings, CommandBarClientSDK> = {
+  name: 'CommandBar',
+  slug: 'actions-commandbar',
+  mode: 'device',
+
+  settings: {
+    orgId: {
+      description: 'The ID of your CommandBar organization.',
+      label: 'Organization ID',
+      type: 'string',
+      required: true
+    },
+    deploy: {
+      description:
+        'If enabled, CommandBar will be deployed to your site automatically and you can remove the snippet from your source code.',
+      label: 'Deploy via Segment',
+      type: 'boolean',
+      required: false
+    }
+  },
+
+  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)
+    }
+  ],
+
+  initialize: async ({ settings }, deps) => {
+    if (!window.CommandBar) {
+      initScript(settings.orgId)
+    }
+
+    await deps.resolveWhen(() => Object.prototype.hasOwnProperty.call(window, 'CommandBar'), 100)
+
+    // Older CommandBar snippets initialize a proxy that traps all field access including `then`
+    // `then` is called implicitly on the return value of an async function on await
+    // So, we need to remove that behavior for the promise to resolve
+    Object.assign(window.CommandBar, { then: undefined })
+
+    return window.CommandBar
+  },
+
+  actions: {
+    identifyUser,
+    trackEvent
+  }
+}
+
+export default browserDestination(destination)

package/src/init-script.ts

@@ -0,0 +1,86 @@
+/* eslint-disable */
+// @ts-nocheck
+
+export function initScript(orgId) {
+  var o = orgId,
+    n = ['Object.assign', 'Symbol', 'Symbol.for'].join('%2C'),
+    a = window
+  function t(o, n) {
+    void 0 === n && (n = !1),
+      'complete' !== document.readyState &&
+        window.addEventListener('load', t.bind(null, o, n), { capture: !1, once: !0 })
+    var a = document.createElement('script')
+    ;(a.type = 'text/javascript'), (a.async = n), (a.src = o), document.head.appendChild(a)
+  }
+  function r() {
+    var n
+    if (void 0 === a.CommandBar) {
+      delete a.__CommandBarBootstrap__
+      var r = Symbol.for('CommandBar::configuration'),
+        e = Symbol.for('CommandBar::orgConfig'),
+        c = Symbol.for('CommandBar::disposed'),
+        i = Symbol.for('CommandBar::isProxy'),
+        m = Symbol.for('CommandBar::queue'),
+        l = Symbol.for('CommandBar::unwrap'),
+        d = [],
+        s = localStorage.getItem('commandbar.lc'),
+        u = s && s.includes('local') ? 'http://localhost:8000' : 'https://api.commandbar.com',
+        f = Object.assign(
+          (((n = {})[r] = { uuid: o }),
+          (n[e] = {}),
+          (n[c] = !1),
+          (n[i] = !0),
+          (n[m] = new Array()),
+          (n[l] = function () {
+            return f
+          }),
+          n),
+          a.CommandBar
+        ),
+        p = ['addCommand', 'boot'],
+        y = f
+      Object.assign(f, {
+        shareCallbacks: function () {
+          return {}
+        },
+        shareContext: function () {
+          return {}
+        }
+      }),
+        (a.CommandBar = new Proxy(f, {
+          get: function (o, n) {
+            if (
+              n === 'then' ||
+              n === 'toJSON' ||
+              n === '$$typeof' ||
+              n === '@@__IMMUTABLE_RECORD__@@' ||
+              n === 'hasAttribute' ||
+              n === 'asymmetricMatch'
+            ) {
+              return Reflect.get(...arguments)
+            }
+            return n in y
+              ? f[n]
+              : p.includes(n)
+              ? function () {
+                  var o = Array.prototype.slice.call(arguments)
+                  return new Promise(function (a, t) {
+                    o.unshift(n, a, t), f[m].push(o)
+                  })
+                }
+              : function () {
+                  var o = Array.prototype.slice.call(arguments)
+                  o.unshift(n), f[m].push(o)
+                }
+          }
+        })),
+        null !== s && d.push('lc='.concat(s)),
+        d.push('version=2'),
+        t(''.concat(u, '/latest/').concat(o, '?').concat(d.join('&')), !0)
+    }
+  }
+  void 0 === Object.assign || 'undefined' == typeof Symbol || void 0 === Symbol.for
+    ? ((a.__CommandBarBootstrap__ = r),
+      t('https://polyfill.io/v3/polyfill.min.js?version=3.101.0&callback=__CommandBarBootstrap__&features=' + n))
+    : r()
+}

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

@@ -0,0 +1,63 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import commandBarDestination, { destination } from '../../index'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Track Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      event_name: {
+        '@path': '$.event'
+      },
+      event_metadata: {
+        '@path': '$.properties'
+      }
+    }
+  }
+]
+
+describe('CommandBar.trackEvent', () => {
+  const settings = {
+    orgId: 'xxxxxxxx'
+  }
+  let mockCommandBarTrackEvent: jest.Mock<any, any>
+
+  let plugin: any
+
+  beforeEach(async () => {
+    const [commandBarPlugin] = await commandBarDestination({
+      ...settings,
+      subscriptions
+    })
+
+    plugin = commandBarPlugin
+
+    mockCommandBarTrackEvent = jest.fn()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      const mockedWithTrack = {
+        boot: jest.fn(),
+        addMetadataBatch: jest.fn(),
+        trackEvent: mockCommandBarTrackEvent
+      }
+      return Promise.resolve(mockedWithTrack)
+    })
+    await plugin.load(Context.system(), {} as Analytics)
+  })
+
+  it('Sends events to CommandBar', async () => {
+    await plugin.track?.(
+      new Context({
+        type: 'track',
+        event: 'example-event',
+        properties: {
+          foo: 'bar'
+        }
+      })
+    )
+
+    expect(mockCommandBarTrackEvent).toHaveBeenCalledWith('example-event', { foo: 'bar' })
+  })
+})

package/src/trackEvent/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The name of the event.
+   */
+  event_name: string
+  /**
+   * Optional metadata describing the event.
+   */
+  event_metadata?: {
+    [k: string]: unknown
+  }
+}

package/src/trackEvent/index.ts

@@ -0,0 +1,40 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import { CommandBarClientSDK } from '../types'
+import type { Payload } from './generated-types'
+
+const action: BrowserActionDefinition<Settings, CommandBarClientSDK, Payload> = {
+  title: 'Track Event',
+  description: "Submit an event's properties as CommandBar metaData.",
+  platform: 'web',
+  defaultSubscription: 'type = "track"',
+
+  fields: {
+    event_name: {
+      description: 'The name of the event.',
+      label: 'Event Name',
+      type: 'string',
+      required: true,
+      default: {
+        '@path': '$.event'
+      }
+    },
+    event_metadata: {
+      description: 'Optional metadata describing the event.',
+      label: 'Event Metadata',
+      type: 'object',
+      required: false,
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+
+  perform: (CommandBar, event) => {
+    if (event.payload.event_name) {
+      CommandBar.trackEvent(event.payload.event_name, event.payload.event_metadata || {})
+    }
+  }
+}
+
+export default action

package/src/types.ts

@@ -0,0 +1,24 @@
+export type ModalFormFactor = { type: 'modal' }
+export type InlineFormFactor = { type: 'inline'; rootElement: string | HTMLElement }
+
+export type FormFactorConfig = ModalFormFactor | InlineFormFactor
+
+export type UserAttributes = Record<string, unknown>
+
+export type InstanceAttributes = {
+  canOpenEditor: boolean
+  hmac?: string
+  formFactor: FormFactorConfig
+}
+
+export type ContextLoader = (chosenValues?: undefined | Record<string, unknown[]>) => unknown
+
+export type Metadata = Record<string, unknown>
+
+export type CommandBarClientSDK = {
+  boot(id: string, userAttributes?: UserAttributes, instanceAttributes?: Partial<InstanceAttributes>): Promise<void>
+
+  addMetadataBatch(data: Metadata, addToUserProperties?: boolean): void
+
+  trackEvent(key: string, properties: Metadata): void
+}

package/tsconfig.json

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