@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

package/packages/public-runtime/src/integration/interaction-tracking-gate.ts

@@ -0,0 +1,142 @@
+/**
+ * Consent + environment gate in front of interaction-tracking delivery
+ * (workstream `tot-storefront-declarative-tracking`, unit
+ * `dt-consent-environment-gate`).
+ *
+ * `interaction-tracking.ts`'s listener deliberately knows nothing about consent,
+ * environment, or tier — it hands every extracted {@link TotInteraction} straight
+ * to whatever `deliver` hook it was installed with. This module is that gate,
+ * wrapped IN FRONT of a caller-supplied `deliver`, never inside the listener:
+ *
+ *   - CONSENT: the `analytics` purpose must be eligible under the current
+ *     snapshot the neutral consent broker maintains
+ *     ({@link isPurposeEligible}, `consent-broker.ts`). A missing or tampered
+ *     `window.__TOT_INTEGRATION_CONSENT__` global fails closed to the
+ *     default-deny snapshot, same as every other consumer of that global
+ *     (`lifecycle-boot.ts`, the Cloudflare Web Analytics loader in
+ *     `Layout.astro`).
+ *   - ENVIRONMENT: the renderer-published four-stage environment
+ *     (`resolveBrowserEnvironment`, `environment.ts`) must resolve AND must not
+ *     be `candidate`. A per-change candidate render is a preview — it is never
+ *     live, and its clicks are not real interaction data, so they are never
+ *     delivered. An unresolved/invalid `window.__TOT_INTEGRATION_ENV__` global
+ *     fails closed exactly like an unresolved consent snapshot: no delivery.
+ *
+ * Both checks are read fresh on EVERY interaction, never cached at wrap time —
+ * so a later consent grant (a CMP update, a native banner decision) or a stage
+ * change is honored on the very next click with no rebinding, the same posture
+ * `managed-analytics-bridge.ts` documents for its own consent handling
+ * ("Consent changes are intentionally an in-place no-op for bridge lifecycle").
+ *
+ * This module does not deliver, batch, transport, or allowlist actions — that is
+ * `dt-collector-v1`'s job. It answers exactly one question: should this
+ * interaction reach the deliver hook at all?
+ */
+import type { InteractionDeliver, TotInteraction } from "../interaction-tracking.js";
+import {
+  defaultConsentSnapshot,
+  isPurposeEligible,
+  parseConsentSnapshot,
+  type ConsentSnapshot,
+} from "./consent-broker.js";
+import { INTEGRATION_CONSENT_GLOBAL } from "./render-phases.js";
+import {
+  validateBrowserEnvironment,
+  BROWSER_ENVIRONMENT_GLOBAL,
+  type BrowserEnvironment,
+} from "./environment.js";
+
+/** The consent purpose interaction tracking declares. A closed-vocabulary member. */
+export const INTERACTION_TRACKING_CONSENT_PURPOSE = "analytics";
+
+/**
+ * The narrow slice of `window` this gate reads — structural, so a test can pass a
+ * plain object instead of a real `window` and the gate stays edge-safe typed.
+ */
+export interface InteractionTrackingGateWindow {
+  [key: string]: unknown;
+}
+
+export interface InteractionTrackingGateOptions {
+  /**
+   * The window to read the consent/environment globals off. Defaults to the
+   * global `window` when present; off the browser (no global `window`, and none
+   * supplied) both reads resolve to their fail-closed defaults, so delivery is
+   * always denied rather than throwing.
+   */
+  win?: InteractionTrackingGateWindow;
+}
+
+function resolveWindow(win?: InteractionTrackingGateWindow): InteractionTrackingGateWindow | null {
+  if (win) return win;
+  return typeof window !== "undefined" ? (window as unknown as InteractionTrackingGateWindow) : null;
+}
+
+/** Read the current consent snapshot off the renderer-inlined global. Fail-closed default-deny. */
+function readConsentSnapshot(win: InteractionTrackingGateWindow | null): ConsentSnapshot {
+  return parseConsentSnapshot(win?.[INTEGRATION_CONSENT_GLOBAL]) ?? defaultConsentSnapshot();
+}
+
+/**
+ * Read the renderer-published environment. `null` when the global is
+ * absent/invalid — the same fail-closed posture `lifecycle-boot.ts` uses, except
+ * this gate has no descriptor-derived fallback to fall back to: an unresolved
+ * environment simply denies delivery.
+ */
+function readBrowserEnvironment(win: InteractionTrackingGateWindow | null): BrowserEnvironment | null {
+  const result = validateBrowserEnvironment(win?.[BROWSER_ENVIRONMENT_GLOBAL]);
+  return result.ok ? result.value : null;
+}
+
+/**
+ * Whether an interaction may be delivered RIGHT NOW: consent AND environment
+ * must both permit it.
+ *
+ *   - Consent: {@link INTERACTION_TRACKING_CONSENT_PURPOSE} must be eligible
+ *     under the live snapshot.
+ *   - Environment: must resolve, and must not be `"candidate"`.
+ *
+ * Exported standalone (in addition to {@link gateInteractionDelivery}) so a
+ * caller that needs the yes/no without wrapping a hook — e.g. a health/
+ * diagnostics assertion — can ask the same question the gate itself asks.
+ */
+export function isInteractionDeliveryPermitted(
+  options: InteractionTrackingGateOptions = {},
+): boolean {
+  const win = resolveWindow(options.win);
+  const consent = readConsentSnapshot(win);
+  if (!isPurposeEligible(consent, INTERACTION_TRACKING_CONSENT_PURPOSE)) return false;
+  const environment = readBrowserEnvironment(win);
+  if (!environment) return false;
+  return environment.environment !== "candidate";
+}
+
+/**
+ * Wrap a delivery hook with the consent+environment gate. The returned function
+ * has the exact {@link InteractionDeliver} shape `installInteractionTracking`
+ * and `onInteraction` expect, so it drops in wherever an unwrapped `deliver`
+ * would go:
+ *
+ * ```ts
+ * import { onInteraction, gateInteractionDelivery } from "@tot/public-runtime";
+ *
+ * onInteraction(gateInteractionDelivery((interaction) => {
+ *   // dt-collector-v1's transport — only ever called when consent AND
+ *   // environment both currently permit it.
+ * }));
+ * ```
+ *
+ * A gated-out interaction is silently dropped: `deliver` is simply never
+ * called for it, there is no error, no queuing, and no retry. `options.win`
+ * is read at CALL TIME (never captured once at wrap time), so gating tracks
+ * live consent/environment changes across the wrapped hook's whole lifetime.
+ */
+export function gateInteractionDelivery(
+  deliver: InteractionDeliver,
+  options: InteractionTrackingGateOptions = {},
+): InteractionDeliver {
+  return (interaction: TotInteraction): void => {
+    if (!isInteractionDeliveryPermitted(options)) return;
+    deliver(interaction);
+  };
+}

package/packages/public-runtime/src/interaction-tracking.ts

@@ -0,0 +1,364 @@
+/**
+ * Declarative interaction tracking — the attribute contract, its emit side, and
+ * the ONE delegated click listener that reads it.
+ *
+ * The contract is three attributes with three DIFFERENT stability properties,
+ * plus an explicit opt-out. Nothing here is inferred: no DOM-position
+ * heuristics, no id-prefix stripping, no derived defaults. A required field
+ * that is absent is a validation failure (chrome.ts) or a stamp-time throw
+ * ({@link InvalidTrackingStampError}) — never something papered over.
+ *
+ *   data-tot-el         IDENTITY.  This specific element. Assigned once,
+ *                       permanent, travels with the element through
+ *                       restructuring. A change here is drift = defect.
+ *   data-tot-action     ACTION / INTENT ("book-demo", "nav-pricing"). Stable,
+ *                       and deliberately SHARED across every placement of the
+ *                       same intent.
+ *   data-tot-placement  PLACEMENT / CONTEXT ("header", "hero", "footer",
+ *                       "mobile-menu"). Expected to change across redesigns; a
+ *                       change here is DATA, not drift. Emitted EXPLICITLY by
+ *                       the renderer — never inferred from DOM position or
+ *                       ancestry.
+ *
+ * Repeat containers carry the instance pair, resolved by nearest ancestor:
+ *   data-tot-scope      the repeat container ("nav-primary", "product-grid")
+ *   data-tot-i          the zero-based instance index within that scope
+ *
+ * OPT-OUT: `tracking: "none"` on a chrome item stamps NOTHING on the element —
+ * no `data-tot-el`, no action, no placement. ABSENCE is the signal; there is
+ * deliberately no sentinel value, because a sentinel would still match the
+ * listener's `[data-tot-el]` selector.
+ *
+ * PAYLOAD GUARDRAIL: this module never reads rendered content. No
+ * `textContent`, `innerText`, `innerHTML`, `alt`, `title`, `value`,
+ * `placeholder`, and no form-field reads — only `getAttribute` and `closest`
+ * against the declared attributes above. Machine-enforced by a source sweep in
+ * tests/interaction-tracking.test.ts, so the guarantee survives edits.
+ *
+ * Full contract, including how downstream units plug in:
+ *   docs/declarative-interaction-tracking-contract.md
+ */
+
+// ---------------------------------------------------------------------------
+// The attribute names — one source of truth for every emitter and reader.
+// ---------------------------------------------------------------------------
+
+export const TRACKING_ATTR_EL = "data-tot-el";
+export const TRACKING_ATTR_ACTION = "data-tot-action";
+export const TRACKING_ATTR_PLACEMENT = "data-tot-placement";
+export const TRACKING_ATTR_SCOPE = "data-tot-scope";
+export const TRACKING_ATTR_INDEX = "data-tot-i";
+
+/** The DOM event the installed listener dispatches when given no `deliver` hook. */
+export const TOT_INTERACTION_EVENT = "tot:interaction";
+
+// ---------------------------------------------------------------------------
+// Declaration — the authored half of the contract.
+// ---------------------------------------------------------------------------
+
+/**
+ * An element either declares a tracked ACTION or explicitly opts out. The union
+ * makes "neither" and "both" unrepresentable in TypeScript; `validateTracking`
+ * is the runtime oracle for authored JSON, which TypeScript never sees.
+ */
+export type TrackingDeclaration =
+  | { action: string; tracking?: undefined }
+  | { action?: undefined; tracking: "none" };
+
+/** Everything the renderer must know to stamp one element. */
+export interface TrackingStamp {
+  /** IDENTITY — assigned once, permanent. */
+  el: string;
+  /** ACTION / INTENT — shared across placements. Absent iff opted out. */
+  action?: string | undefined;
+  /** Explicit opt-out. When "none", NOTHING is stamped. */
+  tracking?: "none" | undefined;
+  /** PLACEMENT / CONTEXT — always passed explicitly by the renderer. */
+  placement: string;
+  /** Repeat-container identity, when this element sits in one. */
+  scope?: string | undefined;
+  /** Zero-based instance index within `scope`. */
+  index?: number | undefined;
+}
+
+/**
+ * Thrown when a renderer asks to stamp an element without the fields the
+ * contract requires. Fails closed at render time with an actionable message
+ * rather than emitting a partial, un-analyzable element — a missing `el`,
+ * `action`, or `placement` is a bug in the caller, not a degraded-but-safe
+ * state.
+ */
+export class InvalidTrackingStampError extends Error {
+  constructor(message: string) {
+    super(
+      `${message} — declarative interaction tracking requires an explicit ${TRACKING_ATTR_EL} ` +
+        `(identity), ${TRACKING_ATTR_ACTION} (intent) and ${TRACKING_ATTR_PLACEMENT} (context) on ` +
+        `every tracked element, or \`tracking: "none"\` to stamp nothing at all. There is no derived ` +
+        `default and no inference from DOM position.`,
+    );
+    this.name = "InvalidTrackingStampError";
+  }
+}
+
+function nonEmpty(v: unknown): v is string {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+/**
+ * The attributes to stamp on one element, or `{}` when the element opted out.
+ * The single emit path for every renderer — component-rendered chrome and
+ * string-built chrome alike — so no path can invent its own attribute set.
+ */
+export function trackingAttributes(stamp: TrackingStamp): Record<string, string> {
+  if (stamp.tracking === "none") {
+    if (nonEmpty(stamp.action)) {
+      throw new InvalidTrackingStampError(
+        `${JSON.stringify(stamp.el)} declares both an \`action\` and \`tracking: "none"\``,
+      );
+    }
+    return {};
+  }
+  if (!nonEmpty(stamp.el)) throw new InvalidTrackingStampError("a tracked element has no `el` identity");
+  if (!nonEmpty(stamp.action)) {
+    throw new InvalidTrackingStampError(`${JSON.stringify(stamp.el)} has no \`action\``);
+  }
+  if (!nonEmpty(stamp.placement)) {
+    throw new InvalidTrackingStampError(`${JSON.stringify(stamp.el)} has no \`placement\``);
+  }
+  const attrs: Record<string, string> = {
+    [TRACKING_ATTR_EL]: stamp.el,
+    [TRACKING_ATTR_ACTION]: stamp.action,
+    [TRACKING_ATTR_PLACEMENT]: stamp.placement,
+  };
+  if (nonEmpty(stamp.scope)) attrs[TRACKING_ATTR_SCOPE] = stamp.scope;
+  if (stamp.index !== undefined) {
+    if (!Number.isInteger(stamp.index) || stamp.index < 0) {
+      throw new InvalidTrackingStampError(`${JSON.stringify(stamp.el)} has a non-integer \`index\``);
+    }
+    attrs[TRACKING_ATTR_INDEX] = String(stamp.index);
+  }
+  return attrs;
+}
+
+function escAttr(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/**
+ * {@link trackingAttributes} serialized for the string-building renderers
+ * (rawChrome.ts). Returns "" for an opted-out element, otherwise a
+ * LEADING-SPACE-prefixed attribute run ready to splice inside a start tag.
+ */
+export function trackingAttributesHtml(stamp: TrackingStamp): string {
+  const attrs = trackingAttributes(stamp);
+  return Object.keys(attrs)
+    .map((name) => ` ${name}="${escAttr(attrs[name] as string)}"`)
+    .join("");
+}
+
+/**
+ * Validate the tracking half of one authored chrome item: EXACTLY ONE of a
+ * non-empty `action` or `tracking: "none"`. Neither is a failure (an item
+ * nobody declared an intent for is un-analyzable); both is a failure (the
+ * author contradicted themselves). Push-into-`errors` shape so it composes
+ * with chrome.ts's collect-every-violation validators.
+ */
+export function validateTracking(v: Record<string, unknown>, path: string, errors: string[]): void {
+  const hasAction = nonEmpty(v.action);
+  const optedOut = v.tracking === "none";
+  if (v.action !== undefined && !hasAction) {
+    errors.push(`${path}.action: must be a non-empty string`);
+  }
+  if (v.tracking !== undefined && !optedOut) {
+    errors.push(`${path}.tracking: the only accepted value is "none"`);
+  }
+  if (hasAction && optedOut) {
+    errors.push(
+      `${path}: declares both \`action\` and \`tracking: "none"\` — an element is either tracked ` +
+        `under one stable intent or explicitly untracked, never both`,
+    );
+  }
+  if (!hasAction && !optedOut && v.tracking === undefined) {
+    errors.push(
+      `${path}.action: required, non-empty string — the stable ACTION/INTENT this element performs ` +
+        `(e.g. "book-demo", "nav-pricing"), shared across every placement of that intent. Set ` +
+        `\`"tracking": "none"\` instead to stamp nothing on this element.`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Read side — the ONE delegated click listener.
+// ---------------------------------------------------------------------------
+
+/** What the listener extracts. Attribute values only; never rendered content. */
+export interface TotInteraction {
+  /** The interaction kind. Only "click" exists in V1. */
+  type: "click";
+  /** `data-tot-el` — the element's permanent identity. */
+  el: string;
+  /** `data-tot-action`, or null when the element carries no action attribute. */
+  action: string | null;
+  /** `data-tot-placement`, or null when unstamped. */
+  placement: string | null;
+  /** `data-tot-scope` from the nearest ancestor repeat container, else null. */
+  scope: string | null;
+  /** `data-tot-i` from the nearest ancestor carrying it, else null. */
+  index: number | null;
+}
+
+/** The delivery hook. Downstream units supply this; this module never delivers. */
+export type InteractionDeliver = (interaction: TotInteraction) => void;
+
+/** A node as this module reads it: declared attributes and ancestor lookup only. */
+export interface TrackingNode {
+  getAttribute?(name: string): string | null;
+  closest?(selector: string): TrackingNode | null;
+}
+
+/** The event target the listener attaches to (`document` in a browser). */
+export interface InteractionTarget {
+  addEventListener(type: string, handler: (event: unknown) => void, capture?: boolean): void;
+  removeEventListener(type: string, handler: (event: unknown) => void, capture?: boolean): void;
+  dispatchEvent?(event: unknown): unknown;
+  /** Install-once marker, so the three injection paths can all install safely. */
+  __totInteractionTracking?: boolean;
+}
+
+/**
+ * The listener itself. SELF-CONTAINED by construction: it references no
+ * module-scope binding, so {@link INTERACTION_TRACKING_BOOT_JS} can serialize it
+ * verbatim for the string-injection render paths and there is exactly ONE
+ * implementation of the read side in the repo. Type annotations are erased at
+ * build time and are therefore free.
+ *
+ * Keep it that way — a reference to an outer constant would survive
+ * minification as a mangled, undefined name in the serialized copy. The
+ * duplicated attribute-name literals are pinned to the exported constants by a
+ * test.
+ */
+function interactionTrackingBoot(
+  deliver: InteractionDeliver | null,
+  target: InteractionTarget | null,
+): () => void {
+  const noop = function (): void {};
+  if (!target || typeof target.addEventListener !== "function") return noop;
+  if (target.__totInteractionTracking) return noop;
+  target.__totInteractionTracking = true;
+
+  const EL = "data-tot-el";
+  const ACTION = "data-tot-action";
+  const PLACEMENT = "data-tot-placement";
+  const SCOPE = "data-tot-scope";
+  const INDEX = "data-tot-i";
+  const EVENT = "tot:interaction";
+
+  const attr = function (node: TrackingNode | null, name: string): string | null {
+    return node && typeof node.getAttribute === "function" ? node.getAttribute(name) : null;
+  };
+  // Nearest ancestor-or-self carrying `name`. A tracked CTA commonly wraps child
+  // markup (an icon, a nested span), so the click target is often NOT the
+  // tracked element — closest-match, never exact-target-only.
+  const nearest = function (node: TrackingNode | null, name: string): TrackingNode | null {
+    return node && typeof node.closest === "function" ? node.closest("[" + name + "]") : null;
+  };
+
+  const handler = function (event: unknown): void {
+    const origin = (event ? (event as { target?: TrackingNode | null }).target : null) ?? null;
+    const el = nearest(origin, EL);
+    const id = attr(el, EL);
+    // No identity anywhere up the ancestor chain: nothing to report.
+    if (!el || !id) return;
+    const rawIndex = attr(nearest(el, INDEX), INDEX);
+    const parsedIndex = rawIndex === null || rawIndex.trim() === "" ? Number.NaN : Number(rawIndex);
+    const interaction: TotInteraction = {
+      type: "click",
+      el: id,
+      action: attr(el, ACTION),
+      placement: attr(el, PLACEMENT),
+      scope: attr(nearest(el, SCOPE), SCOPE),
+      index: Number.isInteger(parsedIndex) ? parsedIndex : null,
+    };
+    if (typeof deliver === "function") {
+      deliver(interaction);
+      return;
+    }
+    if (typeof target.dispatchEvent === "function" && typeof CustomEvent === "function") {
+      target.dispatchEvent(new CustomEvent(EVENT, { detail: interaction }));
+    }
+  };
+
+  // Capture phase: a tracked click still reports even when intervening markup
+  // calls stopPropagation().
+  target.addEventListener("click", handler, true);
+  return function (): void {
+    target.removeEventListener("click", handler, true);
+    target.__totInteractionTracking = false;
+  };
+}
+
+/**
+ * Install the delegated click listener on `target` (default: `document`).
+ * Idempotent — the second install on the same target is a no-op, which is what
+ * lets all three render paths install unconditionally.
+ *
+ * `deliver` is the ONLY extension point: consent gating, environment gating,
+ * ingest allowlisting and transport all live in the hook's implementation
+ * (other units), never here. Omit it and each interaction is dispatched as a
+ * {@link TOT_INTERACTION_EVENT} CustomEvent instead, which is how the
+ * string-injected render paths hand off.
+ *
+ * @returns an uninstall function.
+ */
+export function installInteractionTracking(
+  options: { deliver?: InteractionDeliver; target?: InteractionTarget } = {},
+): () => void {
+  const target =
+    options.target ??
+    (typeof document !== "undefined" ? (document as unknown as InteractionTarget) : null);
+  return interactionTrackingBoot(options.deliver ?? null, target);
+}
+
+/**
+ * Subscribe to interactions delivered as {@link TOT_INTERACTION_EVENT} events —
+ * the hand-off for code that cannot pass a `deliver` hook at install time
+ * (anything running on a string-injected page). Returns an unsubscribe function.
+ */
+export function onInteraction(
+  handler: InteractionDeliver,
+  target?: InteractionTarget,
+): () => void {
+  const t =
+    target ?? (typeof document !== "undefined" ? (document as unknown as InteractionTarget) : null);
+  if (!t || typeof t.addEventListener !== "function") return () => {};
+  const listener = (event: unknown): void => {
+    const detail = (event as { detail?: TotInteraction } | null)?.detail;
+    if (detail) handler(detail);
+  };
+  t.addEventListener(TOT_INTERACTION_EVENT, listener);
+  return () => t.removeEventListener(TOT_INTERACTION_EVENT, listener);
+}
+
+/**
+ * {@link interactionTrackingBoot}'s own compiled source — the anchor that makes
+ * "one implementation, every render path" checkable: the imported path calls the
+ * function, the string-injected paths embed exactly this text. Exported so a
+ * test can evaluate the serialized copy and assert it behaves identically to the
+ * imported one.
+ */
+export const INTERACTION_TRACKING_LISTENER_SOURCE = String(interactionTrackingBoot);
+
+/**
+ * The listener as an inline `<script>` body, for the render paths that build
+ * HTML as strings and have no module graph to import from. Serialized from
+ * {@link interactionTrackingBoot} itself, so the string-injected paths and the
+ * imported path can never drift apart.
+ *
+ * Contains no `</script>` sequence, and is safe to embed more than once per
+ * document (the install-once marker makes the later copies no-ops).
+ */
+export const INTERACTION_TRACKING_BOOT_JS = `(${INTERACTION_TRACKING_LISTENER_SOURCE})(null, typeof document !== "undefined" ? document : null);`;