@segment/analytics-browser-actions-userpilot 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@segment/analytics-browser-actions-userpilot",
+  "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,132 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import userpilot, { destination } from '../index'
+
+const example: Subscription[] = [
+  {
+    partnerAction: 'identifyUser',
+    name: 'Identify User',
+    enabled: true,
+    subscribe: 'type = "identify"',
+    mapping: {
+      userId: {
+        '@path': '$.userId'
+      },
+      anonymousId: {
+        '@path': '$.anonymousId'
+      },
+      traits: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  {
+    partnerAction: 'trackEvent',
+    name: 'Track Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      name: {
+        '@path': '$.name'
+      },
+      properties: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  {
+    partnerAction: 'pageView',
+    name: 'Page View',
+    enabled: true,
+    subscribe: 'type = "page"',
+    mapping: {
+      name: {
+        '@path': '$.name'
+      },
+      properties: {
+        '@path': '$.properties'
+      }
+    }
+  }
+]
+
+describe('Userpilot', () => {
+  it('should load the Userpilot script', async () => {
+    const [event] = await userpilot({
+      token: 'NX-917089a3',
+      subscriptions: example
+    })
+    jest.spyOn(destination, 'initialize')
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(window.userpilot).toBeDefined()
+  })
+})
+
+describe('IdentifyUser', () => {
+  it('should call identify if user id is provided', async () => {
+    const [identifyUser] = await userpilot({
+      token: 'NX-917089a3',
+      subscriptions: example
+    })
+    await identifyUser.load(Context.system(), {} as Analytics)
+    const up = jest.spyOn(window.userpilot, 'identify')
+
+    await identifyUser.identify?.(
+      new Context({
+        type: 'identify',
+        userId: 'test',
+        traits: {
+          example: 'test prop'
+        }
+      })
+    )
+    expect(up).toHaveBeenCalledWith('test', { example: 'test prop' })
+  })
+})
+
+describe('TrackEvent', () => {
+  it('should call track if event name is provided', async () => {
+    const [_identifyUser, trackEvent] = await userpilot({
+      token: 'NX-917089a3',
+      subscriptions: example
+    })
+
+    await trackEvent.load(Context.system(), {} as Analytics)
+    const up = jest.spyOn(window.userpilot, 'track')
+
+    await trackEvent.track?.(
+      new Context({
+        type: 'track',
+        name: 'test',
+        properties: {
+          example: 'test prop'
+        }
+      })
+    )
+    expect(up).toHaveBeenCalledWith('test', { example: 'test prop' })
+  })
+})
+
+describe('PageView', () => {
+  it('should call Userpilot reload', async () => {
+    const [_identifyUser, _trackEvent, pageView] = await userpilot({
+      token: 'NX-917089a3',
+      subscriptions: example
+    })
+    await pageView.load(Context.system(), {} as Analytics)
+
+    const up = jest.spyOn(window.userpilot, 'reload')
+
+    await pageView.page?.(
+      new Context({
+        type: 'page',
+        name: 'test',
+        properties: {
+          example: 'test prop'
+        }
+      })
+    )
+    expect(up).toHaveBeenCalledWith('test', { example: 'test prop' })
+  })
+})

package/src/generated-types.ts

@@ -0,0 +1,16 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * Your Userpilot app token, you can find it in the [Userpilot installation](https://run.userpilot.io/installation) dashboard.
+   */
+  token: string
+  /**
+   * By default, Userpilot would use a service discovery mechanism to determine the API endpoint to connect to. If you are using a proxy or a firewall, you can specify the API endpoint here.
+   */
+  endpoint?: string
+  /**
+   * By default, Segment will load the Userpilot JS snippet onto the page. If you are already loading the Userpilot JS onto the page then disable this setting and Segment will detect the Userpilot JS on the page
+   */
+  shouldSegmentLoadSDK: boolean
+}

package/src/identifyCompany/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The ID of the company.
+   */
+  groupId: string
+  /**
+   * Company traits
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/identifyCompany/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 { Userpilot } from '../types'
+// Change from unknown to the partner SDK types
+const action: BrowserActionDefinition<Settings, Userpilot, Payload> = {
+  title: 'Identify Company',
+  description: 'Create or update a company entity in Userpilot',
+  platform: 'web',
+  defaultSubscription: 'type = "group"',
+  fields: {
+    groupId: {
+      type: 'string',
+      required: true,
+      description: 'The ID of the company.',
+      label: 'Company ID',
+      default: {
+        '@path': '$.groupId'
+      }
+    },
+    traits: {
+      type: 'object',
+      required: false,
+      description: 'Company traits',
+      label: 'Traits',
+      default: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  perform: (_, events) => {
+    window.userpilot.group(events.payload.groupId ?? '', events.payload.traits ?? {})
+  }
+}
+
+export default action

package/src/identifyUser/generated-types.ts

@@ -0,0 +1,18 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The ID of the logged-in user.
+   */
+  userId: string
+  /**
+   * The date the user profile was created at
+   */
+  createdAt?: string | number
+  /**
+   * User traits.
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/identifyUser/index.ts

@@ -0,0 +1,54 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Userpilot } from '../types'
+
+const action: BrowserActionDefinition<Settings, Userpilot, Payload> = {
+  title: 'Identify User',
+  description:
+    "Create or update a user entity in Userpilot. It's mandatory to identify a user by calling identify() prior to invoking other methods such as track(), page(), or group(). You can learn more by visiting the [Userpilot documentation](https://docs.userpilot.com/article/23-identify-users-track-custom-events).",
+  platform: 'web',
+  defaultSubscription: 'type = "identify"',
+  fields: {
+    userId: {
+      type: 'string',
+      required: true,
+      description: 'The ID of the logged-in user.',
+      label: 'User ID',
+      default: {
+        '@if': {
+          exists: { '@path': '$.userId' },
+          then: { '@path': '$.userId' },
+          else: { '@path': '$.anonymousId' }
+        }
+      }
+    },
+    createdAt: {
+      type: 'datetime',
+      required: false,
+      description: 'The date the user profile was created at',
+      label: 'User Created At Date',
+      default: {
+        '@path': '$.traits.createdAt'
+      }
+    },
+    traits: {
+      type: 'object',
+      required: false,
+      description: 'User traits.',
+      label: 'Traits',
+      default: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  perform: (_, event) => {
+    const { userId, traits } = event.payload
+
+    traits?.createdAt && delete traits.createdAt
+
+    window.userpilot.identify(userId, { ...traits, created_at: event.payload.createdAt || traits?.created_at })
+  }
+}
+
+export default action

package/src/index.ts

@@ -0,0 +1,96 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import type { Userpilot } from './types'
+
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import { defaultValues } from '@segment/actions-core'
+
+import identifyUser from './identifyUser'
+import trackEvent from './trackEvent'
+import pageView from './pageView'
+
+import identifyCompany from './identifyCompany'
+
+declare global {
+  interface Window {
+    userpilot: Userpilot
+    userpilotSettings: Settings
+  }
+}
+
+// Switch from unknown to the partner SDK client types
+export const destination: BrowserDestinationDefinition<Settings, Userpilot> = {
+  name: 'Userpilot Web (Actions)',
+  slug: 'actions-userpilot-web',
+  mode: 'device',
+  presets: [
+    {
+      name: 'Identify User',
+      subscribe: 'type = "identify"',
+      partnerAction: 'identifyUser',
+      mapping: defaultValues(identifyUser.fields)
+    },
+    {
+      name: 'Track Event',
+      subscribe: 'type = "track"',
+      partnerAction: 'trackEvent',
+      mapping: defaultValues(trackEvent.fields)
+    },
+    {
+      name: 'Page View',
+      subscribe: 'type = "page"',
+      partnerAction: 'pageView',
+      mapping: defaultValues(pageView.fields)
+    }
+  ],
+  settings: {
+    token: {
+      label: 'App Token',
+      description:
+        'Your Userpilot app token, you can find it in the [Userpilot installation](https://run.userpilot.io/installation) dashboard.',
+      required: true,
+      type: 'string'
+    },
+    endpoint: {
+      label: 'The API endpoint the SDK would connect to',
+      description:
+        'By default, Userpilot would use a service discovery mechanism to determine the API endpoint to connect to. If you are using a proxy or a firewall, you can specify the API endpoint here.',
+      required: false,
+      type: 'string'
+    },
+    shouldSegmentLoadSDK: {
+      label: 'Segment Loads Userpilot JS',
+      description:
+        'By default, Segment will load the Userpilot JS snippet onto the page. If you are already loading the Userpilot JS onto the page then disable this setting and Segment will detect the Userpilot JS on the page',
+      required: true,
+      type: 'boolean',
+      default: true
+    }
+  },
+  initialize: async ({ settings }, deps) => {
+    const shouldLoadSDK = settings.shouldSegmentLoadSDK ?? true
+
+    if (shouldLoadSDK) {
+      window.userpilotSettings = {
+        token: settings.token,
+        endpoint: settings.endpoint,
+        shouldSegmentLoadSDK: shouldLoadSDK
+      }
+
+      await deps.loadScript('//js.userpilot.io/sdk/latest.js')
+      await deps.resolveWhen(() => Object.prototype.hasOwnProperty.call(window, 'userpilot'), 100)
+    } else {
+      await deps.resolveWhen(() => window.userpilot !== undefined, 100)
+    }
+    return window.userpilot
+  },
+
+  actions: {
+    identifyUser,
+    trackEvent,
+    pageView,
+    identifyCompany
+  }
+}
+
+export default browserDestination(destination)

package/src/pageView/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The name of the page that was viewed.
+   */
+  name?: string
+  /**
+   * The properties of the page that was viewed.
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/pageView/index.ts

@@ -0,0 +1,38 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Userpilot } from '../types'
+
+// Change from unknown to the partner SDK types
+const action: BrowserActionDefinition<Settings, Userpilot, Payload> = {
+  title: 'Page View',
+  description:
+    "Update the content queue designed to trigger on a specific page. It's mandatory to identify a user by calling identify() prior to invoking other methods such as page()",
+  platform: 'web',
+  defaultSubscription: 'type = "page"',
+  fields: {
+    name: {
+      type: 'string',
+      required: false,
+      description: 'The name of the page that was viewed.',
+      label: 'Page Name',
+      default: {
+        '@path': '$.name'
+      }
+    },
+    properties: {
+      type: 'object',
+      required: false,
+      description: 'The properties of the page that was viewed.',
+      label: 'Properties',
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  perform: (_, event) => {
+    window.userpilot.reload(event.payload.name ?? '', event.payload.properties ?? {})
+  }
+}
+
+export default action

package/src/trackEvent/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * Event name
+   */
+  name: string
+  /**
+   * Event properties
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/trackEvent/index.ts

@@ -0,0 +1,37 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Userpilot } from '../types'
+
+const action: BrowserActionDefinition<Settings, Userpilot, Payload> = {
+  title: 'Track Event',
+  description:
+    "Send an event to Userpilot. It's mandatory to identify a user by calling identify() prior to invoking other methods such as track(). You can learn more by visiting the [Userpilot documentation](https://docs.userpilot.com/article/23-identify-users-track-custom-events).",
+  platform: 'web',
+  defaultSubscription: 'type = "track"',
+  fields: {
+    name: {
+      type: 'string',
+      required: true,
+      description: 'Event name',
+      label: 'Name',
+      default: {
+        '@path': '$.event'
+      }
+    },
+    properties: {
+      type: 'object',
+      required: false,
+      description: 'Event properties',
+      label: 'Properties',
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  perform: (_, event) => {
+    window.userpilot.track(event.payload.name, event.payload.properties ?? {})
+  }
+}
+
+export default action

package/src/types.ts

@@ -0,0 +1,6 @@
+export type Userpilot = {
+  identify: (user_id: String, traits: { [key: string]: unknown }) => void
+  track: (eventName: String, eventProperties: { [key: string]: unknown }) => void
+  reload: (pageName: String, pageProperties: Object) => void
+  group: (groupId: String, groupTraits: Object) => void
+}

package/tsconfig.json

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