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

package/src/device-storage.js

@@ -0,0 +1,213 @@
+/**
+ * Two device writes beyond the SDK's own buffers.
+ *
+ *   held store     events the consent gate holds for an unanswered CMP, in sessionStorage per
+ *                  property, so a navigation before the answer (a sign-in redirect) does not lose
+ *                  them (`holdAcrossPages`, 3.5). They leave only on a grant, on whichever page it
+ *                  comes; a refusal deletes them.
+ *   device cookie  Hyper-Personalisation's device id, for a source whose settings say `hp_cookie`
+ *                  (3.6). Under strict consent it is written only once analytics is granted.
+ */
+
+import { getCookie, perRequest } from './context.js';
+import { realId, uuid } from './shape.js';
+import { storageKey, storageName } from './storage-scope.js';
+
+/** How long held events may wait for an answer across pages. A tab left for longer starts over. */
+export const HELD_MAX_AGE_MS = 30 * 60 * 1000;
+
+const session = () => {
+	try {
+		return typeof sessionStorage === 'undefined' ? null : sessionStorage;
+	} catch {
+		return null;
+	}
+};
+
+const local = () => {
+	try {
+		return typeof localStorage === 'undefined' ? null : localStorage;
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * @param {string} key  A property-scoped key (storageKey(storageName('held'), propertyId)).
+ * @param {() => number} [now]
+ */
+export function createHeldStore(key, now = () => Date.now()) {
+	return {
+		/** @returns {{ items: object[], anonymousId: string|null }} */
+		read() {
+			try {
+				const raw = session()?.getItem(key);
+				const saved = raw ? JSON.parse(raw) : null;
+				if (!saved || now() - saved.savedAt > HELD_MAX_AGE_MS) {
+					if (saved) session()?.removeItem(key);
+					return { items: [], anonymousId: null };
+				}
+				return {
+					items: Array.isArray(saved.items) ? saved.items : [],
+					anonymousId:
+						typeof saved.anonymousId === 'string' ? saved.anonymousId : null,
+				};
+			} catch {
+				return { items: [], anonymousId: null };
+			}
+		},
+		write(items, anonymousId = null) {
+			try {
+				if (items.length === 0) session()?.removeItem(key);
+				else
+					session()?.setItem(
+						key,
+						JSON.stringify({ savedAt: now(), items, anonymousId }),
+					);
+			} catch {
+				/* quota or private browsing: the events are still held for this page */
+			}
+		},
+	};
+}
+
+/** 400 days, the longest a browser keeps a cookie (RFC 6265bis); refreshed on every page. */
+export const DEVICE_COOKIE_MAX_AGE = 400 * 24 * 60 * 60;
+
+export function writeCookie(name, value, maxAge, domain) {
+	if (typeof document === 'undefined') return false;
+	try {
+		const secure =
+			typeof location !== 'undefined' && location.protocol === 'https:'
+				? '; Secure'
+				: '';
+		const scope = domain ? `; Domain=${domain}` : '';
+		// No Max-Age: a session cookie, gone when the browser closes.
+		const age = maxAge === null ? '' : `; Max-Age=${maxAge}`;
+		document.cookie =
+			`${name}=${encodeURIComponent(value)}; Path=/${age}; SameSite=Lax` +
+			scope +
+			secure;
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Hyper-Personalisation's own device cookie (3.6, a source set to `hp_cookie`): a first-party
+ * cookie the SDK mints and keeps, one per browser rather than per property. Under strict consent
+ * it is written only once analytics is granted; until then the id lives in memory, and in the held
+ * store beside the events that carry it. Every page under a grant writes it again, so it lasts 400
+ * days from the last visit rather than the first.
+ *
+ * A device id 3.5 minted into localStorage (`mintAnonymousId`) is adopted as the cookie's value,
+ * and its localStorage key removed, the first time the cookie is written.
+ *
+ * @param {object} options
+ * @param {string} options.name        The cookie name, storageName('anonymousId').
+ * @param {string|null} [options.domain] As the consent cookie's (`consentCookieDomain`).
+ * @param {string} options.legacyKey   3.5's localStorage key for this property.
+ * @param {(name: string) => string|null} options.read   Reads a cookie.
+ * @param {() => string} options.mint
+ * @param {() => boolean} options.mayStore  Strict consent: analytics is granted.
+ * @param {string|null} [options.carried]   An id carried in the held store from an earlier page.
+ */
+export function createDeviceCookie({
+	name,
+	domain = null,
+	legacyKey,
+	read,
+	mint,
+	mayStore,
+	carried = null,
+}) {
+	let legacy = null;
+	try {
+		legacy = local()?.getItem(legacyKey) || null;
+	} catch {
+		legacy = null;
+	}
+	let id = read(name) ?? legacy ?? carried;
+	let written = false;
+
+	const persist = () => {
+		if (written || id === null || !mayStore()) return;
+		written = writeCookie(name, id, DEVICE_COOKIE_MAX_AGE, domain);
+		if (!written || legacy === null) return;
+		try {
+			local()?.removeItem(legacyKey);
+			legacy = null;
+		} catch {
+			/* left for the next page to remove */
+		}
+	};
+
+	return {
+		get() {
+			id ??= mint();
+			persist();
+			return id;
+		},
+		/** The id so far, without minting one. */
+		peek: () => id,
+		/** Consent was granted: write what was minted before it. */
+		persist,
+		/**
+		 * Consent was refused or withdrawn: the id must not outlive the permission it was kept under,
+		 * so a later grant starts a new device, as `analytics.reset()` does.
+		 */
+		forget() {
+			writeCookie(name, '', 0, domain);
+			id = null;
+			written = false;
+			try {
+				local()?.removeItem(legacyKey);
+			} catch {
+				/* nothing was stored */
+			}
+			legacy = null;
+		},
+	};
+}
+
+/**
+ * Where device ids come from, from the source's settings (`hp.anonymousId`, ADR-0017).
+ *
+ *   site_cookie  the cookie the settings name, or (no name) `getAnonymousId`, the integration's own.
+ *   hp_cookie    Hyper-Personalisation's cookie, minted and kept here. `getAnonymousId` is ignored.
+ *   absent       settings from before 3.6: `getAnonymousId`, as before.
+ *
+ * With `orOwn`, a visitor the site has no id for (the cookie missing, empty or a placeholder) gets
+ * Hyper-Personalisation's cookie rather than none, as analytics.js does: an event with no device id
+ * belongs to nobody (3.18).
+ *
+ * Replaces `cfg.getAnonymousId` to match, and returns the device cookie it may fall back to.
+ */
+export function deviceIdFrom(cfg, { carried = null, mayStore, orOwn = false }) {
+	const setting = cfg.anonymousIdSource;
+	const own = () =>
+		createDeviceCookie({
+			name: storageName('anonymousId'),
+			domain: cfg.consentCookieDomain ?? null,
+			legacyKey: storageKey(storageName('anonymousId'), cfg.propertyId),
+			read: getCookie,
+			mint: uuid,
+			mayStore,
+			carried,
+		});
+	if (setting?.source === 'hp_cookie') {
+		const device = own();
+		cfg.getAnonymousId = () => device.get();
+		return device;
+	}
+	if (setting?.source === 'site_cookie' && setting.cookie) {
+		const name = setting.cookie;
+		cfg.getAnonymousId = () => getCookie(name);
+	}
+	if (!orOwn) return null;
+	const site = cfg.getAnonymousId;
+	const device = own();
+	cfg.getAnonymousId = () => realId(perRequest(site, null)) ?? device.get();
+	return device;
+}

package/src/experiments.js

@@ -0,0 +1,220 @@
+/**
+ * Deterministic experiment assignment for recommendation rails, and the fingerprint that
+ * identifies the candidate set a rail was drawn from.
+ *
+ * The arm is decided in the browser before the rail is requested (a control must not call the
+ * recommender) and recorded on the impression. It is a hash of a stable unit rather than a stored
+ * coin flip, so a visitor never moves between arms when storage is cleared. The holdout is carved
+ * off the top of the bucket space before the variants, as DecisionSlot.holdout is. Which
+ * experiments exist and who is eligible is the host's business.
+ */
+
+/** Bucket resolution. 10,000 makes a 0.01% share expressible, which is finer than any real split. */
+const DEFAULT_BUCKETS = 10000;
+
+/** The arm name recorded for held-out traffic when the caller does not choose one. */
+const DEFAULT_HOLDOUT_NAME = 'holdout';
+
+/**
+ * 32-bit hash of a string: FNV-1a, then MurmurHash3's finaliser (fmix32), which FNV-1a needs to
+ * avalanche on short, similar ids. Not cryptographic; synchronous because assignment happens
+ * before the first render, and crypto.subtle is async.
+ */
+export function hash32(input) {
+	let h = 0x811c9dc5;
+	const s = String(input);
+	for (let i = 0; i < s.length; i += 1) {
+		h ^= s.charCodeAt(i);
+		// FNV prime, via shifts: `h * 16777619` overflows the double's integer range and loses bits.
+		h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+	}
+	h ^= h >>> 16;
+	h = Math.imul(h, 0x85ebca6b) >>> 0;
+	h ^= h >>> 13;
+	h = Math.imul(h, 0xc2b2ae35) >>> 0;
+	h ^= h >>> 16;
+	return h >>> 0;
+}
+
+/**
+ * Which bucket a unit falls in for a given salt. Salted per experiment so concurrent experiments
+ * are independent permutations of the population.
+ */
+export function hashBucket(unit, salt, buckets = DEFAULT_BUCKETS) {
+	// A NUL separator prevents `ab|c` colliding with `a|bc`. Keep it an escape: a literal NUL byte
+	// makes git treat the file as binary.
+	return hash32(`${salt}\0${unit}`) % buckets;
+}
+
+/**
+ * Assign a visitor to an arm of a recommendation experiment.
+ *
+ * @param {object} options
+ * @param {string|null} options.unit The thing being bucketed — usually the anonymous id.
+ * @param {string} options.experiment Experiment name; also the default hash salt.
+ * @param {Array<{name: string, share: number}>} options.variants Arms and their shares of the
+ *   NON-held-out traffic. Shares are normalised, so [1, 1] and [0.5, 0.5] mean the same thing.
+ * @param {number} [options.holdoutShare] Fraction of ALL traffic withheld from personalisation.
+ * @param {string} [options.holdoutName] Arm name recorded for held-out traffic.
+ * @param {string} [options.salt] Override the salt to keep an arm stable across a rename.
+ * @param {number} [options.buckets] Bucket resolution.
+ * @param {'anonymous_id'|'customer_id'|'session_id'|'other'} [options.unitKind] What `unit` is.
+ * @returns {{experiment: string, variant: string, holdout: boolean, assignment_bucket: number,
+ *   assignment_unit_kind: string}|null} Shaped to spread straight onto the impression event.
+ *   Null when there is no unit to bucket.
+ */
+export function assignRecommendationVariant(options) {
+	const {
+		unit,
+		experiment,
+		variants,
+		holdoutShare = 0,
+		holdoutName = DEFAULT_HOLDOUT_NAME,
+		salt,
+		buckets = DEFAULT_BUCKETS,
+		unitKind = 'anonymous_id',
+	} = options ?? {};
+
+	if (typeof experiment !== 'string' || experiment === '') {
+		throw new Error('assignRecommendationVariant: experiment is required');
+	}
+	if (!Array.isArray(variants) || variants.length === 0) {
+		throw new Error(
+			'assignRecommendationVariant: variants must be a non-empty array',
+		);
+	}
+
+	const total = variants.reduce((sum, v) => sum + (Number(v?.share) || 0), 0);
+	if (!(total > 0)) {
+		throw new Error(
+			'assignRecommendationVariant: variant shares must sum to more than zero',
+		);
+	}
+
+	// No unit, no assignment, and specifically not the holdout, which would fill with every
+	// unidentifiable visitor. The caller serves the rail normally and records `variant: null`.
+	if (unit == null || unit === '') return null;
+
+	const bucket = hashBucket(unit, salt ?? experiment, buckets);
+
+	// Whole buckets, so a boundary cannot land either side of a bucket depending on float rounding.
+	const holdoutCut = Math.round(
+		Math.min(Math.max(holdoutShare, 0), 1) * buckets,
+	);
+	if (bucket < holdoutCut) {
+		return {
+			experiment,
+			variant: holdoutName,
+			holdout: true,
+			assignment_bucket: bucket,
+			assignment_unit_kind: unitKind,
+		};
+	}
+
+	const treated = buckets - holdoutCut;
+	let edge = holdoutCut;
+	for (let i = 0; i < variants.length; i += 1) {
+		edge += Math.round((treated * (Number(variants[i].share) || 0)) / total);
+		// The last arm takes whatever rounding left over, so no bucket is unassignable.
+		if (bucket < edge || i === variants.length - 1) {
+			return {
+				experiment,
+				variant: String(variants[i].name),
+				holdout: false,
+				assignment_bucket: bucket,
+				assignment_unit_kind: unitKind,
+			};
+		}
+	}
+
+	return null;
+}
+
+/**
+ * A property holdout's split as a serving response states it: the share held out and the share of
+ * ALL shoppers personalised (the ramp, capped by what the holdout leaves; everyone else without
+ * one). The public API's `personalisedShare` computes the same.
+ *
+ * @param {{share: number, ramp?: number|null}} holdout The property's holdout.
+ * @returns {{holdout_share: number, personalised_share: number}}
+ */
+export function holdoutShares(holdout) {
+	const clamp = (share) => Math.min(Math.max(Number(share) || 0, 0), 1);
+	const share = clamp(holdout.share);
+	const rest = 1 - share;
+	return {
+		holdout_share: share,
+		personalised_share:
+			holdout.ramp == null ? rest : Math.min(clamp(holdout.ramp), rest),
+	};
+}
+
+/**
+ * A shopper's group for a property's personalisation: the same answer the activation edge and the
+ * public API give, from the same hash and the same fixed ranges (spec/assignment/holdout.json holds
+ * the vectors). Below `share` the shopper is held out; below `share + ramp` personalised; above it
+ * excluded, seeing the default and counted in neither group. A null ramp personalises everyone
+ * outside the holdout. Ramping widens only the personalised range, so nobody ever moves into or out
+ * of the holdout. No unit is never held out; under a ramp it is excluded, since it could only ever
+ * count on the treated side.
+ *
+ * @param {{share: number, ramp?: number|null, salt: string}|null|undefined} holdout The property's holdout.
+ * @param {string|null|undefined} unit The anonymous id.
+ * @returns {{holdout: boolean, bucket: number|null, group: 'holdout'|'personalised'|'excluded'}}
+ */
+export function holdoutAssignment(holdout, unit) {
+	if (!holdout || typeof holdout.salt !== 'string')
+		return { holdout: false, bucket: null, group: 'personalised' };
+	const ramped = holdout.ramp != null;
+	if (unit == null || unit === '')
+		return {
+			holdout: false,
+			bucket: null,
+			group: ramped ? 'excluded' : 'personalised',
+		};
+	const { holdout_share: share, personalised_share: personalised } =
+		holdoutShares(holdout);
+	const bucket = hashBucket(unit, holdout.salt);
+	const cut = (s) => Math.round(s * DEFAULT_BUCKETS);
+	const group =
+		share > 0 && bucket < cut(share)
+			? 'holdout'
+			: !ramped || bucket < cut(share + personalised)
+				? 'personalised'
+				: 'excluded';
+	return { holdout: group === 'holdout', bucket, group };
+}
+
+/**
+ * A visitor's side of a readout slot's bandit-vs-default 50/50, as the public API decides it
+ * (spec/assignment/bandit-split.json): the holdout's hash over the same anonymous id, salted with
+ * the experiment name `bandit-vs-default:<slot>`, so it is independent of the holdout and of every
+ * other slot. Buckets below 5000 are the slot's default; the rest get the bandit. Null without a
+ * slot or a unit: such a visitor is in no split.
+ *
+ * @param {string} slot The slot key.
+ * @param {string|null|undefined} unit The anonymous id.
+ * @returns {'bandit'|'default'|null}
+ */
+export function banditSplit(slot, unit) {
+	if (typeof slot !== 'string' || slot === '' || unit == null || unit === '')
+		return null;
+	return hashBucket(unit, `bandit-vs-default:${slot}`) < DEFAULT_BUCKETS / 2
+		? 'default'
+		: 'bandit';
+}
+
+/**
+ * Fingerprint an ordered candidate set: the candidates the serving response carried, not the
+ * tiles rendered. Order is part of the identity. Prefixed with the count (`24-3f9a1c07`) so a
+ * truncated set is visible without a lookup.
+ */
+export function candidateSetFingerprint(productIds) {
+	const ids = (productIds ?? [])
+		.map((id) => String(id ?? ''))
+		.filter((id) => id !== '');
+	if (ids.length === 0) return null;
+	// Same separator, same reason: joining on a byte that cannot appear in an id keeps
+	// ['ab', 'c'] and ['a', 'bc'] distinct fingerprints.
+	return `${ids.length}-${hash32(ids.join('\0')).toString(16).padStart(8, '0')}`;
+}

package/src/ga4.js

@@ -0,0 +1,124 @@
+/**
+ * GA4 items -> spec products. Shared by the client and the dataLayer adapter.
+ */
+
+/**
+ * Normalise a category path to the spec's '/'-joined form, so `A / B` and `A/B` are one category.
+ */
+function categoryPath(value) {
+	if (value == null) return null;
+	const path = String(value)
+		.split('/')
+		.map((level) => level.trim())
+		.filter(Boolean)
+		.join('/');
+	return path === '' ? null : path;
+}
+
+/** GA4 splits a path over item_category..item_category5; some sites send it pre-joined in item_category. */
+function ga4Category(item) {
+	const first = item.item_category;
+	if (first != null && String(first).includes('/')) return categoryPath(first);
+	const levels = [
+		first,
+		item.item_category2,
+		item.item_category3,
+		item.item_category4,
+		item.item_category5,
+	]
+		.map((level) => (level == null ? '' : String(level).trim()))
+		.filter(Boolean);
+	return categoryPath(levels.join('/'));
+}
+
+const text = (v) => {
+	// An object is never a name or an id, however a tracker happens to fill the field.
+	if (v == null || typeof v === 'object') return null;
+	const trimmed = String(v).trim();
+	return trimmed === '' ? null : trimmed;
+};
+
+/**
+ * GA4's parent id is `item_group_id` (the Merchant Center attribute GA4 items accept); `item_id`
+ * is the purchasable variant. The spec's product_id is the parent, so they cross over.
+ */
+/**
+ * The first usable id among candidates: a platform that sends `item_group_id: ''` has sent no
+ * parent, and letting the blank win would drop the product rather than fall back to the item.
+ */
+export function firstId(...candidates) {
+	for (const value of candidates) {
+		if (typeof value === 'number' && Number.isFinite(value))
+			return String(value);
+		if (typeof value === 'string' && value.trim() !== '') return value.trim();
+	}
+	return null;
+}
+
+export const defaultProductId = (item) =>
+	firstId(item.item_group_id, item.item_id);
+
+/**
+ * Map a GA4 item onto a spec product.
+ *
+ * @param {object} item
+ * @param {(item: object) => unknown} [productId] Resolves the parent product id; a platform whose
+ *   items name it differently passes its own, usually through a preset.
+ */
+export function fromGa4Item(item, productId = defaultProductId) {
+	if (!item) return null;
+	const num = (v) =>
+		v == null || v === '' || Number.isNaN(Number(v)) ? null : Number(v);
+	// Six places clears float noise (32.99 - 16.49 = 16.500000000000004) without rounding any currency.
+	const money = (v) => {
+		const n = num(v);
+		return n == null ? null : Math.round(n * 1e6) / 1e6;
+	};
+	const nonNegative = (v) => {
+		const n = money(v);
+		return n != null && n >= 0 ? n : null;
+	};
+	const count = (v) => {
+		const n = num(v);
+		return Number.isInteger(n) && n >= 0 ? n : null;
+	};
+	// Trimmed: 'Acme' and 'Acme ' would be two brands that render identically.
+	const str = text;
+
+	return {
+		product_id: str(productId(item)),
+		sku: str(item.item_id),
+		name: str(item.item_name),
+		brand: str(item.item_brand),
+		variant: str(item.item_variant) ?? str(item.variant),
+		category: ga4Category(item),
+		price: money(item.price),
+		discount: nonNegative(item.discount),
+		// No per-line `currency`: a basket cannot mix currencies, so it is context.currency,
+		// set once per event rather than repeated on every line of every commerce event.
+		quantity: count(item.quantity),
+		// Line-level, and independent of any order-level code — GA4 says so explicitly, and only the
+		// line knows which line a promotion actually landed on.
+		coupon: str(item.coupon),
+		// Rank in a list, which only the caller knows. Never the offset in `products`: that would
+		// stamp position 1 on every single-product event and bias the position metric.
+		position: count(item.index) != null ? count(item.index) + 1 : null,
+		// `image_link` is the product feeds' (Google, Meta) name for `image_url`. Both are sent even
+		// though the catalogue has them: products absent from the feed have no other source.
+		url: str(item.url) ?? str(item.item_url) ?? null,
+		image_url: str(item.image_url) ?? str(item.image_link) ?? null,
+		// The variant a tile rendered when the shopper has chosen nothing, kept apart from `sku` so an
+		// impression is never mistaken for a selection.
+		displayed_sku: str(item.displayed_sku) ?? str(item.displayed_variant_sku),
+	};
+}
+
+/**
+ * Map GA4 items to spec products, dropping any that carry no identity: validation is per event,
+ * so one id-less row would quarantine the whole impression.
+ */
+export function toProducts(items, productId = defaultProductId) {
+	return (items ?? [])
+		.map((item) => fromGa4Item(item, productId))
+		.filter((p) => p?.product_id);
+}

package/src/hash.js

@@ -0,0 +1,138 @@
+/**
+ * SHA-256, synchronously, so a page can hash an address in the same call that reports it and never
+ * awaits the SDK. SubtleCrypto is asynchronous only, and absent outside a secure context.
+ */
+
+const primes = [];
+for (let n = 2; primes.length < 64; n++) {
+	if (primes.every((p) => n % p !== 0)) primes.push(n);
+}
+const fraction = (x) => ((x - Math.floor(x)) * 2 ** 32) >>> 0;
+/** FIPS 180-4: the first 32 bits of the fractional parts of the primes' square and cube roots. */
+const INITIAL = primes.slice(0, 8).map((p) => fraction(Math.sqrt(p)));
+const ROUND = primes.map((p) => fraction(Math.cbrt(p)));
+
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+
+/** SHA-256 of a string's UTF-8 bytes, as lowercase hex. */
+export function sha256Hex(text) {
+	const bytes = new TextEncoder().encode(String(text));
+	const words = new Uint32Array(((bytes.length + 8) >> 6) * 16 + 16);
+	bytes.forEach((byte, i) => {
+		words[i >> 2] |= byte << (24 - (i % 4) * 8);
+	});
+	words[bytes.length >> 2] |= 0x80 << (24 - (bytes.length % 4) * 8);
+	words[words.length - 2] = Math.floor(bytes.length / 2 ** 29);
+	words[words.length - 1] = bytes.length * 8;
+
+	const hash = Uint32Array.from(INITIAL);
+	const w = new Uint32Array(64);
+	for (let block = 0; block < words.length; block += 16) {
+		for (let t = 0; t < 64; t++) {
+			if (t < 16) {
+				w[t] = words[block + t];
+				continue;
+			}
+			const a = w[t - 15];
+			const b = w[t - 2];
+			const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+			const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+			w[t] = w[t - 16] + s0 + w[t - 7] + s1;
+		}
+		let [a, b, c, d, e, f, g, h] = hash;
+		for (let t = 0; t < 64; t++) {
+			const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+			const t1 = (h + s1 + ((e & f) ^ (~e & g)) + ROUND[t] + w[t]) | 0;
+			const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+			const t2 = (s0 + ((a & b) ^ (a & c) ^ (b & c))) | 0;
+			[h, g, f, e, d, c, b, a] = [
+				g,
+				f,
+				e,
+				(d + t1) | 0,
+				c,
+				b,
+				a,
+				(t1 + t2) | 0,
+			];
+		}
+		[a, b, c, d, e, f, g, h].forEach((value, i) => {
+			hash[i] += value;
+		});
+	}
+	return Array.from(hash, (x) => x.toString(16).padStart(8, '0')).join('');
+}
+
+/**
+ * `email_sha256` for an address, now: trimmed, lowercased, hashed. Null for anything that is not an
+ * email, so a blank form field never becomes the hash of the empty string.
+ */
+export function emailSha256(email) {
+	if (typeof email !== 'string') return null;
+	const normalised = email.trim().toLowerCase();
+	return normalised.includes('@') ? sha256Hex(normalised) : null;
+}
+
+const rotl = (x, n) => (x << n) | (x >>> (32 - n));
+
+/**
+ * SHA-1 of bytes, as 20 bytes, synchronously. Only for name-based UUIDs (RFC 9562 version 5), which
+ * are defined over SHA-1; never for anything that must resist a collision.
+ */
+export function sha1(bytes) {
+	const words = new Uint32Array(((bytes.length + 8) >> 6) * 16 + 16);
+	bytes.forEach((byte, i) => {
+		words[i >> 2] |= byte << (24 - (i % 4) * 8);
+	});
+	words[bytes.length >> 2] |= 0x80 << (24 - (bytes.length % 4) * 8);
+	words[words.length - 2] = Math.floor(bytes.length / 2 ** 29);
+	words[words.length - 1] = bytes.length * 8;
+
+	const hash = Uint32Array.of(
+		0x67452301,
+		0xefcdab89,
+		0x98badcfe,
+		0x10325476,
+		0xc3d2e1f0,
+	);
+	const w = new Uint32Array(80);
+	for (let block = 0; block < words.length; block += 16) {
+		for (let t = 0; t < 80; t++) {
+			w[t] =
+				t < 16
+					? words[block + t]
+					: rotl(w[t - 3] ^ w[t - 8] ^ w[t - 14] ^ w[t - 16], 1);
+		}
+		let [a, b, c, d, e] = hash;
+		for (let t = 0; t < 80; t++) {
+			let f;
+			let k;
+			if (t < 20) {
+				f = (b & c) | (~b & d);
+				k = 0x5a827999;
+			} else if (t < 40) {
+				f = b ^ c ^ d;
+				k = 0x6ed9eba1;
+			} else if (t < 60) {
+				f = (b & c) | (b & d) | (c & d);
+				k = 0x8f1bbcdc;
+			} else {
+				f = b ^ c ^ d;
+				k = 0xca62c1d6;
+			}
+			const next = (rotl(a, 5) + f + e + k + w[t]) | 0;
+			[e, d, c, b, a] = [d, c, rotl(b, 30), a, next];
+		}
+		[a, b, c, d, e].forEach((value, i) => {
+			hash[i] += value;
+		});
+	}
+	const out = new Uint8Array(20);
+	hash.forEach((word, i) => {
+		out[i * 4] = word >>> 24;
+		out[i * 4 + 1] = word >>> 16;
+		out[i * 4 + 2] = word >>> 8;
+		out[i * 4 + 3] = word;
+	});
+	return out;
+}