@thg-agentic/hyper-personalisation-web 3.17.1 → 3.19.0

package/src/device-storage.js

@@ -9,8 +9,8 @@
  *                  (3.6). Under strict consent it is written only once analytics is granted.
  */
 
-import { getCookie } from './context.js';
-import { uuid } from './shape.js';
+import { getCookie, perRequest } from './context.js';
+import { realId, uuid } from './shape.js';
 import { storageKey, storageName } from './storage-scope.js';
 
 /** How long held events may wait for an answer across pages. A tab left for longer starts over. */
@@ -153,9 +153,14 @@ export function createDeviceCookie({
 		peek: () => id,
 		/** Consent was granted: write what was minted before it. */
 		persist,
-		/** Consent was refused or withdrawn: the id must not outlive the permission it was kept under. */
+		/**
+		 * Consent was refused or withdrawn, or the user signed out: the id must not outlive the
+		 * permission or the person it was kept under, so the next event starts a new device, as
+		 * Segment's `analytics.reset()` does.
+		 */
 		forget() {
 			writeCookie(name, '', 0, domain);
+			id = null;
 			written = false;
 			try {
 				local()?.removeItem(legacyKey);
@@ -168,34 +173,42 @@ export function createDeviceCookie({
 }
 
 /**
- * Where device ids come from, from the source's settings (`hp.anonymousId`, ADR-0017): one place,
- * never a fallback between two.
+ * Where device ids come from, from the source's settings (`hp.anonymousId`, ADR-0017).
  *
- *   site_cookie  the cookie the settings name, or (no name) `getAnonymousId`, the integration's
- *                own. Read only: a visitor without it has no device id.
+ *   site_cookie  the cookie the settings name, or (no name) `getAnonymousId`, the integration's own.
  *   hp_cookie    Hyper-Personalisation's cookie, minted and kept here. `getAnonymousId` is ignored.
  *   absent       settings from before 3.6: `getAnonymousId`, as before.
  *
- * Replaces `cfg.getAnonymousId` to match, and returns the device cookie under `hp_cookie`.
+ * With `orOwn`, a visitor the site has no id for (the cookie missing, empty or a placeholder) gets
+ * Hyper-Personalisation's cookie rather than none, as analytics.js does: an event with no device id
+ * belongs to nobody (3.18).
+ *
+ * Replaces `cfg.getAnonymousId` to match, and returns the device cookie it may fall back to.
  */
-export function deviceIdFrom(cfg, { carried, mayStore }) {
+export function deviceIdFrom(cfg, { carried = null, mayStore, orOwn = false }) {
 	const setting = cfg.anonymousIdSource;
+	const own = () =>
+		createDeviceCookie({
+			name: storageName('anonymousId'),
+			domain: cfg.consentCookieDomain ?? null,
+			legacyKey: storageKey(storageName('anonymousId'), cfg.propertyId),
+			read: getCookie,
+			mint: uuid,
+			mayStore,
+			carried,
+		});
+	if (setting?.source === 'hp_cookie') {
+		const device = own();
+		cfg.getAnonymousId = () => device.get();
+		return device;
+	}
 	if (setting?.source === 'site_cookie' && setting.cookie) {
 		const name = setting.cookie;
 		cfg.getAnonymousId = () => getCookie(name);
-		return null;
 	}
-	if (setting?.source !== 'hp_cookie') return null;
-	const name = storageName('anonymousId');
-	const device = createDeviceCookie({
-		name,
-		domain: cfg.consentCookieDomain ?? null,
-		legacyKey: storageKey(name, cfg.propertyId),
-		read: getCookie,
-		mint: uuid,
-		mayStore,
-		carried,
-	});
-	cfg.getAnonymousId = () => device.get();
+	if (!orOwn) return null;
+	const site = cfg.getAnonymousId;
+	const device = own();
+	cfg.getAnonymousId = () => realId(perRequest(site, null)) ?? device.get();
 	return device;
 }

package/src/guard.js

@@ -0,0 +1,46 @@
+/**
+ * Tracking never throws into the host. Every public method runs behind `guard`: a failure is logged
+ * and the method answers what a client that could not decide answers. That fails closed, as the CDN
+ * stub does before the client starts: no personalisation, no consent headers, nothing sent.
+ */
+
+/** `throwOnInvalid`: the one failure a caller asked to have thrown at them. */
+export class InvalidEventError extends Error {}
+
+const FALLBACKS = {
+	inHoldout: () => true,
+	personalisationGroup: () => 'excluded',
+	servingHeaders: () => ({}),
+	recommendationContext: () => ({}),
+	flush: () => Promise.resolve(),
+	reset: () => undefined,
+};
+
+/** `method` behind the guard, answering `name`'s fallback when it throws. */
+export function guard(name, method) {
+	const fallback = FALLBACKS[name] ?? (() => null);
+	const failed = (err) => {
+		console.warn(`[hp] ${String(name)} failed; nothing was sent`, err);
+		return fallback();
+	};
+	return function guarded(...args) {
+		try {
+			const result = method.apply(this, args);
+			return typeof result?.then === 'function'
+				? Promise.resolve(result).catch(failed)
+				: result;
+		} catch (err) {
+			if (err instanceof InvalidEventError) throw err;
+			return failed(err);
+		}
+	};
+}
+
+/** Every method of `client` behind the guard, in place. Getters are left as they are. */
+export function guardMethods(client) {
+	for (const key of Reflect.ownKeys(client)) {
+		const { value } = Object.getOwnPropertyDescriptor(client, key) ?? {};
+		if (typeof value === 'function') client[key] = guard(key, value);
+	}
+	return client;
+}

package/src/identity-option.js

@@ -0,0 +1,6 @@
+/**
+ * Marks bootstrap's own identify, from its `identity` option, so it never counts as the earlier
+ * user a later host `identify` would be switching away from: the host may name the same person
+ * in another form.
+ */
+export const IDENTITY_OPTION = Symbol('hp.identityOption');

package/src/index.js

@@ -14,7 +14,8 @@
  *     propertyId: 'acme-gb',
  *     consent: oneTrustConsent(),
  *     // Where device ids come from, as the source's settings say (`hp.anonymousId`). Without it,
- *     // getAnonymousId is the device id; with `hp_cookie` the SDK mints and keeps its own.
+ *     // getAnonymousId is the device id; with `hp_cookie`, or when the site has none, the SDK mints
+ *     // and keeps its own.
  *     anonymousIdSource: settings.anonymousId,
  *     getAnonymousId: () => getCookie('device_id'),
  *     getSessionId:   () => getCookie('session_id'),
@@ -52,13 +53,16 @@ import {
 	holdoutAssignment,
 	holdoutShares,
 } from './experiments.js';
+import { guardMethods, InvalidEventError } from './guard.js';
 import { emailSha256, sha256Hex } from './hash.js';
+import { IDENTITY_OPTION } from './identity-option.js';
 import { applyPreview } from './preview.js';
 import {
 	forgetVisit,
 	keepVisit,
 	recommendationContextFrom,
 } from './recommendation-context.js';
+import { sampledIn } from './sampling.js';
 import { recordSessionEvent } from './session/record.js';
 import {
 	clearSessionSignals,
@@ -80,7 +84,11 @@ import {
 	storageKey,
 	storageName,
 } from './storage-scope.js';
-import { Transport } from './transport.js';
+import {
+	MAX_EVENT_BYTES,
+	Transport,
+	byteLength as utf8Bytes,
+} from './transport.js';
 import { LIB, VERSION } from './version.js';
 
 /** The surfaces a `Personalisation Exposed` names, as the public API's exposures do. */
@@ -190,6 +198,19 @@ export { createSocialProof } from './social-proof.js';
 export { VERSION };
 
 let warnedMintAnonymousId = false;
+let warnedHostBasis = false;
+
+/**
+ * Without a consent adapter the SDK sends under the host's lawful basis: fail-open, so say it once.
+ * Requiring `consent` is a breaking change, planned for 4.0.
+ */
+function warnHostBasis() {
+	if (warnedHostBasis) return;
+	warnedHostBasis = true;
+	console.warn(
+		"[hp] no consent adapter: events are sent under the host's lawful basis (basis 'host'). Pass `consent` to send only once the visitor allows analytics.",
+	);
+}
 
 /** 3.5's `mintAnonymousId` does nothing since 3.6: where device ids come from is the source's. */
 function warnMintAnonymousId(debug) {
@@ -200,6 +221,15 @@ function warnMintAnonymousId(debug) {
 	);
 }
 
+/** UTF-8 bytes of the event as sent; 0 for one JSON cannot serialise, which delivery drops itself. */
+function serialisedBytes(event) {
+	try {
+		return utf8Bytes(JSON.stringify(event));
+	} catch {
+		return 0;
+	}
+}
+
 /** Per-call context overrides, given directly or analytics-next style as `{ context }`. */
 function contextOverrides(options) {
 	if (
@@ -238,6 +268,7 @@ export function createAnalytics(options) {
 	// A consent adapter makes the SDK strict: nothing is sent or stored until analytics is granted.
 	// Without one the host has decided the lawful basis itself, and every event says so (spec 1.5).
 	const strict = Boolean(cfg.consent);
+	if (!strict) warnHostBasis();
 	let gate = null;
 	cfg.getConsent = () => (gate ? gate.stamp() : hostConsent());
 	const granted = () => !strict || gate?.status === 'granted';
@@ -253,24 +284,28 @@ export function createAnalytics(options) {
 	const device = deviceIdFrom(cfg, {
 		carried: carried.anonymousId,
 		mayStore: granted,
+		orOwn: true,
 	});
 
-	// No session from the host: the SDK keeps one (3.15). Never a second beside the host's.
-	const session =
-		cfg.getSessionId == null
-			? createSessionId({
-					name: storageName('session'),
-					domain: cfg.consentCookieDomain ?? null,
-					mayStore: granted,
-				})
-			: null;
-	if (session) cfg.getSessionId = () => session.get();
+	// The host's session when it has one, otherwise the SDK's (3.15; 3.18 when the host's is empty).
+	const session = createSessionId({
+		name: storageName('session'),
+		domain: cfg.consentCookieDomain ?? null,
+		mayStore: granted,
+	});
+	const hostSession = cfg.getSessionId;
+	cfg.getSessionId = () =>
+		realId(perRequest(hostSession, null)) ?? session.get();
 
 	const previewing = applyPreview(
 		storageName('preview'),
 		cfg.consentCookieDomain ?? null,
 	);
 
+	/** Delivery problems, logged with `debug`. */
+	const reportError = (message, err) =>
+		cfg.debug && console.warn('[hp]', message, err ?? '');
+
 	const transport =
 		cfg.transport ??
 		new Transport({
@@ -283,7 +318,7 @@ export function createAnalytics(options) {
 			// grant (see onStatus below, which replays on a grant and clears on a refusal).
 			mayPersist: strict ? () => gate?.status === 'granted' : undefined,
 			deferReplay: strict,
-			onError: (m, e) => cfg.debug && console.warn('[hp]', m, e ?? ''),
+			onError: reportError,
 		});
 
 	// The previous page view's messageId, carried across navigations in sessionStorage, per tenant.
@@ -318,11 +353,26 @@ export function createAnalytics(options) {
 	cfg.getDecisions ??= decisions.current;
 
 	let userId = realId(perRequest(cfg.getUserId, null));
+	/** The user the host's last `identify` named: a different one later on this page is a switch. */
+	let identifiedUserId = null;
+	/** The user bootstrap's `identity` option named, only to warn when the host names another form. */
+	let optionsUserId = null;
 
 	/** The call being replayed: its first event keeps the messageId and time it was made with. */
 	let replaying = null;
 
+	/** Tracking never throws into the host: an event that fails to build or deliver is dropped. */
 	function emit(partial, ctxOverrides, force = false) {
+		try {
+			return compose(partial, ctxOverrides, force);
+		} catch (err) {
+			if (err instanceof InvalidEventError) throw err;
+			console.warn('[hp] the event was not sent', err);
+			return null;
+		}
+	}
+
+	function compose(partial, ctxOverrides, force) {
 		const made = replaying;
 		replaying = null;
 		let event = {
@@ -336,6 +386,12 @@ export function createAnalytics(options) {
 
 		if (event.properties) event.properties = pruneProperties(event.properties);
 
+		// Outside the source's sample (3.18): nothing about this visitor is sent.
+		if (!force && !sampledIn(event.anonymousId, cfg.sampleRate)) {
+			if (cfg.debug) console.debug('[hp] not sent: outside the sample', event);
+			return null;
+		}
+
 		// A redaction or sampling hook may change what an event says or drop it, never what it is.
 		// One that fails drops the event rather than sending what it was meant to redact.
 		if (cfg.beforeSend) {
@@ -362,13 +418,23 @@ export function createAnalytics(options) {
 			const res = cfg.validate(event, { producer: 'web' });
 			if (!res.valid) {
 				const msg = `[hp] invalid ${event.event ?? event.type}:\n  ${res.errors.join('\n  ')}`;
-				if (cfg.throwOnInvalid) throw new Error(msg);
+				if (cfg.throwOnInvalid) throw new InvalidEventError(msg);
 				console.error(msg);
 			}
 		}
 
 		if (cfg.debug) console.debug('[hp]', event.event ?? event.type, event);
 
+		// Too big to travel in a keepalive request on its own: it could never go at unload, and once
+		// persisted it would push every other batch out of the retry buffer.
+		const bytes = serialisedBytes(event);
+		if (bytes > MAX_EVENT_BYTES) {
+			reportError(
+				`${event.event ?? event.type} not sent: ${bytes} bytes, over the ${MAX_EVENT_BYTES}-byte limit for one event`,
+			);
+			return null;
+		}
+
 		deliver(event, force);
 		return event;
 	}
@@ -407,15 +473,36 @@ export function createAnalytics(options) {
 				visitKept = true;
 			} else {
 				// Not allowed, or withdrawn: what was kept under the permission goes with it.
-				forgetVisit();
-				if (visitKept) clearSessionSignals();
-				visitKept = false;
+				forgetKeptVisit();
 			}
 		} catch (err) {
 			if (cfg.debug) console.warn('[hp] the visit was not recorded', err);
 		}
 	}
 
+	/**
+	 * What the visit built up for recommendations, kept only under personalisation consent. The
+	 * session signals are cleared only when this SDK built them, unless `all`: a refusal or a sign-out.
+	 */
+	function forgetKeptVisit(all = false) {
+		forgetVisit();
+		if (all || visitKept) clearSessionSignals();
+		visitKept = false;
+	}
+
+	/**
+	 * A sign-out, or another user signing in: the SDK's session, the decisions in force, the visit
+	 * and the SDK's own device id go with the user, as Segment's `reset()` starts a new anonymousId.
+	 * A device id read from the site's own cookie stays: the SDK does not own it.
+	 */
+	function forgetVisitor() {
+		session.forget();
+		decisions.forget();
+		exposedTokens.clear();
+		device?.forget();
+		forgetKeptVisit(true);
+	}
+
 	function deliver(event, force) {
 		// The observer only sees what will be sent, never an event the visitor has not allowed.
 		if (!strict || force || gate.admits()) {
@@ -471,7 +558,7 @@ export function createAnalytics(options) {
 			onStatus(status) {
 				if (status === 'granted') {
 					device?.persist();
-					session?.persist();
+					session.persist();
 					if (lastPageMessageId) writeLastPageMessageId(lastPageMessageId);
 					decisions.persist();
 					transport.replayPersisted?.();
@@ -480,13 +567,14 @@ export function createAnalytics(options) {
 					// Nothing kept on the device may outlive the permission it was kept under.
 					transport.clearPersisted?.();
 					device?.forget();
-					session?.forget();
+					session.forget();
 					try {
 						sessionStorage.removeItem(PREV_PAGE_KEY);
 					} catch {
 						/* nothing was stored */
 					}
 					decisions.forget();
+					forgetKeptVisit(true);
 				}
 				try {
 					cfg.onConsentStatus?.(status);
@@ -494,7 +582,12 @@ export function createAnalytics(options) {
 					console.warn('[hp] onConsentStatus observer failed', err);
 				}
 			},
-			announce({ action, state, withdrawal }) {
+			announce({ action, state, previous, withdrawal }) {
+				// Withdrawn here, not only when the next event reaches recordVisit: a beforeSend that drops
+				// it must not keep the visit. A withdrawal on a later page, before it recorded anything,
+				// forgets the signals an earlier page kept under the permission.
+				if (state?.personalisation !== true)
+					forgetKeptVisit(previous?.personalisation === true);
 				emit(
 					{
 						type: 'track',
@@ -589,11 +682,12 @@ export function createAnalytics(options) {
 		);
 	}
 
-	return {
+	return guardMethods({
 		/** Escape hatch for events not yet in the core spec. Prefer a named method. */
 		track,
 
-		page(props = {}, ctx) {
+		page(props, ctx) {
+			props ??= {};
 			// page.type is inherited by every later event on the page, so an unknown value would get
 			// them all rejected. Keep the last good type instead: stale beats invalid.
 			let pageType = cfg.pageType ?? null;
@@ -625,10 +719,31 @@ export function createAnalytics(options) {
 			return ev;
 		},
 
-		identify(traits, ctx) {
+		identify(traits, ctx, source) {
 			const { userId: id, ...rest } =
 				traits && typeof traits === 'object' ? traits : {};
-			if (id !== undefined) userId = realId(id);
+			if (id !== undefined) {
+				const next = realId(id);
+				if (source === IDENTITY_OPTION) {
+					optionsUserId = next;
+				} else if (identifiedUserId && next && next !== identifiedUserId) {
+					// The host named another user after an earlier one on this page: nothing the last one
+					// built up carries over. A host cookie or bootstrap's identity option never counts as
+					// the earlier user: either may name the same person in another form.
+					forgetVisitor();
+				} else if (
+					cfg.debug &&
+					optionsUserId &&
+					next &&
+					next !== optionsUserId
+				) {
+					console.warn(
+						'[hp] identify names another userId than the identity option; using the new one',
+					);
+				}
+				userId = next;
+				if (next && source !== IDENTITY_OPTION) identifiedUserId = next;
+			}
 			// A digest in hex or base64 is sent as hex; anything that is not one is not sent.
 			if (typeof rest.email_sha256 === 'string') {
 				const email = normaliseSha256(rest.email_sha256);
@@ -638,9 +753,16 @@ export function createAnalytics(options) {
 			return emit({ type: 'identify', traits: rest }, ctx);
 		},
 
-		/** Clear identity on sign-out so the next events are not attributed to the old user. */
+		/**
+		 * Clear the signed-in user. At a real sign-out (a user was signed in), also forget what the visit
+		 * built up and the SDK's own device id, so the next person on a shared device inherits none of
+		 * it. A device id from the site's own cookie stays: the site owns it.
+		 */
 		reset() {
+			if (userId) forgetVisitor();
 			userId = null;
+			identifiedUserId = null;
+			optionsUserId = null;
 			writeLastPageMessageId('');
 		},
 
@@ -706,7 +828,14 @@ export function createAnalytics(options) {
 		personalisationGroup,
 		productClicked: (p, c) => track('Product Clicked', p, c),
 		productListFiltered: (p, c) => track('Product List Filtered', p, c),
+		/** A submitted search and the results page it produced: the query, its results and `pagination`. */
 		productsSearched: (p, c) => track('Products Searched', p, c),
+		/**
+		 * The search box's suggested products for a partly typed query, once seen: never
+		 * productsSearched, which is a submitted search's results page. A click on one carries this
+		 * set's `search_request_id`.
+		 */
+		searchSuggestionsViewed: (p, c) => track('Search Suggestions Viewed', p, c),
 		productAdded: (p, c) => track('Product Added', p, c),
 		productRemoved: (p, c) => track('Product Removed', p, c),
 		/**
@@ -758,7 +887,10 @@ export function createAnalytics(options) {
 		/** Sent under the signed-in identity, which is then cleared for whoever uses the device next. */
 		signedOut(c) {
 			const event = track('Signed Out', {}, c);
+			if (userId) forgetVisitor();
 			userId = null;
+			identifiedUserId = null;
+			optionsUserId = null;
 			return event;
 		},
 		newsletterSubscribed: (p, c) => track('Newsletter Subscribed', p, c),
@@ -796,7 +928,7 @@ export function createAnalytics(options) {
 		get lastPageMessageId() {
 			return readLastPageMessageId();
 		},
-		/** The device id events carry: the site's cookie's, or under `hp_cookie` the SDK's own. */
+		/** The device id events carry: the site's, or the SDK's own under `hp_cookie` or without one. */
 		get anonymousId() {
 			return realId(perRequest(cfg.getAnonymousId, null));
 		},
@@ -814,5 +946,5 @@ export function createAnalytics(options) {
 				replaying = null;
 			}
 		},
-	};
+	});
 }

package/src/recommendation-context.js

@@ -7,6 +7,8 @@
  * `new URLSearchParams(context)` is the query string to append, and an empty visit appends nothing.
  */
 
+import { parseConsentCookie } from './consent.js';
+import { getCookie } from './context.js';
 import { storageName } from './storage-scope.js';
 
 /** packages/cdp/src/recommendations/request.ts: MAX_IDS, MAX_ID_LENGTH, five queries, 60 pairs. */
@@ -86,9 +88,16 @@ export function forgetVisit() {
 	}
 }
 
-/** The visit an earlier page kept, or `{}` once it has lapsed. */
+/**
+ * The visit an earlier page kept, or `{}` once it has lapsed, or when the consent cookie does not
+ * grant personalisation: a withdrawal on a page this SDK never ran on still stops it being read.
+ */
 export function keptVisit(now = Date.now()) {
 	try {
+		const { personalisation } = parseConsentCookie(
+			getCookie(storageName('consent')),
+		);
+		if (personalisation !== true) return {};
 		const kept = JSON.parse(
 			localStorage.getItem(storageName('recommendationContext')) ?? 'null',
 		);

package/src/sampling.js

@@ -0,0 +1,19 @@
+/**
+ * Sampling (3.18): the source's settings may send for only a share of visitors. Decided per
+ * anonymous id, so a visitor is in or out for every event, on every page and in every tab, as the
+ * holdout is. A visitor with no anonymous id yet is kept.
+ */
+
+import { hashBucket } from './experiments.js';
+
+/** Salts the hash, so who is sampled is independent of who is held out or in an experiment. */
+export const SAMPLE_SALT = 'hp_sample';
+
+const BUCKETS = 10000;
+
+/** Whether the visitor `unit` is sent for at `rate`, a share in [0, 1]. */
+export function sampledIn(unit, rate) {
+	if (!(typeof rate === 'number' && rate < 1)) return true;
+	if (unit == null || unit === '') return true;
+	return hashBucket(unit, SAMPLE_SALT, BUCKETS) < Math.round(rate * BUCKETS);
+}

package/src/segment.js

@@ -52,6 +52,11 @@ import { VERSION } from './version.js';
 
 /** Option key that lets the withdrawal record through a gate that is about to close. */
 const WITHDRAWAL_FLAG = 'thg_hp_consent_withdrawal';
+/**
+ * The device id a withdrawal withdraws, taken when it is announced: analytics-next runs the plugin
+ * later, after the refusal has forgotten that id.
+ */
+const WITHDRAWN_AS = 'thg_hp_withdrawn_as';
 
 /** Context keys analytics-next fills itself; the spec's versions (scrubbed, site locale) replace them. */
 const LIBRARY_OWNED = new Set([
@@ -234,14 +239,17 @@ export function cdpPlugins(options = {}) {
 	function admit(ctx) {
 		const context = ctx.event.context ?? {};
 		const forced = context[WITHDRAWAL_FLAG] === true;
+		const withdrawnAs = context[WITHDRAWN_AS];
 		delete context[WITHDRAWAL_FLAG];
+		delete context[WITHDRAWN_AS];
 
 		if (off) throw cancellation(ctx, 'not enabled for this write key');
 		if (ctx.event.type === 'track' && !planAllows(cfg.plan, ctx.event.event)) {
 			throw cancellation(ctx, 'disabled by the tracking plan');
 		}
 
-		const anonymousId = cfg.getAnonymousId?.();
+		const anonymousId =
+			forced && withdrawnAs ? withdrawnAs : cfg.getAnonymousId?.();
 		if (anonymousId) ctx.updateEvent('anonymousId', String(anonymousId));
 
 		if (!gate || forced || gate.admits()) return ctx;
@@ -346,7 +354,12 @@ export function cdpPlugins(options = {}) {
 					analytics.track(
 						'Consent Updated',
 						{ action, state },
-						withdrawal ? { [WITHDRAWAL_FLAG]: true } : undefined,
+						withdrawal
+							? {
+									[WITHDRAWAL_FLAG]: true,
+									[WITHDRAWN_AS]: cfg.getAnonymousId?.() ?? null,
+								}
+							: undefined,
 					);
 				},
 			});

package/src/session/record.js

@@ -13,11 +13,12 @@ const ENGAGEMENT_EVENTS = new Set([
 	'Product Added to Wishlist',
 ]);
 
-/** Engagement the warehouse's category affinity does not count, so a session measure must not. */
-const UNCOUNTED_ENGAGEMENT = new Set([
-	'Product Clicked',
-	'Product Added to Wishlist',
-]);
+/**
+ * The browsing events the warehouse's category affinity counts (identifier_affinity_daily), so a
+ * session measure counts the same: a product shown in a listing, removed or found in search is not
+ * interest. The warehouse also counts orders, which a visit's own measure leaves out.
+ */
+const CATEGORY_EVENTS = new Set(['Product Viewed', 'Product Added']);
 
 /**
  * Fold one CDP event into the session signals.
@@ -39,9 +40,8 @@ export function recordSessionEvent(eventName, properties) {
 			bump(s.recentBrowse, s.browsingCategory);
 			break;
 		case 'Product List Viewed':
-			s.listViews += 1;
-			// Only a category list is browsing. A rail or carousel names its widget (no slash, or a
-			// `cdp-` id), and counting it would let personalisation measure itself.
+			// Only a category list is browsing, or a category page viewed. A rail or carousel names its
+			// widget (no slash, or a `cdp-` id), and counting it would let personalisation measure itself.
 			{
 				const list = properties?.list_id;
 				const isCategoryPath =
@@ -49,6 +49,7 @@ export function recordSessionEvent(eventName, properties) {
 					list.includes('/') &&
 					!list.startsWith('cdp-');
 				if (isCategoryPath) {
+					s.listViews += 1;
 					s.browsingCategory = bump(s.recentBrowse, list) ?? s.browsingCategory;
 				}
 			}
@@ -103,6 +104,19 @@ export function recordSessionEvent(eventName, properties) {
 		case 'Product Clicked':
 		case 'Product Added to Wishlist':
 			break;
+		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.
+			const value = properties?.value;
+			s.basketValue =
+				typeof value === 'number' && Number.isFinite(value) && value >= 0
+					? value
+					: null;
+			writeSignals(s);
+			return s;
+		}
 		default:
 			return s;
 	}
@@ -146,7 +160,7 @@ export function recordSessionEvent(eventName, properties) {
 			].slice(0, RECENT_LIMIT);
 		}
 		if (
-			!UNCOUNTED_ENGAGEMENT.has(eventName) &&
+			CATEGORY_EVENTS.has(eventName) &&
 			typeof p.category === 'string' &&
 			p.category
 		) {