@segment/browser-destination-runtime 1.0.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@segment/browser-destination-runtime",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "yarn build:esm && yarn build:cjs",
+    "build:esm": "tsc --outDir ./dist/esm",
+    "build:cjs": "tsc  --module commonjs --outDir ./dist/cjs"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./load-script": {
+      "require": "./dist/cjs/load-script.js",
+      "default": "./dist/esm/load-script.js"
+    },
+    "./plugin": {
+      "require": "./dist/cjs/plugin.js",
+      "default": "./dist/esm/plugin.js"
+    },
+    "./resolve-when": {
+      "require": "./dist/cjs/resolve-when.js",
+      "default": "./dist/esm/resolve-when.js"
+    },
+    "./shim": {
+      "require": "./dist/cjs/shim.js",
+      "default": "./dist/esm/shim.js"
+    },
+    "./types": {
+      "require": "./dist/cjs/types.js",
+      "default": "./dist/esm/types.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "dist/esm/index.d.ts"
+      ],
+      "load-script": [
+        "dist/esm/load-script.d.ts"
+      ],
+      "plugin": [
+        "dist/esm/plugin.d.ts"
+      ],
+      "resolve-when": [
+        "dist/esm/resolve-when.d.ts"
+      ],
+      "shim": [
+        "dist/esm/shim.d.ts"
+      ],
+      "types": [
+        "dist/esm/types.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "@segment/actions-core": "^3.71.0"
+  },
+  "devDependencies": {
+    "@segment/analytics-next": "*"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": "*"
+  }
+}

package/src/__tests__/plugin.test.ts

@@ -0,0 +1,62 @@
+import { BrowserDestinationDefinition } from '../types'
+import { generatePlugins } from '../plugin'
+
+describe('generatePlugins', () => {
+  const initializeSpy = jest.fn()
+  const destinationDefinition: BrowserDestinationDefinition<{}, unknown> = {
+    name: 'Test destination',
+    slug: 'test-web-destination',
+    mode: 'device',
+    settings: {},
+    initialize: async () => {
+      initializeSpy()
+    },
+    actions: {
+      trackEventA: {
+        title: 'Track Event',
+        description: 'Tests track events',
+        platform: 'web',
+        defaultSubscription: 'type = "track"',
+        fields: {},
+        perform: () => {}
+      },
+      trackEventB: {
+        title: 'Track Event',
+        description: 'Tests track events',
+        platform: 'web',
+        defaultSubscription: 'type = "track"',
+        fields: {},
+        perform: () => {}
+      }
+    }
+  }
+
+  beforeEach(() => {
+    jest.resetAllMocks()
+  })
+
+  test('only loads once', async () => {
+    const plugins = generatePlugins(destinationDefinition, {}, [
+      {
+        enabled: true,
+        mapping: {},
+        name: 'a',
+        partnerAction: 'trackEventA',
+        subscribe: 'type = "track"'
+      },
+      {
+        enabled: true,
+        mapping: {},
+        name: 'b',
+        partnerAction: 'trackEventB',
+        subscribe: 'type = "track"'
+      }
+    ])
+
+    expect(plugins.length).toBe(2)
+
+    await Promise.all(plugins.map((p) => p.load({} as any, {} as any)))
+
+    expect(initializeSpy).toHaveBeenCalledTimes(1)
+  })
+})

package/src/load-script.ts

@@ -0,0 +1,47 @@
+export async function loadScript(src: string, attributes?: Record<string, string>): Promise<HTMLScriptElement> {
+  const scripts = Array.from(window.document.querySelectorAll('script'))
+  const found = scripts.find((s) => s.src === src)
+
+  if (found !== undefined) {
+    const status = found?.getAttribute('status')
+
+    if (status === 'loaded') {
+      return found
+    }
+
+    if (status === 'loading') {
+      return new Promise((resolve, reject) => {
+        found.addEventListener('load', () => resolve(found))
+        found.addEventListener('error', (err) => reject(err))
+      })
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const script = window.document.createElement('script')
+
+    script.type = 'text/javascript'
+    script.src = src
+    script.async = true
+
+    script.setAttribute('status', 'loading')
+    for (const [k, v] of Object.entries(attributes ?? {})) {
+      script.setAttribute(k, v)
+    }
+
+    script.onload = (): void => {
+      script.onerror = script.onload = null
+      script.setAttribute('status', 'loaded')
+      resolve(script)
+    }
+
+    script.onerror = (): void => {
+      script.onerror = script.onload = null
+      script.setAttribute('status', 'error')
+      reject(new Error(`Failed to load ${src}`))
+    }
+
+    const tag = window.document.getElementsByTagName('script')[0]
+    tag.parentElement?.insertBefore(script, tag)
+  })
+}

package/src/plugin.ts

@@ -0,0 +1,87 @@
+import type { Analytics, Context, Plugin } from '@segment/analytics-next'
+import type { JSONObject } from '@segment/actions-core'
+import { transform } from '@segment/actions-core/mapping-kit'
+import { parseFql, validate } from '@segment/destination-subscriptions'
+import { ActionInput, BrowserDestinationDefinition, Subscription } from './types'
+import { loadScript } from './load-script'
+import { resolveWhen } from './resolve-when'
+
+type MaybePromise<T> = T | Promise<T>
+
+export function generatePlugins<S, C>(
+  def: BrowserDestinationDefinition<S, C>,
+  settings: S,
+  subscriptions: Subscription[]
+): Plugin[] {
+  let hasInitialized = false
+  let client: C
+  let analytics: Analytics
+  let initializing: Promise<C> | undefined
+
+  const load: Plugin['load'] = async (_ctx, analyticsInstance) => {
+    if (hasInitialized) {
+      return
+    }
+
+    if (initializing) {
+      await initializing
+      return
+    }
+
+    analytics = analyticsInstance
+    initializing = def.initialize?.({ settings, analytics }, { loadScript, resolveWhen })
+    client = await initializing
+    hasInitialized = true
+  }
+
+  return Object.entries(def.actions).reduce((acc, [key, action]) => {
+    // Grab all the enabled subscriptions that invoke this action
+    const actionSubscriptions = subscriptions.filter((s) => s.enabled && s.partnerAction === key)
+    if (actionSubscriptions.length === 0) return acc
+
+    async function evaluate(ctx: Context): Promise<Context> {
+      const invocations: Array<MaybePromise<unknown>> = []
+
+      for (const sub of actionSubscriptions) {
+        const isSubscribed = validate(parseFql(sub.subscribe), ctx.event)
+        if (!isSubscribed) continue
+
+        const mapping = (sub.mapping ?? {}) as JSONObject
+        const payload = transform(mapping, ctx.event as unknown as JSONObject)
+
+        const input: ActionInput<S, unknown> = {
+          payload,
+          mapping,
+          settings,
+          analytics,
+          context: ctx
+        }
+
+        invocations.push(action.perform(client, input))
+      }
+
+      await Promise.all(invocations)
+      // TODO: some sort of error handling
+      return ctx
+    }
+
+    const plugin = {
+      name: `${def.name} ${key}`,
+      type: action.lifecycleHook ?? 'destination',
+      version: '0.1.0',
+      ready: () => Promise.resolve(),
+
+      isLoaded: () => hasInitialized,
+      load,
+
+      track: evaluate,
+      page: evaluate,
+      alias: evaluate,
+      identify: evaluate,
+      group: evaluate
+    }
+
+    acc.push(plugin)
+    return acc
+  }, [] as Plugin[])
+}

package/src/resolve-when.ts

@@ -0,0 +1,19 @@
+export async function resolveWhen(condition: () => boolean, timeout?: number): Promise<void> {
+  return new Promise((resolve, _reject) => {
+    if (condition()) {
+      resolve()
+      return
+    }
+
+    const check = () =>
+      setTimeout(() => {
+        if (condition()) {
+          resolve()
+        } else {
+          check()
+        }
+      }, timeout)
+
+    check()
+  })
+}

package/src/shim.ts

@@ -0,0 +1,16 @@
+import type { BrowserDestinationDefinition, PluginFactory, Subscription } from './types'
+
+export function browserDestination<S, C>(definition: BrowserDestinationDefinition<S, C>): PluginFactory {
+  const factory = (async (settings: S & { subscriptions?: Subscription[] }) => {
+    const plugin = await import(
+      /* webpackChunkName: "actions-plugin" */
+      /* webpackMode: "lazy-once" */
+      './plugin'
+    )
+    return plugin.generatePlugins(definition, settings, settings.subscriptions || [])
+  }) as unknown as PluginFactory
+
+  factory.pluginName = definition.name
+
+  return factory
+}

package/src/types.ts

@@ -0,0 +1,69 @@
+import type { Analytics, Context, Plugin } from '@segment/analytics-next'
+import type {
+  BaseDefinition,
+  BaseActionDefinition,
+  ExecuteInput,
+  JSONLikeObject,
+  GlobalSetting,
+  JSONValue
+} from '@segment/actions-core'
+
+export type ActionInput<Settings, Payload> = ExecuteInput<Settings, Payload> & {
+  analytics: Analytics
+  context: Context
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface BrowserActionDefinition<Settings, Client, Payload = any> extends BaseActionDefinition {
+  /** The operation to perform when this action is triggered */
+  perform: (client: Client, data: ActionInput<Settings, Payload>) => Promise<unknown> | unknown
+
+  /**
+   * The target platform for the action
+   */
+  platform: 'web'
+
+  /** Which step in the Analytics.js lifecycle this action should run */
+  lifecycleHook?: Plugin['type']
+}
+
+export interface BrowserDestinationDependencies {
+  loadScript: (src: string, attributes?: Record<string, string>) => Promise<HTMLScriptElement>
+  resolveWhen: (condition: () => boolean, timeout?: number) => Promise<void>
+}
+
+export type InitializeOptions<Settings> = { settings: Settings; analytics: Analytics }
+
+export interface BrowserDestinationDefinition<Settings = unknown, Client = unknown> extends BaseDefinition {
+  mode: 'device'
+
+  /**
+   * The function called when the destination has loaded and is ready to be initialized
+   * Typically you would configure an SDK or API client here.
+   * The return value is injected to your actions as the `client`
+   */
+  initialize: (options: InitializeOptions<Settings>, dependencies: BrowserDestinationDependencies) => Promise<Client>
+
+  /**
+   * Top-level settings that should be available across all actions
+   * This is often where you would put initialization settings,
+   * SDK keys, API subdomains, etc.
+   */
+  settings?: Record<string, GlobalSetting>
+
+  /** Actions */
+  actions: Record<string, BrowserActionDefinition<Settings, Client>>
+}
+
+export interface Subscription {
+  partnerAction: string
+  name: string
+  enabled: boolean
+  subscribe: string
+  mapping: JSONLikeObject
+}
+
+export interface PluginFactory {
+  (settings: JSONValue): Plugin | Plugin[] | Promise<Plugin | Plugin[]>
+  pluginName: string
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "removeComments": false,
+    "baseUrl": "."
+  },
+  "exclude": ["dist"]
+}