@financial-times/cmp-client 2.2.1 → 2.2.3-alpha

package/README.md

@@ -1,6 +1,6 @@
 # CMP Client
 
-A package to help you add a CMP (currently provided by Sourcepoint) to your application.
+A client-side package to help you add a CMP (currently provided by Sourcepoint) to your application.
 
 ## Installation
 
@@ -24,64 +24,120 @@ Visit https://localhost:5173 (see setup details in `src/examples/cmp-client`) to
 
 ```js
 import { initSourcepointCmp } from "@financial-times/cmp-client/client";
-import { FT_DOTCOM_LOCAL } from "@financial-times/cmp-client/properties";
+import { FT_DOTCOM_TEST } from "@financial-times/cmp-client/properties";
 
 // we suggest using a feature flag to disable the existing cookie banner and enable the new one
 if (flagsClient.get("adsDisableInternalCMP")) {
   initSourcepointCmp({
-    propertyConfig: FT_DOTCOM_LOCAL,
-    // useConsentStore: false (set to false e.g for non-FT.com properties or websites)
+    propertyConfig: FT_DOTCOM_TEST,
+    // useConsentStore: false (set to false for non-FT.com properties or websites)
   });
 }
 ```
 
-We will be adding new properties and their configs as we start rolling out. Please reach out to the Ads & Privacy team if you think you need to create a new property for your domain e.g it is on a different domain from the `ft.com` domain
+We will be adding new properties (websites under FT group) and their configs as we start rolling out. Please reach out to the Ads & Privacy team if you think you need to create a new property for your domain - for example, if it is on a different domain from the `ft.com` domain.
 
 ### CMP configuration options:
 
-| Option                               | Description                                                                                                                                                                                                                                       |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `propertyConfig` (SourcepointConfig) | This config object is directly passed to Sourcepoint (our external CMP) and presets (imported like example usage) will be made available for different properties/titles under the FT group. This currently defaults to the FT_DOTCOM_PROD preset |
-| `userId` (string)                    | Please provide a userId if the user is a logged in user. If your app uses the FT Secure Session token, you can leave empty and set `useFTSession` to true instead. Defaults to `undefined` for anonymous users                                    |
-| `useFTSession` (boolean)             | Set this flag if you want the user's Id to be automatically derived from their FT Secure Session . Defaults to `true`                                                                                                                             |
-| `consentProxyHost` (string)          | The fully qualified domain name for your consent proxy instance e.g `https://consent.thebanker.com`. Defaults to `https://consent.ft.com`                                                                                                         |
-| `cookieDomain` (string)              | The domain (and subdomains) that the FTConsent cookie will apply to e.g `.thebanker.com`. Defaults to `.ft.com`                                                                                                                                   |
-| `formOfWordsId` (string)             | The IAB custom categories that you have adapted might be tracked under a different FOW ID. At the moment, all custom categories are tracked under the `sourcepointCmp` form-of-words and its ID is default value                                  |
-| `useConsentStore` (boolean)          | Specifies whether the user's consent record should also be backed by the Single Consent Store. Properties like Specialist titles will need to explicitly set this to `false` as `true` is the default behavior                                    |
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Description</th>
+    </tr>
+  <thead/>
+  <tbody>
+    <tr>
+      <td><code>propertyConfig</code> (SourcepointConfig)</td>
+      <td>This config object is directly passed to Sourcepoint (our external CMP) and presets (imported like example usage) will be made available for different properties/titles under the FT group. This currently defaults to the <code>FT_DOTCOM_PROD</code> preset</td>
+    </tr>
+    <tr>
+      <td><code>userId</code> (string)</td>
+      <td>Please provide a userId if the user is a logged in user. If your app uses the FT Secure Session token, you can leave empty and set <code>useFTSession</code> to true instead. Defaults to <code>undefined</code> for anonymous users</td>
+    </tr>
+    <tr>
+      <td><code>useFTSession</code> (boolean)</td>
+      <td>Set this flag if you want the user's Id to be automatically derived from their FT Secure Session. Set to <code>false</code> if your app doesn't use FT Secure Session. Defaults to <code>true</code></td>
+    </tr>
+    <tr>
+      <td><code>consentProxyHost</code> (string)</td>
+      <td>The fully qualified domain name for your consent proxy instance e.g <code>https://consent.thebanker.com</code>. Defaults to <code>https://consent.ft.com</code></td>
+    </tr>
+    <tr>
+      <td><code>cookieDomain</code> (string)</td>
+      <td>The domain (and subdomains) that the FTConsent cookie will apply to e.g <code>.thebanker.com</code>. Defaults to <code>.ft.com</code></td>
+    </tr>
+    <tr>
+      <td><code>formOfWordsId</code> (string)</td>
+      <td>The IAB custom categories that you have adapted might be tracked under a different FOW ID. At the moment, all custom categories are tracked under the <code>sourcepointCmp</code> form-of-words and it defaults to <code>sourcepointCmp/VngD.XycZut.595cp9fWdp5XYP9vlFvk</code>. Properties using the consent banner as presented should use the default value</td>
+    </tr>
+    <tr>
+      <td><code>useConsentStore</code> (boolean)</td>
+      <td>Specifies whether the user's consent record should also be backed by the Single Consent Store. Properties like Specialist titles will need to explicitly set this to <code>false</code> as <code>true</code> is the default behavior</td>
+    </tr>
+    <tr>
+      <td><code>events</code> (object)</td>
+      <td>Used internally to define handlers for events emitted by the Vendor-supplied CMP module. See notes on "Responding to CMP events" below for details on how to define custom event handlers</td>
+    </tr>
+  </tbody>
+<table/>
+
+## Responding to CMP events
+
+If you need to do additional work in response to events emitted by the CMP Vendor module you can do so via the `window._sp_.addEventListener` method:
 
-### Available Properties (constantly being updated)
-
-| Property Key      | Details                                                                                                             |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `FT_DOTCOM_LOCAL` | Configuration preset for all properties on FT.com domain operating in a local environment - `https://local.ft.com`  |
-| `FT_DOTCOM_PROD`  | Configuration preset for all properties on FT.com domain operating in a production environment - `https://*.ft.com` |
+```js
+window._sp_.addEventListener("onMessageReady", (messageType) => {... });
+window._sp_.addEventListener("onConsentReady", (legislation, consentUUID, consentString, consentMeta) => { ... });
+```
 
-## Consent Banner scripts only
+> [!Note]
+> The `onConsentReady` event is fired
+>
+> 1. As soon as the CMP has finished loading and the user's consent choices are available
+> 1. Subsequently, whenever the user's consent choices change
 
-If you only want the scripts to setup the consent banner for your page with interacting without interacting with the FT's consent APIs, the package also exposes a `getCmpScripts` method, which returns a `DocumentFragment` containing block of scripts that you can to your page's `<head>` element.
+See the [Sourcepoint docs](https://docs.sourcepoint.com/hc/en-us/articles/4412176150035-Queue-event-callbacks) for a full listing of the events you can listen for and the arguments passed to the callbacks.
 
-```js
-import { getCmpScripts } from "@financial-times/cmp-client/client";
-import { FT_DOTCOM_LOCAL } from "@financial-times/cmp-client/properties";
+### Available Properties (constantly being updated)
 
-const cmpScripts = getCmpScripts(FT_DOTCOM_LOCAL);
-document.head.appendChild(cmpScripts);
-```
+<table>
+  <thead>
+    <tr>
+      <th>Property Key</th>
+      <th>Details</th>
+    </tr>
+  <thead/>
+  <tbody>
+    <tr>
+      <td><code>FT_DOTCOM_TEST</code></td>
+      <td>
+        <p>Use this configuration preset for testing the CMP on a property that has not yet been registered in the Sourcepoint portal.</p>
+        <p>All <code>*.ft.com</code> are currently registered and this config will spoof your request as coming from <code>https://local.ft.com</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>FT_DOTCOM_PROD</code></td>
+      <td>Configuration preset for all properties on FT.com domain operating in a production environment - <code>https://*.ft.com</code></td>
+    </tr>
+  </tbody>
+<table/>
 
 ## Debugging
 
-You can verify that the CMP is correctly configured by adding an `events` map to your configuration: the `debug` module used in the examples provides a sample implementation:
+You can verify that the CMP is correctly configured with the `debug` module, as deomstrated in [the CMP Client example](src/examples/src/scripts/cmp-client.ts):
 
 ```js
-import { getCmpScripts } from "@financial-times/cmp-client/client";
-import { ft } from "@financial-times/cmp-client/properties";
-import { events } from "@financial-times/cmp-client/debug";
+import { debug } from "@financial-times/cmp-client";
 
-// Merge the events map into the domain configuration
-const config = { ...ft, events };
-document.head.appendChild(getCmpScripts(config));
+debug.logCmpEvents();
 ```
 
 If everything's working then when running the demo app you'll see the CMP log its lifecycle events to the console, _even if its UI isn't displayed_.
 
 This can easily happen when you've made a previous consent choice and the CMP is now picking it up from local storage. We recommend running in an incognito window during development.
+
+## How it works
+
+The overview of how the CMP client works is diagrammatically [presented here](https://financialtimes.atlassian.net/wiki/spaces/ADS/pages/8151990292/New+Consent+Migration+Guide+for+teams#What-happens-when-a-user-visits-%5BinlineCard%5D--in-the-new-consent-framework%3F)

package/dist/index.cjs

@@ -7,6 +7,87 @@ var __publicField = (obj, key, value) => {
 };
 var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r;
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const version = "2.2.3-alpha";
+const events = {
+  onMessageChoiceSelect: (...args) => {
+    console.log("[debug] onMessageChoiceSelect", args);
+  },
+  onMessageReady: (...args) => {
+    console.log("[debug] onMessageReady", args);
+  },
+  onMessageChoiceError: (...args) => {
+    console.log("[debug] onMessageChoiceError", args);
+  },
+  onPrivacyManagerAction: (...args) => {
+    console.log("[debug] onPrivacyManagerAction", args);
+  },
+  onPMCancel: (...args) => {
+    console.log("[debug] onPMCancel", args);
+  },
+  onMessageReceiveData: (...args) => {
+    console.log("[debug] onMessageReceiveData", args);
+  },
+  onSPPMObjectReady: (...args) => {
+    console.log("[debug] onSPPMObjectReady", args);
+  },
+  onConsentReady: async (...args) => {
+    const [legislation2, consentUUID, consentString, consentMeta] = args;
+    console.log("[debug] onConsentReady", { legislation: legislation2, consentString, consentMeta, consentUUID });
+  },
+  onError: (...args) => {
+    console.log("[debug] onError", args);
+  }
+};
+function logCmpEvents() {
+  window._sp_queue = window._sp_queue ?? [];
+  window._sp_queue.push(() => {
+    var _a2, _b2;
+    for (const [eventId, eventHandler] of Object.entries(events)) {
+      (_b2 = (_a2 = window._sp_).addEventListener) == null ? void 0 : _b2.call(_a2, eventId, eventHandler);
+    }
+  });
+}
+const debug = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  events,
+  logCmpEvents
+}, Symbol.toStringTag, { value: "Module" }));
+const defaults = {
+  joinHref: true,
+  gdpr: {},
+  ccpa: {}
+};
+const FT_DOTCOM_TEST = {
+  ...defaults,
+  accountId: 1906,
+  baseEndpoint: "https://consent-manager.ft.com",
+  propertyHref: "https://local.ft.com"
+};
+const FT_DOTCOM_PROD = {
+  ...defaults,
+  accountId: 1906,
+  baseEndpoint: "https://consent-manager.ft.com",
+  propertyId: 31642
+};
+const properties = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  FT_DOTCOM_PROD,
+  FT_DOTCOM_TEST
+}, Symbol.toStringTag, { value: "Module" }));
+function updateFooterLinkCMP() {
+  const cookieLink = document.querySelector(
+    "[href='https://www.ft.com/preferences/manage-cookies']"
+  );
+  if (cookieLink) {
+    cookieLink.href = "#";
+    cookieLink.setAttribute("onclick", "window._sp_.gdpr.loadPrivacyManagerModal(827767);");
+    cookieLink.dataset.cmpLink = "updated";
+    return true;
+  } else {
+    console.warn("CMP Footer Link was not found and not updated");
+    return false;
+  }
+}
 const request = (url, { credentials = "omit" } = {}) => {
   return fetch(`https://session-next.ft.com${url}`, {
     credentials,
@@ -113,30 +194,9 @@ const iabCustomCategories = {
     specialFeatures: []
   }
 };
-const defaults = {
-  joinHref: true,
-  gdpr: {},
-  ccpa: {}
-};
-const FT_DOTCOM_LOCAL = {
-  ...defaults,
-  accountId: 1906,
-  baseEndpoint: "https://consent-manager.ft.com",
-  propertyHref: "https://local.ft.com"
-};
-const FT_DOTCOM_PROD = {
-  ...defaults,
-  accountId: 1906,
-  baseEndpoint: "https://consent-manager.ft.com",
-  propertyId: 31642
-};
-const properties = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  FT_DOTCOM_LOCAL,
-  FT_DOTCOM_PROD
-}, Symbol.toStringTag, { value: "Module" }));
-function createContentScript(content) {
+function createContentScript(cmpScript, content) {
   const s = document.createElement("script");
+  s.dataset.cmpScript = cmpScript;
   s.innerHTML = content;
   return s;
 }
@@ -145,47 +205,25 @@ function createSourceScript(src) {
   s.src = src;
   return s;
 }
-function encodeConfig(obj) {
-  let str = "";
-  if (!obj)
-    return str;
-  for (const [key, val] of Object.entries(obj)) {
-    switch (typeof val) {
-      case "function":
-        str += `${key}:${val.toString().replace(/"/g, "'").replace(/\s/g, "")},`;
-        break;
-      case "string":
-        str += `${key}:"${val.replace(/"/g, "'").replace(/\s/g, "")}",`;
-        break;
-      case "object":
-        str += `${key}:{${encodeConfig(val)}},`;
-        break;
-      default:
-        str += `${key}:${val},`;
-        break;
-    }
-  }
-  return str.slice(0, -1);
-}
-function getSPConfig(config) {
-  return `window._sp_queue=[];window._sp_={config:{${encodeConfig(config)}}}`;
-}
 const scriptSources = {
   cmpFrames: "https://consent-manager.ft.com/unified/wrapperMessagingWithoutDetection.js"
 };
 const scriptContent = {
-  getSPConfig,
   tcfStub: `"use strict";function _typeof(t){return(_typeof="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t})(t)}!function(){var t=function(){var t,e,o=[],n=window,r=n;for(;r;){try{if(r.frames.__tcfapiLocator){t=r;break}}catch(t){}if(r===n.top)break;r=r.parent}t||(!function t(){var e=n.document,o=!!n.frames.__tcfapiLocator;if(!o)if(e.body){var r=e.createElement("iframe");r.style.cssText="display:none",r.name="__tcfapiLocator",e.body.appendChild(r)}else setTimeout(t,5);return!o}(),n.__tcfapi=function(){for(var t=arguments.length,n=new Array(t),r=0;r<t;r++)n[r]=arguments[r];if(!n.length)return o;"setGdprApplies"===n[0]?n.length>3&&2===parseInt(n[1],10)&&"boolean"==typeof n[3]&&(e=n[3],"function"==typeof n[2]&&n[2]("set",!0)):"ping"===n[0]?"function"==typeof n[2]&&n[2]({gdprApplies:e,cmpLoaded:!1,cmpStatus:"stub"}):o.push(n)},n.addEventListener("message",(function(t){var e="string"==typeof t.data,o={};if(e)try{o=JSON.parse(t.data)}catch(t){}else o=t.data;var n="object"===_typeof(o)&&null!==o?o.__tcfapiCall:null;n&&window.__tcfapi(n.command,n.version,(function(o,r){var a={__tcfapiReturn:{returnValue:o,success:r,callId:n.callId}};t&&t.source&&t.source.postMessage&&t.source.postMessage(e?JSON.stringify(a):a,"*")}),n.parameter)}),!1))};"undefined"!=typeof module?module.exports=t:t()}();`,
   uspStub: `"use strict";(function () { var e = false; var c = window; var t = document; function r() { if (!c.frames["__uspapiLocator"]) { if (t.body) { var a = t.body; var e = t.createElement("iframe"); e.style.cssText = "display:none"; e.name = "__uspapiLocator"; a.appendChild(e) } else { setTimeout(r, 5) } } } r(); function p() { var a = arguments; __uspapi.a = __uspapi.a || []; if (!a.length) { return __uspapi.a } else if (a[0] === "ping") { a[2]({ gdprAppliesGlobally: e, cmpLoaded: false }, true) } else { __uspapi.a.push([].slice.apply(a)) } } function l(t) { var r = typeof t.data === "string"; try { var a = r ? JSON.parse(t.data) : t.data; if (a.__cmpCall) { var n = a.__cmpCall; c.__uspapi(n.command, n.parameter, function (a, e) { var c = { __cmpReturn: { returnValue: a, success: e, callId: n.callId } }; t.source.postMessage(r ? JSON.stringify(c) : c, "*") }) } } catch (a) { } } if (typeof __uspapi !== "function") { c.__uspapi = p; __uspapi.msgHandler = l; c.addEventListener("message", l, false) } })();`
 };
-function getCmpScripts(config) {
+function getCmpScripts() {
   const fragment = document.createDocumentFragment();
-  fragment.appendChild(createContentScript(scriptContent.tcfStub));
-  fragment.appendChild(createContentScript(scriptContent.uspStub));
-  fragment.appendChild(createContentScript(scriptContent.getSPConfig(config)));
+  fragment.appendChild(createContentScript("tcf", scriptContent.tcfStub));
+  fragment.appendChild(createContentScript("usp", scriptContent.uspStub));
   fragment.appendChild(createSourceScript(scriptSources.cmpFrames));
   return fragment;
 }
+function bootstrapCmp(config) {
+  window._sp_ = { config };
+  window._sp_queue ?? (window._sp_queue = []);
+  document.head.appendChild(getCmpScripts());
+}
 function getConsentPayload(parsedConsent, { shouldUpdateConsentStore, formOfWordsId, cookieDomain }) {
   const categoryNames = Object.keys(parsedConsent);
   const data = categoryNames.reduce(
@@ -203,7 +241,7 @@ function getConsentPayload(parsedConsent, { shouldUpdateConsentStore, formOfWord
     {}
   );
   if (!shouldUpdateConsentStore) {
-    return { data };
+    return { data, cookieDomain };
   } else {
     return {
       setConsentCookie: true,
@@ -1247,7 +1285,7 @@ class VendorVectorEncoder {
     }
     return retrString;
   }
-  static decode(value, version) {
+  static decode(value, version2) {
     let vector;
     let index = 0;
     const maxId = IntEncoder.decode(value.substr(index, BitLength.maxId), BitLength.maxId);
@@ -1256,7 +1294,7 @@ class VendorVectorEncoder {
     index += BitLength.encodingType;
     if (encodingType === VectorEncodingType.RANGE) {
       vector = new Vector();
-      if (version === 1) {
+      if (version2 === 1) {
         if (value.substr(index, 1) === "1") {
           throw new DecodingError("Unable to decode default consent=1");
         }
@@ -1721,12 +1759,12 @@ const _GVL = class _GVL extends Cloneable {
         throw new GVLError("must specify GVL.baseUrl before loading GVL json");
       }
       if (versionOrVendorList > 0) {
-        const version = versionOrVendorList;
-        if (_GVL.CACHE.has(version)) {
-          this.populate(_GVL.CACHE.get(version));
+        const version2 = versionOrVendorList;
+        if (_GVL.CACHE.has(version2)) {
+          this.populate(_GVL.CACHE.get(version2));
           this.readyPromise = Promise.resolve();
         } else {
-          url += _GVL.versionedFilename.replace("[VERSION]", String(version));
+          url += _GVL.versionedFilename.replace("[VERSION]", String(version2));
           this.readyPromise = this.fetchJson(url);
         }
       } else {
@@ -2800,7 +2838,7 @@ async function saveConsent(consentEndpoint, payload) {
 }
 function consentReadyHandlerFn(props) {
   const { userId, consentProxyHost, cookieDomain, formOfWordsId, useConsentStore } = props;
-  return async function consentReadyHandler(legislation2, _, consentString, consentMeta) {
+  return async function consentReadyHandler(legislation2, _consentUUID, consentString, consentMeta) {
     const activeLegislation = consentMeta.applies ? legislation2 : "gdpr";
     if (activeLegislation !== legislation2 || !consentString) {
       return;
@@ -2837,6 +2875,7 @@ async function initSourcepointCmp({
   formOfWordsId = SOURCEPOINT_FOW_ID,
   useConsentStore = true
 } = {}) {
+  var _a2;
   if (!userId && useFTSession) {
     try {
       const response = await getUuid();
@@ -2851,70 +2890,23 @@ async function initSourcepointCmp({
   if (userId) {
     propertyConfig.authId = userId;
   }
-  const scripts = getCmpScripts(propertyConfig);
-  document.head.appendChild(scripts);
-  window._sp_queue.push(() => {
-    window._sp_.addEventListener(
-      "onConsentReady",
-      consentReadyHandlerFn({
-        userId,
-        consentProxyHost,
-        cookieDomain,
-        formOfWordsId,
-        useConsentStore
-      })
-    );
-  });
-}
-const events = {
-  onMessageChoiceSelect: (...args) => {
-    console.log("[event] onMessageChoiceSelect", args);
-  },
-  onMessageReady: (...args) => {
-    console.log("[event] onMessageReady", args);
-  },
-  onMessageChoiceError: (...args) => {
-    console.log("[event] onMessageChoiceError", args);
-  },
-  onPrivacyManagerAction: (...args) => {
-    console.log("[event] onPrivacyManagerAction", args);
-  },
-  onPMCancel: (...args) => {
-    console.log("[event] onPMCancel", args);
-  },
-  onMessageReceiveData: (...args) => {
-    console.log("[event] onMessageReceiveData", args);
-  },
-  onSPPMObjectReady: (...args) => {
-    console.log("[event] onSPPMObjectReady", args);
-  },
-  onConsentReady: (...args) => {
-    console.log("[event] onConsentReady", args);
-  },
-  onError: (...args) => {
-    console.log("[event] onError", args);
-  }
-};
-const debug = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  events
-}, Symbol.toStringTag, { value: "Module" }));
-function updateFooterLinkCMP() {
-  const cookieLink = document.querySelector(
-    "[href='https://www.ft.com/preferences/manage-cookies']"
-  );
-  if (cookieLink) {
-    cookieLink.href = "#";
-    cookieLink.setAttribute("onclick", "window._sp_.gdpr.loadPrivacyManagerModal(827767);");
-    cookieLink.dataset.cmpLink = "updated";
-    return true;
-  } else {
-    console.warn("CMP Footer Link was not found and not updated");
-    return false;
+  if ((_a2 = propertyConfig.events) == null ? void 0 : _a2.onConsentReady) {
+    console.warn("[cmp-client] The supplied 'onConsentReady' event handler will be overwritten.");
   }
+  const events2 = {
+    ...propertyConfig.events ?? {},
+    onConsentReady: consentReadyHandlerFn({
+      userId,
+      consentProxyHost,
+      cookieDomain,
+      formOfWordsId,
+      useConsentStore
+    })
+  };
+  bootstrapCmp({ ...propertyConfig, events: events2 });
 }
+window.FT_CMP_CLIENT_VERSION = version;
 exports.debug = debug;
-exports.getCmpScripts = getCmpScripts;
 exports.initSourcepointCmp = initSourcepointCmp;
 exports.properties = properties;
 exports.updateFooterLinkCMP = updateFooterLinkCMP;