@customerio/cdp-analytics-browser 0.0.1

package/src/core/arguments-resolver/index.ts

@@ -0,0 +1,166 @@
+import {
+  isFunction,
+  isPlainObject,
+  isString,
+  isNumber,
+} from '../../plugins/validation'
+import { Context } from '../context'
+import {
+  Callback,
+  JSONObject,
+  Options,
+  EventProperties,
+  CustomerioEvent,
+  Traits,
+  GroupTraits,
+  UserTraits,
+} from '../events'
+import { ID, User } from '../user'
+
+/**
+ * Helper for the track method
+ */
+export function resolveArguments(
+  eventName: string | CustomerioEvent,
+  properties?: EventProperties | Callback,
+  options?: Options | Callback,
+  callback?: Callback
+): [string, EventProperties | Callback, Options, Callback | undefined] {
+  const args = [eventName, properties, options, callback]
+
+  const name = isPlainObject(eventName) ? eventName.event : eventName
+  if (!name || !isString(name)) {
+    throw new Error('Event missing')
+  }
+
+  const data = isPlainObject(eventName)
+    ? eventName.properties ?? {}
+    : isPlainObject(properties)
+      ? properties
+      : {}
+
+  let opts: Options = {}
+  if (!isFunction(options)) {
+    opts = options ?? {}
+  }
+
+  if (isPlainObject(eventName) && !isFunction(properties)) {
+    opts = properties ?? {}
+  }
+
+  const cb = args.find(isFunction) as Callback | undefined
+  return [name, data, opts, cb]
+}
+
+/**
+ * Helper for page, screen methods
+ */
+export function resolvePageArguments(
+  category?: string | object,
+  name?: string | object | Callback,
+  properties?: EventProperties | Options | Callback | null,
+  options?: Options | Callback,
+  callback?: Callback
+): [
+    string | null,
+    string | null,
+    EventProperties,
+    Options,
+    Callback | undefined
+  ] {
+  let resolvedCategory: string | undefined | null = null
+  let resolvedName: string | undefined | null = null
+  const args = [category, name, properties, options, callback]
+
+  const strings = args.filter(isString)
+  if (strings[0] !== undefined && strings[1] !== undefined) {
+    resolvedCategory = strings[0]
+    resolvedName = strings[1]
+  }
+
+  if (strings.length === 1) {
+    resolvedCategory = null
+    resolvedName = strings[0]
+  }
+
+  const resolvedCallback = args.find(isFunction) as Callback | undefined
+
+  const objects = args.filter((obj) => {
+    if (resolvedName === null) {
+      return isPlainObject(obj)
+    }
+    return isPlainObject(obj) || obj === null
+  }) as Array<JSONObject | null>
+
+  const resolvedProperties = (objects[0] ?? {}) as EventProperties
+  const resolvedOptions = (objects[1] ?? {}) as Options
+
+  return [
+    resolvedCategory,
+    resolvedName,
+    resolvedProperties,
+    resolvedOptions,
+    resolvedCallback,
+  ]
+}
+
+/**
+ * Helper for group, identify methods
+ */
+export const resolveUserArguments = <T extends Traits, U extends User>(
+  user: U
+): ResolveUser<T> => {
+  return (...args): ReturnType<ResolveUser<T>> => {
+    let id: string | ID | null = null
+    id = args.find(isString) ?? args.find(isNumber)?.toString() ?? user.id()
+
+    const objects = args.filter((obj) => {
+      if (id === null) {
+        return isPlainObject(obj)
+      }
+      return isPlainObject(obj) || obj === null
+    }) as Array<Traits | null>
+
+    const traits = (objects[0] ?? {}) as T
+    const opts = (objects[1] ?? {}) as Options
+
+    const resolvedCallback = args.find(isFunction) as Callback | undefined
+
+    return [id, traits, opts, resolvedCallback]
+  }
+}
+
+/**
+ * Helper for alias method
+ */
+export function resolveAliasArguments(
+  to: string | number,
+  from?: string | number | Options,
+  options?: Options | Callback,
+  callback?: Callback
+): [string, string | null, Options, Callback | undefined] {
+  if (isNumber(to)) to = to.toString() // Legacy behaviour - allow integers for alias calls
+  if (isNumber(from)) from = from.toString()
+  const args = [to, from, options, callback]
+
+  const [aliasTo = to, aliasFrom = null] = args.filter(isString)
+  const [opts = {}] = args.filter(isPlainObject)
+  const resolvedCallback = args.find(isFunction) as Callback | undefined
+
+  return [aliasTo, aliasFrom, opts, resolvedCallback]
+}
+
+type ResolveUser<T extends Traits> = (
+  id?: ID | object,
+  traits?: T | Callback | null,
+  options?: Options | Callback,
+  callback?: Callback
+) => [ID, T, Options, Callback | undefined]
+
+export type IdentifyParams = Parameters<ResolveUser<UserTraits>>
+export type GroupParams = Parameters<ResolveUser<GroupTraits>>
+export type EventParams = Parameters<typeof resolveArguments>
+export type PageParams = Parameters<typeof resolvePageArguments>
+export type AliasParams = Parameters<typeof resolveAliasArguments>
+
+export type DispatchedEvent = Context

package/src/core/auto-track.ts

@@ -0,0 +1,152 @@
+import { Analytics } from './analytics'
+import { EventProperties, Options } from './events'
+import { pTimeout } from './callback'
+
+// Check if a user is opening the link in a new tab
+function userNewTab(event: Event): boolean {
+  const typedEvent = event as Event & {
+    ctrlKey: boolean
+    shiftKey: boolean
+    metaKey: boolean
+    button: number
+  }
+  if (
+    typedEvent.ctrlKey ||
+    typedEvent.shiftKey ||
+    typedEvent.metaKey ||
+    (typedEvent.button && typedEvent.button == 1)
+  ) {
+    return true
+  }
+  return false
+}
+
+// Check if the link opens in new tab
+function linkNewTab(element: HTMLAnchorElement, href: string | null): boolean {
+  if (element.target === '_blank' && href) {
+    return true
+  }
+  return false
+}
+
+export interface JQueryShim<TElement = HTMLElement> {
+  toArray(): TElement[]
+}
+
+export function link(
+  this: Analytics,
+  links: Element | Array<Element> | JQueryShim | null,
+  event: string | Function,
+  properties?: EventProperties | Function,
+  options?: Options
+): Analytics {
+  let elements: Array<Element> = []
+  // always arrays, handles jquery
+  if (!links) {
+    return this
+  }
+  if (links instanceof Element) {
+    elements = [links]
+  } else if ('toArray' in links) {
+    elements = links.toArray()
+  } else {
+    elements = links
+  }
+
+  elements.forEach((el: Element) => {
+    el.addEventListener(
+      'click',
+      (elementEvent: Event) => {
+        const ev = event instanceof Function ? event(el) : event
+        const props =
+          properties instanceof Function ? properties(el) : properties
+        const href =
+          el.getAttribute('href') ||
+          el.getAttributeNS('http://www.w3.org/1999/xlink', 'href') ||
+          el.getAttribute('xlink:href') ||
+          el.getElementsByTagName('a')[0]?.getAttribute('href')
+
+        const trackEvent = pTimeout(
+          this.track(ev, props, options ?? {}),
+          this.settings.timeout ?? 500
+        )
+
+        if (
+          !linkNewTab(el as HTMLAnchorElement, href) &&
+          !userNewTab(elementEvent)
+        ) {
+          if (href) {
+            elementEvent.preventDefault
+              ? elementEvent.preventDefault()
+              : (elementEvent.returnValue = false)
+            trackEvent
+              .catch(console.error)
+              .then(() => {
+                window.location.href = href
+              })
+              .catch(console.error)
+          }
+        }
+      },
+      false
+    )
+  })
+
+  return this
+}
+
+export type LinkArgs = Parameters<typeof link>
+
+export function form(
+  this: Analytics,
+  forms: HTMLFormElement | Array<HTMLFormElement> | null,
+  event: string | Function,
+  properties?: EventProperties | Function,
+  options?: Options
+): Analytics {
+  // always arrays, handles jquery
+  if (!forms) return this
+  if (forms instanceof HTMLFormElement) forms = [forms]
+
+  const elements = forms
+
+  elements.forEach((el) => {
+    if (!(el instanceof Element))
+      throw new TypeError('Must pass HTMLElement to trackForm/trackSubmit.')
+    const handler = (elementEvent: Event): void => {
+      elementEvent.preventDefault
+        ? elementEvent.preventDefault()
+        : (elementEvent.returnValue = false)
+
+      const ev = event instanceof Function ? event(el) : event
+      const props = properties instanceof Function ? properties(el) : properties
+
+      const trackEvent = pTimeout(
+        this.track(ev, props, options ?? {}),
+        this.settings.timeout ?? 500
+      )
+
+      trackEvent
+        .catch(console.error)
+        .then(() => {
+          el.submit()
+        })
+        .catch(console.error)
+    }
+
+    // Support the events happening through jQuery or Zepto instead of through
+    // the normal DOM API, because `el.submit` doesn't bubble up events...
+
+    const $ = (window as any).jQuery || (window as any).Zepto
+    if ($) {
+      $(el).submit(handler)
+    } else {
+      // eslint-disable-next-line @typescript-eslint/no-misused-promises
+      el.addEventListener('submit', handler, false)
+    }
+  })
+
+  return this
+}
+
+export type FormArgs = Parameters<typeof form>

package/src/core/buffer/index.ts

@@ -0,0 +1,289 @@
+import { Analytics } from '../analytics'
+import { Context } from '../context'
+import { isThenable } from '../../lib/is-thenable'
+import { AnalyticsBrowserCore } from '../analytics/interfaces'
+import { version } from '../../generated/version'
+
+/**
+ * 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)
+  })
+}
+
+/**
+ *  Represents a buffered method call that occurred before initialization.
+ */
+export interface PreInitMethodCall<
+  MethodName extends PreInitMethodName = PreInitMethodName
+> {
+  method: MethodName
+  args: PreInitMethodParams<MethodName>
+  called: boolean
+  resolve: (v: ReturnType<Analytics[MethodName]>) => void
+  reject: (reason: any) => void
+}
+
+export type PreInitMethodParams<MethodName extends PreInitMethodName> =
+  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[]>>
+
+/**
+ *  Represents any and all the buffered method calls that occurred before initialization.
+ */
+export class PreInitMethodCallBuffer {
+  private _value = {} as MethodCallMap
+
+  toArray(): PreInitMethodCall[] {
+    return ([] as PreInitMethodCall[]).concat(...Object.values(this._value))
+  }
+
+  getCalls<T extends PreInitMethodName>(methodName: T): PreInitMethodCall<T>[] {
+    return (this._value[methodName] ?? []) as PreInitMethodCall<T>[]
+  }
+
+  push(...calls: PreInitMethodCall[]): PreInitMethodCallBuffer {
+    calls.forEach((call) => {
+      if (this._value[call.method]) {
+        this._value[call.method]!.push(call)
+      } else {
+        this._value[call.method] = [call]
+      }
+    })
+    return this
+  }
+
+  clear(): PreInitMethodCallBuffer {
+    this._value = {} as MethodCallMap
+    return this
+  }
+}
+
+/**
+ *  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 = new PreInitMethodCallBuffer()
+  private _promise: Promise<[Analytics, Context]>
+  constructor(loader: AnalyticsLoader) {
+    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({
+          method: methodName,
+          args,
+          resolve: resolve,
+          reject: reject,
+          called: false,
+        } as PreInitMethodCall)
+      })
+    }
+  }
+
+  /**
+   *  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({
+          method: methodName,
+          args,
+          resolve: () => {},
+          reject: console.error,
+          called: false,
+        } as PreInitMethodCall)
+      }
+
+      return this
+    }
+  }
+}

package/src/core/buffer/snippet.ts

@@ -0,0 +1,43 @@
+import type {
+  PreInitMethodCall,
+  PreInitMethodName,
+  PreInitMethodParams,
+} from '.'
+
+export function transformSnippetCall([
+  methodName,
+  ...args
+]: SnippetWindowBufferedMethodCall): PreInitMethodCall {
+  return {
+    method: methodName,
+    resolve: () => {},
+    reject: console.error,
+    args,
+    called: false,
+  }
+}
+
+const normalizeSnippetBuffer = (buffer: SnippetBuffer): PreInitMethodCall[] => {
+  return buffer.map(transformSnippetCall)
+}
+
+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[]
+
+/**
+ * Fetch the buffered method calls from the window object and normalize them.
+ * This removes existing buffered calls from the window object.
+ */
+export const popSnippetWindowBuffer = (): PreInitMethodCall[] => {
+  const wa = window.analytics
+  if (!Array.isArray(wa)) return []
+  const buffered = wa.splice(0, wa.length)
+  return normalizeSnippetBuffer(buffered)
+}

package/src/core/callback/index.ts

@@ -0,0 +1 @@
+export { invokeCallback, pTimeout } from '@customerio/cdp-analytics-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/context/index.ts

@@ -0,0 +1,21 @@
+import {
+  CoreContext,
+  ContextCancelation,
+  ContextFailedDelivery,
+  SerializedContext,
+  CancelationOptions,
+} from '@customerio/cdp-analytics-core'
+import { CustomerioEvent } from '../events/interfaces'
+import { Stats } from '../stats'
+
+export class Context extends CoreContext<CustomerioEvent> {
+  static override system() {
+    return new this({ type: 'track', event: 'system' })
+  }
+  constructor(event: CustomerioEvent, 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()
+}