@thg-agentic/hyper-personalisation-web 0.0.0-stage → 3.17.1

package/src/transport.js

@@ -0,0 +1,436 @@
+/**
+ * Delivery for the CDP browser SDK.
+ *
+ * Speaks the Segment wire protocol (`POST <apiHost>/v1/batch`).
+ *
+ *  1. Persisted retry: every batch is written to localStorage before its first attempt and
+ *     removed only once the ingest has answered for it.
+ *  2. Unload delivery: on pagehide the queue goes by sendBeacon, which outlives the document.
+ *  3. Bounded: queue size, retry age and payload size are capped, so a broken ingest degrades
+ *     instead of filling the user's disk.
+ */
+
+import { DEFAULT_STORAGE_NAMES } from './storage-scope.js';
+
+const DEFAULTS = {
+	flushAt: 20,
+	flushIntervalMs: 10_000,
+	maxQueue: 500,
+	maxRetryAgeMs: 24 * 60 * 60 * 1000,
+	maxRetries: 5,
+	// What the retry buffer may occupy. localStorage is ~5MB per ORIGIN and shared with the host
+	// page, so an ingest outage must not be able to take all of it; the oldest batch goes first.
+	maxPersistedBatches: 20,
+	maxPersistedBytes: 1024 * 1024,
+	// createAnalytics passes a per-property key built from `storageNames.retry`.
+	storageKey: DEFAULT_STORAGE_NAMES.retry,
+	// sendBeacon hard-fails above ~64KB. Stay clear of the cliff.
+	beaconSafeBytes: 56 * 1024,
+	// The ingest accepts 1MB per request; half that leaves room for a proxy's own limits.
+	maxBatchEvents: 100,
+	maxBatchBytes: 500 * 1024,
+};
+
+const now = () => Date.now();
+
+/**
+ * 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) =>
+	typeof TextEncoder !== 'undefined'
+		? new TextEncoder().encode(s).length
+		: Buffer.byteLength(s);
+const isBrowser = () =>
+	typeof window !== 'undefined' && typeof document !== 'undefined';
+
+/**
+ * localStorage if it can be reached, probed by a read: under strict consent nothing may be written
+ * before the visitor answers. A write that fails later is caught where it happens.
+ */
+function safeStorage() {
+	try {
+		if (!isBrowser() || !window.localStorage) return null;
+		window.localStorage.getItem('thg_hp_probe');
+		return window.localStorage;
+	} catch {
+		return null;
+	}
+}
+
+export class Transport {
+	/**
+	 * @param {object} opts
+	 * @param {string} opts.apiHost   e.g. 'http://localhost:8080' — the /v1/batch base
+	 * @param {string} opts.writeKey
+	 * @param {(msg:string, ...a:any[])=>void} [opts.onError]
+	 * @param {() => boolean} [opts.mayPersist] Whether a batch may be written to storage now. Strict
+	 *   consent passes "analytics is granted"; without it, persistence is always allowed.
+	 * @param {boolean} [opts.deferReplay] Do not replay persisted batches until replayPersisted() is
+	 *   called. Strict consent sets it: a replay is a send, and it must wait for the gate like any other.
+	 */
+	constructor(opts) {
+		this.o = { ...DEFAULTS, ...opts };
+		this.queue = [];
+		this.timer = null;
+		this.storage = safeStorage();
+		this.inflight = null;
+		// Ids of persisted entries this instance is already sending, so a replay never races them.
+		this.sending = new Set();
+		this.replayAllowed = !this.o.deferReplay;
+		this.draining = null;
+
+		if (isBrowser()) {
+			// pagehide is the unload, and the beacon the only send sure to outlive it. A hidden tab may
+			// come back, so it takes the normal path: persisted first, retried, and sent with keepalive.
+			window.addEventListener('pagehide', () => this.flush({ beacon: true }));
+			document.addEventListener('visibilitychange', () => {
+				if (document.visibilityState === 'hidden') this.flush();
+			});
+			this.#drainPersisted();
+		}
+	}
+
+	/** Allow, and start, the replay of persisted batches. Idempotent. */
+	replayPersisted() {
+		this.replayAllowed = true;
+		return this.#drainPersisted();
+	}
+
+	/**
+	 * Forget every persisted batch and stop replaying. For a refusal or a withdrawal: what was kept
+	 * for a later page must not outlive the permission it was kept under.
+	 */
+	clearPersisted() {
+		this.replayAllowed = false;
+		if (!this.storage) return;
+		try {
+			this.storage.removeItem(this.o.storageKey);
+		} catch {
+			/* nothing was readable, so nothing will be replayed either */
+		}
+	}
+
+	enqueue(event) {
+		this.queue.push(event);
+		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);
+		}
+		if (this.queue.length >= this.o.flushAt) {
+			this.flush();
+		} else {
+			this.#schedule();
+		}
+	}
+
+	#schedule() {
+		if (this.timer) return;
+		this.timer = setTimeout(() => this.flush(), this.o.flushIntervalMs);
+		// A pending batch must not keep a server-rendering process alive; a no-op in browsers.
+		this.timer?.unref?.();
+	}
+
+	#clearTimer() {
+		if (this.timer) {
+			clearTimeout(this.timer);
+			this.timer = null;
+		}
+	}
+
+	#body(batch) {
+		return JSON.stringify({
+			batch,
+			writeKey: this.o.writeKey,
+			sentAt: new Date().toISOString(),
+		});
+	}
+
+	#url() {
+		return `${this.o.apiHost.replace(/\/$/, '')}/v1/batch`;
+	}
+
+	/**
+	 * Split events into batches of at most `maxEvents` whose request body stays within `maxBytes`.
+	 * An event that is too big on its own still gets a batch, so it is attempted rather than lost.
+	 */
+	#chunk(events, maxEvents, maxBytes) {
+		const envelope = byteLength(this.#body([]));
+		const chunks = [];
+		let current = [];
+		let bytes = envelope;
+		for (const event of events) {
+			const size = byteLength(JSON.stringify(event)) + 1;
+			if (
+				current.length &&
+				(current.length >= maxEvents || bytes + size > maxBytes)
+			) {
+				chunks.push(current);
+				current = [];
+				bytes = envelope;
+			}
+			current.push(event);
+			bytes += size;
+		}
+		if (current.length) chunks.push(current);
+		return chunks;
+	}
+
+	/**
+	 * @param {{beacon?: boolean}} [opts] beacon=true is the unload path: synchronous
+	 *   handoff to the browser, no retry possible, so it must not be the normal path.
+	 */
+	flush(opts = {}) {
+		this.#clearTimer();
+		if (this.queue.length === 0) return Promise.resolve();
+
+		if (
+			opts.beacon &&
+			isBrowser() &&
+			typeof navigator !== 'undefined' &&
+			navigator.sendBeacon
+		) {
+			this.#flushBeacon();
+			return Promise.resolve();
+		}
+
+		// One request in flight at a time; what accumulates meanwhile stays queued and goes next.
+		if (this.inflight) return this.inflight;
+
+		// Every batch is persisted before the first request leaves, so a page closed or crashed mid-retry
+		// loses nothing.
+		const batches = this.#chunk(
+			this.queue,
+			this.o.maxBatchEvents,
+			this.o.maxBatchBytes,
+		).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);
+			return { batch, id };
+		});
+		this.queue = [];
+		this.inflight = (async () => {
+			for (const { batch, id } of batches) await this.#send(batch, 0, id);
+		})().finally(() => {
+			this.inflight = null;
+			if (this.queue.length >= this.o.flushAt) this.flush();
+			else if (this.queue.length) this.#schedule();
+		});
+		return this.inflight;
+	}
+
+	/**
+	 * Unload: every chunk that fits goes by beacon. A chunk the browser refuses (its keepalive
+	 * quota is shared across the page) is persisted for the next page load AND tried by fetch;
+	 * a fetch that lands removes it again, and a duplicate is deduplicated on messageId downstream.
+	 *
+	 * The fetch builds its own body rather than reusing the beacon's, for the same reason every retry
+	 * does: see #send.
+	 */
+	#flushBeacon() {
+		const events = this.queue;
+		this.queue = [];
+		const url = this.#url();
+		for (const batch of this.#chunk(
+			events,
+			this.o.maxBatchEvents,
+			this.o.beaconSafeBytes,
+		)) {
+			const body = this.#body(batch);
+			if (byteLength(body) <= this.o.beaconSafeBytes) {
+				let ok = false;
+				try {
+					// text/plain keeps this a CORS-safelisted request, avoiding a preflight
+					// that would never complete during unload.
+					ok = navigator.sendBeacon(
+						url,
+						new Blob([body], { type: 'text/plain' }),
+					);
+				} catch {
+					ok = false;
+				}
+				if (ok) continue;
+			}
+			this.#send(batch, 0, this.#persist(batch));
+		}
+	}
+
+	/**
+	 * Deliver one batch, retrying in memory with backoff. `persisted` is its storage id, removed only
+	 * when the ingest has answered for it — 2xx, or a 4xx no retry can fix. Anything else leaves it
+	 * stored for the next page load.
+	 *
+	 * 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) {
+		if (persisted) this.sending.add(persisted);
+		const body = this.#body(batch);
+		try {
+			const res = await fetch(this.#url(), {
+				method: 'POST',
+				headers: { 'Content-Type': 'text/plain' },
+				body,
+				// Over the keepalive byte budget the request is rejected, not downgraded.
+				keepalive: byteLength(body) <= this.o.beaconSafeBytes,
+			});
+
+			if (res.ok) {
+				this.#settle(persisted);
+				// The ingest is answering again: whatever an earlier outage left behind can go now.
+				this.#drainPersisted();
+				return true;
+			}
+			// 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) {
+				this.#settle(persisted);
+				this.o.onError?.(
+					`CDP ingest rejected batch (${res.status}); dropping ${batch.length} events`,
+				);
+				return true;
+			}
+			throw new Error(`retryable ${res.status}`);
+		} catch (err) {
+			if (attempt >= this.o.maxRetries) {
+				if (persisted) this.sending.delete(persisted);
+				const fate = persisted ? 'kept for the next page' : 'dropped';
+				this.o.onError?.(
+					`CDP ingest unreachable after ${attempt} attempts; ${fate}: ${batch.length} events`,
+					err,
+				);
+				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);
+		}
+	}
+
+	#settle(id) {
+		if (!id) return;
+		this.sending.delete(id);
+		this.#unpersist(id);
+	}
+
+	#readPersisted() {
+		const entries = JSON.parse(this.storage.getItem(this.o.storageKey) || '[]');
+		return Array.isArray(entries) ? entries : [];
+	}
+
+	/**
+	 * Store `entries` plus `entry`, newest last, within the count and byte caps: the oldest go first,
+	 * and a write the browser refuses (quota) is retried with fewer. The new entry is always kept if
+	 * anything is — callers check it fits the byte cap on its own.
+	 * @returns {boolean} whether it was written.
+	 */
+	#writePersisted(entries, entry) {
+		const size = (e) => byteLength(JSON.stringify(e)) + 1;
+		let kept = [...entries, entry].slice(-this.o.maxPersistedBatches);
+		let bytes = kept.reduce((sum, e) => sum + size(e), 2);
+		while (kept.length > 1 && bytes > this.o.maxPersistedBytes) {
+			bytes -= size(kept[0]);
+			kept = kept.slice(1);
+		}
+		while (kept.length) {
+			try {
+				this.storage.setItem(this.o.storageKey, JSON.stringify(kept));
+				return true;
+			} catch {
+				kept = kept.slice(1);
+			}
+		}
+		return false;
+	}
+
+	/** @returns {string|null} an id for #unpersist, or null when nothing was stored. */
+	#persist(batch) {
+		if (!this.storage) return null;
+		if (this.o.mayPersist && !this.o.mayPersist()) return null;
+		try {
+			const entry = {
+				at: now(),
+				id: `${now()}-${Math.random().toString(36).slice(2)}`,
+				batch,
+			};
+			// A batch bigger than the whole budget is sent without a second chance rather than being
+			// allowed to evict every other batch on its way to not fitting either.
+			if (byteLength(JSON.stringify(entry)) + 3 > this.o.maxPersistedBytes)
+				return null;
+			return this.#writePersisted(this.#readPersisted(), entry)
+				? entry.id
+				: null;
+		} catch {
+			// Storage unreadable or unwritable: the batch is still sent, it just has no second chance.
+			return null;
+		}
+	}
+
+	#unpersist(id) {
+		if (!id || !this.storage) return;
+		try {
+			const kept = this.#readPersisted().filter((entry) => entry.id !== id);
+			if (kept.length)
+				this.storage.setItem(this.o.storageKey, JSON.stringify(kept));
+			else this.storage.removeItem(this.o.storageKey);
+		} catch {
+			/* a replay of already-delivered events is deduplicated on messageId */
+		}
+	}
+
+	/**
+	 * Re-send what an earlier page (or an earlier outage on this one) left behind, one batch at a
+	 * time. Nothing but stale entries is removed until its send succeeds. Another tab replaying the
+	 * same batch is a duplicate, which stg_events removes on messageId.
+	 */
+	#drainPersisted() {
+		if (!this.storage || !this.replayAllowed)
+			return this.draining ?? Promise.resolve();
+		if (this.draining) return this.draining;
+		let entries;
+		try {
+			const all = this.#readPersisted();
+			entries = all
+				.filter(
+					(entry) =>
+						Array.isArray(entry?.batch) &&
+						now() - entry.at < this.o.maxRetryAgeMs,
+				)
+				// An entry with no id cannot be removed on its own once delivered, so it is given one.
+				.map((entry) =>
+					entry.id
+						? entry
+						: {
+								...entry,
+								id: `${entry.at}-${Math.random().toString(36).slice(2)}`,
+							},
+				);
+			if (
+				entries.length !== all.length ||
+				entries.some((entry, i) => entry !== all[i])
+			) {
+				if (entries.length)
+					this.storage.setItem(this.o.storageKey, JSON.stringify(entries));
+				else this.storage.removeItem(this.o.storageKey);
+			}
+		} catch {
+			return Promise.resolve();
+		}
+		const pending = entries.filter((entry) => !this.sending.has(entry.id));
+		if (!pending.length) return Promise.resolve();
+		this.draining = (async () => {
+			for (const entry of pending) {
+				if (!this.replayAllowed) return;
+				// Re-sent, not re-enqueued, so messageIds are preserved. A batch that exhausts its retries
+				// stops the replay: the ingest is down.
+				if (!(await this.#send(entry.batch, 0, entry.id))) return;
+			}
+		})().finally(() => {
+			this.draining = null;
+		});
+		return this.draining;
+	}
+}

package/src/version.js

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

package/types/auto.d.ts

@@ -0,0 +1,51 @@
+import type { AnalyticsClient } from './index';
+
+export interface ViewabilityOptions {
+	/** Fraction of the element on screen. Default 0.5 (MRC). */
+	visibleRatio?: number;
+	/** Continuous time on screen. Default 1000ms (MRC). */
+	dwellMs?: number;
+	root?: Document | Element;
+}
+
+export interface TrackPromotionsOptions extends ViewabilityOptions {
+	selector?: string;
+	resolve?(el: Element, index: number): Record<string, unknown> | null;
+}
+
+/** A list is `data-hp-list="<id>"`; its tiles carry `data-hp-product`, the spec product as JSON. */
+export interface TrackProductListsOptions extends ViewabilityOptions {
+	selector?: string;
+	tileSelector?: string;
+}
+
+export interface TrackRecommendationRailsOptions extends ViewabilityOptions {
+	selector?: string;
+	tileSelector?: string;
+	resolveRail?(el: Element): Record<string, unknown> | null;
+	resolveTile?(el: Element, index: number): Record<string, unknown> | null;
+}
+
+/** An element is `data-hp-exposure="<surface>"`: recommendations, decisions or audiences (3.15). */
+export interface TrackExposuresOptions extends ViewabilityOptions {
+	selector?: string;
+}
+
+/** Returns a teardown. */
+export declare function trackPromotions(
+	analytics: AnalyticsClient,
+	options?: TrackPromotionsOptions,
+): () => void;
+export declare function trackProductLists(
+	analytics: AnalyticsClient,
+	options?: TrackProductListsOptions,
+): () => void;
+export declare function trackRecommendationRails(
+	analytics: AnalyticsClient,
+	options?: TrackRecommendationRailsOptions,
+): () => void;
+/** `surfaceViewed` for each `data-hp-exposure` element once it is viewable (3.15). */
+export declare function trackExposures(
+	analytics: Pick<AnalyticsClient, 'surfaceViewed'>,
+	options?: TrackExposuresOptions,
+): () => void;

package/types/bootstrap.d.ts

@@ -0,0 +1,154 @@
+import type {
+	TrackExposuresOptions,
+	TrackProductListsOptions,
+	TrackPromotionsOptions,
+	TrackRecommendationRailsOptions,
+} from './auto';
+import type {
+	ConsentAdapter,
+	ConsentState,
+	CookieConsentOptions,
+	DidomiConsentOptions,
+	OneTrustConsentOptions,
+} from './consent';
+import type { DataLayerPreset } from './datalayer';
+import type {
+	AnalyticsClient,
+	AnalyticsOptions,
+	CdpEvent,
+	PageType,
+	StorageNames,
+} from './index';
+
+/** Everything the page itself configures: the rest is the tenant's, and comes from settings. */
+export interface HpConfig {
+	/** The source's publishable key, `hp_pk_{live|test}_…`. Safe in page source. */
+	writeKey: string;
+	/**
+	 * Optional: only for a first-party proxy. Without it the SDK uses the HP API; the key selects the
+	 * tenant, the property and test or live. `api.example.com` or `https://api.example.com`.
+	 */
+	apiHost?: string;
+}
+
+/** Which CMP the page runs. Which purposes it reports comes from the settings. */
+export type ConsentConfig =
+	| ({ provider: 'didomi' } & DidomiConsentOptions)
+	| ({ provider: 'onetrust' } & OneTrustConsentOptions)
+	| ({ provider: 'cookie' } & Partial<Omit<CookieConsentOptions, 'parse'>>)
+	| { provider: 'forwarded'; name?: string }
+	| { provider: 'static'; state: Partial<ConsentState> };
+
+/** `GET {apiHost}/v1/projects/{writeKey}/settings`, the Segment-compatible settings response. */
+export interface SettingsResponse {
+	integrations?: Record<string, unknown>;
+	plan?: { track?: Record<string, { enabled?: boolean }> };
+	hp?: {
+		enabled: boolean;
+		/** Null for a source scoped to several properties: the page passes `propertyId`. */
+		propertyId?: string | null;
+		environment?: 'production' | 'staging' | 'development';
+		/** Strict is the only mode. `purposes`: the ones this property asks for, and so reports. */
+		consent?: {
+			mode: 'strict';
+			purposes?: Partial<Record<keyof ConsentState, boolean>>;
+		};
+		queryParamAllowlist?: string[];
+		/** Host for ingest and for the API. */
+		apiHost?: string;
+		/** Each property's personalisation holdout, keyed by property id. */
+		holdouts?: Record<
+			string,
+			{ share: number; salt: string; readoutSlots?: string[] }
+		>;
+	};
+}
+
+/** A dataLayer preset that may also supply consent adapter factories by provider name. */
+export interface Preset extends DataLayerPreset {
+	consent?: Partial<
+		Record<
+			'didomi' | 'onetrust' | 'cookie' | 'static',
+			(options: Record<string, unknown>) => ConsentAdapter
+		>
+	>;
+}
+
+/** The signed-in visitor, or a lookup of them: bootstrap waits for it alongside the settings. */
+export interface Identity {
+	userId?: string | number | null;
+	emailSha256?: string | null;
+}
+
+export interface AutocaptureOptions {
+	promotions?: boolean | TrackPromotionsOptions;
+	productLists?: boolean | TrackProductListsOptions;
+	recommendations?: boolean | TrackRecommendationRailsOptions;
+	/** `data-hp-exposure="<surface>"`: `surfaceViewed` once the element is viewable (3.15). */
+	exposures?: boolean | TrackExposuresOptions;
+}
+
+export interface BootstrapOptions {
+	/** The page's CMP, as a provider name or an adapter of its own. Required: consent is strict. */
+	consent: ConsentConfig | ConsentAdapter;
+	/**
+	 * The declarative trackers, on by default because they report only what the page tags:
+	 * promotions (`data-hp-promotion`), product lists and clicks (`data-hp-list`, `data-hp-product`)
+	 * and recommendation rails (`data-hp-reco-request`). `false` turns all off; per tracker, `false`
+	 * or its options.
+	 */
+	autocapture?: false | AutocaptureOptions;
+	/**
+	 * Redact or drop an event before it is sent: return it (changed or not), or null to drop it.
+	 * Its type, name, id and time are kept. A hook that throws drops the event.
+	 */
+	beforeSend?(event: CdpEvent): CdpEvent | null;
+	/** Only for a key scoped to several properties, whose settings name none: which one this page is. */
+	propertyId?: string;
+	/** Domain for the consent cookie, e.g. '.example.com' to share it with checkout. */
+	consentCookieDomain?: string;
+	/**
+	 * The site's own first-party identity cookies. `sessionId` is always read from here; without it
+	 * the SDK keeps its own session (3.15, see AnalyticsContextSources.getSessionId).
+	 * `anonymousId` is read only when the source's settings name no device cookie of their own: a
+	 * source set to the site's cookie without a name, or settings from before 3.6. Otherwise the
+	 * settings decide (see AnalyticsOptions.anonymousIdSource). Without any: no anonymousId,
+	 * identity_trust 'none'.
+	 */
+	identityCookies?: { anonymousId?: string; sessionId?: string };
+	/** See AnalyticsOptions.holdAcrossPages. Default false. */
+	holdAcrossPages?: boolean;
+	/** @deprecated Ignored since 3.6: see AnalyticsOptions.mintAnonymousId. */
+	mintAnonymousId?: boolean;
+	/** The signed-in visitor. userId goes on every event; the identify is sent once per session. */
+	identity?: Identity | Promise<Identity | null | undefined>;
+	/** Read per event: a site can trade in several currencies and ship anywhere. */
+	getCurrency?(): string | null | undefined;
+	getShipToCountry?(): string | null | undefined;
+	getLocale?(): string | null | undefined;
+	preset?: Preset;
+	pageType?: PageType;
+	/** Connect a GA4 dataLayer. `name` defaults to 'dataLayer'; `ignore` adds to the preset's. */
+	dataLayer?: { name?: string; ignore?: string[] };
+	/** Rename what the SDK stores. Defaults are `thg_hp_*`. */
+	storageNames?: StorageNames;
+	debug?: boolean;
+	/** Development and tests: use this settings response and never fetch or cache one. */
+	settings?: SettingsResponse;
+	/** createAnalytics options that are functions, e.g. getRecommendations or getExtensions. */
+	extend?: Partial<AnalyticsOptions>;
+}
+
+/**
+ * The client, or null when the key is not enabled, the settings cannot be fetched on a first
+ * visit, or the options are invalid. Never rejects. Idempotent per page.
+ */
+export declare function bootstrap(
+	config: HpConfig,
+	options: BootstrapOptions,
+): Promise<AnalyticsClient | null>;
+/** Every reason the config and options cannot be used; empty when they can. */
+export declare function validateConfig(
+	config: unknown,
+	options?: Partial<BootstrapOptions>,
+): string[];