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

package/src/context.js

@@ -0,0 +1,439 @@
+import { realId } from './shape.js';
+import { SPEC_VERSION } from './spec-version.js';
+
+/**
+ * Context assembly: everything ambient that hangs off each event. What the server must own (ip,
+ * bot classification, parsed user agent) is left null here.
+ */
+
+export function getCookie(name) {
+	if (typeof document === 'undefined') return null;
+	try {
+		const match = document.cookie
+			.split(';')
+			.map((s) => s.trim())
+			.find((row) => row.startsWith(`${name}=`));
+		if (!match) return null;
+		return decodeURIComponent(match.slice(name.length + 1)) || null;
+	} catch {
+		// Malformed cookie values can throw in decodeURIComponent.
+		return null;
+	}
+}
+
+const CLICK_IDS = { gclid: 'gclid', fbclid: 'fbclid', ttclid: 'ttclid' };
+
+const EMAIL = /[a-z0-9._%+-]+@[a-z0-9-]+(\.[a-z0-9-]+)*\.[a-z]{2,}/i;
+/** 13 or more digits, optionally grouped by single spaces or dashes: a card number's shape. */
+const LONG_DIGITS = /\d(?:[ -]?\d){12,}/;
+
+/** Opaque ad-platform tokens: their values are random, so a digit run in one proves nothing. */
+const OPAQUE_PARAMS = new Set(['gclid', 'fbclid', 'ttclid', 'msclkid']);
+
+/**
+ * Whether a query value carries personal data whatever its parameter is called: an email address,
+ * or a digit run long enough to be a card number. Checked on the decoded value and, for a value
+ * that was encoded twice on its way here, on the value decoded once more.
+ */
+export function isSensitiveValue(value, name = '') {
+	if (typeof value !== 'string' || value === '') return false;
+	const forms = [value];
+	try {
+		const again = decodeURIComponent(value.replace(/\+/g, ' '));
+		if (again !== value) forms.push(again);
+	} catch {
+		/* not double-encoded */
+	}
+	const digits = !OPAQUE_PARAMS.has(String(name).toLowerCase());
+	return forms.some(
+		(form) => EMAIL.test(form) || (digits && LONG_DIGITS.test(form)),
+	);
+}
+
+/**
+ * Build context.campaign from the current URL, click ids included. Values get the same personal
+ * data check as any URL value (an ESP can merge the recipient into utm_content).
+ */
+export function readCampaign(search) {
+	if (!search) return null;
+	const p = new URLSearchParams(search);
+	const out = {};
+	const utm = {
+		utm_source: 'source',
+		utm_medium: 'medium',
+		utm_campaign: 'name',
+		utm_term: 'term',
+		utm_content: 'content',
+	};
+	for (const [param, field] of [
+		...Object.entries(utm),
+		...Object.entries(CLICK_IDS),
+	]) {
+		const v = p.get(param);
+		if (v && !isSensitiveValue(v, param)) out[field] = v;
+	}
+	return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Strip params matching the integrator's blocklist before the query string is ever
+ * sent. Patterns are anchored and case-insensitive; an invalid pattern degrades to
+ * a literal match rather than throwing.
+ */
+export function filterSearch(search, blocklist = []) {
+	if (!search) return null;
+	if (!blocklist.length) return search;
+	try {
+		const p = new URLSearchParams(search);
+		const matchers = blocklist.map((raw) => {
+			try {
+				return new RegExp(`^${raw}$`, 'i');
+			} catch {
+				return { test: (s) => s.toLowerCase() === String(raw).toLowerCase() };
+			}
+		});
+		for (const key of [...p.keys()]) {
+			if (matchers.some((m) => m.test(key))) p.delete(key);
+		}
+		const s = p.toString();
+		return s ? `?${s}` : '';
+	} catch {
+		// Drop the whole query string rather than risk leaking a suppressed param.
+		return '';
+	}
+}
+
+/**
+ * Params stripped from every URL the SDK reports, whatever the integrator configured. Each is a
+ * name that, on some storefront, carries an email address, a credential or an address fragment.
+ * Matched exactly (case-insensitively); the patterns below catch the names built around them.
+ */
+export const SENSITIVE_PARAMS = [
+	'email',
+	'e-mail',
+	'password',
+	'pass',
+	'pwd',
+	'token',
+	'auth',
+	'code',
+	'uid',
+	'customer_id',
+	'postcode',
+	'zip',
+	'phone',
+	'applyCode',
+];
+
+/**
+ * Fragments that make a param name sensitive wherever they appear in it (`resetToken`,
+ * `customerEmail`), compared with case and the separators `-`, `_` and `.` removed.
+ */
+export const SENSITIVE_PARAM_FRAGMENTS = [
+	'email',
+	'password',
+	'passwd',
+	'pwd',
+	'token',
+	'secret',
+	'auth',
+	'session',
+	'phone',
+	'postcode',
+	'zip',
+	'address',
+	'birth',
+	'card',
+	'cvv',
+	'iban',
+	'ssn',
+	'customerid',
+	'userid',
+];
+
+/**
+ * Too short to match inside a word — `hotel`, `guid` and `adobe` are not personal data — so these
+ * count only as a whole word of the name: `tel`, `customer_tel`, `userUid`, `dob`.
+ */
+export const SENSITIVE_PARAM_WORDS = ['tel', 'uid', 'dob'];
+
+/** Kept under an allowlist regardless, because attribution depends on them. */
+export const CAMPAIGN_PARAMS = [
+	'utm_source',
+	'utm_medium',
+	'utm_campaign',
+	'utm_term',
+	'utm_content',
+	'gclid',
+	'fbclid',
+	'ttclid',
+	'msclkid',
+];
+
+const SENSITIVE = new Set(SENSITIVE_PARAMS.map((p) => p.toLowerCase()));
+
+/** Whether a param NAME is sensitive by the built-in rules. */
+export function isSensitiveParam(name) {
+	const lower = String(name).toLowerCase();
+	if (SENSITIVE.has(lower)) return true;
+	const compact = lower.replace(/[-_.]/g, '');
+	if (SENSITIVE_PARAM_FRAGMENTS.some((fragment) => compact.includes(fragment)))
+		return true;
+	const words = String(name)
+		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+		.toLowerCase()
+		.split(/[^a-z0-9]+/);
+	return words.some((word) => SENSITIVE_PARAM_WORDS.includes(word));
+}
+
+function matchers(patterns) {
+	return (patterns ?? []).map((raw) => {
+		try {
+			return new RegExp(`^${raw}$`, 'i');
+		} catch {
+			return { test: (s) => s.toLowerCase() === String(raw).toLowerCase() };
+		}
+	});
+}
+
+/**
+ * The query string as it may leave the browser: built-in denylist always applied, then either the
+ * allowlist (plus campaign params) or the legacy blocklist.
+ *
+ * Two built-in checks, and only one of them can be waived:
+ *  - a param whose NAME matches the built-in rules is dropped, unless `sensitiveParamAllowlist`
+ *    names it — the escape hatch for a false positive such as a storefront's own `author` filter;
+ *  - a param whose VALUE is an email address or a card-length digit run is dropped whatever it is
+ *    called, campaign params included, and nothing re-admits it.
+ *
+ * @param {string} search
+ * @param {{ queryParamAllowlist?: string[] | null, queryParamBlocklist?: string[], sensitiveParamAllowlist?: string[] }} [cfg]
+ */
+export function scrubSearch(search, cfg = {}) {
+	if (!search) return null;
+	try {
+		const params = new URLSearchParams(search);
+		const allow = cfg.queryParamAllowlist
+			? matchers([...cfg.queryParamAllowlist, ...CAMPAIGN_PARAMS])
+			: null;
+		const block = matchers(cfg.queryParamBlocklist);
+		const exempt = matchers(cfg.sensitiveParamAllowlist);
+		for (const key of new Set(params.keys())) {
+			const drop =
+				(isSensitiveParam(key) && !exempt.some((m) => m.test(key))) ||
+				params.getAll(key).some((value) => isSensitiveValue(value, key)) ||
+				(allow
+					? !allow.some((m) => m.test(key))
+					: block.some((m) => m.test(key)));
+			if (drop) params.delete(key);
+		}
+		const out = params.toString();
+		return out ? `?${out}` : '';
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * Same-origin referrers are scrubbed like the page URL; cross-origin ones keep origin and path
+ * only, because another site's query string is not ours to collect.
+ */
+export function scrubReferrer(referrer, origin, cfg = {}) {
+	if (!referrer) return null;
+	try {
+		const url = new URL(referrer);
+		if (origin && url.origin === origin) {
+			return url.origin + url.pathname + (scrubSearch(url.search, cfg) ?? '');
+		}
+		return url.origin + url.pathname;
+	} catch {
+		return null;
+	}
+}
+
+/** ISO-4217, uppercased; anything else is dropped rather than sent to fail validation. */
+export function currencyCode(value) {
+	if (typeof value !== 'string') return null;
+	const code = value.trim().toUpperCase();
+	return /^[A-Z]{3}$/.test(code) ? code : null;
+}
+
+/** ISO-3166-1 alpha-2, uppercased; anything else is dropped. */
+export function countryCode(value) {
+	if (typeof value !== 'string') return null;
+	const code = value.trim().toUpperCase();
+	return /^[A-Z]{2}$/.test(code) ? code : null;
+}
+
+/**
+ * A BCP-47 locale tag (`en`, `en-GB`, `zh-Hant-TW`). Platform spellings such as `en_GB` are
+ * normalised, so one site's locale is one string whichever system reported it; anything that is
+ * not a locale is dropped.
+ */
+export function localeTag(value) {
+	if (typeof value !== 'string') return null;
+	const tag = value.trim().replace(/_/g, '-');
+	if (!/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(tag)) return null;
+	try {
+		return Intl.getCanonicalLocales(tag)[0];
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * A per-request value: the host's getter when it has one and it answers, else the static option.
+ * Every host getter is read through this, per event, and one that throws costs its field, never the
+ * event: multi-currency, multi-destination tenants change these mid-visit.
+ */
+export function perRequest(getter, fallback) {
+	if (typeof getter === 'function') {
+		try {
+			const value = getter();
+			if (value != null) return value;
+		} catch {
+			/* a failing getter must not cost the event */
+		}
+	}
+	return fallback;
+}
+
+/** Top-level keys of the core context schema; anything else is refused by the ingest. */
+export const CONTEXT_KEYS = [
+	'spec',
+	'library',
+	'source',
+	'session_id',
+	'render_id',
+	'identity_trust',
+	'page',
+	'campaign',
+	'device',
+	'currency',
+	'locale',
+	'timezone',
+	'country',
+	'ship_to_country',
+	'ip',
+	'original_timestamp',
+	'consent',
+	'experiments',
+	'bot',
+	'extensions',
+	'audiences',
+	'decisions',
+	'recommendations',
+	'is_impersonated',
+];
+
+export function sourceContext(cfg) {
+	return {
+		property_id: String(cfg.propertyId),
+		channel: cfg.channel ?? null,
+		market: cfg.market ?? null,
+		environment: cfg.environment ?? null,
+	};
+}
+
+/** context.page with every URL scrubbed. Shared by both delivery paths. */
+export function pageContext(cfg) {
+	const loc = typeof window !== 'undefined' ? window.location : null;
+	const search = loc ? scrubSearch(loc.search, cfg) : null;
+	return {
+		url: loc
+			? loc.origin + loc.pathname + (search ?? '')
+			: (cfg.pageUrl ?? null),
+		path: loc ? loc.pathname : (cfg.pagePath ?? null),
+		search: search ?? null,
+		referrer:
+			typeof document !== 'undefined'
+				? scrubReferrer(document.referrer, loc?.origin, cfg)
+				: null,
+		title: typeof document !== 'undefined' ? document.title || null : null,
+		type: cfg.pageType ?? null,
+	};
+}
+
+/**
+ * @param {object} cfg  resolved SDK config
+ * @param {object} [overrides] per-call context overrides
+ */
+export function buildContext(cfg, overrides = {}) {
+	const loc = typeof window !== 'undefined' ? window.location : null;
+
+	const ctx = {
+		library: { name: cfg.libraryName, version: cfg.libraryVersion },
+		spec: { version: SPEC_VERSION },
+		source: sourceContext(cfg),
+		session_id: perRequest(cfg.getSessionId, null),
+		render_id: perRequest(cfg.getRenderId, null),
+		// The browser is always a real device. Only a cacheable server render is not.
+		identity_trust: realId(perRequest(cfg.getAnonymousId, null))
+			? 'device'
+			: 'none',
+		// Emitted even with no `window`: under SSR the integrator still knows the page type and path.
+		page: pageContext(cfg),
+		campaign: loc ? readCampaign(loc.search) : null,
+		device: {
+			user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : null,
+			// type/os/browser are derived server-side at ingest from the UA.
+			type: null,
+			viewport_width: typeof window !== 'undefined' ? window.innerWidth : null,
+			viewport_height:
+				typeof window !== 'undefined' ? window.innerHeight : null,
+		},
+		currency: currencyCode(perRequest(cfg.getCurrency, cfg.currency)),
+		// The site's locale (which storefront was served), not navigator.language, so it agrees with
+		// the backend's for the same render.
+		locale: localeTag(perRequest(cfg.getLocale, cfg.locale)),
+		timezone: (() => {
+			try {
+				return Intl.DateTimeFormat().resolvedOptions().timeZone;
+			} catch {
+				return null;
+			}
+		})(),
+		country: countryCode(cfg.country),
+		ship_to_country: countryCode(
+			perRequest(cfg.getShipToCountry, cfg.shipToCountry),
+		),
+		// Server-owned. Explicitly null so a violation is visible if anyone sets them.
+		ip: null,
+		bot: null,
+		consent: cfg.getConsent?.() ?? null,
+		experiments: perRequest(cfg.getExperiments, null),
+		// Memberships at this moment, read per event because session membership changes mid-visit.
+		// Kept apart from `experiments`: a membership is a fact about the visitor, a holdout a choice
+		// made to them, and measuring lift needs both separately.
+		audiences: perRequest(cfg.getAudiences, null),
+		// Decisions in force, on every event so later outcomes (a basket, an order) join to them. The
+		// decision and its propensity are logged server-side; only the ids travel here.
+		decisions: perRequest(cfg.getDecisions, null),
+		// Rails in force, host-supplied and read per event. Kept apart from `decisions`: a rail has no
+		// propensity, and estimators downstream of the decision log weight by one.
+		recommendations: perRequest(cfg.getRecommendations, null),
+		extensions: perRequest(cfg.getExtensions, null),
+	};
+
+	return deepMerge(ctx, overrides);
+}
+
+function deepMerge(base, extra) {
+	if (!extra) return base;
+	const out = { ...base };
+	for (const [k, v] of Object.entries(extra)) {
+		if (
+			v &&
+			typeof v === 'object' &&
+			!Array.isArray(v) &&
+			base[k] &&
+			typeof base[k] === 'object' &&
+			!Array.isArray(base[k])
+		) {
+			out[k] = deepMerge(base[k], v);
+		} else if (v !== undefined) {
+			out[k] = v;
+		}
+	}
+	return out;
+}