@segment/analytics-browser-actions-intercom 1.0.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@segment/analytics-browser-actions-intercom",
+  "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/actions-shared": "^1.53.0",
+    "@segment/browser-destination-runtime": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": "*"
+  }
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,55 @@
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { Analytics, Context } from '@segment/analytics-next'
+import intercomDestination, { destination } from '../index'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Show',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      event_name: {
+        '@path': '$.event'
+      },
+      event_metadata: {
+        '@path': '$.properties'
+      },
+      revenue: {
+        '@path': '$.properties.revenue'
+      },
+      currency: {
+        '@path': '$.properties.currency'
+      }
+    }
+  }
+]
+
+describe('Intercom (actions)', () => {
+  test('loads Intercom with just appID', async () => {
+    const [event] = await intercomDestination({
+      appId: 'topSecretKey',
+      richLinkProperties: ['article'],
+      activator: '#test',
+      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
+          src="https://widget.intercom.io/widget/topSecretKey"
+          type="text/javascript"
+        />,
+        <script>
+          // the emptiness
+        </script>,
+      ]
+    `)
+  })
+})

package/src/__tests__/utils.test.ts

@@ -0,0 +1,90 @@
+import dayjs from 'dayjs'
+import { convertDateToUnix, filterCustomTraits, getWidgetOptions, isEmpty } from '../utils'
+
+describe('Utils test', () => {
+  describe('date handling tests', () => {
+    test('handles ISO datestrings', () => {
+      const date = new Date()
+      const isoDate = date.toISOString()
+      const unixDate = dayjs(isoDate).unix()
+
+      expect(convertDateToUnix(isoDate)).toEqual(unixDate)
+    })
+
+    test('accepts Unix timestamps in seconds', () => {
+      const date = Math.floor(new Date().getTime() / 1000)
+
+      expect(convertDateToUnix(date)).toEqual(date)
+    })
+
+    test('accepts Unix timestamps in milliseconds', () => {
+      const dateInMS = Math.floor(new Date().getTime())
+      const dateInS = Math.floor(dateInMS / 1000)
+
+      expect(convertDateToUnix(dateInMS)).toEqual(dateInS)
+    })
+  })
+
+  describe('custom trait filtering tests', () => {
+    test('objects & arrays will be filtered out of traits', () => {
+      const traits = {
+        name: 'ibum',
+        badObj: {
+          badKey: 'badValue'
+        },
+        badArray: ['i will be dropped']
+      }
+
+      expect(filterCustomTraits(traits)).toEqual({
+        name: 'ibum'
+      })
+    })
+
+    test('custom traits will be filtered with undefined traits object', () => {
+      const traits = undefined
+      expect(filterCustomTraits(traits)).toEqual({})
+    })
+  })
+
+  describe('isEmpty tests', () => {
+    test('isEmpty returns true if object is empty', () => {
+      const obj = {}
+      expect(isEmpty(obj)).toBe(true)
+    })
+
+    test('isEmpty returns false if object is not empty', () => {
+      const obj = { prop: 'value' }
+      expect(isEmpty(obj)).toBe(false)
+    })
+
+    test('isEmpty works for undefined obj', () => {
+      const obj = undefined
+      expect(isEmpty(obj)).toBe(true)
+    })
+  })
+
+  describe('widget options tests', () => {
+    test('attaches `activator` if activator is not default', () => {
+      const activator = '#my-widget'
+      const hide_default_launcher = undefined
+
+      expect(getWidgetOptions(hide_default_launcher, activator)).toEqual({
+        widget: {
+          activator: activator
+        }
+      })
+    })
+
+    test('attaches `hide_default_launcher` if its not undefined ', () => {
+      const activator = '#my-widget'
+      const hide_default_launcher = false
+
+      expect(getWidgetOptions(hide_default_launcher, activator)).toEqual({
+        widget: {
+          activator: activator
+        },
+        hide_default_launcher: false
+      })
+    })
+  })
+})

package/src/api.ts

@@ -0,0 +1,11 @@
+type method = 'trackEvent' | 'update'
+
+type IntercomApi = {
+  richLinkProperties: string[] | undefined
+  appId: string
+  activator: string | undefined
+}
+
+type IntercomFunction = (method: method, ...args: unknown[]) => void
+
+export type Intercom = IntercomFunction & IntercomApi

package/src/generated-types.ts

@@ -0,0 +1,20 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * The app_id of your Intercom app which will indicate where to store any data.
+   */
+  appId: string
+  /**
+   * By default, Intercom will inject their own inbox button onto the page, but you can choose to use your own custom button instead by providing a CSS selector, e.g. #my-button. You must have the "Show the Intercom Inbox" setting enabled for this to work. The default value is #IntercomDefaultWidget.
+   */
+  activator?: string
+  /**
+   * A list of rich link property keys.
+   */
+  richLinkProperties?: string[]
+  /**
+   * The regional API to use for processing the data
+   */
+  apiBase?: string
+}

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

@@ -0,0 +1,308 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import intercomDestination, { destination } from '../../index'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'identifyCompany',
+    name: 'Show',
+    enabled: true,
+    subscribe: 'type = "group"',
+    mapping: {
+      company: {
+        company_id: { '@path': '$.groupId' },
+        company_custom_traits: {
+          city: {
+            '@path': '$.traits.city'
+          },
+          tech: {
+            '@path': '$.traits.tech'
+          }
+        },
+        name: { '@path': '$.traits.name' },
+        plan: { '@path': '$.traits.plan' },
+        monthly_spend: { '@path': '$.traits.monthlySpend' },
+        created_at: {
+          '@if': {
+            exists: { '@path': '$.traits.createdAt' },
+            then: { '@path': '$.traits.createdAt' },
+            else: { '@path': '$.traits.created_at' }
+          }
+        },
+        size: { '@path': '$.traits.size' },
+        website: { '@path': '$.traits.website' },
+        industry: { '@path': '$.traits.industry' }
+      },
+      hide_default_launcher: {
+        '@if': {
+          exists: { '@path': '$.context.Intercom.hideDefaultLauncher' },
+          then: { '@path': '$.context.Intercom.hideDefaultLauncher' },
+          else: { '@path': '$.context.Intercom.hide_default_launcher' }
+        }
+      }
+    }
+  }
+]
+
+describe('Intercom.update (Company)', () => {
+  const settings = {
+    appId: 'superSecretAppID',
+    activator: '#IntercomDefaultWidget'
+  }
+
+  let mockIntercom: jest.Mock<any, any>
+  let identifyCompany: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [identifyCompanyPlugin] = await intercomDestination({
+      ...settings,
+      subscriptions
+    })
+    identifyCompany = identifyCompanyPlugin
+
+    mockIntercom = jest.fn()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      const mockedWithProps = Object.assign(mockIntercom as any, settings)
+      return Promise.resolve(mockedWithProps)
+    })
+    await identifyCompany.load(Context.system(), {} as Analytics)
+  })
+
+  test('sends an id', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id'
+    })
+
+    await identifyCompany.group?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id'
+      }
+    })
+  })
+
+  test('sends an id & properties', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {
+        name: 'Jeff'
+      }
+    })
+
+    await identifyCompany.group?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id',
+        name: 'Jeff'
+      }
+    })
+  })
+
+  test('converts created_at from ISO-8601 to Unix', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {
+        createdAt: '2018-01-23T22:28:55.111Z'
+      }
+    })
+
+    await identifyCompany.group?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id',
+        created_at: 1516746535
+      }
+    })
+  })
+
+  test('maps created_at properly regardless of it being sent in snake_case or camelCase', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {
+        created_at: '2018-01-23T22:28:55.111Z'
+      }
+    })
+
+    await identifyCompany.group?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id',
+        created_at: 1516746535
+      }
+    })
+  })
+
+  test('sends custom traits', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {
+        wave: 'Capitola',
+        city: 'SF',
+        tech: true
+      }
+    })
+
+    await identifyCompany.group?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id',
+        city: 'SF',
+        tech: true
+      }
+    })
+  })
+
+  test('drops arrays or objects in traits', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {
+        badArray: ['i', 'shall', 'be', 'dropped'],
+        badObject: {
+          rip: 'i will cease to exist'
+        },
+        city: 'Belmar'
+      }
+    })
+
+    await identifyCompany.group?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id',
+        city: 'Belmar'
+      }
+    })
+  })
+
+  test('should set hide_default_launcher if the setting is there', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {
+        name: 'Segment'
+      },
+      context: {
+        Intercom: {
+          hideDefaultLauncher: true
+        }
+      }
+    })
+
+    await identifyCompany.group?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id',
+        name: 'Segment'
+      },
+      hide_default_launcher: true
+    })
+  })
+})
+
+describe('Intercom.update (user) widget options', () => {
+  const settings = {
+    appId: 'superSecretAppID',
+    activator: '#customWidget'
+  }
+
+  let mockIntercom: jest.Mock<any, any>
+  let identifyCompany: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [identifyCompanyPlugin] = await intercomDestination({
+      ...settings,
+      subscriptions
+    })
+    identifyCompany = identifyCompanyPlugin
+
+    mockIntercom = jest.fn()
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      const mockedWithProps = Object.assign(mockIntercom as any, settings)
+      return Promise.resolve(mockedWithProps)
+    })
+    await identifyCompany.load(Context.system(), {} as Analytics)
+  })
+
+  test('sets activator if activator is not #IntercomDefaultWidget', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {}
+    })
+
+    await identifyCompany.group?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id'
+      },
+      widget: {
+        activator: '#customWidget'
+      }
+    })
+  })
+
+  test('should set hide_default_launcher if the setting is there', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {},
+      context: {
+        Intercom: {
+          hideDefaultLauncher: false
+        }
+      }
+    })
+
+    await identifyCompany.identify?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id'
+      },
+      hide_default_launcher: false,
+      widget: {
+        activator: '#customWidget'
+      }
+    })
+  })
+
+  test('maps hide_default_launcher correctly regardless of it being sent in snake_case or camelCase', async () => {
+    const context = new Context({
+      type: 'group',
+      groupId: 'id',
+      traits: {},
+      context: {
+        Intercom: {
+          hideDefaultLauncher: false
+        }
+      }
+    })
+
+    await identifyCompany.identify?.(context)
+
+    expect(mockIntercom).toHaveBeenCalledWith('update', {
+      company: {
+        company_id: 'id'
+      },
+      hide_default_launcher: false,
+      widget: {
+        activator: '#customWidget'
+      }
+    })
+  })
+})

package/src/identifyCompany/generated-types.ts

@@ -0,0 +1,51 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The user's company.
+   */
+  company: {
+    /**
+     * The unique identifier of the company.
+     */
+    company_id: string
+    /**
+     * The name of the company.
+     */
+    name: string
+    /**
+     * The time the company was created in your system.
+     */
+    created_at?: string | number
+    /**
+     * The name of the plan you have associated with the company.
+     */
+    plan?: string
+    /**
+     * The monthly spend of the company, e.g. how much revenue the company generates for your business.
+     */
+    monthly_spend?: number
+    /**
+     * The number of employees in the company.
+     */
+    size?: number
+    /**
+     * The URL for the company website.
+     */
+    website?: string
+    /**
+     * The industry that the company operates in.
+     */
+    industry?: string
+    /**
+     * The custom attributes for the company object.
+     */
+    company_custom_traits?: {
+      [k: string]: unknown
+    }
+  }
+  /**
+   * Selectively show the chat widget. As per [Intercom docs](https://www.intercom.com/help/en/articles/189-turn-off-show-or-hide-the-intercom-messenger), you want to first hide the Messenger for all users inside the Intercom UI using Messenger settings. Then think about how you want to programmatically decide which users you would like to show the widget to.
+   */
+  hide_default_launcher?: boolean
+}

package/src/identifyCompany/index.ts

@@ -0,0 +1,82 @@
+import { InputField } from '@segment/actions-core'
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import { Intercom } from '../api'
+import type { Settings } from '../generated-types'
+import { getCompanyProperties } from '../sharedCompanyProperties'
+import { convertDateToUnix, filterCustomTraits, getWidgetOptions } from '../utils'
+import type { Payload } from './generated-types'
+
+const companyProperties: Record<string, InputField> = getCompanyProperties()
+
+const action: BrowserActionDefinition<Settings, Intercom, Payload> = {
+  title: 'Identify Company',
+  description: 'Create or update a company in Intercom.',
+  defaultSubscription: 'type = "group"',
+  platform: 'web',
+  fields: {
+    company: {
+      description: "The user's company.",
+      label: 'Company',
+      type: 'object',
+      required: true,
+      properties: companyProperties,
+      default: {
+        company_id: { '@path': '$.groupId' },
+        name: { '@path': '$.traits.name' },
+        created_at: {
+          '@if': {
+            exists: { '@path': '$.traits.createdAt' },
+            then: { '@path': '$.traits.createdAt' },
+            else: { '@path': '$.traits.created_at' }
+          }
+        },
+        plan: { '@path': '$.traits.plan' },
+        size: { '@path': '$.traits.size' },
+        website: { '@path': '$.traits.website' },
+        industry: { '@path': '$.traits.industry' },
+        monthly_spend: { '@path': '$.traits.monthly_spend' }
+      }
+    },
+    hide_default_launcher: {
+      description:
+        'Selectively show the chat widget. As per [Intercom docs](https://www.intercom.com/help/en/articles/189-turn-off-show-or-hide-the-intercom-messenger), you want to first hide the Messenger for all users inside the Intercom UI using Messenger settings. Then think about how you want to programmatically decide which users you would like to show the widget to.',
+      label: 'Hide Default Launcher',
+      type: 'boolean',
+      required: false,
+      default: {
+        '@if': {
+          exists: { '@path': '$.context.Intercom.hideDefaultLauncher' },
+          then: { '@path': '$.context.Intercom.hideDefaultLauncher' },
+          else: { '@path': '$.context.Intercom.hide_default_launcher' }
+        }
+      }
+    }
+  },
+  perform: (Intercom, event) => {
+    // remove properties that require extra handling
+    const { company_custom_traits, ...rest } = event.payload.company
+    let company = { ...rest }
+
+    // convert date from ISO-8601 to UNIX
+    if (company?.created_at) {
+      company.created_at = convertDateToUnix(company.created_at)
+    }
+
+    // drop custom objects & arrays
+    const filteredCustomTraits = filterCustomTraits(company_custom_traits)
+
+    // merge filtered custom traits back into company object
+    company = { ...company, ...filteredCustomTraits }
+
+    // get user's widget options
+    const widgetOptions = getWidgetOptions(event.payload.hide_default_launcher, Intercom.activator)
+
+    //API call
+    Intercom('update', {
+      company,
+      ...widgetOptions
+    })
+  }
+}
+
+export default action