@segment/analytics-browser-actions-sprig 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@segment/analytics-browser-actions-sprig",
+  "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__/__snapshots__/index.test.ts.snap

@@ -0,0 +1,18 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Sprig initialization can load Sprig: 
+      <script
+          src="https://cdn.sprig.com/shim.js?id=testEnvId"
+          status="loaded"
+          type="text/javascript"
+        />,
+        <script>
+          // the emptiness
+        </script>,
+     1`] = `
+NodeList [
+  <script>
+    // the emptiness
+  </script>,
+]
+`;

package/src/__tests__/index.test.ts

@@ -0,0 +1,48 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import sprigWebDestination, { destination } from '../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Track Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      name: {
+        '@path': '$.name'
+      }
+    }
+  }
+]
+
+describe('Sprig initialization', () => {
+  beforeAll(() => {
+    jest.mock('@segment/browser-destination-runtime/load-script', () => ({
+      loadScript: (_src: any, _attributes: any) => {}
+    }))
+  })
+  test('can load Sprig', async () => {
+    const [event] = await sprigWebDestination({
+      envId: 'testEnvId',
+      subscriptions
+    })
+
+    jest.spyOn(destination, 'initialize')
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+
+    const scripts = window.document.querySelectorAll('script')
+    expect(scripts).toMatchSnapshot(`
+      <script
+          src="https://cdn.sprig.com/shim.js?id=testEnvId"
+          status="loaded"
+          type="text/javascript"
+        />,
+        <script>
+          // the emptiness
+        </script>,
+    `)
+  })
+})

package/src/generated-types.ts

@@ -0,0 +1,12 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * Your environment ID (production or development).
+   */
+  envId: string
+  /**
+   * Enable debug mode for testing purposes.
+   */
+  debugMode?: boolean
+}

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

@@ -0,0 +1,65 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import sprigWebDestination, { destination } from '../../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'identifyUser',
+    name: 'Identify User',
+    enabled: true,
+    subscribe: 'type = "identify"',
+    mapping: {
+      anonymousId: {
+        '@path': '$.anonymousId'
+      },
+      userId: {
+        '@path': '$.userId'
+      },
+      traits: {
+        '@path': '$.traits'
+      }
+    }
+  }
+]
+
+describe('identifyUser', () => {
+  beforeAll(() => {
+    jest.mock('@segment/browser-destination-runtime/load-script', () => ({
+      loadScript: (_src: any, _attributes: any) => {}
+    }))
+  })
+  test('it maps event parameters correctly to identify function ', async () => {
+    const [identifyEvent] = await sprigWebDestination({
+      envId: 'testEnvId',
+      subscriptions
+    })
+
+    destination.actions.identifyUser.perform = jest.fn()
+    jest.spyOn(destination.actions.identifyUser, 'perform')
+    await identifyEvent.load(Context.system(), {} as Analytics)
+
+    await identifyEvent.identify?.(
+      new Context({
+        type: 'identify',
+        anonymousId: 'anonymous-id-0',
+        userId: 'user-id-1',
+        traits: {
+          email: 'test-email-2@gmail.com'
+        }
+      })
+    )
+
+    expect(destination.actions.identifyUser.perform).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        payload: {
+          anonymousId: 'anonymous-id-0',
+          userId: 'user-id-1',
+          traits: {
+            email: 'test-email-2@gmail.com'
+          }
+        }
+      })
+    )
+  })
+})

package/src/identifyUser/generated-types.ts

@@ -0,0 +1,18 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * Unique identifier for the user
+   */
+  userId?: string
+  /**
+   * Anonymous identifier for the user
+   */
+  anonymousId?: string
+  /**
+   * The Segment user traits to be forwarded to Sprig and set as attributes
+   */
+  traits?: {
+    [k: string]: unknown
+  }
+}

package/src/identifyUser/index.ts

@@ -0,0 +1,78 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Sprig } from '../types'
+
+const action: BrowserActionDefinition<Settings, Sprig, Payload> = {
+  title: 'Identify User',
+  description: 'Set user ID and/or attributes.',
+  platform: 'web',
+  defaultSubscription: 'type = "identify"',
+  fields: {
+    userId: {
+      type: 'string',
+      required: false,
+      description: 'Unique identifier for the user',
+      label: 'User ID',
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    anonymousId: {
+      type: 'string',
+      required: false,
+      description: 'Anonymous identifier for the user',
+      label: 'Anonymous ID',
+      default: {
+        '@path': '$.anonymousId'
+      }
+    },
+    traits: {
+      type: 'object',
+      required: false,
+      description: 'The Segment user traits to be forwarded to Sprig and set as attributes',
+      label: 'User Attributes',
+      default: {
+        '@path': '$.traits'
+      }
+    }
+  },
+  perform: (Sprig, event) => {
+    const payload = event.payload
+    if (!payload || typeof payload !== 'object' || !(payload.userId || payload.anonymousId || payload.traits)) {
+      console.warn(
+        '[Sprig] received invalid payload (expected userId, anonymousId, or traits to be present); skipping identifyUser',
+        payload
+      )
+      return
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sprigIdentifyAndSetAttributesPayload: {
+      userId?: string
+      anonymousId?: string
+      attributes?: { [key: string]: any }
+    } = {}
+
+    if (payload.userId) {
+      sprigIdentifyAndSetAttributesPayload.userId = payload.userId
+    }
+
+    if (payload.anonymousId) {
+      sprigIdentifyAndSetAttributesPayload.anonymousId = payload.anonymousId
+    }
+
+    if (payload.traits && Object.keys(payload.traits).length > 0) {
+      const traits = { ...payload.traits }
+      if (traits.email) {
+        traits['!email'] = traits.email
+        delete traits.email
+      }
+      sprigIdentifyAndSetAttributesPayload.attributes = traits
+    }
+
+    Sprig('identifyAndSetAttributes', sprigIdentifyAndSetAttributesPayload)
+  }
+}
+
+export default action

package/src/index.ts

@@ -0,0 +1,91 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import { Sprig } from './types'
+import identifyUser from './identifyUser'
+import signoutUser from './signoutUser'
+import trackEvent from './trackEvent'
+import updateUserId from './updateUserId'
+import { defaultValues } from '@segment/actions-core'
+
+declare global {
+  interface Window {
+    Sprig: Sprig
+    UserLeap: Sprig
+  }
+}
+
+export const destination: BrowserDestinationDefinition<Settings, Sprig> = {
+  name: 'Sprig (Actions)',
+  slug: 'sprig-web',
+  mode: 'device',
+
+  presets: [
+    {
+      name: 'Identify User',
+      subscribe: 'type = "identify"',
+      partnerAction: 'identifyUser',
+      mapping: defaultValues(identifyUser.fields)
+    },
+    {
+      name: 'Sign Out User',
+      subscribe: 'type = "track" and event = "Signed Out"',
+      partnerAction: 'signoutUser',
+      mapping: defaultValues(signoutUser.fields)
+    },
+    {
+      name: 'Track Event',
+      subscribe: 'type = "track" and event != "Signed Out"',
+      partnerAction: 'trackEvent',
+      mapping: defaultValues(trackEvent.fields)
+    },
+    {
+      name: 'Update User ID',
+      subscribe: 'type = "alias"',
+      partnerAction: 'updateUserId',
+      mapping: defaultValues(updateUserId.fields)
+    }
+  ],
+
+  settings: {
+    envId: {
+      description: 'Your environment ID (production or development).',
+      label: 'Environment ID',
+      type: 'string',
+      required: true
+    },
+    debugMode: {
+      description: 'Enable debug mode for testing purposes.',
+      label: 'Debug mode',
+      type: 'boolean',
+      required: false,
+      default: false
+    }
+  },
+
+  actions: {
+    identifyUser,
+    signoutUser,
+    trackEvent,
+    updateUserId
+  },
+
+  initialize: async ({ settings }, deps) => {
+    if (!window.Sprig || !window.Sprig.envId) {
+      window.Sprig = function (...args) {
+        S._queue && S._queue.push(args)
+      }
+      const S = window.Sprig
+      S.envId = settings.envId
+      S.debugMode = !!settings.debugMode
+      S._queue = []
+      S._segment = 1
+      window.UserLeap = S
+      await deps.loadScript(`https://cdn.sprig.com/shim.js?id=${S.envId}`)
+    }
+
+    return window.Sprig
+  }
+}
+
+export default browserDestination(destination)

package/src/signoutUser/generated-types.ts

@@ -0,0 +1,3 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {}

package/src/signoutUser/index.ts

@@ -0,0 +1,17 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Sprig } from '../types'
+
+const action: BrowserActionDefinition<Settings, Sprig, Payload> = {
+  title: 'Sign Out User',
+  description: 'Clear stored user ID so that future events and traits are not associated with this user.',
+  platform: 'web',
+  defaultSubscription: 'type = "track" and event = "Signed Out"',
+  fields: {},
+  perform: (Sprig, _event) => {
+    Sprig('logoutUser')
+  }
+}
+
+export default action

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

@@ -0,0 +1,60 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import sprigWebDestination, { destination } from '../../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackEvent',
+    name: 'Track Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      name: {
+        '@path': '$.name'
+      },
+      anonymousId: {
+        '@path': '$.anonymousId'
+      },
+      userId: {
+        '@path': '$.userId'
+      },
+      properties: {
+        '@path': '$.properties'
+      }
+    }
+  }
+]
+
+describe('trackEvent', () => {
+  beforeAll(() => {
+    jest.mock('@segment/browser-destination-runtime/load-script', () => ({
+      loadScript: (_src: any, _attributes: any) => {}
+    }))
+  })
+  test('it maps event parameters correctly to track function ', async () => {
+    const [trackEvent] = await sprigWebDestination({
+      envId: 'testEnvId',
+      subscriptions
+    })
+
+    destination.actions.trackEvent.perform = jest.fn()
+    jest.spyOn(destination.actions.trackEvent, 'perform')
+    await trackEvent.load(Context.system(), {} as Analytics)
+    const properties = { property1: 'value1', property2: false }
+    await trackEvent.track?.(
+      new Context({
+        type: 'track',
+        name: 'Button Clicked',
+        anonymousId: 'anonymous-id-0',
+        properties
+      })
+    )
+
+    expect(destination.actions.trackEvent.perform).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        payload: { name: 'Button Clicked', anonymousId: 'anonymous-id-0', properties }
+      })
+    )
+  })
+})

package/src/trackEvent/generated-types.ts

@@ -0,0 +1,22 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The event name that will be shown on Sprig's dashboard
+   */
+  name: string
+  /**
+   * Unique identifier for the user
+   */
+  userId?: string
+  /**
+   * Anonymous identifier for the user
+   */
+  anonymousId?: string
+  /**
+   * Object containing the properties of the event
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/trackEvent/index.ts

@@ -0,0 +1,80 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Sprig } from '../types'
+
+const action: BrowserActionDefinition<Settings, Sprig, Payload> = {
+  title: 'Track Event',
+  description: 'Track event to potentially filter user studies (microsurveys) later, or trigger a study now.',
+  platform: 'web',
+  defaultSubscription: 'type = "track" and event != "Signed Out"',
+  fields: {
+    name: {
+      description: "The event name that will be shown on Sprig's dashboard",
+      label: 'Event name',
+      required: true,
+      type: 'string',
+      default: {
+        '@path': '$.event'
+      }
+    },
+    userId: {
+      type: 'string',
+      required: false,
+      description: 'Unique identifier for the user',
+      label: 'User ID',
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    anonymousId: {
+      type: 'string',
+      required: false,
+      description: 'Anonymous identifier for the user',
+      label: 'Anonymous ID',
+      default: {
+        '@path': '$.anonymousId'
+      }
+    },
+    properties: {
+      type: 'object',
+      required: false,
+      description: 'Object containing the properties of the event',
+      label: 'Event Properties',
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  perform: (Sprig, event) => {
+    const payload = event.payload
+    if (!payload || typeof payload !== 'object' || !payload.name) {
+      console.warn('[Sprig] received invalid payload (expected name to be present); skipping trackEvent', payload)
+      return
+    }
+
+    const sprigIdentifyAndTrackPayload: {
+      eventName: string
+      userId?: string
+      anonymousId?: string
+      properties?: { [key: string]: unknown }
+    } = {
+      eventName: payload.name
+    }
+    if (payload.userId) {
+      sprigIdentifyAndTrackPayload.userId = payload.userId
+    }
+
+    if (payload.anonymousId) {
+      sprigIdentifyAndTrackPayload.anonymousId = payload.anonymousId
+    }
+
+    if (payload.properties) {
+      sprigIdentifyAndTrackPayload.properties = payload.properties
+    }
+
+    Sprig('identifyAndTrack', sprigIdentifyAndTrackPayload)
+  }
+}
+
+export default action

package/src/types.ts

@@ -0,0 +1,7 @@
+export interface Sprig {
+  (...args: unknown[]): unknown
+  envId?: string
+  debugMode?: boolean
+  _queue?: unknown[]
+  _segment?: number
+}

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

@@ -0,0 +1,81 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import sprigWebDestination, { destination } from '../../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'updateUserId',
+    name: 'Update User ID',
+    enabled: true,
+    subscribe: 'type = "alias"',
+    mapping: {
+      anonymousId: {
+        '@path': '$.anonymousId'
+      },
+      userId: {
+        '@path': '$.userId'
+      }
+    }
+  }
+]
+
+describe('updateUserId', () => {
+  beforeAll(() => {
+    jest.mock('@segment/browser-destination-runtime/load-script', () => ({
+      loadScript: (_src: any, _attributes: any) => {}
+    }))
+  })
+  test('it maps event parameters correctly to alias function with user id', async () => {
+    const [aliasEvent] = await sprigWebDestination({
+      envId: 'testEnvId',
+      subscriptions
+    })
+
+    destination.actions.updateUserId.perform = jest.fn()
+    jest.spyOn(destination.actions.updateUserId, 'perform')
+    await aliasEvent.load(Context.system(), {} as Analytics)
+
+    await aliasEvent.alias?.(
+      new Context({
+        type: 'alias',
+        userId: 'user-id-1'
+      })
+    )
+
+    expect(destination.actions.updateUserId.perform).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        payload: {
+          userId: 'user-id-1'
+        }
+      })
+    )
+  })
+
+  test('it maps event parameters correctly to alias function with anonymous id', async () => {
+    const [aliasEvent] = await sprigWebDestination({
+      envId: 'testEnvId',
+      subscriptions
+    })
+
+    destination.actions.updateUserId.perform = jest.fn()
+    jest.spyOn(destination.actions.updateUserId, 'perform')
+    await aliasEvent.load(Context.system(), {} as Analytics)
+
+    await aliasEvent.alias?.(
+      new Context({
+        type: 'alias',
+        anonymousId: 'anonymous-id-0'
+      })
+    )
+
+    expect(destination.actions.updateUserId.perform).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        payload: {
+          anonymousId: 'anonymous-id-0'
+        }
+      })
+    )
+  })
+})

package/src/updateUserId/generated-types.ts

@@ -0,0 +1,12 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * New unique identifier for the user
+   */
+  userId?: string
+  /**
+   * New anonymous identifier for the user
+   */
+  anonymousId?: string
+}

package/src/updateUserId/index.ts

@@ -0,0 +1,55 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Sprig } from '../types'
+
+const action: BrowserActionDefinition<Settings, Sprig, Payload> = {
+  title: 'Update User ID',
+  description: 'Set updated user ID.',
+  platform: 'web',
+  defaultSubscription: 'type = "alias"',
+  fields: {
+    userId: {
+      type: 'string',
+      required: false,
+      description: 'New unique identifier for the user',
+      label: 'User ID',
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    anonymousId: {
+      type: 'string',
+      required: false,
+      description: 'New anonymous identifier for the user',
+      label: 'Anonymous ID',
+      default: {
+        '@path': '$.anonymousId'
+      }
+    }
+  },
+  perform: (Sprig, event) => {
+    const payload = event.payload
+    if (!payload || typeof payload !== 'object' || !(payload.userId || payload.anonymousId)) {
+      console.warn(
+        '[Sprig] received invalid payload (expected userId or anonymousId to be present); skipping updateUserId',
+        payload
+      )
+      return
+    }
+
+    const sprigIdentifyAndSetAttributesPayload: { userId?: string; anonymousId?: string } = {}
+
+    if (payload.userId) {
+      sprigIdentifyAndSetAttributesPayload.userId = payload.userId
+    }
+
+    if (payload.anonymousId) {
+      sprigIdentifyAndSetAttributesPayload.anonymousId = payload.anonymousId
+    }
+
+    Sprig('identifyAndSetAttributes', sprigIdentifyAndSetAttributesPayload)
+  }
+}
+
+export default action

package/tsconfig.json

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