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

package/src/preview.js

@@ -0,0 +1,44 @@
+/**
+ * Preview (3.15): a trader opens the site with `?hp_preview=<token>`, a token the console made to
+ * force one arm of one slot. The SDK keeps it in a session cookie, so every server render of the
+ * visit can forward it to `/v1/assignments`, which answers the forced arm and logs nothing.
+ * `?hp_preview=` with no value ends the preview.
+ *
+ * While a preview is on, the browser reports no exposure and no slot engagement: the trader is not
+ * a shopper, so their views must neither train a slot nor count in its readout. Everything else is
+ * sent as usual. The token is checked by the server, never here; one that has expired forces
+ * nothing there, and still silences these two events here until the browser session ends.
+ */
+
+import { getCookie } from './context.js';
+import { writeCookie } from './device-storage.js';
+
+export const PREVIEW_PARAM = 'hp_preview';
+
+/** Longest token taken from a URL; the console's are far shorter. */
+const MAX_TOKEN_LENGTH = 256;
+
+/**
+ * Apply the page URL's `hp_preview` to the preview cookie, and return the preview now in force, or
+ * null.
+ *
+ * @param {string} name  The cookie name, storageName('preview').
+ * @param {string|null} [domain]
+ */
+export function applyPreview(name, domain = null) {
+	if (typeof location === 'undefined') return getCookie(name);
+	let given = null;
+	try {
+		given = new URLSearchParams(location.search).get(PREVIEW_PARAM);
+	} catch {
+		given = null;
+	}
+	if (given === null) return getCookie(name);
+	const token = given.trim();
+	if (token === '' || token.length > MAX_TOKEN_LENGTH) {
+		writeCookie(name, '', 0, domain);
+		return null;
+	}
+	writeCookie(name, token, null, domain);
+	return token;
+}

package/src/recommendation-context.js

@@ -0,0 +1,101 @@
+/**
+ * This visit, in the form the recommendations API takes it as query parameters: `viewed`, `basket`
+ * and `q` as comma-separated lists, newest first, and `impressed` as `id:count` pairs. The API
+ * truncates rather than rejects, so these are its own limits: nothing sent is thrown away there.
+ *
+ * Every key is optional and present only when it has something in it, so
+ * `new URLSearchParams(context)` is the query string to append, and an empty visit appends nothing.
+ */
+
+import { storageName } from './storage-scope.js';
+
+/** packages/cdp/src/recommendations/request.ts: MAX_IDS, MAX_ID_LENGTH, five queries, 60 pairs. */
+const MAX_IDS = 40;
+const MAX_ID_LENGTH = 128;
+const MAX_QUERIES = 5;
+const MAX_IMPRESSIONS = 60;
+
+/** A comma would split one id into two on the wire. */
+const sendable = (id) =>
+	typeof id === 'string' &&
+	id !== '' &&
+	id.length <= MAX_ID_LENGTH &&
+	!id.includes(',');
+
+const ids = (list) =>
+	Array.isArray(list) ? list.filter(sendable).slice(0, MAX_IDS) : [];
+
+const queries = (list) =>
+	Array.isArray(list)
+		? list
+				.filter((q) => typeof q === 'string')
+				.map((q) => q.replaceAll(',', ' ').trim())
+				.filter((q) => q !== '')
+				.slice(0, MAX_QUERIES)
+		: [];
+
+/** The products shown most often without being engaged with: those are the ones a rail demotes. */
+const impressions = (counts) =>
+	Object.entries(counts && typeof counts === 'object' ? counts : {})
+		.filter(([id, n]) => sendable(id) && Number.isFinite(n) && n >= 1)
+		.sort(([, a], [, b]) => b - a)
+		.slice(0, MAX_IMPRESSIONS)
+		.map(([id, n]) => `${id}:${Math.floor(n)}`);
+
+/**
+ * @param {object} signals The session signals (`getSessionSignals()` from `./session`).
+ * @returns {{ viewed?: string, basket?: string, q?: string, impressed?: string }}
+ */
+export function recommendationContextFrom(signals) {
+	const context = {};
+	const lists = {
+		viewed: ids(signals?.recentProducts),
+		basket: ids(signals?.basketProducts),
+		q: queries(signals?.recentSearches),
+		impressed: impressions(signals?.impressions),
+	};
+	for (const [name, list] of Object.entries(lists)) {
+		if (list.length > 0) context[name] = list.join(',');
+	}
+	return context;
+}
+
+/** How long a page's visit stays readable to the next page, from the last event: a web session. */
+const KEPT_FOR_MS = 30 * 60 * 1000;
+
+/**
+ * Keep the visit's wire form where the next page can read it synchronously before its SDK has
+ * downloaded: a rail requested at page load would otherwise go without it.
+ */
+export function keepVisit(context, now = Date.now()) {
+	try {
+		localStorage.setItem(
+			storageName('recommendationContext'),
+			JSON.stringify({ context, until: now + KEPT_FOR_MS }),
+		);
+	} catch {
+		// Quota or a disabled store: the next page's first rail goes without the visit.
+	}
+}
+
+export function forgetVisit() {
+	try {
+		localStorage.removeItem(storageName('recommendationContext'));
+	} catch {
+		// Nothing was kept.
+	}
+}
+
+/** The visit an earlier page kept, or `{}` once it has lapsed. */
+export function keptVisit(now = Date.now()) {
+	try {
+		const kept = JSON.parse(
+			localStorage.getItem(storageName('recommendationContext')) ?? 'null',
+		);
+		return kept?.until > now && kept.context && typeof kept.context === 'object'
+			? kept.context
+			: {};
+	} catch {
+		return {};
+	}
+}

package/src/sampling.js

@@ -0,0 +1,19 @@
+/**
+ * Sampling (3.18): the source's settings may send for only a share of visitors. Decided per
+ * anonymous id, so a visitor is in or out for every event, on every page and in every tab, as the
+ * holdout is. A visitor with no anonymous id yet is kept.
+ */
+
+import { hashBucket } from './experiments.js';
+
+/** Salts the hash, so who is sampled is independent of who is held out or in an experiment. */
+export const SAMPLE_SALT = 'hp_sample';
+
+const BUCKETS = 10000;
+
+/** Whether the visitor `unit` is sent for at `rate`, a share in [0, 1]. */
+export function sampledIn(unit, rate) {
+	if (!(typeof rate === 'number' && rate < 1)) return true;
+	if (unit == null || unit === '') return true;
+	return hashBucket(unit, SAMPLE_SALT, BUCKETS) < Math.round(rate * BUCKETS);
+}

package/src/segment.js

@@ -0,0 +1,388 @@
+/**
+ * The spec as @segment/analytics-next plugins.
+ *
+ *   import { AnalyticsBrowser } from '@segment/analytics-next';
+ *   import {
+ *     cdpPlugins, DEFAULT_API_HOST, hpLoadOptions,
+ *   } from '@thg-agentic/hyper-personalisation-web/segment';
+ *   import { didomiConsent } from '@thg-agentic/hyper-personalisation-web/consent';
+ *
+ *   const hp = { writeKey: 'hp_pk_live_…' };
+ *   const analytics = AnalyticsBrowser.load(
+ *     { writeKey: hp.writeKey, cdnURL: DEFAULT_API_HOST, plugins: cdpPlugins({ consent: didomiConsent() }) },
+ *     hpLoadOptions(hp),
+ *   );
+ *
+ * `cdnURL` points analytics-next's settings fetch at `{apiHost}/v1/projects/{writeKey}/settings`,
+ * the HP API unless the page proxies it (then both take the proxy's host),
+ * the same Segment-compatible path the built-in bootstrap reads. The plugins take the property, the
+ * environment, the reported consent purposes, the query-param allowlist and the tracking plan from
+ * its `hp` block, so the host passes only what the page knows. hpLoadOptions() does the rest.
+ *
+ * Two plugins, sharing every rule with the built-in client — the delivery path is the only thing
+ * that differs:
+ *   'before'      strict consent (./consent-gate.js): holds, releases or cancels each event
+ *   'enrichment'  context shaped to the spec (./context.js), properties pruned (./shape.js)
+ *
+ * @segment/analytics-consent-tools was considered and not used: it writes
+ * `context.consent.categoryPreferences` (not the spec's consent block) and keeps delivering to
+ * Segment.io after a withdrawal, which strict mode must not do.
+ */
+
+import { hostConsent, reportingPurposes } from './consent.js';
+import { createConsentGate } from './consent-gate.js';
+import { buildContext, CONTEXT_KEYS } from './context.js';
+import { deviceIdFrom } from './device-storage.js';
+import { planAllows, readSettings, resolveApiHost } from './settings.js';
+
+export { DEFAULT_API_HOST } from './settings.js';
+
+import {
+	detectNavigationTrigger,
+	PAGE_TYPES,
+	pruneProperties,
+} from './shape.js';
+import {
+	configureStorageNames,
+	migrateLegacyStorage,
+	storageKey,
+	storageName,
+} from './storage-scope.js';
+import { VERSION } from './version.js';
+
+/** Option key that lets the withdrawal record through a gate that is about to close. */
+const WITHDRAWAL_FLAG = 'thg_hp_consent_withdrawal';
+/**
+ * The device id a withdrawal withdraws, taken when it is announced: analytics-next runs the plugin
+ * later, after the refusal has forgotten that id.
+ */
+const WITHDRAWN_AS = 'thg_hp_withdrawn_as';
+
+/** Context keys analytics-next fills itself; the spec's versions (scrubbed, site locale) replace them. */
+const LIBRARY_OWNED = new Set([
+	'library',
+	'page',
+	'campaign',
+	'locale',
+	'device',
+	'timezone',
+]);
+
+/** Never taken from a caller: consent comes from the gate, the rest is server-owned. */
+const NOT_OVERRIDABLE = new Set([
+	'spec',
+	'consent',
+	'identity_trust',
+	'ip',
+	'bot',
+	'original_timestamp',
+]);
+
+const PAGE_PROPERTY_FIELDS = [
+	'url',
+	'path',
+	'search',
+	'referrer',
+	'title',
+	'type',
+];
+
+const EVENT_TYPES = ['track', 'page', 'identify', 'screen', 'group', 'alias'];
+
+/**
+ * A cancellation analytics-next will not retry.
+ *
+ * Built from the host's own ContextCancelation class, reached through ctx.cancel(), rather than
+ * imported: the queue checks `instanceof`, and a second copy of analytics-core in the bundle would
+ * make our cancellation look like an ordinary error, which it retries.
+ */
+function cancellation(ctx, reason) {
+	try {
+		ctx.cancel();
+	} catch (err) {
+		const Cancelation = err?.constructor;
+		if (typeof Cancelation === 'function')
+			return new Cancelation({ retry: false, type: 'thg_hp', reason });
+	}
+	return new Error(reason);
+}
+
+/**
+ * `disable` for AnalyticsBrowser.load: true unless the settings response switches the key on. A
+ * response with no `hp` block at all (inline `cdnSettings` in development) is not a refusal.
+ */
+export function hpDisabled(cdnSettings) {
+	return cdnSettings?.hp !== undefined && !readSettings(cdnSettings).enabled;
+}
+
+/**
+ * The second argument of AnalyticsBrowser.load for a `cdnURL` at the apiHost.
+ *
+ * analytics-next takes its delivery host and the write key it puts in every body from the settings'
+ * `integrations['Segment.io']` block, and without one sends to api.segment.io — its own telemetry
+ * too. The gateway's settings carry that block, pointing at the collection host, so a page that
+ * sets only `cdnURL` already delivers to us. This keeps the settings' block when there is one and
+ * writes the same block from `apiHost` when there is not (inline `cdnSettings`, a key the settings
+ * do not enable), turns telemetry off, makes a key the settings do not enable a no-op, and keeps
+ * analytics-next from writing its own id cookies: it would write them before the consent plugin runs.
+ *
+ * @param {{ writeKey: string, apiHost?: string }} config The same config bootstrap() takes.
+ */
+export function hpLoadOptions({ writeKey, apiHost }) {
+	return {
+		disable: hpDisabled,
+		disableClientPersistence: true,
+		updateCDNSettings(cdnSettings) {
+			const integrations = { ...cdnSettings.integrations };
+			if (!integrations['Segment.io']?.apiHost) {
+				const origin =
+					readSettings(cdnSettings).apiHost ?? resolveApiHost(apiHost);
+				if (!origin) return cdnSettings;
+				const { protocol, host } = new URL(origin);
+				integrations['Segment.io'] = {
+					apiKey: writeKey,
+					apiHost: `${host}/v1`,
+					protocol: protocol.replace(':', ''),
+				};
+			}
+			return {
+				...cdnSettings,
+				integrations,
+				metrics: { ...cdnSettings.metrics, sampleRate: 0 },
+			};
+		},
+	};
+}
+
+/**
+ * @param {object} options Same names and meanings as createAnalytics().
+ * @param {string} [options.propertyId] For a key scoped to several properties, or without settings:
+ *   the `hp` block's propertyId wins when it has one.
+ * @param {string} [options.channel]
+ * @param {string} [options.market]
+ * @param {string} [options.environment]
+ * @param {string} [options.currency]
+ * @param {string} [options.locale]
+ * @param {string} [options.country]
+ * @param {string} [options.shipToCountry]
+ * @param {() => string|null} [options.getCurrency] Read per event; wins over `currency`.
+ * @param {() => string|null} [options.getShipToCountry] Read per event; wins over `shipToCountry`.
+ * @param {() => string|null} [options.getLocale] Read per event; wins over `locale`.
+ * @param {import('./consent.js').ConsentAdapter} [options.consent]
+ * @param {number} [options.consentTimeoutMs]
+ * @param {string} [options.consentCookieDomain]
+ * @param {object} [options.storageNames] Renames what is stored; see storage-scope.js.
+ * @param {string[]} [options.queryParamAllowlist] Only without settings: the `hp` block's wins.
+ * @param {string[]} [options.queryParamBlocklist]
+ * @param {string[]} [options.sensitiveParamAllowlist]
+ * @param {() => string|null} [options.getAnonymousId] Pin analytics-next to the site's device id.
+ *   The settings' `hp.anonymousId` decides where device ids come from (3.6): a site cookie they
+ *   name, or Hyper-Personalisation's cookie, replaces it.
+ * @param {object} [options.anonymousIdSource] Only without settings: the `hp` block's wins.
+ * @param {() => string|null} [options.getPageType]
+ * @param {() => string|null} [options.getSessionId]
+ * @param {() => string|null} [options.getRenderId]
+ * @param {() => object|null} [options.getExtensions]
+ * @param {() => object[]|null} [options.getExperiments]
+ * @param {() => object[]|null} [options.getAudiences]
+ * @param {() => object[]|null} [options.getDecisions]
+ * @param {() => object[]|null} [options.getRecommendations]
+ * @returns {object[]} analytics-next plugins
+ */
+export function cdpPlugins(options = {}) {
+	const cfg = { queryParamBlocklist: [], consentTimeoutMs: 5000, ...options };
+	let gate = null;
+	let pageType = null;
+	let lastPageMessageId = null;
+	let prevPageKey = null;
+	let off = null;
+	let device = null;
+
+	cfg.getConsent = () => (gate ? gate.stamp() : hostConsent());
+
+	/**
+	 * Once, at the first plugin load: the tenant's settings from the response analytics-next
+	 * fetched, over the local options. Everything tenant-level comes from there; without an `hp`
+	 * block (inline cdnSettings in development) the local options stand.
+	 */
+	function configure(analytics) {
+		if (off !== null) return;
+		const cdnSettings = analytics?.settings?.cdnSettings;
+		if (cdnSettings?.hp !== undefined) {
+			const settings = readSettings(cdnSettings);
+			if (settings.enabled) {
+				cfg.propertyId = settings.propertyId ?? cfg.propertyId;
+				cfg.environment = settings.environment;
+				if (settings.queryParamAllowlist)
+					cfg.queryParamAllowlist = settings.queryParamAllowlist;
+				if (settings.anonymousId) cfg.anonymousIdSource = settings.anonymousId;
+				cfg.plan = settings.plan;
+				if (cfg.consent)
+					cfg.consent = reportingPurposes(
+						cfg.consent,
+						settings.consentPurposes,
+					);
+			} else {
+				cfg.propertyId = null;
+			}
+		}
+		off = !cfg.propertyId;
+		if (off) return;
+		configureStorageNames(cfg.storageNames);
+		migrateLegacyStorage();
+		prevPageKey = storageKey(storageName('previousPage'), cfg.propertyId);
+		device = deviceIdFrom(cfg, {
+			mayStore: () => !cfg.consent || gate?.status === 'granted',
+		});
+	}
+
+	function admit(ctx) {
+		const context = ctx.event.context ?? {};
+		const forced = context[WITHDRAWAL_FLAG] === true;
+		const withdrawnAs = context[WITHDRAWN_AS];
+		delete context[WITHDRAWAL_FLAG];
+		delete context[WITHDRAWN_AS];
+
+		if (off) throw cancellation(ctx, 'not enabled for this write key');
+		if (ctx.event.type === 'track' && !planAllows(cfg.plan, ctx.event.event)) {
+			throw cancellation(ctx, 'disabled by the tracking plan');
+		}
+
+		const anonymousId =
+			forced && withdrawnAs ? withdrawnAs : cfg.getAnonymousId?.();
+		if (anonymousId) ctx.updateEvent('anonymousId', String(anonymousId));
+
+		if (!gate || forced || gate.admits()) return ctx;
+		// Still unanswered, before or after the timeout: held until the CMP answers.
+		if (gate.status !== 'pending' && gate.status !== 'unknown')
+			throw cancellation(ctx, `consent ${gate.status}`);
+		// Holding one event pauses analytics-next's queue behind it, which keeps order and means
+		// nothing else is sent before the answer either.
+		return new Promise((resolve, reject) => {
+			gate.hold({
+				resolve: () => resolve(ctx),
+				reject: () => reject(cancellation(ctx, 'consent not granted')),
+			});
+		});
+	}
+
+	const readPreviousPage = () => {
+		if (lastPageMessageId) return lastPageMessageId;
+		try {
+			return sessionStorage.getItem(prevPageKey) || null;
+		} catch {
+			return null;
+		}
+	};
+
+	const writePreviousPage = (id) => {
+		lastPageMessageId = id;
+		if (gate && gate.status !== 'granted') return;
+		try {
+			sessionStorage.setItem(prevPageKey, id);
+		} catch {
+			/* the chain still holds within this document */
+		}
+	};
+
+	function shapePage(event) {
+		const props = event.properties ?? {};
+		if (PAGE_TYPES.has(props.type)) pageType = props.type;
+		for (const field of PAGE_PROPERTY_FIELDS) delete props[field];
+		if (event.category != null) props.category ??= event.category;
+		delete event.category;
+		props.navigation_trigger ??= detectNavigationTrigger();
+		props.previous_message_id ??= readPreviousPage();
+		writePreviousPage(event.messageId);
+		event.properties = props;
+	}
+
+	function enrich(ctx) {
+		const event = ctx.event;
+		if (event.type === 'page') shapePage(event);
+
+		const theirs = event.context ?? {};
+		const ours = buildContext({
+			...cfg,
+			pageType: cfg.getPageType?.() ?? pageType,
+		});
+		const context = {};
+		for (const key of CONTEXT_KEYS) {
+			const override =
+				!LIBRARY_OWNED.has(key) &&
+				!NOT_OVERRIDABLE.has(key) &&
+				theirs[key] !== undefined;
+			context[key] = override ? theirs[key] : ours[key];
+		}
+		context.library = theirs.library ?? {
+			name: '@thg-agentic/hyper-personalisation-web/segment',
+			version: VERSION,
+		};
+		context.identity_trust = event.anonymousId ? 'device' : 'none';
+		event.context = context;
+
+		if (event.properties) event.properties = pruneProperties(event.properties);
+		return ctx;
+	}
+
+	const hooks = (fn) =>
+		Object.fromEntries(EVENT_TYPES.map((type) => [type, fn]));
+
+	const consentPlugin = {
+		name: 'THG Hyper-Personalisation Consent',
+		type: 'before',
+		version: VERSION,
+		isLoaded: () => true,
+		load(_ctx, analytics) {
+			configure(analytics);
+			if (off || !cfg.consent) return Promise.resolve();
+			gate = createConsentGate({
+				adapter: cfg.consent,
+				timeoutMs: cfg.consentTimeoutMs,
+				cookieDomain: cfg.consentCookieDomain,
+				debug: cfg.debug,
+				release: (item) => item.resolve(),
+				discard: (item) => item.reject(),
+				onStatus(status) {
+					if (status === 'granted') {
+						device?.persist();
+						if (lastPageMessageId) writePreviousPage(lastPageMessageId);
+					}
+					if (status === 'denied') device?.forget();
+				},
+				announce({ action, state, withdrawal }) {
+					analytics.track(
+						'Consent Updated',
+						{ action, state },
+						withdrawal
+							? {
+									[WITHDRAWAL_FLAG]: true,
+									[WITHDRAWN_AS]: cfg.getAnonymousId?.() ?? null,
+								}
+							: undefined,
+					);
+				},
+			});
+			gate.start();
+			return Promise.resolve();
+		},
+		unload() {
+			gate?.stop();
+		},
+		...hooks(admit),
+	};
+
+	const contextPlugin = {
+		name: 'THG Hyper-Personalisation Context',
+		type: 'enrichment',
+		version: VERSION,
+		isLoaded: () => true,
+		load(_ctx, analytics) {
+			configure(analytics);
+			return Promise.resolve();
+		},
+		...hooks(enrich),
+	};
+
+	return [consentPlugin, contextPlugin];
+}

package/src/session/category.js

@@ -0,0 +1,40 @@
+/** One spelling for a category: `Apparel / Clothing`, `/apparel/clothing/` → `apparel/clothing`. */
+export function categoryKey(value) {
+	return value
+		.trim()
+		.toLowerCase()
+		.replace(/\s*\/\s*/g, '/')
+		.replace(/^\/+|\/+$/g, '');
+}
+
+/**
+ * Matches the warehouse's `cdp_path_prefix(..., 2)`: a dimension must be mutually exclusive to be
+ * worth a share, and uncut sub-paths would split one interest across several.
+ */
+const CATEGORY_DEPTH = 2;
+
+/**
+ * How many category interactions an affinity is measured over: the session-scale counterpart of
+ * the warehouse's affinity half-life.
+ */
+export const AFFINITY_WINDOW = 12;
+
+/**
+ * A category path cut to its first `depth` segments: the browser's `cdp_path_prefix`.
+ *
+ * Kept apart from `categoryKey` so both sides compose the same two primitives, which
+ * `assert_category_key_matches_sdk` checks.
+ */
+export function pathPrefix(value, depth = CATEGORY_DEPTH) {
+	return value.split('/').slice(0, depth).join('/');
+}
+
+/** Record one interaction with a category, oldest falling off the end. Returns the key used. */
+export function bump(trail, value) {
+	if (typeof value !== 'string' || !value.trim()) return null;
+	const key = pathPrefix(categoryKey(value));
+	if (!key) return null;
+	trail.unshift(key);
+	trail.length = Math.min(trail.length, AFFINITY_WINDOW);
+	return key;
+}