utneque 1.0.0

package/packages/browser/src/browser/__tests__/update-cdn-settings.test.ts

@@ -0,0 +1,71 @@
+import { HtEventsBrowser } from '../..'
+import { setGlobalCDNUrl } from '../../lib/parse-cdn'
+import { remoteLoader } from '../../plugins/remote-loader'
+import unfetch from 'unfetch'
+import { createSuccess } from '../../test-helpers/factories'
+jest.mock('unfetch')
+
+const INTG_TO_DELETE = 'deleteMe'
+
+const cdnSettings = {
+  integrations: {
+    [INTG_TO_DELETE]: { bar: true },
+    otherIntegration: { foo: true },
+  },
+}
+const mockFetchSettingsSuccessResponse = (cdnSettings: any) => {
+  return jest
+    .mocked(unfetch)
+    .mockImplementation(() => createSuccess(cdnSettings))
+}
+
+jest.mock('../../plugins/remote-loader')
+const remoteLoaderSpy = jest.fn().mockResolvedValue([])
+jest.mocked(remoteLoader).mockImplementation(remoteLoaderSpy)
+
+describe('updateCDNSettings configuration option', () => {
+  beforeEach(() => {
+    setGlobalCDNUrl(undefined as any)
+    ;(window as any).htevents = undefined
+  })
+  it('should update the configuration options if they are passed directly', async () => {
+    await HtEventsBrowser.load(
+      {
+        writeKey: 'foo',
+        cdnSettings,
+      },
+      {
+        updateCDNSettings: (settings) => {
+          delete settings.integrations.deleteMe
+          return settings
+        },
+      }
+    )
+    const [arg1] = remoteLoaderSpy.mock.lastCall
+    expect(arg1.integrations.otherIntegration).toEqual(
+      cdnSettings.integrations.otherIntegration
+    )
+    expect(arg1.integrations[INTG_TO_DELETE]).toBeUndefined()
+  })
+
+  // By default, we no longer fetch settings from the CDN
+  it.skip('should update the configuration options if they are fetched', async () => {
+    mockFetchSettingsSuccessResponse(cdnSettings)
+    await HtEventsBrowser.load(
+      {
+        writeKey: 'foo',
+      },
+      {
+        updateCDNSettings: (settings) => {
+          delete settings.integrations.deleteMe
+          return settings
+        },
+      }
+    )
+    const [arg1] = remoteLoaderSpy.mock.lastCall
+    expect(arg1.integrations.otherIntegration).toEqual(
+      cdnSettings.integrations.otherIntegration
+    )
+    expect(arg1.integrations[INTG_TO_DELETE]).toBeUndefined()
+  })
+})

package/packages/browser/src/browser/browser-umd.ts

@@ -0,0 +1,19 @@
+import { getCDN, setGlobalCDNUrl } from '../lib/parse-cdn'
+import { setVersionType } from '../lib/version-type'
+
+if (process.env.ASSET_PATH) {
+  if (process.env.ASSET_PATH === '/dist/umd/') {
+    // @ts-ignore
+    __webpack_public_path__ = '/dist/umd/'
+  } else {
+    const cdn = getCDN()
+    setGlobalCDNUrl(cdn) // preserving original behavior -- TODO: neccessary?
+    // @ts-ignore
+    __webpack_public_path__ =
+      cdn + `/${process.env.PATH_PREFIX}/${process.env.PATH_VERSION}/`
+  }
+}
+
+setVersionType('web')
+
+export * from '.'

package/packages/browser/src/browser/index.ts

@@ -0,0 +1,486 @@
+import { getProcessEnv } from '../lib/get-process-env'
+import { getCDN, setGlobalCDNUrl } from '../lib/parse-cdn'
+
+import { fetch } from '../lib/fetch'
+import { Analytics, AnalyticsSettings, InitOptions } from '../core/analytics'
+import { Context } from '../core/context'
+import { Plan } from '../core/events'
+import { Plugin } from '../core/plugin'
+import { MetricsOptions } from '../core/stats/remote-metrics'
+import { mergedOptions } from '../lib/merged-options'
+import { createDeferred } from '../lib/create-deferred'
+import { envEnrichment } from '../plugins/env-enrichment'
+import {
+  PluginFactory,
+  remoteLoader,
+  RemotePlugin,
+} from '../plugins/remote-loader'
+import type { RoutingRule } from '../plugins/routing-middleware'
+import { hightouchio, HightouchioSettings } from '../plugins/hightouchio'
+import { validation } from '../plugins/validation'
+import {
+  AnalyticsBuffered,
+  PreInitMethodCallBuffer,
+  flushAnalyticsCallsInNewTask,
+  flushAddSourceMiddleware,
+  flushSetAnonymousID,
+  flushOn,
+} from '../core/buffer'
+import { ClassicIntegrationSource } from '../plugins/ajs-destination/types'
+import { attachInspector } from '../core/inspector'
+import { setGlobalAnalyticsKey } from '../lib/global-analytics-helper'
+
+export interface LegacyIntegrationConfiguration {
+  /* @deprecated - This does not indicate browser types anymore */
+  type?: string
+
+  versionSettings?: {
+    version?: string
+    override?: string
+    componentTypes?: Array<'browser' | 'android' | 'ios' | 'server'>
+  }
+
+  bundlingStatus?: string
+
+  /**
+   * Consent settings for the integration
+   */
+  consentSettings?: {
+    /**
+     * Consent categories for the integration
+     * @example ["Analytics", "Advertising", "CAT001"]
+     */
+    categories: string[]
+  }
+
+  // Hightouch.io specific
+  retryQueue?: boolean
+
+  // any extra unknown settings
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any
+}
+
+export interface LegacySettings {
+  integrations: {
+    [name: string]: LegacyIntegrationConfiguration
+  }
+
+  middlewareSettings?: {
+    routingRules: RoutingRule[]
+  }
+
+  enabledMiddleware?: Record<string, boolean>
+  metrics?: MetricsOptions
+
+  plan?: Plan
+
+  legacyVideoPluginsEnabled?: boolean
+
+  remotePlugins?: RemotePlugin[]
+
+  /**
+   * Top level consent settings
+   */
+  consentSettings?: {
+    /**
+     * All unique consent categories.
+     * There can be categories in this array that are important for consent that are not included in any integration  (e.g. 2 cloud mode categories).
+     * @example ["Analytics", "Advertising", "CAT001"]
+     */
+    allCategories: string[]
+  }
+}
+
+export interface HtEventsBrowserSettings extends AnalyticsSettings {
+  /**
+   * The settings for the Hightouch Source.
+   * If provided, `HtEventsBrowser` will not fetch remote settings
+   * for the source.
+   */
+  cdnSettings?: LegacySettings & Record<string, unknown>
+  /**
+   * If provided, will override the default Hightouch CDN (https://cdn.hightouch-events.com) for this application.
+   */
+  cdnURL?: string
+}
+
+export function loadLegacySettings(
+  writeKey: string,
+  cdnURL?: string
+): Promise<LegacySettings> {
+  const baseUrl = cdnURL ?? getCDN()
+
+  return fetch(`${baseUrl}/v1/projects/${writeKey}/settings`)
+    .then((res) => {
+      if (!res.ok) {
+        return res.text().then((errorResponseMessage) => {
+          throw new Error(errorResponseMessage)
+        })
+      }
+      return res.json()
+    })
+    .catch((err) => {
+      console.error(err.message)
+      throw err
+    })
+}
+
+function hasLegacyDestinations(settings: LegacySettings): boolean {
+  return (
+    getProcessEnv().NODE_ENV !== 'test' &&
+    // just one integration means hightouchio
+    Object.keys(settings.integrations).length > 1
+  )
+}
+
+function hasTsubMiddleware(settings: LegacySettings): boolean {
+  return (
+    getProcessEnv().NODE_ENV !== 'test' &&
+    (settings.middlewareSettings?.routingRules?.length ?? 0) > 0
+  )
+}
+
+/**
+ * With AJS classic, we allow users to call setAnonymousId before the library initialization.
+ * This is important because some of the destinations will use the anonymousId during the initialization,
+ * and if we set anonId afterwards, that wouldn’t impact the destination.
+ *
+ * Also Ensures events can be registered before library initialization.
+ * This is important so users can register to 'initialize' and any events that may fire early during setup.
+ */
+function flushPreBuffer(
+  analytics: Analytics,
+  buffer: PreInitMethodCallBuffer
+): void {
+  flushSetAnonymousID(analytics, buffer)
+  flushOn(analytics, buffer)
+}
+
+/**
+ * Finish flushing buffer and cleanup.
+ */
+async function flushFinalBuffer(
+  analytics: Analytics,
+  buffer: PreInitMethodCallBuffer
+): Promise<void> {
+  // Call popSnippetWindowBuffer before each flush task since there may be
+  // analytics calls during async function calls.
+  await flushAddSourceMiddleware(analytics, buffer)
+  flushAnalyticsCallsInNewTask(analytics, buffer)
+  // Clear buffer, just in case analytics is loaded twice; we don't want to fire events off again.
+  buffer.clear()
+}
+
+async function registerPlugins(
+  writeKey: string,
+  legacySettings: LegacySettings,
+  analytics: Analytics,
+  opts: InitOptions,
+  options: InitOptions,
+  pluginLikes: (Plugin | PluginFactory)[] = [],
+  legacyIntegrationSources: ClassicIntegrationSource[]
+): Promise<Context> {
+  const plugins = pluginLikes?.filter(
+    (pluginLike) => typeof pluginLike === 'object'
+  ) as Plugin[]
+
+  const pluginSources = pluginLikes?.filter(
+    (pluginLike) =>
+      typeof pluginLike === 'function' &&
+      typeof pluginLike.pluginName === 'string'
+  ) as PluginFactory[]
+
+  const tsubMiddleware = hasTsubMiddleware(legacySettings)
+    ? await import(
+        /* webpackChunkName: "tsub-middleware" */ '../plugins/routing-middleware'
+      ).then((mod) => {
+        return mod.tsubMiddleware(
+          legacySettings.middlewareSettings!.routingRules
+        )
+      })
+    : undefined
+
+  const legacyDestinations =
+    hasLegacyDestinations(legacySettings) || legacyIntegrationSources.length > 0
+      ? await import(
+          /* webpackChunkName: "ajs-destination" */ '../plugins/ajs-destination'
+        ).then((mod) => {
+          return mod.ajsDestinations(
+            writeKey,
+            legacySettings,
+            analytics.integrations,
+            opts,
+            tsubMiddleware,
+            legacyIntegrationSources
+          )
+        })
+      : []
+
+  if (legacySettings.legacyVideoPluginsEnabled) {
+    await import(
+      /* webpackChunkName: "legacyVideos" */ '../plugins/legacy-video-plugins'
+    ).then((mod) => {
+      return mod.loadLegacyVideoPlugins(analytics)
+    })
+  }
+
+  const schemaFilter = opts.plan?.track
+    ? await import(
+        /* webpackChunkName: "schemaFilter" */ '../plugins/schema-filter'
+      ).then((mod) => {
+        return mod.schemaFilter(opts.plan?.track, legacySettings)
+      })
+    : undefined
+
+  const mergedSettings = mergedOptions(legacySettings, options)
+  const remotePlugins = await remoteLoader(
+    legacySettings,
+    analytics.integrations,
+    mergedSettings,
+    options.obfuscate,
+    tsubMiddleware,
+    pluginSources
+  ).catch(() => [])
+
+  const toRegister = [
+    validation,
+    envEnrichment,
+    ...plugins,
+    ...legacyDestinations,
+    ...remotePlugins,
+  ]
+
+  if (schemaFilter) {
+    toRegister.push(schemaFilter)
+  }
+
+  const shouldIgnoreHightouchio =
+    (opts.integrations?.All === false && !opts.integrations['Hightouch.io']) ||
+    (opts.integrations && opts.integrations['Hightouch.io'] === false)
+
+  if (!shouldIgnoreHightouchio) {
+    toRegister.push(
+      await hightouchio(
+        analytics,
+        mergedSettings['Hightouch.io'] as HightouchioSettings,
+        legacySettings.integrations
+      )
+    )
+  }
+
+  const ctx = await analytics.register(...toRegister)
+
+  if (
+    Object.entries(legacySettings.enabledMiddleware ?? {}).some(
+      ([, enabled]) => enabled
+    )
+  ) {
+    await import(
+      /* webpackChunkName: "remoteMiddleware" */ '../plugins/remote-middleware'
+    ).then(async ({ remoteMiddlewares }) => {
+      const middleware = await remoteMiddlewares(
+        ctx,
+        legacySettings,
+        options.obfuscate
+      )
+      const promises = middleware.map((mdw) =>
+        analytics.addSourceMiddleware(mdw)
+      )
+      return Promise.all(promises)
+    })
+  }
+
+  return ctx
+}
+
+const defaultHightouchIntegration: HightouchioSettings = {
+  apiKey: 'WRITE_KEY',
+  apiHost: 'us-east-1.hightouch-events.com',
+  protocol: 'https',
+  unbundledIntegrations: [],
+  addBundledMetadata: false,
+  maybeBundledConfigIds: {},
+  deliveryStrategy: {
+    strategy: 'batching',
+    config: { timeout: 1000, size: 10 }, // 1 second or 10 items
+  },
+}
+
+const defaultSettings: LegacySettings = {
+  integrations: {},
+  plan: {
+    track: { __default: { enabled: true, integrations: {} } },
+    identify: { __default: { enabled: true } },
+    group: { __default: { enabled: true } },
+  },
+  enabledMiddleware: {},
+  metrics: { sampleRate: 0.0 },
+  legacyVideoPluginsEnabled: false,
+  remotePlugins: [],
+}
+
+async function loadAnalytics(
+  settings: HtEventsBrowserSettings,
+  options: InitOptions = {},
+  preInitBuffer: PreInitMethodCallBuffer
+): Promise<[Analytics, Context]> {
+  if (options.globalAnalyticsKey)
+    setGlobalAnalyticsKey(options.globalAnalyticsKey)
+  // this is an ugly side-effect, but it's for the benefits of the plugins that get their cdn via getCDN()
+  if (settings.cdnURL) setGlobalCDNUrl(settings.cdnURL)
+
+  let legacySettings
+  if (settings.cdnSettings) {
+    legacySettings = settings.cdnSettings
+  } else {
+    defaultSettings.integrations['Hightouch.io'] = {
+      ...defaultHightouchIntegration,
+      ...(settings.writeKey ? { apiKey: settings.writeKey } : {}),
+      ...(options.apiHost ? { apiHost: options.apiHost } : {}),
+      ...(options.protocol ? { protocol: options.protocol } : {}),
+      // defaultHightouchIntegration defaults to 'batching'
+      // allow the options override to turn it off
+      ...(options.batching == false
+        ? {
+            deliveryStrategy: {
+              strategy: 'standard',
+            },
+          }
+        : {}),
+    }
+    legacySettings = defaultSettings
+  }
+
+  if (options.updateCDNSettings) {
+    legacySettings = options.updateCDNSettings(legacySettings)
+  }
+
+  const retryQueue: boolean =
+    legacySettings.integrations['Hightouch.io']?.retryQueue ?? true
+
+  const opts: InitOptions = { retryQueue, ...options }
+  const analytics = new Analytics(settings, opts)
+
+  attachInspector(analytics)
+
+  const plugins = settings.plugins ?? []
+
+  const classicIntegrations = settings.classicIntegrations ?? []
+
+  // Uncomment to re-enable RemoteMetrics -- also see standalone.ts RemoteMetrics usage
+  // Stats.initRemoteMetrics(legacySettings.metrics)
+
+  // needs to be flushed before plugins are registered
+  flushPreBuffer(analytics, preInitBuffer)
+
+  const ctx = await registerPlugins(
+    settings.writeKey,
+    legacySettings,
+    analytics,
+    opts,
+    options,
+    plugins,
+    classicIntegrations
+  )
+
+  const search = window.location.search ?? ''
+  const hash = window.location.hash ?? ''
+
+  const term = search.length ? search : hash.replace(/(?=#).*(?=\?)/, '')
+
+  if (term.includes('ajs_')) {
+    await analytics.queryString(term).catch(console.error)
+  }
+
+  analytics.initialized = true
+  analytics.emit('initialize', settings, options)
+
+  if (options.initialPageview) {
+    analytics.page().catch(console.error)
+  }
+
+  await flushFinalBuffer(analytics, preInitBuffer)
+
+  return [analytics, ctx]
+}
+
+/**
+ * The public browser interface for Hightouch Events
+ *
+ * @example
+ * ```ts
+ *  export const htevents = new HtEventsBrowser()
+ *  htevents.load({ writeKey: 'foo' })
+ * ```
+ * @link https://github.com/ht-sdks/events-sdk-js-mono/tree/master/packages/browser#readme
+ */
+export class HtEventsBrowser extends AnalyticsBuffered {
+  private _resolveLoadStart: (
+    settings: HtEventsBrowserSettings,
+    options: InitOptions
+  ) => void
+
+  constructor() {
+    const { promise: loadStart, resolve: resolveLoadStart } =
+      createDeferred<Parameters<HtEventsBrowser['load']>>()
+
+    super((buffer) =>
+      loadStart.then(([settings, options]) =>
+        loadAnalytics(settings, options, buffer)
+      )
+    )
+
+    this._resolveLoadStart = (settings, options) =>
+      resolveLoadStart([settings, options])
+  }
+
+  /**
+   * Fully initialize an analytics instance, including:
+   *
+   * * Fetching settings from the CDN (by default).
+   * * Fetching all remote destinations configured by the user (if applicable).
+   * * Flushing buffered analytics events.
+   * * Loading all middleware.
+   *
+   * Note:️  This method should only be called *once* in your application.
+   *
+   * @example
+   * ```ts
+   * export const analytics = new HtEventsBrowser()
+   * analytics.load({ writeKey: 'foo' })
+   * ```
+   */
+  load(
+    settings: HtEventsBrowserSettings,
+    options: InitOptions = {}
+  ): HtEventsBrowser {
+    this._resolveLoadStart(settings, options)
+    return this
+  }
+
+  /**
+   * Instantiates an object exposing Analytics methods.
+   *
+   * @example
+   * ```ts
+   * const ajs = HtEventsBrowser.load({ writeKey: '<YOUR_WRITE_KEY>' })
+   *
+   * ajs.track("foo")
+   * ...
+   * ```
+   */
+  static load(
+    settings: HtEventsBrowserSettings,
+    options: InitOptions = {}
+  ): HtEventsBrowser {
+    return new HtEventsBrowser().load(settings, options)
+  }
+
+  static standalone(
+    writeKey: string,
+    options?: InitOptions
+  ): Promise<Analytics> {
+    return HtEventsBrowser.load({ writeKey }, options).then((res) => res[0])
+  }
+}

package/packages/browser/src/browser/standalone-analytics.ts

@@ -0,0 +1,62 @@
+import { HtEventsBrowser } from '.'
+import { embeddedWriteKey } from '../lib/embedded-write-key'
+import { HtEventsSnippet } from './standalone-interface'
+import {
+  getGlobalAnalytics,
+  setGlobalAnalytics,
+} from '../lib/global-analytics-helper'
+
+function getWriteKey(): string | undefined {
+  if (embeddedWriteKey()) {
+    return embeddedWriteKey()
+  }
+
+  const analytics = getGlobalAnalytics()
+  if (analytics?._writeKey) {
+    return analytics._writeKey
+  }
+
+  const regex = /http.*\/analytics\.js\/v1\/([^/]*)(\/platform)?\/analytics.*/
+  const scripts = Array.prototype.slice.call(
+    document.querySelectorAll('script')
+  )
+  let writeKey: string | undefined = undefined
+
+  for (const s of scripts) {
+    const src = s.getAttribute('src') ?? ''
+    const result = regex.exec(src)
+
+    if (result && result[1]) {
+      writeKey = result[1]
+      break
+    }
+  }
+
+  if (!writeKey && document.currentScript) {
+    const script = document.currentScript as HTMLScriptElement
+    const src = script.src
+
+    const result = regex.exec(src)
+
+    if (result && result[1]) {
+      writeKey = result[1]
+    }
+  }
+
+  return writeKey
+}
+
+export async function install(): Promise<void> {
+  const writeKey = getWriteKey()
+  const options = getGlobalAnalytics()?._loadOptions ?? {}
+  if (!writeKey) {
+    console.error(
+      'Failed to load Write Key. Make sure to use the latest version of the hightouch snippet, which can be found in your source settings.'
+    )
+    return
+  }
+
+  setGlobalAnalytics(
+    (await HtEventsBrowser.standalone(writeKey, options)) as HtEventsSnippet
+  )
+}

package/packages/browser/src/browser/standalone-interface.ts

@@ -0,0 +1,11 @@
+import { Analytics, InitOptions } from '../core/analytics'
+
+export interface HtEventsSnippet extends AnalyticsStandalone {
+  load: (writeKey: string, options?: InitOptions) => void
+}
+
+export interface AnalyticsStandalone extends Analytics {
+  _loadOptions?: InitOptions
+  _writeKey?: string
+  _cdn?: string
+}