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

package/src/bootstrap.js

@@ -0,0 +1,504 @@
+/**
+ * One call from a write key to a running client: remote settings, consent, identity, the page
+ * view, the dataLayer bridge and a once-per-session identify.
+ *
+ *   const hp = await bootstrap(
+ *     { writeKey: 'hp_pk_live_…' },
+ *     { consent: { provider: 'onetrust' }, identityCookies: { anonymousId: 'device_id' }, pageType: 'product' },
+ *   );
+ *
+ * The key is the whole config: `apiHost` is optional, for a first-party proxy (DEFAULT_API_HOST
+ * otherwise). Everything tenant-level comes from `GET {apiHost}/v1/projects/{writeKey}/settings`: whether the
+ * SDK is on, the property, the environment, the reported consent purposes, the query-param
+ * allowlist, where device ids come from, the tracking plan (which events are blocked), the sampling
+ * rate and debug logging. What only the page can know stays
+ * in code: the CMP, the session cookie's name (and, for a source whose settings name no device
+ * cookie, the device cookie's), the per-request currency / ship-to / locale getters, the preset,
+ * the page type, debug, and which property this page is for a key scoped to several.
+ *
+ * Resolves to the client, or null when the key is disabled or unknown, the settings cannot be
+ * fetched on a first visit, or the options are invalid. Never throws into the page, and is
+ * idempotent per page. createAnalytics() and connectDataLayer() remain the lower-level API.
+ */
+
+import { assignmentDecisionId, assignmentSession } from './assignment.js';
+import {
+	trackExposures,
+	trackProductLists,
+	trackPromotions,
+	trackRecommendationRails,
+} from './auto.js';
+import { createCarry } from './carry.js';
+import {
+	cookieConsent,
+	didomiConsent,
+	forwardedConsent,
+	oneTrustConsent,
+	parseConsentCookie,
+	reportingPurposes,
+	staticConsent,
+} from './consent.js';
+import { getCookie } from './context.js';
+import { connectDataLayer } from './datalayer.js';
+import { sessionDebug } from './debug.js';
+import { createAnalytics, normaliseSha256, PAGE_TYPES } from './index.js';
+import {
+	cachedSettings,
+	cacheSettings,
+	DISABLED,
+	fetchSettings,
+	forgetSettings,
+	readSettings,
+	resolveApiHost,
+} from './settings.js';
+import { realId, uuid } from './shape.js';
+import {
+	configureStorageNames,
+	migrateLegacyStorage,
+	storageKey,
+	storageName,
+} from './storage-scope.js';
+
+const INSTANCE = Symbol.for('@thg-agentic/hyper-personalisation-web.bootstrap');
+const DRAIN = Symbol.for('@thg-agentic/hyper-personalisation-web.drain');
+const CARRY = Symbol.for('@thg-agentic/hyper-personalisation-web.carry');
+const REPLAY = Symbol.for('@thg-agentic/hyper-personalisation-web.replay');
+/** Where bootstrap leaves `hp.assignmentDecisionId` its reader of the page's identity cookies. */
+const ASSIGNMENT = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.assignment',
+);
+/** Where bootstrap leaves `hp.recommendationContext` the started client's reader of the visit. */
+const RECOMMENDATION_CONTEXT = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.recommendation-context',
+);
+
+const cookie = (name) => (name ? () => getCookie(name) : () => null);
+
+const BUILT_IN_CONSENT = {
+	didomi: (o) => didomiConsent({ purposes: o.purposes }),
+	onetrust: (o) =>
+		oneTrustConsent({ groups: o.groups, impliedConsent: o.impliedConsent }),
+	cookie: (o) =>
+		cookieConsent({
+			name: o.name,
+			categories: o.categories,
+			refusedValue: o.refusedValue,
+			source: o.source,
+			changeEvent: o.changeEvent,
+		}),
+	// The page without a CMP reads the cookie the CMP page writes, so they share storageNames.consent.
+	forwarded: (o) => forwardedConsent({ name: o.name }),
+	static: (o) => {
+		if (!o.state || typeof o.state !== 'object')
+			throw new Error('consent.state is required for provider "static"');
+		return staticConsent(o.state);
+	},
+};
+
+const PROVIDERS = Object.keys(BUILT_IN_CONSENT);
+
+const isObject = (v) =>
+	v !== null && typeof v === 'object' && !Array.isArray(v);
+const isString = (v) => typeof v === 'string' && v !== '';
+const isStringArray = (v) =>
+	Array.isArray(v) && v.every((s) => typeof s === 'string');
+const isAdapter = (v) => isObject(v) && typeof v.read === 'function';
+
+/** Every reason the config and options cannot be used; empty when they can. */
+export function validateConfig(config, options = {}) {
+	const problems = [];
+	if (!isObject(config)) return ['config must be { writeKey, apiHost? }'];
+	if (!isString(config.writeKey)) problems.push('writeKey is required');
+	if (!resolveApiHost(config.apiHost))
+		problems.push('apiHost, when given, must be a host or an http(s) origin');
+	if (options.propertyId !== undefined && !isString(options.propertyId))
+		problems.push('propertyId must be a string');
+
+	const { consent } = options;
+	if (
+		!isAdapter(consent) &&
+		!(isObject(consent) && PROVIDERS.includes(consent.provider))
+	) {
+		problems.push(
+			`consent must be a consent adapter or { provider: ${PROVIDERS.join(' | ')} }`,
+		);
+	}
+	if (
+		options.autocapture !== undefined &&
+		options.autocapture !== false &&
+		!isObject(options.autocapture)
+	)
+		problems.push(
+			'autocapture must be false or { promotions, productLists, recommendations }',
+		);
+	if (
+		options.beforeSend !== undefined &&
+		typeof options.beforeSend !== 'function'
+	)
+		problems.push('beforeSend must be a function');
+	if (options.identityCookies !== undefined) {
+		if (!isObject(options.identityCookies))
+			problems.push('identityCookies must be an object');
+		else {
+			for (const key of ['anonymousId', 'sessionId']) {
+				const name = options.identityCookies[key];
+				if (name !== undefined && !isString(name))
+					problems.push(`identityCookies.${key} must be a cookie name`);
+			}
+		}
+	}
+	for (const key of ['getCurrency', 'getShipToCountry', 'getLocale']) {
+		if (options[key] !== undefined && typeof options[key] !== 'function')
+			problems.push(`${key} must be a function`);
+	}
+	if (options.dataLayer !== undefined) {
+		if (!isObject(options.dataLayer))
+			problems.push('dataLayer must be an object');
+		else {
+			if (
+				options.dataLayer.name !== undefined &&
+				!isString(options.dataLayer.name)
+			) {
+				problems.push('dataLayer.name must be a string');
+			}
+			if (
+				options.dataLayer.ignore !== undefined &&
+				!isStringArray(options.dataLayer.ignore)
+			) {
+				problems.push('dataLayer.ignore must be an array of strings');
+			}
+		}
+	}
+	return problems;
+}
+
+function consentAdapter(consent, settings, preset) {
+	if (isAdapter(consent))
+		return reportingPurposes(consent, settings.consentPurposes);
+	const { provider, ...options } = consent;
+	const factory = preset?.consent?.[provider] ?? BUILT_IN_CONSENT[provider];
+	return reportingPurposes(factory(options), settings.consentPurposes);
+}
+
+/** Who an identify named, as the session remembers it: `userId|email_sha256`. */
+const identifyMarker = (userId, email) => `${userId ?? ''}|${email ?? ''}`;
+
+/** The traits to identify with on this page, or null when this session already identified them. */
+function pendingIdentify(propertyId, identity) {
+	const userId = realId(identity?.userId);
+	const email = normaliseSha256(identity?.emailSha256);
+	if (!userId && !email) return null;
+
+	try {
+		const key = storageKey(storageName('identified'), propertyId);
+		if (sessionStorage.getItem(key) === identifyMarker(userId, email))
+			return null;
+	} catch {
+		/* no session storage: identify on every page rather than never */
+	}
+	return {
+		...(userId ? { userId } : {}),
+		...(email ? { email_sha256: email } : {}),
+	};
+}
+
+/**
+ * The settings to start this page with, and the answer to cache once analytics is granted.
+ *
+ * Inline settings (development, tests) are used as given and never fetched or cached. Otherwise a
+ * cached answer starts the page at once while the API is asked again for the next page; with no
+ * cache the page waits for the API, and `unreachable` says when it could not be asked.
+ */
+async function resolveSettings({ writeKey, apiHost }, options) {
+	if (options.settings !== undefined)
+		return { settings: readSettings(options.settings), revalidated: null };
+	const fetched = fetchSettings(apiHost, writeKey);
+	const cached = cachedSettings(writeKey);
+	if (cached) return { settings: cached, revalidated: fetched };
+	const answer = await fetched;
+	const settings = answer ?? DISABLED;
+	return {
+		settings,
+		revalidated: Promise.resolve(settings),
+		unreachable: answer === null,
+	};
+}
+
+/**
+ * @param {{ writeKey: string, apiHost?: string }} config
+ * @param {import('../types/bootstrap').BootstrapOptions} options See types/bootstrap.d.ts.
+ * @returns {Promise<object|null>} the client, or null when it is off.
+ */
+export function bootstrap(config, options = {}) {
+	const host = typeof window !== 'undefined' ? window : null;
+	if (host?.[INSTANCE]) return host[INSTANCE];
+	// What `hp` queued on an earlier page that navigated before its client started. Carried only as
+	// the held store is: once this device has granted analytics, or unanswered with holdAcrossPages.
+	const carry = createCarry(config?.writeKey, () => {
+		const { analytics } = parseConsentCookie(getCookie(storageName('consent')));
+		return (
+			analytics === true ||
+			(analytics === null && options.holdAcrossPages === true)
+		);
+	});
+	const started = start(config, options, carry);
+	if (host) {
+		// Known from the options alone, so it answers before the client has started: the session the
+		// events carry, else the visitor cookie, as the renderer forwards them to the assignment.
+		const session =
+			options.extend?.getSessionId ??
+			cookie(options.identityCookies?.sessionId);
+		const visitor = cookie(options.identityCookies?.anonymousId);
+		host[ASSIGNMENT] = ({ slot, arm } = {}) =>
+			assignmentDecisionId({
+				sessionId: assignmentSession(session(), visitor()),
+				slot,
+				arm,
+			});
+		host[INSTANCE] = started;
+		host[CARRY] = carry;
+		// Calls made through `hp` before this ran: that module, if the page loaded it, replays them.
+		host[DRAIN]?.(started);
+	}
+	return started;
+}
+
+/**
+ * When this document was navigated to: the wall clock less the time since, not `timeOrigin`, which
+ * browsers derive from a monotonic clock that drifts from the wall clock after a sleep.
+ */
+function navigatedAt() {
+	const since = globalThis.performance?.now?.();
+	return new Date(
+		Date.now() - (Number.isFinite(since) ? since : 0),
+	).toISOString();
+}
+
+/**
+ * The declarative trackers: they report only what the page tags (`data-hp-promotion`,
+ * `data-hp-list` / `data-hp-product`, `data-hp-reco-request`, `data-hp-exposure`), so they are on
+ * unless turned off.
+ * Returns what stops them.
+ */
+function startAutocapture(client, autocapture) {
+	if (autocapture === false) return () => {};
+	const on = {
+		promotions: true,
+		productLists: true,
+		recommendations: true,
+		exposures: true,
+		...autocapture,
+	};
+	const options = (value) => (value && typeof value === 'object' ? value : {});
+	const stops = [];
+	try {
+		if (on.promotions)
+			stops.push(trackPromotions(client, options(on.promotions)));
+		if (on.productLists)
+			stops.push(trackProductLists(client, options(on.productLists)));
+		if (on.recommendations)
+			stops.push(trackRecommendationRails(client, options(on.recommendations)));
+		if (on.exposures) stops.push(trackExposures(client, options(on.exposures)));
+	} catch (err) {
+		// A page the trackers cannot read still gets its explicit calls sent.
+		console.warn('[hp] autocapture not started:', err?.message ?? err);
+	}
+	return () => {
+		for (const stop of stops) stop();
+	};
+}
+
+/** This page is off: what `hp` queued on it is dropped rather than carried. */
+function off(carry) {
+	carry.close();
+	return null;
+}
+
+async function start(config, options, carry) {
+	try {
+		const problems = validateConfig(config, options);
+		if (problems.length) {
+			console.warn(
+				`[hp] not started, the configuration is invalid: ${problems.join('; ')}`,
+			);
+			return off(carry);
+		}
+		configureStorageNames(options.storageNames);
+		migrateLegacyStorage();
+
+		const { writeKey } = config;
+		// The visitor's identity may still be looking itself up; it is waited for alongside the
+		// settings, never before them. A lookup that fails leaves the visitor anonymous.
+		const [{ settings, revalidated, unreachable }, identity] =
+			await Promise.all([
+				resolveSettings(config, options),
+				Promise.resolve(options.identity).catch(() => null),
+			]);
+
+		// What to cache is the newest answer; when is the first grant. Either may come first.
+		let latest = revalidated ? settings : null;
+		let granted = false;
+		const keep = () => granted && latest && cacheSettings(writeKey, latest);
+		revalidated?.then((next) => {
+			if (!next) return;
+			latest = next;
+			if (next.enabled) keep();
+			else forgetSettings(writeKey);
+		});
+
+		// Unreachable, or left before the answer: what `hp` queued goes to the next page.
+		if (unreachable) return null;
+		if (!settings.enabled) {
+			if (options.debug)
+				console.info(
+					'[hp] off: the settings for this write key do not enable it',
+				);
+			return off(carry);
+		}
+		// A source scoped to one property names it; a source scoped to several leaves it to the page.
+		const propertyId = settings.propertyId ?? options.propertyId;
+		if (!propertyId) {
+			console.warn(
+				'[hp] not started: this write key covers several properties, so propertyId is required',
+			);
+			return off(carry);
+		}
+
+		const { preset } = options;
+		const identified = pendingIdentify(propertyId, identity);
+		// Settings from before 3.18, cached or served, have none of these: nothing sampled, no logging.
+		const debug =
+			options.debug === true ||
+			settings.debug?.enabled === true ||
+			sessionDebug(settings.debug?.tokenSha256 ?? null, storageName('debug'));
+		const userId = realId(identity?.userId);
+
+		const client = createAnalytics({
+			apiHost: settings.apiHost ?? resolveApiHost(config.apiHost),
+			writeKey,
+			propertyId,
+			// Known before the first page view, so an event the client sends while starting (the consent
+			// answer a returning visitor already gave) carries it too.
+			pageType: PAGE_TYPES.has(options.pageType) ? options.pageType : undefined,
+			environment: settings.environment,
+			queryParamAllowlist: settings.queryParamAllowlist ?? undefined,
+			plan: settings.plan,
+			sampleRate: settings.sampleRate ?? 1,
+			holdout: settings.holdouts?.[propertyId],
+			// Per request, never per tenant: a site can trade in several currencies and ship anywhere.
+			getCurrency: options.getCurrency,
+			getShipToCountry: options.getShipToCountry,
+			getLocale: options.getLocale,
+			consent: consentAdapter(options.consent, settings, preset),
+			consentCookieDomain: options.consentCookieDomain,
+			storageNames: options.storageNames,
+			holdAcrossPages: options.holdAcrossPages === true,
+			// Deprecated in 3.6 and ignored; passed on only so debug can say so.
+			mintAnonymousId: options.mintAnonymousId,
+			debug,
+			// Where device ids come from is the source's: with no setting (settings from before 3.6),
+			// the cookie named here, as before.
+			anonymousIdSource: settings.anonymousId ?? undefined,
+			getAnonymousId: cookie(options.identityCookies?.anonymousId),
+			// No session cookie named: the SDK keeps the session itself (3.15).
+			getSessionId: options.identityCookies?.sessionId
+				? cookie(options.identityCookies.sessionId)
+				: undefined,
+			// Every page carries the signed-in user; only the identify itself is once per session.
+			getUserId: () => userId,
+			beforeSend: options.beforeSend,
+			...options.extend,
+			onConsentStatus(status) {
+				if (status === 'granted') {
+					granted = true;
+					keep();
+				}
+				if (status === 'denied') {
+					forgetSettings(writeKey);
+					try {
+						sessionStorage.removeItem(
+							storageKey(storageName('identified'), propertyId),
+						);
+					} catch {
+						/* nothing was stored */
+					}
+				}
+				options.extend?.onConsentStatus?.(status);
+			},
+			onEvent(event) {
+				// The session flag is set only once an identify is on its way, so a visitor whose consent
+				// arrives later in the session is still identified. Any identify counts, including one the
+				// page sends itself at sign-in, so the next page of the session does not repeat it.
+				if (event.type === 'identify') {
+					const marker = identifyMarker(
+						realId(event.userId),
+						normaliseSha256(event.traits?.email_sha256),
+					);
+					try {
+						sessionStorage.setItem(
+							storageKey(storageName('identified'), propertyId),
+							marker,
+						);
+					} catch {
+						/* identify again next page */
+					}
+				}
+				options.extend?.onEvent?.(event);
+			},
+		});
+
+		if (typeof window !== 'undefined')
+			window[RECOMMENDATION_CONTEXT] = () => client.recommendationContext();
+
+		// Before this page's own events: they were made first. Consent here decides, as for any call.
+		for (const [method, args, made] of carry.take()) {
+			try {
+				client[REPLAY](method, args, made);
+			} catch (err) {
+				console.warn(`[hp] carried ${method} failed`, err);
+			}
+		}
+
+		// Stamped when the document was navigated to, not when the settings came back: the page view
+		// is the page's first event, ahead of what the page queued through `hp` meanwhile (#527).
+		client[REPLAY](
+			'page',
+			[options.pageType ? { type: options.pageType } : {}],
+			{
+				messageId: uuid(),
+				timestamp: navigatedAt(),
+			},
+		);
+		let stopAutocapture = startAutocapture(client, options.autocapture);
+		// Impressions count once per page view, so a single-page app's next route reports afresh.
+		const page = client.page;
+		client.page = (...args) => {
+			const event = page(...args);
+			stopAutocapture();
+			stopAutocapture = startAutocapture(client, options.autocapture);
+			return event;
+		};
+
+		const host = typeof window !== 'undefined' ? window : null;
+		if (options.dataLayer && host) {
+			const name = options.dataLayer.name ?? 'dataLayer';
+			host[name] = host[name] || [];
+			connectDataLayer(client, {
+				...preset,
+				dataLayer: host[name],
+				ignore: [
+					...(preset?.ignore ?? []),
+					...(options.dataLayer.ignore ?? []),
+				],
+				onError: (err) =>
+					debug && console.warn('[hp] dataLayer mapping failed', err),
+			});
+		}
+
+		if (identified) client.identify(identified);
+		return client;
+	} catch (err) {
+		console.warn('[hp] not started:', err?.message ?? err);
+		return off(carry);
+	}
+}

package/src/carry.js

@@ -0,0 +1,74 @@
+/**
+ * Calls made through `hp` before the SDK started, carried to the next page (3.9).
+ *
+ * A page that navigates before the SDK has started (a sign-in that redirects at once) would lose
+ * what `hp` queued for it: the queue is in memory. At pagehide `hp` saves it here, in
+ * sessionStorage per write key, and the next page's bootstrap replays it once, in order, with each
+ * call's original messageId and time. Consent is the next page's to apply, as for any call: a grant
+ * sends them, a refusal drops them.
+ *
+ * Saving is a device write, so it follows the held store's rule: only once this device has
+ * granted analytics (the consent cookie), or unanswered with `holdAcrossPages`. Never after a
+ * refusal. And never from a page whose settings turned it off: what was made while the key is off is
+ * not collected later (3.9.1).
+ */
+
+import { HELD_MAX_AGE_MS } from './device-storage.js';
+import { storageKey, storageName } from './storage-scope.js';
+
+/** As many calls as `hp` queues for one page. */
+const MAX_CARRIED = 200;
+
+/**
+ * @param {string} writeKey
+ * @param {() => boolean} mayStore  Whether consent allows writing the calls to the device.
+ * @param {() => number} [now]
+ */
+export function createCarry(writeKey, mayStore, now = () => Date.now()) {
+	const key = () => storageKey(storageName('carried'), writeKey);
+	let closed = false;
+
+	/** What is carried and still fresh. Unreadable is nothing. */
+	function read() {
+		try {
+			const saved = JSON.parse(sessionStorage.getItem(key()) ?? 'null');
+			if (!saved || !(now() - saved.savedAt <= HELD_MAX_AGE_MS)) return [];
+			return Array.isArray(saved.calls) ? saved.calls : [];
+		} catch {
+			return [];
+		}
+	}
+
+	return {
+		/** What an earlier page carried, removed so it is replayed once. Oldest first. */
+		take() {
+			const calls = read();
+			try {
+				sessionStorage.removeItem(key());
+			} catch {
+				/* no storage: nothing was carried */
+			}
+			return calls;
+		},
+		/** Adds `calls` to what is carried. False when they cannot be: they stay this page's. */
+		save(calls) {
+			try {
+				if (closed || !mayStore()) return false;
+				sessionStorage.setItem(
+					key(),
+					JSON.stringify({
+						savedAt: now(),
+						calls: [...read(), ...calls].slice(-MAX_CARRIED),
+					}),
+				);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		/** This page is off for good: nothing it made is carried. */
+		close() {
+			closed = true;
+		},
+	};
+}