@recapi/client 0.0.0-stage → 0.2.0

package/src/client.js

@@ -0,0 +1,678 @@
+/**
+ * The recapi client: local history, event batching, recommendations and
+ * automatic attribution.
+ *
+ * @module client
+ */
+
+import {
+  applyEvent,
+  decodeState,
+  emptyHistory,
+  encodeState,
+  fromSnapshot,
+  isEmpty,
+  isId,
+  merge,
+  mergeSnapshot,
+  resolveConfig,
+  toWire
+} from './history.js';
+import { createStore, defaultStorage, storageKey } from './storage.js';
+import { RecapiError, createTransport, defaultSleep, withRetry } from './transport.js';
+
+/**
+ * Attribution windows (README "Attribution"): an event on a shown item
+ * within 30 minutes of the display is the click from the widget, about one
+ * visit (Nosto, Clerk). Later the shopper has likely found the item some
+ * other way, so only a clicked item's events (cart, purchase) are
+ * attributed, for 24 hours after the click (Rebuy).
+ */
+const DISPLAY_WINDOW_MS = 30 * 60 * 1000;
+const CLICK_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Bounds the item→recommendation map so storage stays small on heavy pages. */
+const MAX_SHOWN_ITEMS = 500;
+/** Server limit for one `POST /v1/events`. */
+const MAX_EVENTS_PER_REQUEST = 1000;
+/** Upper bound for the flush delay after repeated failures (e.g. offline). */
+const MAX_FLUSH_BACKOFF_MS = 60000;
+/**
+ * How long `recommend()` waits before it falls back to popular items, and
+ * the fallback request after it. A widget above the fold that is still empty
+ * after 1.5 s has lost the shopper; the general `timeoutMs` (5 s) suits
+ * events, not that.
+ */
+const RECOMMEND_TIMEOUT_MS = 1500;
+/** Server defaults and limits for `count` (docs/api.md). */
+const DEFAULT_COUNT = 10;
+const MAX_COUNT = 100;
+/**
+ * Names for the recommended level scale (docs/api.md "Interaction levels"),
+ * so integrators don't have to learn the numbers. The API itself only
+ * takes integers; the name is resolved here.
+ */
+const LEVEL_NAMES = Object.freeze({ view: 3, cart: 5, purchase: 10, reject: -10 });
+/** The API's limit on a request's `exclude` list (docs/api.md). */
+const MAX_EXCLUDE = 500;
+/**
+ * Only a public key may travel in a URL: the API refuses a secret key from
+ * `?key=`, because URLs end up in proxy and CDN logs.
+ */
+const PUBLIC_KEY_PREFIX = 'rk_pub_';
+
+/**
+ * @typedef {import('./storage.js').StorageAdapter} StorageAdapter
+ * @typedef {import('./history.js').HistoryConfig} HistoryConfig
+ * @typedef {import('./history.js').HistoryState} HistoryState
+ * @typedef {import('./history.js').ServerSnapshot} ServerSnapshot
+ */
+
+/**
+ * @typedef {object} ClientOptions
+ * @property {string} apiKey Public key (`rk_pub_…`) in browsers.
+ * @property {string} baseUrl Your recapi API origin, e.g. `https://api.example.com`.
+ * @property {StorageAdapter} [storage] Defaults to localStorage, else memory.
+ * @property {string} [project] Storage namespace; defaults to the first 16
+ *   characters of the API key.
+ * @property {string} [placement] Default placement for `recommend()`.
+ * @property {number} [flushIntervalMs]
+ * @property {number} [maxBatch]
+ * @property {number} [timeoutMs] Per-request timeout.
+ * @property {Partial<HistoryConfig>} [historyConfig]
+ * @property {boolean} [consent] Initial storage consent (default `true`).
+ * @property {boolean} [respectDoNotTrack] Start without consent when the
+ *   browser sends Do Not Track or Global Privacy Control.
+ * @property {(error: unknown) => void} [onError] Receives background errors,
+ *   and the errors `recommend()` fell back from.
+ * @property {() => number} [now] Clock in unix ms.
+ * @property {typeof fetch} [fetch]
+ * @property {(ms: number) => Promise<void>} [sleep] Backoff sleep (tests).
+ */
+
+/**
+ * Creates a client. Nothing is sent until `track()`/`recommend()` is called.
+ *
+ * @param {ClientOptions} options
+ */
+export function createClient(options) {
+  const {
+    apiKey,
+    baseUrl,
+    placement: defaultPlacement,
+    flushIntervalMs = 2000,
+    timeoutMs = 5000,
+    now = Date.now,
+    sleep = defaultSleep
+  } = options ?? {};
+  if (typeof apiKey !== 'string' || !apiKey) throw new TypeError('apiKey is required');
+  if (typeof baseUrl !== 'string' || !baseUrl) throw new TypeError('baseUrl is required');
+  const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (typeof fetchImpl !== 'function') throw new TypeError('fetch is not available; pass options.fetch');
+
+  const maxBatch = Math.min(Math.max(1, options.maxBatch ?? 100), MAX_EVENTS_PER_REQUEST);
+  const maxQueue = Math.max(MAX_EVENTS_PER_REQUEST, maxBatch);
+  const config = resolveConfig(options.historyConfig);
+  const report = (error) => {
+    try {
+      options.onError?.(error);
+    } catch {
+      // A faulty error handler must not break tracking.
+    }
+  };
+  const transport = createTransport({ baseUrl, apiKey, fetch: fetchImpl, timeoutMs });
+  const store = createStore(
+    options.storage ?? defaultStorage(report),
+    storageKey(options.project ?? apiKey.slice(0, 16)),
+    decodePersisted,
+    report
+  );
+
+  let consent = options.consent ?? true;
+  if (options.respectDoNotTrack && doNotTrackEnabled()) consent = false;
+
+  /** @type {HistoryState} */
+  let history = emptyHistory();
+  let userId = null;
+  let anonId = null;
+  /**
+   * item id → [recommendation id, shown at, clicked at?]; insertion order =
+   * age, for eviction.
+   */
+  let shown = new Map();
+  /**
+   * Set once the history holds recapi's stored one (a snapshot), so it is
+   * merged only once, as in the server libraries: scores add up in a merge.
+   */
+  let restored = false;
+  const queue = [];
+  let chain = Promise.resolve();
+  let timer = null;
+  let failures = 0;
+  let destroyed = false;
+  /** False after a failed write: storage is then stale and memory is the truth. */
+  let synced = true;
+
+  if (consent) {
+    reload();
+    if (!anonId) {
+      anonId = uuid();
+      persist();
+    }
+  }
+
+  function reload() {
+    if (!synced) return;
+    const saved = store.load();
+    if (!saved) return;
+    ({ history, userId, anonId, restored } = saved);
+    shown = new Map(saved.shown);
+  }
+
+  function persist() {
+    if (!consent) return;
+    const t = now();
+    for (const [item, entry] of shown) if (!attributable(entry, t)) shown.delete(item);
+    synced = store.save({
+      anonId,
+      userId,
+      history: encodeState(history),
+      shown: [...shown].map(([item, entry]) => [item, ...entry]),
+      // Only when set: browsers (public keys) never get a snapshot.
+      restored: restored || undefined
+    });
+  }
+
+  /**
+   * Read-modify-write against storage so several tabs sharing localStorage
+   * build one history instead of overwriting each other's updates.
+   */
+  function mutate(fn) {
+    if (consent) reload();
+    fn();
+    persist();
+  }
+
+  /**
+   * The recommendation an event on `itemId` at `t` belongs to, if any. The
+   * first event above level 0 within the display window is the click on the
+   * item: it opens the click window and is stored with the entry.
+   */
+  function attributedRecommendation(itemId, level, t) {
+    const entry = shown.get(itemId);
+    if (!entry || !attributable(entry, t)) return undefined;
+    if (level > 0 && entry.length < 3) entry.push(t);
+    return entry[0];
+  }
+
+  function enqueue(event) {
+    queue.push(event);
+    if (queue.length > maxQueue) dropOverflow();
+    if (queue.length >= maxBatch) flush();
+    else schedule();
+  }
+
+  function dropOverflow() {
+    const dropped = queue.splice(0, queue.length - maxQueue).length;
+    report(new RecapiError('queue_overflow', `dropped ${dropped} oldest events`));
+  }
+
+  function schedule() {
+    if (timer || destroyed || !queue.length) return;
+    const delay = Math.min(flushIntervalMs * 2 ** failures, MAX_FLUSH_BACKOFF_MS);
+    timer = setTimeout(() => {
+      timer = null;
+      flush();
+    }, delay);
+    timer.unref?.();
+  }
+
+  /**
+   * Always keepalive, so a batch already in flight when the user navigates
+   * away still completes.
+   */
+  async function sendBatch(events, { retry }) {
+    const send = () => transport.request({ method: 'POST', path: '/v1/events', body: { events }, keepalive: true });
+    const response = retry ? await withRetry(send, { sleep }) : await send();
+    if (response?.rejected?.length) {
+      report(new RecapiError('event_rejected', `${response.rejected.length} event(s) rejected`, {
+        status: 202,
+        details: response.rejected.map((r) => ({ ...r, event: events[r.index] }))
+      }));
+    }
+  }
+
+  /** Puts a failed batch back at the head of the queue if it may succeed later. */
+  function handleSendError(error, events) {
+    report(error);
+    if (error instanceof RecapiError && error.retryable) {
+      queue.unshift(...events);
+      if (queue.length > maxQueue) dropOverflow();
+      return true;
+    }
+    return false;
+  }
+
+  async function drain() {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    while (queue.length) {
+      const events = queue.splice(0, maxBatch);
+      try {
+        await sendBatch(events, { retry: true });
+        failures = 0;
+      } catch (error) {
+        if (handleSendError(error, events)) {
+          failures++;
+          break;
+        }
+      }
+    }
+    schedule();
+  }
+
+  /**
+   * Sends everything immediately without retries, outside the serial chain:
+   * the page may be gone before a sleeping retry wakes up.
+   */
+  function flushOnHide() {
+    while (queue.length) {
+      const events = queue.splice(0, maxBatch);
+      sendBatch(events, { retry: false }).catch((error) => {
+        handleSendError(error, events);
+        schedule();
+      });
+    }
+  }
+
+  /**
+   * Sends all queued events. Never rejects: failures go to `onError`, and
+   * retryable batches stay queued for the next automatic flush.
+   *
+   * @returns {Promise<void>}
+   */
+  function flush() {
+    chain = chain.then(drain, drain);
+    return chain;
+  }
+
+  /** `POST /v1/recommendations`; remembers the shown items for attribution. */
+  async function personalised(params, deadline) {
+    if (consent) reload();
+    const wire = toWire(history, now(), config);
+    const sentEmpty = wire.history.length === 0;
+    const response = await transport.request({
+      method: 'POST',
+      path: '/v1/recommendations',
+      timeoutMs: deadline,
+      body: compact({
+        user_id: userId ?? undefined,
+        anon_id: anonId ?? undefined,
+        placement: params.placement ?? defaultPlacement,
+        count: params.count,
+        tags_any: params.tagsAny,
+        tags_all: params.tagsAll,
+        exclude: withRejected(params.exclude, wire.rejected),
+        context_item_id: params.contextItemId,
+        history: wire.history,
+        recent: wire.recent,
+        discovery: params.discovery
+      })
+    });
+    if (typeof response?.recommendation_id !== 'string' || !Array.isArray(response.items)) {
+      throw new RecapiError('invalid_response', 'malformed recommendations response');
+    }
+
+    const recommendationId = response.recommendation_id;
+    const items = response.items.map(({ item_id: itemId, score, slot }) => ({ itemId, score, slot }));
+    mutate(() => {
+      const t = now();
+      for (const { itemId } of items) {
+        shown.delete(itemId);
+        shown.set(itemId, [recommendationId, t]);
+      }
+      while (shown.size > MAX_SHOWN_ITEMS) shown.delete(shown.keys().next().value);
+      // A snapshot is only trusted when we sent nothing, and merged once: a
+      // concurrent first call (two placements on one page) may have merged
+      // it already. An empty one leaves the next one trusted. The local
+      // state is merged, never overwritten: it holds the events tracked
+      // while the request was in flight, and rejections the server may not
+      // have yet.
+      if (sentEmpty && response.history && !(restored && !isEmpty(history))) {
+        history = mergeSnapshot(history, fromSnapshot(response.history, config), t, config);
+        restored = true;
+      }
+    });
+    return { recommendationId, fallback: false, items };
+  }
+
+  /**
+   * Popular items standing in for a failed `recommend()`. The list keeps the
+   * requested length (a shorter one shifts the page) without the excluded
+   * items or the page's own product, so a few more are asked for. Nothing
+   * goes into the attribution map: there is no recommendation to credit.
+   */
+  async function popularFallback({ count, tagsAny, tagsAll, exclude, contextItemId }, deadline) {
+    // 0 is the default count for recommendations, but /v1/popular refuses it.
+    const n = count || DEFAULT_COUNT;
+    const skip = new Set(withRejected(exclude, toWire(history, now(), config).rejected));
+    if (contextItemId !== undefined) skip.add(contextItemId);
+    const items = await fetchPopular({ tagsAny, tagsAll, count: Math.min(n + skip.size, MAX_COUNT) }, deadline);
+    return items
+      .filter(({ item_id: itemId }) => !skip.has(itemId))
+      .slice(0, n)
+      .map(({ item_id: itemId, score }) => ({ itemId, score, slot: 'backfill' }));
+  }
+
+  /**
+   * `GET /v1/popular` for `popular()` and the fallback; `deadline` defaults
+   * to `timeoutMs`. A public key goes in the query string (CDN-cacheable, no
+   * CORS preflight); any other key in the header (Node with a secret key).
+   */
+  async function fetchPopular({ tagsAny, tagsAll, count }, deadline) {
+    const response = await transport.request({
+      method: 'GET',
+      path: '/v1/popular',
+      auth: apiKey.startsWith(PUBLIC_KEY_PREFIX) ? 'query' : 'header',
+      timeoutMs: deadline,
+      query: { tags_any: tagsAny?.join(','), tags_all: tagsAll?.join(','), count }
+    });
+    if (!Array.isArray(response?.items)) {
+      throw new RecapiError('invalid_response', 'malformed popular response');
+    }
+    return response.items;
+  }
+
+  const onVisibility = () => {
+    if (globalThis.document?.visibilityState === 'hidden') flushOnHide();
+  };
+  globalThis.document?.addEventListener?.('visibilitychange', onVisibility);
+  globalThis.window?.addEventListener?.('pagehide', flushOnHide);
+
+  return {
+    /**
+     * Records an interaction: updates the local history immediately (so the
+     * next `recommend()` reflects it) and queues the event. Level 0 is an
+     * impression: sent for statistics, never added to the history.
+     *
+     * @param {string} itemId
+     * @param {number | 'view' | 'cart' | 'purchase' | 'reject'} level Integer
+     *   -10–10, or the name of a level on the recommended scale (3, 5 and 10;
+     *   `reject` is -10). A negative level is an explicit rejection ("not
+     *   interested"): the item is never recommended to this user again until
+     *   a positive event on it. Don't send skips or bounces as rejections.
+     * @param {{ recommendationId?: string | null }} [options] Overrides the
+     *   automatic attribution. `null` (a fallback list's id) is no override.
+     */
+    track(itemId, level, { recommendationId: explicit } = {}) {
+      // A fallback list has a null id, and a page passing it on must not
+      // send `null` or lose the item's earlier, real attribution.
+      const recommendationId = explicit ?? undefined;
+      if (!isId(itemId)) throw new RecapiError('invalid_request', 'itemId must be 1-256 bytes of UTF-8 without control characters');
+      if (typeof level === 'string' && Object.hasOwn(LEVEL_NAMES, level)) level = LEVEL_NAMES[level];
+      if (!Number.isInteger(level) || level < -10 || level > 10) {
+        throw new RecapiError(
+          'invalid_request',
+          "level must be an integer between -10 and 10, or 'view', 'cart', 'purchase' or 'reject'"
+        );
+      }
+      const t = now();
+      let attributed = recommendationId;
+      mutate(() => {
+        if (level !== 0) history = applyEvent(history, { item: itemId, level, t }, config);
+        // An explicit id of the recommendation that showed the item is still
+        // the click on it; another id leaves the entry alone.
+        if (recommendationId === undefined || recommendationId === shown.get(itemId)?.[0]) {
+          attributed = attributedRecommendation(itemId, level, t) ?? recommendationId;
+        }
+      });
+      enqueue(compact({
+        item_id: itemId,
+        level,
+        user_id: userId ?? undefined,
+        anon_id: anonId ?? undefined,
+        recommendation_id: attributed,
+        timestamp: new Date(t).toISOString(),
+        event_id: uuid()
+      }));
+    },
+
+    /**
+     * Fetches personalised recommendations. Fails fast (no retry, at most
+     * 1.5 s). When recapi is unreachable, slow or failing (network error,
+     * timeout, 5xx), resolves with popular items instead, with `fallback:
+     * true` and no recommendation id, and reports the error to `onError`.
+     * When the popular request fails too (recapi is down), the list is
+     * empty: hide the slot. Other errors still reject: a 4xx is an
+     * integration bug or a tenant limit (429), and a fallback would hide it.
+     *
+     * @param {{ count?: number, tagsAny?: string[], tagsAll?: string[], exclude?: string[],
+     *   contextItemId?: string, placement?: string, discovery?: number }} [params]
+     * @returns {Promise<{ recommendationId: string | null, fallback: boolean,
+     *   items: Array<{ itemId: string, score: number, slot: string }> }>}
+     */
+    async recommend(params = {}) {
+      const deadline = Math.min(timeoutMs, RECOMMEND_TIMEOUT_MS);
+      try {
+        return await personalised(params, deadline);
+      } catch (error) {
+        if (!outage(error)) throw error;
+        report(error);
+        let items = [];
+        try {
+          items = await popularFallback(params, deadline);
+        } catch (fallbackError) {
+          // recapi is down altogether. The page awaits recommend() without a
+          // catch (the README says it may), so an empty list it can hide
+          // beats a rejection that breaks it.
+          report(fallbackError);
+        }
+        return { recommendationId: null, fallback: true, items };
+      }
+    },
+
+    /**
+     * Non-personalised popular items. A public key goes in the query string
+     * so the response is CDN-cacheable and the request needs no CORS
+     * preflight; a secret key stays in the `Authorization` header.
+     *
+     * @param {{ tagsAny?: string[], tagsAll?: string[], count?: number }} [params]
+     * @returns {Promise<{ items: Array<{ itemId: string, score: number }> }>}
+     */
+    async popular(params = {}) {
+      const items = await fetchPopular(params);
+      return { items: items.map(({ item_id: itemId, score }) => ({ itemId, score })) };
+    },
+
+    /**
+     * Attaches a user id to subsequent events and requests. The anonymous
+     * history is kept (it is this user's activity before login), but
+     * switching from one user id to another starts a fresh history.
+     *
+     * `options.history` takes a server snapshot (from
+     * `GET /v1/users/{id}/history`, fetched by your backend with the secret
+     * key) and merges it into the local history. Only pass a snapshot that
+     * does not already contain this device's events, or they count twice.
+     *
+     * @param {string} id
+     * @param {{ history?: ServerSnapshot }} [options]
+     */
+    identify(id, { history: snapshot } = {}) {
+      if (!isId(id)) throw new RecapiError('invalid_request', 'userId must be 1-256 bytes of UTF-8 without control characters');
+      mutate(() => {
+        if (userId && userId !== id) {
+          history = emptyHistory();
+          shown = new Map();
+          restored = false;
+        }
+        userId = id;
+        if (snapshot) {
+          history = mergeSnapshot(history, fromSnapshot(snapshot, config), now(), config);
+          restored = true;
+        }
+      });
+    },
+
+    /**
+     * Logout: forgets the user id, the history, attribution data and the
+     * anonymous id (a new one is generated). Already queued events keep the
+     * ids they were tracked with.
+     */
+    reset() {
+      history = emptyHistory();
+      userId = null;
+      shown = new Map();
+      restored = false;
+      anonId = consent ? uuid() : null;
+      persist();
+    },
+
+    /**
+     * Grants or withdraws consent for device storage (ePrivacy). Without
+     * consent nothing is read from or written to storage and no anonymous id
+     * exists; the history lives in memory for the current page only.
+     * Withdrawing deletes the stored data. Granting merges any previously
+     * stored history with the in-memory one.
+     *
+     * @param {boolean} value
+     */
+    setConsent(value) {
+      if (value === consent) return;
+      consent = Boolean(value);
+      if (!consent) {
+        store.remove();
+        anonId = null;
+        return;
+      }
+      const saved = store.load();
+      if (saved) {
+        history = merge(saved.history, history, now(), config);
+        restored ||= saved.restored;
+        userId = userId ?? saved.userId;
+        anonId = saved.anonId;
+        for (const [item, entry] of saved.shown) if (!shown.has(item)) shown.set(item, entry);
+      }
+      anonId = anonId ?? uuid();
+      persist();
+    },
+
+    flush,
+
+    /**
+     * The history exactly as the next recommendation request would send it;
+     * `rejected` goes into its `exclude`.
+     *
+     * @returns {{ history: Array<[string, number, number]>, recent: string[], rejected: string[] }}
+     */
+    getHistory() {
+      if (consent) reload();
+      return toWire(history, now(), config);
+    },
+
+    /**
+     * Removes listeners and timers, then flushes what is queued.
+     *
+     * @returns {Promise<void>}
+     */
+    destroy() {
+      destroyed = true;
+      if (timer) clearTimeout(timer);
+      timer = null;
+      globalThis.document?.removeEventListener?.('visibilitychange', onVisibility);
+      globalThis.window?.removeEventListener?.('pagehide', flushOnHide);
+      return flush();
+    }
+  };
+}
+
+/**
+ * Whether `recommend()` should fall back to popular items: recapi could not
+ * answer in time or failed on its side. A 429 is the tenant's own limit
+ * (`rate_limited` or `quota_exceeded`), not an outage, so it stays visible.
+ *
+ * @param {unknown} error
+ */
+function outage(error) {
+  return error instanceof RecapiError && (error.code === 'network' || error.code === 'timeout' || error.status >= 500);
+}
+
+/**
+ * Whether a shown-map entry still attributes events at `t`: within the
+ * display window until the item is clicked, then for the click window.
+ *
+ * @param {[string, number, number?]} entry [recommendation id, shown at, clicked at]
+ * @param {number} t
+ */
+function attributable([, shownAt, clickedAt], t) {
+  return clickedAt === undefined ? t - shownAt <= DISPLAY_WINDOW_MS : t - clickedAt <= CLICK_WINDOW_MS;
+}
+
+/**
+ * @param {any} raw Parsed JSON of unknown shape.
+ * @returns {{ history: HistoryState, userId: string | null, anonId: string,
+ *   shown: Array<[string, [string, number, number?]]>, restored: boolean } | null}
+ */
+function decodePersisted(raw) {
+  const history = decodeState(raw?.history);
+  if (!history || typeof raw.anonId !== 'string' || !Array.isArray(raw.shown)) return null;
+  if (raw.userId !== null && typeof raw.userId !== 'string') return null;
+  const shown = [];
+  for (const entry of raw.shown) {
+    if (!Array.isArray(entry) || typeof entry[0] !== 'string' || typeof entry[1] !== 'string' ||
+        !Number.isFinite(entry[2]) || (entry.length > 3 && !Number.isFinite(entry[3]))) {
+      return null;
+    }
+    // Entries without a click time are also the format of SDKs before the
+    // click window, so their storage keeps working.
+    if (isId(entry[0])) shown.push(/** @type {[string, [string, number, number?]]} */ ([entry[0], entry.slice(1, 4)]));
+  }
+  // Like the history's entries, a user id earlier SDKs let through but the
+  // API refuses is dropped, so requests work again (anonymously).
+  return { history, userId: isId(raw.userId) ? raw.userId : null, anonId: raw.anonId, shown, restored: raw.restored === true };
+}
+
+/**
+ * The caller's exclude list plus the rejected items, newest rejection first
+ * up to the API's limit. Unchanged when nothing was rejected.
+ *
+ * @param {string[] | undefined} exclude
+ * @param {string[]} rejected Oldest first.
+ */
+function withRejected(exclude, rejected) {
+  if (rejected.length === 0) return exclude;
+  const out = new Set(exclude);
+  for (let i = rejected.length - 1; i >= 0 && out.size < MAX_EXCLUDE; i--) out.add(rejected[i]);
+  return [...out];
+}
+
+function compact(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
+}
+
+function doNotTrackEnabled() {
+  const nav = globalThis.navigator;
+  return nav?.doNotTrack === '1' || nav?.globalPrivacyControl === true;
+}
+
+/**
+ * RFC 4122 v4 id. `crypto.randomUUID` needs a secure context (and Node 19+
+ * as a global), hence the fallbacks.
+ *
+ * @returns {string}
+ */
+export function uuid() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === 'function') {
+    try {
+      return c.randomUUID();
+    } catch {
+      // Insecure context: fall through.
+    }
+  }
+  const bytes = new Uint8Array(16);
+  if (typeof c?.getRandomValues === 'function') c.getRandomValues(bytes);
+  else for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}