@thg-agentic/hyper-personalisation-web 3.29.0 → 3.31.0

package/src/onsite/render.js

@@ -422,7 +422,11 @@ export function mountForm(o) {
 		modal: false,
 		mobile: preview?.device === 'mobile',
 		answers: {},
+		// The step each answer was given on, by question.
+		answeredOn: {},
 		sent: new Set(),
+		// Whether this view's click is counted: a view counts one, whatever was clicked.
+		clicked: false,
 		// The products blocks' rails reported seen, by id: a step shown again does not report it twice.
 		seen: new Set(),
 		receipt: null,
@@ -481,8 +485,17 @@ export function mountForm(o) {
 		small.addEventListener?.('change', resize);
 	}
 
+	/** A form that collects nothing: a message, products, or a quiz. */
+	const asksNothing = !form.channels?.length;
+
 	const engaged = (engagement, step, item = {}) => {
 		if (preview || !decision.decision_id || !access.analytics()) return;
+		// A view counts one click; a products card's always says which product was clicked.
+		if (engagement === 'click') {
+			const counted = state.clicked;
+			state.clicked = true;
+			if (counted && !item.products) return;
+		}
 		client.slotEngaged({
 			decision_id: decision.decision_id,
 			slot: decision.slot,
@@ -768,8 +781,9 @@ export function mountForm(o) {
 		node.href = href;
 		node.rel = 'noopener';
 		node.addEventListener('click', (e) => {
-			if (preview) e.preventDefault();
-			else engaged('click');
+			if (preview) return e.preventDefault();
+			engaged('click');
+			leaving();
 		});
 		return node;
 	}
@@ -1184,54 +1198,76 @@ export function mountForm(o) {
 					(i) => i.value,
 				),
 			].filter(Boolean);
-			if (values.length) state.answers[key] = values;
-			else delete state.answers[key];
+			if (values.length) {
+				state.answers[key] = values;
+				state.answeredOn[key] = state.step.id;
+			} else delete state.answers[key];
 		}
 	}
 
-	/** After the sign-up, an answer the gateway did not carry is the page's to report. */
+	/**
+	 * An answer the gateway did not carry is the page's to report: after the sign-up, or, on a form
+	 * that collects nothing (a quiz), as each step's answers are given.
+	 */
 	function stated() {
-		const answers = [];
-		for (const [question, values] of Object.entries(state.answers)) {
-			const marker = `${question}=${values.join(',')}`;
-			if (state.sent.has(marker)) continue;
-			state.sent.add(marker);
-			answers.push({ question, values });
-		}
-		const step = state.step.id;
+		const fresh = Object.entries(state.answers)
+			.map(([question, values]) => ({ question, values }))
+			.filter((a) => !state.sent.has(marker(a)));
+		// Each answer goes with the step it was given on (collect records it), maybe an earlier one.
+		const stepOf = ({ question }) => state.answeredOn[question];
 		// After the email step, the gateway relays them to that address's profile and records them.
-		if (state.signedUp && answers.length)
-			return void api.answers({
-				anonymousId: access.anonymousId(),
-				sessionId: access.sessionId() ?? undefined,
-				slot: decision.slot,
-				arm: decision.arm ?? undefined,
-				decision_id: decision.decision_id ?? undefined,
-				step,
-				...state.signedUp,
-				answers,
-				context: pageContext(),
-			});
-		if (access.analytics())
-			for (const answer of answers)
-				client.preferencesStated({
-					...answer,
-					source: 'onsite',
+		if (state.signedUp) {
+			for (const step of new Set(fresh.map(stepOf))) {
+				const answers = fresh.filter((a) => stepOf(a) === step);
+				for (const answer of answers) state.sent.add(marker(answer));
+				api.answers({
+					anonymousId: access.anonymousId(),
+					sessionId: access.sessionId() ?? undefined,
 					slot: decision.slot,
-					arm: decision.arm ?? null,
-					decision_id: decision.decision_id ?? null,
+					arm: decision.arm ?? undefined,
+					decision_id: decision.decision_id ?? undefined,
 					step,
+					...state.signedUp,
+					answers,
+					context: pageContext(),
 				});
+			}
+			return;
+		}
+		// Kept back without analytics consent, so a later grant still reports it.
+		if (!access.analytics()) return;
+		for (const answer of fresh) {
+			state.sent.add(marker(answer));
+			client.preferencesStated({
+				...answer,
+				source: 'onsite',
+				slot: decision.slot,
+				arm: decision.arm ?? null,
+				decision_id: decision.decision_id ?? null,
+				step: stepOf(answer),
+			});
+		}
 	}
 
+	const marker = ({ question, values }) => `${question}=${values.join(',')}`;
+
+	/** A quiz left by a link or closed keeps the answers given so far, as on moving on. */
+	const leaving = () => {
+		if (!asksNothing) return;
+		collect();
+		stated();
+	};
+
 	const pageContext = () => ({
 		page: { url: access.pageUrl() },
 		locale: access.locale() ?? undefined,
 		consent: access.consent(),
 	});
 
+	// Answers are reported as the form moves on: after a receipt, or on a form that collects nothing.
+	// A sign-up form's answers before the sign-up travel with it.
 	const advance = (explicit) => {
-		if (state.receipt && !preview) stated();
+		if (!preview && (state.receipt || asksNothing)) stated();
 		show(nextStep(state.step, state.answers, explicit));
 	};
 
@@ -1475,14 +1511,19 @@ export function mountForm(o) {
 		// A preview only moves between steps: nothing is checked, sent or claimed.
 		if (preview) return advance(block.next);
 		if (wrong) return say(wrong.error, wrong.input);
+		// A quiz learns from clicks: moving on with an answer is a click.
+		if (
+			asksNothing &&
+			state.step.blocks.some((b) => state.answers[b?.question])
+		)
+			engaged('click');
 		if (block.action === 'apply') {
 			o.emit?.('apply', {
 				coupon: state.claim?.code ? { code: state.claim.code } : null,
 			});
 			engaged('click');
-			return nextStep(state.step, state.answers, block.next)
-				? advance(block.next)
-				: close('done');
+			// With no step after it, the form closes, done.
+			return advance(block.next);
 		}
 		if (block.action === 'submit') return submit(block);
 		if (block.action === 'spin') return spin(block);
@@ -1520,6 +1561,7 @@ export function mountForm(o) {
 	function close(reason) {
 		// A preview stays on screen: closing is the shopper's, not the trader's.
 		if (state.closed || preview) return;
+		leaving();
 		if (!state.submitted && reason !== 'done') engaged('dismiss');
 		counters.closed(form.slot);
 		counters.tab?.(form.slot, false);

package/src/onsite/visit-audiences.js

@@ -7,7 +7,11 @@
  * limited and the visitor allowed personalisation.
  */
 
-import { catalogueBrowse, sessionRulesHold } from '../session/rules.js';
+import {
+	answeredRulesHold,
+	catalogueBrowse,
+	sessionRulesHold,
+} from '../session/rules.js';
 
 /** What the decide request accepts: more, or a longer slug, and it ignores the lot. */
 const MAX_AUDIENCES = 100;
@@ -45,7 +49,9 @@ export function prefetch(api) {
  *   personalisation consent.
  * @param {string[]} [targets] The audiences the form is limited to.
  * @param {string[]} [given] The session audiences the page gave (`startOnsite`'s `audiences()`).
- * @returns {Promise<string[]>}
+ * @returns {Promise<{ claims: string[], answered: string[] }>} `claims`, the slugs to send as
+ *   `visit_audiences`; `answered`, the early audiences that hold on the answers this device keeps,
+ *   as `answered_audiences`.
  */
 export async function visitAudiences(api, signals, targets = [], given = []) {
 	const datafile = await prefetch(api);
@@ -54,7 +60,12 @@ export async function visitAudiences(api, signals, targets = [], given = []) {
 		? datafile.session_audiences
 		: [];
 	const held = datafile && visit ? holdingAudiences(datafile, visit) : [];
-	return firstWanted([...held, ...given], targets, session);
+	const claims = firstWanted([...held, ...given], targets, session);
+	const answered =
+		datafile && visit
+			? holdingAudiences(datafile, visit, answeredRulesHold)
+			: [];
+	return { claims, answered: firstWanted(answered, targets, session) };
 }
 
 /** `slugs`, once each, `targets` and their transitive `requires` first, capped. */
@@ -79,16 +90,15 @@ export function firstWanted(slugs, targets, session) {
 /**
  * @param {{ session_audiences?: unknown, browse_categories?: unknown }} datafile `GET /v1/audiences/datafile`.
  * @param {object} signals This visit's session signals.
+ * @param {(audience: object, signals: object) => boolean} [holds]
  * @returns {string[]}
  */
-export function holdingAudiences(datafile, signals) {
+export function holdingAudiences(datafile, signals, holds = sessionRulesHold) {
 	const audiences = Array.isArray(datafile?.session_audiences)
 		? datafile.session_audiences
 		: [];
 	const visit = catalogueBrowse(signals, datafile.browse_categories ?? null);
 	return audiences
-		.filter(
-			(audience) => isSlug(audience?.slug) && sessionRulesHold(audience, visit),
-		)
+		.filter((audience) => isSlug(audience?.slug) && holds(audience, visit))
 		.map((audience) => audience.slug);
 }

package/src/session/rules.js

@@ -33,6 +33,16 @@ const STRING_OPERATORS = {
 	contains: (a, b) => text(b) && tagMatches(a, 'contains', b),
 };
 
+/**
+ * Operators on an answer (`answer.<question>`): the values the shopper chose against the rule's
+ * list, as the SQL compiler reads them. With no answer kept, "is none of" holds, as `not exists`.
+ */
+const LIST_OPERATORS = {
+	in: (chosen, list) => list.some((v) => chosen.includes(v)),
+	not_in: (chosen, list) => !list.some((v) => chosen.includes(v)),
+	all: (chosen, list) => list.every((v) => chosen.includes(v)),
+};
+
 /**
  * Every operator this evaluator can apply, including `between`. A contract test keeps the session
  * trait catalogue inside this set, since an unsupported operator fails closed silently.
@@ -40,6 +50,7 @@ const STRING_OPERATORS = {
 export const SESSION_OPERATORS = new Set([
 	...Object.keys(OPERATORS),
 	...Object.keys(STRING_OPERATORS),
+	...Object.keys(LIST_OPERATORS),
 	'between',
 ]);
 
@@ -71,10 +82,11 @@ const MEASURES = {
 /**
  * What a rule's field is worth right now, or null if this build does not know the field.
  *
- * A field is a counter name, `measure.dimension` (`browseShare.damen/schuhe`), or one of the
+ * A field is a counter name, `measure.dimension` (`browseShare.damen/schuhe`), one of the
  * visit's campaign tags (`campaign.source`), which is text and null for a visit that arrived
- * untagged. Exported so a storefront can explain a personalisation. Unknown fields fail the rule
- * closed.
+ * untagged, or an answer (`answer.shopping_for`), the values chosen and empty for none, but null
+ * where the signals carry no answers (the onsite runtime's do). Exported so a storefront can
+ * explain a personalisation. Unknown fields fail the rule closed.
  */
 export function measureField(field, signals) {
 	const separator = field.indexOf('.');
@@ -87,6 +99,13 @@ export function measureField(field, signals) {
 				: null;
 			return typeof tag === 'string' ? tag : null;
 		}
+		if (name === 'answer') {
+			const { answers } = signals;
+			if (!answers || typeof answers !== 'object') return null;
+			return Object.hasOwn(answers, arg) && Array.isArray(answers[arg])
+				? answers[arg]
+				: [];
+		}
 		const fn = MEASURES[name];
 		return fn && arg ? fn(signals, arg) : null;
 	}
@@ -97,6 +116,14 @@ export function measureField(field, signals) {
 export function evaluateSessionRule(rule, signals) {
 	const actual = measureField(rule.field, signals);
 	if (actual === null) return false;
+	if (Array.isArray(actual)) {
+		const list = Array.isArray(rule.value) && rule.value.length > 0;
+		return (
+			list &&
+			Object.hasOwn(LIST_OPERATORS, rule.operator) &&
+			LIST_OPERATORS[rule.operator](actual, rule.value)
+		);
+	}
 	if (typeof actual === 'string') {
 		const compare = STRING_OPERATORS[rule.operator];
 		return compare ? compare(actual, rule.value) : false;
@@ -146,6 +173,25 @@ export function sessionRulesHold(audience, signals) {
 		: groupResults.every(Boolean);
 }
 
+/**
+ * Whether an early audience (ADR 0064) holds on the answers this device keeps: its visit rules and
+ * its `answer_rules` together, grouped as authored. Never when the signals carry no answers.
+ */
+export function answeredRulesHold(audience, signals) {
+	return (
+		audience.early === true &&
+		Array.isArray(audience.answer_rules) &&
+		typeof signals?.answers === 'object' &&
+		sessionRulesHold(
+			{
+				...audience,
+				rules: [...(audience.rules ?? []), ...audience.answer_rules],
+			},
+			signals,
+		)
+	);
+}
+
 /**
  * The audiences this visitor is in right now: precomputed membership from the edge, plus any
  * session audience whose rules hold.
@@ -229,12 +275,21 @@ export function resolveAudienceMemberships(
 			if (active.has(audience.slug)) continue;
 			const required = audience.requires ?? [];
 			if (!required.every(met)) continue;
-			if (audience.mixed && !qualified.has(audience.slug)) continue;
-			if (!audience.rules || audience.rules.length === 0) continue;
-			if (sessionRulesHold(audience, visit)) {
+			// An early audience is in from the answers this device keeps, without the warehouse: they are
+			// the shopper's own. Otherwise it is the MIXED audience it ships as.
+			const source = answeredRulesHold(audience, visit)
+				? 'session'
+				: (!audience.mixed || qualified.has(audience.slug)) &&
+						audience.rules?.length > 0 &&
+						sessionRulesHold(audience, visit)
+					? audience.mixed
+						? 'mixed'
+						: 'session'
+					: null;
+			if (source) {
 				active.add(audience.slug);
 				// Mixed is its own source: half of it was decided by a batch run, not by this visit.
-				bySlug.set(audience.slug, audience.mixed ? 'mixed' : 'session');
+				bySlug.set(audience.slug, source);
 				admitted = true;
 			}
 		}

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.21';
+export const SPEC_VERSION = '1.22';

package/src/storage-scope.js

@@ -70,6 +70,12 @@ export const DEFAULT_STORAGE_NAMES = Object.freeze({
 	 * person id (3.26).
 	 */
 	visitCampaign: 'thg_hp_visit_campaign',
+	/**
+	 * localStorage, per property: the answers given to its onsite forms, each kept 90 days, so an
+	 * audience on answers is decided as the shopper answers. Only under personalisation consent;
+	 * question keys and option values, never contact data (3.31).
+	 */
+	answers: 'thg_hp_answers',
 });
 
 /**
@@ -138,6 +144,22 @@ export function storagePrefix(name, tenant) {
 	return `${name}:${segment(tenant)}:`;
 }
 
+/**
+ * Remove every tenant's localStorage keys of one kind on this origin: consent is withdrawn on the
+ * device, and a sign-out ends what the device kept for everyone.
+ *
+ * @param {keyof typeof DEFAULT_STORAGE_NAMES} kind
+ */
+export function forgetEveryScope(kind) {
+	const prefix = `${names[kind]}:`;
+	try {
+		for (const key of Object.keys(localStorage))
+			if (key.startsWith(prefix)) localStorage.removeItem(key);
+	} catch {
+		// Nothing was kept.
+	}
+}
+
 /**
  * Move every legacy `cdp*` key to its current name, once per page, in both stores.
  *

package/src/version.js

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

package/src/visit-campaign.js

@@ -13,7 +13,7 @@
  */
 
 import { SESSION_TIMEOUT_MS } from './session-id.js';
-import { storageKey, storageName } from './storage-scope.js';
+import { forgetEveryScope, storageKey, storageName } from './storage-scope.js';
 
 /** The longest a tag is read: the control plane's CAMPAIGN_VALUE_MAX, which the server cuts to. */
 const TAG_MAX = 100;
@@ -167,11 +167,5 @@ export function keepVisitCampaign(
 /** Forget every property's visit campaign on this origin: a sign-out, or consent withdrawn. */
 export function clearVisitCampaign() {
 	memory.clear();
-	try {
-		const prefix = `${storageName('visitCampaign')}:`;
-		for (const key of Object.keys(localStorage))
-			if (key.startsWith(prefix)) localStorage.removeItem(key);
-	} catch {
-		/* nothing was kept */
-	}
+	forgetEveryScope('visitCampaign');
 }

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.21
+// Spec version: 1.22
 
 /** context.source.environment. Environment the producer runs in. */
 export type CdpSourceEnvironment = 'production' | 'staging' | 'development';
@@ -104,6 +104,7 @@ export interface RecommendationServed {
 	strategy?: string | null;
 	algorithm_version?: string | null;
 	candidate_algorithm_version?: string | null;
+	shadow_algorithm_version?: string | null;
 	ranked_by?: 'ranker' | 'blend' | 'session' | 'manual' | 'other' | null;
 	fusion?: string | null;
 	fast_weight?: number | null;
@@ -713,7 +714,7 @@ export interface SignUpRelayed {
 }
 
 /** The spec version these models implement. SDKs stamp it on context.spec.version. */
-export const SPEC_VERSION = '1.21';
+export const SPEC_VERSION = '1.22';
 
 /** Every event name the registry accepts. Anything else is rejected at the ingest. */
 export type CdpEventName =

package/types/index.d.ts

@@ -496,6 +496,11 @@ export interface StorageNames {
 	preview?: string;
 	/** sessionStorage: the debug token from `?hp_debug=` (3.18). Default 'thg_hp_debug'. */
 	debug?: string;
+	/**
+	 * localStorage, per property, under personalisation consent: the answers given to its onsite
+	 * forms, each kept 90 days (3.31). Default 'thg_hp_answers'.
+	 */
+	answers?: string;
 }
 
 /** Where a source's device ids come from: the settings' `hp.anonymousId` (since 3.6). */