utneque 1.0.0

package/packages/consent/consent-wrapper-onetrust/src/domain/__tests__/wrapper.test.ts

@@ -0,0 +1,151 @@
+import * as ConsentTools from '@ht-sdks/events-sdk-js-consent-tools'
+import * as OneTrustAPI from '../../lib/onetrust-api'
+import { sleep } from '@internal/test-helpers'
+import { withOneTrust } from '../wrapper'
+import { OneTrustMockGlobal, analyticsMock } from '../../test-helpers/mocks'
+
+const throwNotImplemented = (): never => {
+  throw new Error('not implemented')
+}
+
+const grpFixture = {
+  StrictlyNeccessary: {
+    CustomGroupId: 'C0001',
+  },
+  Targeting: {
+    CustomGroupId: 'C0004',
+  },
+  Performance: {
+    CustomGroupId: 'C0005',
+  },
+}
+
+const getConsentedGroupIdsSpy = jest
+  .spyOn(OneTrustAPI, 'getConsentedGroupIds')
+  .mockImplementationOnce(throwNotImplemented)
+
+const createWrapperSpyHelper = {
+  _spy: jest.spyOn(ConsentTools, 'createWrapper'),
+  get shouldLoad() {
+    return createWrapperSpyHelper._spy.mock.lastCall[0].shouldLoad!
+  },
+  get getCategories() {
+    return createWrapperSpyHelper._spy.mock.lastCall[0].getCategories!
+  },
+  get registerOnConsentChanged() {
+    return createWrapperSpyHelper._spy.mock.lastCall[0]
+      .registerOnConsentChanged!
+  },
+}
+
+/**
+ * These tests are not meant to be comprehensive, but they should cover the most important cases.
+ * We should prefer unit tests for most functionality (see lib/__tests__)
+ */
+describe('High level "integration" tests', () => {
+  let resolveResolveWhen = () => {}
+  beforeEach(() => {
+    jest
+      .spyOn(OneTrustAPI, 'getOneTrustGlobal')
+      .mockImplementation(() => OneTrustMockGlobal)
+    getConsentedGroupIdsSpy.mockReset()
+    Object.values(OneTrustMockGlobal).forEach((fn) => fn.mockReset())
+    /**
+     * Typically, resolveWhen triggers when a predicate is true. We can manually 'check' so we don't have to use timeouts.
+     */
+    jest.spyOn(ConsentTools, 'resolveWhen').mockImplementation(async (fn) => {
+      return new Promise((_resolve) => {
+        resolveResolveWhen = () => {
+          if (fn()) {
+            _resolve()
+          } else {
+            throw new Error('Refuse to resolve, resolveWhen condition is false')
+          }
+        }
+      })
+    })
+  })
+
+  describe('shouldLoad', () => {
+    it('should be resolved successfully', async () => {
+      withOneTrust(analyticsMock)
+      OneTrustMockGlobal.GetDomainData.mockReturnValueOnce({
+        Groups: [grpFixture.StrictlyNeccessary, grpFixture.Performance],
+      })
+      getConsentedGroupIdsSpy.mockImplementation(() => [
+        grpFixture.StrictlyNeccessary.CustomGroupId,
+      ])
+      const shouldLoadP = Promise.resolve(
+        createWrapperSpyHelper.shouldLoad({} as any)
+      )
+      let shouldLoadResolved = false
+      void shouldLoadP.then(() => (shouldLoadResolved = true))
+      await sleep(0)
+      expect(shouldLoadResolved).toBe(false)
+      OneTrustMockGlobal.IsAlertBoxClosed.mockReturnValueOnce(true)
+      resolveResolveWhen()
+      const result = await shouldLoadP
+      expect(result).toBe(undefined)
+    })
+  })
+
+  describe('getCategories', () => {
+    it('should get categories successfully', async () => {
+      withOneTrust(analyticsMock)
+      OneTrustMockGlobal.GetDomainData.mockReturnValue({
+        Groups: [
+          grpFixture.StrictlyNeccessary,
+          grpFixture.Performance,
+          grpFixture.Targeting,
+        ],
+      })
+      getConsentedGroupIdsSpy.mockImplementation(() => [
+        grpFixture.StrictlyNeccessary.CustomGroupId,
+      ])
+      const categories = createWrapperSpyHelper.getCategories()
+      // contain both consented and denied category
+      expect(categories).toEqual({
+        C0001: true,
+        C0004: false,
+        C0005: false,
+      })
+    })
+  })
+
+  describe('Consent changed', () => {
+    it('should enable consent changed by default', async () => {
+      withOneTrust(analyticsMock)
+      OneTrustMockGlobal.GetDomainData.mockReturnValue({
+        Groups: [
+          grpFixture.StrictlyNeccessary,
+          grpFixture.Performance,
+          grpFixture.Targeting,
+        ],
+      })
+      const onCategoriesChangedCb = jest.fn()
+
+      createWrapperSpyHelper.registerOnConsentChanged(onCategoriesChangedCb)
+      onCategoriesChangedCb()
+
+      resolveResolveWhen() // wait for OneTrust global to be available
+      await sleep(0)
+
+      const onConsentChangedArg =
+        OneTrustMockGlobal.OnConsentChanged.mock.lastCall[0]
+      onConsentChangedArg(
+        new CustomEvent('', {
+          detail: [
+            grpFixture.StrictlyNeccessary.CustomGroupId,
+            grpFixture.Performance.CustomGroupId,
+          ],
+        })
+      )
+      // expect to be normalized!
+      expect(onCategoriesChangedCb.mock.lastCall[0]).toEqual({
+        [grpFixture.StrictlyNeccessary.CustomGroupId]: true,
+        [grpFixture.Performance.CustomGroupId]: true,
+        [grpFixture.Targeting.CustomGroupId]: false,
+      })
+    })
+  })
+})

package/packages/consent/consent-wrapper-onetrust/src/domain/wrapper.ts

@@ -0,0 +1,61 @@
+import {
+  AnyAnalytics,
+  createWrapper,
+  CreateWrapperSettings,
+  RegisterOnConsentChangedFunction,
+  resolveWhen,
+} from '@ht-sdks/events-sdk-js-consent-tools'
+
+import {
+  getNormalizedCategoriesFromGroupData,
+  getNormalizedCategoriesFromGroupIds,
+  getConsentedGroupIds,
+  getOneTrustGlobal,
+} from '../lib/onetrust-api'
+
+export interface OneTrustSettings {
+  integrationCategoryMappings?: CreateWrapperSettings['integrationCategoryMappings']
+  disableConsentChangedEvent?: boolean
+}
+
+/**
+ *
+ * @param analyticsInstance - An analytics instance. Either `window.htevents`, or the instance returned by `new HtEventsBrowser()` or `HtEventsBrowser.load({...})`
+ * @param settings - Optional settings for configuring your OneTrust wrapper
+ */
+export const withOneTrust = <Analytics extends AnyAnalytics>(
+  analyticsInstance: Analytics,
+  settings: OneTrustSettings = {}
+): Analytics => {
+  const registerOnConsentChanged: RegisterOnConsentChangedFunction = async (
+    onCategoriesChangedCb
+  ) => {
+    await resolveWhen(() => getOneTrustGlobal() !== undefined, 500)
+    getOneTrustGlobal()!.OnConsentChanged((event) => {
+      const normalizedCategories = getNormalizedCategoriesFromGroupIds(
+        event.detail
+      )
+      onCategoriesChangedCb(normalizedCategories)
+    })
+  }
+  return createWrapper<Analytics>({
+    shouldLoad: async () => {
+      await resolveWhen(() => {
+        const oneTrustGlobal = getOneTrustGlobal()
+        return (
+          oneTrustGlobal !== undefined &&
+          Boolean(getConsentedGroupIds().length) &&
+          oneTrustGlobal.IsAlertBoxClosed()
+        )
+      }, 500)
+    },
+    getCategories: () => {
+      const results = getNormalizedCategoriesFromGroupData()
+      return results
+    },
+    registerOnConsentChanged: settings.disableConsentChangedEvent
+      ? undefined
+      : registerOnConsentChanged,
+    integrationCategoryMappings: settings.integrationCategoryMappings,
+  })(analyticsInstance)
+}

package/packages/consent/consent-wrapper-onetrust/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * This is the public API for this package.
+ * We avoid using splat (*) exports so that we can control what is exposed.
+ */
+export { withOneTrust } from './domain/wrapper'
+export type { OneTrustSettings } from './domain/wrapper'

package/packages/consent/consent-wrapper-onetrust/src/index.umd.ts

@@ -0,0 +1,11 @@
+/**
+ * This file is meant to be used to create a webpack bundle.
+ */
+import { withOneTrust } from './index'
+export { withOneTrust }
+
+// this will almost certainly be executed in the browser, but since this is UMD,
+// we are checking just for the sake of being thorough
+if (typeof window !== 'undefined') {
+  ;(window as any).withOneTrust = withOneTrust
+}

package/packages/consent/consent-wrapper-onetrust/src/lib/__tests__/onetrust-api.test.ts

@@ -0,0 +1,181 @@
+import '../../test-helpers/onetrust-globals.d.ts'
+
+import {
+  getConsentedGroupIds,
+  getGroupDataFromGroupIds,
+  getNormalizedCategoriesFromGroupData,
+  getOneTrustActiveGroups,
+  getNormalizedCategoriesFromGroupIds,
+  getOneTrustGlobal,
+  getAllGroups,
+} from '../onetrust-api'
+import { OneTrustMockGlobal } from '../../test-helpers/mocks'
+import { OneTrustApiValidationError } from '../validation'
+
+beforeEach(() => {
+  // @ts-ignore
+  delete window.OneTrustActiveGroups
+  // @ts-ignore
+  delete window.OneTrust
+})
+
+describe(getOneTrustGlobal, () => {
+  it('should get the global', () => {
+    ;(window as any).OneTrust = OneTrustMockGlobal
+    expect(getOneTrustGlobal()).toEqual(OneTrustMockGlobal)
+  })
+
+  it('should throw an error if the global is missing fields', () => {
+    ;(window as any).OneTrust = {}
+    expect(() => getOneTrustGlobal()).toThrow(OneTrustApiValidationError)
+  })
+})
+
+describe(getAllGroups, () => {
+  it('works if OneTrust global is not available', () => {
+    ;(window as any).OneTrust = undefined
+    expect(getAllGroups()).toEqual([])
+  })
+  it('get the normalized groups', () => {
+    ;(window as any).OneTrust = OneTrustMockGlobal
+    window.OneTrust = {
+      ...OneTrustMockGlobal,
+      GetDomainData: () => ({
+        Groups: [
+          {
+            CustomGroupId: 'C0001',
+          },
+          {
+            CustomGroupId: 'C0004',
+          },
+          {
+            CustomGroupId: '  C0005',
+          },
+          {
+            CustomGroupId: 'C0006  ',
+          },
+        ],
+      }),
+    }
+    expect(getAllGroups()).toEqual([
+      { groupId: 'C0001' },
+      { groupId: 'C0004' },
+      { groupId: 'C0005' },
+      { groupId: 'C0006' },
+    ])
+  })
+})
+
+describe(getNormalizedCategoriesFromGroupData, () => {
+  it('should return a set of groups', () => {
+    expect(
+      getNormalizedCategoriesFromGroupData({
+        userSetConsentGroups: [{ groupId: 'C0003' }],
+        userDeniedConsentGroups: [{ groupId: 'C0001' }, { groupId: 'C0002' }],
+      })
+    ).toEqual({ C0003: true, C0001: false, C0002: false })
+  })
+})
+
+describe(getOneTrustActiveGroups, () => {
+  it('should return the global string', () => {
+    window.OnetrustActiveGroups = 'hello'
+    expect(getOneTrustActiveGroups()).toBe('hello')
+  })
+  it('should return undefined if no groups are defined', () => {
+    // @ts-ignore
+    window.OnetrustActiveGroups = undefined
+    expect(getOneTrustActiveGroups()).toBe(undefined)
+
+    // @ts-ignore
+    window.OnetrustActiveGroups = null
+    expect(getOneTrustActiveGroups()).toBe(undefined)
+
+    window.OnetrustActiveGroups = ''
+    expect(getOneTrustActiveGroups()).toBe(undefined)
+  })
+
+  it('should throw an error if OneTrustActiveGroups is invalid', () => {
+    // @ts-ignore
+    window.OnetrustActiveGroups = []
+    expect(() => getOneTrustActiveGroups()).toThrow(OneTrustApiValidationError)
+  })
+})
+
+describe(getConsentedGroupIds, () => {
+  it('should normalize groupIds', () => {
+    expect(getConsentedGroupIds(',C0001,')).toEqual(['C0001'])
+    expect(getConsentedGroupIds('C0001,C0004')).toEqual(['C0001', 'C0004'])
+    expect(getConsentedGroupIds(',C0001,C0004')).toEqual(['C0001', 'C0004'])
+    expect(getConsentedGroupIds(',')).toEqual([])
+    expect(getConsentedGroupIds('')).toEqual([])
+    expect(getConsentedGroupIds(',,')).toEqual([])
+  })
+
+  it('should return an empty array if no groups are defined', () => {
+    // @ts-ignore
+    window.OnetrustActiveGroups = undefined
+    expect(getConsentedGroupIds()).toEqual([])
+  })
+})
+
+describe(getGroupDataFromGroupIds, () => {
+  it('should partition groups into consent/deny', () => {
+    window.OnetrustActiveGroups = ',C0001,C0004'
+    window.OneTrust = {
+      ...OneTrustMockGlobal,
+      GetDomainData: () => ({
+        Groups: [
+          {
+            CustomGroupId: 'C0001',
+          },
+          {
+            CustomGroupId: 'C0004',
+          },
+          {
+            CustomGroupId: 'SOME_OTHER_GROUP',
+          },
+        ],
+      }),
+    }
+    const data = getGroupDataFromGroupIds()
+
+    expect(data.userSetConsentGroups).toEqual([
+      {
+        groupId: 'C0001',
+      },
+      {
+        groupId: 'C0004',
+      },
+    ])
+
+    expect(data.userDeniedConsentGroups).toEqual([
+      {
+        groupId: 'SOME_OTHER_GROUP',
+      },
+    ])
+  })
+})
+
+describe(getNormalizedCategoriesFromGroupIds, () => {
+  it('should get normalized categories', () => {
+    window.OneTrust = {
+      ...OneTrustMockGlobal,
+      GetDomainData: () => ({
+        Groups: [
+          {
+            CustomGroupId: 'C0001',
+          },
+          {
+            CustomGroupId: 'C0004',
+          },
+          {
+            CustomGroupId: 'SOME_OTHER_GROUP',
+          },
+        ],
+      }),
+    }
+    const ids = getNormalizedCategoriesFromGroupIds(['C0001'])
+    expect(ids).toEqual({ C0001: true, C0004: false, SOME_OTHER_GROUP: false })
+  })
+})

package/packages/consent/consent-wrapper-onetrust/src/lib/onetrust-api.ts

@@ -0,0 +1,155 @@
+import { Categories } from '@ht-sdks/events-sdk-js-consent-tools'
+import { OneTrustApiValidationError } from './validation'
+/**
+ * @example ["C0001", "C0002"]
+ */
+type ConsentGroupIds = string[]
+
+/**
+ * @example
+ * ",C0001,C0002" => ["C0001", "C0002"]
+ */
+const normalizeActiveGroupIds = (
+  oneTrustActiveGroups: string
+): ConsentGroupIds => {
+  return oneTrustActiveGroups.trim().split(',').filter(Boolean)
+}
+
+type GroupInfoDto = {
+  CustomGroupId: string
+}
+
+type OtConsentChangedEvent = CustomEvent<ConsentGroupIds>
+
+/**
+ * The data model used by the OneTrust lib
+ */
+export interface OneTrustGlobal {
+  GetDomainData: () => {
+    Groups: GroupInfoDto[]
+  }
+  /**
+   *  This callback appears to fire whenever the alert box is closed, no matter what.
+   * E.g:
+   * - if a user continues without accepting
+   * - if a user makes a selection
+   * - if a user rejects all
+   */
+  OnConsentChanged: (cb: (event: OtConsentChangedEvent) => void) => void
+  IsAlertBoxClosed: () => boolean
+}
+
+export const getOneTrustGlobal = (): OneTrustGlobal | undefined => {
+  const oneTrust = (window as any).OneTrust
+  if (!oneTrust) return undefined
+  if (
+    typeof oneTrust === 'object' &&
+    'OnConsentChanged' in oneTrust &&
+    'IsAlertBoxClosed' in oneTrust &&
+    'GetDomainData' in oneTrust
+  ) {
+    return oneTrust
+  }
+
+  throw new OneTrustApiValidationError(
+    'window.OneTrust is not in expected format',
+    oneTrust
+  )
+}
+
+export const getOneTrustActiveGroups = (): string | undefined => {
+  const groups = (window as any).OnetrustActiveGroups
+  if (!groups) return undefined
+  if (typeof groups !== 'string') {
+    throw new OneTrustApiValidationError(
+      `window.OnetrustActiveGroups is not a string`,
+      groups
+    )
+  }
+  return groups
+}
+
+export const getConsentedGroupIds = (
+  groups = getOneTrustActiveGroups()
+): ConsentGroupIds => {
+  if (!groups) {
+    return []
+  }
+  return normalizeActiveGroupIds(groups || '')
+}
+
+export type GroupInfo = {
+  groupId: string
+}
+
+const normalizeGroupInfo = (groupInfo: GroupInfoDto): GroupInfo => ({
+  groupId: groupInfo.CustomGroupId.trim(),
+})
+
+/**
+ * get *all* groups / categories, not just active ones
+ */
+export const getAllGroups = (): GroupInfo[] => {
+  const oneTrustGlobal = getOneTrustGlobal()
+  if (!oneTrustGlobal) return []
+  return oneTrustGlobal.GetDomainData().Groups.map(normalizeGroupInfo)
+}
+
+type UserConsentGroupData = {
+  userSetConsentGroups: GroupInfo[]
+  userDeniedConsentGroups: GroupInfo[]
+}
+
+// derive the groupIds from the active groups
+export const getGroupDataFromGroupIds = (
+  userSetConsentGroupIds = getConsentedGroupIds()
+): UserConsentGroupData => {
+  // partition all groups into "consent" or "deny"
+  const userConsentGroupData = getAllGroups().reduce<UserConsentGroupData>(
+    (acc, group) => {
+      if (userSetConsentGroupIds.includes(group.groupId)) {
+        acc.userSetConsentGroups.push(group)
+      } else {
+        acc.userDeniedConsentGroups.push(group)
+      }
+      return acc
+    },
+    { userSetConsentGroups: [], userDeniedConsentGroups: [] }
+  )
+
+  return userConsentGroupData
+}
+
+export const getNormalizedCategoriesFromGroupData = (
+  groupData = getGroupDataFromGroupIds()
+): Categories => {
+  const { userSetConsentGroups, userDeniedConsentGroups } = groupData
+  const consentedCategories = userSetConsentGroups.reduce<Categories>(
+    (acc, c) => {
+      return {
+        ...acc,
+        [c.groupId]: true,
+      }
+    },
+    {}
+  )
+
+  const deniedCategories = userDeniedConsentGroups.reduce<Categories>(
+    (acc, c) => {
+      return {
+        ...acc,
+        [c.groupId]: false,
+      }
+    },
+    {}
+  )
+  return { ...consentedCategories, ...deniedCategories }
+}
+
+export const getNormalizedCategoriesFromGroupIds = (
+  groupIds: ConsentGroupIds
+): Categories => {
+  return getNormalizedCategoriesFromGroupData(
+    getGroupDataFromGroupIds(groupIds)
+  )
+}

package/packages/consent/consent-wrapper-onetrust/src/lib/validation/index.ts

@@ -0,0 +1 @@
+export * from './onetrust-api-error'

package/packages/consent/consent-wrapper-onetrust/src/lib/validation/onetrust-api-error.ts

@@ -0,0 +1,11 @@
+/**
+ * An Errot that represents that the OneTrust API is not in the expected format.
+ * This is not something that could happen unless our API types are wrong and something is very wonky.
+ * Not a recoverable error.
+ */
+export class OneTrustApiValidationError extends Error {
+  name = 'OtConsentWrapperValidationError'
+  constructor(message: string, received: any) {
+    super(`Invariant: ${message} (Received: ${JSON.stringify(received)})`)
+  }
+}

package/packages/consent/consent-wrapper-onetrust/src/test-helpers/mocks.ts

@@ -0,0 +1,23 @@
+import { OneTrustGlobal } from '../lib/onetrust-api'
+import { throwNotImplemented } from './utils'
+import type { AnyAnalytics } from '@ht-sdks/events-sdk-js-consent-tools'
+/**
+ * This can be used to mock the OneTrust global object in individual tests
+ * @example
+ * ```ts
+ * import * as OneTrustAPI from '../onetrust-api'
+ * jest.spyOn(OneTrustAPI, 'getOneTrustGlobal').mockImplementation(() => OneTrustMockGlobal)
+ * ````
+ */
+export const OneTrustMockGlobal: jest.Mocked<OneTrustGlobal> = {
+  GetDomainData: jest.fn().mockImplementation(throwNotImplemented),
+  IsAlertBoxClosed: jest.fn().mockImplementation(throwNotImplemented),
+  OnConsentChanged: jest.fn().mockImplementation(throwNotImplemented), // not implemented atm
+}
+
+export const analyticsMock: jest.Mocked<AnyAnalytics> = {
+  addSourceMiddleware: jest.fn().mockImplementation(throwNotImplemented),
+  load: jest.fn().mockImplementation(throwNotImplemented),
+  on: jest.fn().mockImplementation(throwNotImplemented),
+  track: jest.fn().mockImplementation(throwNotImplemented),
+}

package/packages/consent/consent-wrapper-onetrust/src/test-helpers/onetrust-globals.d.ts

@@ -0,0 +1,11 @@
+import { OneTrustGlobal } from '../lib/onetrust-api'
+/**
+ * ALERT: It's OK to declare ambient globals in test code, but __not__ in library code
+ * This file should not be included in the final package
+ */
+export declare global {
+  interface Window {
+    OneTrust: OneTrustGlobal
+    OnetrustActiveGroups: string
+  }
+}

package/packages/consent/consent-wrapper-onetrust/src/test-helpers/utils.ts

@@ -0,0 +1,3 @@
+export const throwNotImplemented = (): never => {
+  throw new Error('not implemented')
+}

package/packages/consent/consent-wrapper-onetrust/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/test-helpers/**"],
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "declarationDir": "./dist/types"
+  }
+}

package/packages/consent/consent-wrapper-onetrust/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.json",
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "module": "ESNext", // es6 modules
+    "target": "ES2020", // don't down-compile *too much* -- if users are using webpack, they can always transpile this library themselves
+    "lib": ["ES2020", "DOM", "DOM.Iterable"], // assume that consumers will be polyfilling at least down to es2020
+    "moduleResolution": "node",
+    "isolatedModules": true // ensure we are friendly to build systems
+  }
+}

package/packages/consent/consent-wrapper-onetrust/webpack.config.js

@@ -0,0 +1,25 @@
+const common = require('@internal/config-webpack/webpack.config.common')
+const path = require('path')
+const { merge } = require('webpack-merge')
+const isProd = process.env.NODE_ENV === 'production'
+/**
+ * @type { import('webpack').Configuration }
+ */
+module.exports = merge(common, {
+  entry: {
+    'analytics-onetrust.umd': {
+      import: path.resolve(__dirname, 'src/index.umd.ts'),
+      library: {
+        name: 'AnalyticsOneTrust',
+        type: 'umd',
+      },
+    },
+  },
+  output: {
+    filename: isProd ? '[name].js' : '[name].development.js',
+    path: path.resolve(__dirname, 'dist/umd'),
+    chunkFilename: isProd
+      ? '[name].[contenthash].js'
+      : '[name].chunk.development.js',
+  },
+})

package/packages/core/.eslintrc.js

@@ -0,0 +1,4 @@
+/** @type { import('eslint').Linter.Config } */
+module.exports = {
+  extends: ['../../.eslintrc.isomorphic'],
+}

package/packages/core/.lintstagedrc.js

@@ -0,0 +1 @@
+module.exports = require("@internal/config").lintStagedConfig