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

package/src/session/record.js

@@ -77,6 +77,61 @@ export const basketItemsOf = (products) =>
 		return n + (Number.isInteger(q) ? q : 1);
 	}, 0);
 
+/** The events that can change the basket's codes: every other leaves them as they are. */
+export const BASKET_CODE_EVENTS = new Set([
+	'Cart Viewed',
+	'Cart Updated',
+	'Coupon Applied',
+	'Coupon Removed',
+	'Order Completed',
+]);
+
+/** Codes compared as a shopper types them: `welcome10` and `WELCOME10 ` are one code. */
+const sameCode = (a, b) => a.toLowerCase() === b.toLowerCase();
+
+const codeText = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+/**
+ * The discount codes in the basket after `eventName`, from the spec's own fields: a cart event's
+ * `discounts` (one entry per code), else its `coupon`, replaces them; Coupon Applied and Coupon
+ * Removed adjust them between cart events, and an order uses them up. A cart event naming neither
+ * field leaves them as they were. Null is unknown, until an event names them, so nothing is decided
+ * on codes never reported.
+ */
+export function basketCodesAfter(codes, eventName, properties) {
+	switch (eventName) {
+		case 'Cart Viewed':
+		case 'Cart Updated': {
+			const { discounts, coupon } = properties ?? {};
+			if (Array.isArray(discounts))
+				return discounts
+					.map((d) => codeText(d?.coupon_name))
+					.filter(Boolean)
+					.filter((c, i, all) => all.findIndex((o) => sameCode(o, c)) === i);
+			if (coupon !== undefined) {
+				const code = codeText(coupon);
+				return code ? [code] : [];
+			}
+			// `discounts: null` is a basket without promotions; naming neither leaves them as they were.
+			return discounts === null ? [] : codes;
+		}
+		case 'Coupon Applied': {
+			const code = codeText(properties?.coupon_name);
+			if (!code) return codes;
+			const kept = codes ?? [];
+			return kept.some((c) => sameCode(c, code)) ? kept : [...kept, code];
+		}
+		case 'Coupon Removed': {
+			const code = codeText(properties?.coupon_name);
+			return code && codes ? codes.filter((c) => !sameCode(c, code)) : codes;
+		}
+		case 'Order Completed':
+			return codes?.length ? [] : codes;
+		default:
+			return codes;
+	}
+}
+
 /**
  * Fold one CDP event into the session signals.
  *
@@ -95,6 +150,7 @@ export function recordSessionEvent(eventName, properties, campaign) {
 	const products = Array.isArray(properties?.products)
 		? properties.products
 		: [];
+	s.basketCodes = basketCodesAfter(s.basketCodes, eventName, properties);
 
 	switch (eventName) {
 		case 'Product Viewed':
@@ -197,6 +253,11 @@ export function recordSessionEvent(eventName, properties, campaign) {
 			if (products.length > 0) s.basketProducts = basketOf(products);
 			writeSignals(s);
 			return s;
+		case 'Coupon Applied':
+		case 'Coupon Removed':
+		case 'Order Completed':
+			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

package/src/session/rules.js

@@ -109,7 +109,9 @@ export function measureField(field, signals) {
 		const fn = MEASURES[name];
 		return fn && arg ? fn(signals, arg) : null;
 	}
-	const value = signals[field];
+	// How many discount codes the basket holds: `eq 0` is a basket without one. Unknown fails closed.
+	const value =
+		field === 'basketCodeCount' ? signals.basketCodes?.length : signals[field];
 	return typeof value === 'number' ? value : null;
 }
 

package/src/session/signals.js

@@ -68,6 +68,7 @@ function readUnscoped() {
 			(parsed.productViews > 0 ||
 				parsed.listViews > 0 ||
 				parsed.basketValue != null ||
+				parsed.basketCodes != null ||
 				parsed.recentProducts?.length ||
 				parsed.recentBrowse?.length ||
 				parsed.campaign);
@@ -95,6 +96,8 @@ function emptySignals() {
 		basketItems: null,
 		// The last Cart Updated's `currency`, the one its value is in; unknown when it named none.
 		basketCurrency: null,
+		// The discount codes in the basket (`basketCodesAfter`); unknown until a cart event names them.
+		basketCodes: 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/shape.js

@@ -30,9 +30,13 @@ export const PAGE_TYPES = new Set([
  *
  * For `properties` only. Context nulls are load-bearing (`consent.analytics: null` means the CMP
  * has not answered). `products: null` is kept, so a failed product mapping still fails validation
- * rather than looking like an empty result.
+ * rather than looking like an empty result. On a cart event `coupon: null` and `discounts: null`
+ * are kept too: they say the basket has no code, which a missing field does not. Other events'
+ * schemas are closed and may not have them, so there they are pruned as before.
  */
-const NEVER_PRUNE = new Set(['products']);
+const NEVER_PRUNE = ['products'];
+const CART_NEVER_PRUNE = ['products', 'coupon', 'discounts'];
+const CART_EVENTS = new Set(['Cart Viewed', 'Cart Updated']);
 
 /** Restore an exempt key only when it was null; an array stays pruned. */
 const isNullish = (v) => v === null || v === undefined;
@@ -58,12 +62,11 @@ function pruneNulls(value, ancestors = new WeakSet()) {
 }
 
 /** Properties as they go on the wire: nulls pruned, `products: null` kept visible. */
-export function pruneProperties(properties) {
+export function pruneProperties(properties, event) {
 	if (!properties) return properties;
 	const pruned = pruneNulls(properties);
-	for (const key of NEVER_PRUNE) {
-		if (key in properties && isNullish(properties[key]))
-			pruned[key] = properties[key];
+	for (const key of CART_EVENTS.has(event) ? CART_NEVER_PRUNE : NEVER_PRUNE) {
+		if (properties[key] === null) pruned[key] = null;
 	}
 	return pruned;
 }

package/src/version.js

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

package/types/index.d.ts

@@ -535,7 +535,7 @@ export declare function toProducts(
 ): CdpProduct[];
 export declare function pruneProperties<
 	T extends Record<string, unknown> | null | undefined,
->(properties: T): T;
+>(properties: T, event?: string): T;
 
 /** SHA-256 as lowercase hex. */
 export declare function sha256(value: string): Promise<string>;

package/types/onsite-preview.d.ts

@@ -34,6 +34,8 @@ export interface PreviewOptions {
 	prizes?: Array<{ key: string; label: string }>;
 	/** The basket a progress block is drawn against; 32 when left out. */
 	basketValue?: number;
+	/** The form's daily cut-off as the settings carry it (`window.daily`), which a `daily` countdown counts to. */
+	daily?: DailyCutoff;
 	/**
 	 * 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.
@@ -83,3 +85,14 @@ export declare function formatValue(
 		now?: number;
 	},
 ): string | null;
+
+/**
+ * A form's daily cut-off as the settings carry it (`window.daily`): the moments it falls, which the
+ * server works out in the shop's time zone, and a `daily` countdown counts to the first ahead.
+ */
+export interface DailyCutoff {
+	/** The cut-offs, epoch milliseconds, earliest first, up to 8 days on from when they were listed. */
+	next: readonly number[];
+	/** The form shows only while the next cut-off is at most this many hours away. */
+	within_hours?: number;
+}

package/types/onsite.d.ts

@@ -31,6 +31,16 @@ export interface OnsiteValueNode {
 	};
 }
 
+/** What a page says about itself, for forms limited by page facts (3.34). */
+export type OnsitePageFacts = Record<string, boolean | number | string>;
+
+/** One rule on a page fact: `is` / `is_not` one of `values`, or `at_least` / `at_most` a number. */
+export interface OnsitePageFactRule {
+	fact: string;
+	op: 'is' | 'is_not' | 'at_least' | 'at_most';
+	values: Array<boolean | number | string>;
+}
+
 /** What the page knows of the shopper for a form's text. Never sent, stored or logged. */
 export interface OnsitePageValues {
 	first_name?: string;
@@ -85,11 +95,31 @@ export interface OnsiteForm {
 		match: 'is' | 'contains';
 		values: string[];
 	}>;
+	/**
+	 * Shown only where the page says so (3.34): rules on the facts it gave with `hp.onsite.facts`.
+	 * Every rule must hold; a fact the page did not give meets none.
+	 */
+	page_facts?: OnsitePageFactRule[];
+	/** Shown only on the pages of chosen products (3.34): the server checks the page's product. */
+	products?: true;
 	/** Shown only with personalisation consent, and only to members as the server decides. */
 	audiences?: string[];
 	exclude_subscribed?: boolean;
+	/**
+	 * Never shown while the basket holds a discount code, as the page's cart events name them
+	 * (`discounts`, `coupon`, Coupon Applied and Removed); one held back tries again once it has none.
+	 */
+	exclude_code_applied?: boolean;
 	caps?: { per_session?: number; lifetime?: number; after_close_days?: number };
-	window?: { starts_at?: string; ends_at?: string };
+	/**
+	 * Its dates and its daily cut-off: with one, it shows only while one of its listed cut-offs is
+	 * still ahead and, with `within_hours`, only that close to it (3.33).
+	 */
+	window?: {
+		starts_at?: string;
+		ends_at?: string;
+		daily?: import('./onsite-preview').DailyCutoff;
+	};
 	/**
 	 * The form's language, BCP 47 (`en-IE`): its phone field starts on this region's country code,
 	 * and a birthday's day and month follow its order and month names. Absent: the page's `lang`.
@@ -328,6 +358,14 @@ export interface OnsiteFacade {
 	 * memory only, never sent, stored or logged. Each call replaces the last; `values({})` forgets.
 	 */
 	values(given: OnsitePageValues): void;
+	/**
+	 * What this page says about itself (3.34), such as `{ next_day_eligible: true }`: kept in memory
+	 * for this page's path only; a form's decision request sends only the facts its rules read,
+	 * never logged. Each call replaces the last; call it again when the shopper picks another size.
+	 * `facts({})` forgets. Names are lower case, digits and underscores; values true or false, a
+	 * number or words; at most 20.
+	 */
+	facts(given: OnsitePageFacts): void;
 	/** Each form's state once the page knows whether onsite forms run on it; `[]` when none will. */
 	ready(): Promise<OnsiteTrace[]>;
 	debug(): OnsiteTrace[];