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

package/src/session/record.js

@@ -0,0 +1,163 @@
+import { bump, categoryKey } from './category.js';
+import { readSignals, writeSignals } from './signals.js';
+
+const RECENT_LIMIT = 20;
+/** Larger than RECENT_LIMIT: one listing page is thirty impressions. */
+const IMPRESSION_LIMIT = 200;
+
+/** Product engagement the visitor chose. Anything else carrying products is an impression. */
+const ENGAGEMENT_EVENTS = new Set([
+	'Product Viewed',
+	'Product Clicked',
+	'Product Added',
+	'Product Added to Wishlist',
+]);
+
+/** Engagement the warehouse's category affinity does not count, so a session measure must not. */
+const UNCOUNTED_ENGAGEMENT = new Set([
+	'Product Clicked',
+	'Product Added to Wishlist',
+]);
+
+/**
+ * Fold one CDP event into the session signals.
+ *
+ * Driven by the events the SDK already sends, so a session rule is only ever about something the
+ * warehouse will also see.
+ */
+export function recordSessionEvent(eventName, properties) {
+	const s = readSignals();
+	if (!s.startedAt) s.startedAt = Date.now();
+
+	const products = Array.isArray(properties?.products)
+		? properties.products
+		: [];
+
+	switch (eventName) {
+		case 'Product Viewed':
+			s.productViews += 1;
+			bump(s.recentBrowse, s.browsingCategory);
+			break;
+		case 'Product List Viewed':
+			s.listViews += 1;
+			// Only a category list is browsing. A rail or carousel names its widget (no slash, or a
+			// `cdp-` id), and counting it would let personalisation measure itself.
+			{
+				const list = properties?.list_id;
+				const isCategoryPath =
+					typeof list === 'string' &&
+					list.includes('/') &&
+					!list.startsWith('cdp-');
+				if (isCategoryPath) {
+					s.browsingCategory = bump(s.recentBrowse, list) ?? s.browsingCategory;
+				}
+			}
+			break;
+		case 'Product List Filtered': {
+			// Storefronts whose menus link to facet URLs navigate by filtering.
+			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;
+			}
+			break;
+		}
+		case 'Product Added': {
+			s.cartAdds += 1;
+			bump(s.recentBrowse, s.browsingCategory);
+			for (const p of products) {
+				const id = p.product_id;
+				if (typeof id !== 'string' || !id) continue;
+				s.basketProducts = [
+					id,
+					...s.basketProducts.filter((x) => x !== id),
+				].slice(0, RECENT_LIMIT);
+			}
+			break;
+		}
+		case 'Product Removed': {
+			for (const p of products) {
+				const id = p.product_id;
+				if (typeof id === 'string' && id) {
+					s.basketProducts = s.basketProducts.filter((x) => x !== id);
+				}
+			}
+			break;
+		}
+		case 'Products Searched': {
+			s.searches += 1;
+			const query = properties?.query;
+			if (typeof query === 'string' && query.trim()) {
+				// Normalised as the corpus model normalises query tokens.
+				const q = query.trim().toLowerCase().slice(0, 64);
+				s.recentSearches = [
+					q,
+					...s.recentSearches.filter((x) => x !== q),
+				].slice(0, 5);
+			}
+			break;
+		}
+		case 'Product Clicked':
+		case 'Product Added to Wishlist':
+			break;
+		default:
+			return s;
+	}
+
+	// Being shown a product is not having seen it: impressions are counted, and engagement clears
+	// the count. Folding impressions into `recentProducts` makes a rail demote its own tiles.
+	const isEngagement = ENGAGEMENT_EVENTS.has(eventName);
+	if (!isEngagement) {
+		for (const p of products) {
+			const master = p.product_id;
+			if (typeof master !== 'string' || !master) continue;
+			s.impressions[master] = (s.impressions[master] ?? 0) + 1;
+		}
+		const ids = Object.keys(s.impressions);
+		if (ids.length > IMPRESSION_LIMIT) {
+			const trimmed = {};
+			for (const id of ids
+				.sort((a, b) => s.impressions[b] - s.impressions[a])
+				.slice(0, IMPRESSION_LIMIT)) {
+				trimmed[id] = s.impressions[id];
+			}
+			s.impressions = trimmed;
+		}
+	} else {
+		for (const p of products) {
+			if (typeof p.product_id === 'string' && p.product_id) {
+				delete s.impressions[p.product_id];
+			}
+		}
+	}
+
+	// Once per event, not per product: a listing of thirty items is one statement of interest.
+	const seen = new Set();
+	for (const p of products) {
+		// The master id, as the warehouse aggregates; a variant id changes with the size picked.
+		const master = p.product_id;
+		if (isEngagement && typeof master === 'string' && master) {
+			s.recentProducts = [
+				master,
+				...s.recentProducts.filter((id) => id !== master),
+			].slice(0, RECENT_LIMIT);
+		}
+		if (
+			!UNCOUNTED_ENGAGEMENT.has(eventName) &&
+			typeof p.category === 'string' &&
+			p.category
+		) {
+			const key = categoryKey(p.category);
+			if (key && !seen.has(key)) {
+				seen.add(key);
+				bump(s.recentCategories, key);
+			}
+		}
+	}
+
+	writeSignals(s);
+	return s;
+}

package/src/session/rules.js

@@ -0,0 +1,195 @@
+import { categoryKey } from './category.js';
+import { readSignals } from './signals.js';
+
+/**
+ * Operators under every spelling the audience store holds (`gte` from the builder,
+ * `greater_than_or_equal` from the seeds). An unknown operator fails the rule closed.
+ */
+const OPERATORS = {
+	gte: (a, b) => a >= b,
+	greater_than_or_equal: (a, b) => a >= b,
+	'>=': (a, b) => a >= b,
+	lte: (a, b) => a <= b,
+	less_than_or_equal: (a, b) => a <= b,
+	'<=': (a, b) => a <= b,
+	eq: (a, b) => a === b,
+	equals: (a, b) => a === b,
+	'=': (a, b) => a === b,
+};
+
+/**
+ * Every operator this evaluator can apply, including `between`. A contract test keeps the session
+ * trait catalogue inside this set, since an unsupported operator fails closed silently.
+ */
+export const SESSION_OPERATORS = new Set([
+	...Object.keys(OPERATORS),
+	'between',
+]);
+
+/** Recent interactions with this category or anything beneath it. */
+function interactions(trail, prefix) {
+	const key = categoryKey(prefix);
+	if (!key) return 0;
+	// `damen/mode` must not match `damen/modern`, so a prefix only counts at a separator.
+	return trail.filter((entry) => entry === key || entry.startsWith(`${key}/`))
+		.length;
+}
+
+/**
+ * This category's share of recent attention, as a fraction between 0 and 1: the same unit as the
+ * warehouse's `affinity_share`. A share falls as attention moves, where a count only ever grows.
+ */
+function share(trail, prefix) {
+	if (trail.length === 0) return 0;
+	return interactions(trail, prefix) / trail.length;
+}
+
+const MEASURES = {
+	categoryViews: (s, arg) => interactions(s.recentCategories, arg),
+	categoryShare: (s, arg) => share(s.recentCategories, arg),
+	browseViews: (s, arg) => interactions(s.recentBrowse, arg),
+	browseShare: (s, arg) => share(s.recentBrowse, arg),
+};
+
+/**
+ * What a rule's field is worth right now, or null if this build does not know the field.
+ *
+ * A field is a counter name or `measure.dimension` (`browseShare.damen/schuhe`). Exported so a
+ * storefront can explain a personalisation. Unknown fields fail the rule closed.
+ */
+export function measureField(field, signals) {
+	const separator = field.indexOf('.');
+	if (separator > 0) {
+		const fn = MEASURES[field.slice(0, separator)];
+		const arg = field.slice(separator + 1);
+		return fn && arg ? fn(signals, arg) : null;
+	}
+	const value = signals[field];
+	return typeof value === 'number' ? value : null;
+}
+
+export function evaluateSessionRule(rule, signals) {
+	const actual = measureField(rule.field, signals);
+	if (actual === null) return false;
+	if (rule.operator === 'between') {
+		// A `between` missing either bound fails closed.
+		return (
+			typeof rule.value === 'number' &&
+			typeof rule.value2 === 'number' &&
+			actual >= rule.value &&
+			actual <= rule.value2
+		);
+	}
+	const compare = OPERATORS[rule.operator];
+	if (!compare || typeof rule.value !== 'number') return false;
+	return compare(actual, rule.value);
+}
+
+/**
+ * Whether an audience's session rules hold, combined group-then-join: the same reduction the SQL
+ * compiler performs, so both evaluators reach the same verdict.
+ */
+export function sessionRulesHold(audience, signals) {
+	const rules = audience.rules ?? [];
+	if (rules.length === 0) return false;
+
+	const byGroup = new Map();
+	for (const rule of rules) {
+		const group = rule.group ?? 0;
+		const bucket = byGroup.get(group);
+		if (bucket) bucket.push(rule);
+		else byGroup.set(group, [rule]);
+	}
+
+	const groupOperators = audience.groupOperators ?? [];
+	const groupResults = [];
+	for (const [group, groupRules] of byGroup) {
+		groupResults.push(
+			groupOperators[group] === 'OR'
+				? groupRules.some((r) => evaluateSessionRule(r, signals))
+				: groupRules.every((r) => evaluateSessionRule(r, signals)),
+		);
+	}
+
+	return audience.groupJoin === 'OR'
+		? groupResults.some(Boolean)
+		: groupResults.every(Boolean);
+}
+
+/**
+ * The audiences this visitor is in right now: precomputed membership from the edge, plus any
+ * session audience whose rules hold.
+ *
+ * A MIXED audience also requires its precomputed half (its slug in `qualifiedFor`), so a session
+ * rule can never admit someone the batch half has not qualified.
+ *
+ * `qualifiedFor` also names an untargetable audience the visitor is in that a targetable one
+ * requires: it satisfies `requires`, and like everything untargetable is never returned.
+ */
+export function resolveAudiences(
+	precomputed,
+	sessionAudiences,
+	signals = readSignals(),
+	qualifiedFor = [],
+) {
+	return resolveAudienceMemberships(
+		precomputed,
+		sessionAudiences,
+		signals,
+		qualifiedFor,
+	).map((m) => m.id);
+}
+
+/**
+ * The same resolution, with where each membership came from, for `context.audiences`.
+ *
+ * Computed now because this is the only moment the answer is knowable. `algorithm_version` is null
+ * for a rule: it names a model revision, and a hand-written rule has none.
+ */
+export function resolveAudienceMemberships(
+	precomputed,
+	sessionAudiences,
+	signals = readSignals(),
+	qualifiedFor = [],
+) {
+	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`.
+	const qualified = new Set(qualifiedFor);
+	const sessionSlugs = new Set(sessionAudiences.map((a) => a.slug));
+	// A qualified slug with no session rules of its own is an untargetable precomputed audience the
+	// visitor is in: it meets a `requires`, though nobody may target it.
+	const met = (slug) =>
+		active.has(slug) || (qualified.has(slug) && !sessionSlugs.has(slug));
+	// An untargetable session audience is evaluated for a `requires` and never reported.
+	const untargetable = new Set(
+		sessionAudiences.filter((a) => a.targetable === false).map((a) => a.slug),
+	);
+
+	// Iterated to a fixed point, because one session audience may require another listed after it.
+	let admitted = true;
+	while (admitted) {
+		admitted = false;
+		for (const audience of sessionAudiences) {
+			if (active.has(audience.slug)) continue;
+			const required = audience.requires ?? [];
+			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)) {
+				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');
+				admitted = true;
+			}
+		}
+	}
+
+	return [...active]
+		.filter((id) => !untargetable.has(id))
+		.map((id) => ({
+			id,
+			source: bySlug.get(id) ?? 'warehouse',
+			algorithm_version: null,
+		}));
+}

package/src/session/signals.js

@@ -0,0 +1,146 @@
+import { storageKey, storageName, storagePrefix } from '../storage-scope.js';
+
+/** Read at use, not import, so a renamed `storageNames.sessionSignals` applies. */
+const baseKey = () => storageName('sessionSignals');
+
+/*
+ * A session is browser-wide, as the host's session cookie and the warehouse's session tables are,
+ * so once the host supplies its session id the counters live in localStorage keyed by it. Unset,
+ * they stay in tab-local sessionStorage.
+ */
+let scope = null;
+
+const scopedKey = () => scope ?? baseKey();
+
+function store() {
+	try {
+		return scope ? localStorage : sessionStorage;
+	} catch {
+		// Accessing either throws outright in some embedded webviews.
+		return undefined;
+	}
+}
+
+/**
+ * Bind the counters to a session, and drop this tenant's other sessions.
+ *
+ * `propertyId` scopes the key to a tenant: one origin can serve several tenants, and a tenant-blind
+ * key would carry one brand's browsing into another's visit. A host serving several tenants on one
+ * origin must pass it.
+ */
+export function setSessionScope(sessionId, propertyId) {
+	const tenant = propertyId == null ? null : String(propertyId);
+	const next = sessionId ? storageKey(baseKey(), tenant, sessionId) : null;
+	if (next === scope) return;
+
+	// Events recorded before the first scope (the SDK can boot after the first Product Viewed) are
+	// carried into the scoped key, unless that key already holds a visit in progress.
+	const pending = scope === null ? readUnscoped() : null;
+
+	scope = next;
+	if (!scope) return;
+
+	try {
+		const keep = scopedKey();
+		// Only this tenant's sessions: another tenant on the same origin may have a live visit.
+		const mine = storagePrefix(baseKey(), tenant);
+		for (const key of Object.keys(localStorage)) {
+			if (key.startsWith(mine) && key !== keep) localStorage.removeItem(key);
+		}
+		if (pending && !localStorage.getItem(keep)) {
+			localStorage.setItem(keep, JSON.stringify(pending));
+			// Dropped once adopted, so a later re-scope cannot replay it into a different session.
+			sessionStorage.removeItem(baseKey());
+		}
+	} catch {
+		// Quota, private browsing, or a disabled store: nothing to sweep and nothing to carry.
+	}
+}
+
+/** The tab-local signals recorded before scoping, or null when the visit has done nothing yet. */
+function readUnscoped() {
+	try {
+		const raw = sessionStorage.getItem(baseKey());
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		const busy =
+			parsed &&
+			(parsed.productViews > 0 ||
+				parsed.listViews > 0 ||
+				parsed.recentProducts?.length ||
+				parsed.recentBrowse?.length);
+		return busy ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+/** A fresh object every call: `bump()` mutates the arrays in place, so they must not be shared. */
+function emptySignals() {
+	return {
+		productViews: 0,
+		listViews: 0,
+		cartAdds: 0,
+		searches: 0,
+		recentProducts: [],
+		recentCategories: [],
+		recentBrowse: [],
+		basketProducts: [],
+		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`.
+		impressions: {},
+		browsingCategory: null,
+		startedAt: 0,
+	};
+}
+
+/*
+ * Every event re-reads before it writes, which is how sibling tabs stay in step. Two tabs writing
+ * in the same instant can lose one increment (last write wins); acceptable for threshold rules.
+ */
+export function readSignals() {
+	const s = store();
+	if (!s) return emptySignals();
+	try {
+		const raw = s.getItem(scopedKey());
+		if (!raw) return { ...emptySignals(), startedAt: Date.now() };
+		return { ...emptySignals(), ...JSON.parse(raw) };
+	} catch {
+		return { ...emptySignals(), startedAt: Date.now() };
+	}
+}
+
+export function writeSignals(signals) {
+	const s = store();
+	if (!s) return;
+	try {
+		s.setItem(scopedKey(), JSON.stringify(signals));
+	} catch {
+		// Quota or a disabled store: the session rules simply do not fire.
+	}
+}
+
+export function getSessionSignals() {
+	return readSignals();
+}
+
+/**
+ * Forget this visit's signals: the consent-withdrawal path.
+ *
+ * Clears both stores and every scope, for every tenant on this origin. Unlike the sweep in
+ * `setSessionScope` this is deliberately not tenant-scoped: consent is withdrawn on the device.
+ */
+export function clearSessionSignals() {
+	for (const get of [() => sessionStorage, () => localStorage]) {
+		try {
+			const s = get();
+			s.removeItem(baseKey());
+			for (const key of Object.keys(s)) {
+				if (key.startsWith(`${baseKey()}:`)) s.removeItem(key);
+			}
+		} catch {
+			// Nothing to clear if the store is unavailable.
+		}
+	}
+}

package/src/session-id.js

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ *
+ * 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
+ * a refusal, like the device cookie.
+ */
+
+import { getCookie } from './context.js';
+import { writeCookie } from './device-storage.js';
+import { uuid } from './shape.js';
+
+/** Inactivity that ends a session. */
+export const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+
+/**
+ * @param {object} options
+ * @param {string} options.name  The cookie name, storageName('session').
+ * @param {string|null} [options.domain]
+ * @param {() => boolean} options.mayStore  Strict consent: analytics is granted.
+ * @param {() => number} [options.now]
+ * @param {() => string} [options.mint]
+ */
+export function createSessionId({
+	name,
+	domain = null,
+	mayStore,
+	now = () => Date.now(),
+	mint = uuid,
+}) {
+	let id = null;
+	let lastSeen = 0;
+
+	const persist = () => {
+		if (id !== null && mayStore())
+			writeCookie(name, id, SESSION_TIMEOUT_MS / 1000, domain);
+	};
+
+	return {
+		/** The current session, started afresh after 30 minutes without one; each call is activity. */
+		get() {
+			const at = now();
+			// Read whatever consent says: an earlier page wrote it under a grant this page has yet to hear.
+			const stored = getCookie(name);
+			if (stored) id = stored;
+			else if (id === null || at - lastSeen >= SESSION_TIMEOUT_MS) id = mint();
+			lastSeen = at;
+			persist();
+			return id;
+		},
+		/** Consent was granted: write the session started before it. */
+		persist,
+		/** Consent was refused or withdrawn. */
+		forget() {
+			writeCookie(name, '', 0, domain);
+			id = null;
+		},
+	};
+}

package/src/session.js

@@ -0,0 +1,28 @@
+/**
+ * In-session audience membership, evaluated in the browser.
+ *
+ * The warehouse answers "who is this person"; this answers "what are they doing right now" from
+ * the events the SDK already emits. A MIXED audience is the intersection of the two. Counters
+ * live as long as the visit, and the host decides which visit that is (`setSessionScope`).
+ */
+
+export { recommendationContextFrom } from './recommendation-context.js';
+export {
+	AFFINITY_WINDOW,
+	categoryKey,
+	pathPrefix,
+} from './session/category.js';
+export { recordSessionEvent } from './session/record.js';
+export {
+	evaluateSessionRule,
+	measureField,
+	resolveAudienceMemberships,
+	resolveAudiences,
+	SESSION_OPERATORS,
+	sessionRulesHold,
+} from './session/rules.js';
+export {
+	clearSessionSignals,
+	getSessionSignals,
+	setSessionScope,
+} from './session/signals.js';