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

package/src/index.js

@@ -0,0 +1,818 @@
+/**
+ * @thg-agentic/hyper-personalisation-web — browser SDK for the THG Hyper-Personalisation event specification.
+ *
+ * It emits the wire format defined in @thg-agentic/hyper-personalisation-spec, as do the
+ * @segment/analytics-next plugins in ./segment.js. Most sites start it with
+ * `bootstrap({ writeKey, apiHost }, options)` from ./bootstrap.js, which fetches the tenant's
+ * settings and calls this. createAnalytics is the lower-level API:
+ *
+ *   import { createAnalytics } from '@thg-agentic/hyper-personalisation-web';
+ *
+ *   const analytics = createAnalytics({
+ *     apiHost: 'https://api.example.com',
+ *     writeKey: 'hp_pk_live_…',
+ *     propertyId: 'acme-gb',
+ *     consent: oneTrustConsent(),
+ *     // Where device ids come from, as the source's settings say (`hp.anonymousId`). Without it,
+ *     // getAnonymousId is the device id; with `hp_cookie` the SDK mints and keeps its own.
+ *     anonymousIdSource: settings.anonymousId,
+ *     getAnonymousId: () => getCookie('device_id'),
+ *     getSessionId:   () => getCookie('session_id'),
+ *     // The rails on the page, stamped onto every event as context.recommendations.
+ *     getRecommendations: () => railsOnThisPage,
+ *   });
+ *
+ *   analytics.page({ type: 'product' });
+ *   analytics.productViewed({ products: [item] });
+ *
+ * Recommendation rails are instrumented from markup, against a viewability standard:
+ *
+ *   import { trackRecommendationRails } from '@thg-agentic/hyper-personalisation-web/auto';
+ *   import { assignRecommendationVariant } from '@thg-agentic/hyper-personalisation-web';
+ *
+ *   // Before requesting the rail: a control arm must not call the recommender.
+ *   const arm = assignRecommendationVariant({
+ *     unit: getCookie('device_id'),
+ *     experiment: 'reco_ranker_v2',
+ *     variants: [{ name: 'blend', share: 0.5 }, { name: 'ranker', share: 0.5 }],
+ *     holdoutShare: 0.05,
+ *   });
+ *
+ *   trackRecommendationRails(analytics);
+ */
+
+import { assignmentSession, surfaceExposureToken } from './assignment.js';
+import { hostConsent, servingHeaders } from './consent.js';
+import { createConsentGate } from './consent-gate.js';
+import { buildContext, getCookie, perRequest } from './context.js';
+import { createDecisionMemory, servedDecisions } from './decisions.js';
+import { createHeldStore, deviceIdFrom } from './device-storage.js';
+import {
+	banditSplit,
+	holdoutAssignment,
+	holdoutShares,
+} from './experiments.js';
+import { emailSha256, sha256Hex } from './hash.js';
+import { applyPreview } from './preview.js';
+import {
+	forgetVisit,
+	keepVisit,
+	recommendationContextFrom,
+} from './recommendation-context.js';
+import { recordSessionEvent } from './session/record.js';
+import {
+	clearSessionSignals,
+	getSessionSignals,
+	setSessionScope,
+} from './session/signals.js';
+import { createSessionId } from './session-id.js';
+import { planAllows, resolveApiHost } from './settings.js';
+import {
+	detectNavigationTrigger,
+	PAGE_TYPES,
+	pruneProperties,
+	realId,
+	uuid,
+} from './shape.js';
+import {
+	configureStorageNames,
+	migrateLegacyStorage,
+	storageKey,
+	storageName,
+} from './storage-scope.js';
+import { Transport } from './transport.js';
+import { LIB, VERSION } from './version.js';
+
+/** The surfaces a `Personalisation Exposed` names, as the public API's exposures do. */
+const EXPOSURE_SURFACES = new Set([
+	'audiences',
+	'decisions',
+	'recommendations',
+]);
+
+export {
+	ASSIGNMENT_DECISION_NAMESPACE,
+	assignmentDecisionId,
+} from './assignment.js';
+export { defaultProductId, fromGa4Item, toProducts } from './ga4.js';
+export { DEFAULT_API_HOST, resolveApiHost } from './settings.js';
+export { PAGE_TYPES, pruneProperties } from './shape.js';
+export { emailSha256, getCookie };
+
+/** How a call made before the SDK started is replayed with the messageId and time it was made at. */
+const REPLAY = Symbol.for('@thg-agentic/hyper-personalisation-web.replay');
+
+/** SHA-256 of a string as lowercase hex. Synchronous since 3.9 (sha256Hex); kept async for callers. */
+export async function sha256(value) {
+	return sha256Hex(String(value));
+}
+
+/**
+ * Cart Updated's properties from the platform's confirmed basket: the lines as given, and
+ * `item_count` summed from their quantities when the basket does not carry one. Prices are left
+ * alone: a line price includes tax where the market displays it so, and `value` does not, so the
+ * SDK never derives `value` from the lines.
+ */
+export function cartSnapshot(basket) {
+	const props = { ...(basket ?? {}) };
+	const lines = Array.isArray(props.products) ? props.products : null;
+	if (props.item_count == null && lines) {
+		const quantities = lines.map((line) => line?.quantity);
+		if (quantities.every(Number.isInteger))
+			props.item_count = quantities.reduce((sum, q) => sum + q, 0);
+	}
+	return props;
+}
+
+/** As emailSha256, kept async for the callers that await it. */
+export async function hashEmail(email) {
+	return emailSha256(email);
+}
+
+/**
+ * `phone_sha256` for identify: the E.164 number (`+` then 8 to 15 digits, spaces, dots, dashes and
+ * brackets removed), hashed. Null for a national number such as `07700 900123`: its country cannot
+ * be known here, and hashing it as typed would never match the same number sent in E.164.
+ */
+export async function hashPhone(phone) {
+	if (typeof phone !== 'string') return null;
+	const normalised = phone.replace(/[\s.()-]/g, '');
+	if (!/^\+[1-9]\d{7,14}$/.test(normalised)) return null;
+	return sha256Hex(normalised);
+}
+
+/**
+ * The digest of the empty string: what a platform that hashes a blank email field sends for "no
+ * email". Every customer without an address would share it.
+ */
+const EMPTY_SHA256 =
+	'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+
+function hexDigest(text) {
+	if (/^[0-9a-fA-F]{64}$/.test(text)) return text.toLowerCase();
+	if (!/^[A-Za-z0-9+/_-]{43}=?$/.test(text)) return null;
+	try {
+		const binary = atob(
+			text.replace(/-/g, '+').replace(/_/g, '/').padEnd(44, '='),
+		);
+		if (binary.length !== 32) return null;
+		return Array.from(binary, (c) =>
+			c.charCodeAt(0).toString(16).padStart(2, '0'),
+		).join('');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * A SHA-256 digest as the lowercase hex `email_sha256` wants, from hex or base64 (standard or
+ * URL-safe). Re-encodes, never re-hashes. Null for anything that is not a 32-byte digest, and for
+ * the digest of the empty string.
+ */
+export function normaliseSha256(value) {
+	if (typeof value !== 'string') return null;
+	const hex = hexDigest(value.trim());
+	return hex === EMPTY_SHA256 ? null : hex;
+}
+
+// On the main entry so integrators find them: without an assigned variant a rail is unmeasurable.
+export {
+	assignRecommendationVariant,
+	banditSplit,
+	candidateSetFingerprint,
+	hash32,
+	hashBucket,
+	holdoutAssignment,
+} from './experiments.js';
+/** Social proof: the one part of this package that reads rather than writes. */
+export { createSocialProof } from './social-proof.js';
+
+export { VERSION };
+
+let warnedMintAnonymousId = false;
+
+/** 3.5's `mintAnonymousId` does nothing since 3.6: where device ids come from is the source's. */
+function warnMintAnonymousId(debug) {
+	if (!debug || warnedMintAnonymousId) return;
+	warnedMintAnonymousId = true;
+	console.warn(
+		'[hp] mintAnonymousId is ignored since 3.6: where device ids come from is set per source in the console (the site’s own cookie, or Hyper-Personalisation’s).',
+	);
+}
+
+/** Per-call context overrides, given directly or analytics-next style as `{ context }`. */
+function contextOverrides(options) {
+	if (
+		options &&
+		typeof options.context === 'object' &&
+		options.context !== null
+	)
+		return options.context;
+	return options;
+}
+
+export function createAnalytics(options) {
+	const apiHost = resolveApiHost(options?.apiHost);
+	if (!apiHost)
+		throw new Error(
+			'createAnalytics: apiHost, when given, must be a host or an http(s) origin',
+		);
+	if (!options?.propertyId)
+		throw new Error('createAnalytics: propertyId is required');
+
+	const cfg = {
+		libraryName: LIB,
+		libraryVersion: VERSION,
+		writeKey: 'web',
+		queryParamBlocklist: [],
+		debug: false,
+		validate: null, // inject @thg-agentic/hyper-personalisation-spec's validateEvent in dev
+		consentTimeoutMs: 5000,
+		...options,
+		apiHost,
+	};
+
+	configureStorageNames(cfg.storageNames);
+	migrateLegacyStorage();
+
+	// A consent adapter makes the SDK strict: nothing is sent or stored until analytics is granted.
+	// Without one the host has decided the lawful basis itself, and every event says so (spec 1.5).
+	const strict = Boolean(cfg.consent);
+	let gate = null;
+	cfg.getConsent = () => (gate ? gate.stamp() : hostConsent());
+	const granted = () => !strict || gate?.status === 'granted';
+
+	// Opt-in (3.5): events held for an unanswered CMP survive a navigation, in sessionStorage.
+	const heldStore =
+		strict && cfg.holdAcrossPages
+			? createHeldStore(storageKey(storageName('held'), cfg.propertyId))
+			: null;
+	const carried = heldStore?.read() ?? { items: [], anonymousId: null };
+
+	if (cfg.mintAnonymousId !== undefined) warnMintAnonymousId(cfg.debug);
+	const device = deviceIdFrom(cfg, {
+		carried: carried.anonymousId,
+		mayStore: granted,
+	});
+
+	// No session from the host: the SDK keeps one (3.15). Never a second beside the host's.
+	const session =
+		cfg.getSessionId == null
+			? createSessionId({
+					name: storageName('session'),
+					domain: cfg.consentCookieDomain ?? null,
+					mayStore: granted,
+				})
+			: null;
+	if (session) cfg.getSessionId = () => session.get();
+
+	const previewing = applyPreview(
+		storageName('preview'),
+		cfg.consentCookieDomain ?? null,
+	);
+
+	const transport =
+		cfg.transport ??
+		new Transport({
+			apiHost: cfg.apiHost,
+			writeKey: cfg.writeKey,
+			// Per tenant: a persisted batch is replayed through whichever instance starts next, with its
+			// writeKey, and one origin can serve several tenants.
+			storageKey: storageKey(storageName('retry'), cfg.propertyId),
+			// Under strict consent, persisting is a device write and replaying is a send: both wait for a
+			// grant (see onStatus below, which replays on a grant and clears on a refusal).
+			mayPersist: strict ? () => gate?.status === 'granted' : undefined,
+			deferReplay: strict,
+			onError: (m, e) => cfg.debug && console.warn('[hp]', m, e ?? ''),
+		});
+
+	// The previous page view's messageId, carried across navigations in sessionStorage, per tenant.
+	const PREV_PAGE_KEY = storageKey(storageName('previousPage'), cfg.propertyId);
+
+	// Memory is authoritative within a document; storage only carries the link across a navigation.
+	let lastPageMessageId = null;
+
+	const readLastPageMessageId = () => {
+		if (lastPageMessageId) return lastPageMessageId;
+		try {
+			return sessionStorage.getItem(PREV_PAGE_KEY) || null;
+		} catch {
+			return null;
+		}
+	};
+
+	const writeLastPageMessageId = (id) => {
+		lastPageMessageId = id || null;
+		if (strict && gate.status !== 'granted') return;
+		try {
+			sessionStorage.setItem(PREV_PAGE_KEY, id);
+		} catch {
+			/* private browsing: the chain still holds within this document */
+		}
+	};
+	// What decisioned slots served, stamped on every later event unless the host supplies its own.
+	const decisions = createDecisionMemory({
+		key: storageKey(storageName('decisions'), cfg.propertyId),
+		mayStore: granted,
+	});
+	cfg.getDecisions ??= decisions.current;
+
+	let userId = realId(perRequest(cfg.getUserId, null));
+
+	/** The call being replayed: its first event keeps the messageId and time it was made with. */
+	let replaying = null;
+
+	function emit(partial, ctxOverrides, force = false) {
+		const made = replaying;
+		replaying = null;
+		let event = {
+			messageId: made?.messageId ?? uuid(),
+			timestamp: made?.timestamp ?? new Date().toISOString(),
+			anonymousId: realId(perRequest(cfg.getAnonymousId, null)),
+			userId: userId ?? null,
+			...partial,
+			context: buildContext(cfg, contextOverrides(ctxOverrides)),
+		};
+
+		if (event.properties) event.properties = pruneProperties(event.properties);
+
+		// A redaction or sampling hook may change what an event says or drop it, never what it is.
+		// One that fails drops the event rather than sending what it was meant to redact.
+		if (cfg.beforeSend) {
+			let shaped;
+			try {
+				shaped = cfg.beforeSend(event);
+			} catch (err) {
+				console.warn('[hp] beforeSend failed; the event was not sent', err);
+				return null;
+			}
+			if (!shaped) return null;
+			const { type, event: name, messageId, timestamp } = event;
+			event = {
+				...shaped,
+				type,
+				messageId,
+				timestamp,
+				...(name ? { event: name } : {}),
+			};
+		}
+
+		// Injected rather than imported, so the validator and ajv never reach a production bundle.
+		if (cfg.validate) {
+			const res = cfg.validate(event, { producer: 'web' });
+			if (!res.valid) {
+				const msg = `[hp] invalid ${event.event ?? event.type}:\n  ${res.errors.join('\n  ')}`;
+				if (cfg.throwOnInvalid) throw new Error(msg);
+				console.error(msg);
+			}
+		}
+
+		if (cfg.debug) console.debug('[hp]', event.event ?? event.type, event);
+
+		deliver(event, force);
+		return event;
+	}
+
+	function observe(event) {
+		if (event.type === 'track') recordVisit(event);
+		// Lets a caller fold the event the warehouse will receive into session state. An observer
+		// that throws must not cost the event.
+		if (cfg.onEvent) {
+			try {
+				cfg.onEvent(event);
+			} catch (err) {
+				console.warn('[hp] onEvent observer failed', err);
+			}
+		}
+	}
+
+	/** The visit is kept on the device only for a visitor who allowed personalisation. */
+	const personalisationGranted = () =>
+		strict && gate?.state?.personalisation === true;
+	const scopeVisit = () =>
+		setSessionScope(perRequest(cfg.getSessionId, null), cfg.propertyId);
+
+	let visitKept = false;
+
+	/** What `recommendationContext()` reads: the products and searches of the events sent. */
+	function recordVisit(event) {
+		try {
+			if (personalisationGranted()) {
+				scopeVisit();
+				keepVisit(
+					recommendationContextFrom(
+						recordSessionEvent(event.event, event.properties),
+					),
+				);
+				visitKept = true;
+			} else {
+				// Not allowed, or withdrawn: what was kept under the permission goes with it.
+				forgetVisit();
+				if (visitKept) clearSessionSignals();
+				visitKept = false;
+			}
+		} catch (err) {
+			if (cfg.debug) console.warn('[hp] the visit was not recorded', err);
+		}
+	}
+
+	function deliver(event, force) {
+		// The observer only sees what will be sent, never an event the visitor has not allowed.
+		if (!strict || force || gate.admits()) {
+			observe(event);
+			transport.enqueue(event);
+		} else {
+			gate.hold(event);
+		}
+	}
+
+	const track = (name, properties, ctx) =>
+		planAllows(cfg.plan, name)
+			? emit({ type: 'track', event: name, properties: properties ?? {} }, ctx)
+			: null;
+
+	// One exposure event per serving response, however often the page reuses it.
+	const exposedTokens = new Set();
+
+	/** What the response personalised, by surface. Nothing in the holdout: nothing was applied. */
+	const exposed = (surface, holdout, body) => {
+		if (surface === 'audiences')
+			return { audiences: holdout ? null : (body.audiences ?? []) };
+		if (surface === 'decisions')
+			return {
+				decisions: (body.decisions ?? []).map((d) => ({
+					slot: d.slot,
+					decision_id: d.decision_id ?? null,
+					arm: d.arm ?? null,
+					...(d.variant && { variant: d.variant }),
+				})),
+			};
+		return {
+			recommendation_request_id: body.recommendation_request_id ?? null,
+		};
+	};
+
+	if (strict) {
+		gate = createConsentGate({
+			adapter: cfg.consent,
+			timeoutMs: cfg.consentTimeoutMs,
+			cookieDomain: cfg.consentCookieDomain,
+			debug: cfg.debug,
+			store: heldStore && {
+				read: () => carried.items,
+				write: (items) => heldStore.write(items, device?.peek() ?? null),
+			},
+			release(event) {
+				// Only the consent block is rewritten; everything else was true when it was collected.
+				if (event.context) event.context.consent = gate.stamp();
+				observe(event);
+				transport.enqueue(event);
+			},
+			onStatus(status) {
+				if (status === 'granted') {
+					device?.persist();
+					session?.persist();
+					if (lastPageMessageId) writeLastPageMessageId(lastPageMessageId);
+					decisions.persist();
+					transport.replayPersisted?.();
+				}
+				if (status === 'denied') {
+					// Nothing kept on the device may outlive the permission it was kept under.
+					transport.clearPersisted?.();
+					device?.forget();
+					session?.forget();
+					try {
+						sessionStorage.removeItem(PREV_PAGE_KEY);
+					} catch {
+						/* nothing was stored */
+					}
+					decisions.forget();
+				}
+				try {
+					cfg.onConsentStatus?.(status);
+				} catch (err) {
+					console.warn('[hp] onConsentStatus observer failed', err);
+				}
+			},
+			announce({ action, state, withdrawal }) {
+				emit(
+					{
+						type: 'track',
+						event: 'Consent Updated',
+						properties: { action, state },
+					},
+					undefined,
+					withdrawal,
+				);
+				if (withdrawal) transport.flush();
+			},
+		});
+		gate.start();
+	}
+
+	/**
+	 * This shopper's group, as the edge and the public API decide it: `holdout` and `excluded` (outside
+	 * the property's ramp) both get the default everywhere, so personalise in the page only for
+	 * `personalised`.
+	 */
+	/** The property's holdout split from the settings, as a serving response would state it. */
+	const configuredShares = () =>
+		cfg.holdout ? holdoutShares(cfg.holdout) : null;
+
+	const personalisationGroup = () =>
+		holdoutAssignment(cfg.holdout, realId(perRequest(cfg.getAnonymousId, null)))
+			.group;
+
+	/**
+	 * The response with each readout slot's side of its bandit-vs-default 50/50 (`variant`): the
+	 * response's own, else this visitor's from the settings, the hash serving used. A page cached per
+	 * arm has no response, so its side is computed here. The default side is no decision: its id is
+	 * dropped, so it is never in force and never names a decision. A held-out visitor is in no split.
+	 */
+	function withSplit(body, holdout) {
+		if (!Array.isArray(body?.decisions)) return body;
+		const readout = cfg.holdout?.readoutSlots ?? [];
+		const visitor = realId(perRequest(cfg.getAnonymousId, null));
+		return {
+			...body,
+			decisions: body.decisions.map((d) => {
+				const variant =
+					d?.variant === 'bandit' || d?.variant === 'default'
+						? d.variant
+						: !holdout && d?.holdout !== true && readout.includes(d?.slot)
+							? banditSplit(d.slot, visitor)
+							: null;
+				if (!variant) return d;
+				return variant === 'default'
+					? { ...d, variant, decision_id: null }
+					: { ...d, variant };
+			}),
+		};
+	}
+
+	/**
+	 * Log the exposure a serving response carries (membership, decisions or recommendations):
+	 * pass the parsed body after rendering it. Null when the response personalised nothing, or its
+	 * token was already recorded. A decisions response's decisions are then in force: every later
+	 * event this session carries them as context.decisions, unless the host passes getDecisions.
+	 *
+	 * A page rendered server-side from `/v1/assignments` and cached has no serving response, so it
+	 * passes the exposure itself (`token` the assignment's derived id, `holdout` from the page's
+	 * hash) and omits the shares: they are then the property's, from these settings, so the
+	 * sample-ratio check can read the split as it does for any response.
+	 */
+	function recordExposure(response, c) {
+		// A trader previewing an arm is not a shopper: nothing they see is exposure or in force.
+		if (previewing) return null;
+		const exposure = response?.exposure;
+		const holdout = exposure?.holdout === true;
+		const body = withSplit(response, holdout);
+		// In force from the render, so a basket later in the session is credited to the slot.
+		decisions.remember(servedDecisions(body));
+		if (!exposure?.token || exposedTokens.has(exposure.token)) return null;
+		exposedTokens.add(exposure.token);
+		return track(
+			'Personalisation Exposed',
+			{
+				exposure_token: exposure.token,
+				surface: exposure.surface,
+				holdout,
+				holdout_share:
+					exposure.holdout_share ?? configuredShares()?.holdout_share ?? null,
+				personalised_share:
+					exposure.personalised_share ??
+					configuredShares()?.personalised_share ??
+					null,
+				...exposed(exposure.surface, holdout, body),
+			},
+			c,
+		);
+	}
+
+	return {
+		/** Escape hatch for events not yet in the core spec. Prefer a named method. */
+		track,
+
+		page(props = {}, ctx) {
+			// page.type is inherited by every later event on the page, so an unknown value would get
+			// them all rejected. Keep the last good type instead: stale beats invalid.
+			let pageType = cfg.pageType ?? null;
+			if (props.type) {
+				if (PAGE_TYPES.has(props.type)) {
+					pageType = props.type;
+					cfg.pageType = props.type;
+				} else if (cfg.debug) {
+					console.warn(
+						`[hp] ignoring unknown page.type "${props.type}". Allowed: ${[...PAGE_TYPES].join(', ')}`,
+					);
+				}
+			}
+
+			const ev = emit(
+				{
+					type: 'page',
+					properties: {
+						name: props.name ?? null,
+						navigation_trigger:
+							props.navigation_trigger ?? detectNavigationTrigger(),
+						previous_message_id: readLastPageMessageId(),
+					},
+				},
+				// page.type is a context field, inherited by every later event on this page.
+				{ page: { type: pageType }, ...(contextOverrides(ctx) ?? {}) },
+			);
+			if (ev) writeLastPageMessageId(ev.messageId);
+			return ev;
+		},
+
+		identify(traits, ctx) {
+			const { userId: id, ...rest } =
+				traits && typeof traits === 'object' ? traits : {};
+			if (id !== undefined) userId = realId(id);
+			// A digest in hex or base64 is sent as hex; anything that is not one is not sent.
+			if (typeof rest.email_sha256 === 'string') {
+				const email = normaliseSha256(rest.email_sha256);
+				if (email) rest.email_sha256 = email;
+				else delete rest.email_sha256;
+			}
+			return emit({ type: 'identify', traits: rest }, ctx);
+		},
+
+		/** Clear identity on sign-out so the next events are not attributed to the old user. */
+		reset() {
+			userId = null;
+			writeLastPageMessageId('');
+		},
+
+		productViewed: (p, c) => track('Product Viewed', p, c),
+		productListViewed: (p, c) => track('Product List Viewed', p, c),
+
+		/**
+		 * A recommendation rail was on screen.
+		 *
+		 * Prefer `trackRecommendationRails` from ./auto, which fires on the MRC viewability standard
+		 * and fills in `viewable`. Call this directly only if the host measures viewability to the same
+		 * standard itself; omit `viewable` rather than guess it.
+		 */
+		recommendationsViewed: (p, c) => track('Recommendations Viewed', p, c),
+
+		/**
+		 * A serving response personalised the page, or would have outside the holdout. Prefer
+		 * `recordExposure`, which reads the response's `exposure` block.
+		 */
+		personalisationExposed: (p, c) => track('Personalisation Exposed', p, c),
+
+		recordExposure,
+
+		/**
+		 * A surface rendered server-side from a serving answer the page never sees (a product rail
+		 * the site's server fetched from HP) came into view: record the property holdout's exposure for it, for
+		 * both groups on the same trigger, so the readout counts like with like. The group is this
+		 * visitor's as serving decides it, from the same holdout settings, salt and visitor id
+		 * (spec/assignment/holdout.json), so it is the one serving answered with. Nothing is recorded
+		 * for a visitor outside the experiment: without the property's holdout in the settings, outside
+		 * the ramp, with no visitor or session id, or where serving personalises the surface only with
+		 * consent this visitor has not given (rails and audiences need personalisation; decisions run
+		 * on analytics, which every event already needs). One exposure per session per surface.
+		 */
+		surfaceViewed({ surface } = {}, c) {
+			if (!EXPOSURE_SURFACES.has(surface) || !cfg.holdout) return null;
+			if (surface !== 'decisions' && !personalisationGranted()) return null;
+			const visitor = realId(perRequest(cfg.getAnonymousId, null));
+			const group = holdoutAssignment(cfg.holdout, visitor).group;
+			if (group === 'excluded') return null;
+			const token = surfaceExposureToken({
+				sessionId: assignmentSession(
+					perRequest(cfg.getSessionId, null),
+					visitor,
+				),
+				surface,
+			});
+			if (!token) return null;
+			return recordExposure(
+				{ exposure: { token, surface, holdout: group === 'holdout' } },
+				c,
+			);
+		},
+
+		/**
+		 * Whether this shopper must see the default: held out, or outside the property's ramp
+		 * (excluded), as the edge and the public API decide it. Skip anything personalised in the page
+		 * itself (session-evaluated audiences, client re-ranking) when true. `personalisationGroup()`
+		 * gives the exact group. An exposure's `holdout` flag comes from the serving response, never
+		 * from this, except in `surfaceViewed`, for a surface whose response the page never sees.
+		 */
+		inHoldout: () => personalisationGroup() !== 'personalised',
+		personalisationGroup,
+		productClicked: (p, c) => track('Product Clicked', p, c),
+		productListFiltered: (p, c) => track('Product List Filtered', p, c),
+		productsSearched: (p, c) => track('Products Searched', p, c),
+		productAdded: (p, c) => track('Product Added', p, c),
+		productRemoved: (p, c) => track('Product Removed', p, c),
+		/**
+		 * The basket as the platform confirmed it after a change: pass the basket your cart API
+		 * returned, every line with its total quantity. Send it alongside productAdded and
+		 * productRemoved, never instead of them. `item_count` is summed from the lines when omitted.
+		 */
+		cartUpdated: (basket, c) => track('Cart Updated', cartSnapshot(basket), c),
+		/**
+		 * An identity edge an identify cannot imply: a guest checkout, a newsletter sign-up, an email
+		 * click. Send the event-named trigger (`signed_in`, not `user_login`).
+		 */
+		identityLinked: (p, c) => track('Identity Linked', p, c),
+		/** A visitor saw, clicked or dismissed a decisioned slot: the bandit's reward signal. */
+		slotEngaged: (p, c) => (previewing ? null : track('Slot Engaged', p, c)),
+		/** A size, colour or flavour the shopper picked: product_id the master, sku the new variant. */
+		productVariantSelected: (p, c) => track('Product Variant Selected', p, c),
+		cartViewed: (p, c) => track('Cart Viewed', p, c),
+		productAddedToWishlist: (p, c) => track('Product Added to Wishlist', p, c),
+		productRemovedFromWishlist: (p, c) =>
+			track('Product Removed from Wishlist', p, c),
+		/** A wishlist conversion. Send productAdded for the cart add as well: they are two facts. */
+		wishlistProductAddedToCart: (p, c) =>
+			track('Wishlist Product Added to Cart', p, c),
+		productShared: (p, c) => track('Product Shared', p, c),
+		cartShared: (p, c) => track('Cart Shared', p, c),
+
+		// Segment fires the coupon events from wherever the code is handled. Report each coupon fact
+		// from ONE producer per property, browser or server, or it is counted twice.
+		couponEntered: (p, c) => track('Coupon Entered', p, c),
+		couponApplied: (p, c) => track('Coupon Applied', p, c),
+		couponDenied: (p, c) => track('Coupon Denied', p, c),
+		couponRemoved: (p, c) => track('Coupon Removed', p, c),
+
+		// Order outcomes are backend-only: the server SDK sends them, and the ingest refuses them from
+		// a web key.
+		checkoutStarted: (p, c) => track('Checkout Started', p, c),
+		promotionViewed: (p, c) => track('Promotion Viewed', p, c),
+		promotionClicked: (p, c) => track('Promotion Clicked', p, c),
+		checkoutStepViewed: (p, c) => track('Checkout Step Viewed', p, c),
+		checkoutStepCompleted: (p, c) => track('Checkout Step Completed', p, c),
+		/** Send INSTEAD of checkoutStepCompleted for the payment step, never as well as it. */
+		paymentInfoEntered: (p, c) => track('Payment Info Entered', p, c),
+		/** Where checkout failed and why. The kind of payment instrument only, never card data. */
+		checkoutFailed: (p, c) => track('Checkout Failed', p, c),
+
+		signedIn: (p, c) => track('Signed In', p, c),
+		signedUp: (p, c) => track('Signed Up', p, c),
+		/** Sent under the signed-in identity, which is then cleared for whoever uses the device next. */
+		signedOut(c) {
+			const event = track('Signed Out', {}, c);
+			userId = null;
+			return event;
+		},
+		newsletterSubscribed: (p, c) => track('Newsletter Subscribed', p, c),
+		/** An on-site opt-out. The ESP reports its own as Email Unsubscribed. */
+		newsletterUnsubscribed: (p, c) => track('Newsletter Unsubscribed', p, c),
+		/** An alert request for one product: back in stock, a price drop or a launch. */
+		backInStockSubscribed: (p, c) => track('Back In Stock Subscribed', p, c),
+		productReviewed: (p, c) => track('Product Reviewed', p, c),
+		consentUpdated: (p, c) => track('Consent Updated', p, c),
+
+		flush: (o) => transport.flush(o),
+		/**
+		 * This visit as the recommendations API's session context: `viewed`, `basket`, `q` and
+		 * `impressed`, newest first, in its wire form. `{}` unless the visitor allowed personalisation.
+		 * Synchronous and never throws: `new URLSearchParams(context)` is what to append. Since 3.11.
+		 */
+		recommendationContext() {
+			if (!personalisationGranted()) return {};
+			try {
+				scopeVisit();
+				return recommendationContextFrom(getSessionSignals());
+			} catch {
+				return {};
+			}
+		},
+		/** The consent state in force (strict mode), or null while the CMP has not answered. */
+		get consent() {
+			return gate ? gate.state : null;
+		},
+		/**
+		 * Headers every request to the serving API must carry: `hp-consent`, so serving personalises
+		 * only what the visitor allowed. Spread them into the recommendations or decisions fetch.
+		 */
+		servingHeaders: () => servingHeaders(gate?.state ?? null),
+		get lastPageMessageId() {
+			return readLastPageMessageId();
+		},
+		/** The device id events carry: the site's cookie's, or under `hp_cookie` the SDK's own. */
+		get anonymousId() {
+			return realId(perRequest(cfg.getAnonymousId, null));
+		},
+		/** `hp` and bootstrap replay a call made before the start through this. Not public API. */
+		[REPLAY](method, args, made) {
+			if (typeof this[method] !== 'function') return;
+			replaying =
+				typeof made?.messageId === 'string' &&
+				typeof made?.timestamp === 'string'
+					? { messageId: made.messageId, timestamp: made.timestamp }
+					: null;
+			try {
+				this[method](...(Array.isArray(args) ? args : []));
+			} finally {
+				replaying = null;
+			}
+		},
+	};
+}