@thg-agentic/hyper-personalisation-web 3.30.0 → 3.32.0

package/src/session/record.js

@@ -1,3 +1,4 @@
+import { currencyCode } from '../context.js';
 import { bump, categoryKey, pathPrefix } from './category.js';
 import { readSignals, writeSignals } from './signals.js';
 
@@ -64,6 +65,18 @@ const basketOf = (products) =>
 		),
 	].slice(0, RECENT_LIMIT);
 
+/**
+ * How many items a cart event's lines hold: a whole positive quantity as it is, a line without one
+ * or with a fractional one (a weight) once, and one of zero, below or not a number not at all.
+ */
+export const basketItemsOf = (products) =>
+	products.reduce((n, p) => {
+		const q = p?.quantity;
+		if (q === undefined || q === null) return n + 1;
+		if (typeof q !== 'number' || !Number.isFinite(q) || q <= 0) return n;
+		return n + (Number.isInteger(q) ? q : 1);
+	}, 0);
+
 /**
  * Fold one CDP event into the session signals.
  *
@@ -192,6 +205,11 @@ export function recordSessionEvent(eventName, properties, campaign) {
 			// Its lines are the basket as it now stands, merges and removals included.
 			if (Array.isArray(properties?.products))
 				s.basketProducts = basketOf(products);
+			s.basketItems = Array.isArray(properties?.products)
+				? basketItemsOf(products)
+				: null;
+			// The basket's own currency, so its value is never shown in another.
+			s.basketCurrency = currencyCode(properties?.currency);
 			const value = properties?.value;
 			s.basketValue =
 				typeof value === 'number' && Number.isFinite(value) && value >= 0

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/session/signals.js

@@ -91,6 +91,10 @@ function emptySignals() {
 		// The last Cart Updated's `value`, in its currency. Unknown (so every rule on it fails closed)
 		// until the visit sends one: a basket carried over from an earlier visit is not zero.
 		basketValue: null,
+		// How many items the last Cart Updated's lines hold; unknown until one lists them.
+		basketItems: null,
+		// The last Cart Updated's `currency`, the one its value is in; unknown when it named none.
+		basketCurrency: null,
 		recentSearches: [],
 		// Shown-and-ignored counts, kept apart from `recentProducts` so a rail's own impressions never
 		// read as interest. The threshold that makes them meaningful lives server-side in `fatigue.ts`.

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.30.0';
+export const VERSION = '3.32.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/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). */

package/types/onsite-preview.d.ts

@@ -34,6 +34,17 @@ export interface PreviewOptions {
 	prizes?: Array<{ key: string; label: string }>;
 	/** The basket a progress block is drawn against; 32 when left out. */
 	basketValue?: number;
+	/**
+	 * A returning shopper's values for the text's shopper values (`answers` by question, as option
+	 * values); null or left out, every value shows its fallback, as a new visitor sees it.
+	 */
+	values?: {
+		first_name?: string;
+		basket_value?: number;
+		basket_items?: number;
+		currency?: string;
+		answers?: Record<string, string[]>;
+	} | null;
 }
 
 export interface OnsitePreview {
@@ -56,3 +67,19 @@ export declare function mountPreview(
 
 /** The countries a phone field's country code picker offers, by ISO code, with their calling codes. */
 export declare const CALLING_CODES: Readonly<Record<string, string>>;
+
+/**
+ * A shopper value as the SDK draws it in a form's text: a number, money in `currency`, a date, a
+ * time from now or text, in `lang`; with `plural`, a number followed by its word. Null when it
+ * cannot be shown (an unknown currency, not a number).
+ */
+export declare function formatValue(
+	raw: unknown,
+	style: 'number' | 'money' | 'date' | 'relative' | 'text',
+	options?: {
+		lang?: string;
+		currency?: string | null;
+		plural?: { one: string; other: string };
+		now?: number;
+	},
+): string | null;

package/types/onsite.d.ts

@@ -1,12 +1,41 @@
 import type { AnalyticsClient } from './index';
 
-/** RichText: plain text, bold, italic and https links. No markup: anything else is dropped. */
+/**
+ * RichText: plain text, bold, italic, https links and shopper values. No markup: anything else is
+ * dropped.
+ */
 export type RichText =
 	| string
 	| Array<
-			string | { b: RichText } | { i: RichText } | { a: RichText; href: string }
+			| string
+			| { b: RichText }
+			| { i: RichText }
+			| { a: RichText; href: string }
+			| OnsiteValueNode
 	  >;
 
+/**
+ * A shopper value in a heading's or a paragraph's text (3.32): filled in the browser as text, never
+ * markup, at most 60 characters. `v` is a key of spec/onsite/values.json: `basket_value`,
+ * `basket_items`, `first_name` (the page's, `hp.onsite.values`) or `answer.<question>` (the label
+ * of the shopper's answer, under personalisation consent). Unknown, it shows `fallback`, or with
+ * the block's `missing: "hide"` the block is not shown. Never inside a link.
+ */
+export interface OnsiteValueNode {
+	v: string;
+	fallback: string;
+	format?: {
+		style: 'number' | 'money' | 'date' | 'relative' | 'text';
+		/** After a number, the word for its count: `{ one: 'item', other: 'items' }`. */
+		plural?: { one: string; other: string };
+	};
+}
+
+/** What the page knows of the shopper for a form's text. Never sent, stored or logged. */
+export interface OnsitePageValues {
+	first_name?: string;
+}
+
 export type OnsiteFormat =
 	| 'popup'
 	| 'sheet'
@@ -171,6 +200,8 @@ export interface OnsiteOptions {
 	/** Log why each form did or did not show. Also on with `?hp_debug=onsite` or the SDK's debug. */
 	debug?: boolean;
 	fetch?: typeof fetch;
+	/** What the page knows of the shopper for a form's text; `hp.onsite.values` replaces it. */
+	values?: OnsitePageValues;
 }
 
 /**
@@ -208,6 +239,7 @@ export type OnsiteNothingCode =
 	| 'no-code'
 	| 'renderer-failed'
 	| 'products-failed'
+	| 'values-failed'
 	| 'error';
 
 /** One form's state on this page, and why. */
@@ -291,6 +323,11 @@ export interface OnsiteFacade {
 	suppress(reason?: string): void;
 	/** Lift `reason`, or every reason. */
 	unsuppress(reason?: string): void;
+	/**
+	 * What the page knows of the shopper for a form's text (3.32), `{ first_name }`: in this page's
+	 * memory only, never sent, stored or logged. Each call replaces the last; `values({})` forgets.
+	 */
+	values(given: OnsitePageValues): void;
 	/** Each form's state once the page knows whether onsite forms run on it; `[]` when none will. */
 	ready(): Promise<OnsiteTrace[]>;
 	debug(): OnsiteTrace[];