@thg-agentic/hyper-personalisation-web 3.22.2 → 3.24.0

package/src/index.js

@@ -45,7 +45,13 @@
 import { assignmentSession, surfaceExposureToken } from './assignment.js';
 import { hostConsent, servingHeaders } from './consent.js';
 import { createConsentGate } from './consent-gate.js';
-import { buildContext, getCookie, perRequest, scrubHref } from './context.js';
+import {
+	buildContext,
+	getCookie,
+	localeTag,
+	perRequest,
+	scrubHref,
+} from './context.js';
 import { createDecisionMemory, servedDecisions } from './decisions.js';
 import { createHeldStore, deviceIdFrom } from './device-storage.js';
 import {
@@ -109,6 +115,10 @@ 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');
+/** How ./onsite reads what it needs from a client it was handed. Not public API. */
+const ONSITE_ACCESS = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite-access',
+);
 
 /** SHA-256 of a string as lowercase hex. Synchronous since 3.9 (sha256Hex); kept async for callers. */
 export async function sha256(value) {
@@ -426,8 +436,34 @@ export function createAnalytics(options) {
 	/** The call being replayed: its first event keeps the messageId and time it was made with. */
 	let replaying = null;
 
+	/**
+	 * The basket this page last reported, in memory only: what a basket bar on this page shows,
+	 * whatever the consent, since it is the shopper's own basket on screen and nothing is kept.
+	 * Noted before the plan, the sample or beforeSend can drop the event.
+	 */
+	let pageBasket = null;
+	const basketListeners = new Set();
+	/** Told once the consent banner is answered, granted or denied (./onsite). */
+	const consentListeners = new Set();
+
+	function noteBasket(partial) {
+		if (partial.type !== 'track' || partial.event !== 'Cart Updated') return;
+		const value = partial.properties?.value;
+		pageBasket =
+			typeof value === 'number' && Number.isFinite(value) && value >= 0
+				? value
+				: null;
+		for (const listener of basketListeners)
+			try {
+				listener();
+			} catch (err) {
+				console.warn('[hp] a basket listener failed', err);
+			}
+	}
+
 	/** Tracking never throws into the host: an event that fails to build or deliver is dropped. */
 	function emit(partial, ctxOverrides, force = false) {
+		noteBasket(partial);
 		try {
 			return compose(partial, ctxOverrides, force);
 		} catch (err) {
@@ -650,6 +686,13 @@ export function createAnalytics(options) {
 				} catch (err) {
 					console.warn('[hp] onConsentStatus observer failed', err);
 				}
+				if (status === 'granted' || status === 'denied')
+					for (const listener of consentListeners)
+						try {
+							listener();
+						} catch (err) {
+							console.warn('[hp] a consent listener failed', err);
+						}
 			},
 			announce({ action, state, previous, withdrawal }) {
 				// Withdrawn here, not only when the next event reaches recordVisit: a beforeSend that drops
@@ -674,15 +717,15 @@ export function createAnalytics(options) {
 		gate.start();
 	}
 
+	/** The property's holdout split from the settings, as a serving response would state it. */
+	const configuredShares = () =>
+		cfg.holdout ? holdoutShares(cfg.holdout) : null;
+
 	/**
 	 * 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;
@@ -967,6 +1010,11 @@ export function createAnalytics(options) {
 		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),
+		/**
+		 * Answers to an approved preference question, given in the account area, a quiz or an onsite
+		 * step after the sign-up. Answers sent with an onsite sign-up are the gateway's to report.
+		 */
+		preferencesStated: (p, c) => track('Preferences Stated', 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),
@@ -1003,6 +1051,53 @@ export function createAnalytics(options) {
 		get anonymousId() {
 			return realId(perRequest(cfg.getAnonymousId, null));
 		},
+		/** What ./onsite needs from this client: hosts, ids, consent and settings. Not public API. */
+		[ONSITE_ACCESS]() {
+			return {
+				writeKey: cfg.writeKey,
+				storageKey: storageKey(storageName('onsite'), cfg.propertyId),
+				gatewayHost: cfg.apiHost,
+				servingHost: cfg.servingHost ?? cfg.apiHost,
+				settings: cfg.onsite ?? null,
+				debug: cfg.debug === true,
+				preview: previewing,
+				anonymousId: () => realId(perRequest(cfg.getAnonymousId, null)),
+				sessionId: () => realId(perRequest(cfg.getSessionId, null)),
+				analytics: granted,
+				personalisation: personalisationGranted,
+				consent: () => cfg.getConsent(),
+				headers: () => servingHeaders(gate?.state ?? null),
+				pageUrl: () =>
+					typeof location === 'undefined'
+						? null
+						: scrubHref(location.href, cfg),
+				locale: () => localeTag(perRequest(cfg.getLocale, cfg.locale)),
+				/**
+				 * A basket bar's progress: the basket this page reported, else the last one this visit
+				 * kept (under personalisation consent), else null.
+				 */
+				basketValue: () => {
+					const value = getSessionSignals().basketValue;
+					return pageBasket ?? (Number.isFinite(value) ? value : null);
+				},
+				/** Calls `listener` whenever the page reports its basket; answers how to stop. */
+				onBasket: (listener) => {
+					basketListeners.add(listener);
+					return () => basketListeners.delete(listener);
+				},
+				/**
+				 * Whether the consent banner is answered. Without a consent adapter there is no banner to
+				 * wait for, so it is.
+				 */
+				consentAnswered: () =>
+					!gate || gate.status === 'granted' || gate.status === 'denied',
+				/** Calls `listener` once the banner is answered; answers how to stop. */
+				onConsentAnswered: (listener) => {
+					consentListeners.add(listener);
+					return () => consentListeners.delete(listener);
+				},
+			};
+		},
 		/** `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;

package/src/onsite/answers-loader.js

@@ -0,0 +1,6 @@
+/**
+ * Date and number fields, only for a form that asks one: a bundler splits this import out of
+ * ./onsite, and the CDN build swaps this module for cdn/answers-loader.js, which loads
+ * dist/onsite-answers.min.js.
+ */
+export const loadAnswers = () => import('./answers.js');

package/src/onsite/answers.js

@@ -0,0 +1,177 @@
+/**
+ * Date and number questions in an onsite form (ADR 0064 part 6): their fields, and the answer each
+ * holds in its stored form (packages/control-plane/src/onsite/question-answers.ts), which the
+ * gateway checks again and never takes from the browser on trust.
+ *
+ * A birthday is a day and a month, and a year when asked, as separate fields (Klaviyo's birthday
+ * block; GOV.UK's date input for a date someone knows, never a calendar): `--MM-DD` without the
+ * year, `YYYY-MM-DD` with it. Any other date is the browser's own date field. A number is a text
+ * field with a numeric keyboard, which takes a comma for the point.
+ */
+
+import { select } from './rules.js';
+
+const pad = (n) => String(n).padStart(2, '0');
+const OLDEST_AGE = 120;
+/** The gateway's limits (question-answers.ts): the digits a number may have, and its size. */
+const NUMBER = /^-?\d{1,10}(?:\.(\d{1,10}))?$/;
+const NUMBER_LIMIT = 1e9;
+
+/** The locale's word for a month, and whether it writes the month before the day (en-US). */
+function calendar(locale) {
+	try {
+		const months = new Intl.DateTimeFormat(locale, {
+			month: 'long',
+			timeZone: 'UTC',
+		});
+		return {
+			name: (m) => months.format(Date.UTC(2016, m - 1, 1)),
+			monthFirst:
+				new Intl.DateTimeFormat(locale, { month: 'numeric', day: 'numeric' })
+					.formatToParts(0)
+					.find((p) => p.type !== 'literal')?.type === 'month',
+		};
+	} catch {
+		return { name: String, monthFirst: false };
+	}
+}
+
+const pick = (make, name, label, count, text, chosen) => {
+	const s = select(
+		make,
+		label,
+		label,
+		Array.from({ length: count }, (_, i) => [pad(i + 1), text(i + 1)]),
+		chosen,
+	);
+	s.name = name;
+	return s;
+};
+
+function input(make, name, label, mode, value) {
+	const i = make('input', 'i');
+	i.name = name;
+	i.inputMode = mode;
+	i.setAttribute('aria-label', label);
+	i.value = value ?? '';
+	return i;
+}
+
+/**
+ * The fields of a date or number question, into its fieldset, holding `value` when there is one. A
+ * birthday's day and month are ordered and named as `locale` writes them (the form's, else the
+ * page's language).
+ */
+export function answerFields(set, q, make, value, locale) {
+	const f = q.format ?? {};
+	const row = make('div', f.kind === 'birthday' ? 'ph bd' : 'ph');
+	if (q.type === 'number') {
+		row.append(
+			input(make, 'hp_v', q.label, f.decimals ? 'decimal' : 'numeric', value),
+		);
+		if (f.unit) row.append(make('span', 'u', f.unit));
+	} else if (f.kind === 'birthday') {
+		const [, y, m, d] = /^(\d{4}|-)-(\d\d)-(\d\d)$/.exec(value ?? '') ?? [];
+		const c = calendar(locale || undefined);
+		const day = pick(make, 'hp_d', 'Day', 31, String, d);
+		const month = pick(make, 'hp_m', 'Month', 12, c.name, m);
+		row.append(...(c.monthFirst ? [month, day] : [day, month]));
+		if (f.year !== 'none') {
+			const year = input(make, 'hp_y', 'Year', 'numeric', y === '-' ? '' : y);
+			// Said on the field itself, not only to a screen reader.
+			year.placeholder = f.year === 'required' ? 'Year' : 'Year (optional)';
+			year.autocomplete = 'bday-year';
+			year.maxLength = 4;
+			row.append(year);
+		}
+	} else {
+		const i = input(make, 'hp_v', q.label, 'none', value);
+		i.type = 'date';
+		i.min = '1900-01-01';
+		i.max = '2100-12-31';
+		row.append(i);
+	}
+	set.append(row);
+}
+
+/** A number as the form's language writes it, else as the browser's does. */
+function written(n, locale) {
+	try {
+		return new Intl.NumberFormat(locale || undefined).format(n);
+	} catch {
+		return String(n);
+	}
+}
+
+const realDate = (y, m, d) => {
+	const t = new Date(Date.UTC(y, m - 1, d));
+	return t.getUTCMonth() === m - 1 && t.getUTCDate() === d;
+};
+
+/**
+ * A typed number as `Number` reads it. Spaces go; with both a point and a comma, the last is the
+ * decimal mark and the other groups thousands; a comma before groups of exactly three digits groups
+ * them (`10,000`); any other comma is the decimal mark (`7,5`).
+ */
+export function plainNumber(typed) {
+	const text = typed.replace(/\s/g, '');
+	const comma = text.lastIndexOf(',');
+	const point = text.lastIndexOf('.');
+	if (comma >= 0 && point >= 0)
+		return comma > point
+			? text.replace(/\./g, '').replace(',', '.')
+			: text.replace(/,/g, '');
+	if (/^-?\d{1,3}(?:,\d{3})+$/.test(text)) return text.replace(/,/g, '');
+	return text.replace(',', '.');
+}
+
+/**
+ * The fieldset's answer: `{ value }` (null when it was left empty), or `{ error, input }` for what
+ * the shopper has to correct, its numbers written as `locale` writes them (50,000).
+ */
+export function answerOf(set, q, now = Date.now(), locale = undefined) {
+	const f = q.format ?? {};
+	const at = (name) => set.querySelector(`[name=${name}]`);
+	if (q.type === 'number') {
+		const i = at('hp_v');
+		const text = plainNumber(i.value);
+		if (!text) return { value: null };
+		const n = Number(text);
+		const match = NUMBER.exec(text);
+		return match &&
+			(match[1]?.replace(/0+$/, '').length ?? 0) <= (f.decimals ? 2 : 0) &&
+			Math.abs(n) <= NUMBER_LIMIT &&
+			!(n < f.min || n > f.max)
+			? { value: String(n === 0 ? 0 : n) }
+			: {
+					error: `Enter a ${f.decimals ? '' : 'whole '}number${f.min != null && f.max != null ? ` from ${written(f.min, locale)} to ${written(f.max, locale)}` : ''}.`,
+					input: i,
+				};
+	}
+	const wrong = (input) => ({ error: 'Enter a real date.', input });
+	if (f.kind !== 'birthday') {
+		const i = at('hp_v');
+		if (!i.value) return { value: null };
+		return i.value >= i.min && i.value <= i.max ? { value: i.value } : wrong(i);
+	}
+	const [d, m, y] = ['hp_d', 'hp_m', 'hp_y'].map(at);
+	const year = y?.value.trim() ?? '';
+	if (!d.value && !m.value && !year) return { value: null };
+	if (!d.value || !m.value) return wrong(d.value ? m : d);
+	if (!year)
+		return f.year === 'required' || !realDate(2016, +m.value, +d.value)
+			? wrong(y ?? d)
+			: { value: `--${m.value}-${d.value}` };
+	const value = `${year}-${m.value}-${d.value}`;
+	// The gateway's own bounds (question-answers.ts dateAnswer): up to tomorrow, anywhere on Earth,
+	// and no earlier than this day OLDEST_AGE years ago, so a date taken here is never refused there.
+	const today = new Date(now).toISOString().slice(0, 10);
+	const latest = new Date(now + 86_400_000).toISOString().slice(0, 10);
+	const earliest = `${+today.slice(0, 4) - OLDEST_AGE}${today.slice(4)}`;
+	return /^\d{4}$/.test(year) &&
+		realDate(+year, +m.value, +d.value) &&
+		value <= latest &&
+		value >= earliest
+		? { value }
+		: wrong(y);
+}

package/src/onsite/api.js

@@ -0,0 +1,93 @@
+/**
+ * The five calls a form makes, each authenticated with the page's publishable key and never with a
+ * cookie: `POST /v1/decisions` and `POST /v1/offers/claim` on the public API (with `hp-consent`, as
+ * every serving request), `GET /v1/capture/challenge`, `POST /v1/capture` and
+ * `POST /v1/capture/answers` on the ingest gateway.
+ * Every call resolves, to `{ status, body }` (status 0 when the network failed).
+ */
+
+const DEFAULT_CHALLENGE = '/v1/capture/challenge';
+
+/** The settings' challenge path, only when it is a path on the gateway. */
+const challengePath = (path) =>
+	typeof path === 'string' && /^\/v1\/[\w/-]+$/.test(path)
+		? path
+		: DEFAULT_CHALLENGE;
+
+/** How long one claim request may take before it counts as failed. */
+const CLAIM_TIMEOUT_MS = 8000;
+
+/**
+ * @param {object} access What the client exposes to ./onsite (index.js, ONSITE_ACCESS).
+ * @param {{ servingHost?: string, gatewayHost?: string, fetch?: typeof fetch, challenge?: string }} [options]
+ */
+export function createApi(access, options = {}) {
+	const doFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
+	const serving = options.servingHost ?? access.servingHost;
+	const gateway = options.gatewayHost ?? access.gatewayHost;
+
+	async function call(
+		url,
+		{ method = 'GET', body, consent = false, timeoutMs } = {},
+	) {
+		if (!doFetch) return { status: 0, body: null };
+		try {
+			const res = await doFetch(url, {
+				method,
+				credentials: 'omit',
+				signal: timeoutMs && AbortSignal.timeout?.(timeoutMs),
+				headers: {
+					accept: 'application/json',
+					authorization: `Bearer ${access.writeKey}`,
+					...(body ? { 'content-type': 'application/json' } : {}),
+					...(consent ? access.headers() : {}),
+				},
+				...(body ? { body: JSON.stringify(body) } : {}),
+			});
+			let parsed = null;
+			try {
+				parsed = await res.json();
+			} catch {
+				/* no body */
+			}
+			return { status: res.status, body: parsed };
+		} catch {
+			return { status: 0, body: null };
+		}
+	}
+
+	return {
+		/** The decision for one slot, as the page's other serving calls ask for it, with its pin. */
+		decide: (slot, pin) =>
+			call(`${serving}/v1/decisions`, {
+				method: 'POST',
+				consent: true,
+				body: {
+					slots: [
+						pin
+							? {
+									key: slot,
+									pin: { experiment: pin[0], arm: pin[1], split: pin[2] },
+								}
+							: slot,
+					],
+					identifier_value: access.anonymousId() ?? undefined,
+					session_id: access.sessionId() ?? undefined,
+					...(access.preview ? { preview: access.preview } : {}),
+				},
+			}),
+		challenge: () => call(`${gateway}${challengePath(options.challenge)}`),
+		capture: (body) => call(`${gateway}/v1/capture`, { method: 'POST', body }),
+		// Answers given after the email step, with its address and receipt.
+		answers: (body) =>
+			call(`${gateway}/v1/capture/answers`, { method: 'POST', body }),
+		// Bounded, so the page's `submitted`, which waits for the claim, always comes.
+		claim: (body) =>
+			call(`${serving}/v1/offers/claim`, {
+				method: 'POST',
+				consent: true,
+				body,
+				timeoutMs: CLAIM_TIMEOUT_MS,
+			}),
+	};
+}

package/src/onsite/counters.js

@@ -0,0 +1,144 @@
+/**
+ * What the caps count, per slot, as opaque numbers: shows this session (sessionStorage), and shows
+ * ever, when it was last closed and whether it was submitted (localStorage), plus one subscribed
+ * flag, whether a teaser's tab is out, when a covering form last showed and the version an A/B test
+ * pinned for the visit (sessionStorage), and the
+ * last code this browser claimed, for a promo reminder. Never an address, a number or an answer.
+ * Every access is wrapped: without storage the caps hold for the page view only.
+ *
+ * The counts follow what the shopper did (saw, closed, signed up) and serve only the caps: UI
+ * preference storage, set before consent like Wisepops and Klaviyo (ICO, the strictly necessary
+ * exception). The subscribed flag and the claimed code mark the shopper rather than the form, so
+ * they outlive the visit only with personalisation consent; without it they hold for the session.
+ */
+
+function store(get, key) {
+	let memory = {};
+	const read = () => {
+		try {
+			const parsed = JSON.parse(get().getItem(key));
+			if (parsed && typeof parsed === 'object') memory = parsed;
+		} catch {
+			/* no storage, or not ours: what is in memory */
+		}
+		return memory;
+	};
+	const write = (change) => {
+		const next = read();
+		change(next);
+		memory = next;
+		try {
+			get().setItem(key, JSON.stringify(next));
+		} catch {
+			/* kept in memory for this page */
+		}
+	};
+	return { read, write };
+}
+
+/**
+ * @param {string} key The storage key, storageName('onsite') scoped to the property.
+ * @param {() => boolean} [keep] Whether the shopper's own markers may outlive the visit.
+ */
+export function createCounters(key, keep = () => true) {
+	const session = store(() => sessionStorage, key);
+	const local = store(() => localStorage, key);
+	/** Where a new marker goes: the browser's store while consent holds, else the visit's. */
+	const own = () => (keep() ? local : session);
+	/** Consent withdrawn: the markers an earlier consented visit kept are forgotten. */
+	const forgetKept = () => {
+		const kept = local.read();
+		if (kept.sub !== undefined || kept.k !== undefined)
+			local.write((all) => {
+				delete all.sub;
+				delete all.k;
+			});
+	};
+	/** The stores the shopper's markers are read from: the browser's only while consent holds. */
+	const markers = () => {
+		if (keep()) return [session.read(), local.read()];
+		forgetKept();
+		return [session.read()];
+	};
+	const slotOf = (all, slot) => {
+		all.f ??= {};
+		all.f[slot] ??= {};
+		return all.f[slot];
+	};
+
+	return {
+		/** `{ session, lifetime, closedAt, submitted }` for `slot`. */
+		seen(slot) {
+			const ever = local.read().f?.[slot] ?? {};
+			return {
+				session: session.read().f?.[slot]?.n ?? 0,
+				lifetime: ever.n ?? 0,
+				closedAt: ever.c ?? null,
+				submitted: ever.s === 1,
+			};
+		},
+		subscribed: () => markers().some((all) => all.sub === 1),
+		shown(slot) {
+			session.write((all) => {
+				const s = slotOf(all, slot);
+				s.n = (s.n ?? 0) + 1;
+			});
+			local.write((all) => {
+				const s = slotOf(all, slot);
+				s.n = (s.n ?? 0) + 1;
+			});
+		},
+		closed(slot, now = Date.now()) {
+			local.write((all) => {
+				slotOf(all, slot).c = now;
+			});
+		},
+		/** Whether a teaser's tab is out, unopened and undismissed: it is kept across pages. */
+		tab(slot, on) {
+			session.write((all) => {
+				const s = slotOf(all, slot);
+				if (on) s.t = 1;
+				else delete s.t;
+			});
+		},
+		tabOut: (slot) => session.read().f?.[slot]?.t === 1,
+		/**
+		 * `[test, arm, split]`: the version this visit was shown in the slot's A/B test (ADR 0065), sent back
+		 * with the next decision so the visit keeps it. Only an arm decided in a test has one.
+		 */
+		pin(slot, value) {
+			if (value === undefined) return session.read().f?.[slot]?.p ?? null;
+			session.write((all) => {
+				slotOf(all, slot).p = value;
+			});
+		},
+		/** When a covering form last showed this session, for the property's gap between them. */
+		coveredAt: () => session.read().o ?? null,
+		covered(now = Date.now()) {
+			session.write((all) => {
+				all.o = now;
+			});
+		},
+		/** The last code this browser claimed, kept 14 days for a reminder; never an address. */
+		code(value, now = Date.now()) {
+			if (value === undefined) {
+				const [kept] = markers()
+					.flatMap((all) => (all.k ? [all.k] : []))
+					.sort((a, b) => b.at - a.at);
+				return kept && now - kept.at < 14 * 86_400_000 ? kept.c : null;
+			}
+			own().write((all) => {
+				all.k = { c: value, at: now };
+			});
+			return value;
+		},
+		submitted(slot) {
+			local.write((all) => {
+				slotOf(all, slot).s = 1;
+			});
+			own().write((all) => {
+				all.sub = 1;
+			});
+		},
+	};
+}