@thg-agentic/hyper-personalisation-web 0.0.0-stage → 3.17.1

package/src/consent.js

@@ -0,0 +1,604 @@
+/**
+ * Consent adapters: one small object per CMP, so the SDK never has to know which one a site runs.
+ *
+ *   { name, read(): ConsentState | null, subscribe(onChange): () => void, observesChanges?: boolean }
+ *
+ * `read()` returns null while the CMP has not answered. A ConsentState carries exactly the five
+ * purposes of schemas/common/consent-state.json, each true, false or null ("never asked").
+ *
+ * `observesChanges: true` promises that `subscribe` reports every change by itself. Without it the
+ * consent gate keeps re-reading the adapter every couple of seconds after the first answer, so a
+ * withdrawal is honoured within seconds even where nothing announces it.
+ */
+
+import { getCookie } from './context.js';
+import { DEFAULT_STORAGE_NAMES, storageName } from './storage-scope.js';
+
+/**
+ * The first-party cookie that carries the consent decision to server producers, unless the host
+ * names another: `storageNames.consent` on the SDK, `name` on forwardedConsent. Both sides of one
+ * domain must agree on it.
+ */
+export const DEFAULT_CONSENT_COOKIE = DEFAULT_STORAGE_NAMES.consent;
+
+/**
+ * Who decided whether an event may be collected: context.consent.basis (spec 1.5, ADR 0019).
+ * `visitor` is the visitor's own answer through a CMP, a banner or the forwarded cookie, where null
+ * is unanswered. `host` is the site's own decision, where a null purpose is no statement.
+ */
+export const CONSENT_BASIS = Object.freeze({
+	visitor: 'visitor',
+	host: 'host',
+});
+
+/**
+ * context.consent with no adapter: the host has settled the lawful basis itself, and says so, so a
+ * warehouse can tell it from a visitor who has not answered.
+ */
+export const hostConsent = () => ({ basis: CONSENT_BASIS.host });
+
+/** The request header that carries consent to the serving API, in the cookie's serialisation. */
+export const CONSENT_HEADER = 'hp-consent';
+
+export const CONSENT_PURPOSES = [
+	'analytics',
+	'marketing',
+	'personalisation',
+	'ad_user_data',
+	'ad_personalization',
+];
+
+const COOKIE_KEYS = {
+	analytics: 'a',
+	marketing: 'm',
+	personalisation: 'p',
+	ad_user_data: 'aud',
+	ad_personalization: 'adp',
+};
+
+const hasWindow = () => typeof window !== 'undefined';
+
+/**
+ * A cookie can change without any event a cookie-based adapter could hear, except through the
+ * Cookie Store API — which Firefox and Safari do not implement. Where it is missing, such an adapter
+ * cannot promise to observe a change, and the consent gate re-reads it instead.
+ */
+const cookieStoreAvailable = () =>
+	hasWindow() && typeof window.cookieStore?.addEventListener === 'function';
+
+const tri = (value) => (value === true ? true : value === false ? false : null);
+
+/** Coerce anything state-shaped to the five schema keys. Unknown keys never reach the wire. */
+export function normaliseConsentState(raw) {
+	if (!raw || typeof raw !== 'object') return null;
+	const state = {};
+	for (const purpose of CONSENT_PURPOSES) state[purpose] = tri(raw[purpose]);
+	return state;
+}
+
+export function sameConsentState(a, b) {
+	if (!a || !b) return a === b;
+	return CONSENT_PURPOSES.every((purpose) => a[purpose] === b[purpose]);
+}
+
+/**
+ * The `thg_hp_consent` cookie value: `a=1&m=0&p=1&aud=0&adp=0`, fixed key order, unknown purposes
+ * omitted. Byte-for-byte what analytics-java's ConsentCookie.format writes.
+ */
+export function formatConsentCookie(state) {
+	if (!state) return '';
+	const pairs = [];
+	for (const purpose of CONSENT_PURPOSES) {
+		const value = state[purpose];
+		if (value === true || value === false)
+			pairs.push(`${COOKIE_KEYS[purpose]}=${value ? 1 : 0}`);
+	}
+	return pairs.join('&');
+}
+
+/**
+ * Headers for a request to the serving API (recommendations, decisions, audiences, social proof):
+ * `hp-consent: a=1&p=0`, exactly the cookie's value. Serving personalises only when `p=1` is
+ * present, so an unanswered CMP sends an empty value and gets the non-personalised response.
+ */
+export function servingHeaders(state) {
+	return {
+		[CONSENT_HEADER]: formatConsentCookie(normaliseConsentState(state)),
+	};
+}
+
+/** Mirrors ConsentCookie.parse: never throws, a key seen twice with different values is unknown. */
+export function parseConsentCookie(value) {
+	const state = normaliseConsentState({});
+	if (value == null) return state;
+	let raw = String(value).trim();
+	if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"'))
+		raw = raw.slice(1, -1);
+	if (raw.includes('%')) {
+		try {
+			raw = decodeURIComponent(raw.replace(/\+/g, ' '));
+		} catch {
+			return state;
+		}
+	}
+	const byKey = Object.fromEntries(
+		Object.entries(COOKIE_KEYS).map(([purpose, key]) => [key, purpose]),
+	);
+	const conflicted = new Set();
+	for (const pair of raw.split('&')) {
+		const eq = pair.indexOf('=');
+		if (eq <= 0) continue;
+		const purpose = byKey[pair.slice(0, eq).trim()];
+		const flag = { 1: true, 0: false }[pair.slice(eq + 1).trim()] ?? null;
+		if (!purpose || flag === null || conflicted.has(purpose)) continue;
+		if (state[purpose] === null) state[purpose] = flag;
+		else if (state[purpose] !== flag) {
+			state[purpose] = null;
+			conflicted.add(purpose);
+		}
+	}
+	return state;
+}
+
+/**
+ * The adapter, reporting only the purposes the property asks for (`hp.consent.purposes` in its
+ * settings). A purpose it does not ask for is reported unanswered, which strict mode never treats as
+ * granted — so neither the event, nor the cookie, nor `hp-consent` claims a grant the property never
+ * sought. Analytics is always reported: it is what collection is gated on.
+ *
+ * @param {object} adapter
+ * @param {Partial<Record<string, boolean>>|null} purposes Absent: every purpose is reported.
+ */
+export function reportingPurposes(adapter, purposes) {
+	if (!purposes) return adapter;
+	const reported = (state) => {
+		if (!state) return state;
+		const out = { ...state };
+		for (const purpose of CONSENT_PURPOSES) {
+			if (purpose !== 'analytics' && purposes[purpose] !== true)
+				out[purpose] = null;
+		}
+		return out;
+	};
+	return {
+		name: adapter.name,
+		basis: adapter.basis,
+		read: () => reported(adapter.read()),
+		subscribe: (onChange) =>
+			adapter.subscribe((state) => onChange(reported(state))),
+		get observesChanges() {
+			return adapter.observesChanges;
+		},
+	};
+}
+
+/** ad_user_data and ad_personalization follow marketing unless a mapping names them. */
+function withAdSignals(state, explicit = {}) {
+	return {
+		...state,
+		ad_user_data: explicit.ad_user_data ?? state.marketing,
+		ad_personalization: explicit.ad_personalization ?? state.marketing,
+	};
+}
+
+/** A subscription whose callbacks stop the moment it is torn down, whatever the CMP does after. */
+function subscription(read, onChange) {
+	let active = true;
+	const notify = () => {
+		if (!active) return;
+		try {
+			const state = read();
+			if (state) onChange(state);
+		} catch {
+			/* a CMP callback must never throw into the CMP */
+		}
+	};
+	return { notify, stop: () => (active = false) };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Didomi
+// ---------------------------------------------------------------------------------------------
+
+const DIDOMI_PURPOSES = {
+	analytics: [
+		'analytics',
+		'measure_content_performance',
+		'audience_measurement',
+	],
+	marketing: [
+		'marketing',
+		'targeting',
+		'advertising',
+		'select_personalized_ads',
+		'create_ads_profile',
+	],
+	personalisation: [
+		'personalisation',
+		'personalization',
+		'select_personalized_content',
+		'create_content_profile',
+	],
+};
+
+/**
+ * Didomi custom purposes carry a per-notice suffix (`analytics-BNjaanaW`), so an id matches itself
+ * or itself plus `-<suffix>`.
+ */
+function didomiPurpose(purposes, ids) {
+	if (!ids?.length) return null;
+	let seen = false;
+	for (const [key, value] of Object.entries(purposes)) {
+		const id = String(value?.id ?? key).toLowerCase();
+		const matches = ids.some((want) => {
+			const w = String(want).toLowerCase();
+			return id === w || id.startsWith(`${w}-`);
+		});
+		if (!matches) continue;
+		seen = true;
+		if (value?.enabled === true) return true;
+	}
+	return seen ? false : null;
+}
+
+/**
+ * @param {{ purposes?: Partial<Record<'analytics'|'marketing'|'personalisation'|'ad_user_data'|'ad_personalization', string[]>> }} [options]
+ */
+export function didomiConsent(options = {}) {
+	const ids = { ...DIDOMI_PURPOSES, ...options.purposes };
+
+	function read() {
+		const didomi = hasWindow() ? window.Didomi : undefined;
+		if (!didomi?.getCurrentUserStatus) return null;
+		// Didomi fills `purposes` with defaults before the visitor answers, so a status that still has
+		// to be collected (or is partial) is "not answered", never a refusal.
+		if (didomi.shouldUserStatusBeCollected?.() !== false) return null;
+		if (didomi.isUserStatusPartial?.() === true) return null;
+		const purposes = didomi.getCurrentUserStatus()?.purposes;
+		if (!purposes || typeof purposes !== 'object') return null;
+
+		const pick = (purpose) => didomiPurpose(purposes, ids[purpose]);
+		return withAdSignals(
+			{
+				analytics: pick('analytics'),
+				marketing: pick('marketing'),
+				personalisation: pick('personalisation'),
+			},
+			{
+				ad_user_data: pick('ad_user_data'),
+				ad_personalization: pick('ad_personalization'),
+			},
+		);
+	}
+
+	return {
+		name: 'didomi',
+		read,
+		observesChanges: true,
+		subscribe(onChange) {
+			if (!hasWindow()) return () => {};
+			const sub = subscription(read, onChange);
+			const listener = { event: 'consent.changed', listener: sub.notify };
+			window.didomiEventListeners = window.didomiEventListeners || [];
+			window.didomiEventListeners.push(listener);
+			window.didomiOnReady = window.didomiOnReady || [];
+			// Once the SDK is up, pushes to its queues may no longer be read, so register directly too.
+			// Duplicate notifications are harmless: the SDK only acts on a state that differs.
+			window.didomiOnReady.push((didomi) => {
+				sub.notify();
+				(didomi ?? window.Didomi)?.on?.('consent.changed', sub.notify);
+			});
+			window.Didomi?.on?.('consent.changed', sub.notify);
+			return sub.stop;
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------------------------
+// OneTrust
+// ---------------------------------------------------------------------------------------------
+
+function parseFormCookie(value) {
+	const out = {};
+	if (!value) return out;
+	for (const pair of String(value).split('&')) {
+		const eq = pair.indexOf('=');
+		if (eq <= 0) continue;
+		let v = pair.slice(eq + 1).replace(/\+/g, ' ');
+		try {
+			v = decodeURIComponent(v);
+		} catch {
+			/* keep the raw value */
+		}
+		out[pair.slice(0, eq)] = v;
+	}
+	return out;
+}
+
+/**
+ * @param {{
+ *   groups?: Partial<Record<'analytics'|'marketing'|'personalisation'|'ad_user_data'|'ad_personalization', string>>,
+ *   impliedConsent?: boolean,
+ * }} [options]
+ *
+ * Answered means the visitor closed the banner (`OptanonAlertBoxClosed`, `IsAlertBoxClosed()`) or
+ * interacted with it (`interactionCount > 0`): OneTrust writes default groups before anyone clicks.
+ * `impliedConsent: true` accepts OneTrust's groups as soon as it has loaded, for sites whose
+ * geolocation rule is notice-only / opt-out; never set it for an opt-in (GDPR) audience.
+ * Global Privacy Control forces marketing and both ad signals to false: GPC is an opt-out of sale
+ * and sharing, which is what those purposes gate. It does not touch analytics.
+ */
+export function oneTrustConsent(options = {}) {
+	const groups = {
+		analytics: 'C0002',
+		personalisation: 'C0003',
+		marketing: 'C0004',
+		...options.groups,
+	};
+	const impliedConsent = options.impliedConsent === true;
+
+	function activeGroups() {
+		const live = hasWindow() ? window.OnetrustActiveGroups : undefined;
+		if (typeof live === 'string' && live.length) {
+			const active = new Set(
+				live
+					.split(',')
+					.map((g) => g.trim())
+					.filter(Boolean),
+			);
+			return (id) => active.has(id);
+		}
+		const cookie = parseFormCookie(getCookie('OptanonConsent'));
+		if (!cookie.groups) return null;
+		const flags = {};
+		for (const entry of cookie.groups.split(',')) {
+			const [id, flag] = entry.split(':');
+			if (id?.trim())
+				flags[id.trim()] = flag === '1' ? true : flag === '0' ? false : null;
+		}
+		return (id) => flags[id] ?? null;
+	}
+
+	function answered() {
+		if (getCookie('OptanonAlertBoxClosed')) return true;
+		try {
+			if (hasWindow() && window.OneTrust?.IsAlertBoxClosed?.() === true)
+				return true;
+		} catch {
+			/* fall through to the cookie */
+		}
+		const count = Number.parseInt(
+			parseFormCookie(getCookie('OptanonConsent')).interactionCount,
+			10,
+		);
+		if (count > 0) return true;
+		return (
+			impliedConsent &&
+			hasWindow() &&
+			(Boolean(window.OneTrust) ||
+				typeof window.OnetrustActiveGroups === 'string')
+		);
+	}
+
+	function read() {
+		if (!answered()) return null;
+		const isActive = activeGroups();
+		if (!isActive) return null;
+		const group = (purpose) =>
+			groups[purpose] ? isActive(groups[purpose]) : null;
+		const state = withAdSignals(
+			{
+				analytics: group('analytics'),
+				marketing: group('marketing'),
+				personalisation: group('personalisation'),
+			},
+			{
+				ad_user_data: group('ad_user_data'),
+				ad_personalization: group('ad_personalization'),
+			},
+		);
+		const cookie = parseFormCookie(getCookie('OptanonConsent'));
+		const gpc =
+			(typeof navigator !== 'undefined' &&
+				navigator.globalPrivacyControl === true) ||
+			cookie.isGpcEnabled === '1';
+		if (gpc) {
+			state.marketing = false;
+			state.ad_user_data = false;
+			state.ad_personalization = false;
+		}
+		return state;
+	}
+
+	return {
+		name: 'onetrust',
+		read,
+		observesChanges: true,
+		subscribe(onChange) {
+			if (!hasWindow()) return () => {};
+			const sub = subscription(read, onChange);
+			let hookedConsentChanged = false;
+			const hookOneTrust = () => {
+				if (hookedConsentChanged || !window.OneTrust?.OnConsentChanged) return;
+				hookedConsentChanged = true;
+				window.OneTrust.OnConsentChanged(sub.notify);
+			};
+
+			window.addEventListener('OneTrustGroupsUpdated', sub.notify);
+			const previous = window.OptanonWrapper;
+			window.OptanonWrapper = function optanonWrapper(...args) {
+				try {
+					if (typeof previous === 'function') previous.apply(this, args);
+				} finally {
+					hookOneTrust();
+					sub.notify();
+				}
+			};
+			hookOneTrust();
+
+			return () => {
+				sub.stop();
+				window.removeEventListener('OneTrustGroupsUpdated', sub.notify);
+			};
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------------------------
+// A site's own banner, read from a cookie
+// ---------------------------------------------------------------------------------------------
+
+/** Comma-separated accepted category ids. Empty means nothing was recorded, so unknown. */
+function parseCategoryList(raw) {
+	const ids = String(raw)
+		.split(',')
+		.map((id) => id.trim())
+		.filter(Boolean);
+	return ids.length ? new Set(ids) : null;
+}
+
+/**
+ * A banner that records the visitor's choice in a first-party cookie.
+ *
+ * @param {object} options
+ * @param {string} options.name Cookie name.
+ * @param {Partial<Record<'analytics'|'marketing'|'personalisation'|'ad_user_data'|'ad_personalization', string>>} options.categories
+ *   The cookie's category id for each purpose; `analytics` is required.
+ * @param {(raw: string) => Set<string>|null} [options.parse] Accepted category ids from the
+ *   (URL-decoded) cookie value, or null when it cannot be read. Default: comma-separated ids.
+ * @param {string} [options.refusedValue] A literal value meaning "rejected everything".
+ * @param {string} [options.source] context.consent.source. Default 'native'.
+ * @param {string} [options.changeEvent] Window event the banner dispatches after writing the cookie.
+ *   Default 'thg_hp_consent_change'.
+ *
+ * No cookie means the banner has not been answered. Cookie Store `change` events are also watched
+ * where the browser has them.
+ */
+export function cookieConsent(options) {
+	const {
+		name,
+		categories,
+		parse = parseCategoryList,
+		refusedValue,
+		source = 'native',
+		changeEvent = 'thg_hp_consent_change',
+	} = options ?? {};
+	if (typeof name !== 'string' || name === '') {
+		throw new Error(
+			'cookieConsent: `name` (the cookie your banner writes) is required',
+		);
+	}
+	if (!categories || typeof categories.analytics !== 'string') {
+		throw new Error(
+			'cookieConsent: `categories.analytics` (the category id that grants analytics) is required',
+		);
+	}
+
+	function read() {
+		const raw = getCookie(name);
+		if (raw == null) return null;
+		let accepted;
+		if (refusedValue !== undefined && raw === refusedValue)
+			accepted = new Set();
+		else {
+			try {
+				accepted = parse(raw);
+			} catch {
+				accepted = null;
+			}
+		}
+		if (!(accepted instanceof Set)) return null;
+		const has = (purpose) =>
+			categories[purpose] ? accepted.has(categories[purpose]) : null;
+		return withAdSignals(
+			{
+				analytics: has('analytics'),
+				marketing: has('marketing'),
+				personalisation: has('personalisation'),
+			},
+			{
+				ad_user_data: has('ad_user_data'),
+				ad_personalization: has('ad_personalization'),
+			},
+		);
+	}
+
+	return {
+		name: source,
+		read,
+		get observesChanges() {
+			return cookieStoreAvailable();
+		},
+		subscribe(onChange) {
+			if (!hasWindow()) return () => {};
+			const sub = subscription(read, onChange);
+			const onCookieChange = (event) => {
+				const touched = [...(event.changed ?? []), ...(event.deleted ?? [])];
+				if (touched.some((cookie) => cookie?.name === name)) sub.notify();
+			};
+			window.addEventListener(changeEvent, sub.notify);
+			window.cookieStore?.addEventListener?.('change', onCookieChange);
+			return () => {
+				sub.stop();
+				window.removeEventListener(changeEvent, sub.notify);
+				window.cookieStore?.removeEventListener?.('change', onCookieChange);
+			};
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------------------------
+// No CMP
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * For pages that run without the CMP — a separate checkout app, a subdomain, a microsite — on the
+ * same registrable domain as a page that has one. The SDK on the CMP page records the visitor's
+ * decision in the `thg_hp_consent` cookie (set `consentCookieDomain` there so it reaches here); this
+ * reads it back. No cookie, or no analytics answer in it, means not answered, never granted.
+ */
+export function forwardedConsent(options = {}) {
+	const name = options.name ?? storageName('consent');
+	const read = () => {
+		const raw = getCookie(name);
+		if (raw == null) return null;
+		const state = parseConsentCookie(raw);
+		return state.analytics == null ? null : state;
+	};
+	return {
+		name: 'forwarded',
+		read,
+		get observesChanges() {
+			return cookieStoreAvailable();
+		},
+		subscribe(onChange) {
+			if (!hasWindow()) return () => {};
+			const sub = subscription(read, onChange);
+			const onCookieChange = (event) => {
+				const touched = [...(event.changed ?? []), ...(event.deleted ?? [])];
+				if (touched.some((cookie) => cookie?.name === name)) sub.notify();
+			};
+			window.cookieStore?.addEventListener?.('change', onCookieChange);
+			return () => {
+				sub.stop();
+				window.cookieStore?.removeEventListener?.('change', onCookieChange);
+			};
+		},
+	};
+}
+
+/**
+ * For a site with no CMP where the integrator has decided the lawful basis, e.g.
+ * `staticConsent({ analytics: true })`. An explicit opt-in: never a default. The state is the host's,
+ * not a visitor's answer, so its events carry `basis: 'host'`.
+ */
+export function staticConsent(state) {
+	const fixed = normaliseConsentState(state);
+	return {
+		name: 'static',
+		basis: CONSENT_BASIS.host,
+		read: () => (fixed ? { ...fixed } : null),
+		observesChanges: true,
+		subscribe: () => () => {},
+	};
+}