@thg-agentic/hyper-personalisation-web 3.18.0 → 3.22.0

package/src/session/record.js

@@ -1,4 +1,4 @@
-import { bump, categoryKey } from './category.js';
+import { bump, categoryKey, pathPrefix } from './category.js';
 import { readSignals, writeSignals } from './signals.js';
 
 const RECENT_LIMIT = 20;
@@ -13,11 +13,46 @@ 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']);
+
+/** The most listing categories a visit counts views of: more than any visit browses. */
+const LIST_CATEGORY_LIMIT = 50;
+
+/**
+ * One interaction with a browse key, and beside it the category of the listing it was reached from
+ * (null for none), so each trail entry is judged on its own listing, as gold judges each event.
+ * Returns the key used.
+ */
+function browsed(s, value) {
+	const key = bump(s.recentBrowse, value);
+	if (!key) return null;
+	// Older visits have no categories: the two lists stay aligned at the head, where entries enter.
+	s.recentBrowseCategories = [
+		s.browsingListing?.category ?? null,
+		...s.recentBrowseCategories,
+	].slice(0, s.recentBrowse.length);
+	return key;
+}
+
+/** One listing view of a category, the counts kept to the categories most viewed. */
+function countListView(s, category) {
+	const counts = s.listViewsByCategory;
+	counts[category] = (counts[category] ?? 0) + 1;
+	const categories = Object.keys(counts);
+	if (categories.length > LIST_CATEGORY_LIMIT) {
+		const kept = {};
+		for (const c of categories
+			.sort((a, b) => counts[b] - counts[a])
+			.slice(0, LIST_CATEGORY_LIMIT))
+			kept[c] = counts[c];
+		s.listViewsByCategory = kept;
+	}
+}
 
 /**
  * Fold one CDP event into the session signals.
@@ -36,38 +71,64 @@ export function recordSessionEvent(eventName, properties) {
 	switch (eventName) {
 		case 'Product Viewed':
 			s.productViews += 1;
-			bump(s.recentBrowse, s.browsingCategory);
+			browsed(s, 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.
+			// A listing must name its own `category`, as the warehouse requires. Each trail entry keeps
+			// that listing's category, as gold judges each event on its own: whether the catalogue files
+			// products under it (a category page, not a merchandising list) is decided against the
+			// datafile's `browse_categories` when audiences are resolved.
 			{
 				const list = properties?.list_id;
+				const category = properties?.category;
 				const isCategoryPath =
 					typeof list === 'string' &&
 					list.includes('/') &&
 					!list.startsWith('cdp-');
-				if (isCategoryPath) {
-					s.browsingCategory = bump(s.recentBrowse, list) ?? s.browsingCategory;
+				if (!isCategoryPath) break;
+				const listed =
+					typeof category === 'string'
+						? pathPrefix(categoryKey(category)) || null
+						: null;
+				const key = listed ? pathPrefix(categoryKey(list)) : '';
+				if (!key) {
+					// A page that is not recorded: what is viewed from it is not the last page's browsing.
+					s.browsingCategory = null;
+					s.browsingListing = null;
+					break;
 				}
+				s.browsingListing = { key, category: listed };
+				browsed(s, key);
+				s.browsingCategory = key;
+				countListView(s, listed);
+				s.listViews += 1;
 			}
 			break;
 		case 'Product List Filtered': {
-			// Storefronts whose menus link to facet URLs navigate by filtering.
+			// Storefronts whose menus link to facet URLs navigate by filtering: a facet of the listing
+			// being browsed, which carries that listing's category. A facet of a listing that was not
+			// recorded is not browsing either.
 			const change = properties?.change;
 			const list =
 				typeof properties?.list_id === 'string' ? properties.list_id : '';
 			const facet = typeof change?.value === 'string' ? change.value : '';
-			if (facet && change?.action !== 'removed') {
-				s.browsingCategory =
-					bump(s.recentBrowse, `${list}/${facet}`) ?? s.browsingCategory;
+			const listing = s.browsingListing;
+			if (
+				facet &&
+				change?.action !== 'removed' &&
+				listing &&
+				pathPrefix(categoryKey(list)) === listing.key
+			) {
+				const key = browsed(s, `${list}/${facet}`);
+				if (key) s.browsingCategory = key;
 			}
 			break;
 		}
 		case 'Product Added': {
 			s.cartAdds += 1;
-			bump(s.recentBrowse, s.browsingCategory);
+			browsed(s, s.browsingCategory);
 			for (const p of products) {
 				const id = p.product_id;
 				if (typeof id !== 'string' || !id) continue;
@@ -159,7 +220,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
 		) {

package/src/session/rules.js

@@ -131,15 +131,38 @@ export function resolveAudiences(
 	sessionAudiences,
 	signals = readSignals(),
 	qualifiedFor = [],
+	browseCategories = null,
 ) {
 	return resolveAudienceMemberships(
 		precomputed,
 		sessionAudiences,
 		signals,
 		qualifiedFor,
+		browseCategories,
 	).map((m) => m.id);
 }
 
+/**
+ * The visit as the warehouse counts browsing: only the listings whose own `category` the catalogue
+ * files products under (the datafile's `browse_categories`), so a merchandising list (best sellers,
+ * new in, a sale) is never browsing interest. Each trail entry is judged on the listing it came
+ * from. Without the list (a datafile that predates it, or a serving store with no catalogue yet),
+ * the visit as recorded.
+ */
+export function catalogueBrowse(signals, browseCategories) {
+	if (!Array.isArray(browseCategories)) return signals;
+	const held = new Set(browseCategories);
+	const categories = signals.recentBrowseCategories ?? [];
+	const recentBrowse = (signals.recentBrowse ?? []).filter((_, i) =>
+		held.has(categories[i]),
+	);
+	const listViews = Object.entries(signals.listViewsByCategory ?? {}).reduce(
+		(sum, [category, n]) => (held.has(category) ? sum + n : sum),
+		0,
+	);
+	return { ...signals, recentBrowse, listViews };
+}
+
 /**
  * The same resolution, with where each membership came from, for `context.audiences`.
  *
@@ -151,7 +174,9 @@ export function resolveAudienceMemberships(
 	sessionAudiences,
 	signals = readSignals(),
 	qualifiedFor = [],
+	browseCategories = null,
 ) {
+	const visit = catalogueBrowse(signals, browseCategories);
 	const active = new Set(precomputed);
 	const bySlug = new Map();
 	// Qualifying on history is not membership of a mixed audience, so this stays out of `active`.
@@ -176,7 +201,7 @@ export function resolveAudienceMemberships(
 			if (!required.every(met)) continue;
 			if (audience.mixed && !qualified.has(audience.slug)) continue;
 			if (!audience.rules || audience.rules.length === 0) continue;
-			if (sessionRulesHold(audience, signals)) {
+			if (sessionRulesHold(audience, visit)) {
 				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');

package/src/session/signals.js

@@ -95,6 +95,12 @@ function emptySignals() {
 		// read as interest. The threshold that makes them meaningful lives server-side in `fatigue.ts`.
 		impressions: {},
 		browsingCategory: null,
+		// Beside each `recentBrowse` entry, the category of the listing it came from (two levels,
+		// `categoryKey` spelling, null for none); the listing being browsed; and listing views per
+		// category. What `browse_categories` is checked against when audiences are resolved.
+		recentBrowseCategories: [],
+		browsingListing: null,
+		listViewsByCategory: {},
 		startedAt: 0,
 	};
 }

package/src/session.js

@@ -14,6 +14,7 @@ export {
 } from './session/category.js';
 export { recordSessionEvent } from './session/record.js';
 export {
+	catalogueBrowse,
 	evaluateSessionRule,
 	measureField,
 	resolveAudienceMemberships,

package/src/settings.js

@@ -51,6 +51,19 @@ export function resolveApiHost(host) {
 		: apiOrigin(host);
 }
 
+/**
+ * Where events go. An `apiHost` the integrator set is a first-party proxy and carries events too;
+ * the settings' host applies only when none was set, and only over https (as the app SDKs do).
+ */
+export function eventsHost(configured, fromSettings) {
+	const hasConfigured =
+		configured !== undefined && configured !== null && configured !== '';
+	if (hasConfigured) return resolveApiHost(configured);
+	return fromSettings?.startsWith('https://')
+		? fromSettings
+		: resolveApiHost(undefined);
+}
+
 /**
  * An API host as an origin. The settings give a bare host (`api.example.com`, the OpenAPI server
  * variable); an integrator may write either. Anything else is not a host.
@@ -143,6 +156,16 @@ function readAnonymousId(raw) {
 		: null;
 }
 
+/**
+ * Whether a 2xx body is a settings answer at all: an `hp` block saying on or off. Anything else (a
+ * captive portal's page, a proxy's error) is no answer, so the last good settings and what was
+ * carried are kept, as on Android, iOS and React Native.
+ */
+export function isSettingsAnswer(body) {
+	const hp = isObject(body) ? body.hp : null;
+	return isObject(hp) && typeof hp.enabled === 'boolean';
+}
+
 /**
  * The settings response as the SDK uses it, or DISABLED for anything that does not switch it on.
  * Unknown fields are ignored, so the API can add to the response without breaking a deployed SDK.
@@ -191,7 +214,8 @@ export async function fetchSettings(
 			headers: { accept: 'application/json' },
 		});
 		if (!res.ok) return null;
-		return readSettings(await res.json());
+		const body = await res.json();
+		return isSettingsAnswer(body) ? readSettings(body) : null;
 	} catch {
 		return null;
 	}

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

package/src/transport.js

@@ -32,12 +32,30 @@ const DEFAULTS = {
 };
 
 const now = () => Date.now();
+const MAX_BACKOFF_MS = 30_000;
+
+/** The largest event the SDK sends: with its batch envelope it still fits one keepalive request. */
+export const MAX_EVENT_BYTES = 55 * 1024;
+
+/**
+ * Retry-After as milliseconds from now: delay-seconds or an HTTP date (RFC 9110 §10.2.3); 0 when
+ * absent or unreadable. Cross-origin, the browser exposes it only if the ingest lists it in
+ * Access-Control-Expose-Headers; a first-party proxy always can.
+ */
+export function retryAfterMs(value, at = now()) {
+	if (typeof value !== 'string') return 0;
+	const text = value.trim();
+	if (/^\d+$/.test(text)) return Number(text) * 1000;
+	if (text === '') return 0;
+	const date = Date.parse(text);
+	return Number.isNaN(date) ? 0 : Math.max(0, date - at);
+}
 
 /**
  * UTF-8 bytes, the unit of sendBeacon's ceiling and the keepalive budget. String length counts
  * UTF-16 code units and undercounts any non-ASCII catalogue.
  */
-const byteLength = (s) =>
+export const byteLength = (s) =>
 	typeof TextEncoder !== 'undefined'
 		? new TextEncoder().encode(s).length
 		: Buffer.byteLength(s);
@@ -77,6 +95,12 @@ export class Transport {
 		this.inflight = null;
 		// Ids of persisted entries this instance is already sending, so a replay never races them.
 		this.sending = new Set();
+		/** Bumped by a refusal: batches cut before it are not sent or retried after it. */
+		this.epoch = 0;
+		/** Persisted ids of the batches cut since the last refusal: the withdrawal's among them. */
+		this.sinceRefusal = new Set();
+		/** End backoff waits early, so a refusal is not held behind a retry. */
+		this.wakers = new Set();
 		this.replayAllowed = !this.o.deferReplay;
 		this.draining = null;
 
@@ -105,12 +129,31 @@ export class Transport {
 		this.replayAllowed = false;
 		if (!this.storage) return;
 		try {
-			this.storage.removeItem(this.o.storageKey);
+			// A batch cut since the refusal is the withdrawal: it keeps its saved copy until delivered.
+			const kept = this.#readPersisted().filter((entry) =>
+				this.sinceRefusal.has(entry?.id),
+			);
+			if (kept.length)
+				this.storage.setItem(this.o.storageKey, JSON.stringify(kept));
+			else this.storage.removeItem(this.o.storageKey);
 		} catch {
 			/* nothing was readable, so nothing will be replayed either */
 		}
 	}
 
+	/**
+	 * Drop every event queued in memory, and stop sending or retrying the batches already cut from
+	 * it. For a refusal: what was collected under the permission is not sent after it is withdrawn.
+	 * The batch already on the wire cannot be recalled.
+	 */
+	discardQueued() {
+		this.queue = [];
+		this.epoch += 1;
+		this.sinceRefusal.clear();
+		this.#clearTimer();
+		for (const wake of this.wakers) wake();
+	}
+
 	/**
 	 * Queued as its JSON form, made once here: an event JSON cannot serialise (a BigInt, a cycle, a
 	 * throwing toJSON) is dropped on its own, rather than throwing from every later flush and holding
@@ -221,12 +264,22 @@ export class Transport {
 		).map((batch) => {
 			const id = this.#persist(batch);
 			// Claimed now, not when its turn comes, so a replay started meanwhile does not send it too.
-			if (id) this.sending.add(id);
+			if (id) {
+				this.sending.add(id);
+				this.sinceRefusal.add(id);
+			}
 			return { batch, id };
 		});
 		this.queue = [];
+		const epoch = this.epoch;
 		this.inflight = (async () => {
-			for (const { batch, id } of batches) await this.#send(batch, 0, id);
+			for (const { batch, id } of batches) {
+				if (epoch !== this.epoch) {
+					this.#settle(id);
+					continue;
+				}
+				await this.#send(batch, 0, id, epoch);
+			}
 		})().finally(() => {
 			this.inflight = null;
 			if (this.queue.length >= this.o.flushAt) this.flush();
@@ -279,9 +332,10 @@ export class Transport {
 	 * The body is rebuilt on every attempt: the ingest corrects clock skew against `sentAt`, so a
 	 * stale `sentAt` would shift every timestamp in the batch by the time spent waiting.
 	 */
-	async #send(batch, attempt, persisted = null) {
+	async #send(batch, attempt, persisted = null, epoch = this.epoch) {
 		if (persisted) this.sending.add(persisted);
 		const body = this.#body(batch);
+		let wait = 0;
 		try {
 			const res = await fetch(this.#url(), {
 				method: 'POST',
@@ -297,9 +351,11 @@ export class Transport {
 				this.#drainPersisted();
 				return true;
 			}
-			// 4xx (except 429) means the payload is wrong; retrying cannot fix it and
+			// 4xx (except 408 and 429) means the payload is wrong; retrying cannot fix it and
 			// would loop forever. Drop and surface.
-			const retryable = res.status === 429 || res.status >= 500;
+			const retryable =
+				res.status === 408 || res.status === 429 || res.status >= 500;
+			if (retryable) wait = retryAfterMs(res.headers?.get?.('retry-after'));
 			if (!retryable) {
 				this.#settle(persisted);
 				this.o.onError?.(
@@ -318,16 +374,33 @@ export class Transport {
 				);
 				return false;
 			}
-			const delay =
-				Math.min(1000 * 2 ** attempt, 30_000) * (0.5 + Math.random());
-			await new Promise((r) => setTimeout(r, delay));
-			return this.#send(batch, attempt + 1, persisted);
+			// The ingest's Retry-After is a floor on the backoff, within the same cap.
+			const delay = Math.max(
+				Math.min(1000 * 2 ** attempt, MAX_BACKOFF_MS) * (0.5 + Math.random()),
+				Math.min(wait, MAX_BACKOFF_MS),
+			);
+			if (epoch === this.epoch)
+				await new Promise((r) => {
+					const wake = () => {
+						clearTimeout(timer);
+						this.wakers.delete(wake);
+						r();
+					};
+					const timer = setTimeout(wake, delay);
+					this.wakers.add(wake);
+				});
+			if (epoch !== this.epoch) {
+				this.#settle(persisted);
+				return false;
+			}
+			return this.#send(batch, attempt + 1, persisted, epoch);
 		}
 	}
 
 	#settle(id) {
 		if (!id) return;
 		this.sending.delete(id);
+		this.sinceRefusal.delete(id);
 		this.#unpersist(id);
 	}
 

package/src/version.js

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

package/types/bootstrap.d.ts

@@ -45,7 +45,7 @@ export interface SettingsResponse {
 	plan?: { track?: Record<string, { enabled?: boolean }> };
 	hp?: {
 		enabled: boolean;
-		/** Null for a source scoped to several properties: the page passes `propertyId`. */
+		/** The source's default property, or null. A `propertyId` the page passes wins over it. */
 		propertyId?: string | null;
 		environment?: 'production' | 'staging' | 'development';
 		/** Strict is the only mode. `purposes`: the ones this property asks for, and so reports. */

package/types/consent.d.ts

@@ -1,9 +1,7 @@
-export type ConsentPurpose =
-	| 'analytics'
-	| 'marketing'
-	| 'personalisation'
-	| 'ad_user_data'
-	| 'ad_personalization';
+import type { CdpConsentPurpose } from './events';
+
+/** The purposes a visitor answers for: the spec's, generated. */
+export type ConsentPurpose = CdpConsentPurpose;
 
 /** schemas/common/consent-state.json: true granted, false refused, null never asked. */
 export type ConsentState = Record<ConsentPurpose, boolean | null>;