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

package/src/core/analytics/interfaces.ts

@@ -0,0 +1,100 @@
+import type { Analytics, AnalyticsSettings, InitOptions } from '.'
+import type { Plugin } from '../plugin'
+import type {
+  EventParams,
+  DispatchedEvent,
+  PageParams,
+  IdentifyParams,
+  AliasParams,
+  GroupParams,
+} from '../arguments-resolver'
+import type { Context } from '../context'
+import type { SegmentEvent } from '../events'
+import type { Group, User } from '../user'
+import type { LegacyIntegration } from '../../plugins/ajs-destination/types'
+import { CoreAnalytics } from '@ht-sdks/events-sdk-js-core'
+
+// we can define a contract because:
+// - it gives us a neat place to put all our typedocs (they end up being inherited by the class that implements them).
+// - it makes it easy to reason about what's being shared between browser and node
+
+/**
+ * All of these methods are a no-op.
+ */
+/** @deprecated */
+interface AnalyticsClassicStubs {
+  /** @deprecated */
+  log(this: never): void
+  /** @deprecated */
+  addIntegrationMiddleware(this: never): void
+  /** @deprecated */
+  listeners(this: never): void
+  /** @deprecated */
+  addEventListener(this: never): void
+  /** @deprecated */
+  removeAllListeners(this: never): void
+  /** @deprecated */
+  removeListener(this: never): void
+  /** @deprecated */
+  removeEventListener(this: never): void
+  /** @deprecated */
+  hasListeners(this: never): void
+  /** @deprecated */
+  // This function is only used to add GA and Appcue, but these are already being added to Integrations by AJSN
+  addIntegration(this: never): void
+  /** @deprecated */
+  add(this: never): void
+}
+
+/** @deprecated */
+export interface AnalyticsClassic extends AnalyticsClassicStubs {
+  /** @deprecated */
+  initialize(
+    settings?: AnalyticsSettings,
+    options?: InitOptions
+  ): Promise<Analytics>
+
+  /** @deprecated */
+  noConflict(): Analytics
+
+  /** @deprecated */
+  normalize(msg: SegmentEvent): SegmentEvent
+
+  /** @deprecated */
+  readonly failedInitializations: string[]
+
+  /** @deprecated */
+  pageview(url: string): Promise<Analytics>
+
+  /**  @deprecated*/
+  readonly plugins: any
+
+  /** @deprecated */
+  readonly Integrations: Record<string, LegacyIntegration>
+}
+
+/**
+ * Interface implemented by concrete Analytics class (commonly accessible if you use "await" on AnalyticsBrowser.load())
+ */
+export interface AnalyticsCore extends CoreAnalytics {
+  track(...args: EventParams): Promise<DispatchedEvent>
+  page(...args: PageParams): Promise<DispatchedEvent>
+  identify(...args: IdentifyParams): Promise<DispatchedEvent>
+  group(): Group
+  group(...args: GroupParams): Promise<DispatchedEvent>
+  alias(...args: AliasParams): Promise<DispatchedEvent>
+  screen(...args: PageParams): Promise<DispatchedEvent>
+  register(...plugins: Plugin[]): Promise<Context>
+  deregister(...plugins: string[]): Promise<Context>
+  user(): User
+  readonly VERSION: string
+}
+
+/**
+ * Interface implemented by AnalyticsBrowser (buffered version of analytics) (commonly accessible through AnalyticsBrowser.load())
+ */
+export type AnalyticsBrowserCore = Omit<AnalyticsCore, 'group' | 'user'> & {
+  group(): Promise<Group>
+  group(...args: GroupParams): Promise<DispatchedEvent>
+  user(): Promise<User>
+}

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

@@ -0,0 +1,200 @@
+import {
+  isFunction,
+  isPlainObject,
+  isString,
+  isNumber,
+} from '@ht-sdks/events-sdk-js-core'
+import { Context } from '../context'
+import {
+  Callback,
+  JSONObject,
+  Options,
+  EventProperties,
+  SegmentEvent,
+  Traits,
+  GroupTraits,
+  UserTraits,
+} from '../events'
+import { ID, User } from '../user'
+
+/**
+ * Helper for the track method
+ */
+export function resolveArguments(
+  eventName: string | SegmentEvent,
+  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>> => {
+    const values: {
+      id?: ID
+      traits?: T | null
+      options?: Options
+      callback?: Callback
+    } = {}
+    // It's a stack so it's reversed so that we go through each of the expected arguments
+    const orderStack: Array<keyof typeof values> = [
+      'callback',
+      'options',
+      'traits',
+      'id',
+    ]
+
+    // Read each argument and eval the possible values here
+    for (const arg of args) {
+      let current = orderStack.pop()
+      if (current === 'id') {
+        if (isString(arg) || isNumber(arg)) {
+          values.id = arg.toString()
+          continue
+        }
+        if (arg === null || arg === undefined) {
+          continue
+        }
+        // First argument should always be the id, if it is not a valid value we can skip it
+        current = orderStack.pop()
+      }
+
+      // Traits and Options
+      if (
+        (current === 'traits' || current === 'options') &&
+        (arg === null || arg === undefined || isPlainObject(arg))
+      ) {
+        values[current] = arg as T
+      }
+
+      // Callback
+      if (isFunction(arg)) {
+        values.callback = arg as Callback
+        break // This is always the last argument
+      }
+    }
+
+    return [
+      values.id ?? user.id(),
+      (values.traits ?? {}) as T,
+      values.options ?? {},
+      values.callback,
+    ]
+  }
+}
+
+/**
+ * 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>