@ht-sdks/events-sdk-js-browser 1.0.4

package/src/plugins/middleware/index.ts

@@ -0,0 +1,131 @@
+import { Context, ContextCancelation } from '../../core/context'
+import { SegmentEvent } from '../../core/events'
+import { Plugin } from '../../core/plugin'
+import { SegmentFacade, toFacade } from '../../lib/to-facade'
+
+export interface MiddlewareParams {
+  payload: SegmentFacade
+
+  integrations?: SegmentEvent['integrations']
+  next: (payload: MiddlewareParams['payload'] | null) => void
+}
+
+export interface DestinationMiddlewareParams {
+  payload: SegmentFacade
+  integration: string
+  next: (payload: MiddlewareParams['payload'] | null) => void
+}
+
+export type MiddlewareFunction = (
+  middleware: MiddlewareParams
+) => void | Promise<void>
+
+export type DestinationMiddlewareFunction = (
+  middleware: DestinationMiddlewareParams
+) => void | Promise<void>
+
+export async function applyDestinationMiddleware(
+  destination: string,
+  evt: SegmentEvent,
+  middleware: DestinationMiddlewareFunction[]
+): Promise<SegmentEvent | null> {
+  // Clone the event so mutations are localized to a single destination.
+  let modifiedEvent = toFacade(evt, {
+    clone: true,
+    traverse: false,
+  }).rawEvent() as SegmentEvent
+  async function applyMiddleware(
+    event: SegmentEvent,
+    fn: DestinationMiddlewareFunction
+  ): Promise<SegmentEvent | null> {
+    let nextCalled = false
+    let returnedEvent: SegmentEvent | null = null
+
+    await fn({
+      payload: toFacade(event, {
+        clone: true,
+        traverse: false,
+      }),
+      integration: destination,
+      next(evt) {
+        nextCalled = true
+
+        if (evt === null) {
+          returnedEvent = null
+        }
+
+        if (evt) {
+          returnedEvent = evt.obj
+        }
+      },
+    })
+
+    if (!nextCalled && returnedEvent !== null) {
+      returnedEvent = returnedEvent as SegmentEvent
+      returnedEvent.integrations = {
+        ...event.integrations,
+        [destination]: false,
+      }
+    }
+
+    return returnedEvent
+  }
+
+  for (const md of middleware) {
+    const result = await applyMiddleware(modifiedEvent, md)
+    if (result === null) {
+      return null
+    }
+    modifiedEvent = result
+  }
+
+  return modifiedEvent
+}
+
+export function sourceMiddlewarePlugin(
+  fn: MiddlewareFunction,
+  integrations: SegmentEvent['integrations']
+): Plugin {
+  async function apply(ctx: Context): Promise<Context> {
+    let nextCalled = false
+
+    await fn({
+      payload: toFacade(ctx.event, {
+        clone: true,
+        traverse: false,
+      }),
+      integrations: integrations ?? {},
+      next(evt) {
+        nextCalled = true
+        if (evt) {
+          ctx.event = evt.obj
+        }
+      },
+    })
+
+    if (!nextCalled) {
+      throw new ContextCancelation({
+        retry: false,
+        type: 'middleware_cancellation',
+        reason: 'Middleware `next` function skipped',
+      })
+    }
+
+    return ctx
+  }
+
+  return {
+    name: `Source Middleware ${fn.name}`,
+    type: 'before',
+    version: '0.1.0',
+
+    isLoaded: (): boolean => true,
+    load: (ctx): Promise<Context> => Promise.resolve(ctx),
+
+    track: apply,
+    page: apply,
+    identify: apply,
+    alias: apply,
+    group: apply,
+  }
+}

package/src/plugins/remote-loader/index.ts

@@ -0,0 +1,256 @@
+import type { Integrations } from '../../core/events/interfaces'
+import { LegacySettings } from '../../browser'
+import { JSONObject, JSONValue } from '../../core/events'
+import { DestinationPlugin, Plugin } from '../../core/plugin'
+import { loadScript } from '../../lib/load-script'
+import { getCDN } from '../../lib/parse-cdn'
+import {
+  applyDestinationMiddleware,
+  DestinationMiddlewareFunction,
+} from '../middleware'
+import { Context, ContextCancelation } from '../../core/context'
+import { Analytics } from '../../core/analytics'
+
+export interface RemotePlugin {
+  /** The name of the remote plugin */
+  name: string
+  /** The creation name of the remote plugin */
+  creationName: string
+  /** The url of the javascript file to load */
+  url: string
+  /** The UMD/global name the plugin uses. Plugins are expected to exist here with the `PluginFactory` method signature */
+  libraryName: string
+  /** The settings related to this plugin. */
+  settings: JSONObject
+}
+
+export class ActionDestination implements DestinationPlugin {
+  name: string // destination name
+  version = '1.0.0'
+  type: Plugin['type']
+
+  alternativeNames: string[] = []
+
+  middleware: DestinationMiddlewareFunction[] = []
+
+  action: Plugin
+
+  constructor(name: string, action: Plugin) {
+    this.action = action
+    this.name = name
+    this.type = action.type
+    this.alternativeNames.push(action.name)
+  }
+
+  addMiddleware(...fn: DestinationMiddlewareFunction[]): void {
+    if (this.type === 'destination') {
+      this.middleware.push(...fn)
+    }
+  }
+
+  private async transform(ctx: Context): Promise<Context> {
+    const modifiedEvent = await applyDestinationMiddleware(
+      this.name,
+      ctx.event,
+      this.middleware
+    )
+
+    if (modifiedEvent === null) {
+      ctx.cancel(
+        new ContextCancelation({
+          retry: false,
+          reason: 'dropped by destination middleware',
+        })
+      )
+    }
+
+    return new Context(modifiedEvent!)
+  }
+
+  private _createMethod(
+    methodName: 'track' | 'page' | 'identify' | 'alias' | 'group' | 'screen'
+  ) {
+    return async (ctx: Context): Promise<Context> => {
+      if (!this.action[methodName]) return ctx
+
+      let transformedContext: Context = ctx
+      // Transformations only allowed for destination plugins. Other plugin types support mutating events.
+      if (this.type === 'destination') {
+        transformedContext = await this.transform(ctx)
+      }
+
+      await this.action[methodName]!(transformedContext)
+
+      return ctx
+    }
+  }
+
+  alias = this._createMethod('alias')
+  group = this._createMethod('group')
+  identify = this._createMethod('identify')
+  page = this._createMethod('page')
+  screen = this._createMethod('screen')
+  track = this._createMethod('track')
+
+  /* --- PASSTHROUGH METHODS --- */
+  isLoaded(): boolean {
+    return this.action.isLoaded()
+  }
+
+  ready(): Promise<unknown> {
+    return this.action.ready ? this.action.ready() : Promise.resolve()
+  }
+
+  load(ctx: Context, analytics: Analytics): Promise<unknown> {
+    return this.action.load(ctx, analytics)
+  }
+
+  unload(ctx: Context, analytics: Analytics): Promise<unknown> | unknown {
+    return this.action.unload?.(ctx, analytics)
+  }
+}
+
+export type PluginFactory = {
+  (settings: JSONValue): Plugin | Plugin[] | Promise<Plugin | Plugin[]>
+  pluginName: string
+}
+
+function validate(pluginLike: unknown): pluginLike is Plugin[] {
+  if (!Array.isArray(pluginLike)) {
+    throw new Error('Not a valid list of plugins')
+  }
+
+  const required = ['load', 'isLoaded', 'name', 'version', 'type']
+  pluginLike.forEach((plugin) => {
+    required.forEach((method) => {
+      if (plugin[method] === undefined) {
+        throw new Error(
+          `Plugin: ${
+            plugin.name ?? 'unknown'
+          } missing required function ${method}`
+        )
+      }
+    })
+  })
+
+  return true
+}
+
+function isPluginDisabled(
+  userIntegrations: Integrations,
+  remotePlugin: RemotePlugin
+) {
+  const creationNameEnabled = userIntegrations[remotePlugin.creationName]
+  const currentNameEnabled = userIntegrations[remotePlugin.name]
+
+  // Check that the plugin isn't explicitly enabled when All: false
+  if (
+    userIntegrations.All === false &&
+    !creationNameEnabled &&
+    !currentNameEnabled
+  ) {
+    return true
+  }
+
+  // Check that the plugin isn't explicitly disabled
+  if (creationNameEnabled === false || currentNameEnabled === false) {
+    return true
+  }
+
+  return false
+}
+
+async function loadPluginFactory(
+  remotePlugin: RemotePlugin,
+  obfuscate?: boolean
+): Promise<void | PluginFactory> {
+  const defaultCdn = new RegExp('https://cdn.hightouch-events.(com|build)')
+  const cdn = getCDN()
+
+  if (obfuscate) {
+    const urlSplit = remotePlugin.url.split('/')
+    const name = urlSplit[urlSplit.length - 2]
+    const obfuscatedURL = remotePlugin.url.replace(
+      name,
+      btoa(name).replace(/=/g, '')
+    )
+    try {
+      await loadScript(obfuscatedURL.replace(defaultCdn, cdn))
+    } catch (error) {
+      // Due to syncing concerns it is possible that the obfuscated action destination (or requested version) might not exist.
+      // We should use the unobfuscated version as a fallback.
+      await loadScript(remotePlugin.url.replace(defaultCdn, cdn))
+    }
+  } else {
+    await loadScript(remotePlugin.url.replace(defaultCdn, cdn))
+  }
+
+  // @ts-expect-error
+  if (typeof window[remotePlugin.libraryName] === 'function') {
+    // @ts-expect-error
+    return window[remotePlugin.libraryName] as PluginFactory
+  }
+}
+
+export async function remoteLoader(
+  settings: LegacySettings,
+  userIntegrations: Integrations,
+  mergedIntegrations: Record<string, JSONObject>,
+  obfuscate?: boolean,
+  routingMiddleware?: DestinationMiddlewareFunction,
+  pluginSources?: PluginFactory[]
+): Promise<Plugin[]> {
+  const allPlugins: Plugin[] = []
+
+  const routingRules = settings.middlewareSettings?.routingRules ?? []
+
+  const pluginPromises = (settings.remotePlugins ?? []).map(
+    async (remotePlugin) => {
+      if (isPluginDisabled(userIntegrations, remotePlugin)) return
+
+      try {
+        const pluginFactory =
+          pluginSources?.find(
+            ({ pluginName }) => pluginName === remotePlugin.name
+          ) || (await loadPluginFactory(remotePlugin, obfuscate))
+
+        if (pluginFactory) {
+          const plugin = await pluginFactory({
+            ...remotePlugin.settings,
+            ...mergedIntegrations[remotePlugin.name],
+          })
+          const plugins = Array.isArray(plugin) ? plugin : [plugin]
+
+          validate(plugins)
+
+          const routing = routingRules.filter(
+            (rule) => rule.destinationName === remotePlugin.creationName
+          )
+
+          plugins.forEach((plugin) => {
+            const wrapper = new ActionDestination(
+              remotePlugin.creationName,
+              plugin
+            )
+
+            /** Make sure we only apply destination filters to actions of the "destination" type to avoid causing issues for hybrid destinations */
+            if (
+              routing.length &&
+              routingMiddleware &&
+              plugin.type === 'destination'
+            ) {
+              wrapper.addMiddleware(routingMiddleware)
+            }
+
+            allPlugins.push(wrapper)
+          })
+        }
+      } catch (error) {
+        console.warn('Failed to load Remote Plugin', error)
+      }
+    }
+  )
+
+  await Promise.all(pluginPromises)
+  return allPlugins.filter(Boolean)
+}

package/src/plugins/remote-middleware/index.ts

@@ -0,0 +1,44 @@
+import { LegacySettings } from '../../browser'
+import { Context } from '../../core/context'
+import { isServer } from '../../core/environment'
+import { loadScript } from '../../lib/load-script'
+import { getNextIntegrationsURL } from '../../lib/parse-cdn'
+import { MiddlewareFunction } from '../middleware'
+
+export async function remoteMiddlewares(
+  ctx: Context,
+  settings: LegacySettings,
+  obfuscate?: boolean
+): Promise<MiddlewareFunction[]> {
+  if (isServer()) {
+    return []
+  }
+  const path = getNextIntegrationsURL()
+  const remoteMiddleware = settings.enabledMiddleware ?? {}
+  const names = Object.entries(remoteMiddleware)
+    .filter(([_, enabled]) => enabled)
+    .map(([name]) => name)
+
+  const scripts = names.map(async (name) => {
+    const nonNamespaced = name.replace('@segment/', '')
+    let bundleName = nonNamespaced
+    if (obfuscate) {
+      bundleName = btoa(nonNamespaced).replace(/=/g, '')
+    }
+    const fullPath = `${path}/middleware/${bundleName}/latest/${bundleName}.js.gz`
+
+    try {
+      await loadScript(fullPath)
+      // @ts-ignore
+      return window[`${nonNamespaced}Middleware`] as MiddlewareFunction
+    } catch (error: any) {
+      ctx.log('error', error)
+      ctx.stats.increment('failed_remote_middleware')
+    }
+  })
+
+  let middleware = await Promise.all(scripts)
+  middleware = middleware.filter(Boolean)
+
+  return middleware as MiddlewareFunction[]
+}

package/src/plugins/routing-middleware/index.ts

@@ -0,0 +1,37 @@
+import * as tsub from '@segment/tsub'
+import { Matcher, Rule } from '@segment/tsub/dist/store'
+import { DestinationMiddlewareFunction } from '../middleware'
+
+// TODO: update tsub definition
+type RoutingRuleMatcher = Matcher & {
+  config?: {
+    expr: string
+  }
+}
+
+export type RoutingRule = Rule & {
+  matchers: RoutingRuleMatcher[]
+}
+
+export const tsubMiddleware =
+  (rules: RoutingRule[]): DestinationMiddlewareFunction =>
+  ({ payload, integration, next }): void => {
+    const store = new tsub.Store(rules)
+    const rulesToApply = store.getRulesByDestinationName(integration)
+
+    rulesToApply.forEach((rule) => {
+      const { matchers, transformers } = rule
+
+      for (let i = 0; i < matchers.length; i++) {
+        if (tsub.matches(payload.obj, matchers[i])) {
+          payload.obj = tsub.transform(payload.obj, transformers[i])
+
+          if (payload.obj === null) {
+            return next(null)
+          }
+        }
+      }
+    })
+
+    next(payload)
+  }

package/src/plugins/schema-filter/index.ts

@@ -0,0 +1,90 @@
+import { LegacySettings } from '../../browser'
+import { Context } from '../../core/context'
+import { PlanEvent, TrackPlan } from '../../core/events/interfaces'
+import { Plugin } from '../../core/plugin'
+import { isPlanEventEnabled } from '../../lib/is-plan-event-enabled'
+import { RemotePlugin } from '../remote-loader'
+
+function disabledActionDestinations(
+  plan: PlanEvent | undefined,
+  settings: LegacySettings
+): { [destination: string]: string[] } {
+  if (!plan || !Object.keys(plan)) {
+    return {}
+  }
+
+  const disabledIntegrations = plan.integrations
+    ? Object.keys(plan.integrations).filter(
+        (i) => plan.integrations![i] === false
+      )
+    : []
+
+  // This accounts for cases like Fullstory, where the settings.integrations
+  // contains a "Fullstory" object but settings.remotePlugins contains "Fullstory (Actions)"
+  const disabledRemotePlugins: string[] = []
+  ;(settings.remotePlugins ?? []).forEach((p: RemotePlugin) => {
+    disabledIntegrations.forEach((int) => {
+      if (p.name.includes(int) || int.includes(p.name)) {
+        disabledRemotePlugins.push(p.name)
+      }
+    })
+  })
+
+  return (settings.remotePlugins ?? []).reduce((acc, p) => {
+    if (p.settings['subscriptions']) {
+      if (disabledRemotePlugins.includes(p.name)) {
+        // @ts-expect-error element implicitly has an 'any' type because p.settings is a JSONObject
+        p.settings['subscriptions'].forEach(
+          // @ts-expect-error parameter 'sub' implicitly has an 'any' type
+          (sub) => (acc[`${p.name} ${sub.partnerAction}`] = false)
+        )
+      }
+    }
+    return acc
+  }, {})
+}
+
+export function schemaFilter(
+  track: TrackPlan | undefined,
+  settings: LegacySettings
+): Plugin {
+  function filter(ctx: Context): Context {
+    const plan = track
+    const ev = ctx.event.event
+
+    if (plan && ev) {
+      const planEvent = plan[ev]
+      if (!isPlanEventEnabled(plan, planEvent)) {
+        ctx.updateEvent('integrations', {
+          ...ctx.event.integrations,
+          All: false,
+          'Hightouch.io': true,
+        })
+        return ctx
+      } else {
+        const disabledActions = disabledActionDestinations(planEvent, settings)
+
+        ctx.updateEvent('integrations', {
+          ...ctx.event.integrations,
+          ...planEvent?.integrations,
+          ...disabledActions,
+        })
+      }
+    }
+
+    return ctx
+  }
+
+  return {
+    name: 'Schema Filter',
+    version: '0.1.0',
+    isLoaded: () => true,
+    load: () => Promise.resolve(),
+    type: 'before',
+    page: filter,
+    alias: filter,
+    track: filter,
+    identify: filter,
+    group: filter,
+  }
+}

package/src/plugins/validation/index.ts

@@ -0,0 +1,44 @@
+import type { Plugin } from '../../core/plugin'
+import type { Context } from '../../core/context'
+import {
+  assertUserIdentity,
+  isPlainObject,
+  ValidationError,
+  assertEventExists,
+  assertEventType,
+  assertTrackEventName,
+} from '@ht-sdks/events-sdk-js-core'
+
+function validate(ctx: Context): Context {
+  const event = ctx.event
+  assertEventExists(event)
+  assertEventType(event)
+
+  if (event.type === 'track') {
+    assertTrackEventName(event)
+  }
+
+  const props = event.properties ?? event.traits
+  if (event.type !== 'alias' && !isPlainObject(props)) {
+    throw new ValidationError('.properties', 'is not an object')
+  }
+
+  assertUserIdentity(event)
+  return ctx
+}
+
+export const validation: Plugin = {
+  name: 'Event Validation',
+  type: 'before',
+  version: '1.0.0',
+
+  isLoaded: () => true,
+  load: () => Promise.resolve(),
+
+  track: validate,
+  identify: validate,
+  page: validate,
+  alias: validate,
+  group: validate,
+  screen: validate,
+}

package/src/test-helpers/browser-storage.ts

@@ -0,0 +1,75 @@
+import cookie from 'js-cookie'
+
+const ajsCookieNames = [
+  'htjs_user_id',
+  'htjs_anonymous_id',
+  'htjs_group_id',
+] as const
+const ajsLocalStorageKeys = [
+  'htjs_user_traits',
+  'htjs_group_properties',
+] as const
+
+export const getAjsBrowserStorage = () => {
+  return getBrowserStorage({
+    cookieNames: ajsCookieNames,
+    localStorageKeys: ajsLocalStorageKeys,
+  })
+}
+
+export const getAnonId = () => getAjsBrowserStorage().htjs_anonymous_id
+
+export const clearAjsBrowserStorage = () => {
+  return clearBrowserStorage({
+    cookieNames: ajsCookieNames,
+    localStorageKeys: ajsLocalStorageKeys,
+  })
+}
+
+export function getBrowserStorage<
+  CookieNames extends string,
+  LSKeys extends string
+>({
+  cookieNames,
+  localStorageKeys,
+}: {
+  cookieNames: readonly CookieNames[]
+  localStorageKeys: readonly LSKeys[]
+}): Record<CookieNames | LSKeys, string | {}> {
+  const result = {} as ReturnType<typeof getBrowserStorage>
+
+  const cookies = cookie.get()
+  cookieNames.forEach((name) => {
+    if (name in cookies) {
+      result[name] = cookies[name]
+    }
+  })
+
+  localStorageKeys.forEach((key) => {
+    const value = localStorage.getItem(key)
+    if (value !== null && typeof value !== 'undefined') {
+      result[key] = JSON.parse(value)
+    }
+  })
+
+  return result
+}
+
+export function clearBrowserStorage({
+  cookieNames,
+  localStorageKeys, // if no keys are passed, the entire thing is cleared
+}: {
+  cookieNames: string[] | readonly string[]
+  localStorageKeys?: string[] | readonly string[]
+}) {
+  cookieNames.forEach((name) => {
+    cookie.remove(name)
+  })
+  if (!localStorageKeys) {
+    localStorage.clear()
+  } else {
+    localStorageKeys.forEach((key) => {
+      localStorage.removeItem(key)
+    })
+  }
+}

package/src/test-helpers/factories.ts

@@ -0,0 +1,18 @@
+export const createSuccess = (body: any, overrides: Partial<Response> = {}) => {
+  return Promise.resolve({
+    json: () => Promise.resolve(body),
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    ...overrides,
+  }) as Promise<Response>
+}
+
+export const createError = (overrides: Partial<Response> = {}) => {
+  return Promise.resolve({
+    ok: false,
+    status: 404,
+    statusText: 'Not Found',
+    ...overrides,
+  }) as Promise<Response>
+}

package/src/test-helpers/fetch-parse.ts

@@ -0,0 +1,8 @@
+export type FetchCall = [input: RequestInfo, init?: RequestInit | undefined]
+
+export const parseFetchCall = ([url, request]: FetchCall) => ({
+  url,
+  method: request?.method,
+  headers: request?.headers,
+  body: request?.body ? JSON.parse(request.body as any) : undefined,
+})