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

package/src/hp.js

@@ -0,0 +1,135 @@
+/**
+ * The page's client, callable from anywhere before it exists: `hp.productAdded({ … })` in any
+ * component, with no reference to pass around and nothing to await.
+ *
+ * Calls made before `bootstrap` has started the client wait here, each with the messageId and time
+ * it was made at, and replay in order once it has; calls after it go straight to the client. When
+ * the client never starts they wait for the page to go: a page that could not reach the API, or that
+ * navigated before it answered, carries them to the next page, whose bootstrap replays them (3.9,
+ * ./carry.js); a page that is off (no key, disabled, invalid config) drops them.
+ * Nothing here ever throws into the caller, and the module is tiny, so a component can use it on a
+ * site that never loads the SDK.
+ */
+
+import { keptVisit } from './recommendation-context.js';
+import { uuid } from './shape.js';
+
+const INSTANCE = Symbol.for('@thg-agentic/hyper-personalisation-web.bootstrap');
+/** How bootstrap hands this queue its client, without the queue being part of the public API. */
+const DRAIN = Symbol.for('@thg-agentic/hyper-personalisation-web.drain');
+/** Where bootstrap leaves the store that carries this queue across a navigation. */
+const CARRY = Symbol.for('@thg-agentic/hyper-personalisation-web.carry');
+const REPLAY = Symbol.for('@thg-agentic/hyper-personalisation-web.replay');
+const ASSIGNMENT = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.assignment',
+);
+const RECOMMENDATION_CONTEXT = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.recommendation-context',
+);
+
+/** Enough for a page's worth of interactions before the SDK loads; later calls are dropped. */
+const MAX_QUEUED = 200;
+
+/** The document all of this belongs to: one per module in a browser, several in a test. */
+let page = null;
+let queue = [];
+/** The bootstrap the queue drains into, and what it resolved to: undefined until then. */
+let bound = null;
+let client;
+
+function invoke(target, [method, args, made]) {
+	try {
+		if (made && target[REPLAY]) target[REPLAY](method, args, made);
+		else if (typeof target[method] === 'function') target[method](...args);
+	} catch (err) {
+		console.warn(`[hp] ${method} failed`, err);
+	}
+}
+
+function bind(pending) {
+	if (pending === bound) return;
+	bound = pending;
+	client = undefined;
+	const drain = (started) => {
+		if (bound !== pending) return;
+		client = started ?? null;
+		if (client) for (const call of queue.splice(0)) invoke(client, call);
+	};
+	Promise.resolve(pending).then(drain, () => drain(null));
+}
+
+/** The page is going before the client started: what it queued goes with it, if it may. */
+function carry(event) {
+	if (queue.length > 0 && event.currentTarget[CARRY]?.save(queue)) queue = [];
+}
+
+function call(method, args) {
+	if (typeof window === 'undefined') return;
+	if (page !== window) {
+		page = window;
+		queue = [];
+		bound = null;
+		client = undefined;
+		window.addEventListener('pagehide', carry);
+	}
+	const pending = window[INSTANCE];
+	if (pending) bind(pending);
+	else {
+		bound = null;
+		client = undefined;
+		// On the window bootstrap will look at when it runs.
+		window[DRAIN] = bind;
+	}
+	if (client) return invoke(client, [method, args]);
+	if (queue.length >= MAX_QUEUED) return;
+	queue.push([
+		method,
+		args,
+		{ messageId: uuid(), timestamp: new Date().toISOString() },
+	]);
+}
+
+/**
+ * The `decision_id` HP logged for assigning `arm` to `slot` in this visitor's session, now: read
+ * from the identity cookies bootstrap was given, so it answers once bootstrap has been called,
+ * started or not. Null before that, and without a session or visitor id.
+ */
+function assignmentDecisionId(assignment) {
+	try {
+		return (
+			(typeof window !== 'undefined' && window[ASSIGNMENT]?.(assignment)) ||
+			null
+		);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * This visit as the recommendations API's session context (`viewed`, `basket`, `q`, `impressed`),
+ * now: from the started client, or, before it has started, as an earlier page of the visit kept it.
+ * `{}` without personalisation consent: a request that appends it then carries no visit.
+ */
+function recommendationContext() {
+	if (typeof window === 'undefined') return {};
+	try {
+		const reader = window[RECOMMENDATION_CONTEXT];
+		const context = reader ? reader() : keptVisit();
+		return context && typeof context === 'object' ? context : {};
+	} catch {
+		return {};
+	}
+}
+
+/** Every client method, callable now. `then` is not one, so `await hp` is not a call. */
+export const hp = new Proxy(
+	{},
+	{
+		get(_, method) {
+			if (typeof method !== 'string' || method === 'then') return undefined;
+			if (method === 'assignmentDecisionId') return assignmentDecisionId;
+			if (method === 'recommendationContext') return recommendationContext;
+			return (...args) => call(method, args);
+		},
+	},
+);