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

package/src/conformance.js

@@ -0,0 +1,530 @@
+/**
+ * Live conformance checking: does this integration work, on this page, right now.
+ *
+ * Checks what a validator cannot:
+ *   1. What a page of this type should have emitted and did not (`page_expectations` in the
+ *      registry): absence is the commoner and costlier failure. An event `required_on_entry` is
+ *      owed only by the first page of a run of pages of one type — checkout owes Checkout Started
+ *      when the shopper enters it, and Checkout Step Viewed on every step.
+ *   2. Whether the events that did fire would survive the ingest: required fields, producers,
+ *      types, enums, and unknown properties (every event schema is `additionalProperties: false`),
+ *      inside `products[]` as well, against the product version the event holds.
+ *   3. What the ingest accepts and the warehouse then cannot use: priced products with no
+ *      currency, and categories that are not `/` paths.
+ *
+ * Off by default, and observe-only: it cannot alter, delay or drop an event.
+ *
+ *   import { createConformanceChecker } from '@thg-agentic/hyper-personalisation-web/conformance';
+ *   import rules from '@thg-agentic/hyper-personalisation-spec/generated/sdk/conformance-rules.json';
+ *
+ *   const checker = createConformanceChecker({ rules, producer: 'web' });
+ *   createAnalytics({ ...config, onEvent: checker.observe });
+ */
+
+/** How long after the last event a page is considered to have settled. */
+const SETTLE_MS = 2500;
+
+const SEVERITY = { error: 3, warning: 2, info: 1 };
+
+/**
+ * The previous page's type, so a full page load can tell entering a run of pages from continuing
+ * one. Per tab and per origin, which is the right scope: a checkout on its own origin starts with
+ * nothing stored, and its first page is the entry.
+ */
+const PAGE_TYPE_KEY = 'thg_hp_conformance_page_type';
+
+function defaultStorage() {
+	try {
+		return globalThis.sessionStorage ?? null;
+	} catch {
+		// Storage access throws where the browser blocks it; the checker then sees one page load.
+		return null;
+	}
+}
+
+function readStored(storage) {
+	try {
+		return storage?.getItem(PAGE_TYPE_KEY) ?? null;
+	} catch {
+		return null;
+	}
+}
+
+function store(storage, pageType) {
+	try {
+		storage?.setItem(PAGE_TYPE_KEY, pageType);
+	} catch {
+		/* a full or blocked store only costs the entry check its memory */
+	}
+}
+
+const typeOf = (value) => {
+	if (value === null) return 'null';
+	if (Array.isArray(value)) return 'array';
+	if (Number.isInteger(value)) return 'integer';
+	return typeof value;
+};
+
+/** Does a value satisfy a rule's declared primitive type? */
+function typeMatches(expected, value) {
+	const actual = typeOf(value);
+	if (actual === expected) return true;
+	// An integer is an acceptable number; the reverse is not.
+	if (expected === 'number' && actual === 'integer') return true;
+	if (expected === 'object' && actual === 'object') return true;
+	return false;
+}
+
+/**
+ * @param {object} options
+ * @param {object} options.rules generated/sdk/conformance-rules.json
+ * @param {string} [options.producer] Which producer this integration claims to be.
+ * @param {(problem: object) => void} [options.onProblem] Called as problems are found.
+ * @param {boolean} [options.log] Print a grouped summary to the console when the page settles.
+ * @param {number} [options.settleMs]
+ * @param {Storage | null} [options.storage] Where the previous page's type is kept across full page
+ *   loads. sessionStorage by default.
+ */
+export function createConformanceChecker(options) {
+	const {
+		rules,
+		producer = 'web',
+		onProblem,
+		log = true,
+		settleMs = SETTLE_MS,
+		storage = defaultStorage(),
+	} = options ?? {};
+
+	if (!rules?.events) {
+		throw new Error(
+			'createConformanceChecker: rules must be the generated conformance-rules.json',
+		);
+	}
+
+	const problems = [];
+	const seen = new Map();
+	let pageType = null;
+	/** The page type before this one: this page load's, or the last load's in this tab. */
+	let previousPageType = readStored(storage);
+	/** Whether the current page began a run of pages of its type. */
+	let entered = false;
+	let settleTimer = null;
+	let settled = false;
+	/** Events named as missing when the summary was printed, so their arrival can be retracted. */
+	let outstanding = new Set();
+
+	const add = (severity, kind, message, detail) => {
+		const problem = { severity, kind, message, ...detail };
+		problems.push(problem);
+		try {
+			onProblem?.(problem);
+		} catch {
+			/* an observer's failure is not the integration's problem */
+		}
+	};
+
+	/** The envelope, whose failures break every event rather than one. */
+	function checkEnvelope(event) {
+		for (const key of rules.envelope_required ?? []) {
+			// `properties` is required per-event, not on identify/page, so it is checked with the
+			// event rather than here.
+			if (key === 'properties') continue;
+			if (event[key] === undefined || event[key] === null) {
+				add(
+					'error',
+					'envelope_missing',
+					`Envelope is missing "${key}" — this quarantines EVERY event, not just this one.`,
+					{
+						event: event.event ?? event.type,
+					},
+				);
+			}
+		}
+		for (const key of rules.context_required ?? []) {
+			if (event.context?.[key] === undefined || event.context?.[key] === null) {
+				add(
+					'error',
+					'context_missing',
+					`context.${key} is missing — this quarantines EVERY event, not just this one.`,
+					{
+						event: event.event ?? event.type,
+					},
+				);
+			}
+		}
+		if (!event.anonymousId && !event.userId) {
+			add(
+				'error',
+				'no_identity',
+				'Event carries neither anonymousId nor userId, so it cannot be attributed to anybody.',
+				{
+					event: event.event ?? event.type,
+				},
+			);
+		}
+		if (event.context?.consent && event.context.consent.analytics === null) {
+			// Not an error: a slow CMP produces this and it resolves itself. Surfaced because a CMP that
+			// never answers looks identical.
+			add(
+				'info',
+				'consent_unknown',
+				'Consent was still unknown when this event was collected. Fine if the CMP later answers; total data loss under strict consent if it never does.',
+				{
+					event: event.event ?? event.type,
+				},
+			);
+		}
+	}
+
+	function checkTrack(event) {
+		const name = event.event;
+		const rule = rules.events[name];
+
+		if (!rule) {
+			add(
+				'error',
+				'unregistered_event',
+				`"${name}" is not in the registry, so the ingest will reject it. Add it to the spec, or send it as "<namespace>.<Name>" under a registered extension namespace.`,
+				{ event: name },
+			);
+			return;
+		}
+
+		if (!rule.producers.includes(producer)) {
+			add(
+				'error',
+				'producer_not_permitted',
+				`A "${producer}" producer may not emit "${name}" — the registry permits ${rule.producers.join(', ')}. This is usually a sign the event belongs in another codebase.`,
+				{ event: name },
+			);
+		}
+
+		const properties = event.properties ?? {};
+
+		for (const key of rule.required) {
+			const value = properties[key];
+			// An empty array is missing only where the schema demands items: an emptied basket
+			// (Cart Updated) and a listing with no results (Product List Viewed) are real, empty facts.
+			const minItems = rule.properties[key]?.minItems ?? 0;
+			if (
+				value === undefined ||
+				value === null ||
+				(Array.isArray(value) && value.length < minItems)
+			) {
+				add(
+					'error',
+					'missing_required',
+					`"${name}" is missing required property "${key}".`,
+					{ event: name, property: key },
+				);
+			}
+		}
+
+		for (const [key, value] of Object.entries(properties)) {
+			const spec = rule.properties[key];
+			if (!spec) {
+				add(
+					'error',
+					'unknown_property',
+					`"${name}" carries "${key}", which is not in its schema. Every event sets additionalProperties:false, so this is a rejection rather than an extra field.`,
+					{ event: name, property: key },
+				);
+				continue;
+			}
+			if (value === null || value === undefined) continue;
+			if (!typeMatches(spec.type, value)) {
+				add(
+					'error',
+					'wrong_type',
+					`"${name}.${key}" should be ${spec.type} but is ${typeOf(value)}.`,
+					{ event: name, property: key },
+				);
+			}
+			if (spec.enum && !spec.enum.includes(value)) {
+				const allowed = spec.enum.filter((v) => v !== null).join(', ');
+				add(
+					'error',
+					'bad_enum',
+					`"${name}.${key}" is "${value}", which is not one of: ${allowed}.`,
+					{ event: name, property: key },
+				);
+			}
+		}
+
+		checkProducts(name, rule, event, properties);
+	}
+
+	/**
+	 * Inside `products[]`, which the checks above see as one array. A malformed item rejects the
+	 * whole event. A price with no currency, or a category that is not a `/` path, is accepted and
+	 * then quietly wasted, so those are warnings, each reported once per event.
+	 */
+	function checkProducts(name, rule, event, properties) {
+		const product = rule.product ? rules.products?.[rule.product] : null;
+		const items = properties.products;
+		if (!product || !Array.isArray(items)) return;
+
+		let priced = false;
+		let notAPath = null;
+		items.forEach((item, i) => {
+			const at = `"${name}.products[${i}]"`;
+			if (typeOf(item) !== 'object') {
+				add(
+					'error',
+					'product_wrong_type',
+					`${at} should be an object but is ${typeOf(item)}.`,
+					{
+						event: name,
+						property: 'products',
+					},
+				);
+				return;
+			}
+			for (const key of product.required) {
+				if (item[key] === undefined || item[key] === null) {
+					add(
+						'error',
+						'product_missing_required',
+						`${at} is missing required "${key}", which rejects the whole event.`,
+						{ event: name, property: `products.${key}` },
+					);
+				}
+			}
+			for (const [key, value] of Object.entries(item)) {
+				const spec = product.properties[key];
+				if (!spec) {
+					add(
+						'error',
+						'product_unknown_property',
+						`${at} carries "${key}", which this event's product schema does not have. It sets additionalProperties:false, so the whole event is rejected.`,
+						{ event: name, property: `products.${key}` },
+					);
+					continue;
+				}
+				if (value === null || value === undefined) continue;
+				if (!typeMatches(spec.type, value)) {
+					add(
+						'error',
+						'product_wrong_type',
+						`${at}.${key} should be ${spec.type} but is ${typeOf(value)}.`,
+						{ event: name, property: `products.${key}` },
+					);
+				} else if (spec.enum && !spec.enum.includes(value)) {
+					const allowed = spec.enum.filter((v) => v !== null).join(', ');
+					add(
+						'error',
+						'product_bad_enum',
+						`${at}.${key} is "${value}", which is not one of: ${allowed}.`,
+						{ event: name, property: `products.${key}` },
+					);
+				}
+			}
+			if (typeof item.price === 'number') priced = true;
+			if (
+				notAPath === null &&
+				typeof item.category === 'string' &&
+				/[>|]/.test(item.category) &&
+				!item.category.includes('/')
+			) {
+				notAPath = item.category;
+			}
+		});
+
+		const named = (value) => typeof value === 'string' && value.trim() !== '';
+		if (
+			priced &&
+			!named(properties.currency) &&
+			!named(event.context?.currency)
+		) {
+			add(
+				'warning',
+				'price_without_currency',
+				`"${name}" prices its products but names no currency, neither its own "currency" nor context.currency. It is accepted, but the warehouse cannot convert the amounts, so they drop out of revenue and average price. Set the "currency" or "getCurrency" option.`,
+				{ event: name, property: 'currency' },
+			);
+		}
+		if (notAPath !== null) {
+			add(
+				'warning',
+				'category_not_a_path',
+				`"${name}" sends the category "${notAPath}". Categories are read as "/" paths, so this counts as one level in category interest and session audiences. Send "Women/Shoes/Boots".`,
+				{ event: name, property: 'products.category' },
+			);
+		}
+	}
+
+	/**
+	 * What this page still owes, recomputed on every call rather than stored: an impression waits on
+	 * a scroll and a rail on a fetch, so a missing event stops being reported the moment it arrives.
+	 */
+	function expectationProblems() {
+		if (!pageType) {
+			return [
+				{
+					severity: 'warning',
+					kind: 'no_page_type',
+					message:
+						'No page view was observed, so nothing could be checked for completeness. Call analytics.page({ type }) on every page.',
+				},
+			];
+		}
+
+		const expectation = rules.page_expectations?.[pageType];
+		if (!expectation) return [];
+
+		const missing = [];
+		for (const name of expectation.required ?? []) {
+			if (!seen.has(name)) {
+				missing.push({
+					severity: 'error',
+					kind: 'missing_expected_event',
+					message: `A "${pageType}" page must emit "${name}" and did not. Nothing invalid was sent — the event simply never fired, which is why schema validation cannot catch this.`,
+					event: name,
+					pageType,
+				});
+			}
+		}
+		for (const name of entered ? (expectation.required_on_entry ?? []) : []) {
+			if (!seen.has(name)) {
+				missing.push({
+					severity: 'error',
+					kind: 'missing_entry_event',
+					message: `Entering a "${pageType}" page from elsewhere must emit "${name}" and did not. It is owed once, by the first page of the run, not by every page.`,
+					event: name,
+					pageType,
+				});
+			}
+		}
+		for (const name of expectation.recommended ?? []) {
+			if (!seen.has(name)) {
+				missing.push({
+					severity: 'warning',
+					kind: 'missing_recommended_event',
+					message: `A "${pageType}" page usually emits "${name}". Still absent — legitimate if the surface is below the fold and nobody scrolled to it.`,
+					event: name,
+					pageType,
+				});
+			}
+		}
+		return missing;
+	}
+
+	/**
+	 * Print the summary once the page has gone quiet.
+	 *
+	 * The print is a snapshot and the object is live: anything that arrives afterwards updates
+	 * `report()`, and a previously-missing event that turns up is announced so the console does not
+	 * leave a retracted warning as the last word on screen.
+	 */
+	function checkExpectations() {
+		if (settled) return;
+		settled = true;
+		outstanding = new Set(
+			expectationProblems()
+				.map((p) => p.event)
+				.filter(Boolean),
+		);
+		if (log) print();
+	}
+
+	function print() {
+		const report = summary();
+		const style = report.ok ? 'color:#0e7a4b' : 'color:#b3261e';
+		const label = report.ok
+			? `CDP conformance: ${pageType} page OK (${report.eventCount} events)`
+			: `CDP conformance: ${report.errors} error(s), ${report.warnings} warning(s) on a ${pageType} page`;
+
+		// groupCollapsed rather than a wall of warnings: this runs on every page of a dev session,
+		// and a checker that buries the actual console is one people turn off.
+		console.groupCollapsed(`%c${label}`, `${style};font-weight:600`);
+		for (const p of report.problems) {
+			const fn =
+				p.severity === 'error'
+					? console.error
+					: p.severity === 'warning'
+						? console.warn
+						: console.info;
+			fn(`[${p.kind}] ${p.message}`);
+		}
+		console.info('Events seen:', Object.fromEntries(seen));
+		console.groupEnd();
+	}
+
+	function summary() {
+		// Validation problems are historical facts and are stored; missing-event problems are a
+		// statement about right now and are recomputed. See expectationProblems.
+		const all = [...problems, ...expectationProblems()];
+		const ordered = [...all].sort(
+			(a, b) => SEVERITY[b.severity] - SEVERITY[a.severity],
+		);
+		const errors = all.filter((p) => p.severity === 'error').length;
+		const warnings = all.filter((p) => p.severity === 'warning').length;
+		return {
+			ok: errors === 0,
+			pageType,
+			entered,
+			specVersion: rules.spec_version,
+			eventCount: [...seen.values()].reduce((n, c) => n + c, 0),
+			seen: Object.fromEntries(seen),
+			errors,
+			warnings,
+			problems: ordered,
+		};
+	}
+
+	const checker = {
+		/** Hand this to createAnalytics as `onEvent`. */
+		observe(event) {
+			try {
+				const name = event.event ?? event.type;
+				seen.set(name, (seen.get(name) ?? 0) + 1);
+				if (event.type === 'page') {
+					if (pageType !== null) previousPageType = pageType;
+					pageType = event.context?.page?.type ?? null;
+					entered = pageType !== previousPageType;
+					if (pageType !== null) store(storage, pageType);
+				}
+
+				// An event the summary already called missing has now turned up. Say so, or the console's
+				// last word on this page is a warning that is no longer true.
+				if (outstanding.delete(name) && log) {
+					console.info(
+						`%cCDP conformance: "${name}" arrived after the page settled — no longer missing.`,
+						'color:#0e7a4b',
+					);
+				}
+
+				checkEnvelope(event);
+				if (event.type === 'track') checkTrack(event);
+
+				clearTimeout(settleTimer);
+				settleTimer = setTimeout(checkExpectations, settleMs);
+			} catch (error) {
+				// The checker must never be the reason an event fails to send.
+				console.warn('[hp] conformance checker failed', error);
+			}
+		},
+
+		/** Force the completeness check now, rather than waiting for the page to go quiet. */
+		finish() {
+			clearTimeout(settleTimer);
+			checkExpectations();
+			return summary();
+		},
+
+		report: summary,
+	};
+
+	if (typeof window !== 'undefined') {
+		// The handle the CI harness reads. Also the fastest way for a developer to ask "what did
+		// this page actually send" without a network tab full of batched beacons.
+		window.__hpConformance = checker;
+		// A visitor who leaves before the page settles still gets checked, which matters because a
+		// fast bounce is precisely when a late event is missed.
+		window.addEventListener('pagehide', () => checkExpectations(), {
+			once: true,
+		});
+	}
+
+	return checker;
+}