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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thg-agentic/hyper-personalisation-web",
-  "version": "3.17.1",
+  "version": "3.18.0",
   "description": "Browser SDK for the THG Hyper-Personalisation event specification: event tracking from a write key and remote settings, strict CMP-agnostic consent, a GA4 dataLayer bridge and in-session audience evaluation. Dependency-free ESM on the Segment wire protocol, a CDN script (dist/hp.min.js), and an optional @segment/analytics-next plugin path.",
   "type": "module",
   "main": "./src/index.js",
@@ -74,7 +74,7 @@
     "esbuild": "^0.28.2",
     "jsdom": "^30.1.1",
     "typescript": "^7.0.2",
-    "@thg-agentic/hyper-personalisation-spec": "1.8.1"
+    "@thg-agentic/hyper-personalisation-spec": "1.10.0"
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs",

package/src/bootstrap.js

@@ -10,7 +10,8 @@
  * The key is the whole config: `apiHost` is optional, for a first-party proxy (DEFAULT_API_HOST
  * otherwise). Everything tenant-level comes from `GET {apiHost}/v1/projects/{writeKey}/settings`: whether the
  * SDK is on, the property, the environment, the reported consent purposes, the query-param
- * allowlist, where device ids come from, and the tracking plan. What only the page can know stays
+ * allowlist, where device ids come from, the tracking plan (which events are blocked), the sampling
+ * rate and debug logging. What only the page can know stays
  * in code: the CMP, the session cookie's name (and, for a source whose settings name no device
  * cookie, the device cookie's), the per-request currency / ship-to / locale getters, the preset,
  * the page type, debug, and which property this page is for a key scoped to several.
@@ -39,6 +40,7 @@ import {
 } from './consent.js';
 import { getCookie } from './context.js';
 import { connectDataLayer } from './datalayer.js';
+import { sessionDebug } from './debug.js';
 import { createAnalytics, normaliseSha256, PAGE_TYPES } from './index.js';
 import {
 	cachedSettings,
@@ -49,7 +51,7 @@ import {
 	readSettings,
 	resolveApiHost,
 } from './settings.js';
-import { realId } from './shape.js';
+import { realId, uuid } from './shape.js';
 import {
 	configureStorageNames,
 	migrateLegacyStorage,
@@ -261,6 +263,17 @@ export function bootstrap(config, options = {}) {
 	return started;
 }
 
+/**
+ * When this document was navigated to: the wall clock less the time since, not `timeOrigin`, which
+ * browsers derive from a monotonic clock that drifts from the wall clock after a sleep.
+ */
+function navigatedAt() {
+	const since = globalThis.performance?.now?.();
+	return new Date(
+		Date.now() - (Number.isFinite(since) ? since : 0),
+	).toISOString();
+}
+
 /**
  * The declarative trackers: they report only what the page tags (`data-hp-promotion`,
  * `data-hp-list` / `data-hp-product`, `data-hp-reco-request`, `data-hp-exposure`), so they are on
@@ -353,6 +366,11 @@ async function start(config, options, carry) {
 
 		const { preset } = options;
 		const identified = pendingIdentify(propertyId, identity);
+		// Settings from before 3.18, cached or served, have none of these: nothing sampled, no logging.
+		const debug =
+			options.debug === true ||
+			settings.debug?.enabled === true ||
+			sessionDebug(settings.debug?.tokenSha256 ?? null, storageName('debug'));
 		const userId = realId(identity?.userId);
 
 		const client = createAnalytics({
@@ -365,6 +383,7 @@ async function start(config, options, carry) {
 			environment: settings.environment,
 			queryParamAllowlist: settings.queryParamAllowlist ?? undefined,
 			plan: settings.plan,
+			sampleRate: settings.sampleRate ?? 1,
 			holdout: settings.holdouts?.[propertyId],
 			// Per request, never per tenant: a site can trade in several currencies and ship anywhere.
 			getCurrency: options.getCurrency,
@@ -376,7 +395,7 @@ async function start(config, options, carry) {
 			holdAcrossPages: options.holdAcrossPages === true,
 			// Deprecated in 3.6 and ignored; passed on only so debug can say so.
 			mintAnonymousId: options.mintAnonymousId,
-			debug: options.debug === true,
+			debug,
 			// Where device ids come from is the source's: with no setting (settings from before 3.6),
 			// the cookie named here, as before.
 			anonymousIdSource: settings.anonymousId ?? undefined,
@@ -440,7 +459,16 @@ async function start(config, options, carry) {
 			}
 		}
 
-		client.page(options.pageType ? { type: options.pageType } : {});
+		// Stamped when the document was navigated to, not when the settings came back: the page view
+		// is the page's first event, ahead of what the page queued through `hp` meanwhile (#527).
+		client[REPLAY](
+			'page',
+			[options.pageType ? { type: options.pageType } : {}],
+			{
+				messageId: uuid(),
+				timestamp: navigatedAt(),
+			},
+		);
 		let stopAutocapture = startAutocapture(client, options.autocapture);
 		// Impressions count once per page view, so a single-page app's next route reports afresh.
 		const page = client.page;
@@ -463,7 +491,7 @@ async function start(config, options, carry) {
 					...(options.dataLayer.ignore ?? []),
 				],
 				onError: (err) =>
-					options.debug && console.warn('[hp] dataLayer mapping failed', err),
+					debug && console.warn('[hp] dataLayer mapping failed', err),
 			});
 		}
 

package/src/debug.js

@@ -0,0 +1,45 @@
+/**
+ * Session debug (3.18): `?hp_debug=<token>` turns console logging on for the rest of the browser
+ * session, but only when the token hashes to the one the source's settings name, so a shopper who
+ * guesses the parameter turns nothing on. `?hp_debug=` with no value ends it. The token is kept in
+ * sessionStorage and checked on every page against the settings that page starts from, so a token
+ * cleared in the console stops working once the browser has read the new settings.
+ */
+
+import { sha256Hex } from './hash.js';
+
+export const DEBUG_PARAM = 'hp_debug';
+
+const MAX_TOKEN_LENGTH = 256;
+
+function readParam() {
+	try {
+		return new URLSearchParams(location.search).get(DEBUG_PARAM);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Whether this session has debug on: apply the page URL's `hp_debug` to sessionStorage under
+ * `name`, then check what is kept against `tokenSha256`.
+ *
+ * @param {string|null} tokenSha256  The settings' `hp.debug.tokenSha256`.
+ * @param {string} name  The sessionStorage key, storageName('debug').
+ */
+export function sessionDebug(tokenSha256, name) {
+	if (typeof location === 'undefined') return false;
+	try {
+		const given = readParam();
+		if (given !== null) {
+			const token = given.trim();
+			if (token === '' || token.length > MAX_TOKEN_LENGTH)
+				sessionStorage.removeItem(name);
+			else sessionStorage.setItem(name, token);
+		}
+		const kept = sessionStorage.getItem(name);
+		return Boolean(tokenSha256 && kept && sha256Hex(kept) === tokenSha256);
+	} catch {
+		return false;
+	}
+}

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,13 @@ 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: the id must not outlive the permission it was kept under,
+		 * so a later grant starts a new device, as `analytics.reset()` does.
+		 */
 		forget() {
 			writeCookie(name, '', 0, domain);
+			id = null;
 			written = false;
 			try {
 				local()?.removeItem(legacyKey);
@@ -168,34 +172,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/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'),
@@ -59,6 +60,7 @@ import {
 	keepVisit,
 	recommendationContextFrom,
 } from './recommendation-context.js';
+import { sampledIn } from './sampling.js';
 import { recordSessionEvent } from './session/record.js';
 import {
 	clearSessionSignals,
@@ -102,6 +104,9 @@ export { emailSha256, getCookie };
 /** How a call made before the SDK started is replayed with the messageId and time it was made at. */
 const REPLAY = Symbol.for('@thg-agentic/hyper-personalisation-web.replay');
 
+/** `throwOnInvalid`: the one failure a caller asked to have thrown at them. */
+class InvalidEventError extends Error {}
+
 /** SHA-256 of a string as lowercase hex. Synchronous since 3.9 (sha256Hex); kept async for callers. */
 export async function sha256(value) {
 	return sha256Hex(String(value));
@@ -253,18 +258,18 @@ 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'),
@@ -322,7 +327,18 @@ export function createAnalytics(options) {
 	/** 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 +352,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,7 +384,7 @@ 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);
 			}
 		}
@@ -471,7 +493,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,7 +502,7 @@ 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 {
@@ -796,7 +818,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));
 		},

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

@@ -103,6 +103,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;
 	}

package/src/session/signals.js

@@ -67,6 +67,7 @@ function readUnscoped() {
 			parsed &&
 			(parsed.productViews > 0 ||
 				parsed.listViews > 0 ||
+				parsed.basketValue != null ||
 				parsed.recentProducts?.length ||
 				parsed.recentBrowse?.length);
 		return busy ? parsed : null;
@@ -86,6 +87,9 @@ function emptySignals() {
 		recentCategories: [],
 		recentBrowse: [],
 		basketProducts: [],
+		// The last Cart Updated's `value`, in its currency. Unknown (so every rule on it fails closed)
+		// until the visit sends one: a basket carried over from an earlier visit is not zero.
+		basketValue: 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/session-id.js

@@ -1,8 +1,8 @@
 /**
  * The session id the SDK keeps when the host names none (3.15): a first-party cookie holding a
  * random id, ended by 30 minutes without an event, as Amplitude and GA4 sessionise. A host that
- * has its own session (`getSessionId`, `identityCookies.sessionId`) keeps it: the SDK never mints a
- * second one beside it.
+ * has its own session (`getSessionId`, `identityCookies.sessionId`) keeps it; this one stands in
+ * only while the host's is missing or empty (3.18), so no event is sent without a session.
  *
  * The cookie is shared by the site's tabs and readable by its servers. Under strict consent it is
  * written only once analytics is granted; until then the id lives in memory, and it is deleted on

package/src/settings.js

@@ -9,7 +9,7 @@
  *
  * The last good answer is cached, only under an analytics grant (it is a device write), and a page
  * with a cache starts from it and revalidates in the background. Until the grant the HTTP cache
- * (`max-age=60, stale-while-revalidate=600`) saves the round trip.
+ * (`max-age=10` and an `ETag`) saves the round trip or answers a `304`.
  */
 
 import { storageKey, storageName } from './storage-scope.js';
@@ -38,12 +38,11 @@ export function settingsUrl(apiHost, writeKey) {
 }
 
 /**
- * Where the SDK talks to when the integrator names no host. The key alone selects the tenant, the
- * property and test or live, as with Stripe and LaunchDarkly; a host is only for a first-party proxy.
- * Until production is live this is the nonprod host, reachable only from allowlisted networks, so
- * for test keys, UAT and previews; the release that moves it to production is the one to go live on.
+ * Where the SDK talks to when the integrator names no host: the one host every client uses, for
+ * test and live keys alike. The key alone selects the tenant, the property and test or live, as
+ * with Stripe and LaunchDarkly; a host is only for a first-party proxy or our own nonprod testing.
  */
-export const DEFAULT_API_HOST = 'https://hp.uat.thgingenuity.com';
+export const DEFAULT_API_HOST = 'https://hp.thgingenuity.com';
 
 /** The integrator's `apiHost` as an origin, DEFAULT_API_HOST when none is given, null when invalid. */
 export function resolveApiHost(host) {
@@ -76,6 +75,23 @@ function readPurposes(raw) {
 const isFraction = (value) =>
 	typeof value === 'number' && value >= 0 && value <= 1;
 
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * Console logging (3.18): on for everyone, or for a session opened with `?hp_debug=<token>`, checked
+ * against the token's hash. Off when the settings do not say.
+ */
+function readDebug(raw) {
+	if (!isObject(raw)) return { enabled: false, tokenSha256: null };
+	return {
+		enabled: raw.enabled === true,
+		tokenSha256:
+			typeof raw.tokenSha256 === 'string' && SHA256_HEX.test(raw.tokenSha256)
+				? raw.tokenSha256
+				: null,
+	};
+}
+
 /**
  * The personalisation holdout per property, `{ share, ramp, salt, readoutSlots }`, or null when the settings carry
  * none. An entry that is not a share in [0, 1] with a non-empty salt, or whose ramp is neither null
@@ -150,6 +166,9 @@ export function readSettings(body) {
 		anonymousId: readAnonymousId(hp.anonymousId),
 		apiHost: apiOrigin(hp.apiHost),
 		holdouts: readHoldouts(hp.holdouts),
+		// The share of visitors sent for (3.18). Anything that is not a share sends for everyone.
+		sampleRate: isFraction(hp.sampleRate) ? hp.sampleRate : 1,
+		debug: readDebug(hp.debug),
 		plan:
 			isObject(body.plan) && isObject(body.plan.track)
 				? { track: body.plan.track }

package/src/shape.js

@@ -37,14 +37,23 @@ const NEVER_PRUNE = new Set(['products']);
 /** Restore an exempt key only when it was null; an array stays pruned. */
 const isNullish = (v) => v === null || v === undefined;
 
-function pruneNulls(value) {
-	if (Array.isArray(value)) return value.map(pruneNulls);
+/**
+ * A Date becomes the ISO string JSON would make of it. A cycle is left in place, not followed: the
+ * transport drops an event it cannot serialise, where following it would overflow the stack.
+ */
+function pruneNulls(value, ancestors = new WeakSet()) {
+	if (value instanceof Date) return value.toJSON();
 	if (value === null || typeof value !== 'object') return value;
-	const out = {};
-	for (const [k, v] of Object.entries(value)) {
-		if (isNullish(v)) continue;
-		out[k] = pruneNulls(v);
-	}
+	if (ancestors.has(value)) return value;
+	ancestors.add(value);
+	const out = Array.isArray(value)
+		? value.map((v) => pruneNulls(v, ancestors))
+		: Object.fromEntries(
+				Object.entries(value)
+					.filter(([, v]) => !isNullish(v))
+					.map(([k, v]) => [k, pruneNulls(v, ancestors)]),
+			);
+	ancestors.delete(value);
 	return out;
 }
 

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

package/src/storage-scope.js

@@ -45,7 +45,7 @@ export const DEFAULT_STORAGE_NAMES = Object.freeze({
 	 */
 	anonymousId: 'thg_hp_anonymous_id',
 	/**
-	 * Cookie, one per browser: the session id the SDK keeps when the host names none, expiring 30
+	 * Cookie, one per browser: the session id the SDK keeps when the host has none, expiring 30
 	 * minutes after the last event (3.15). Only under a grant.
 	 */
 	session: 'thg_hp_session',
@@ -54,6 +54,11 @@ export const DEFAULT_STORAGE_NAMES = Object.freeze({
 	 * (`?hp_preview=`), for the site's server to forward to `/v1/assignments` (3.15).
 	 */
 	preview: 'thg_hp_preview',
+	/**
+	 * sessionStorage, for the browser session: the debug token a developer opened the site with
+	 * (`?hp_debug=`), checked against the settings on every page (3.18).
+	 */
+	debug: 'thg_hp_debug',
 });
 
 /**

package/src/transport.js

@@ -111,8 +111,23 @@ export class Transport {
 		}
 	}
 
+	/**
+	 * 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
+	 * every event behind it.
+	 */
 	enqueue(event) {
-		this.queue.push(event);
+		let wire;
+		try {
+			wire = JSON.parse(JSON.stringify(event));
+		} catch (err) {
+			this.o.onError?.(
+				`event ${event?.messageId ?? ''} cannot be serialised; dropped`,
+				err,
+			);
+			return;
+		}
+		this.queue.push(wire);
 		if (this.queue.length > this.o.maxQueue) {
 			// Drop oldest: recent behaviour is more useful than a complete-but-stale tail.
 			this.queue.splice(0, this.queue.length - this.o.maxQueue);

package/src/version.js

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