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

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.12';

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

@@ -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);
@@ -111,8 +129,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);
@@ -267,6 +300,7 @@ export class Transport {
 	async #send(batch, attempt, persisted = null) {
 		if (persisted) this.sending.add(persisted);
 		const body = this.#body(batch);
+		let wait = 0;
 		try {
 			const res = await fetch(this.#url(), {
 				method: 'POST',
@@ -285,6 +319,7 @@ export class Transport {
 			// 4xx (except 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;
+			if (retryable) wait = retryAfterMs(res.headers?.get?.('retry-after'));
 			if (!retryable) {
 				this.#settle(persisted);
 				this.o.onError?.(
@@ -303,8 +338,11 @@ export class Transport {
 				);
 				return false;
 			}
-			const delay =
-				Math.min(1000 * 2 ** attempt, 30_000) * (0.5 + Math.random());
+			// 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),
+			);
 			await new Promise((r) => setTimeout(r, delay));
 			return this.#send(batch, attempt + 1, persisted);
 		}

package/src/version.js

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

package/types/bootstrap.d.ts

@@ -56,6 +56,13 @@ export interface SettingsResponse {
 		queryParamAllowlist?: string[];
 		/** Host for ingest and for the API. */
 		apiHost?: string;
+		/** The share of visitors sent for, decided per anonymous id (since 3.18). Absent: 1. */
+		sampleRate?: number;
+		/**
+		 * Console logging for everyone, or for a session opened with `?hp_debug=<token>` whose SHA-256
+		 * is `tokenSha256` (since 3.18). Absent: off.
+		 */
+		debug?: { enabled: boolean; tokenSha256: string | null };
 		/** Each property's personalisation holdout, keyed by property id. */
 		holdouts?: Record<
 			string,
@@ -132,6 +139,10 @@ export interface BootstrapOptions {
 	dataLayer?: { name?: string; ignore?: string[] };
 	/** Rename what the SDK stores. Defaults are `thg_hp_*`. */
 	storageNames?: StorageNames;
+	/**
+	 * Log every event to the console. Also on when the settings turn it on (`hp.debug`), for everyone
+	 * or for a session opened with `?hp_debug=<token>`, without a release of the page.
+	 */
 	debug?: boolean;
 	/** Development and tests: use this settings response and never fetch or cache one. */
 	settings?: SettingsResponse;

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>;

package/types/events.d.ts

@@ -1,7 +1,39 @@
 // Generated from spec/registry.json by scripts/generate-sdk-models.mjs.
 // DO NOT EDIT. Change the schema and regenerate — the schema is the contract,
 // and a hand-edit here is an SDK that disagrees with the ingest.
-// Spec version: 1.8
+// Spec version: 1.12
+
+/** context.source.environment. Lets non-production traffic be filtered out of the warehouse without a separate writeKey. */
+export type CdpSourceEnvironment = 'production' | 'staging' | 'development';
+export declare const CDP_SOURCE_ENVIRONMENT_VALUES: readonly CdpSourceEnvironment[];
+
+/** context.identity_trust. Whether anonymousId on THIS event identifies a single real visitor. */
+export type CdpIdentityTrust = 'device' | 'shared_render' | 'none';
+export declare const CDP_IDENTITY_TRUST_VALUES: readonly CdpIdentityTrust[];
+
+/** context.page.type. Normalised page taxonomy. */
+export type CdpPageType = 'home' | 'list' | 'product' | 'search' | 'basket' | 'checkout' | 'order_confirmation' | 'login' | 'register' | 'account' | 'info' | 'blog' | 'other';
+export declare const CDP_PAGE_TYPE_VALUES: readonly CdpPageType[];
+
+/** context.device.type. The kind of thing this is. */
+export type CdpDeviceType = 'desktop' | 'mobile' | 'tablet' | 'bot' | 'app';
+export declare const CDP_DEVICE_TYPE_VALUES: readonly CdpDeviceType[];
+
+/** context.device.network. How the device was connected when the event happened, as a native app reports it. */
+export type CdpDeviceNetwork = 'wifi' | 'cellular' | 'wired' | 'offline' | 'other';
+export declare const CDP_DEVICE_NETWORK_VALUES: readonly CdpDeviceNetwork[];
+
+/** context.consent.basis. Who decided whether this event may be collected (spec 1.5). */
+export type CdpConsentBasis = 'visitor' | 'host';
+export declare const CDP_CONSENT_BASIS_VALUES: readonly CdpConsentBasis[];
+
+/** context.decisions[].kind. The KIND of decision this was. */
+export type CdpDecisionKind = 'recommendation' | 'search_rank' | 'banner' | 'offer' | 'layout' | 'copy' | 'price' | 'other';
+export declare const CDP_DECISION_KIND_VALUES: readonly CdpDecisionKind[];
+
+/** context.consent. The purposes a visitor answers for: context.consent and Consent Updated `state`. */
+export type CdpConsentPurpose = 'analytics' | 'marketing' | 'personalisation' | 'ad_user_data' | 'ad_personalization';
+export declare const CDP_CONSENT_PURPOSE_VALUES: readonly CdpConsentPurpose[];
 
 /** The product shape shared by every commerce event. */
 export interface CdpProduct {
@@ -36,6 +68,7 @@ export interface DecisionMade {
 	propensity: number;
 	arm: string;
 	kind?: 'recommendation' | 'search_rank' | 'banner' | 'offer' | 'layout' | 'copy' | 'price' | 'other' | null;
+	learning_reset_at?: string | null;
 	explored?: boolean | null;
 	context_features?: Record<string, unknown> | null;
 	context_key?: string | null;
@@ -137,6 +170,13 @@ export interface ProductsSearched {
 	search_request_id?: string | null;
 }
 
+/** A search box suggested products for a partly typed query, and they were seen. */
+export interface SearchSuggestionsViewed {
+	query: string;
+	products: CdpProduct[];
+	search_request_id?: string | null;
+}
+
 /** A product was added to the basket. */
 export interface ProductAdded {
 	products: CdpProduct[];
@@ -260,6 +300,7 @@ export interface OrderUpdated {
 	taxes_included?: boolean | null;
 	discount?: number | null;
 	coupon?: string | null;
+	payment_method?: string | null;
 	products?: CdpProduct[] | null;
 	reason?: 'line_added' | 'line_removed' | 'quantity_changed' | 'address_changed' | 'delivery_changed' | 'payment_changed' | 'price_adjusted' | 'partial_cancellation' | 'other' | 'status_changed' | null;
 	status?: 'processing' | 'despatched' | 'partially_despatched' | 'delivered' | 'collected' | 'held' | 'payment_problem' | null;
@@ -565,8 +606,32 @@ export interface EmailMarkedAsSpam {
 	email_id?: string | null;
 }
 
+/** The app was launched for the first time after being installed. */
+export interface ApplicationInstalled {
+	version: string;
+	build: string;
+}
+
+/** The app was launched, or came back to the foreground. */
+export interface ApplicationOpened {
+	from_background: boolean;
+	version: string;
+	build: string;
+}
+
+/** The app went to the background. */
+export type ApplicationBackgrounded = Record<string, never>;
+
+/** The app was launched for the first time after an update to a different version or build. */
+export interface ApplicationUpdated {
+	previous_version: string;
+	previous_build: string;
+	version: string;
+	build: string;
+}
+
 /** The spec version these models implement. SDKs stamp it on context.spec.version. */
-export const SPEC_VERSION = '1.8';
+export const SPEC_VERSION = '1.12';
 
 /** Every event name the registry accepts. Anything else is rejected at the ingest. */
 export type CdpEventName =
@@ -580,6 +645,7 @@ export type CdpEventName =
 	| 'Product Clicked'
 	| 'Product List Filtered'
 	| 'Products Searched'
+	| 'Search Suggestions Viewed'
 	| 'Product Added'
 	| 'Product Removed'
 	| 'Cart Viewed'
@@ -620,6 +686,10 @@ export type CdpEventName =
 	| 'Order Returned'
 	| 'Email Bounced'
 	| 'Email Marked as Spam'
+	| 'Application Installed'
+	| 'Application Opened'
+	| 'Application Backgrounded'
+	| 'Application Updated'
 ;
 
 /** Event name -> its properties, so a generic emitter stays type-safe. */
@@ -634,6 +704,7 @@ export interface CdpEventProperties {
 	'Product Clicked': ProductClicked;
 	'Product List Filtered': ProductListFiltered;
 	'Products Searched': ProductsSearched;
+	'Search Suggestions Viewed': SearchSuggestionsViewed;
 	'Product Added': ProductAdded;
 	'Product Removed': ProductRemoved;
 	'Cart Viewed': CartViewed;
@@ -674,6 +745,10 @@ export interface CdpEventProperties {
 	'Order Returned': OrderReturned;
 	'Email Bounced': EmailBounced;
 	'Email Marked as Spam': EmailMarkedAsSpam;
+	'Application Installed': ApplicationInstalled;
+	'Application Opened': ApplicationOpened;
+	'Application Backgrounded': ApplicationBackgrounded;
+	'Application Updated': ApplicationUpdated;
 }
 
 /** Which producers the registry permits for each event. Emitting from another is refused. */

package/types/index.d.ts

@@ -6,6 +6,7 @@ import type {
 	CartViewed,
 	CdpEventName,
 	CdpEventProperties,
+	CdpPageType,
 	CdpProduct,
 	CheckoutFailed,
 	CheckoutStarted,
@@ -36,6 +37,7 @@ import type {
 	PromotionClicked,
 	PromotionViewed,
 	RecommendationsViewed,
+	SearchSuggestionsViewed,
 	SignedIn,
 	SignedUp,
 	SlotEngaged,
@@ -45,20 +47,8 @@ import type {
 export type { ConsentAdapter, ConsentBasis, ConsentState } from './consent';
 export type * from './events';
 
-export type PageType =
-	| 'home'
-	| 'list'
-	| 'product'
-	| 'search'
-	| 'basket'
-	| 'checkout'
-	| 'order_confirmation'
-	| 'login'
-	| 'register'
-	| 'account'
-	| 'info'
-	| 'blog'
-	| 'other';
+/** context.page.type: the spec's page taxonomy, generated. */
+export type PageType = CdpPageType;
 
 export interface PageProperties {
 	/** Stored as context.page.type and inherited by later events on the page. */
@@ -171,6 +161,11 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 
 	/** The property's personalisation holdout, from the settings (`hp.holdouts`). */
 	holdout?: Holdout | null;
+	/**
+	 * The share of visitors to send for, from the settings (`hp.sampleRate`): a visitor whose
+	 * anonymous id falls outside it sends nothing. Default 1. Since 3.18.
+	 */
+	sampleRate?: number;
 
 	/** Keep only these query params (anchored, case-insensitive patterns), plus campaign params. */
 	queryParamAllowlist?: string[];
@@ -184,10 +179,10 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 
 	/**
 	 * Where device ids come from, as the source's settings serve it (`hp.anonymousId`, chosen in the
-	 * console). One place per source, never a fallback between two:
+	 * console):
 	 *
 	 * - `site_cookie`: the site's own first-party cookie, the one named here or, with `cookie: null`,
-	 *   whatever `getAnonymousId` reads. Read only: a visitor without it has no device id.
+	 *   whatever `getAnonymousId` reads. Read only; a visitor without it gets the SDK's own (3.18).
 	 * - `hp_cookie`: Hyper-Personalisation's own first-party cookie (`storageNames.anonymousId`,
 	 *   `thg_hp_anonymous_id`), which the SDK mints and keeps; `getAnonymousId` is ignored.
 	 *
@@ -231,11 +226,11 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 	};
 }
 
-/** The event as queued, or null when the tracking plan disables it. */
+/** The event as queued, or null when the tracking plan disables it or the visitor is outside the sample. */
 type Emit<P> = (properties: P, options?: CallOptions) => CdpEvent | null;
 
 export interface AnalyticsClient {
-	/** Null when the tracking plan disables the event. */
+	/** Null when the tracking plan disables the event or the visitor is outside the sample. */
 	track<E extends CdpEventName>(
 		event: E,
 		properties?: CdpEventProperties[E],
@@ -247,9 +242,13 @@ export interface AnalyticsClient {
 		properties?: Record<string, unknown>,
 		options?: CallOptions,
 	): CdpEvent | null;
-	page(properties?: PageProperties, options?: CallOptions): CdpEvent;
-	identify(traits?: IdentifyTraits, options?: CallOptions): CdpEvent;
-	/** Clear identity and the page chain. */
+	/** Null when the event is not sent: outside the sample, dropped by `beforeSend`, or failed. */
+	page(properties?: PageProperties, options?: CallOptions): CdpEvent | null;
+	identify(traits?: IdentifyTraits, options?: CallOptions): CdpEvent | null;
+	/**
+	 * Sign-out on a shared device: forget the user, the page chain, the SDK's session, the decisions
+	 * in force and the recommendation context. The device id stays.
+	 */
 	reset(): void;
 
 	productViewed: Emit<ProductViewed>;
@@ -288,7 +287,13 @@ export interface AnalyticsClient {
 	personalisationGroup(): PersonalisationGroup;
 	productClicked: Emit<ProductClicked>;
 	productListFiltered: Emit<ProductListFiltered>;
+	/** A submitted search and the results page it produced. */
 	productsSearched: Emit<ProductsSearched>;
+	/**
+	 * The search box's suggested products for a partly typed query, once seen. Never productsSearched,
+	 * which is a submitted search's results page.
+	 */
+	searchSuggestionsViewed: Emit<SearchSuggestionsViewed>;
 	productAdded: Emit<ProductAdded>;
 	productRemoved: Emit<ProductRemoved>;
 	/**
@@ -473,6 +478,8 @@ export interface StorageNames {
 	session?: string;
 	/** Session cookie: the preview token from `?hp_preview=` (3.15). Default 'thg_hp_preview'. */
 	preview?: string;
+	/** sessionStorage: the debug token from `?hp_debug=` (3.18). Default 'thg_hp_debug'. */
+	debug?: string;
 }
 
 /** Where a source's device ids come from: the settings' `hp.anonymousId` (since 3.6). */