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

package/src/plugins/env-enrichment/index.ts

@@ -0,0 +1,208 @@
+import jar from 'js-cookie'
+import type { Context } from '../../core/context'
+import type { Plugin } from '../../core/plugin'
+import { version } from '../../generated/version'
+import { SegmentEvent } from '../../core/events'
+import { Campaign, PluginType } from '@ht-sdks/events-sdk-js-core'
+import { getVersionType } from '../../lib/version-type'
+import { tld } from '../../core/user/tld'
+import { gracefulDecodeURIComponent } from '../../core/query-string/gracefulDecodeURIComponent'
+import { CookieStorage, UniversalStorage } from '../../core/storage'
+import { Analytics } from '../../core/analytics'
+import { clientHints } from '../../lib/client-hints'
+import { UADataValues } from '../../lib/client-hints/interfaces'
+
+let cookieOptions: jar.CookieAttributes | undefined
+function getCookieOptions(): jar.CookieAttributes {
+  if (cookieOptions) {
+    return cookieOptions
+  }
+
+  const domain = tld(window.location.href)
+  cookieOptions = {
+    expires: 31536000000, // 1 year
+    secure: false,
+    path: '/',
+  }
+  if (domain) {
+    cookieOptions.domain = domain
+  }
+
+  return cookieOptions
+}
+
+type Ad = { id: string; type: string }
+
+function ads(query: string): Ad | undefined {
+  const queryIds: Record<string, string> = {
+    btid: 'dataxu',
+    urid: 'millennial-media',
+  }
+
+  if (query.startsWith('?')) {
+    query = query.substring(1)
+  }
+  query = query.replace(/\?/g, '&')
+  const parts = query.split('&')
+
+  for (const part of parts) {
+    const [k, v] = part.split('=')
+    if (queryIds[k]) {
+      return {
+        id: v,
+        type: queryIds[k],
+      }
+    }
+  }
+}
+
+export function utm(query: string): Campaign {
+  if (query.startsWith('?')) {
+    query = query.substring(1)
+  }
+  query = query.replace(/\?/g, '&')
+
+  return query.split('&').reduce((acc, str) => {
+    const [k, v = ''] = str.split('=')
+    if (k.includes('utm_') && k.length > 4) {
+      let utmParam = k.slice(4) as keyof Campaign
+      if (utmParam === 'campaign') {
+        utmParam = 'name'
+      }
+      acc[utmParam] = gracefulDecodeURIComponent(v)
+    }
+    return acc
+  }, {} as Campaign)
+}
+
+export function ampId(): string | undefined {
+  const ampId = jar.get('_ga')
+  if (ampId && ampId.startsWith('amp')) {
+    return ampId
+  }
+}
+
+function referrerId(
+  query: string,
+  ctx: SegmentEvent['context'],
+  disablePersistance: boolean
+): void {
+  const storage = new UniversalStorage<{
+    's:context.referrer': Ad
+  }>(disablePersistance ? [] : [new CookieStorage(getCookieOptions())])
+
+  const stored = storage.get('s:context.referrer')
+
+  const ad = ads(query) ?? stored
+
+  if (!ad) {
+    return
+  }
+
+  if (ctx) {
+    ctx.referrer = { ...ctx.referrer, ...ad }
+  }
+
+  storage.set('s:context.referrer', ad)
+}
+
+/**
+ *
+ * @param obj e.g. { foo: 'b', bar: 'd', baz: ['123', '456']}
+ * @returns e.g. 'foo=b&bar=d&baz=123&baz=456'
+ */
+const objectToQueryString = (
+  obj: Record<string, string | string[]>
+): string => {
+  try {
+    const searchParams = new URLSearchParams()
+    Object.entries(obj).forEach(([k, v]) => {
+      if (Array.isArray(v)) {
+        v.forEach((value) => searchParams.append(k, value))
+      } else {
+        searchParams.append(k, v)
+      }
+    })
+    return searchParams.toString()
+  } catch {
+    return ''
+  }
+}
+
+class EnvironmentEnrichmentPlugin implements Plugin {
+  private instance!: Analytics
+  private userAgentData: UADataValues | undefined
+
+  name = 'Page Enrichment'
+  type: PluginType = 'before'
+  version = '0.1.0'
+  isLoaded = () => true
+  load = async (_ctx: Context, instance: Analytics) => {
+    this.instance = instance
+    try {
+      this.userAgentData = await clientHints(
+        this.instance.options.highEntropyValuesClientHints
+      )
+    } catch (_) {
+      // if client hints API doesn't return anything leave undefined
+    }
+    return Promise.resolve()
+  }
+
+  private enrich = (ctx: Context): Context => {
+    // Note: Types are off - context should never be undefined here, since it is set as part of event creation.
+    const evtCtx = ctx.event.context!
+
+    const search = evtCtx.page!.search || ''
+
+    const query =
+      typeof search === 'object' ? objectToQueryString(search) : search
+
+    evtCtx.userAgent = navigator.userAgent
+    evtCtx.userAgentData = this.userAgentData
+
+    // @ts-ignore
+    const locale = navigator.userLanguage || navigator.language
+
+    if (typeof evtCtx.locale === 'undefined' && typeof locale !== 'undefined') {
+      evtCtx.locale = locale
+    }
+
+    evtCtx.library ??= {
+      name: 'events-sdk-js',
+      version: `${getVersionType() === 'web' ? 'web' : 'npm'}-${version}`,
+    }
+
+    if (query && !evtCtx.campaign) {
+      evtCtx.campaign = utm(query)
+    }
+
+    const amp = ampId()
+    if (amp) {
+      evtCtx.amp = { id: amp }
+    }
+
+    referrerId(
+      query,
+      evtCtx,
+      this.instance.options.disableClientPersistence ?? false
+    )
+
+    try {
+      evtCtx.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+    } catch (_) {
+      // If browser doesn't have support leave timezone undefined
+    }
+
+    return ctx
+  }
+
+  track = this.enrich
+  identify = this.enrich
+  page = this.enrich
+  group = this.enrich
+  alias = this.enrich
+  screen = this.enrich
+}
+
+export const envEnrichment = new EnvironmentEnrichmentPlugin()

package/src/plugins/hightouchio/batched-dispatcher.ts

@@ -0,0 +1,127 @@
+import { SegmentEvent } from '../../core/events'
+import { fetch } from '../../lib/fetch'
+import { onPageChange } from '../../lib/on-page-change'
+
+export type BatchingDispatchConfig = {
+  size?: number
+  timeout?: number
+}
+
+const MAX_PAYLOAD_SIZE = 500
+
+function kilobytes(buffer: unknown): number {
+  const size = encodeURI(JSON.stringify(buffer)).split(/%..|./).length - 1
+  return size / 1024
+}
+
+/**
+ * Checks if the payload is over or close to
+ * the maximum payload size allowed by tracking
+ * API.
+ */
+function approachingTrackingAPILimit(buffer: unknown): boolean {
+  return kilobytes(buffer) >= MAX_PAYLOAD_SIZE - 50
+}
+
+function chunks(batch: object[]): Array<object[]> {
+  const result: object[][] = []
+  let index = 0
+
+  batch.forEach((item) => {
+    const size = kilobytes(result[index])
+    if (size >= 64) {
+      index++
+    }
+
+    if (result[index]) {
+      result[index].push(item)
+    } else {
+      result[index] = [item]
+    }
+  })
+
+  return result
+}
+
+export default function batch(
+  apiHost: string,
+  config?: BatchingDispatchConfig,
+  protocol = 'https'
+) {
+  let buffer: object[] = []
+  let pageUnloaded = false
+
+  const limit = config?.size ?? 10
+  const timeout = config?.timeout ?? 5000
+
+  function sendBatch(batch: object[]) {
+    if (batch.length === 0) {
+      return
+    }
+
+    const writeKey = (batch[0] as SegmentEvent)?.writeKey
+
+    // Remove sentAt from every event as batching only needs a single timestamp
+    const updatedBatch = batch.map((event) => {
+      const { sentAt, ...newEvent } = event as SegmentEvent
+      return newEvent
+    })
+
+    return fetch(`${protocol}://${apiHost}/v1/batch`, {
+      keepalive: pageUnloaded,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      method: 'post',
+      body: JSON.stringify({
+        writeKey,
+        batch: updatedBatch,
+        sentAt: new Date().toISOString(),
+      }),
+    })
+  }
+
+  async function flush(): Promise<unknown> {
+    if (buffer.length) {
+      const batch = buffer
+      buffer = []
+      return sendBatch(batch)
+    }
+  }
+
+  let schedule: NodeJS.Timeout | undefined
+
+  function scheduleFlush(): void {
+    if (schedule) {
+      return
+    }
+
+    schedule = setTimeout(() => {
+      schedule = undefined
+      flush().catch(console.error)
+    }, timeout)
+  }
+
+  onPageChange((unloaded) => {
+    pageUnloaded = unloaded
+
+    if (pageUnloaded && buffer.length) {
+      const reqs = chunks(buffer).map(sendBatch)
+      Promise.all(reqs).catch(console.error)
+    }
+  })
+
+  async function dispatch(_url: string, body: object): Promise<unknown> {
+    buffer.push(body)
+
+    const bufferOverflow =
+      buffer.length >= limit || approachingTrackingAPILimit(buffer)
+
+    return bufferOverflow || pageUnloaded ? flush() : scheduleFlush()
+  }
+
+  return {
+    dispatch,
+  }
+}

package/src/plugins/hightouchio/fetch-dispatcher.ts

@@ -0,0 +1,27 @@
+import { fetch } from '../../lib/fetch'
+
+export type Dispatcher = (url: string, body: object) => Promise<unknown>
+
+export type StandardDispatcherConfig = {
+  keepalive?: boolean
+}
+
+export default function (config?: StandardDispatcherConfig): {
+  dispatch: Dispatcher
+} {
+  function dispatch(url: string, body: object): Promise<unknown> {
+    return fetch(url, {
+      keepalive: config?.keepalive,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      method: 'post',
+      body: JSON.stringify(body),
+    })
+  }
+
+  return {
+    dispatch,
+  }
+}

package/src/plugins/hightouchio/index.ts

@@ -0,0 +1,147 @@
+import { Facade } from '@segment/facade'
+import { Analytics } from '../../core/analytics'
+import { LegacySettings } from '../../browser'
+import { isOffline } from '../../core/connection'
+import { Context } from '../../core/context'
+import { Plugin } from '../../core/plugin'
+import { PriorityQueue } from '../../lib/priority-queue'
+import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
+import { toFacade } from '../../lib/to-facade'
+import batch, { BatchingDispatchConfig } from './batched-dispatcher'
+import standard, { StandardDispatcherConfig } from './fetch-dispatcher'
+import { normalize } from './normalize'
+import { scheduleFlush } from './schedule-flush'
+import { HIGHTOUCH_API_HOST } from '../../core/constants'
+
+type DeliveryStrategy =
+  | {
+      strategy?: 'standard'
+      config?: StandardDispatcherConfig
+    }
+  | {
+      strategy?: 'batching'
+      config?: BatchingDispatchConfig
+    }
+
+export type HightouchioSettings = {
+  apiKey: string
+  apiHost?: string
+  protocol?: 'http' | 'https'
+
+  addBundledMetadata?: boolean
+  unbundledIntegrations?: string[]
+  bundledConfigIds?: string[]
+  unbundledConfigIds?: string[]
+
+  maybeBundledConfigIds?: Record<string, string[]>
+
+  deliveryStrategy?: DeliveryStrategy
+}
+
+type JSON = ReturnType<Facade['json']>
+
+function onAlias(analytics: Analytics, json: JSON): JSON {
+  const user = analytics.user()
+  json.previousId =
+    json.previousId ?? json.from ?? user.id() ?? user.anonymousId()
+  json.userId = json.userId ?? json.to
+  delete json.from
+  delete json.to
+  return json
+}
+
+export function hightouchio(
+  analytics: Analytics,
+  settings?: HightouchioSettings,
+  integrations?: LegacySettings['integrations']
+): Plugin {
+  // Attach `pagehide` before buffer is created so that inflight events are added
+  // to the buffer before the buffer persists events in its own `pagehide` handler.
+  window.addEventListener('pagehide', () => {
+    buffer.push(...Array.from(inflightEvents))
+    inflightEvents.clear()
+  })
+
+  const writeKey = settings?.apiKey ?? ''
+
+  const buffer = analytics.options.disableClientPersistence
+    ? new PriorityQueue<Context>(analytics.queue.queue.maxAttempts, [])
+    : new PersistedPriorityQueue(
+        analytics.queue.queue.maxAttempts,
+        `${writeKey}:dest-Hightouch.io`
+      )
+
+  const inflightEvents = new Set<Context>()
+  const flushing = false
+
+  const apiHost = settings?.apiHost ?? HIGHTOUCH_API_HOST
+  const protocol = settings?.protocol ?? 'https'
+  const remote = `${protocol}://${apiHost}`
+
+  const deliveryStrategy = settings?.deliveryStrategy
+  const client =
+    deliveryStrategy?.strategy === 'batching'
+      ? batch(apiHost, deliveryStrategy.config, protocol)
+      : standard(deliveryStrategy?.config as StandardDispatcherConfig)
+
+  async function send(ctx: Context): Promise<Context> {
+    if (isOffline()) {
+      buffer.push(ctx)
+      // eslint-disable-next-line @typescript-eslint/no-use-before-define
+      scheduleFlush(flushing, buffer, hightouch, scheduleFlush)
+      return ctx
+    }
+
+    inflightEvents.add(ctx)
+
+    const eventType = ctx.event.type
+
+    let json = toFacade(ctx.event).json()
+
+    if (ctx.event.type === 'track') {
+      delete json.traits
+    }
+
+    if (ctx.event.type === 'alias') {
+      json = onAlias(analytics, json)
+    }
+
+    return client
+      .dispatch(
+        `${remote}/v1/${eventType}`,
+        normalize(analytics, json, settings, integrations)
+      )
+      .then(() => ctx)
+      .catch(() => {
+        buffer.pushWithBackoff(ctx)
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        scheduleFlush(flushing, buffer, hightouch, scheduleFlush)
+        return ctx
+      })
+      .finally(() => {
+        inflightEvents.delete(ctx)
+      })
+  }
+
+  const hightouch: Plugin = {
+    name: 'Hightouch.io',
+    type: 'after',
+    version: '0.1.0',
+    isLoaded: (): boolean => true,
+    load: (): Promise<void> => Promise.resolve(),
+    track: send,
+    identify: send,
+    page: send,
+    alias: send,
+    group: send,
+    screen: send,
+  }
+
+  // Buffer may already have items if they were previously stored in localStorage.
+  // Start flushing them immediately.
+  if (buffer.todo) {
+    scheduleFlush(flushing, buffer, hightouch, scheduleFlush)
+  }
+
+  return hightouch
+}

package/src/plugins/hightouchio/normalize.ts

@@ -0,0 +1,71 @@
+import { Analytics } from '../../core/analytics'
+import { LegacySettings } from '../../browser'
+import { SegmentFacade } from '../../lib/to-facade'
+import { HightouchioSettings } from './index'
+
+export function normalize(
+  analytics: Analytics,
+  json: ReturnType<SegmentFacade['json']>,
+  settings?: HightouchioSettings,
+  integrations?: LegacySettings['integrations']
+): object {
+  const user = analytics.user()
+
+  delete json.options
+
+  json.writeKey = settings?.apiKey
+
+  json.userId = json.userId || user.id()
+  json.anonymousId = json.anonymousId || user.anonymousId()
+
+  json.sentAt = new Date()
+
+  const failed = analytics.queue.failedInitializations || []
+  if (failed.length > 0) {
+    json._metadata = { failedInitializations: failed }
+  }
+
+  const bundled: string[] = []
+  const unbundled: string[] = []
+
+  for (const key in integrations) {
+    const integration = integrations[key]
+    if (key === 'Hightouch.io') {
+      bundled.push(key)
+    }
+    if (integration.bundlingStatus === 'bundled') {
+      bundled.push(key)
+    }
+    if (integration.bundlingStatus === 'unbundled') {
+      unbundled.push(key)
+    }
+  }
+
+  // This will make sure that the disabled cloud mode destinations will be
+  // included in the unbundled list.
+  for (const settingsUnbundled of settings?.unbundledIntegrations || []) {
+    if (!unbundled.includes(settingsUnbundled)) {
+      unbundled.push(settingsUnbundled)
+    }
+  }
+
+  const configIds = settings?.maybeBundledConfigIds ?? {}
+  const bundledConfigIds: string[] = []
+
+  bundled.sort().forEach((name) => {
+    ;(configIds[name] ?? []).forEach((id) => {
+      bundledConfigIds.push(id)
+    })
+  })
+
+  if (settings?.addBundledMetadata !== false) {
+    json._metadata = {
+      ...json._metadata,
+      bundled: bundled.sort(),
+      unbundled: unbundled.sort(),
+      bundledIds: bundledConfigIds,
+    }
+  }
+
+  return json
+}

package/src/plugins/hightouchio/schedule-flush.ts

@@ -0,0 +1,58 @@
+import { isOffline } from '../../core/connection'
+import { Context } from '../../core/context'
+import { Plugin } from '../../core/plugin'
+import { attempt } from '@ht-sdks/events-sdk-js-core'
+import { pWhile } from '../../lib/p-while'
+import { PriorityQueue } from '../../lib/priority-queue'
+
+async function flushQueue(
+  xt: Plugin,
+  queue: PriorityQueue<Context>
+): Promise<PriorityQueue<Context>> {
+  const failedQueue: Context[] = []
+  if (isOffline()) {
+    return queue
+  }
+
+  await pWhile(
+    () => queue.length > 0 && !isOffline(),
+    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 function scheduleFlush(
+  flushing: boolean,
+  buffer: PriorityQueue<Context>,
+  xt: Plugin,
+  scheduleFlush: Function
+): void {
+  if (flushing) {
+    return
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-misused-promises
+  setTimeout(async () => {
+    let isFlushing = true
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    const newBuffer = await flushQueue(xt, buffer)
+    isFlushing = false
+
+    if (buffer.todo > 0) {
+      scheduleFlush(isFlushing, newBuffer, xt, scheduleFlush)
+    }
+  }, Math.random() * 5000)
+}

package/src/plugins/legacy-video-plugins/index.ts

@@ -0,0 +1,16 @@
+import { Analytics } from '../../core/analytics'
+
+export async function loadLegacyVideoPlugins(
+  analytics: Analytics
+): Promise<void> {
+  const plugins = await import(
+    // @ts-expect-error
+    '@segment/analytics.js-video-plugins/dist/index.umd.js'
+  )
+
+  // This is super gross, but we need to support the `window.analytics.plugins` namespace
+  // that is linked in the segment docs in order to be backwards compatible with ajs-classic
+
+  // @ts-expect-error
+  analytics._plugins = plugins
+}