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

package/src/plugins/ajs-destination/index.ts

@@ -0,0 +1,392 @@
+import { Integrations, JSONObject } from '../../core/events'
+import { Alias, Facade, Group, Identify, Page, Track } from '@segment/facade'
+import { Analytics, InitOptions } from '../../core/analytics'
+import { LegacySettings } from '../../browser'
+import { isOffline, isOnline } from '../../core/connection'
+import { Context, ContextCancelation } from '../../core/context'
+import { isServer } from '../../core/environment'
+import { DestinationPlugin, Plugin } from '../../core/plugin'
+import { attempt } from '@ht-sdks/events-sdk-js-core'
+import { isPlanEventEnabled } from '../../lib/is-plan-event-enabled'
+import { mergedOptions } from '../../lib/merged-options'
+import { pWhile } from '../../lib/p-while'
+import { PriorityQueue } from '../../lib/priority-queue'
+import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
+import {
+  applyDestinationMiddleware,
+  DestinationMiddlewareFunction,
+} from '../middleware'
+import {
+  buildIntegration,
+  loadIntegration,
+  resolveIntegrationNameFromSource,
+  resolveVersion,
+  unloadIntegration,
+} from './loader'
+import { LegacyIntegration, ClassicIntegrationSource } from './types'
+import { isPlainObject } from '@ht-sdks/events-sdk-js-core'
+import {
+  isDisabledIntegration as shouldSkipIntegration,
+  isInstallableIntegration,
+} from './utils'
+
+export type ClassType<T> = new (...args: unknown[]) => T
+
+async function flushQueue(
+  xt: Plugin,
+  queue: PriorityQueue<Context>
+): Promise<PriorityQueue<Context>> {
+  const failedQueue: Context[] = []
+
+  if (isOffline()) {
+    return queue
+  }
+
+  await pWhile(
+    () => queue.length > 0 && isOnline(),
+    async () => {
+      const ctx = queue.pop()
+      if (!ctx) {
+        return
+      }
+
+      const result = await attempt(ctx, xt)
+      const success = result instanceof Context
+      if (!success) {
+        failedQueue.push(ctx)
+      }
+    }
+  )
+
+  // re-add failed tasks
+  failedQueue.map((failed) => queue.pushWithBackoff(failed))
+  return queue
+}
+
+export class LegacyDestination implements DestinationPlugin {
+  name: string
+  version: string
+  settings: JSONObject
+  options: InitOptions = {}
+  type: Plugin['type'] = 'destination'
+  middleware: DestinationMiddlewareFunction[] = []
+
+  private _ready = false
+  private _initialized = false
+  private onReady: Promise<unknown> | undefined
+  private onInitialize: Promise<unknown> | undefined
+  private disableAutoISOConversion: boolean
+
+  integrationSource?: ClassicIntegrationSource
+  integration: LegacyIntegration | undefined
+
+  buffer: PriorityQueue<Context>
+  flushing = false
+
+  constructor(
+    name: string,
+    version: string,
+    writeKey: string,
+    settings: JSONObject = {},
+    options: InitOptions,
+    integrationSource?: ClassicIntegrationSource
+  ) {
+    this.name = name
+    this.version = version
+    this.settings = { ...settings }
+    this.disableAutoISOConversion = options.disableAutoISOConversion || false
+    this.integrationSource = integrationSource
+
+    // AJS-Renderer sets an extraneous `type` setting that clobbers
+    // existing type defaults. We need to remove it if it's present
+    if (this.settings['type'] && this.settings['type'] === 'browser') {
+      delete this.settings['type']
+    }
+
+    this.options = options
+    this.buffer = options.disableClientPersistence
+      ? new PriorityQueue(4, [])
+      : new PersistedPriorityQueue(4, `${writeKey}:dest-${name}`)
+
+    this.scheduleFlush()
+  }
+
+  isLoaded(): boolean {
+    return this._ready
+  }
+
+  ready(): Promise<unknown> {
+    return this.onReady ?? Promise.resolve()
+  }
+
+  async load(ctx: Context, analyticsInstance: Analytics): Promise<void> {
+    if (this._ready || this.onReady !== undefined) {
+      return
+    }
+
+    const integrationSource =
+      this.integrationSource ??
+      (await loadIntegration(
+        ctx,
+        this.name,
+        this.version,
+        this.options.obfuscate
+      ))
+
+    this.integration = buildIntegration(
+      integrationSource,
+      this.settings,
+      analyticsInstance
+    )
+
+    this.onReady = new Promise((resolve) => {
+      const onReadyFn = (): void => {
+        this._ready = true
+        resolve(true)
+      }
+
+      this.integration!.once('ready', onReadyFn)
+    })
+
+    this.onInitialize = new Promise((resolve) => {
+      const onInit = (): void => {
+        this._initialized = true
+        resolve(true)
+      }
+
+      this.integration!.on('initialize', onInit)
+    })
+
+    try {
+      ctx.stats.increment('analytics_js.integration.invoke', 1, [
+        `method:initialize`,
+        `integration_name:${this.name}`,
+      ])
+
+      this.integration.initialize()
+    } catch (error) {
+      ctx.stats.increment('analytics_js.integration.invoke.error', 1, [
+        `method:initialize`,
+        `integration_name:${this.name}`,
+      ])
+
+      throw error
+    }
+  }
+
+  unload(_ctx: Context, _analyticsInstance: Analytics): Promise<void> {
+    return unloadIntegration(this.name, this.version, this.options.obfuscate)
+  }
+
+  addMiddleware(...fn: DestinationMiddlewareFunction[]): void {
+    this.middleware = this.middleware.concat(...fn)
+  }
+
+  shouldBuffer(ctx: Context): boolean {
+    return (
+      // page events can't be buffered because of destinations that automatically add page views
+      ctx.event.type !== 'page' &&
+      (isOffline() || this._ready === false || this._initialized === false)
+    )
+  }
+
+  private async send<T extends Facade>(
+    ctx: Context,
+    clz: ClassType<T>,
+    eventType: 'track' | 'identify' | 'page' | 'alias' | 'group'
+  ): Promise<Context> {
+    if (this.shouldBuffer(ctx)) {
+      this.buffer.push(ctx)
+      this.scheduleFlush()
+      return ctx
+    }
+
+    const plan = this.options?.plan?.track
+    const ev = ctx.event.event
+
+    if (plan && ev && this.name !== 'Hightouch.io') {
+      // events are always sent to hightouch (legacy behavior)
+      const planEvent = plan[ev]
+      if (!isPlanEventEnabled(plan, planEvent)) {
+        ctx.updateEvent('integrations', {
+          ...ctx.event.integrations,
+          All: false,
+          'Hightouch.io': true,
+        })
+        ctx.cancel(
+          new ContextCancelation({
+            retry: false,
+            reason: `Event ${ev} disabled for integration ${this.name} in tracking plan`,
+            type: 'Dropped by plan',
+          })
+        )
+        return ctx
+      } else {
+        ctx.updateEvent('integrations', {
+          ...ctx.event.integrations,
+          ...planEvent?.integrations,
+        })
+      }
+
+      if (planEvent?.enabled && planEvent?.integrations![this.name] === false) {
+        ctx.cancel(
+          new ContextCancelation({
+            retry: false,
+            reason: `Event ${ev} disabled for integration ${this.name} in tracking plan`,
+            type: 'Dropped by plan',
+          })
+        )
+        return ctx
+      }
+    }
+
+    const afterMiddleware = await applyDestinationMiddleware(
+      this.name,
+      ctx.event,
+      this.middleware
+    )
+
+    if (afterMiddleware === null) {
+      return ctx
+    }
+
+    const event = new clz(afterMiddleware, {
+      traverse: !this.disableAutoISOConversion,
+    })
+
+    ctx.stats.increment('analytics_js.integration.invoke', 1, [
+      `method:${eventType}`,
+      `integration_name:${this.name}`,
+    ])
+
+    try {
+      if (this.integration) {
+        await this.integration.invoke.call(this.integration, eventType, event)
+      }
+    } catch (err) {
+      ctx.stats.increment('analytics_js.integration.invoke.error', 1, [
+        `method:${eventType}`,
+        `integration_name:${this.name}`,
+      ])
+      throw err
+    }
+
+    return ctx
+  }
+
+  async track(ctx: Context): Promise<Context> {
+    return this.send(ctx, Track as ClassType<Track>, 'track')
+  }
+
+  async page(ctx: Context): Promise<Context> {
+    if (this.integration?._assumesPageview && !this._initialized) {
+      this.integration.initialize()
+    }
+
+    return this.onInitialize!.then(() => {
+      return this.send(ctx, Page as ClassType<Page>, 'page')
+    })
+  }
+
+  async identify(ctx: Context): Promise<Context> {
+    return this.send(ctx, Identify as ClassType<Identify>, 'identify')
+  }
+
+  async alias(ctx: Context): Promise<Context> {
+    return this.send(ctx, Alias as ClassType<Alias>, 'alias')
+  }
+
+  async group(ctx: Context): Promise<Context> {
+    return this.send(ctx, Group as ClassType<Group>, 'group')
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushing) {
+      return
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    setTimeout(async () => {
+      this.flushing = true
+      this.buffer = await flushQueue(this, this.buffer)
+      this.flushing = false
+
+      if (this.buffer.todo > 0) {
+        this.scheduleFlush()
+      }
+    }, Math.random() * 5000)
+  }
+}
+
+export function ajsDestinations(
+  writeKey: string,
+  settings: LegacySettings,
+  globalIntegrations: Integrations = {},
+  options: InitOptions = {},
+  routingMiddleware?: DestinationMiddlewareFunction,
+  legacyIntegrationSources?: ClassicIntegrationSource[]
+): LegacyDestination[] {
+  if (isServer()) {
+    return []
+  }
+
+  if (settings.plan) {
+    options = options ?? {}
+    options.plan = settings.plan
+  }
+
+  const routingRules = settings.middlewareSettings?.routingRules ?? []
+  const remoteIntegrationsConfig = settings.integrations
+  const localIntegrationsConfig = options.integrations
+  // merged remote CDN settings with user provided options
+  const integrationOptions = mergedOptions(settings, options ?? {}) as Record<
+    string,
+    JSONObject
+  >
+
+  const adhocIntegrationSources = legacyIntegrationSources?.reduce(
+    (acc, integrationSource) => ({
+      ...acc,
+      [resolveIntegrationNameFromSource(integrationSource)]: integrationSource,
+    }),
+    {} as Record<string, ClassicIntegrationSource>
+  )
+
+  const installableIntegrations = new Set([
+    // Remotely configured installable integrations
+    ...Object.keys(remoteIntegrationsConfig).filter((name) =>
+      isInstallableIntegration(name, remoteIntegrationsConfig[name])
+    ),
+
+    // Directly provided integration sources are only installable if settings for them are available
+    ...Object.keys(adhocIntegrationSources || {}).filter(
+      (name) =>
+        isPlainObject(remoteIntegrationsConfig[name]) ||
+        isPlainObject(localIntegrationsConfig?.[name])
+    ),
+  ])
+
+  return Array.from(installableIntegrations)
+    .filter((name) => !shouldSkipIntegration(name, globalIntegrations))
+    .map((name) => {
+      const integrationSettings = remoteIntegrationsConfig[name]
+      const version = resolveVersion(integrationSettings)
+      const destination = new LegacyDestination(
+        name,
+        version,
+        writeKey,
+        integrationOptions[name],
+        options,
+        adhocIntegrationSources?.[name]
+      )
+
+      const routing = routingRules.filter(
+        (rule) => rule.destinationName === name
+      )
+      if (routing.length > 0 && routingMiddleware) {
+        destination.addMiddleware(routingMiddleware)
+      }
+
+      return destination
+    })
+}

package/src/plugins/ajs-destination/loader.ts

@@ -0,0 +1,129 @@
+import { Analytics } from '../../core/analytics'
+import { LegacyIntegrationConfiguration } from '../../browser'
+import { getNextIntegrationsURL } from '../../lib/parse-cdn'
+import { Context } from '../../core/context'
+import { User } from '../../core/user'
+import { loadScript, unloadScript } from '../../lib/load-script'
+import {
+  LegacyIntegration,
+  ClassicIntegrationBuilder,
+  ClassicIntegrationSource,
+} from './types'
+
+function normalizeName(name: string): string {
+  return name.toLowerCase().replace('.', '').replace(/\s+/g, '-')
+}
+
+function obfuscatePathName(pathName: string, obfuscate = false): string | void {
+  return obfuscate ? btoa(pathName).replace(/=/g, '') : undefined
+}
+
+export function resolveIntegrationNameFromSource(
+  integrationSource: ClassicIntegrationSource
+) {
+  return (
+    'Integration' in integrationSource
+      ? integrationSource.Integration
+      : integrationSource
+  ).prototype.name
+}
+
+function recordLoadMetrics(fullPath: string, ctx: Context, name: string): void {
+  try {
+    const [metric] =
+      window?.performance?.getEntriesByName(fullPath, 'resource') ?? []
+    // we assume everything that took under 100ms is cached
+    metric &&
+      ctx.stats.gauge('legacy_destination_time', Math.round(metric.duration), [
+        name,
+        ...(metric.duration < 100 ? ['cached'] : []),
+      ])
+  } catch (_) {
+    // not available
+  }
+}
+
+export function buildIntegration(
+  integrationSource: ClassicIntegrationSource,
+  integrationSettings: { [key: string]: any },
+  analyticsInstance: Analytics
+): LegacyIntegration {
+  let integrationCtr: ClassicIntegrationBuilder
+  // GA and Appcues use a different interface to instantiating integrations
+  if ('Integration' in integrationSource) {
+    const analyticsStub = {
+      user: (): User => analyticsInstance.user(),
+      addIntegration: (): void => {},
+    }
+
+    integrationSource(analyticsStub)
+    integrationCtr = integrationSource.Integration
+  } else {
+    integrationCtr = integrationSource
+  }
+
+  const integration = new integrationCtr(integrationSettings)
+  integration.analytics = analyticsInstance
+  return integration
+}
+
+export async function loadIntegration(
+  ctx: Context,
+  name: string,
+  version: string,
+  obfuscate?: boolean
+): Promise<ClassicIntegrationSource> {
+  const pathName = normalizeName(name)
+  const obfuscatedPathName = obfuscatePathName(pathName, obfuscate)
+  const path = getNextIntegrationsURL()
+
+  const fullPath = `${path}/integrations/${
+    obfuscatedPathName ?? pathName
+  }/${version}/${obfuscatedPathName ?? pathName}.dynamic.js.gz`
+
+  try {
+    await loadScript(fullPath)
+    recordLoadMetrics(fullPath, ctx, name)
+  } catch (err) {
+    ctx.stats.gauge('legacy_destination_time', -1, [`plugin:${name}`, `failed`])
+    throw err
+  }
+
+  // @ts-ignore
+  const deps: string[] = window[`${pathName}Deps`]
+  await Promise.all(deps.map((dep) => loadScript(path + dep + '.gz')))
+
+  // @ts-ignore
+  window[`${pathName}Loader`]()
+
+  return window[
+    // @ts-ignore
+    `${pathName}Integration`
+  ] as ClassicIntegrationSource
+}
+
+export async function unloadIntegration(
+  name: string,
+  version: string,
+  obfuscate?: boolean
+): Promise<void> {
+  const path = getNextIntegrationsURL()
+  const pathName = normalizeName(name)
+  const obfuscatedPathName = obfuscatePathName(name, obfuscate)
+
+  const fullPath = `${path}/integrations/${
+    obfuscatedPathName ?? pathName
+  }/${version}/${obfuscatedPathName ?? pathName}.dynamic.js.gz`
+
+  return unloadScript(fullPath)
+}
+
+export function resolveVersion(
+  settings?: LegacyIntegrationConfiguration
+): string {
+  return (
+    settings?.versionSettings?.override ??
+    settings?.versionSettings?.version ??
+    'latest'
+  )
+}

package/src/plugins/ajs-destination/types.ts

@@ -0,0 +1,44 @@
+import { Group, Identify, Track, Page, Alias } from '@segment/facade'
+import { Analytics } from '../../core/analytics'
+import { Emitter } from '@ht-sdks/events-sdk-js-core'
+import { User } from '../../core/user'
+
+export interface LegacyIntegration extends Emitter {
+  name: string
+  analytics?: Analytics
+  initialize: () => void
+  loaded: () => boolean
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  invoke: (method: string, ...args: any[]) => unknown
+
+  track?: (event: Track) => void | Promise<void>
+  identify?: (event: Identify) => void | Promise<void>
+  page?: (event: Page) => void | Promise<void>
+  alias?: (event: Alias) => void | Promise<void>
+  group?: (event: Group) => void | Promise<void>
+
+  // Segment.io specific
+  ontrack?: (event: Track) => void | Promise<void>
+  onidentify?: (event: Identify) => void | Promise<void>
+  onpage?: (event: Page) => void | Promise<void>
+  onalias?: (event: Alias) => void | Promise<void>
+  ongroup?: (event: Group) => void | Promise<void>
+
+  _assumesPageview?: boolean
+  options?: object
+}
+
+export interface ClassicIntegrationBuilder {
+  new (options: object): LegacyIntegration
+  prototype: LegacyIntegration
+}
+
+export interface ClassicIntegrationGenerator {
+  (analytics: { user: () => User; addIntegration: () => void }): void
+  Integration: ClassicIntegrationBuilder
+}
+
+export type ClassicIntegrationSource =
+  | ClassicIntegrationGenerator
+  | ClassicIntegrationBuilder

package/src/plugins/ajs-destination/utils.ts

@@ -0,0 +1,32 @@
+import { Integrations } from '@ht-sdks/events-sdk-js-core'
+import { LegacyIntegrationConfiguration } from '../..'
+
+export const isInstallableIntegration = (
+  name: string,
+  integrationSettings: LegacyIntegrationConfiguration
+) => {
+  const { type, bundlingStatus, versionSettings } = integrationSettings
+  // We use `!== 'unbundled'` (versus `=== 'bundled'`) to be inclusive of
+  // destinations without a defined value for `bundlingStatus`
+  const deviceMode =
+    bundlingStatus !== 'unbundled' &&
+    (type === 'browser' || versionSettings?.componentTypes?.includes('browser'))
+
+  // checking for iterable is a quick fix we need in place to prevent
+  // errors showing Iterable as a failed destiantion. Ideally, we should
+  // fix the Iterable metadata instead, but that's a longer process.
+  return !name.startsWith('Segment') && name !== 'Iterable' && deviceMode
+}
+
+export const isDisabledIntegration = (
+  integrationName: string,
+  globalIntegrations: Integrations
+) => {
+  const allDisableAndNotDefined =
+    globalIntegrations.All === false &&
+    globalIntegrations[integrationName] === undefined
+
+  return (
+    globalIntegrations[integrationName] === false || allDisableAndNotDefined
+  )
+}

package/src/plugins/analytics-node/index.ts

@@ -0,0 +1,67 @@
+import { Plugin } from '../../core/plugin'
+import { Context } from '../../core/context'
+import { SegmentEvent } from '../../core/events'
+import fetch from 'node-fetch'
+import { version } from '../../generated/version'
+
+interface AnalyticsNodeSettings {
+  writeKey: string
+  name: string
+  type: Plugin['type']
+  version: string
+}
+
+const btoa = (val: string): string => Buffer.from(val).toString('base64')
+
+export async function post(
+  event: SegmentEvent,
+  writeKey: string
+): Promise<SegmentEvent> {
+  const res = await fetch(
+    `https://us-east-1.hightouch-events.com/v1/${event.type}`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'analytics-node-next/latest',
+        Authorization: `Basic ${btoa(writeKey)}`,
+      },
+      body: JSON.stringify(event),
+    }
+  )
+
+  if (!res.ok) {
+    throw new Error('Message Rejected')
+  }
+
+  return event
+}
+
+export function analyticsNode(settings: AnalyticsNodeSettings): Plugin {
+  const send = async (ctx: Context): Promise<Context> => {
+    ctx.updateEvent('context.library.name', 'analytics-node-next')
+    ctx.updateEvent('context.library.version', version)
+    ctx.updateEvent('_metadata.nodeVersion', process.versions.node)
+
+    await post(ctx.event, settings.writeKey)
+    return ctx
+  }
+
+  const plugin: Plugin = {
+    name: settings.name,
+    type: settings.type,
+    version: settings.version,
+
+    load: (ctx) => Promise.resolve(ctx),
+    isLoaded: () => true,
+
+    track: send,
+    identify: send,
+    page: send,
+    alias: send,
+    group: send,
+    screen: send,
+  }
+
+  return plugin
+}