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

package/src/onsite/index.js

@@ -0,0 +1,525 @@
+/**
+ * Onsite forms (ADR 0064): sign-up popups, bars, teasers, inline forms and spin-to-win, shown by
+ * the settings' `hp.onsite` index and decided by the server.
+ *
+ *   import { startOnsite } from '@thg-agentic/hyper-personalisation-web/onsite';
+ *   startOnsite(hp); // the client bootstrap resolved to, or pass `onsite: true` to bootstrap
+ *
+ * The browser judges the trigger; the server decides the rest. Each live form's trigger is watched
+ * here, with its pages, devices, dates and caps. When one fires, `POST /v1/decisions` is asked for
+ * that one slot: a held-out visitor, or no decision, shows nothing. One overlay per page view, the
+ * highest priority among those that fire within 50 ms; one that cannot show passes to the next, but
+ * a held-out visitor sees none, and once one has shown, closing it lets no other in; with the
+ * property's `overlay_gap_minutes`, none until that long after the last one this session. A form
+ * the site opens on the shopper's click (`manual`) is past the caps, the gap and the allowance. `?hp_debug=onsite` logs why each form did
+ * or did not show; `hp.onsite.debug()` returns it. The renderer (./render.js, its own chunk) is
+ * fetched only once a trigger fires, alongside the decision request; a page whose forms never fire
+ * never downloads it.
+ */
+
+import { loadAnswers } from './answers-loader.js';
+import { createApi } from './api.js';
+import { createCounters } from './counters.js';
+import { loadRender } from './render-loader.js';
+import {
+	ASKED,
+	blockers,
+	byPriority,
+	deviceOf,
+	INTERRUPTS,
+	OVERLAY,
+	readCreative,
+	readForm,
+} from './rules.js';
+import { watch } from './triggers.js';
+import { loadWheel } from './wheel-loader.js';
+
+const ACCESS = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite-access',
+);
+const CONTROLLER = Symbol.for('@thg-agentic/hyper-personalisation-web.onsite');
+const PENDING = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.pending',
+);
+const LISTENERS = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.listeners',
+);
+const SUPPRESSED = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.suppressed',
+);
+
+/** A preview link's counters: a trader's visit counts nothing and is capped by nothing. */
+const INERT = {
+	seen: () => ({ session: 0, lifetime: 0, closedAt: null, submitted: false }),
+	subscribed: () => false,
+	shown() {},
+	closed() {},
+	submitted() {},
+	tab() {},
+	tabOut: () => false,
+	pin: () => null,
+	coveredAt: () => null,
+	covered() {},
+	code: () => null,
+};
+
+/** How long a fired trigger waits for others, so two forms entering together show the higher priority. */
+const FIRE_WINDOW_MS = 50;
+/** The longest a form waits for its first step's pictures before it opens without them. */
+const WARM_MS = 300;
+
+const debugParam = () => {
+	try {
+		return new URLSearchParams(location.search).get('hp_debug') === 'onsite';
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * Start onsite forms for `client`, once per page. Returns the controller, or null without a
+ * browser or a client from this SDK.
+ *
+ * @param {object} client The SDK client (bootstrap or createAnalytics).
+ * @param {import('../../types/onsite').OnsiteOptions} [options]
+ */
+export function startOnsite(client, options = {}) {
+	if (typeof window === 'undefined' || typeof document === 'undefined')
+		return null;
+	if (window[CONTROLLER]) return window[CONTROLLER];
+	const access =
+		typeof client?.[ACCESS] === 'function' ? client[ACCESS]() : null;
+	if (!access) {
+		console.warn(
+			'[hp] onsite: startOnsite needs the client bootstrap or createAnalytics made',
+		);
+		return null;
+	}
+	const settings = options.settings ?? access.settings ?? {};
+	const api = createApi(access, {
+		...options,
+		challenge: settings.capture?.challenge,
+	});
+	const counters = access.preview
+		? INERT
+		: createCounters(access.storageKey, access.personalisation);
+	const mounted = new Map();
+	const suppressed = () => window[SUPPRESSED]?.size > 0;
+
+	/** Tell the page's `hp.onsite.on` listeners; a listener that throws never reaches the form. */
+	const emit = (name, detail) => {
+		for (const fn of window[LISTENERS]?.[name] ?? []) {
+			try {
+				fn(detail);
+			} catch (err) {
+				console.warn(`[hp] onsite ${name} listener failed:`, err);
+			}
+		}
+	};
+	const device = deviceOf(window);
+	const logging = access.debug || options.debug === true || debugParam();
+	const trace = new Map();
+	const stops = new Map();
+	const forms = [];
+	for (const raw of Array.isArray(settings.forms) ? settings.forms : []) {
+		const form = readForm(raw);
+		if (form) forms.push(form);
+		else
+			trace.set(String(raw?.slot ?? `form ${trace.size + 1}`), {
+				slot: String(raw?.slot ?? ''),
+				state: 'invalid',
+				reasons: ['not a form this SDK can show'],
+			});
+	}
+	/**
+	 * The covering forms on screen or being opened, by slot (a bar and a popup the shopper asked for
+	 * can both be up), the slots being opened now, and the form that spent this page view's allowance.
+	 */
+	const covering = new Map();
+	const opening = new Map();
+	let spent = null;
+	/** The pictures warmed on this page view, by every form, so none is fetched twice. */
+	const warmed = new Set();
+	/**
+	 * The covering form that keeps `asked` (a form the shopper asked for, or not) off the screen. Any
+	 * covering form keeps one the page triggered away; one the shopper asked for waits only for a
+	 * form still being opened, or for a modal actually on screen (an expanded teaser is one), so it
+	 * opens over a bar or a teaser's tab.
+	 */
+	const blocker = (asked) => {
+		for (const slot of covering.keys()) {
+			const handle = mounted.get(slot);
+			if (!asked || !handle || handle.modal?.()) return slot;
+		}
+		return null;
+	};
+	let fired = [];
+	const gap = Number.isInteger(settings.overlay_gap_minutes)
+		? settings.overlay_gap_minutes
+		: 0;
+	/** Why the property's gap between covering forms still holds this session, or null. */
+	const gapHolds = () => {
+		const at = counters.coveredAt();
+		if (!(gap > 0) || typeof at !== 'number') return null;
+		const ago = Math.max(0, Math.floor((Date.now() - at) / 60_000));
+		return ago < gap
+			? `a popup showed ${ago} min ago; ${gap} min between them`
+			: null;
+	};
+	/** Forms whose trigger fired on an empty basket: they try again when the basket changes. */
+	const awaitingBasket = new Set();
+	/** Covering forms whose trigger fired before the consent banner was answered. */
+	const awaitingConsent = new Map();
+
+	const note = (form, state, reasons = []) => {
+		trace.set(form.slot, {
+			slot: form.slot,
+			format: form.format,
+			trigger: form.trigger.type,
+			priority: form.priority,
+			state,
+			reasons,
+		});
+		if (logging)
+			console.info(
+				`[hp] onsite ${form.slot}: ${state}${reasons.length ? ` (${reasons.join('; ')})` : ''}`,
+			);
+		return state;
+	};
+
+	const sessionAudiences = () => {
+		try {
+			const given = options.audiences?.();
+			return Array.isArray(given) ? given : null;
+		} catch {
+			return null;
+		}
+	};
+
+	const env = (form) => ({
+		path: location.pathname,
+		device,
+		now: Date.now(),
+		seen: counters.seen(form.slot),
+		subscribed: counters.subscribed() || options.subscribed?.() === true,
+		personalisation: access.personalisation(),
+		preview: Boolean(access.preview),
+		audiences: sessionAudiences(),
+	});
+
+	const unwatch = (form) => {
+		stops.get(form.slot)?.();
+		stops.delete(form.slot);
+	};
+
+	/**
+	 * Show `form` if its rules allow it; resolves to the state its trace records. A form on screen is
+	 * not mounted again, and a second call while it is being opened (a double click during the
+	 * decision) shares the first one's answer.
+	 */
+	function show(form, reason, kept = false, asked = ASKED(form)) {
+		if (mounted.has(form.slot)) return Promise.resolve('shown');
+		if (!opening.has(form.slot))
+			opening.set(
+				form.slot,
+				attempt(form, reason, kept, asked).finally(() =>
+					opening.delete(form.slot),
+				),
+			);
+		return opening.get(form.slot);
+	}
+
+	/**
+	 * `kept`: a teaser's tab carried from an earlier page, shown again whatever its caps. `asked`: the
+	 * shopper asked for it (a `manual` form, or one opened by an alias), so its counters do not apply.
+	 */
+	async function attempt(form, reason, kept, asked) {
+		if (suppressed()) {
+			return note(form, 'not shown', [
+				`suppressed: ${[...window[SUPPRESSED]].join(', ')}`,
+			]);
+		}
+		const reasons = blockers(form, {
+			...env(form),
+			...(kept ? { seen: INERT.seen() } : {}),
+			asked,
+		});
+		if (reasons.length) {
+			return note(form, 'not eligible', reasons);
+		}
+		// The gap first: it holds for the whole session, so it is the reason worth reading.
+		const interrupts = INTERRUPTS(form.format) && !kept;
+		const wait = interrupts && !asked && gapHolds();
+		if (wait) {
+			return note(form, 'not shown', [wait]);
+		}
+		// Never over an unanswered consent banner: the shopper answers it first, whatever the answer.
+		if (interrupts && !access.preview && access.consentAnswered?.() === false) {
+			awaitingConsent.set(form, asked);
+			return note(form, 'not shown', ['waiting for the consent banner']);
+		}
+		const covers = OVERLAY(form.format);
+		const shown = covers && blocker(asked);
+		if (shown) return note(form, 'not shown', [`${shown} is showing`]);
+		if (covers && spent && !asked) {
+			return note(form, 'not shown', [
+				`${spent} already showed on this page view`,
+			]);
+		}
+		let container = null;
+		if (!covers) {
+			try {
+				container = document.querySelector(form.trigger.selector ?? '');
+			} catch {
+				container = null;
+			}
+			if (!container) {
+				return note(form, 'not shown', ['no element matches its selector']);
+			}
+		}
+		if (covers) covering.set(form.slot, form);
+		unwatch(form);
+		note(form, 'asking for a decision', [reason]);
+		// The renderer is fetched while the decision is asked, so neither waits on the other.
+		const renderer = loadRender().catch((err) => {
+			console.warn('[hp] onsite renderer not loaded:', err?.message ?? err);
+			return null;
+		});
+		const res = await api.decide(form.slot, counters.pin(form.slot));
+		const decision =
+			res.status === 200
+				? res.body?.decisions?.find((d) => d?.slot === form.slot)
+				: null;
+		// The version this visit was shown in the form's A/B test, kept for the rest of it (ADR 0065).
+		if (decision?.experiment && decision.arm && decision.split)
+			counters.pin(form.slot, [
+				decision.experiment,
+				decision.arm,
+				decision.split,
+			]);
+		const creative =
+			decision && decision.holdout !== true
+				? readCreative(decision.payload)
+				: null;
+		// A reminder needs a code to remind of, and a basket bar a basket: without one, nothing shows.
+		const first = creative?.steps[0].blocks ?? [];
+		const coupon =
+			decision?.offer?.code ?? (access.preview ? 'PREVIEW' : counters.code());
+		const basket = access.basketValue?.() ?? null;
+		const missing =
+			(first.some((b) => b?.t === 'code') &&
+				!coupon &&
+				'no code to remind of') ||
+			(first.some((b) => b?.t === 'progress') &&
+				!(basket > 0) &&
+				'the basket is empty');
+		if (missing) {
+			covering.delete(form.slot);
+			if (missing === 'the basket is empty') awaitingBasket.add(form);
+			return note(form, 'not shown', [missing]);
+		}
+		awaitingBasket.delete(form);
+		if (!creative) {
+			// A held-out visitor whose trigger fired is exposed to the default, as a treated one is,
+			// and its page stays one with no popup: the allowance is spent as a shown one spends it.
+			if (decision?.holdout === true && access.analytics())
+				client.recordExposure(res.body);
+			covering.delete(form.slot);
+			if (covers && decision?.holdout === true) spent ??= form.slot;
+			// The site shows a held-out visitor what it shows without HP, at the same moment; a form
+			// the site opened hears so from `open`, which resolves false.
+			if (decision?.holdout === true && !asked)
+				emit('held', {
+					slot: form.slot,
+					arm: decision.arm ?? null,
+					format: form.format,
+				});
+			return note(
+				form,
+				decision?.holdout === true ? 'held out' : 'no decision',
+				[
+					res.status === 200
+						? 'no creative for this visitor'
+						: `decisions answered ${res.status}`,
+				],
+			);
+		}
+		const render = await renderer;
+		if (!render) {
+			covering.delete(form.slot);
+			return note(form, 'not shown', ['the renderer did not load']);
+		}
+		// Its first step's pictures fetched and decoded first, so it never opens on an empty one, and
+		// never waits for them longer than WARM_MS.
+		await Promise.race([
+			render.warm?.(form, creative, creative.steps[0].id, warmed),
+			new Promise((resolve) => setTimeout(resolve, WARM_MS)),
+		]);
+		if (suppressed()) {
+			covering.delete(form.slot);
+			return note(form, 'not shown', ['suppressed']);
+		}
+		if (!kept) counters.shown(form.slot);
+		if (interrupts) counters.covered();
+		if (covers) spent ??= form.slot;
+		const tell = (name, detail = {}) =>
+			emit(name, {
+				slot: form.slot,
+				arm: decision.arm ?? null,
+				format: creative.format ?? form.format,
+				...detail,
+			});
+		const handle = render.mountForm({
+			form,
+			creative,
+			decision,
+			access,
+			client,
+			api,
+			counters,
+			loadWheel,
+			loadAnswers,
+			container,
+			warmed,
+			coupon,
+			basket: () => access.basketValue?.() ?? null,
+			emit: tell,
+			onClose(why) {
+				mounted.delete(form.slot);
+				covering.delete(form.slot);
+				note(form, 'closed', [why]);
+				tell('closed', { reason: why });
+			},
+		});
+		mounted.set(form.slot, handle);
+		if (access.analytics()) client.recordExposure(res.body);
+		note(form, 'shown', [reason]);
+		tell('shown');
+		return 'shown';
+	}
+
+	/**
+	 * Triggers that fire within FIRE_WINDOW_MS of each other compete: only the highest priority shows.
+	 * One that cannot show passes to the next; a held-out visitor sees none, so the holdout stays clean.
+	 */
+	function fire(form, reason, asked = ASKED(form)) {
+		if (!OVERLAY(form.format)) return show(form, reason, false, asked);
+		fired.push([form, reason, asked]);
+		if (fired.length > 1) return;
+		setTimeout(async () => {
+			const queue = fired.sort(([a], [b]) => byPriority(a, b));
+			fired = [];
+			for (const [i, [next, why, ask]] of queue.entries()) {
+				const state = await show(next, why, false, ask);
+				if (state === 'shown' || state === 'held out') {
+					for (const [f] of queue.slice(i + 1))
+						note(f, 'not shown', [`${next.slot} has a higher priority`]);
+					return;
+				}
+			}
+		}, FIRE_WINDOW_MS);
+	}
+
+	for (const form of forms) {
+		// A teaser's tab still out from an earlier page comes back whatever its caps and trigger.
+		if (form.format === 'teaser' && counters.tabOut(form.slot)) {
+			show(form, 'tab kept from an earlier page', true);
+			continue;
+		}
+		const reasons = blockers(form, env(form));
+		if (reasons.length) {
+			note(form, 'not eligible', reasons);
+			continue;
+		}
+		const type = form.trigger.type;
+		if (type === 'manual') note(form, 'waiting for hp.onsite.open');
+		else if (type === 'inline' || form.format === 'inline')
+			show(form, 'inline');
+		else arm(form);
+	}
+
+	/** Watch a form's trigger; when it fires, the form competes to show. */
+	function arm(form) {
+		// A form armed again (after the consent banner) stops its first watcher, so it fires once.
+		unwatch(form);
+		stops.set(
+			form.slot,
+			watch(
+				form.trigger,
+				(reason) => {
+					unwatch(form);
+					fire(form, reason);
+				},
+				{ device },
+			),
+		);
+		note(form, 'armed', [`${form.trigger.type} on ${device}`]);
+	}
+
+	// Once the banner is answered, a form that waited is armed again, so it opens at its trigger's
+	// next moment (an exit form at the next exit), not at once; a form the site opened is shown.
+	const stopConsent = access.onConsentAnswered?.(() => {
+		const waiting = [...awaitingConsent];
+		awaitingConsent.clear();
+		for (const [form, asked] of waiting)
+			if (!mounted.has(form.slot))
+				asked ? fire(form, 'manual', asked) : arm(form);
+	});
+
+	const stopBasket = access.onBasket?.(() => {
+		if (!((access.basketValue?.() ?? 0) > 0)) return;
+		// Out of the set before the decision is asked, so a second update cannot show them twice;
+		// covering ones compete on priority as any trigger does.
+		const waiting = [...awaitingBasket];
+		awaitingBasket.clear();
+		for (const form of waiting)
+			if (!mounted.has(form.slot)) fire(form, 'the basket changed');
+	});
+
+	const controller = Object.freeze({
+		/**
+		 * Show the form keyed `name`, else the first whose `aliases` has it (the site's own sign-up
+		 * button names one), now, whatever its trigger. From there it is that form, by its slot.
+		 */
+		open(name) {
+			const keyed = forms.find((f) => f.slot === name);
+			const form = keyed ?? forms.find((f) => f.aliases.includes(name));
+			if (!form) return Promise.resolve(false);
+			// One already on screen (an inline form) is shown, not mounted twice. A form opened by an
+			// alias is the shopper asking, as a `manual` one is.
+			return mounted.has(form.slot)
+				? Promise.resolve(true)
+				: show(form, 'manual', false, ASKED(form) || !keyed).then(
+						(state) => state === 'shown',
+					);
+		},
+		/** `hp.onsite.suppress`: take every form off the screen, quietly; none shows until unsuppressed. */
+		suppress() {
+			for (const [slot, handle] of mounted) {
+				handle.destroy();
+				mounted.delete(slot);
+				covering.delete(slot);
+				const form = forms.find((f) => f.slot === slot);
+				if (form) note(form, 'closed', ['suppressed']);
+			}
+		},
+		/** Each form's state on this page and why, in settings order. */
+		debug: () =>
+			[...trace.values()].map((t) => ({ ...t, reasons: [...t.reasons] })),
+		/** Stop watching every trigger. A form on screen stays until it is closed. */
+		stop() {
+			for (const stop of stops.values()) stop();
+			stops.clear();
+			stopBasket?.();
+			stopConsent?.();
+			awaitingBasket.clear();
+			awaitingConsent.clear();
+			if (window[CONTROLLER] === controller) delete window[CONTROLLER];
+		},
+	});
+	window[CONTROLLER] = controller;
+	for (const { slot, resolve } of window[PENDING]?.splice(0) ?? [])
+		resolve(controller.open(slot));
+	if (logging) console.table?.(controller.debug());
+	return controller;
+}

package/src/onsite/pow.js

@@ -0,0 +1,127 @@
+/**
+ * ALTCHA's proof of work (the v1 SHA-256 challenge, MIT), solved headless: find `number` in
+ * [0, maxnumber] with `sha256(salt + number) === challenge`. The answer is the base64 payload
+ * `/v1/capture` takes as `altcha`. Off the main thread in a Worker made from a Blob; where a CSP or
+ * the browser refuses one, on the main thread, yielding to the page between batches.
+ */
+
+const TIMEOUT_MS = 20_000;
+
+/**
+ * Self-contained, so it can be the Worker's body: SubtleCrypto, 256 hashes at a time. `pause`
+ * yields between batches on the main thread; an aborted `signal` stops it there, with null.
+ *
+ * @param {{ challenge: string, salt: string, maxnumber?: number }} c
+ * @param {() => Promise<void>} [pause]
+ * @param {AbortSignal} [signal]
+ */
+export async function solveChallenge(c, pause, signal) {
+	const hex = (buf) =>
+		Array.from(new Uint8Array(buf), (b) =>
+			b.toString(16).padStart(2, '0'),
+		).join('');
+	const encoder = new TextEncoder();
+	const max = c.maxnumber ?? 1e6;
+	for (let start = 0; start <= max; start += 256) {
+		const batch = [];
+		for (let n = start; n < start + 256 && n <= max; n++)
+			batch.push(crypto.subtle.digest('SHA-256', encoder.encode(c.salt + n)));
+		const found = (await Promise.all(batch)).findIndex(
+			(d) => hex(d) === c.challenge,
+		);
+		if (found >= 0) return start + found;
+		if (pause) await pause();
+		if (signal?.aborted) return null;
+	}
+	return null;
+}
+
+/**
+ * A turn for the page between batches: a `user-visible` task, queued behind the page's own, with no
+ * timer's 4 ms clamp (the proof ends 1.4 to 2x sooner than with setTimeout). Not `background`,
+ * which a busy page starves until the proof times out, nor `scheduler.yield`, whose continuation
+ * runs ahead of the page's tasks and held off its timers for the whole proof.
+ */
+const pause = () =>
+	globalThis.scheduler?.postTask?.(() => {}, { priority: 'user-visible' }) ??
+	new Promise((resolve) => setTimeout(resolve, 0));
+
+/** On the main thread, giving the page a turn between batches, until `signal` aborts. */
+export const solveOnMainThread = (c, signal) =>
+	solveChallenge(c, pause, signal);
+
+function solveWithWorker(c, signal) {
+	const source = `onmessage=async(e)=>postMessage(await(${solveChallenge})(e.data))`;
+	const url = URL.createObjectURL(
+		new Blob([source], { type: 'text/javascript' }),
+	);
+	return new Promise((resolve, reject) => {
+		let worker;
+		try {
+			worker = new Worker(url);
+		} catch (err) {
+			URL.revokeObjectURL(url);
+			reject(err);
+			return;
+		}
+		const done = (fn, value) => {
+			worker.terminate();
+			URL.revokeObjectURL(url);
+			fn(value);
+		};
+		signal.addEventListener('abort', () => done(resolve, null), {
+			once: true,
+		});
+		worker.onmessage = (e) => done(resolve, e.data);
+		worker.onerror = (e) => {
+			e.preventDefault?.();
+			done(reject, e);
+		};
+		worker.postMessage({
+			challenge: c.challenge,
+			salt: c.salt,
+			maxnumber: c.maxnumber,
+		});
+	});
+}
+
+const isChallenge = (c) =>
+	c &&
+	c.algorithm === 'SHA-256' &&
+	typeof c.challenge === 'string' &&
+	typeof c.salt === 'string' &&
+	typeof c.signature === 'string';
+
+/** The `altcha` payload for challenge `c`, or null when it cannot be solved in time. */
+export async function solve(c) {
+	// Without SubtleCrypto (not a secure context) there is no proof: the gateway decides.
+	if (!isChallenge(c) || typeof crypto?.subtle?.digest !== 'function')
+		return null;
+	const started = Date.now();
+	// Out of time, the proof stops: the worker is ended, the main thread's batches cease.
+	const stop = new AbortController();
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(null), TIMEOUT_MS);
+	});
+	const work =
+		typeof Worker === 'function' && typeof Blob === 'function'
+			? solveWithWorker(c, stop.signal).catch(() =>
+					solveOnMainThread(c, stop.signal),
+				)
+			: solveOnMainThread(c, stop.signal);
+	const number = await Promise.race([work, timeout]);
+	clearTimeout(timer);
+	stop.abort();
+	if (typeof number !== 'number') return null;
+	return btoa(
+		JSON.stringify({
+			algorithm: c.algorithm,
+			challenge: c.challenge,
+			number,
+			salt: c.salt,
+			signature: c.signature,
+			took: Date.now() - started,
+		}),
+	);
+}