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

package/src/lib/global-analytics-helper.ts

@@ -0,0 +1,31 @@
+import { AnalyticsSnippet } from '../browser/standalone-interface'
+
+/**
+ * Stores the global window analytics key
+ */
+let _globalAnalyticsKey = 'htevents'
+
+/**
+ * Gets the global analytics/buffer
+ * @param key name of the window property where the buffer is stored (default: analytics)
+ * @returns AnalyticsSnippet
+ */
+export function getGlobalAnalytics(): AnalyticsSnippet | undefined {
+  return (window as any)[_globalAnalyticsKey]
+}
+
+/**
+ * Replaces the global window key for the analytics/buffer object
+ * @param key key name
+ */
+export function setGlobalAnalyticsKey(key: string) {
+  _globalAnalyticsKey = key
+}
+
+/**
+ * Sets the global analytics object
+ * @param analytics analytics snippet
+ */
+export function setGlobalAnalytics(analytics: AnalyticsSnippet): void {
+  ;(window as any)[_globalAnalyticsKey] = analytics
+}

package/src/lib/group-by.ts

@@ -0,0 +1,30 @@
+type Grouper<T> = (obj: T) => string | number
+
+export function groupBy<T>(
+  collection: T[],
+  grouper: keyof T | Grouper<T>
+): Record<string, T[]> {
+  const results: Record<string, T[]> = {}
+
+  collection.forEach((item) => {
+    let key: string | number | undefined = undefined
+
+    if (typeof grouper === 'string') {
+      const suggestedKey = item[grouper]
+      key =
+        typeof suggestedKey !== 'string'
+          ? JSON.stringify(suggestedKey)
+          : suggestedKey
+    } else if (grouper instanceof Function) {
+      key = grouper(item)
+    }
+
+    if (key === undefined) {
+      return
+    }
+
+    results[key] = [...(results[key] ?? []), item]
+  })
+
+  return results
+}

package/src/lib/is-plan-event-enabled.ts

@@ -0,0 +1,20 @@
+import { PlanEvent, TrackPlan } from '../core/events/interfaces'
+
+/**
+ * Determines whether a track event is allowed to be sent based on the
+ * user's tracking plan.
+ * If the user does not have a tracking plan or the event is allowed based
+ * on the tracking plan configuration, returns true.
+ */
+export function isPlanEventEnabled(
+  plan: TrackPlan | undefined,
+  planEvent: PlanEvent | undefined
+): boolean {
+  // Always prioritize the event's `enabled` status
+  if (typeof planEvent?.enabled === 'boolean') {
+    return planEvent.enabled
+  }
+
+  // Assume absence of a tracking plan means events are enabled
+  return plan?.__default?.enabled ?? true
+}

package/src/lib/is-thenable.ts

@@ -0,0 +1,9 @@
+/**
+ *  Check if  thenable
+ *  (instanceof Promise doesn't respect realms)
+ */
+export const isThenable = (value: unknown): boolean =>
+  typeof value === 'object' &&
+  value !== null &&
+  'then' in value &&
+  typeof (value as any).then === 'function'

package/src/lib/load-script.ts

@@ -0,0 +1,66 @@
+function findScript(src: string): HTMLScriptElement | undefined {
+  const scripts = Array.prototype.slice.call(
+    window.document.querySelectorAll('script')
+  )
+  return scripts.find((s) => s.src === src)
+}
+
+export function loadScript(
+  src: string,
+  attributes?: Record<string, string>
+): Promise<HTMLScriptElement> {
+  const found = findScript(src)
+
+  if (found !== undefined) {
+    const status = found?.getAttribute('status')
+
+    if (status === 'loaded') {
+      return Promise.resolve(found)
+    }
+
+    if (status === 'loading') {
+      return new Promise((resolve, reject) => {
+        found.addEventListener('load', () => resolve(found))
+        found.addEventListener('error', (err) => reject(err))
+      })
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const script = window.document.createElement('script')
+
+    script.type = 'text/javascript'
+    script.src = src
+    script.async = true
+
+    script.setAttribute('status', 'loading')
+    for (const [k, v] of Object.entries(attributes ?? {})) {
+      script.setAttribute(k, v)
+    }
+
+    script.onload = (): void => {
+      script.onerror = script.onload = null
+      script.setAttribute('status', 'loaded')
+      resolve(script)
+    }
+
+    script.onerror = (): void => {
+      script.onerror = script.onload = null
+      script.setAttribute('status', 'error')
+      reject(new Error(`Failed to load ${src}`))
+    }
+
+    const tag = window.document.getElementsByTagName('script')[0]
+    tag.parentElement?.insertBefore(script, tag)
+  })
+}
+
+export function unloadScript(src: string): Promise<void> {
+  const found = findScript(src)
+
+  if (found !== undefined) {
+    found.remove()
+  }
+
+  return Promise.resolve()
+}

package/src/lib/merged-options.ts

@@ -0,0 +1,46 @@
+import { JSONObject, Options } from '../core/events/interfaces'
+import { LegacySettings } from '../browser'
+
+/**
+ * Merge legacy settings and initialized Integration option overrides.
+ *
+ * This will merge any options that were passed from initialization into
+ * overrides for settings that are returned by the Segment CDN.
+ *
+ * i.e. this allows for passing options directly into destinations from
+ * the Analytics constructor.
+ */
+export function mergedOptions(
+  settings: LegacySettings,
+  options: Options
+): Record<string, JSONObject> {
+  const optionOverrides = Object.entries(options.integrations ?? {}).reduce(
+    (overrides, [integration, options]) => {
+      if (typeof options === 'object') {
+        return {
+          ...overrides,
+          [integration]: options,
+        }
+      }
+
+      return {
+        ...overrides,
+        [integration]: {},
+      }
+    },
+    {} as Record<string, JSONObject>
+  )
+
+  return Object.entries(settings.integrations).reduce(
+    (integrationSettings, [integration, settings]) => {
+      return {
+        ...integrationSettings,
+        [integration]: {
+          ...settings,
+          ...optionOverrides[integration],
+        },
+      }
+    },
+    {} as Record<string, JSONObject>
+  )
+}

package/src/lib/on-page-change.ts

@@ -0,0 +1,29 @@
+/**
+ * Register event listener on document that fires when:
+ * * tab change or tab close (in mobile or desktop)
+ * * click back / forward button
+ * * click any link or perform any other navigation action
+ * * soft refresh / hard refresh
+ *
+ * adapted from https://stackoverflow.com/questions/3239834/window-onbeforeunload-not-working-on-the-ipad/52864508#52864508,
+ */
+export const onPageChange = (cb: (unloaded: boolean) => void) => {
+  let unloaded = false // prevents double firing if both are supported
+
+  window.addEventListener('pagehide', () => {
+    if (unloaded) return
+    unloaded = true
+    cb(unloaded)
+  })
+
+  // using document instead of window because of bug affecting browsers before safari 14 (detail in footnotes https://caniuse.com/?search=visibilitychange)
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState == 'hidden') {
+      if (unloaded) return
+      unloaded = true
+    } else {
+      unloaded = false
+    }
+    cb(unloaded)
+  })
+}

package/src/lib/p-while.ts

@@ -0,0 +1,12 @@
+export const pWhile = async <T>(
+  condition: (value: T | undefined) => boolean,
+  action: () => T | PromiseLike<T>
+): Promise<void> => {
+  const loop = async (actionResult: T | undefined): Promise<void> => {
+    if (condition(actionResult)) {
+      return loop(await action())
+    }
+  }
+
+  return loop(undefined)
+}

package/src/lib/parse-cdn.ts

@@ -0,0 +1,56 @@
+import { getGlobalAnalytics } from './global-analytics-helper'
+
+const analyticsScriptRegex =
+  /(https:\/\/.*)\/analytics\.js\/v1\/(?:.*?)\/(?:platform|analytics.*)?/
+const getCDNUrlFromScriptTag = (): string | undefined => {
+  let cdn: string | undefined
+  const scripts = Array.prototype.slice.call(
+    document.querySelectorAll('script')
+  )
+  scripts.forEach((s) => {
+    const src = s.getAttribute('src') ?? ''
+    const result = analyticsScriptRegex.exec(src)
+
+    if (result && result[1]) {
+      cdn = result[1]
+    }
+  })
+  return cdn
+}
+
+let _globalCDN: string | undefined // set globalCDN as in-memory singleton
+const getGlobalCDNUrl = (): string | undefined => {
+  const result = _globalCDN ?? getGlobalAnalytics()?._cdn
+  return result
+}
+
+export const setGlobalCDNUrl = (cdn: string) => {
+  const globalAnalytics = getGlobalAnalytics()
+  if (globalAnalytics) {
+    globalAnalytics._cdn = cdn
+  }
+  _globalCDN = cdn
+}
+
+export const getCDN = (): string => {
+  const globalCdnUrl = getGlobalCDNUrl()
+
+  if (globalCdnUrl) return globalCdnUrl
+
+  const cdnFromScriptTag = getCDNUrlFromScriptTag()
+
+  if (cdnFromScriptTag) {
+    return cdnFromScriptTag
+  } else {
+    // it's possible that the CDN is not found in the page because:
+    // - the script is loaded through a proxy
+    // - the script is removed after execution
+    // in this case, we fall back to the default Segment CDN
+    return `https://cdn.hightouch-events.com`
+  }
+}
+
+export const getNextIntegrationsURL = () => {
+  const cdn = getCDN()
+  return `${cdn}/next-integrations`
+}

package/src/lib/pick.ts

@@ -0,0 +1,28 @@
+export function pick<T extends Record<string, any>, K extends keyof T>(
+  object: T,
+  keys: readonly K[]
+): Pick<T, K>
+
+export function pick<T extends Record<string, any>>(
+  object: T,
+  keys: string[]
+): Partial<T>
+
+/**
+ * @example
+ * pick({ 'a': 1, 'b': '2', 'c': 3 }, ['a', 'c'])
+ * => { 'a': 1, 'c': 3 }
+ */
+export function pick<T extends Record<string, any>, K extends keyof T>(
+  object: T,
+  keys: string[] | K[] | readonly K[]
+) {
+  return Object.assign(
+    {},
+    ...keys.map((key) => {
+      if (object && Object.prototype.hasOwnProperty.call(object, key)) {
+        return { [key]: object[key] }
+      }
+    })
+  )
+}

package/src/lib/priority-queue/backoff.ts

@@ -0,0 +1,24 @@
+type BackoffParams = {
+  /** The number of milliseconds before starting the first retry. Default is 500 */
+  minTimeout?: number
+
+  /** The maximum number of milliseconds between two retries. Default is Infinity */
+  maxTimeout?: number
+
+  /** The exponential factor to use. Default is 2. */
+  factor?: number
+
+  /** The current attempt */
+  attempt: number
+}
+
+export function backoff(params: BackoffParams): number {
+  const random = Math.random() + 1
+  const {
+    minTimeout = 500,
+    factor = 2,
+    attempt,
+    maxTimeout = Infinity,
+  } = params
+  return Math.min(random * minTimeout * Math.pow(factor, attempt), maxTimeout)
+}

package/src/lib/priority-queue/index.ts

@@ -0,0 +1,6 @@
+import {
+  PriorityQueue,
+  ON_REMOVE_FROM_FUTURE,
+} from '@ht-sdks/events-sdk-js-core'
+
+export { PriorityQueue, ON_REMOVE_FROM_FUTURE }

package/src/lib/priority-queue/persisted.ts

@@ -0,0 +1,127 @@
+import { PriorityQueue } from '.'
+import { Context, SerializedContext } from '../../core/context'
+import { isBrowser } from '../../core/environment'
+
+let loc:
+  | Storage
+  | { getItem: () => void; setItem: () => void; removeItem: () => void } = {
+  getItem() {},
+  setItem() {},
+  removeItem() {},
+}
+
+try {
+  loc = isBrowser() && window.localStorage ? window.localStorage : loc
+} catch (err) {
+  console.warn('Unable to access localStorage', err)
+}
+
+function persisted(key: string): Context[] {
+  const items = loc.getItem(key)
+  return (items ? JSON.parse(items) : []).map(
+    (p: SerializedContext) => new Context(p.event, p.id)
+  )
+}
+
+function persistItems(key: string, items: Context[]): void {
+  const existing = persisted(key)
+  const all = [...items, ...existing]
+
+  const merged = all.reduce((acc, item) => {
+    return {
+      ...acc,
+      [item.id]: item,
+    }
+  }, {} as Record<string, Context>)
+
+  loc.setItem(key, JSON.stringify(Object.values(merged)))
+}
+
+function seen(key: string): Record<string, number> {
+  const stored = loc.getItem(key)
+  return stored ? JSON.parse(stored) : {}
+}
+
+function persistSeen(key: string, memory: Record<string, number>): void {
+  const stored = seen(key)
+
+  loc.setItem(
+    key,
+    JSON.stringify({
+      ...stored,
+      ...memory,
+    })
+  )
+}
+
+function remove(key: string): void {
+  loc.removeItem(key)
+}
+
+const now = (): number => new Date().getTime()
+
+function mutex(key: string, onUnlock: Function, attempt = 0): void {
+  const lockTimeout = 50
+  const lockKey = `persisted-queue:v1:${key}:lock`
+
+  const expired = (lock: number): boolean => new Date().getTime() > lock
+  const rawLock = loc.getItem(lockKey)
+  const lock = rawLock ? (JSON.parse(rawLock) as number) : null
+
+  const allowed = lock === null || expired(lock)
+  if (allowed) {
+    loc.setItem(lockKey, JSON.stringify(now() + lockTimeout))
+    onUnlock()
+    loc.removeItem(lockKey)
+    return
+  }
+
+  if (!allowed && attempt < 3) {
+    setTimeout(() => {
+      mutex(key, onUnlock, attempt + 1)
+    }, lockTimeout)
+  } else {
+    console.error('Unable to retrieve lock')
+  }
+}
+
+export class PersistedPriorityQueue extends PriorityQueue<Context> {
+  constructor(maxAttempts: number, key: string) {
+    super(maxAttempts, [])
+
+    const itemsKey = `persisted-queue:v1:${key}:items`
+    const seenKey = `persisted-queue:v1:${key}:seen`
+
+    let saved: Context[] = []
+    let lastSeen: Record<string, number> = {}
+
+    mutex(key, () => {
+      try {
+        saved = persisted(itemsKey)
+        lastSeen = seen(seenKey)
+        remove(itemsKey)
+        remove(seenKey)
+
+        this.queue = [...saved, ...this.queue]
+        this.seen = { ...lastSeen, ...this.seen }
+      } catch (err) {
+        console.error(err)
+      }
+    })
+
+    window.addEventListener('pagehide', () => {
+      // we deliberately want to use the less powerful 'pagehide' API to only persist on events where the analytics instance gets destroyed, and not on tab away.
+      if (this.todo > 0) {
+        const items = [...this.queue, ...this.future]
+        try {
+          mutex(key, () => {
+            persistItems(itemsKey, items)
+            persistSeen(seenKey, this.seen)
+          })
+        } catch (err) {
+          console.error(err)
+        }
+      }
+    })
+  }
+}

package/src/lib/sleep.ts

@@ -0,0 +1,4 @@
+export const sleep = (time: number): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, time)
+  })

package/src/lib/to-facade.ts

@@ -0,0 +1,50 @@
+import {
+  Alias,
+  Facade,
+  Group,
+  Identify,
+  Options,
+  Page,
+  Screen,
+  Track,
+} from '@segment/facade'
+import { SegmentEvent } from '../core/events'
+
+export type SegmentFacade = Facade<SegmentEvent> & {
+  obj: SegmentEvent
+}
+
+export function toFacade(evt: SegmentEvent, options?: Options): SegmentFacade {
+  let fcd = new Facade(evt, options)
+
+  if (evt.type === 'track') {
+    fcd = new Track(evt, options)
+  }
+
+  if (evt.type === 'identify') {
+    fcd = new Identify(evt, options)
+  }
+
+  if (evt.type === 'page') {
+    fcd = new Page(evt, options)
+  }
+
+  if (evt.type === 'alias') {
+    fcd = new Alias(evt, options)
+  }
+
+  if (evt.type === 'group') {
+    fcd = new Group(evt, options)
+  }
+
+  if (evt.type === 'screen') {
+    fcd = new Screen(evt, options)
+  }
+
+  Object.defineProperty(fcd, 'obj', {
+    value: evt,
+    writable: true,
+  })
+
+  return fcd as SegmentFacade
+}

package/src/lib/version-type.ts

@@ -0,0 +1,10 @@
+// Default value will be updated to 'web' in `bundle-umd.ts` for web build.
+let _version: 'web' | 'npm' = 'npm'
+
+export function setVersionType(version: typeof _version) {
+  _version = version
+}
+
+export function getVersionType(): typeof _version {
+  return _version
+}

package/src/node/index.ts

@@ -0,0 +1,36 @@
+import { Analytics } from '../core/analytics'
+import { Context } from '../core/context'
+import { validation } from '../plugins/validation'
+import { analyticsNode } from '../plugins/analytics-node'
+import { Plugin } from '../core/plugin'
+import { EventQueue } from '../core/queue/event-queue'
+import { PriorityQueue } from '../lib/priority-queue'
+
+export class AnalyticsNode {
+  static async load(settings: {
+    writeKey: string
+  }): Promise<[Analytics, Context]> {
+    const cookieOptions = {
+      persist: false,
+    }
+
+    const queue = new EventQueue(new PriorityQueue(3, []))
+    const options = { user: cookieOptions, group: cookieOptions }
+    const analytics = new Analytics(settings, options, queue)
+
+    const nodeSettings = {
+      writeKey: settings.writeKey,
+      name: 'analytics-node-next',
+      type: 'after' as Plugin['type'],
+      version: 'latest',
+    }
+
+    const ctx = await analytics.register(
+      validation,
+      analyticsNode(nodeSettings)
+    )
+    analytics.emit('initialize', settings, cookieOptions ?? {})
+
+    return [analytics, ctx]
+  }
+}

package/src/node/node.browser.ts

@@ -0,0 +1,7 @@
+export class AnalyticsNode {
+  static load(): Promise<never> {
+    return Promise.reject(
+      new Error('AnalyticsNode is not available in browsers.')
+    )
+  }
+}