utneque 1.0.0

package/packages/consent/consent-tools/src/domain/__tests__/typedef-tests.ts

@@ -0,0 +1,21 @@
+import type {
+  HtEventsSnippet,
+  HtEventsBrowser,
+} from '@ht-sdks/events-sdk-js-browser'
+import { createWrapper, AnyAnalytics } from '../../index'
+
+type Extends<T, U> = T extends U ? true : false
+
+{
+  const wrap = createWrapper({ getCategories: () => ({ foo: true }) })
+  wrap({} as HtEventsBrowser)
+  wrap({} as HtEventsSnippet)
+
+  // see HtEventsSnippet and HtEventsBrowser extend AnyAnalytics
+  const f: Extends<HtEventsSnippet, AnyAnalytics> = true
+  const g: Extends<HtEventsBrowser, AnyAnalytics> = true
+  console.log(f, g)
+
+  // should be chainable
+  wrap({} as HtEventsBrowser).load({ writeKey: 'foo' })
+}

package/packages/consent/consent-tools/src/domain/consent-changed.ts

@@ -0,0 +1,51 @@
+import { AnyAnalytics, Categories } from '../types'
+import { getInitializedAnalytics } from './get-initialized-analytics'
+import { validateCategories } from './validation'
+
+/**
+ * Dispatch an event that looks like:
+ * ```ts
+ * {
+ * "type": "track",
+ *  "event": "Hightouch Consent Preference",
+ *  "context": {
+ *    "consent": {
+ *      "categoryPreferences" : {
+ *         "C0001": true,
+ *         "C0002": false,
+ *    }
+ *  }
+ * ...
+ * ```
+ */
+export const sendConsentChangedEvent = (
+  analytics: AnyAnalytics,
+  categories: Categories
+): void => {
+  getInitializedAnalytics(analytics).track(
+    CONSENT_CHANGED_EVENT,
+    undefined,
+    createConsentChangedCtxDto(categories)
+  )
+}
+
+const CONSENT_CHANGED_EVENT = 'Hightouch Consent Preference'
+
+const createConsentChangedCtxDto = (categories: Categories) => ({
+  consent: {
+    categoryPreferences: categories,
+  },
+})
+
+export const validateAndSendConsentChangedEvent = (
+  analytics: AnyAnalytics,
+  categories: Categories
+) => {
+  try {
+    validateCategories(categories)
+    sendConsentChangedEvent(analytics, categories)
+  } catch (err) {
+    // Not sure if there's a better way to handle this, but this makes testing a bit easier.
+    console.error(err)
+  }
+}

package/packages/consent/consent-tools/src/domain/consent-stamping.ts

@@ -0,0 +1,19 @@
+import { AnyAnalytics, Categories } from '../types'
+
+type CreateConsentMw = (
+  getCategories: () => Promise<Categories>
+) => AnyAnalytics['addSourceMiddleware']
+
+/**
+ * Create analytics addSourceMiddleware fn that stamps each event
+ */
+export const createConsentStampingMiddleware: CreateConsentMw =
+  (getCategories) =>
+  async ({ payload, next }) => {
+    const categories = await getCategories()
+    payload.obj.context.consent = {
+      ...payload.obj.context.consent,
+      categoryPreferences: categories,
+    }
+    next(payload)
+  }

package/packages/consent/consent-tools/src/domain/create-wrapper.ts

@@ -0,0 +1,238 @@
+import {
+  Categories,
+  CreateWrapper,
+  AnyAnalytics,
+  InitOptions,
+  CreateWrapperSettings,
+  CDNSettings,
+} from '../types'
+import {
+  validateAnalyticsInstance,
+  validateCategories,
+  validateSettings,
+} from './validation'
+import { createConsentStampingMiddleware } from './consent-stamping'
+import { pipe, pick, uniq } from '../utils'
+import { AbortLoadError, LoadContext } from './load-cancellation'
+import { ValidationError } from './validation/validation-error'
+import { validateAndSendConsentChangedEvent } from './consent-changed'
+
+export const createWrapper = <Analytics extends AnyAnalytics>(
+  ...[createWrapperOptions]: Parameters<CreateWrapper<Analytics>>
+): ReturnType<CreateWrapper<Analytics>> => {
+  validateSettings(createWrapperOptions)
+
+  const {
+    shouldDisableHightouch,
+    shouldDisableConsentRequirement,
+    getCategories,
+    shouldLoad,
+    integrationCategoryMappings,
+    shouldEnableIntegration,
+    pruneUnmappedCategories,
+    registerOnConsentChanged,
+  } = createWrapperOptions
+
+  return (analytics: Analytics) => {
+    validateAnalyticsInstance(analytics)
+
+    // Call this function as early as possible. OnConsentChanged events can happen before .load is called.
+    registerOnConsentChanged?.((categories) =>
+      // whenever consent changes, dispatch a new event with the latest consent information
+      validateAndSendConsentChangedEvent(analytics, categories)
+    )
+
+    const ogLoad = analytics.load
+
+    const loadWithConsent: AnyAnalytics['load'] = async (
+      settings,
+      options
+    ): Promise<void> => {
+      // do not load anything -- hightouch included
+      if (await shouldDisableHightouch?.()) {
+        return
+      }
+
+      const consentRequirementDisabled =
+        await shouldDisableConsentRequirement?.()
+      if (consentRequirementDisabled) {
+        // ignore consent -- just call analytics.load as usual
+        return ogLoad.call(analytics, settings, options)
+      }
+
+      // use these categories to disable/enable the appropriate device mode plugins
+      let initialCategories: Categories
+      try {
+        initialCategories =
+          (await shouldLoad?.(new LoadContext())) || (await getCategories())
+      } catch (e: unknown) {
+        // consumer can call ctx.abort({ loadHightouchNormally: true })
+        // to load Segment but disable consent requirement
+        if (e instanceof AbortLoadError) {
+          if (e.loadHightouchNormally === true) {
+            ogLoad.call(analytics, settings, options)
+          }
+          // do not load anything, but do not log anything either
+          // if someone calls ctx.abort(), they are handling the error themselves
+          return
+        } else {
+          throw e
+        }
+      }
+
+      validateCategories(initialCategories)
+
+      const getPrunedCategories = async (
+        cdnSettingsP: Promise<CDNSettings>
+      ): Promise<Categories> => {
+        const cdnSettings = await cdnSettingsP
+        // we don't want to send _every_ category to hightouch, only the ones that the user has explicitly configured in their integrations
+        let allCategories: string[]
+        // We need to get all the unique categories so we can prune the consent object down to only the categories that are configured
+        // There can be categories that are not included in any integration in the integrations object (e.g. 2 cloud mode categories), which is why we need a special allCategories array
+        if (integrationCategoryMappings) {
+          allCategories = uniq(
+            Object.values(integrationCategoryMappings).reduce((p, n) =>
+              p.concat(n)
+            )
+          )
+        } else {
+          allCategories = cdnSettings.consentSettings?.allCategories || []
+        }
+
+        if (!allCategories.length) {
+          // No configured integrations found, so no categories will be sent (should not happen unless there's a configuration error)
+          throw new ValidationError(
+            'Invariant: No consent categories defined in Segment',
+            []
+          )
+        }
+
+        const categories = await getCategories()
+
+        return pick(categories, allCategories)
+      }
+
+      // create getCategories and validate them regardless of whether pruning is turned on or off
+      const getValidCategoriesForConsentStamping = pipe(
+        pruneUnmappedCategories
+          ? getPrunedCategories.bind(
+              this,
+              new Promise<CDNSettings>((resolve) =>
+                analytics.on('initialize', resolve)
+              )
+            )
+          : getCategories,
+        async (categories) => {
+          validateCategories(await categories)
+          return categories
+        }
+      ) as () => Promise<Categories>
+
+      // register listener to stamp all events with latest consent information
+      analytics.addSourceMiddleware(
+        createConsentStampingMiddleware(getValidCategoriesForConsentStamping)
+      )
+
+      const updateCDNSettings: InitOptions['updateCDNSettings'] = (
+        cdnSettings
+      ) => {
+        if (!cdnSettings.remotePlugins) {
+          return cdnSettings
+        }
+
+        return disableIntegrations(
+          cdnSettings,
+          initialCategories,
+          integrationCategoryMappings,
+          shouldEnableIntegration
+        )
+      }
+
+      return ogLoad.call(analytics, settings, {
+        ...options,
+        updateCDNSettings: pipe(
+          updateCDNSettings,
+          options?.updateCDNSettings ? options.updateCDNSettings : (f) => f
+        ),
+      })
+    }
+    analytics.load = loadWithConsent
+    return analytics
+  }
+}
+
+/**
+ * Parse list of categories from `cdnSettings.integration.myIntegration` object
+ * @example
+ * returns ["Analytics", "Advertising"]
+ */
+const getConsentCategories = (integration: unknown): string[] | undefined => {
+  if (
+    integration &&
+    typeof integration === 'object' &&
+    'consentSettings' in integration &&
+    typeof integration.consentSettings === 'object' &&
+    integration.consentSettings &&
+    'categories' in integration.consentSettings &&
+    Array.isArray(integration.consentSettings.categories)
+  ) {
+    return (integration.consentSettings.categories as string[]) || undefined
+  }
+
+  return undefined
+}
+
+const disableIntegrations = (
+  cdnSettings: CDNSettings,
+  consentedCategories: Categories,
+  integrationCategoryMappings: CreateWrapperSettings['integrationCategoryMappings'],
+  shouldEnableIntegration: CreateWrapperSettings['shouldEnableIntegration']
+): CDNSettings => {
+  const { remotePlugins, integrations } = cdnSettings
+
+  const isPluginEnabled = (creationName: string) => {
+    const categories = integrationCategoryMappings
+      ? // allow hardcoding of consent category mappings for testing (or other reasons)
+        integrationCategoryMappings[creationName]
+      : getConsentCategories(integrations[creationName])
+
+    // allow user to customize consent logic if needed
+    if (shouldEnableIntegration) {
+      return shouldEnableIntegration(categories || [], consentedCategories, {
+        creationName,
+      })
+    }
+
+    const isMissingCategories = !categories || !categories.length
+
+    // Enable integration by default if it contains no consent categories data (most likely because consent has not been configured).
+    if (isMissingCategories) {
+      return true
+    }
+
+    // Enable if all of its consent categories are consented to
+    const hasUserConsent = categories.every((c) => consentedCategories[c])
+    return hasUserConsent
+  }
+
+  const results = Object.keys(integrations).reduce<CDNSettings>(
+    (acc, creationName) => {
+      if (!isPluginEnabled(creationName)) {
+        // remote disabled action destinations
+        acc.remotePlugins =
+          acc.remotePlugins &&
+          acc.remotePlugins.filter((el) => el.creationName !== creationName)
+        // remove disabled classic destinations and locally-installed action destinations
+        delete acc.integrations[creationName]
+      }
+      return acc
+    },
+    {
+      ...cdnSettings,
+      remotePlugins,
+      integrations: { ...integrations }, // make shallow copy to avoid mutating original
+    }
+  )
+  return results
+}

package/packages/consent/consent-tools/src/domain/get-initialized-analytics.ts

@@ -0,0 +1,25 @@
+import { AnyAnalytics } from '../types'
+
+/**
+ * There is a known bug for people who attempt to to wrap the library: the analytics reference does not get updated when the analytics.js library loads.
+ * Thus, we need to proxy events to the global reference instead.
+ *
+ * There is a universal fix here: however, many users may not have updated it:
+ * https://github.com/segmentio/snippet/commit/081faba8abab0b2c3ec840b685c4ff6d6cccf79c
+ */
+export const getInitializedAnalytics = (
+  analytics: AnyAnalytics
+): AnyAnalytics => {
+  const isSnippetUser = Array.isArray(analytics)
+  if (isSnippetUser) {
+    const opts = (analytics as any)._loadOptions ?? {}
+    const globalAnalytics = (window as any)[
+      opts?.globalAnalyticsKey ?? 'htevents'
+    ]
+    if ((globalAnalytics as any).initialized) {
+      return globalAnalytics
+    }
+  }
+
+  return analytics
+}

package/packages/consent/consent-tools/src/domain/load-cancellation.ts

@@ -0,0 +1,31 @@
+import { AnalyticsConsentError } from '../types/errors'
+import { ValidationError } from './validation/validation-error'
+
+/**
+ * Thrown when a load should be cancelled.
+ */
+export class AbortLoadError extends AnalyticsConsentError {
+  constructor(public loadHightouchNormally: boolean) {
+    super('AbortLoadError', '')
+  }
+}
+
+export interface AbortLoadOptions {
+  /**
+   * Whether or not to load hightouch.
+   * If true -- load hightouch normally (and disable consent requirement.) Wrapper is essentially a no-op
+   */
+  loadHightouchNormally: boolean
+}
+
+export class LoadContext {
+  /**
+   * Abort the load (this function will always throw)
+   */
+  abort(options: AbortLoadOptions): never {
+    if (typeof options !== 'object') {
+      throw new ValidationError('arg should be an object', options)
+    }
+    throw new AbortLoadError(options.loadHightouchNormally)
+  }
+}

package/packages/consent/consent-tools/src/domain/validation/__tests__/options-validators.test.ts

@@ -0,0 +1,77 @@
+import { CreateWrapperSettings } from '../../../types'
+import { validateCategories, validateSettings } from '../options-validators'
+import { ValidationError } from '../validation-error'
+
+const DEFAULT_OPTIONS: CreateWrapperSettings = {
+  getCategories: () => ({}),
+}
+
+describe(validateSettings, () => {
+  it('should throw if options is not a plain object', () => {
+    expect(() => validateSettings(null as any)).toThrow()
+    expect(() => validateSettings(undefined as any)).toThrow()
+    expect(() => validateSettings('hello' as any)).toThrow()
+  })
+
+  it('should throw an instance of ValidationError', () => {
+    expect(() => validateSettings(null as any)).toThrowError(ValidationError)
+  })
+
+  it('should throw with the expected error', () => {
+    expect(() =>
+      validateSettings(null as any)
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"[Validation] Options should be an object (Received: null)"`
+    )
+  })
+
+  it('should throw if required property(s) are not included', () => {
+    expect(() => validateSettings({} as any)).toThrow()
+  })
+
+  it('should throw if getCategories() is not a function', () => {
+    expect(() =>
+      validateSettings({
+        getCategories: {},
+      })
+    ).toThrow()
+  })
+
+  it('should throw if registerOnChanged() is not a function', () => {
+    expect(() =>
+      validateSettings({
+        ...DEFAULT_OPTIONS,
+        registerOnConsentChanged: {} as any,
+      })
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"[Validation] registerOnConsentChanged is not a function (Received: {})"`
+    )
+  })
+})
+
+describe(validateCategories, () => {
+  it('should throw if categories is not a plain object', () => {
+    expect(() => validateCategories(null)).toThrow()
+    expect(() => validateCategories(undefined)).toThrow()
+    expect(() => validateCategories('hello')).toThrow()
+  })
+
+  it('should throw an instance of ValidationError', () => {
+    expect(() => validateCategories(null)).toThrow(ValidationError)
+  })
+
+  it('should throw with the expected error', () => {
+    expect(() => validateCategories(null)).toThrowErrorMatchingInlineSnapshot(
+      `"[Validation] Consent Categories should be {[categoryName: string]: boolean} (Received: null)"`
+    )
+  })
+
+  it('should throw if categories does not match {categoryName: boolean}', () => {
+    expect(() => validateCategories({})).not.toThrow() // if getCategories is empty object, it is the same as 'consent to all categories' if false
+    expect(() => validateCategories({ a: true })).not.toThrow()
+    expect(() => validateCategories({ a: 'foo' })).toThrow()
+    expect(() => validateCategories({ a: 'true' })).toThrow()
+    expect(() => validateCategories({ a: true, b: 'foo' })).toThrow()
+    expect(() => validateCategories({ a: true, b: 'foo', c: true })).toThrow()
+  })
+})

package/packages/consent/consent-tools/src/domain/validation/__tests__/validation-error.test.ts

@@ -0,0 +1,15 @@
+import { ValidationError } from '../validation-error'
+
+describe(ValidationError, () => {
+  it('should have the correct shape', () => {
+    const err = new ValidationError('foo', 'bar')
+
+    expect(err).toBeInstanceOf(Error)
+
+    expect(err.name).toBe('ValidationError')
+
+    expect(err.message).toMatchInlineSnapshot(
+      `"[Validation] foo (Received: \\"bar\\")"`
+    )
+  })
+})

package/packages/consent/consent-tools/src/domain/validation/common-validators.ts

@@ -0,0 +1,19 @@
+import { ValidationError } from './validation-error'
+
+export function assertIsFunction(
+  val: unknown,
+  variableName: string
+): asserts val is Function {
+  if (typeof val !== 'function') {
+    throw new ValidationError(`${variableName} is not a function`, val)
+  }
+}
+
+export function assertIsObject(
+  val: unknown,
+  variableName: string
+): asserts val is object {
+  if (val === null || typeof val !== 'object') {
+    throw new ValidationError(`${variableName} is not an object`, val)
+  }
+}

package/packages/consent/consent-tools/src/domain/validation/index.ts

@@ -0,0 +1 @@
+export * from './options-validators'

package/packages/consent/consent-tools/src/domain/validation/options-validators.ts

@@ -0,0 +1,74 @@
+import { AnyAnalytics, Categories, CreateWrapperSettings } from '../../types'
+import { assertIsFunction, assertIsObject } from './common-validators'
+import { ValidationError } from './validation-error'
+
+export function validateCategories(
+  ctgs: unknown
+): asserts ctgs is NonNullable<Categories> {
+  let hasError = true
+  if (ctgs && typeof ctgs === 'object' && !Array.isArray(ctgs)) {
+    hasError = false
+    for (const k in ctgs) {
+      if (typeof (ctgs as any)[k] !== 'boolean') {
+        hasError = true
+        break
+      }
+    }
+  }
+  if (hasError) {
+    throw new ValidationError(
+      `Consent Categories should be {[categoryName: string]: boolean}`,
+      ctgs
+    )
+  }
+}
+
+export function validateSettings(options: {
+  [k in keyof CreateWrapperSettings]: unknown
+}): asserts options is CreateWrapperSettings {
+  if (typeof options !== 'object' || !options) {
+    throw new ValidationError('Options should be an object', options)
+  }
+
+  assertIsFunction(options.getCategories, 'getCategories')
+
+  options.shouldLoad && assertIsFunction(options.shouldLoad, 'shouldLoad')
+
+  options.shouldDisableConsentRequirement &&
+    assertIsFunction(
+      options.shouldDisableConsentRequirement,
+      'shouldDisableConsentRequirement'
+    )
+
+  options.shouldEnableIntegration &&
+    assertIsFunction(options.shouldEnableIntegration, 'shouldEnableIntegration')
+
+  options.shouldDisableHightouch &&
+    assertIsFunction(options.shouldDisableHightouch, 'shouldDisableHightouch')
+
+  options.integrationCategoryMappings &&
+    assertIsObject(
+      options.integrationCategoryMappings,
+      'integrationCategoryMappings'
+    )
+
+  options.registerOnConsentChanged &&
+    assertIsFunction(
+      options.registerOnConsentChanged,
+      'registerOnConsentChanged'
+    )
+}
+
+export function validateAnalyticsInstance(
+  analytics: unknown
+): asserts analytics is AnyAnalytics {
+  assertIsObject(analytics, 'analytics')
+  if (
+    'load' in analytics &&
+    'on' in analytics &&
+    'addSourceMiddleware' in analytics
+  ) {
+    return
+  }
+  throw new ValidationError('analytics is not an Analytics instance', analytics)
+}

package/packages/consent/consent-tools/src/domain/validation/validation-error.ts

@@ -0,0 +1,11 @@
+import { AnalyticsConsentError } from '../../types/errors'
+
+export class ValidationError extends AnalyticsConsentError {
+  constructor(message: string, received?: any) {
+    if (arguments.length === 2) {
+      // to ensure that explicitly passing undefined as second argument still works
+      message += ` (Received: ${JSON.stringify(received)})`
+    }
+    super('ValidationError', `[Validation] ${message}`)
+  }
+}

package/packages/consent/consent-tools/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * This is the public API for this package.
+ * We avoid using splat (*) exports so that we can control what is exposed.
+ */
+export { createWrapper } from './domain/create-wrapper'
+export { resolveWhen } from './utils'
+
+export type {
+  Wrapper,
+  CreateWrapper,
+  CreateWrapperSettings,
+  IntegrationCategoryMappings,
+  Categories,
+  RegisterOnConsentChangedFunction,
+  AnyAnalytics,
+} from './types'

package/packages/consent/consent-tools/src/types/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Base Consent Error
+ */
+export abstract class AnalyticsConsentError extends Error {
+  /**
+   *
+   * @param name - Pass the name explicitly to work around the limitation that 'name' is automatically set to the parent class.
+   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends#using_extends
+   * @param message - Error message
+   */
+  constructor(public name: string, message: string) {
+    super(message)
+  }
+}

package/packages/consent/consent-tools/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './wrapper'
+export * from './settings'
+export * from './errors'