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

package/src/index.js

@@ -45,7 +45,7 @@
 import { assignmentSession, surfaceExposureToken } from './assignment.js';
 import { hostConsent, servingHeaders } from './consent.js';
 import { createConsentGate } from './consent-gate.js';
-import { buildContext, getCookie, perRequest } from './context.js';
+import { buildContext, getCookie, perRequest, scrubHref } from './context.js';
 import { createDecisionMemory, servedDecisions } from './decisions.js';
 import { createHeldStore, deviceIdFrom } from './device-storage.js';
 import {
@@ -183,6 +183,64 @@ export function normaliseSha256(value) {
 	return hex === EMPTY_SHA256 ? null : hex;
 }
 
+/** The identify traits the spec defines (core/identify, `additionalProperties: false`), by type. */
+export const IDENTIFY_TRAITS = Object.freeze({
+	email_sha256: 'sha256',
+	phone_sha256: 'sha256',
+	accepts_marketing: 'boolean',
+	gender: 'string',
+	created_at: 'date-time',
+});
+
+const RFC3339 =
+	/^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)$/i;
+
+/** An RFC 3339 date-time naming a real day: 2026-02-30 is not one, though Date.parse rolls it on. */
+function isDateTime(value) {
+	if (typeof value !== 'string' || !RFC3339.test(value)) return false;
+	const [year, month, day] = value.slice(0, 10).split('-').map(Number);
+	const date = new Date(Date.UTC(year, month - 1, day));
+	return (
+		date.getUTCMonth() === month - 1 &&
+		date.getUTCDate() === day &&
+		!Number.isNaN(Date.parse(value))
+	);
+}
+
+/** One trait as the spec takes it, or undefined when it is not one: then it is not sent. */
+function identifyTrait(kind, value) {
+	if (value === null) return null;
+	if (kind === 'sha256') return normaliseSha256(value) ?? undefined;
+	if (kind === 'date-time') {
+		if (value instanceof Date)
+			return Number.isNaN(value.getTime()) ? undefined : value.toISOString();
+		return isDateTime(value) ? value : undefined;
+	}
+	return typeof value === kind ? value : undefined;
+}
+
+/**
+ * Only the traits the spec defines, each of its type: a raw email or phone never leaves the page, and
+ * an identify is never quarantined for an extra key. Digests in hex or base64 are sent as hex.
+ */
+function identifyTraits(traits, debug) {
+	const kept = {};
+	const dropped = [];
+	for (const [key, value] of Object.entries(traits)) {
+		const kind = Object.hasOwn(IDENTIFY_TRAITS, key)
+			? IDENTIFY_TRAITS[key]
+			: null;
+		const trait = kind ? identifyTrait(kind, value) : undefined;
+		if (trait === undefined) dropped.push(key);
+		else kept[key] = trait;
+	}
+	if (debug && dropped.length)
+		console.warn(
+			`[hp] identify: not sent, not spec traits: ${dropped.join(', ')}`,
+		);
+	return kept;
+}
+
 // On the main entry so integrators find them: without an assigned variant a rail is unmeasurable.
 export {
 	assignRecommendationVariant,
@@ -336,6 +394,13 @@ export function createAnalytics(options) {
 		}
 	};
 
+	// A document restored from the back/forward cache resumes after the pages it led to: the tab's
+	// last page view is the one in storage, not this document's own.
+	if (typeof window !== 'undefined')
+		window.addEventListener('pageshow', (event) => {
+			if (event.persisted) lastPageMessageId = null;
+		});
+
 	const writeLastPageMessageId = (id) => {
 		lastPageMessageId = id || null;
 		if (strict && gate.status !== 'granted') return;
@@ -375,6 +440,10 @@ export function createAnalytics(options) {
 	function compose(partial, ctxOverrides, force) {
 		const made = replaying;
 		replaying = null;
+		// The plan is keyed as the gateway keys it: a track's name, otherwise the call's type. A
+		// withdrawal is the record of the refusal, so no plan drops it.
+		const key = partial.type === 'track' ? partial.event : partial.type;
+		if (!force && !planAllows(cfg.plan, key)) return null;
 		let event = {
 			messageId: made?.messageId ?? uuid(),
 			timestamp: made?.timestamp ?? new Date().toISOString(),
@@ -385,6 +454,8 @@ export function createAnalytics(options) {
 		};
 
 		if (event.properties) event.properties = pruneProperties(event.properties);
+		if (typeof event.properties?.href === 'string')
+			event.properties.href = scrubHref(event.properties.href, cfg);
 
 		// Outside the source's sample (3.18): nothing about this visitor is sent.
 		if (!force && !sampledIn(event.anonymousId, cfg.sampleRate)) {
@@ -514,9 +585,7 @@ export function createAnalytics(options) {
 	}
 
 	const track = (name, properties, ctx) =>
-		planAllows(cfg.plan, name)
-			? emit({ type: 'track', event: name, properties: properties ?? {} }, ctx)
-			: null;
+		emit({ type: 'track', event: name, properties: properties ?? {} }, ctx);
 
 	// One exposure event per serving response, however often the page reuses it.
 	const exposedTokens = new Set();
@@ -588,6 +657,8 @@ export function createAnalytics(options) {
 				// forgets the signals an earlier page kept under the permission.
 				if (state?.personalisation !== true)
 					forgetKeptVisit(previous?.personalisation === true);
+				// Events collected under the grant are not sent after it is withdrawn: only the withdrawal.
+				if (withdrawal) transport.discardQueued?.();
 				emit(
 					{
 						type: 'track',
@@ -682,9 +753,19 @@ export function createAnalytics(options) {
 		);
 	}
 
+	/** After a sign-out is sent under the signed-in identity: clear it for whoever uses the device next. */
+	function signOut(event) {
+		if (userId) forgetVisitor();
+		userId = null;
+		identifiedUserId = null;
+		optionsUserId = null;
+		return event;
+	}
+
 	return guardMethods({
 		/** Escape hatch for events not yet in the core spec. Prefer a named method. */
-		track,
+		track: (event, p, c) =>
+			event === 'Signed Out' ? signOut(track(event, p, c)) : track(event, p, c),
 
 		page(props, ctx) {
 			props ??= {};
@@ -744,13 +825,10 @@ export function createAnalytics(options) {
 				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);
-				if (email) rest.email_sha256 = email;
-				else delete rest.email_sha256;
-			}
-			return emit({ type: 'identify', traits: rest }, ctx);
+			return emit(
+				{ type: 'identify', traits: identifyTraits(rest, cfg.debug) },
+				ctx,
+			);
 		},
 
 		/**
@@ -885,14 +963,7 @@ export function createAnalytics(options) {
 		signedIn: (p, c) => track('Signed In', p, c),
 		signedUp: (p, c) => track('Signed Up', p, c),
 		/** 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;
-		},
+		signedOut: (c) => signOut(track('Signed Out', {}, c)),
 		newsletterSubscribed: (p, c) => track('Newsletter Subscribed', p, c),
 		/** An on-site opt-out. The ESP reports its own as Email Unsubscribed. */
 		newsletterUnsubscribed: (p, c) => track('Newsletter Unsubscribed', p, c),

package/src/segment.js

@@ -33,7 +33,7 @@ import { hostConsent, reportingPurposes } from './consent.js';
 import { createConsentGate } from './consent-gate.js';
 import { buildContext, CONTEXT_KEYS } from './context.js';
 import { deviceIdFrom } from './device-storage.js';
-import { planAllows, readSettings, resolveApiHost } from './settings.js';
+import { eventsHost, planAllows, readSettings } from './settings.js';
 
 export { DEFAULT_API_HOST } from './settings.js';
 
@@ -134,12 +134,20 @@ export function hpLoadOptions({ writeKey, apiHost }) {
 		disableClientPersistence: true,
 		updateCDNSettings(cdnSettings) {
 			const integrations = { ...cdnSettings.integrations };
-			if (!integrations['Segment.io']?.apiHost) {
-				const origin =
-					readSettings(cdnSettings).apiHost ?? resolveApiHost(apiHost);
+			const block = integrations['Segment.io'];
+			// The settings' block is kept only where the settings' host would be: no apiHost set, and https.
+			const configured =
+				apiHost !== undefined && apiHost !== null && apiHost !== '';
+			if (
+				configured ||
+				!block?.apiHost ||
+				(block.protocol ?? 'https') !== 'https'
+			) {
+				const origin = eventsHost(apiHost, readSettings(cdnSettings).apiHost);
 				if (!origin) return cdnSettings;
 				const { protocol, host } = new URL(origin);
 				integrations['Segment.io'] = {
+					...block,
 					apiKey: writeKey,
 					apiHost: `${host}/v1`,
 					protocol: protocol.replace(':', ''),
@@ -156,8 +164,8 @@ export function hpLoadOptions({ writeKey, apiHost }) {
 
 /**
  * @param {object} options Same names and meanings as createAnalytics().
- * @param {string} [options.propertyId] For a key scoped to several properties, or without settings:
- *   the `hp` block's propertyId wins when it has one.
+ * @param {string} [options.propertyId] The page's property. It wins over the `hp` block's, which is
+ *   the source's default property, as on Android, iOS and React Native.
  * @param {string} [options.channel]
  * @param {string} [options.market]
  * @param {string} [options.environment]
@@ -181,7 +189,6 @@ export function hpLoadOptions({ writeKey, apiHost }) {
  * @param {object} [options.anonymousIdSource] Only without settings: the `hp` block's wins.
  * @param {() => string|null} [options.getPageType]
  * @param {() => string|null} [options.getSessionId]
- * @param {() => string|null} [options.getRenderId]
  * @param {() => object|null} [options.getExtensions]
  * @param {() => object[]|null} [options.getExperiments]
  * @param {() => object[]|null} [options.getAudiences]
@@ -211,7 +218,7 @@ export function cdpPlugins(options = {}) {
 		if (cdnSettings?.hp !== undefined) {
 			const settings = readSettings(cdnSettings);
 			if (settings.enabled) {
-				cfg.propertyId = settings.propertyId ?? cfg.propertyId;
+				cfg.propertyId = cfg.propertyId ?? settings.propertyId;
 				cfg.environment = settings.environment;
 				if (settings.queryParamAllowlist)
 					cfg.queryParamAllowlist = settings.queryParamAllowlist;
@@ -244,7 +251,8 @@ export function cdpPlugins(options = {}) {
 		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)) {
+		const key = ctx.event.type === 'track' ? ctx.event.event : ctx.event.type;
+		if (!forced && !planAllows(cfg.plan, key)) {
 			throw cancellation(ctx, 'disabled by the tracking plan');
 		}
 

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;
@@ -20,6 +20,40 @@ const ENGAGEMENT_EVENTS = new Set([
  */
 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.
  *
@@ -37,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':
 			// 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.listViews += 1;
-					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;

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

package/src/transport.js

@@ -95,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;
 
@@ -123,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
@@ -239,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();
@@ -297,7 +332,7 @@ 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;
@@ -316,9 +351,10 @@ 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);
@@ -343,14 +379,28 @@ export class Transport {
 				Math.min(1000 * 2 ** attempt, MAX_BACKOFF_MS) * (0.5 + Math.random()),
 				Math.min(wait, MAX_BACKOFF_MS),
 			);
-			await new Promise((r) => setTimeout(r, delay));
-			return this.#send(batch, attempt + 1, persisted);
+			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.19.0';
+export const VERSION = '3.22.2';
 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. */