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

package/src/core/buffer/index.ts

@@ -0,0 +1,371 @@
+import { Analytics } from '../analytics'
+import { Context } from '../context'
+import { isThenable } from '../../lib/is-thenable'
+import { AnalyticsBrowserCore } from '../analytics/interfaces'
+import { version } from '../../generated/version'
+import { getGlobalAnalytics } from '../../lib/global-analytics-helper'
+import {
+  isBufferedPageContext,
+  BufferedPageContext,
+  getDefaultBufferedPageContext,
+  createPageContext,
+  PageContext,
+} from '../page'
+
+/**
+ * The names of any AnalyticsBrowser methods that also exist on Analytics
+ */
+export type PreInitMethodName =
+  | 'screen'
+  | 'register'
+  | 'deregister'
+  | 'user'
+  | 'trackSubmit'
+  | 'trackClick'
+  | 'trackLink'
+  | 'trackForm'
+  | 'pageview'
+  | 'identify'
+  | 'reset'
+  | 'group'
+  | 'track'
+  | 'ready'
+  | 'alias'
+  | 'debug'
+  | 'page'
+  | 'once'
+  | 'off'
+  | 'on'
+  | 'addSourceMiddleware'
+  | 'setAnonymousId'
+  | 'addDestinationMiddleware'
+
+// Union of all analytics methods that _do not_ return a Promise
+type SyncPreInitMethodName = {
+  [MethodName in PreInitMethodName]: ReturnType<
+    Analytics[MethodName]
+  > extends Promise<any>
+    ? never
+    : MethodName
+}[PreInitMethodName]
+
+const flushSyncAnalyticsCalls = (
+  name: SyncPreInitMethodName,
+  analytics: Analytics,
+  buffer: PreInitMethodCallBuffer
+): void => {
+  buffer.getCalls(name).forEach((c) => {
+    // While the underlying methods are synchronous, the callAnalyticsMethod returns a promise,
+    // which normalizes success and error states between async and non-async methods, with no perf penalty.
+    callAnalyticsMethod(analytics, c).catch(console.error)
+  })
+}
+
+export const flushAddSourceMiddleware = async (
+  analytics: Analytics,
+  buffer: PreInitMethodCallBuffer
+) => {
+  for (const c of buffer.getCalls('addSourceMiddleware')) {
+    await callAnalyticsMethod(analytics, c).catch(console.error)
+  }
+}
+
+export const flushOn = flushSyncAnalyticsCalls.bind(this, 'on')
+
+export const flushSetAnonymousID = flushSyncAnalyticsCalls.bind(
+  this,
+  'setAnonymousId'
+)
+
+export const flushAnalyticsCallsInNewTask = (
+  analytics: Analytics,
+  buffer: PreInitMethodCallBuffer
+): void => {
+  buffer.toArray().forEach((m) => {
+    setTimeout(() => {
+      callAnalyticsMethod(analytics, m).catch(console.error)
+    }, 0)
+  })
+}
+
+export const popPageContext = (args: unknown[]): PageContext | undefined => {
+  if (hasBufferedPageContextAsLastArg(args)) {
+    const ctx = args.pop() as BufferedPageContext
+    return createPageContext(ctx)
+  }
+}
+
+export const hasBufferedPageContextAsLastArg = (
+  args: unknown[]
+): args is [...unknown[], BufferedPageContext] | [BufferedPageContext] => {
+  const lastArg = args[args.length - 1]
+  return isBufferedPageContext(lastArg)
+}
+
+/**
+ *  Represents a buffered method call that occurred before initialization.
+ */
+export class PreInitMethodCall<
+  MethodName extends PreInitMethodName = PreInitMethodName
+> {
+  method: MethodName
+  args: PreInitMethodParams<MethodName>
+  called: boolean
+  resolve: (v: ReturnType<Analytics[MethodName]>) => void
+  reject: (reason: any) => void
+  constructor(
+    method: PreInitMethodCall<MethodName>['method'],
+    args: PreInitMethodParams<MethodName>,
+    resolve: PreInitMethodCall<MethodName>['resolve'] = () => {},
+    reject: PreInitMethodCall<MethodName>['reject'] = console.error
+  ) {
+    this.method = method
+    this.resolve = resolve
+    this.reject = reject
+    this.called = false
+    this.args = args
+  }
+}
+
+export type PreInitMethodParams<MethodName extends PreInitMethodName> =
+  | [...Parameters<Analytics[MethodName]>, BufferedPageContext]
+  | Parameters<Analytics[MethodName]>
+
+/**
+ * Infer return type; if return type is promise, unwrap it.
+ */
+type ReturnTypeUnwrap<Fn> = Fn extends (...args: any[]) => infer ReturnT
+  ? ReturnT extends PromiseLike<infer Unwrapped>
+    ? Unwrapped
+    : ReturnT
+  : never
+
+type MethodCallMap = Partial<Record<PreInitMethodName, PreInitMethodCall[]>>
+
+type SnippetWindowBufferedMethodCall<
+  MethodName extends PreInitMethodName = PreInitMethodName
+> = [MethodName, ...PreInitMethodParams<MethodName>]
+
+/**
+ * A list of the method calls before initialization for snippet users
+ * For example, [["track", "foo", {bar: 123}], ["page"], ["on", "ready", function(){..}]
+ */
+type SnippetBuffer = SnippetWindowBufferedMethodCall[]
+
+/**
+ *  Represents any and all the buffered method calls that occurred before initialization.
+ */
+export class PreInitMethodCallBuffer {
+  private _callMap: MethodCallMap = {}
+
+  constructor(...calls: PreInitMethodCall[]) {
+    this.push(...calls)
+  }
+
+  /**
+   * Pull any buffered method calls from the window object, and use them to hydrate the instance buffer.
+   */
+  private get calls() {
+    this._pushSnippetWindowBuffer()
+    return this._callMap
+  }
+
+  private set calls(calls: MethodCallMap) {
+    this._callMap = calls
+  }
+
+  getCalls<T extends PreInitMethodName>(methodName: T): PreInitMethodCall<T>[] {
+    return (this.calls[methodName] ?? []) as PreInitMethodCall<T>[]
+  }
+
+  push(...calls: PreInitMethodCall[]): void {
+    calls.forEach((call) => {
+      const eventsExpectingPageContext: PreInitMethodName[] = [
+        'track',
+        'screen',
+        'alias',
+        'group',
+        'page',
+        'identify',
+      ]
+      if (
+        eventsExpectingPageContext.includes(call.method) &&
+        !hasBufferedPageContextAsLastArg(call.args)
+      ) {
+        call.args = [...call.args, getDefaultBufferedPageContext()]
+      }
+
+      if (this.calls[call.method]) {
+        this.calls[call.method]!.push(call)
+      } else {
+        this.calls[call.method] = [call]
+      }
+    })
+  }
+
+  clear(): void {
+    // clear calls in the global snippet buffered array.
+    this._pushSnippetWindowBuffer()
+    // clear calls in this instance
+    this.calls = {}
+  }
+
+  toArray(): PreInitMethodCall[] {
+    return ([] as PreInitMethodCall[]).concat(...Object.values(this.calls))
+  }
+
+  /**
+   * Fetch the buffered method calls from the window object,
+   * normalize them, and use them to hydrate the buffer.
+   * This removes existing buffered calls from the window object.
+   */
+  private _pushSnippetWindowBuffer(): void {
+    const wa = getGlobalAnalytics()
+    if (!Array.isArray(wa)) return undefined
+    const buffered: SnippetBuffer = wa.splice(0, wa.length)
+    const calls = buffered.map(
+      ([methodName, ...args]) => new PreInitMethodCall(methodName, args)
+    )
+    this.push(...calls)
+  }
+}
+
+/**
+ *  Call method and mark as "called"
+ *  This function should never throw an error
+ */
+export async function callAnalyticsMethod<T extends PreInitMethodName>(
+  analytics: Analytics,
+  call: PreInitMethodCall<T>
+): Promise<void> {
+  try {
+    if (call.called) {
+      return undefined
+    }
+    call.called = true
+
+    const result: ReturnType<Analytics[T]> = (
+      analytics[call.method] as Function
+    )(...call.args)
+
+    if (isThenable(result)) {
+      // do not defer for non-async methods
+      await result
+    }
+
+    call.resolve(result)
+  } catch (err) {
+    call.reject(err)
+  }
+}
+
+export type AnalyticsLoader = (
+  preInitBuffer: PreInitMethodCallBuffer
+) => Promise<[Analytics, Context]>
+
+export class AnalyticsBuffered
+  implements PromiseLike<[Analytics, Context]>, AnalyticsBrowserCore
+{
+  instance?: Analytics
+  ctx?: Context
+  private _preInitBuffer: PreInitMethodCallBuffer
+  private _promise: Promise<[Analytics, Context]>
+  constructor(loader: AnalyticsLoader) {
+    this._preInitBuffer = new PreInitMethodCallBuffer()
+    this._promise = loader(this._preInitBuffer)
+    this._promise
+      .then(([ajs, ctx]) => {
+        this.instance = ajs
+        this.ctx = ctx
+      })
+      .catch(() => {
+        // intentionally do nothing...
+        // this result of this promise will be caught by the 'catch' block on this class.
+      })
+  }
+
+  then<T1, T2 = never>(
+    ...args: [
+      onfulfilled:
+        | ((instance: [Analytics, Context]) => T1 | PromiseLike<T1>)
+        | null
+        | undefined,
+      onrejected?: (reason: unknown) => T2 | PromiseLike<T2>
+    ]
+  ) {
+    return this._promise.then(...args)
+  }
+
+  catch<TResult = never>(
+    ...args: [
+      onrejected?:
+        | ((reason: any) => TResult | PromiseLike<TResult>)
+        | undefined
+        | null
+    ]
+  ) {
+    return this._promise.catch(...args)
+  }
+
+  finally(...args: [onfinally?: (() => void) | undefined | null]) {
+    return this._promise.finally(...args)
+  }
+
+  trackSubmit = this._createMethod('trackSubmit')
+  trackClick = this._createMethod('trackClick')
+  trackLink = this._createMethod('trackLink')
+  pageView = this._createMethod('pageview')
+  identify = this._createMethod('identify')
+  reset = this._createMethod('reset')
+  group = this._createMethod('group') as AnalyticsBrowserCore['group']
+  track = this._createMethod('track')
+  ready = this._createMethod('ready')
+  alias = this._createMethod('alias')
+  debug = this._createChainableMethod('debug')
+  page = this._createMethod('page')
+  once = this._createChainableMethod('once')
+  off = this._createChainableMethod('off')
+  on = this._createChainableMethod('on')
+  addSourceMiddleware = this._createMethod('addSourceMiddleware')
+  setAnonymousId = this._createMethod('setAnonymousId')
+  addDestinationMiddleware = this._createMethod('addDestinationMiddleware')
+
+  screen = this._createMethod('screen')
+  register = this._createMethod('register')
+  deregister = this._createMethod('deregister')
+  user = this._createMethod('user')
+  readonly VERSION = version
+
+  private _createMethod<T extends PreInitMethodName>(methodName: T) {
+    return (
+      ...args: Parameters<Analytics[T]>
+    ): Promise<ReturnTypeUnwrap<Analytics[T]>> => {
+      if (this.instance) {
+        const result = (this.instance[methodName] as Function)(...args)
+        return Promise.resolve(result)
+      }
+      return new Promise((resolve, reject) => {
+        this._preInitBuffer.push(
+          new PreInitMethodCall(methodName, args, resolve as any, reject)
+        )
+      })
+    }
+  }
+
+  /**
+   *  These are for methods that where determining when the method gets "flushed" is not important.
+   *  These methods will resolve when analytics is fully initialized, and return type (other than Analytics)will not be available.
+   */
+  private _createChainableMethod<T extends PreInitMethodName>(methodName: T) {
+    return (...args: Parameters<Analytics[T]>): AnalyticsBuffered => {
+      if (this.instance) {
+        void (this.instance[methodName] as Function)(...args)
+        return this
+      } else {
+        this._preInitBuffer.push(new PreInitMethodCall(methodName, args))
+      }
+
+      return this
+    }
+  }
+}

package/src/core/callback/index.ts

@@ -0,0 +1 @@
+export { invokeCallback, pTimeout } from '@ht-sdks/events-sdk-js-core'

package/src/core/connection/index.ts

@@ -0,0 +1,13 @@
+import { isBrowser } from '../environment'
+
+export function isOnline(): boolean {
+  if (isBrowser()) {
+    return window.navigator.onLine
+  }
+
+  return true
+}
+
+export function isOffline(): boolean {
+  return !isOnline()
+}

package/src/core/constants/index.ts

@@ -0,0 +1 @@
+export const HIGHTOUCH_API_HOST = 'us-east-1.hightouch-events.com'

package/src/core/context/index.ts

@@ -0,0 +1,21 @@
+import {
+  CoreContext,
+  ContextCancelation,
+  ContextFailedDelivery,
+  SerializedContext,
+  CancelationOptions,
+} from '@ht-sdks/events-sdk-js-core'
+import { SegmentEvent } from '../events/interfaces'
+import { Stats } from '../stats'
+
+export class Context extends CoreContext<SegmentEvent> {
+  static override system() {
+    return new this({ type: 'track', event: 'system' })
+  }
+  constructor(event: SegmentEvent, id?: string) {
+    super(event, id, new Stats())
+  }
+}
+
+export { ContextCancelation }
+export type { ContextFailedDelivery, SerializedContext, CancelationOptions }

package/src/core/environment/index.ts

@@ -0,0 +1,7 @@
+export function isBrowser(): boolean {
+  return typeof window !== 'undefined'
+}
+
+export function isServer(): boolean {
+  return !isBrowser()
+}

package/src/core/events/index.ts

@@ -0,0 +1,277 @@
+import { v4 as uuid } from '@lukeed/uuid'
+import { dset } from 'dset'
+import { ID, User } from '../user'
+import {
+  Options,
+  Integrations,
+  EventProperties,
+  Traits,
+  SegmentEvent,
+} from './interfaces'
+import md5 from 'spark-md5'
+import { addPageContext, PageContext } from '../page'
+
+export * from './interfaces'
+
+export class EventFactory {
+  constructor(public user: User) {}
+
+  track(
+    event: string,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): SegmentEvent {
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        event,
+        type: 'track' as const,
+        properties,
+        options: { ...options },
+        integrations: { ...globalIntegrations },
+      },
+      pageCtx
+    )
+  }
+
+  page(
+    category: string | null,
+    page: string | null,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): SegmentEvent {
+    const event: Partial<SegmentEvent> = {
+      type: 'page' as const,
+      properties: { ...properties },
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    }
+
+    if (category !== null) {
+      event.category = category
+      event.properties = event.properties ?? {}
+      event.properties.category = category
+    }
+
+    if (page !== null) {
+      event.name = page
+    }
+
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        ...event,
+      } as SegmentEvent,
+      pageCtx
+    )
+  }
+
+  screen(
+    category: string | null,
+    screen: string | null,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): SegmentEvent {
+    const event: Partial<SegmentEvent> = {
+      type: 'screen' as const,
+      properties: { ...properties },
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    }
+
+    if (category !== null) {
+      event.category = category
+    }
+
+    if (screen !== null) {
+      event.name = screen
+    }
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        ...event,
+      } as SegmentEvent,
+      pageCtx
+    )
+  }
+
+  identify(
+    userId: ID,
+    traits?: Traits,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): SegmentEvent {
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        type: 'identify' as const,
+        userId,
+        traits,
+        options: { ...options },
+        integrations: { ...globalIntegrations },
+      },
+      pageCtx
+    )
+  }
+
+  group(
+    groupId: ID,
+    traits?: Traits,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): SegmentEvent {
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        type: 'group' as const,
+        traits,
+        options: { ...options },
+        integrations: { ...globalIntegrations },
+        groupId,
+      },
+      pageCtx
+    )
+  }
+
+  alias(
+    to: string,
+    from: string | null,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): SegmentEvent {
+    const base: Partial<SegmentEvent> = {
+      userId: to,
+      type: 'alias' as const,
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    }
+
+    if (from !== null) {
+      base.previousId = from
+    }
+
+    if (to === undefined) {
+      return this.normalize({
+        ...base,
+        ...this.baseEvent(),
+      } as SegmentEvent)
+    }
+
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        ...base,
+      } as SegmentEvent,
+      pageCtx
+    )
+  }
+
+  private baseEvent(): Partial<SegmentEvent> {
+    const base: Partial<SegmentEvent> = {
+      integrations: {},
+      options: {},
+    }
+
+    const user = this.user
+
+    if (user.id()) {
+      base.userId = user.id()
+    }
+
+    if (user.anonymousId()) {
+      base.anonymousId = user.anonymousId()
+    }
+
+    return base
+  }
+
+  /**
+   * Builds the context part of an event based on "foreign" keys that
+   * are provided in the `Options` parameter for an Event
+   */
+  private context(event: SegmentEvent): [object, object] {
+    const optionsKeys = ['integrations', 'anonymousId', 'timestamp', 'userId']
+
+    const options = event.options ?? {}
+    delete options['integrations']
+
+    const providedOptionsKeys = Object.keys(options)
+
+    const context = event.options?.context ?? {}
+    const overrides = {}
+
+    providedOptionsKeys.forEach((key) => {
+      if (key === 'context') {
+        return
+      }
+
+      if (optionsKeys.includes(key)) {
+        dset(overrides, key, options[key])
+      } else {
+        dset(context, key, options[key])
+      }
+    })
+
+    return [context, overrides]
+  }
+
+  public normalize(event: SegmentEvent, pageCtx?: PageContext): SegmentEvent {
+    // set anonymousId globally if we encounter an override
+    event.options?.anonymousId &&
+      this.user.anonymousId(event.options.anonymousId)
+
+    const integrationBooleans = Object.keys(event.integrations ?? {}).reduce(
+      (integrationNames, name) => {
+        return {
+          ...integrationNames,
+          [name]: Boolean(event.integrations?.[name]),
+        }
+      },
+      {} as Record<string, boolean>
+    )
+
+    // This is pretty trippy, but here's what's going on:
+    // - a) We don't pass initial integration options as part of the event, only if they're true or false
+    // - b) We do accept per integration overrides (like integrations.Amplitude.sessionId) at the event level
+    // Hence the need to convert base integration options to booleans, but maintain per event integration overrides
+    const allIntegrations = {
+      // Base config integrations object as booleans
+      ...integrationBooleans,
+
+      // Per event overrides, for things like amplitude sessionId, for example
+      ...event.options?.integrations,
+    }
+
+    const [context, overrides] = this.context(event)
+    const { options, ...rest } = event
+
+    const newEvent: SegmentEvent = {
+      timestamp: new Date(),
+      ...rest,
+      context,
+      integrations: allIntegrations,
+      ...overrides,
+      messageId: md5.hash(JSON.stringify(event) + uuid()),
+    }
+    addPageContext(newEvent, pageCtx)
+
+    const session = this.user.getAndUpdateSession()
+    if (session != null) {
+      newEvent.context = {
+        ...newEvent.context,
+        ...session,
+      }
+    }
+
+    return newEvent
+  }
+}