update API to 'withOneTrust'

segmentio · Aug 24, 2023 · f9afc77 · f9afc77
1 parent 03a6f32
commit f9afc77
Show file tree

Hide file tree

Showing 13 changed files with 57 additions and 29 deletions.
diff --git a/.changeset/angry-cows-compete.md b/.changeset/angry-cows-compete.md
@@ -0,0 +1,5 @@
+---
+'@segment/analytics-consent-wrapper-onetrust': minor
+---
+
+Change API from oneTrust(analytics) -> withOneTrust(analytics). Allow withOneTrust(analytics).load(...).
diff --git a/.changeset/heavy-boxes-grab.md b/.changeset/heavy-boxes-grab.md
@@ -0,0 +1,5 @@
+---
+'@segment/analytics-consent-tools': patch
+---
+
+have createWrapper return analytics instance to allow .load to be chained.
diff --git a/packages/consent/consent-tools-integration-tests/src/page-bundles/onetrust/index.ts b/packages/consent/consent-tools-integration-tests/src/page-bundles/onetrust/index.ts
@@ -1,9 +1,9 @@
 import { AnalyticsBrowser } from '@segment/analytics-next'
-import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust'
+import { withOneTrust } from '@segment/analytics-consent-wrapper-onetrust'
 
 export const analytics = new AnalyticsBrowser()
 
-oneTrust(analytics, {
+withOneTrust(analytics, {
   disableConsentChangedEvent: false,
   integrationCategoryMappings: {
     Fullstory: ['C0001'],

diff --git a/packages/consent/consent-tools-integration-tests/src/page-bundles/snippet/index.ts b/packages/consent/consent-tools-integration-tests/src/page-bundles/snippet/index.ts
@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-floating-promises */
-import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust'
+import { withOneTrust } from '@segment/analytics-consent-wrapper-onetrust'
 
-oneTrust(window.analytics, {
+withOneTrust(window.analytics, {
   integrationCategoryMappings: {
     Fullstory: ['C0001'],
     'Actions Amplitude': ['C0004'],

diff --git a/packages/consent/consent-tools/src/domain/__tests__/create-wrapper.test.ts b/packages/consent/consent-tools/src/domain/__tests__/create-wrapper.test.ts
@@ -117,6 +117,12 @@ describe(createWrapper, () => {
     expect(addSourceMiddlewareSpy).toBeCalledWith(expect.any(Function))
   })
 
+  it('should be chainable', async () => {
+    await wrapTestAnalytics().load(DEFAULT_LOAD_SETTINGS)
+    const { args } = getAnalyticsLoadLastCall()
+    expect(args.length).toBeTruthy()
+  })
+
   describe('shouldLoad', () => {
     describe('Throwing errors / aborting load', () => {
       const createShouldLoadThatThrows = (

diff --git a/packages/consent/consent-tools/src/domain/__tests__/typedef-tests.ts b/packages/consent/consent-tools/src/domain/__tests__/typedef-tests.ts
@@ -15,4 +15,7 @@ type Extends<T, U> = T extends U ? true : false
   const f: Extends<AnalyticsSnippet, AnyAnalytics> = true
   const g: Extends<AnalyticsBrowser, AnyAnalytics> = true
   console.log(f, g)
+
+  // should be chainable
+  wrap({} as AnalyticsBrowser).load({ writeKey: 'foo' })
 }
diff --git a/packages/consent/consent-tools/src/domain/create-wrapper.ts b/packages/consent/consent-tools/src/domain/create-wrapper.ts
@@ -160,6 +160,7 @@ export const createWrapper: CreateWrapper = (createWrapperOptions) => {
       })
     }
     analytics.load = loadWithConsent
+    return analytics
   }
 }
 

diff --git a/packages/consent/consent-tools/src/types/wrapper.ts b/packages/consent/consent-tools/src/types/wrapper.ts
@@ -41,7 +41,9 @@ export interface AnyAnalytics {
  **/
 // 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 = (analyticsInstance: object) => void
+export type Wrapper = <Analytics extends object>(
+  analyticsInstance: Analytics
+) => Analytics
 
 /**
  * Create a function which wraps analytics instances to add consent management.

diff --git a/packages/consent/consent-wrapper-onetrust/README.md b/packages/consent/consent-wrapper-onetrust/README.md
@@ -1,23 +1,30 @@
 This package is for the OneTrust integration for analytics consent
 
-
 # Quick Start
 
 ## Configure OneTrust + Segment
+
 ### Ensure that the OneTrust Banner SDK is loaded first
+
 ```html
 <head>
-<!-- This should be included before the Segment snippet -->
-  <script src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" type="text/javascript" charset="UTF-8"
-    data-domain-script="0000-0000-000-test"></script>
+  <!-- This should be included before the Segment 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 Segment 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 "CAT0001", "CAT0002"and are configurable in OneTrust
-![onetrust category ids](img/onetrust-cat-id.jpg)
+  The IDs look like "CAT0001", "CAT0002"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).
+- 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).
 
 ## Install dependency
 
@@ -34,17 +41,17 @@ yarn add @segment/analytics-consent-wrapper-onetrust
 - Use the following initialization code
 
 ```ts
-import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust'
+import { withOneTrust } from '@segment/analytics-consent-wrapper-onetrust'
 import { AnalyticsBrowser } from '@segment/analytics-next'
 
 export const analytics = new AnalyticsBrowser()
 
-oneTrust(analytics)
-analytics.load({ writeKey: '<MY_WRITE_KEY'> })
+withOneTrust(analytics).load({ writeKey: '<MY_WRITE_KEY'> })
 
 ```
 
 ## For snippet users (window.analytics) who _also_ use a bundler like webpack
+
 ### _NOTE:_ a pre-bundled version that can be loaded through a `<script>` is on the roadmap, but _not_ supported at this point
 
 - Install the dependency (see directions)
@@ -57,8 +64,7 @@ analytics.load({ writeKey: '<MY_WRITE_KEY'> })
 - Use the following initialization code
 
 ```ts
-import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust'
+import { withOneTrust } from '@segment/analytics-consent-wrapper-onetrust'
 
-oneTrust(window.analytics)
-window.analytics.load('<WRITE_KEY>')
+withOneTrust(window.analytics).load('<WRITE_KEY>')
 ```
diff --git a/packages/consent/consent-wrapper-onetrust/src/domain/__tests__/wrapper.test.ts b/packages/consent/consent-wrapper-onetrust/src/domain/__tests__/wrapper.test.ts
@@ -1,7 +1,7 @@
 import * as ConsentTools from '@segment/analytics-consent-tools'
 import * as OneTrustAPI from '../../lib/onetrust-api'
 import { sleep } from '@internal/test-helpers'
-import { oneTrust } from '../wrapper'
+import { withOneTrust } from '../wrapper'
 import { OneTrustMockGlobal, analyticsMock } from '../../test-helpers/mocks'
 
 const throwNotImplemented = (): never => {
@@ -69,7 +69,7 @@ describe('High level "integration" tests', () => {
     })
 
     it('should be resolved successfully', async () => {
-      oneTrust(analyticsMock)
+      withOneTrust(analyticsMock)
       OneTrustMockGlobal.GetDomainData.mockReturnValueOnce({
         Groups: [grpFixture.StrictlyNeccessary, grpFixture.Performance],
       })
@@ -92,7 +92,7 @@ describe('High level "integration" tests', () => {
 
   describe('getCategories', () => {
     it('should get categories successfully', async () => {
-      oneTrust(analyticsMock)
+      withOneTrust(analyticsMock)
       OneTrustMockGlobal.GetDomainData.mockReturnValue({
         Groups: [
           grpFixture.StrictlyNeccessary,
@@ -115,7 +115,7 @@ describe('High level "integration" tests', () => {
 
   describe('Consent changed', () => {
     it('should enable consent changed by default', async () => {
-      oneTrust(analyticsMock)
+      withOneTrust(analyticsMock)
       OneTrustMockGlobal.GetDomainData.mockReturnValue({
         Groups: [
           grpFixture.StrictlyNeccessary,

diff --git a/packages/consent/consent-wrapper-onetrust/src/domain/wrapper.ts b/packages/consent/consent-wrapper-onetrust/src/domain/wrapper.ts
@@ -21,11 +21,11 @@ export interface OneTrustSettings {
  * @param analyticsInstance - An analytics instance. Either `window.analytics`, or the instance returned by `new AnalyticsBrowser()` or `AnalyticsBrowser.load({...})`
  * @param settings - Optional settings for configuring your OneTrust wrapper
  */
-export const oneTrust = (
-  analyticsInstance: object, // typing this as 'object', rather than AnyAnalytics to avoid misc type mismatches. createWrapper will throw an error if the analytics instance is not compatible.
+export const withOneTrust = <Analytics extends object>(
+  analyticsInstance: Analytics, // typing this as 'object', rather than AnyAnalytics to avoid misc type mismatches. createWrapper will throw an error if the analytics instance is not compatible.
   settings: OneTrustSettings = {}
-) => {
-  createWrapper({
+): Analytics => {
+  return createWrapper({
     shouldLoad: async () => {
       await resolveWhen(() => {
         const oneTrustGlobal = getOneTrustGlobal()

diff --git a/packages/consent/consent-wrapper-onetrust/src/index.ts b/packages/consent/consent-wrapper-onetrust/src/index.ts
@@ -2,5 +2,5 @@
  * This is the public API for this package.
  * We avoid using splat (*) exports so that we can control what is exposed.
  */
-export { oneTrust } from './domain/wrapper'
+export { withOneTrust } from './domain/wrapper'
 export type { OneTrustSettings } from './domain/wrapper'
diff --git a/packages/consent/consent-wrapper-onetrust/src/standalone/index.ts b/packages/consent/consent-wrapper-onetrust/src/standalone/index.ts
@@ -1,4 +1,4 @@
-import { oneTrust } from '../index'
+import { withOneTrust } from '../index'
 
 /**
  * usage:
@@ -20,7 +20,7 @@ import { oneTrust } from '../index'
 
 // If we ever need to support an analytics instance that is renamed something else, we can add support for a custom attribute to the script tag.
 if ((window as any).analytics) {
-  oneTrust((window as any).analytics)
+  withOneTrust((window as any).analytics)
 } else {
   console.error(
     'Will not load OneTrust wrapper. window.analytics is not defined'