utneque 1.0.0

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

@@ -0,0 +1,121 @@
+import { LoadContext } from '../domain/load-cancellation'
+import type {
+  Categories,
+  IntegrationCategoryMappings,
+  CDNSettingsRemotePlugin,
+} from './wrapper'
+
+export type RegisterOnConsentChangedFunction = (
+  categoriesChangedCb: (categories: Categories) => void
+) => void
+
+/**
+ * Consent wrapper function configuration
+ */
+export interface CreateWrapperSettings {
+  /**
+   * Wait until this function resolves/returns before loading analytics.
+   * This function should return a list of initial categories.
+   * If this function returns `undefined`, `getCategories()` function will be called to get initial categories.
+   **/
+  shouldLoad?: (
+    context: LoadContext
+  ) => Categories | void | Promise<Categories | void>
+
+  /**
+   * Fetch the categories which stamp every event. Called each time a new Hightouch event is dispatched.
+   * @example
+   * ```ts
+   * () => ({ "Advertising": true, "Analytics": false })
+   * ```
+   **/
+  getCategories: () => Categories | Promise<Categories>
+
+  /**
+   * Function to register a listener for consent changes to programatically send a "Hightouch Consent Preference" event to Hightouch when consent preferences change.
+   *
+   * #### Note: The callback requires the categories to be in the shape of { "C0001": true, "C0002": false }, so some normalization may be needed.
+   * @example
+   * ```ts
+   * async (categoriesChangedCb) => {
+   *   await resolveWhen(() => window.MyCMP !== undefined, 500)
+   *   window.MyCMP.OnConsentChanged((event.detail) => categoriesChangedCb(normalizeCategories(event.detail))
+   * }
+   *
+   * /* event payload
+   * {
+   *  "type": "track",
+   *  "event": "Hightouch Consent Preference",
+   *  "context": {
+   *    "consent": {
+   *      "version": 2,
+   *      "categoryPreferences" : {
+   *         "C0001": true,
+   *         "C0002": false,
+   *    }
+   *  }
+   * ..
+   * ```
+   */
+  registerOnConsentChanged?: RegisterOnConsentChangedFunction
+
+  /**
+   * This permanently disables any consent requirement (i.e device mode gating, event pref stamping).
+   * Called on wrapper initialization. **shouldLoad will never be called**
+   **/
+  shouldDisableConsentRequirement?: () => boolean | Promise<boolean>
+
+  /**
+   * Disable the HtEvents SDK completely. htevents.load() will have no effect.
+   * .track / .identify etc calls should not throw any errors, but analytics settings will never be fetched and no events will be sent to Hightouch.
+   * Called on wrapper initialization. This can be useful in dev environments (e.g. 'devMode').
+   * **shouldLoad will never be called**
+   **/
+  shouldDisableHightouch?: () => boolean | Promise<boolean>
+
+  /**
+   * Object that maps `integrationName -> categories`. Typically, this is not needed, as this data comes from the CDN and is attached to each integration.
+   * However, it may be desirable to hardcode these mappings (e.g, for testing).
+   * @example
+   * {"Braze Web Mode (Actions)": ["Advertising", "Analytics"]
+   */
+  integrationCategoryMappings?: IntegrationCategoryMappings
+
+  /**
+   * Predicate function to override default logic around whether or not to load an integration. By default, consent requires a user to have all categories enabled for a given integration.
+   * @example
+   * ```ts
+   * // Always disable a particular plugin
+   * const shouldEnableIntegration = (integrationCategories, categories, { creationName }) => {
+   *    if (creationName === 'FullStory') return false
+   *    if (!integrationCategories.length) return true
+   *    return integrationCategories.every((c) => categories[c])
+   * }
+   * ```
+   */
+  shouldEnableIntegration?: (
+    integrationCategories: string[],
+    categories: Categories,
+    integrationInfo: Pick<CDNSettingsRemotePlugin, 'creationName'>
+  ) => boolean
+
+  /**
+   * Prune consent categories from the `context.consent.categoryPreferences` payload if that category is not mapped to any integration in your Hightouch.io source.
+   * This is helpful if you want to save on bytes sent to Hightouch and do need the complete list of CMP's categories for debugging or other reasons.
+   * By default, all consent categories returned by `getCategories()` are sent to Hightouch.
+   * @default false
+   * ### Example Behavior
+   * You have the following categories mappings defined:
+   * ```
+   * FullStory -> 'CAT002',
+   * Braze -> 'CAT003'
+   * ```
+   * ```ts
+   * // pruneUnmappedCategories = false (default)
+   * { CAT0001: true, CAT0002: true, CAT0003: true }
+   * // pruneUnmappedCategories = true
+   * { CAT0002: true, CAT0003: true  } // pruneUnmappedCategories = true
+   * ```
+   */
+  pruneUnmappedCategories?: boolean
+}

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

@@ -0,0 +1,107 @@
+import type { CreateWrapperSettings } from './settings'
+
+export interface HtEventsBrowserSettings {
+  writeKey: string
+  cdnURL?: string
+  cdnSettings?: CDNSettings
+}
+
+/**
+ * 2nd arg to HtEventsBrowser.load / analytics
+ */
+export interface InitOptions {
+  updateCDNSettings(cdnSettings: CDNSettings): CDNSettings
+}
+
+/**
+ * This interface is a stub of the actual HtEvents instance.
+ * This can be either:
+ * - window.htevents (i.e `HtEventsSnippet`)
+ * - the instance returned by `HtEventsBrowser.load({...})`
+ * - the instance created by `new HtEventsBrowser(...)`
+ */
+export interface AnyAnalytics {
+  addSourceMiddleware(...args: any[]): any
+  on(event: 'initialize', callback: (cdnSettings: CDNSettings) => void): void
+  track(event: string, properties?: unknown, ...args: any[]): void
+
+  /**
+   * This interface is meant to be compatible with both the snippet (`window.htevents.load`)
+   * and the npm lib (`HtEventsBrowser.load`)
+   */
+  load(
+    writeKeyOrSettings: HtEventsBrowserSettings | string,
+    options?: InitOptions
+  ): void
+}
+
+/**
+ * This function modifies an analytics instance to add consent management.
+ * This is an analytics instance (either window.htevents, new HtEventsBrowser(), or the instance returned by `HtEventsBrowser.load({...})`
+ **/
+// Why type this as 'object' rather than 'AnyAnalytics'? IMO, the chance of a false positive is much higher than the chance that someone will pass in an object that is not an analytics instance.
+// We have an assertion function that throws an error if the analytics instance is not compatible.
+export type Wrapper<Analytics extends AnyAnalytics> = (
+  analyticsInstance: Analytics
+) => Analytics
+
+/**
+ * Create a function which wraps analytics instances to add consent management.
+ */
+export type CreateWrapper<Analytics extends AnyAnalytics> = (
+  settings: CreateWrapperSettings
+) => Wrapper<Analytics>
+
+export interface Categories {
+  [category: string]: boolean
+}
+
+export interface IntegrationCategoryMappings {
+  [integrationName: string]: string[]
+}
+
+export interface CDNSettings {
+  integrations: CDNSettingsIntegrations
+  remotePlugins?: CDNSettingsRemotePlugin[]
+  consentSettings?: {
+    // all unique categories keys
+    allCategories: string[]
+  }
+}
+
+/**
+ *CDN Settings Integrations object.
+ * @example
+ * { "Fullstory": {...}, "Braze Web Mode (Actions)": {...}}
+ */
+export interface CDNSettingsIntegrations {
+  [integrationName: string]: { [key: string]: any }
+}
+
+export interface CDNSettingsRemotePlugin {
+  /** The creation name of the remote plugin
+   * @example 'Actions Amplitude',
+   */
+  creationName: string
+  /** The name of the remote plugin
+   * @example 'Amplitude (Actions)'
+   */
+  name: string
+  /** The url of the javascript file to load
+   * @example https://cdn.hightouch-events.com/next-integrations/actions/amplitude-plugins/67621cf169443c119b.js
+   */
+  url: string
+  /** The UMD/global name the plugin uses. Plugins are expected to exist here with the `PluginFactory` method signature
+   * @example  'amplitude-pluginsDestination',
+   */
+  libraryName: string
+  /** The settings related to this plugin.
+   * @example
+   * ```js
+   * versionSettings: { componentTypes: [] },
+   * subscriptions: [{ id: 'nEx215jtwHt4kJmFXSmHMd', name: 'Browser Session Tracking'...}]
+   * ```
+   */
+  // using "any" here because otherwise this conflict with the JSONValue type inside of analytics-next, and we're not sharing types ATM.
+  settings: any
+}

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

@@ -0,0 +1,4 @@
+export * from './pipe'
+export * from './resolve-when'
+export * from './uniq'
+export * from './pick'

package/packages/consent/consent-tools/src/utils/pick.ts

@@ -0,0 +1,18 @@
+/**
+ * @example
+ * pick({ a: 1, b: 2, c: 3 }, ['a', 'c']) => { a: 1, c: 3 }
+ */
+export const pick = <
+  Obj extends Record<string, unknown>,
+  Key extends keyof Obj
+>(
+  obj: Obj,
+  keys: Key[]
+): Pick<Obj, Key> => {
+  return keys.reduce((acc, k) => {
+    if (k in obj) {
+      acc[k] = obj[k]
+    }
+    return acc
+  }, {} as Pick<Obj, Key>)
+}

package/packages/consent/consent-tools/src/utils/pipe.ts

@@ -0,0 +1,14 @@
+/**
+ * Everyday variadic pipe function (reverse of 'compose')
+ * @example pipe(fn1, fn2, fn3)(value) // fn3(fn2(fn1(value)))
+ */
+export const pipe = <T extends any[], U>(
+  fn: (...args: T) => U,
+  ...fns: ((a: U) => U)[]
+) => {
+  const piped = fns.reduce(
+    (prevFn, nextFn) => (value: U) => nextFn(prevFn(value)),
+    (value) => value
+  )
+  return (...args: T) => piped(fn(...args))
+}

package/packages/consent/consent-tools/src/utils/resolve-when.ts

@@ -0,0 +1,32 @@
+/**
+ *
+ * @param condition - predicate function that, if true, will cause the promise to resolve.
+ * @param delayMs - The frequency, in milliseconds (thousandths of a second), to check the condition.
+ * @example
+ * ```ts
+ * // check 'readyState' every 500ms
+ * await resolveWhen(() => document.readyState === 'complete', 500)
+ * ```
+ */
+export async function resolveWhen(
+  condition: () => boolean,
+  delayMs: number
+): Promise<void> {
+  return new Promise((resolve, _reject) => {
+    if (condition()) {
+      resolve()
+      return
+    }
+
+    const check = () =>
+      setTimeout(() => {
+        if (condition()) {
+          resolve()
+        } else {
+          check()
+        }
+      }, delayMs)
+
+    check()
+  })
+}

package/packages/consent/consent-tools/src/utils/uniq.ts

@@ -0,0 +1,4 @@
+/**
+ * This function removes duplicates from an array
+ */
+export const uniq = <T>(arr: T[]): T[] => Array.from(new Set(arr))

package/packages/consent/consent-tools/tsconfig.build.json

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

package/packages/consent/consent-tools/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "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",
+    "resolveJsonModule": true,
+    "isolatedModules": true // ensure we are friendly to build systems
+  }
+}

package/packages/consent/consent-wrapper-onetrust/.eslintrc.js

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

package/packages/consent/consent-wrapper-onetrust/.lintstagedrc.js

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

package/packages/consent/consent-wrapper-onetrust/LICENSE

@@ -0,0 +1,45 @@
+The MIT License (MIT)
+
+Copyright © 2023 Hightouch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---
+
+The MIT License (MIT)
+
+Copyright © 2023 Segment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/packages/consent/consent-wrapper-onetrust/README.md

@@ -0,0 +1,125 @@
+# @ht-sdks/events-sdk-js-consent-wrapper-onetrust
+
+### Try our Playground! [Next.js CodeSandbox](https://codesandbox.io/p/sandbox/focused-bhaskara-jysqr5) 🚀
+
+<img src="img/onetrust-popup.jpg" width="500" />
+
+# Quick Start
+
+## Configure OneTrust + hightouch
+
+### Ensure that the OneTrust Banner SDK is loaded first
+
+```html
+<head>
+  <!-- This should be included before the hightouch snippet -->
+  <script
+    src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js"
+    type="text/javascript"
+    charset="UTF-8"
+    data-domain-script="0000-0000-000-test"
+  ></script>
+</head>
+```
+
+### Ensure that consent is enabled and that you have created your Integration -> Consent Category Mappings
+
+- Ensure that your integrations in the hightouch UI have consent enabled, and that they map to your Consent Category IDs (also called Cookie Group IDs or Cookie Consent IDs).
+  The IDs look like "C0001", "C0002"and are configurable in OneTrust
+  ![onetrust category ids](img/onetrust-cat-id.jpg)
+
+- Debugging: this library expects the [OneTrust Banner SDK](https://community.cookiepro.com/s/article/UUID-d8291f61-aa31-813a-ef16-3f6dec73d643?language=en_US) to be available in order interact with OneTrust. This library derives the group IDs that are active for the current user from the `window.OneTrustActiveGroups` object provided by the OneTrust SDK. [Read this for more information [community.cookiepro.com]](https://community.cookiepro.com/s/article/UUID-66bcaaf1-c7ca-5f32-6760-c75a1337c226?language=en_US).
+
+## For `npm` library users
+
+1. Install the package
+
+```sh
+# npm
+npm install @ht-sdks/events-sdk-js-consent-wrapper-onetrust
+
+# yarn
+yarn add @ht-sdks/events-sdk-js-consent-wrapper-onetrust
+
+# pnpm
+pnpm add @ht-sdks/events-sdk-js-consent-wrapper-onetrust
+```
+
+2. Initialize alongside analytics
+
+```ts
+import { withOneTrust } from '@ht-sdks/events-sdk-js-consent-wrapper-onetrust'
+import { HtEventsBrowser } from '@ht-sdks/events-sdk-js-browser'
+
+export const analytics = new HtEventsBrowser()
+
+withOneTrust(analytics).load({ writeKey: '<MY_WRITE_KEY'> })
+
+```
+
+## For snippet users (window.htevents)
+
+1. In your head
+
+```html
+<head>
+  <!-- Add OneTrust -->
+  <script
+    src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js"
+    type="text/javascript"
+    charset="UTF-8"
+    data-domain-script="YOUR-DOMAIN-SCRIPT-ID"
+  ></script>
+
+  <!-- Add OneTrust Consent Wrapper -->
+  <script src="https://cdn.jsdelivr.net/npm/@ht-sdks/events-sdk-js-consent-wrapper-onetrust@latest/dist/umd/analytics-onetrust.umd.js"></script>
+
+  <!--
+    Add / Modify hightouch Analytics Snippet
+    * Find and replace: analytics.load('<MY_WRITE_KEY'>) -> withOneTrust(analytics).load('<MY_WRITE_KEY'>)
+  -->
+  <script>
+    !function(){var htevents=window.htevents...
+    ....
+    withOneTrust(htevents).load('<MY_WRITE_KEY'>) // replace analytics.load()
+    ....
+  </script>
+</head>
+```
+
+#### ⚠️ Reminder: _you must modify_ `analytics.load('....')` from the original hightouch snippet. See markup comment in example above.
+
+## Other examples:
+
+> Note: Playgrounds are meant for experimentation / testing, and as such, may be a bit overly complicated.
+> We recommend you try to follcaow the documentation for best practice.
+
+- [Standalone playground](/examples/standalone-playground/pages/index-consent.html)
+
+## Environments
+
+### Build Artifacts
+
+- We build three versions of the library:
+
+1. `cjs` (CommonJS modules) - for npm library users
+2. `esm` (es6 modules) - for npm library users
+3. `umd` (bundle) - for snippet users (typically)
+
+### Browser Support
+
+- `cjs/esm` - Support modern JS syntax (ES2020). These are our npm library users, so we expect them to transpile this module themselves using something like babel/webpack if they need extra legacy browser support.
+
+- `umd` - Support back to IE11, but **do not** polyfill . See our docs on [supported browsers](https://hightouch.com/docs/connections/sources/catalog/libraries/website/javascript/supported-browsers).
+
+In order to get full ie11 support, you are expected to bring your own polyfills. e.g. adding the following to your script tag:
+
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/7.7.0/polyfill.min.js"></script>
+```
+
+or
+
+```html
+<script src="https://polyfill.io/v3/polyfill.min.js?features=es5,es2015,es2016,es2017,es2018,es2019,es2020&flags=gated"></script>
+```

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

@@ -0,0 +1,6 @@
+const { createJestTSConfig } = require('@internal/config')
+
+module.exports = createJestTSConfig(__dirname, {
+  testEnvironment: 'jsdom',
+  setupFilesAfterEnv: ['./jest.setup.js'],
+})

package/packages/consent/consent-wrapper-onetrust/jest.setup.js

@@ -0,0 +1,4 @@
+const fetch = require('node-fetch')
+
+// eslint-disable-next-line no-undef
+globalThis.fetch = fetch // polyfill fetch so nock will work correctly on node 18 (https://github.com/nock/nock/issues/2336)

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

@@ -0,0 +1,60 @@
+{
+  "name": "@ht-sdks/events-sdk-js-consent-wrapper-onetrust",
+  "version": "0.3.1",
+  "keywords": [],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": [
+    "./dist/umd/analytics-onetrust.umd.js"
+  ],
+  "jsdeliver": "./dist/umd/analytics-onetrust.umd.js",
+  "unpkg": "./dist/umd/analytics-onetrust.umd.js",
+  "files": [
+    "LICENSE",
+    "dist/",
+    "src/",
+    "!**/__tests__/**",
+    "!**/test-helpers/**",
+    "!*.tsbuildinfo"
+  ],
+  "scripts": {
+    ".": "yarn run -T turbo run --filter=@ht-sdks/events-sdk-js-consent-wrapper-onetrust...",
+    "test": "yarn jest",
+    "lint": "yarn concurrently 'yarn:eslint .' 'yarn:tsc --noEmit'",
+    "build": "rm -rf dist && yarn concurrently 'yarn:build:*'",
+    "build:esm": "yarn tsc -p tsconfig.build.json",
+    "build:cjs": "yarn tsc -p tsconfig.build.json --outDir ./dist/cjs --module commonjs",
+    "build:bundle": "NODE_ENV=production yarn run webpack",
+    "build:bundle-dev": "NODE_ENV=development yarn run webpack",
+    "watch": "yarn concurrently 'yarn build:bundle-dev --watch' 'yarn build:esm --watch'",
+    "watch:test": "yarn test --watch",
+    "tsc": "yarn run -T tsc",
+    "eslint": "yarn run -T eslint",
+    "concurrently": "yarn run -T concurrently --raw",
+    "jest": "yarn run -T jest",
+    "webpack": "yarn run -T webpack"
+  },
+  "dependencies": {
+    "@ht-sdks/events-sdk-js-consent-tools": "0.2.1"
+  },
+  "peerDependencies": {
+    "@ht-sdks/events-sdk-js-browser": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ht-sdks/events-sdk-js-browser": {
+      "optional": true
+    }
+  },
+  "packageManager": "yarn@3.4.1",
+  "license": "MIT",
+  "repository": {
+    "directory": "packages/consent/consent-wrapper-onetrust",
+    "type": "git",
+    "url": "https://github.com/ht-sdks/events-sdk-js-mono"
+  },
+  "devDependencies": {
+    "@internal/config-webpack": "workspace:^",
+    "@internal/test-helpers": "workspace:^"
+  }
+}