@thg-agentic/hyper-personalisation-web 3.32.0 → 3.34.0

package/src/onsite/index.js

@@ -6,7 +6,7 @@
  *   startOnsite(hp); // the client bootstrap resolved to, or pass `onsite: true` to bootstrap
  *
  * The browser judges the trigger; the server decides the rest. Each live form's trigger is watched
- * here, with its pages, devices, dates and caps. When one fires, `POST /v1/decisions` is asked for
+ * here, with its pages, devices, dates, daily cut-off and caps. When one fires, `POST /v1/decisions` is asked for
  * that one slot: a held-out visitor, or no decision, shows nothing. One overlay per page view, the
  * highest priority among those that fire within 50 ms; one that cannot show passes to the next, but
  * a held-out visitor sees none, and once one has shown, closing it lets no other in; with the
@@ -21,6 +21,7 @@ import { loadAnswers } from './answers-loader.js';
 import { createApi } from './api.js';
 import { loadAudiences } from './audiences-loader.js';
 import { createCounters } from './counters.js';
+import { factsFor, pageFacts } from './page-facts.js';
 import { loadProducts } from './products-loader.js';
 import { loadRender } from './render-loader.js';
 import { holdsValue } from './rich-text.js';
@@ -30,9 +31,12 @@ import {
 	byPriority,
 	deviceOf,
 	INTERRUPTS,
+	OUTSIDE_WINDOW,
 	OVERLAY,
+	opensIn,
 	readCreative,
 	readForm,
+	UNSAID,
 } from './rules.js';
 import { watch } from './triggers.js';
 import { loadValues } from './values-loader.js';
@@ -48,6 +52,9 @@ const PENDING = Symbol.for(
 const LISTENERS = Symbol.for(
 	'@thg-agentic/hyper-personalisation-web.onsite.listeners',
 );
+const PAGE_SAID = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-said',
+);
 const SUPPRESSED = Symbol.for(
 	'@thg-agentic/hyper-personalisation-web.onsite.suppressed',
 );
@@ -226,6 +233,11 @@ export function startOnsite(client, options = {}) {
 	};
 	/** Forms whose trigger fired on an empty basket: they try again when the basket changes. */
 	const awaitingBasket = new Set();
+	/**
+	 * Teasers' tabs kept from an earlier page, held back only until the page says what it is about
+	 * (its facts, its product), which it may do after onsite starts: they try again when it does.
+	 */
+	const awaitingPage = new Set();
 	/** Covering forms whose trigger fired before the consent banner was answered. */
 	const awaitingConsent = new Map();
 
@@ -289,6 +301,9 @@ export function startOnsite(client, options = {}) {
 		path: location.pathname,
 		device,
 		campaign: campaign(),
+		// What the page says, and the product it is about: both held in memory, cheap to read.
+		facts: pageFacts(),
+		product: access.pageProduct?.(),
 		now: Date.now(),
 		seen: counters.seen(form.slot),
 		subscribed: counters.subscribed() || options.subscribed?.() === true,
@@ -357,8 +372,30 @@ export function startOnsite(client, options = {}) {
 			asked,
 		});
 		if (reasons.length) {
+			if (kept && reasons.every((r) => UNSAID.includes(r)))
+				awaitingPage.add(form);
+			// A trigger that fired before the form's daily window opened is watched again once it
+			// opens, so the shopper's next exit (or the page's entry) still counts.
+			if (
+				reasons.length === 1 &&
+				reasons[0] === OUTSIDE_WINDOW &&
+				!asked &&
+				!kept &&
+				!stopped
+			) {
+				const inline =
+					form.trigger.type === 'inline' || form.format === 'inline';
+				// In place of any watcher it still has (the site opened it by hand), never beside it.
+				unwatch(form);
+				const later = setTimeout(
+					() => (inline ? show(form, 'inline') : arm(form)),
+					opensIn(form, Date.now()),
+				);
+				stops.set(form.slot, () => clearTimeout(later));
+			}
 			return note(form, 'not eligible', 'not-eligible', reasons);
 		}
+		awaitingPage.delete(form);
 		// The gap first: it holds for the whole session, so it is the reason worth reading.
 		const interrupts = INTERRUPTS(form.format) && !kept;
 		const wait = interrupts && !asked && gapHolds();
@@ -442,11 +479,17 @@ export function startOnsite(client, options = {}) {
 						api.decide(form.slot, counters.pin(form.slot), {
 							visitAudiences: claimed,
 							visitCampaign: form.arrived_from.length ? campaign() : null,
-							// Only for a form whose products are filled from it; never kept or logged by the server.
+							// Only for a form whose products are filled from it, or limited to products (then only
+							// the page's product); never kept or logged by the server.
 							visitContext:
 								form.visit_context === true
 									? (access.visitContext?.() ?? null)
-									: null,
+									: form.products
+										? { product_id: access.pageProduct?.() }
+										: null,
+							pageFacts: form.page_facts.length
+								? factsFor(form.page_facts, pageFacts())
+								: null,
 							timeoutMs: deadline - Date.now(),
 						}),
 						deadline,
@@ -651,7 +694,10 @@ export function startOnsite(client, options = {}) {
 			show(form, 'tab kept from an earlier page', true);
 			continue;
 		}
-		const reasons = blockers(form, env(form));
+		// What the page says, which product it is about, and whether its daily window is open may
+		// all change while the shopper is on it, so a form waits on its trigger for them; they are
+		// judged when it fires.
+		const reasons = blockers(form, { ...env(form), later: true });
 		if (reasons.length) {
 			note(form, 'not eligible', 'not-eligible', reasons);
 			continue;
@@ -692,6 +738,20 @@ export function startOnsite(client, options = {}) {
 				asked ? fire(form, 'manual', asked) : arm(form);
 	});
 
+	const heard = () => {
+		const waiting = [...awaitingPage];
+		awaitingPage.clear();
+		// After any attempt still settling: it judged the page before the page said so.
+		for (const form of waiting)
+			Promise.resolve(opening.get(form.slot)?.done).then(
+				() =>
+					stopped ||
+					mounted.has(form.slot) ||
+					show(form, 'tab kept from an earlier page', true),
+			);
+	};
+	(window[PAGE_SAID] ??= new Set()).add(heard);
+
 	const stopBasket = access.onBasket?.(() => {
 		if (!((access.basketValue?.() ?? 0) > 0)) return;
 		// Out of the set before the decision is asked, so a second update cannot show them twice;
@@ -744,6 +804,8 @@ export function startOnsite(client, options = {}) {
 			stopConsent?.();
 			awaitingBasket.clear();
 			awaitingConsent.clear();
+			awaitingPage.clear();
+			window[PAGE_SAID]?.delete(heard);
 			if (window[CONTROLLER] === controller) delete window[CONTROLLER];
 		},
 	});

package/src/onsite/page-facts.js

@@ -0,0 +1,61 @@
+/**
+ * Page facts (#1164): what the page says about itself, given with `hp.onsite.facts({ … })`, such as
+ * whether the product on it can be delivered tomorrow. Kept in the page's memory for the path it was
+ * given on, so a single-page app's next page starts with none; an anchor or a variant's query on the
+ * same path keeps them. A form's
+ * `page_facts` rules are judged here and again by the public API, which reads the facts the request carries (only those the rules
+ * read) and drops any that are not a fact: both run spec/onsite/examples/page-facts.cases.json.
+ */
+
+/** Where `hp.onsite.facts` (../onsite-facade.js) keeps them: the page's, not this chunk's. */
+const PAGE_FACTS = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-facts',
+);
+
+/** The facts this page gave, on the path it is on now; `{}` when none. */
+export function pageFacts(win = globalThis.window) {
+	const held = win?.[PAGE_FACTS];
+	return held?.path === win?.location?.pathname ? held.facts : {};
+}
+
+/** A fact as the public API reads it: words up to 100 characters. */
+const read = (v) => (typeof v === 'string' ? v.slice(0, 100) : v);
+
+const norm = (v) => (typeof v === 'string' ? v.trim().toLowerCase() : v);
+
+/**
+ * Whether `facts` meets every rule. A fact the page did not give, or gave as another kind, meets no
+ * rule on it, `is_not` included; a rule this SDK cannot read meets none. No rules is any page. The
+ * control plane's `pageFactsHold` is the same.
+ *
+ * @param {Array<{ fact: string, op: string, values: unknown[] }>} rules
+ * @param {Record<string, unknown> | null} facts
+ */
+export const pageFactsHold = (rules, facts) =>
+	rules.every((rule) => {
+		// As the public API reads them, and only finite numbers.
+		const have = read(facts?.[rule.fact]);
+		const values = Array.isArray(rule.values) ? rule.values : [];
+		if (
+			have == null ||
+			typeof have !== typeof values[0] ||
+			(typeof have === 'number' && !Number.isFinite(have))
+		)
+			return false;
+		const any = values.some((want) => norm(want) === norm(have));
+		return rule.op === 'is'
+			? any
+			: rule.op === 'is_not'
+				? !any
+				: rule.op === 'at_least'
+					? have >= values[0]
+					: rule.op === 'at_most' && have <= values[0];
+	});
+
+/** Only the facts `rules` read, for the decision request: nothing else the page gave leaves it. */
+export const factsFor = (rules, facts) =>
+	Object.fromEntries(
+		rules
+			.filter((r) => r.fact in facts)
+			.map((r) => [r.fact, read(facts[r.fact])]),
+	);

package/src/onsite/preview.js

@@ -38,10 +38,12 @@ const SAMPLE_BASKET = 32;
  * @param {unknown} creative The arm's payload.
  * @param {{ step?: string, device?: 'desktop'|'mobile', consentText?: string, smsConsentText?: string, locale?: string,
  *   questions?: Array<{ key: string, type?: 'one'|'many'|'date'|'number', label?: string, options?: Array<{ value: string, label?: string }>, format?: object }>,
- *   prizes?: Array<{ key: string, label: string }>, basketValue?: number,
+ *   prizes?: Array<{ key: string, label: string }>, basketValue?: number, daily?: object,
  *   values?: { first_name?: string, basket_value?: number, basket_items?: number, currency?: string, answers?: Record<string, string[]> } | null }} [options]
  *   `values`: a returning shopper's, for the text's shopper values; without them every value shows
- *   its fallback, as for a new visitor, but for an answer given in the form itself.
+ *   its fallback, as for a new visitor, but for an answer given in the form itself. `daily`: the
+ *   form's daily cut-off as the settings carry it (`window.daily`, its moments), which a `daily`
+ *   countdown counts to.
  * @returns {{ update(creative: unknown, options?: object): void, destroy(): void, step(): string|null }}
  */
 export function mountPreview(host, creative, options = {}) {
@@ -64,6 +66,7 @@ export function mountPreview(host, creative, options = {}) {
 			sms_consent_text: { text: opts.smsConsentText ?? SAMPLE_SMS_CONSENT },
 			questions: Array.isArray(opts.questions) ? opts.questions : [],
 			prizes: Array.isArray(opts.prizes) ? opts.prizes : [],
+			window: opts.daily ? { daily: opts.daily } : {},
 		};
 		const values = opts.values ?? null;
 		mounted = mountForm({

package/src/onsite/render.js

@@ -761,7 +761,8 @@ export function mountForm(o) {
 
 	/**
 	 * A countdown's place: the answers chunk draws its label and timer into it and ticks it
-	 * (./countdown.js), showing it, and hides it again once a deadline passes. Hidden until then, so
+	 * (./countdown.js), a daily one to the form's next cut-off, showing it, and hides it again once a
+	 * deadline passes. Hidden until then, so
 	 * a chunk that never comes leaves nothing behind, not an empty timer.
 	 */
 	function countdown(block) {
@@ -773,7 +774,9 @@ export function mountForm(o) {
 			(m) =>
 				m &&
 				box.isConnected &&
-				state.timers.push(m.countdown(box, block, preview, el)),
+				state.timers.push(
+					m.countdown(box, block, preview, el, form.window.daily?.next),
+				),
 		);
 		return box;
 	}

package/src/onsite/rules.js

@@ -4,6 +4,10 @@
  */
 
 import { arrivedFrom } from '../visit-campaign.js';
+import { pageFactsHold } from './page-facts.js';
+
+/** What holds a form back until the page says what it is about: its facts, or its product. */
+export const UNSAID = ['the page does not say so', 'not a product page'];
 
 export const FORMATS = [
 	'popup',
@@ -41,10 +45,12 @@ const strings = (v) =>
 	Array.isArray(v) ? v.filter((s) => typeof s === 'string') : [];
 const count = (v) => (Number.isInteger(v) && v >= 0 ? v : null);
 
-/** A rule no visit meets: what an `arrived_from` this SDK cannot read becomes, so it fails closed. */
-const NEVER = { field: null, match: null, values: [] };
-const arrivedRules = (raw) =>
-	raw == null ? [] : Array.isArray(raw) && raw.every(isObject) ? raw : [NEVER];
+/**
+ * Rules as the runtime reads them: none when absent, and ones this SDK cannot read become `never`, a
+ * rule no visit or page meets, so the form fails closed.
+ */
+const rulesOr = (raw, never) =>
+	raw == null ? [] : Array.isArray(raw) && raw.every(isObject) ? raw : [never];
 
 /** A form from the settings as the runtime uses it, or null when it cannot be used. */
 export function readForm(raw) {
@@ -62,7 +68,13 @@ export function readForm(raw) {
 		devices: strings(raw.devices),
 		aliases: strings(raw.aliases),
 		audiences: strings(raw.audiences),
-		arrived_from: arrivedRules(raw.arrived_from),
+		arrived_from: rulesOr(raw.arrived_from, {
+			field: null,
+			match: null,
+			values: [],
+		}),
+		page_facts: rulesOr(raw.page_facts, { fact: null, op: null, values: [] }),
+		products: raw.products === true,
 		caps: {
 			per_session: count(caps.per_session),
 			lifetime: count(caps.lifetime),
@@ -136,10 +148,20 @@ const at = (iso) => (typeof iso === 'string' ? Date.parse(iso) : Number.NaN);
  */
 export const ASKED = (form) => form.trigger.type === 'manual';
 
+/** A form held back only until its daily window opens; `opensIn` says how long that is. */
+export const OUTSIDE_WINDOW = 'outside its daily window';
+export const opensIn = (form, now) => {
+	const { daily } = form.window;
+	return daily.next.find((t) => t > now) - daily.within_hours * 36e5 - now;
+};
+
 /**
- * Every reason `form` may not show now, empty when it may. `env` is the page:
- * `{ path, device, campaign, now, seen, subscribed, personalisation, preview, audiences }`, where
- * `campaign` is the visit's (`visitCampaign`), `seen` the slot's counters and `audiences` the
+ * Every reason `form` may not show now, empty when it may: its pages, devices, campaign, page
+ * facts and products, dates and daily cut-off, audiences and counters. `env` is the page:
+ * `{ path, device, campaign, facts, product, now, seen, subscribed, personalisation, preview,
+ * audiences }`, where `campaign` is the visit's (`visitCampaign`), `facts` what the page said
+ * about itself (`hp.onsite.facts`), `product` the id of the product the page is about (its last
+ * Product Viewed), `seen` the slot's counters and `audiences` the
  * session audiences the host gave, or null. The campaign is context about this visit, as the page
  * is, so it needs no personalisation consent. A form limited to audiences needs personalisation
  * consent; whether the visitor is in one is the server's to decide (`POST /v1/decisions`), unless
@@ -152,9 +174,26 @@ export function blockers(form, env) {
 		reasons.push(`not on ${env.device}`);
 	if (!arrivedFrom(form.arrived_from, env.campaign))
 		reasons.push('not from its campaign');
+	// A preview shows the version asked for on any page, as the server answers it.
+	if (!env.later && !env.preview) {
+		if (!pageFactsHold(form.page_facts, env.facts)) reasons.push(UNSAID[0]);
+		// Which products: the server's to decide; a page about none can never be one of them.
+		if (form.products && !env.product) reasons.push(UNSAID[1]);
+	}
 	const starts = at(form.window.starts_at);
 	const ends = at(form.window.ends_at);
 	if (env.now < starts || env.now >= ends) reasons.push('outside its dates');
+	// Its daily cut-off is targeting too: checked before any decision, so a held-out visitor is
+	// filtered as a shown one is. Its window is judged when the trigger fires (`later` at start), as
+	// it may open while the shopper is on the page; with no cut-off ahead it never can. The server
+	// lists the moments; a trader previewing sees it at any hour.
+	const { daily } = form.window;
+	if (daily && !env.preview) {
+		const left = daily.next?.find?.((t) => t > env.now) - env.now;
+		if (!(left > 0)) reasons.push('no cut-off ahead');
+		else if (!env.later && left > daily.within_hours * 36e5)
+			reasons.push(OUTSIDE_WINDOW);
+	}
 	// A trader previewing a limited form sees it, as the server answers a preview.
 	if (form.audiences.length && !env.preview) {
 		if (!env.personalisation)

package/src/onsite-facade.js

@@ -19,11 +19,27 @@ const SUPPRESSED = Symbol.for(
 const PAGE_VALUES = Symbol.for(
 	'@thg-agentic/hyper-personalisation-web.onsite.page-values',
 );
+const PAGE_FACTS = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-facts',
+);
+/** The runtime's listeners for what the page says: its facts, or the product it is about. */
+const PAGE_SAID = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-said',
+);
 const EVENTS = ['shown', 'submitted', 'apply', 'closed', 'held', 'nothing'];
 const MAX_PENDING = 10;
 
 const page = () => (typeof window === 'undefined' ? null : window);
 
+/** The page said what it is about (facts, or a Product Viewed): the runtime judges again what waited. */
+export function pageSaid() {
+	try {
+		for (const heard of page()?.[PAGE_SAID] ?? []) heard();
+	} catch {
+		/* never into the page */
+	}
+}
+
 /** No onsite runtime will start on this page: every `open` waiting for one resolves `false`. */
 export function dropPendingOpens() {
 	try {
@@ -111,6 +127,27 @@ export const onsite = Object.freeze({
 			/* never into the page */
 		}
 	},
+	/**
+	 * What this page says about itself, for forms limited by page facts:
+	 * `{ next_day_eligible: true }`, each value true or false, a number or words. Kept in memory for
+	 * this page's path only (a single-page app's next page starts with none); a form's request sends
+	 * only the facts its rules read, never logged.
+	 * Each call replaces the last (call it again when the shopper picks another size), and
+	 * `facts({})` forgets.
+	 */
+	facts(given) {
+		try {
+			const w = page();
+			if (w)
+				w[PAGE_FACTS] = {
+					path: w.location?.pathname,
+					facts: given && typeof given === 'object' ? { ...given } : {},
+				};
+		} catch {
+			/* never into the page */
+		}
+		pageSaid();
+	},
 	/**
 	 * Each form's state, as `debug`, once the page knows whether onsite forms run on it: when the
 	 * runtime has started, or `[]` once none will (not opted in, no live form, the chunk failed).

package/src/version.js

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

package/types/onsite-preview.d.ts

@@ -34,6 +34,8 @@ export interface PreviewOptions {
 	prizes?: Array<{ key: string; label: string }>;
 	/** The basket a progress block is drawn against; 32 when left out. */
 	basketValue?: number;
+	/** The form's daily cut-off as the settings carry it (`window.daily`), which a `daily` countdown counts to. */
+	daily?: DailyCutoff;
 	/**
 	 * A returning shopper's values for the text's shopper values (`answers` by question, as option
 	 * values); null or left out, every value shows its fallback, as a new visitor sees it.
@@ -83,3 +85,14 @@ export declare function formatValue(
 		now?: number;
 	},
 ): string | null;
+
+/**
+ * A form's daily cut-off as the settings carry it (`window.daily`): the moments it falls, which the
+ * server works out in the shop's time zone, and a `daily` countdown counts to the first ahead.
+ */
+export interface DailyCutoff {
+	/** The cut-offs, epoch milliseconds, earliest first, up to 8 days on from when they were listed. */
+	next: readonly number[];
+	/** The form shows only while the next cut-off is at most this many hours away. */
+	within_hours?: number;
+}

package/types/onsite.d.ts

@@ -31,6 +31,16 @@ export interface OnsiteValueNode {
 	};
 }
 
+/** What a page says about itself, for forms limited by page facts (3.34). */
+export type OnsitePageFacts = Record<string, boolean | number | string>;
+
+/** One rule on a page fact: `is` / `is_not` one of `values`, or `at_least` / `at_most` a number. */
+export interface OnsitePageFactRule {
+	fact: string;
+	op: 'is' | 'is_not' | 'at_least' | 'at_most';
+	values: Array<boolean | number | string>;
+}
+
 /** What the page knows of the shopper for a form's text. Never sent, stored or logged. */
 export interface OnsitePageValues {
 	first_name?: string;
@@ -85,11 +95,26 @@ export interface OnsiteForm {
 		match: 'is' | 'contains';
 		values: string[];
 	}>;
+	/**
+	 * Shown only where the page says so (3.34): rules on the facts it gave with `hp.onsite.facts`.
+	 * Every rule must hold; a fact the page did not give meets none.
+	 */
+	page_facts?: OnsitePageFactRule[];
+	/** Shown only on the pages of chosen products (3.34): the server checks the page's product. */
+	products?: true;
 	/** Shown only with personalisation consent, and only to members as the server decides. */
 	audiences?: string[];
 	exclude_subscribed?: boolean;
 	caps?: { per_session?: number; lifetime?: number; after_close_days?: number };
-	window?: { starts_at?: string; ends_at?: string };
+	/**
+	 * Its dates and its daily cut-off: with one, it shows only while one of its listed cut-offs is
+	 * still ahead and, with `within_hours`, only that close to it (3.33).
+	 */
+	window?: {
+		starts_at?: string;
+		ends_at?: string;
+		daily?: import('./onsite-preview').DailyCutoff;
+	};
 	/**
 	 * The form's language, BCP 47 (`en-IE`): its phone field starts on this region's country code,
 	 * and a birthday's day and month follow its order and month names. Absent: the page's `lang`.
@@ -328,6 +353,14 @@ export interface OnsiteFacade {
 	 * memory only, never sent, stored or logged. Each call replaces the last; `values({})` forgets.
 	 */
 	values(given: OnsitePageValues): void;
+	/**
+	 * What this page says about itself (3.34), such as `{ next_day_eligible: true }`: kept in memory
+	 * for this page's path only; a form's decision request sends only the facts its rules read,
+	 * never logged. Each call replaces the last; call it again when the shopper picks another size.
+	 * `facts({})` forgets. Names are lower case, digits and underscores; values true or false, a
+	 * number or words; at most 20.
+	 */
+	facts(given: OnsitePageFacts): void;
 	/** Each form's state once the page knows whether onsite forms run on it; `[]` when none will. */
 	ready(): Promise<OnsiteTrace[]>;
 	debug(): OnsiteTrace[];