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

package/src/datalayer.js

@@ -0,0 +1,411 @@
+/**
+ * GA4 dataLayer -> CDP events.
+ *
+ *   const disconnect = connectDataLayer(analytics);
+ *
+ * The core knows the GA4 standard only: `{ event: 'view_item', ecommerce: { items, currency,
+ * value } }` as GTM documents it, parameters at the top level for non-ecommerce events
+ * (`{ event: 'login', method }`), and gtag's `['event', name, params]`. A platform with its own
+ * conventions is taught them by a preset, which the host passes in: `eventName`, `transform` and
+ * `productId` normalise its pushes into that standard, and `map` adds the events GA4 has no name
+ * for.
+ *
+ * Works with this package's client and with an analytics-next instance: the only call it makes is
+ * `analytics.track(event, properties, { context })`, plus `analytics.signedOut()` when a mapping
+ * emits Signed Out and the client has one (so identity is cleared after the event, not before).
+ *
+ * `purchase` and `refund` are never mapped: orders are reported by the service that took them,
+ * which sees every order exactly once. A browser copy would be a second system of record.
+ */
+
+import { currencyCode } from './context.js';
+import { defaultProductId, toProducts } from './ga4.js';
+
+/** Re-exported for presets: the first usable id among the candidates, as a string, or null. */
+export { firstId } from './ga4.js';
+
+const DEDUPE_MS = 1000;
+const DEFAULT_STEPS = { shipping: 2, payment: 3 };
+const SIGN_IN_METHODS = new Set([
+	'password',
+	'google',
+	'apple',
+	'facebook',
+	'magic_link',
+	'sso',
+	'passkey',
+	'other',
+]);
+
+const text = (v) => {
+	if (v == null || typeof v === 'object') return null;
+	const s = String(v).trim();
+	return s === '' ? null : s;
+};
+
+const amount = (v) => {
+	if (v == null || v === '' || typeof v === 'object') return null;
+	const n = Number(v);
+	return Number.isFinite(n) && n >= 0 ? n : null;
+};
+
+const isObject = (v) => v !== null && typeof v === 'object';
+
+/** Null when the push carried no item list at all, which is not the same as an empty one. */
+function readItems(ecommerce) {
+	if (!Array.isArray(ecommerce.items)) return null;
+	return ecommerce.items.filter(isObject);
+}
+
+function signInMethod(value) {
+	const method = text(value)
+		?.toLowerCase()
+		.replace(/[\s-]+/g, '_');
+	if (!method) return null;
+	if (SIGN_IN_METHODS.has(method)) return method;
+	if (method === 'email' || method === 'email_password') return 'password';
+	return 'other';
+}
+
+/** Promotion fields live on ecommerce, or on each item (GA4 allows both). One per promotion id. */
+function promotionsOf({ ecommerce, items }) {
+	const read = (source) => ({
+		promotion_id: text(source.promotion_id),
+		name: text(source.promotion_name),
+		creative: text(source.creative_name),
+		// GA4's creative_slot is Segment's `position`, which spec 1.2 restored.
+		position: text(source.creative_slot),
+	});
+	const seen = new Set();
+	const out = [];
+	for (const promotion of [read(ecommerce), ...items.map(read)]) {
+		// Never invent identity: a name is not an id, and an impression nobody can join is noise.
+		if (!promotion.promotion_id || seen.has(promotion.promotion_id)) continue;
+		seen.add(promotion.promotion_id);
+		out.push(promotion);
+	}
+	return out;
+}
+
+const listId = ({ ecommerce, items }) =>
+	text(ecommerce.item_list_id) ??
+	text(ecommerce.item_list_name) ??
+	text(items[0]?.item_list_id) ??
+	text(items[0]?.item_list_name);
+
+const needProducts = (event, properties) =>
+	properties.products?.length ? { event, properties } : null;
+
+/** GA4 `share` names what was shared by content_type; only a product maps onto Product Shared. */
+const SHARED_PRODUCT_TYPES = new Set(['product', 'products', 'item', 'items']);
+
+/**
+ * GA4's recommended `share` event ({ method, content_type, item_id }) -> Product Shared.
+ *
+ * `item_id` is the shared content's id, not a GA4 item, so it is taken as the product id as it
+ * stands. A share of anything other than a product (an article, a video) is not an ecommerce
+ * event, and GA4 has no basket share, so there is nothing here for Cart Shared.
+ */
+function productShared({ ecommerce }) {
+	const productId = text(ecommerce.item_id);
+	const contentType = text(ecommerce.content_type)?.toLowerCase();
+	if (!productId || (contentType && !SHARED_PRODUCT_TYPES.has(contentType)))
+		return null;
+	return {
+		event: 'Product Shared',
+		properties: {
+			share_via: text(ecommerce.method),
+			products: [{ product_id: productId }],
+		},
+	};
+}
+
+/**
+ * GA4's recommended ecommerce and account events -> spec events. Each builder returns only fields
+ * the target schema allows, or null when the push cannot make a valid event.
+ *
+ * GA4 has no coupon events (`coupon` is a parameter on the commerce events, carried through
+ * above), no wishlist removal or wishlist-to-basket event, and no basket share, so Coupon Entered,
+ * Applied, Denied and Removed, Product Removed from Wishlist, Wishlist Product Added to Cart and
+ * Cart Shared have no default mapping. A preset whose platform pushes them adds one through `map`.
+ */
+function defaultMappings(steps) {
+	const listViewed = (p) =>
+		needProducts('Product List Viewed', {
+			list_id: listId(p),
+			products: p.products,
+		});
+	const searched = (p) => {
+		const query = text(p.ecommerce.search_term);
+		if (!query) return null;
+		return {
+			event: 'Products Searched',
+			properties: {
+				query,
+				...(p.products.length ? { products: p.products } : {}),
+			},
+		};
+	};
+	const promotion = (event) => (p) =>
+		p.promotions.map((fields) => ({ event, properties: fields }));
+
+	return {
+		view_item: (p) =>
+			needProducts('Product Viewed', {
+				currency: p.currency,
+				value: p.value,
+				products: p.products.slice(0, 1),
+			}),
+		view_item_list: listViewed,
+		view_search_results: (p) => searched(p) ?? listViewed(p),
+		search: searched,
+		select_item: (p) =>
+			needProducts('Product Clicked', {
+				list_id: listId(p),
+				products: p.products.slice(0, 1),
+			}),
+		add_to_cart: (p) =>
+			needProducts('Product Added', {
+				cart_id: text(p.ecommerce.cart_id),
+				products: p.products,
+			}),
+		remove_from_cart: (p) =>
+			needProducts('Product Removed', {
+				cart_id: text(p.ecommerce.cart_id),
+				products: p.products,
+			}),
+		view_cart: (p) => ({
+			event: 'Cart Viewed',
+			properties: {
+				cart_id: text(p.ecommerce.cart_id),
+				value: p.value,
+				currency: p.currency,
+				coupon: text(p.ecommerce.coupon),
+				// A view_cart without items says nothing about the basket; [] would claim it was empty.
+				...(p.itemsListed ? { products: p.products } : {}),
+			},
+		}),
+		begin_checkout: (p) =>
+			needProducts('Checkout Started', {
+				value: p.value,
+				currency: p.currency,
+				coupon: text(p.ecommerce.coupon),
+				products: p.products,
+			}),
+		add_shipping_info: (p) => ({
+			event: 'Checkout Step Completed',
+			properties: {
+				step: steps.shipping,
+				step_name: 'shipping',
+				shipping_method: text(p.ecommerce.shipping_tier),
+			},
+		}),
+		add_payment_info: (p) => ({
+			event: 'Payment Info Entered',
+			properties: {
+				step: steps.payment,
+				step_name: 'payment',
+				payment_method: text(p.ecommerce.payment_type),
+			},
+		}),
+		view_promotion: promotion('Promotion Viewed'),
+		select_promotion: promotion('Promotion Clicked'),
+		add_to_wishlist: (p) =>
+			needProducts('Product Added to Wishlist', { products: p.products }),
+		share: productShared,
+		login: (p) => ({
+			event: 'Signed In',
+			properties: { method: signInMethod(p.ecommerce.method) },
+		}),
+		sign_up: (p) => ({
+			event: 'Signed Up',
+			properties: { method: signInMethod(p.ecommerce.method) },
+		}),
+	};
+}
+
+const defaultEventName = (entry) => entry.event;
+
+/**
+ * An entry as { name, entry, ecommerce }: gtag's `['event', name, params]`, or a dataLayer object
+ * whose ecommerce block, when it has none, is its own top level (GTM puts event parameters there).
+ */
+function readEntry(entry, eventName) {
+	if (!isObject(entry)) return null;
+	if (
+		typeof entry.length === 'number' &&
+		entry[0] === 'event' &&
+		typeof entry[1] === 'string'
+	) {
+		const params = isObject(entry[2]) ? entry[2] : {};
+		return { name: entry[1], entry: params, ecommerce: params };
+	}
+	const name = text(eventName(entry));
+	if (!name) return null;
+	return {
+		name,
+		entry,
+		ecommerce: isObject(entry.ecommerce) ? entry.ecommerce : entry,
+	};
+}
+
+/** JSON with object keys sorted, so two equal payloads always serialise identically. */
+function stableJson(value) {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+	if (value && typeof value === 'object') {
+		return `{${Object.keys(value)
+			.sort()
+			.map((k) => `${JSON.stringify(k)}:${stableJson(value[k])}`)
+			.join(',')}}`;
+	}
+	return JSON.stringify(value ?? null);
+}
+
+/**
+ * @param {{ track: Function, signedOut?: Function }} analytics
+ * @param {object} [options]
+ * @param {unknown[]} [options.dataLayer] Defaults to `window.dataLayer`, created if absent.
+ * @param {(entry: object) => string|null|undefined} [options.eventName] The GA4 event name of a
+ *   push. Default `entry.event`.
+ * @param {(entry: unknown) => unknown} [options.transform] Rewrites a push before anything else
+ *   reads it; return null to skip it.
+ * @param {(item: object) => unknown} [options.productId] Parent product id of a GA4 item.
+ *   Default `item.item_group_id ?? item.item_id`.
+ * @param {Record<string, (payload: object, helpers: object) => object | object[] | null>} [options.map]
+ *   Add or override mappings, keyed by GA4 event name. `payload` is the (transformed) entry.
+ * @param {string[]} [options.ignore] GA4 event names to skip.
+ * @param {{ shipping?: number, payment?: number }} [options.steps] Checkout step numbers.
+ * @param {number} [options.dedupeMs] Window in which an identical push is emitted once.
+ * @param {(error: unknown, entry: unknown) => void} [options.onError]
+ * @returns {() => void} disconnect
+ */
+export function connectDataLayer(analytics, options = {}) {
+	if (!analytics || typeof analytics.track !== 'function') {
+		throw new Error(
+			'connectDataLayer: analytics must have a track(event, properties, options) method',
+		);
+	}
+	const dataLayer =
+		options.dataLayer ??
+		(typeof window !== 'undefined'
+			? (window.dataLayer = window.dataLayer || [])
+			: null);
+	if (!Array.isArray(dataLayer)) return () => {};
+
+	const defaults = defaultMappings({ ...DEFAULT_STEPS, ...options.steps });
+	const custom = options.map ?? {};
+	const eventName = options.eventName ?? defaultEventName;
+	const productId = options.productId ?? defaultProductId;
+	const ignore = new Set(['purchase', 'refund', ...(options.ignore ?? [])]);
+	const dedupeMs = options.dedupeMs ?? DEDUPE_MS;
+	const recent = new Map();
+	let connected = true;
+
+	// Duplicate means the same event with the same properties, in the same currency: legacy trackers
+	// push some events twice, and item-less events (two filter changes) must stay distinct.
+	function isDuplicate(event, properties, currency) {
+		if (dedupeMs <= 0) return false;
+		const key = `${event}|${currency ?? ''}|${stableJson(properties)}`;
+		const now = Date.now();
+		for (const [k, at] of recent) if (now - at > dedupeMs) recent.delete(k);
+		if (recent.has(key)) return true;
+		recent.set(key, now);
+		return false;
+	}
+
+	// A product's details are viewed once per page. GA4 storefronts commonly push view_item again
+	// when a size or colour is picked, which is a variant change, not another view. The page is the
+	// path: a variant is often carried in the query string.
+	let viewedPage = null;
+	const viewedProducts = new Set();
+	function isRepeatView(event, properties) {
+		if (event !== 'Product Viewed') return false;
+		const page = typeof location === 'undefined' ? '' : location.pathname;
+		if (page !== viewedPage) {
+			viewedPage = page;
+			viewedProducts.clear();
+		}
+		const productId = properties.products?.[0]?.product_id;
+		if (!productId) return false;
+		if (viewedProducts.has(productId)) return true;
+		viewedProducts.add(productId);
+		return false;
+	}
+
+	// A push's prices are in the push's currency. Events whose schema has `currency` carry it as a
+	// property; every event also gets it as a context override, so the site's current currency can
+	// never be stamped onto a price that was pushed in another.
+	function send({ event, properties = {} }, currency) {
+		if (
+			!event ||
+			isDuplicate(event, properties, currency) ||
+			isRepeatView(event, properties)
+		) {
+			return;
+		}
+		const callOptions = currency ? { context: { currency } } : undefined;
+		if (event === 'Signed Out' && typeof analytics.signedOut === 'function') {
+			analytics.signedOut(callOptions);
+			return;
+		}
+		analytics.track(event, properties, callOptions);
+	}
+
+	function handle(raw) {
+		const entry = options.transform ? options.transform(raw) : raw;
+		const read = readEntry(entry, eventName);
+		if (!read || ignore.has(read.name)) return;
+		const isCustom = Object.hasOwn(custom, read.name);
+		const mapping = isCustom ? custom[read.name] : defaults[read.name];
+		if (typeof mapping !== 'function') return;
+
+		const listed = readItems(read.ecommerce);
+		const items = listed ?? [];
+		const payload = {
+			...read,
+			items,
+			itemsListed: listed !== null,
+			products: toProducts(items, productId),
+			currency: currencyCode(read.ecommerce.currency),
+			value: amount(read.ecommerce.value),
+		};
+		payload.promotions = promotionsOf(payload);
+
+		const result = isCustom
+			? mapping(entry, {
+					...payload,
+					toProducts: (list) => toProducts(list, productId),
+				})
+			: mapping(payload);
+		for (const out of [result].flat()) if (out) send(out, payload.currency);
+	}
+
+	function safely(entry) {
+		if (!connected) return;
+		try {
+			handle(entry);
+		} catch (err) {
+			try {
+				options.onError?.(err, entry);
+			} catch {
+				/* never throw into the page */
+			}
+		}
+	}
+
+	for (const entry of dataLayer.slice()) safely(entry);
+
+	// Wrap, never replace: GTM wraps push too, and whichever of us loads second must call through.
+	const previousPush = dataLayer.push;
+	function push(...entries) {
+		const result = previousPush.apply(this, entries);
+		for (const entry of entries) safely(entry);
+		return result;
+	}
+	dataLayer.push = push;
+
+	return () => {
+		connected = false;
+		if (dataLayer.push === push) dataLayer.push = previousPush;
+	};
+}

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/decisions.js

@@ -0,0 +1,90 @@
+/**
+ * The decisions in force for a visitor: what a decisions response served and the page rendered,
+ * latest per slot. Every later event carries them as `context.decisions`, which is how a basket is
+ * credited to the slot shown before it (decision_rewards bounds that to the decision's session and
+ * attribution tail). They survive a navigation in sessionStorage, which is written only under a grant.
+ */
+
+/**
+ * `context.decisions[].kind`, as spec core/context 1-0-0 closes it. Any other value is dropped
+ * rather than sent: one would quarantine the event carrying it, basket and all.
+ */
+export const DECISION_KINDS = [
+	'recommendation',
+	'search_rank',
+	'banner',
+	'offer',
+	'layout',
+	'copy',
+	'price',
+	'other',
+];
+
+const named = (value) => typeof value === 'string' && value !== '';
+
+/**
+ * What a decisions response served, as `context.decisions[]` entries. Only logged decisions: a
+ * held-out shopper, or a visitor without analytics consent, gets no `decision_id`, and has nothing
+ * a reward could join to.
+ */
+export function servedDecisions(body) {
+	return (Array.isArray(body?.decisions) ? body.decisions : [])
+		.filter((d) => named(d?.slot) && named(d.decision_id) && d.holdout !== true)
+		.map(({ decision_id, slot, arm, kind }) => ({
+			decision_id,
+			slot,
+			...(named(arm) && { arm }),
+			...(DECISION_KINDS.includes(kind) && { kind }),
+		}));
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.key  The sessionStorage key, scoped to the property.
+ * @param {() => boolean} options.mayStore  Whether a device write is allowed now.
+ */
+export function createDecisionMemory({ key, mayStore }) {
+	// Memory is authoritative within a document; storage only carries the decisions across a navigation.
+	let inForce;
+	const load = () => {
+		if (inForce) return inForce;
+		try {
+			const stored = JSON.parse(sessionStorage.getItem(key));
+			inForce = Array.isArray(stored)
+				? stored.filter((d) => named(d?.slot))
+				: [];
+		} catch {
+			inForce = [];
+		}
+		return inForce;
+	};
+	const persist = () => {
+		try {
+			if (inForce?.length && mayStore())
+				sessionStorage.setItem(key, JSON.stringify(inForce));
+		} catch {
+			/* private browsing: the decisions still hold within this document */
+		}
+	};
+
+	return {
+		persist,
+		/** A copy, so a beforeSend that edits one event cannot edit the next. */
+		current: () => (load().length ? inForce.map((d) => ({ ...d })) : null),
+		/** Put these in force, replacing whatever each slot decided before. */
+		remember(served) {
+			if (!served.length) return;
+			const slots = new Set(served.map((d) => d.slot));
+			inForce = [...load().filter((d) => !slots.has(d.slot)), ...served];
+			persist();
+		},
+		forget() {
+			inForce = [];
+			try {
+				sessionStorage.removeItem(key);
+			} catch {
+				/* nothing was stored */
+			}
+		},
+	};
+}