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

package/src/consent-gate.js

@@ -0,0 +1,324 @@
+/**
+ * Strict consent, independent of how events are delivered.
+ *
+ * Both delivery paths — the built-in transport and the analytics-next plugins — hand every event
+ * to one of these, so "what may be sent, and when" has a single implementation.
+ *
+ *   pending   CMP has not answered: items are held (in memory, or with a `store` in
+ *             sessionStorage too, so they survive a navigation)
+ *   granted   analytics === true: items pass
+ *   denied    analytics === false: items are dropped
+ *   unknown   timed out: still held, and the CMP is read more slowly until it answers
+ *
+ * Strict is the only mode. An unanswered CMP never becomes a grant, however long it takes; what is
+ * held leaves only on a grant, and is dropped on a refusal or when the page ends. A visitor who
+ * reads the banner for a minute before accepting keeps the page view that brought them here.
+ */
+
+import {
+	CONSENT_BASIS,
+	CONSENT_PURPOSES,
+	formatConsentCookie,
+	normaliseConsentState,
+	parseConsentCookie,
+	sameConsentState,
+} from './consent.js';
+import { getCookie } from './context.js';
+import { storageName } from './storage-scope.js';
+
+const CONSENT_COOKIE_MAX_AGE = 180 * 24 * 60 * 60;
+const POLL_MS = 100;
+const SLOW_POLL_MS = 1000;
+/**
+ * How often an answered page re-reads an adapter that cannot report changes itself: cookie-based
+ * adapters rely on the Cookie Store API, which Firefox and Safari lack, so a mid-page withdrawal is
+ * noticed within seconds. Only while the page is visible.
+ */
+const RECHECK_MS = 2000;
+/** What a page that never gets an answer may hold, so memory stays bounded; later items drop. */
+const MAX_HELD = 500;
+
+// Never the reason a server-rendering or test process stays alive; a no-op in browsers.
+const unref = (handle) => {
+	handle?.unref?.();
+	return handle;
+};
+
+export function consentAction(next, previous) {
+	if (previous?.analytics === true && next.analytics === false)
+		return 'withdrawn';
+	const known = CONSENT_PURPOSES.map((purpose) => next[purpose]).filter(
+		(v) => v !== null,
+	);
+	if (known.length && known.every(Boolean)) return 'accept_all';
+	if (known.length && known.every((v) => !v)) return 'reject_all';
+	return 'custom';
+}
+
+export function writeConsentCookie(
+	state,
+	domain,
+	name = storageName('consent'),
+) {
+	if (typeof document === 'undefined') return;
+	try {
+		const secure =
+			typeof location !== 'undefined' && location.protocol === 'https:'
+				? '; Secure'
+				: '';
+		const scope = domain ? `; Domain=${domain}` : '';
+		document.cookie =
+			`${name}=${formatConsentCookie(state)}; Path=/; Max-Age=${CONSENT_COOKIE_MAX_AGE}; SameSite=Lax` +
+			scope +
+			secure;
+	} catch {
+		/* a sandboxed document without cookie access */
+	}
+}
+
+/** The last decision this device reported, so a stored answer re-read on each page is not a change. */
+function previousFromCookie(name) {
+	const state = parseConsentCookie(getCookie(name));
+	return CONSENT_PURPOSES.some((purpose) => state[purpose] !== null)
+		? state
+		: null;
+}
+
+/**
+ * @param {object} options
+ * @param {{ name: string, read: () => object|null, subscribe?: (fn: (state: object) => void) => () => void }} options.adapter
+ * @param {number} [options.timeoutMs]
+ * @param {string} [options.cookieDomain]
+ * @param {string} [options.cookieName] Defaults to storageName('consent'), `thg_hp_consent`.
+ * @param {(item: any) => void} options.release   A held item may now be sent.
+ * @param {(item: any) => void} [options.discard] A held item will never be sent.
+ * @param {(update: { action: string, state: object, withdrawal: boolean }) => void} options.announce
+ *   Record a Consent Updated. Called only when analytics is granted, or for the withdrawal itself.
+ * @param {(status: string) => void} [options.onStatus]
+ * @param {boolean} [options.debug]
+ * @param {{ read: () => any[], write: (items: any[]) => void }} [options.store]
+ *   Carry held items across pages (`holdAcrossPages`). Read on start, so a grant on the next page
+ *   releases what the previous one held; cleared on a grant or a refusal, never at unload.
+ */
+export function createConsentGate(options) {
+	const {
+		adapter,
+		timeoutMs = 5000,
+		cookieDomain = null,
+		cookieName = storageName('consent'),
+		release,
+		announce,
+	} = options;
+	const discard = options.discard ?? (() => {});
+
+	let status = 'pending';
+	let state = null;
+	let poll = null;
+	let timer = null;
+	let recheck = null;
+	let stopped = false;
+	let unsubscribe = null;
+	const held = [];
+
+	const setStatus = (next) => {
+		status = next;
+		options.onStatus?.(next);
+	};
+
+	function read() {
+		try {
+			return normaliseConsentState(adapter.read());
+		} catch {
+			return null;
+		}
+	}
+
+	function stopWatching() {
+		if (poll) clearInterval(poll);
+		if (timer) clearTimeout(timer);
+		poll = null;
+		timer = null;
+	}
+
+	const hasDocument = () =>
+		typeof window !== 'undefined' && typeof document !== 'undefined';
+
+	/** An adapter that reports every change itself (a CMP event API) needs no re-reading. */
+	const observesChanges = () => {
+		try {
+			return (
+				typeof adapter.subscribe === 'function' &&
+				adapter.observesChanges === true
+			);
+		} catch {
+			return false;
+		}
+	};
+
+	function pauseRecheck() {
+		if (recheck) clearInterval(recheck);
+		recheck = null;
+	}
+
+	/** After the first answer: keep re-reading, slowly, while the page is visible. */
+	function resumeRecheck() {
+		if (stopped || recheck || state === null || observesChanges()) return;
+		if (hasDocument() && document.visibilityState === 'hidden') return;
+		recheck = unref(setInterval(() => apply(read()), RECHECK_MS));
+	}
+
+	const awaitingAnswer = () => status === 'pending' || status === 'unknown';
+	const store = options.store ?? null;
+	const releaseHeld = () => {
+		const items = held.splice(0);
+		store?.write([]);
+		for (const item of items) release(item);
+	};
+	const discardHeld = () => {
+		const items = held.splice(0);
+		store?.write([]);
+		for (const item of items) discard(item);
+	};
+
+	function apply(raw) {
+		const next = normaliseConsentState(raw);
+		// Gating is on analytics alone; a state that does not answer it is still "not answered".
+		if (!next || next.analytics === null) return;
+		const first = state === null;
+		const previous = first ? previousFromCookie(cookieName) : state;
+		if (!first && sameConsentState(previous, next)) return;
+
+		stopWatching();
+		state = next;
+		resumeRecheck();
+		writeConsentCookie(next, cookieDomain, cookieName);
+		const changed = !sameConsentState(previous, next);
+
+		if (next.analytics) {
+			setStatus('granted');
+			releaseHeld();
+			if (changed)
+				announce({
+					action: consentAction(next, previous),
+					state: next,
+					withdrawal: false,
+				});
+			return;
+		}
+
+		discardHeld();
+		// A withdrawal is recorded, then nothing more: the raw table is where a refusal is proven to
+		// have been received, and the warehouse's consent filter keeps it out of every model.
+		if (previous?.analytics === true)
+			announce({ action: 'withdrawn', state: next, withdrawal: true });
+		setStatus('denied');
+	}
+
+	function timedOut() {
+		timer = null;
+		if (status !== 'pending') return;
+		setStatus('unknown');
+		// Keep holding and keep listening, more slowly: a visitor who answers the banner a minute in
+		// still counts, landing page included.
+		if (poll) clearInterval(poll);
+		poll = unref(setInterval(() => apply(read()), SLOW_POLL_MS));
+	}
+
+	/**
+	 * Unload before an answer: nothing unconsented leaves.
+	 *
+	 * @param {{ type?: string, persisted?: boolean }} [event] The DOM event that hid the page.
+	 *
+	 * Only the end of the page discards: a hidden tab or a pagehide into the back/forward cache can
+	 * come back and be accepted. Held events are in memory only, so keeping them risks nothing.
+	 */
+	function onHidden(event) {
+		if (!awaitingAnswer()) return;
+		// With a store, the stored copy is what the next page answers for: the end of this one
+		// discards nothing.
+		if (store) return;
+		if (event?.type !== 'visibilitychange' && !event?.persisted) discardHeld();
+	}
+
+	const onVisibility = (event) => {
+		if (document.visibilityState === 'hidden') {
+			pauseRecheck();
+			onHidden(event);
+		} else {
+			resumeRecheck();
+		}
+	};
+
+	const onPageHide = (event) => {
+		pauseRecheck();
+		onHidden(event);
+	};
+
+	const onPageShow = () => resumeRecheck();
+
+	return {
+		get status() {
+			return status;
+		},
+		get state() {
+			return state ? { ...state } : null;
+		},
+		/** context.consent for an event collected now. An adapter is the visitor's answer unless it says otherwise. */
+		stamp() {
+			return state
+				? {
+						...state,
+						source: adapter.name ?? null,
+						basis: adapter.basis ?? CONSENT_BASIS.visitor,
+					}
+				: null;
+		},
+		admits() {
+			return status === 'granted';
+		},
+		/** Hold an item until the CMP answers. Returns false (and discards) once it has answered. */
+		hold(item) {
+			if (!awaitingAnswer() || held.length >= MAX_HELD) {
+				discard(item);
+				return false;
+			}
+			held.push(item);
+			store?.write(held);
+			return true;
+		},
+		/** Items unload would lose; the caller's own unload path flushes after this. */
+		onHidden,
+		start() {
+			stopped = false;
+			try {
+				unsubscribe = adapter.subscribe?.((next) => apply(next)) ?? null;
+			} catch (err) {
+				if (options.debug)
+					console.warn('[hp] consent adapter subscribe failed', err);
+			}
+			if (hasDocument()) {
+				window.addEventListener('pagehide', onPageHide);
+				window.addEventListener('pageshow', onPageShow);
+				document.addEventListener('visibilitychange', onVisibility);
+			}
+			// What an earlier page held for an answer it never got, oldest first.
+			if (store && held.length === 0)
+				held.push(...store.read().slice(-MAX_HELD));
+			apply(read());
+			if (state) return;
+			poll = unref(setInterval(() => apply(read()), POLL_MS));
+			timer = unref(setTimeout(timedOut, timeoutMs));
+		},
+		stop() {
+			stopped = true;
+			stopWatching();
+			pauseRecheck();
+			if (typeof unsubscribe === 'function') unsubscribe();
+			if (hasDocument()) {
+				window.removeEventListener('pagehide', onPageHide);
+				window.removeEventListener('pageshow', onPageShow);
+				document.removeEventListener('visibilitychange', onVisibility);
+			}
+		},
+	};
+}