@thg-agentic/hyper-personalisation-web 3.27.0 → 3.28.1

package/src/onsite/products.js

@@ -0,0 +1,190 @@
+/**
+ * An onsite form's products block (ADR 0064 as amended 2026-11-02): the products the server filled
+ * it with (`served`), as cards that each link to the product, in a row that scrolls sideways or a
+ * grid. A chunk of its own, loaded only for a form that shows one.
+ *
+ * Reported as a rail is (../auto/rails.js): Recommendations Viewed once a card meets the viewability
+ * standard (or before the first click), and Product Clicked with the block's
+ * `recommendation_request_id`, which the form's Slot Engaged also records. A preview draws what the
+ * console filled it with, whatever the block's `min`, never navigates and reports nothing.
+ */
+
+import { watchViewability } from '../auto/viewability.js';
+import { httpsHref } from './rich-text.js';
+
+const CSS = `.pr ul{list-style:none;margin:0;padding:0;display:grid;gap:12px}
+.pr-c ul{grid-auto-flow:column;grid-auto-columns:minmax(132px,42%);overflow-x:auto;scroll-snap-type:x mandatory;scroll-behavior:smooth;padding-bottom:6px;overscroll-behavior-x:contain}
+.pr-c li{scroll-snap-align:start}
+.pr-g ul{grid-template-columns:repeat(auto-fill,minmax(132px,1fr))}
+.mob .pr-g ul{grid-template-columns:repeat(2,1fr)}
+.pr.a-center ul{justify-content:center}
+.pa{display:flex;flex-direction:column;gap:4px;height:100%;color:inherit;text-decoration:none;border-radius:var(--ir);outline-offset:2px}
+.pa:focus-visible{outline:2px solid var(--a)}
+.pf{display:block;aspect-ratio:1;border-radius:var(--ir);background:#f4f4f4;overflow:hidden;isolation:isolate}
+.pf.e{background:color-mix(in srgb,var(--t) 7%,var(--b))}
+.pi{display:block;width:100%;height:100%;object-fit:contain;mix-blend-mode:multiply}
+.pn{font-size:14px;line-height:1.3;min-height:2.6em;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
+.pp{font-size:14px;font-weight:700}
+.pp s{font-weight:400;color:var(--mu)}
+.pb{margin-top:auto;padding:8px 12px;font-size:14px}
+@media (prefers-reduced-motion:reduce){.pr-c ul{scroll-behavior:auto}}`;
+
+const ALIGNS = ['left', 'center', 'right'];
+const isObject = (v) =>
+	v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** Money in the form's language; the bare amount for a currency the browser does not know. */
+function moneyIn(lang, currency) {
+	try {
+		const format = new Intl.NumberFormat(lang || undefined, {
+			style: 'currency',
+			currency,
+		});
+		return (n) => format.format(n);
+	} catch {
+		return (n) => n.toFixed(2);
+	}
+}
+
+/**
+ * Draw `block`'s served products into `box`, in the form's shadow `root`.
+ *
+ * @param {HTMLElement} box The block's node, already on the step.
+ * @param {object} block The products block, with the server's `served`.
+ * @param {{ el: Function, lang?: string, root: ShadowRoot, placement: string, preview: boolean,
+ *   client: object|null, engaged: Function, seen: Set<string> }} o `client` is null when nothing
+ *   is reported; `seen` holds the form's rails already reported seen, so a step shown again is not.
+ * @returns {(() => void)|undefined} Stops watching the cards, for when the step changes.
+ */
+export function mountProducts(box, block, o) {
+	const { el } = o;
+	const served = isObject(block.served) ? block.served : {};
+	const limit = Number.isInteger(block.limit)
+		? Math.min(Math.max(block.limit, 1), 12)
+		: 4;
+	const shown = (Array.isArray(served.products) ? served.products : [])
+		.filter(
+			(p) =>
+				isObject(p) && typeof p.product_id === 'string' && httpsHref(p.url),
+		)
+		.slice(0, limit);
+	if (shown.length === 0) return;
+	const show = isObject(block.show) ? block.show : {};
+	const grid = block.layout === 'grid';
+	box.classList.add(grid ? 'pr-g' : 'pr-c');
+	if (ALIGNS.includes(block.align)) box.classList.add(`a-${block.align}`);
+	// A row that scrolls is named as a region; each card is a link, so Tab walks it into view.
+	if (!grid) {
+		box.setAttribute('role', 'region');
+		box.setAttribute('aria-label', 'Products');
+	}
+	const style = el('style');
+	style.textContent = CSS;
+	const list = el('ul');
+	list.setAttribute('role', 'list');
+
+	const tile = (p, position) => ({
+		product_id: p.product_id,
+		...(typeof p.name === 'string' ? { name: p.name } : {}),
+		...(Number.isFinite(p.price) ? { price: p.price } : {}),
+		position,
+	});
+	const client =
+		typeof served.recommendation_request_id === 'string' && !o.preview
+			? o.client
+			: null;
+	const viewable = new Map();
+	const id = served.recommendation_request_id;
+	const seen = o.seen ?? new Set();
+	let pending = null;
+	const impression = () => {
+		clearTimeout(pending);
+		if (!client || seen.has(id)) return;
+		seen.add(id);
+		client.recommendationsViewed({
+			recommendation_request_id: id,
+			placement: served.placement || o.placement,
+			// Required outside a holdout: a list that is the shopper's own (their basket) has no source.
+			strategy: served.strategy || served.recipe || block.source,
+			recipe: served.recipe ?? null,
+			algorithm_version: served.algorithm_version ?? null,
+			products: shown.map((p, i) => tile(p, i + 1)),
+			viewable: [...viewable.values()].sort((a, b) => a.position - b.position),
+		});
+	};
+
+	for (const [i, p] of shown.entries()) {
+		const position = i + 1;
+		const item = el('li', 'pc');
+		item.dataset.hpProduct = p.product_id;
+		item.dataset.hpPosition = String(position);
+		const a = el('a', 'pa');
+		const name = typeof p.name === 'string' ? p.name : '';
+		const image = httpsHref(p.image);
+		if (image) {
+			const img = el('img', 'pi');
+			// The card's name says what it is; with the name hidden, the picture says it.
+			img.alt = show.name === false ? name : '';
+			img.loading = 'lazy';
+			img.decoding = 'async';
+			img.src = image;
+			// On one light tile, so packshots on white and on grey read as one set.
+			const frame = el('span', 'pf');
+			frame.append(img);
+			a.append(frame);
+		} else a.append(el('span', 'pf e'));
+		// Kept when empty too, so every price in a row sits on one line.
+		if (show.name !== false) a.append(el('span', 'pn', name));
+		if (show.price !== false && Number.isFinite(p.price)) {
+			const money = moneyIn(o.lang, p.currency);
+			const price = el('span', 'pp');
+			price.append(el('span', '', money(p.price)));
+			if (Number.isFinite(p.compare_at_price) && p.compare_at_price > p.price) {
+				const was = el('s', '', money(p.compare_at_price));
+				was.setAttribute('aria-label', `was ${money(p.compare_at_price)}`);
+				price.append(' ', was);
+			}
+			a.append(price);
+		}
+		if (show.name === false && !image)
+			a.setAttribute('aria-label', name || p.product_id);
+		if (typeof block.button === 'string' && block.button)
+			a.append(el('span', 'btn pb', block.button));
+		a.href = httpsHref(p.url);
+		a.rel = 'noopener';
+		a.addEventListener('click', (e) => {
+			if (o.preview) return e.preventDefault();
+			// The impression first, so the click joins it, as a rail's does.
+			impression();
+			client?.productClicked({
+				recommendation_request_id: served.recommendation_request_id,
+				interaction: 'navigate',
+				products: [tile(p, position)],
+			});
+			o.engaged('click', undefined, {
+				position,
+				products: [tile(p, position)],
+			});
+		});
+		item.append(a);
+		list.append(item);
+	}
+	box.append(style, list);
+	if (!client || seen.has(id)) return;
+	return watchViewability({
+		selector: '[data-hp-product]',
+		root: o.root,
+		onViewable(node) {
+			const position = Number(node.dataset.hpPosition);
+			if (!viewable.has(position))
+				viewable.set(position, {
+					position,
+					product_id: node.dataset.hpProduct,
+					viewable_at: new Date().toISOString(),
+				});
+			// Deferred a turn, so cards that became viewable together land on one event.
+			pending ??= setTimeout(impression, 0);
+			return true;
+		},
+	});
+}

package/src/onsite/render.js

@@ -213,6 +213,9 @@ export function warm(form, creative, id, seen = new Set()) {
 	);
 }
 
+/** A timer the step set, or what a products block watches (a teardown). */
+const stopTimer = (t) => (t?.call ? t() : clearInterval(t));
+
 let ids = 0;
 const uid = (kind) => `hp-${kind}-${++ids}`;
 
@@ -315,6 +318,8 @@ function styles(root) {
  * @param {ReturnType<import('./api.js').createApi>} o.api
  * @param {ReturnType<import('./counters.js').createCounters>} o.counters
  * @param {() => Promise<{ mountWheel: Function }>} o.loadWheel
+ * @param {() => Promise<{ mountProducts: Function }>} [o.loadProducts] A products block's cards
+ *   (./products.js), loaded when a step shows one.
  * @param {() => Promise<{ answerFields: Function, answerOf: Function }>} o.loadAnswers The fields of
  *   a date or number question (./answers.js), loaded once as the form mounts when it asks one.
  * @param {Element|null} [o.container] The page's element, for an inline form.
@@ -393,6 +398,8 @@ export function mountForm(o) {
 		mobile: preview?.device === 'mobile',
 		answers: {},
 		sent: new Set(),
+		// The products blocks' rails reported seen, by id: a step shown again does not report it twice.
+		seen: new Set(),
 		receipt: null,
 		claim: o.coupon
 			? { code: o.coupon }
@@ -444,7 +451,7 @@ export function mountForm(o) {
 		small.addEventListener?.('change', resize);
 	}
 
-	const engaged = (engagement, step) => {
+	const engaged = (engagement, step, item = {}) => {
 		if (preview || !decision.decision_id || !access.analytics()) return;
 		client.slotEngaged({
 			decision_id: decision.decision_id,
@@ -452,6 +459,7 @@ export function mountForm(o) {
 			arm: decision.arm ?? null,
 			engagement,
 			step: step ?? state.step?.id ?? null,
+			...item,
 		});
 	};
 
@@ -798,6 +806,32 @@ export function mountForm(o) {
 		return box;
 	}
 
+	/**
+	 * The products the server filled the block with (`served`), drawn by ./products.js, a chunk of its
+	 * own loaded only for a form that shows them. A preview draws what the console filled it with.
+	 */
+	function products(block) {
+		const box = el('div', 'pr');
+		o.loadProducts?.()
+			.then((m) => {
+				if (box.isConnected)
+					state.timers.push(
+						m.mountProducts(box, block, {
+							el,
+							lang,
+							root,
+							placement: form.slot,
+							preview,
+							client: !preview && access.analytics() && client,
+							engaged,
+							seen: state.seen,
+						}),
+					);
+			})
+			.catch(() => {});
+		return box;
+	}
+
 	const BLOCKS = {
 		heading(block) {
 			const h = typeset(el('h2', '', block.text), block, 'xl');
@@ -857,6 +891,7 @@ export function mountForm(o) {
 		},
 		countdown,
 		progress,
+		products,
 		image: picture,
 		video: picture,
 		spacer(block) {
@@ -951,7 +986,7 @@ export function mountForm(o) {
 				: null;
 		state.step = step;
 		state.touched = false;
-		for (const t of state.timers.splice(0)) clearInterval(t);
+		for (const t of state.timers.splice(0)) stopTimer(t);
 		state.codes = [];
 		state.videos = [];
 		state.wheel = null;
@@ -1418,7 +1453,7 @@ export function mountForm(o) {
 
 	function teardown() {
 		state.closed = true;
-		for (const t of state.timers.splice(0)) clearInterval(t);
+		for (const t of state.timers.splice(0)) stopTimer(t);
 		document.removeEventListener('visibilitychange', visibility);
 		small?.removeEventListener?.('change', resize);
 		const remove = () => {

package/src/session/record.js

@@ -54,6 +54,16 @@ function countListView(s, category) {
 	}
 }
 
+/** A cart event's lines as the basket's product ids, each once, as many as RECENT_LIMIT. */
+const basketOf = (products) =>
+	[
+		...new Set(
+			products
+				.map((p) => p?.product_id)
+				.filter((id) => typeof id === 'string' && id),
+		),
+	].slice(0, RECENT_LIMIT);
+
 /**
  * Fold one CDP event into the session signals.
  *
@@ -169,11 +179,19 @@ export function recordSessionEvent(eventName, properties, campaign) {
 		case 'Product Clicked':
 		case 'Product Added to Wishlist':
 			break;
+		case 'Cart Viewed':
+			// The basket as the page shows it: its lines are the basket's products, not attention.
+			if (products.length > 0) s.basketProducts = basketOf(products);
+			writeSignals(s);
+			return s;
 		case 'Cart Updated': {
 			// The basket as it now stands, priced by the platform, so a merge, a repricing or a code is
 			// already in it. Summing the lines of Product Added would drift from that, and its line
 			// prices include tax where `value` does not. Its lines are the basket, not attention.
 			// The latest basket is the only one that counts: unpriced, its value is unknown again.
+			// Its lines are the basket as it now stands, merges and removals included.
+			if (Array.isArray(properties?.products))
+				s.basketProducts = basketOf(products);
 			const value = properties?.value;
 			s.basketValue =
 				typeof value === 'number' && Number.isFinite(value) && value >= 0

package/src/spec-version.js

@@ -1,4 +1,4 @@
 // Generated from the spec by scripts/build-types.mjs. DO NOT EDIT: run `pnpm run build:types`.
 
 /** The event specification this SDK emits, stamped on every event as context.spec.version. */
-export const SPEC_VERSION = '1.20';
+export const SPEC_VERSION = '1.21';

package/src/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '3.27.0';
+export const VERSION = '3.28.1';
 export const LIB = '@thg-agentic/hyper-personalisation-web';

package/types/events.d.ts

@@ -1,7 +1,7 @@
 // Generated from spec/registry.json by scripts/generate-sdk-models.mjs.
 // DO NOT EDIT. Change the schema and regenerate — the schema is the contract,
 // and a hand-edit here is an SDK that disagrees with the ingest.
-// Spec version: 1.20
+// Spec version: 1.21
 
 /** context.source.environment. Environment the producer runs in. */
 export type CdpSourceEnvironment = 'production' | 'staging' | 'development';
@@ -103,6 +103,7 @@ export interface RecommendationServed {
 	recipe?: string | null;
 	strategy?: string | null;
 	algorithm_version?: string | null;
+	candidate_algorithm_version?: string | null;
 	ranked_by?: 'ranker' | 'blend' | 'session' | 'manual' | 'other' | null;
 	fusion?: string | null;
 	fast_weight?: number | null;
@@ -712,7 +713,7 @@ export interface SignUpRelayed {
 }
 
 /** The spec version these models implement. SDKs stamp it on context.spec.version. */
-export const SPEC_VERSION = '1.20';
+export const SPEC_VERSION = '1.21';
 
 /** Every event name the registry accepts. Anything else is rejected at the ingest. */
 export type CdpEventName =

package/types/onsite.d.ts

@@ -85,9 +85,54 @@ export interface OnsiteForm {
 	prizes?: Array<{ key: string; label: string }>;
 	/** A destination is handed the shopper's code, so the brand's email can carry it. */
 	code_relayed?: true;
+	/**
+	 * One of the form's versions shows products: its decision request carries the visit's context
+	 * (`OnsiteVisitContext`), and only its.
+	 */
+	visit_context?: true;
+	/** What the form collects; empty for one that collects nothing (a message, products). */
 	channels?: Array<'email' | 'sms'>;
 }
 
+/**
+ * What a form that shows products is decided with, for that request only: the page, and with
+ * personalisation consent the basket's product ids (from the cart events the page sends) and the
+ * visit's views, at most 20 each, newest first.
+ */
+export interface OnsiteVisitContext {
+	page_type?: string;
+	product_id?: string;
+	basket?: string[];
+	viewed?: string[];
+}
+
+/** One product the server filled a form's products block with. */
+export interface OnsiteServedProduct {
+	product_id: string;
+	name: string;
+	price?: number | null;
+	compare_at_price?: number | null;
+	currency?: string | null;
+	image?: string | null;
+	url: string;
+	position: number;
+}
+
+/**
+ * A products block's `served`, as `POST /v1/decisions` fills it (spec/onsite/creative.schema.json
+ * `servedProducts`). A preview passes it in the creative itself.
+ */
+export interface OnsiteServedProducts {
+	recommendation_request_id: string;
+	placement: string;
+	requested: string;
+	recipe: string;
+	degraded: boolean;
+	strategy?: string | null;
+	algorithm_version?: string | null;
+	products: OnsiteServedProduct[];
+}
+
 /**
  * A date question's (`kind`: a `birthday`, its `year` not asked, optional or required, or any
  * full `date`) or a number question's (`min`, `max`, `decimals`, `unit`).