@thg-agentic/hyper-personalisation-web 3.34.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.34.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.d.ts

@@ -105,6 +105,11 @@ export interface OnsiteForm {
 	/** 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 };
 	/**
 	 * Its dates and its daily cut-off: with one, it shows only while one of its listed cut-offs is