@tokenoftrust/storefront-runner 2.2.69 → 2.2.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.69",
+  "version": "2.2.70",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/integration/consent-broker.ts

@@ -507,6 +507,7 @@ interface ViewerConsentWindow {
   localStorage?: {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
+    removeItem?(key: string): void;
   };
   document?: Document;
   addEventListener?: (type: string, listener: (event: { key?: string | null }) => void) => void;
@@ -649,6 +650,16 @@ export function applyEarlyViewerAnalyticsConsent(
         : rawEligible.includes(purpose)),
   );
   const approved = canonicalPurposes.filter((purpose) => rawApproved.includes(purpose));
+  // Analytics ineligible here (denial, GPC, tenant not approved) forgets this context's
+  // Amplitude visitor id and session before any adapter can run. The key is the
+  // native-amplitude.ts VISITOR_CONTINUITY_STORAGE_KEY prefix over the same contextKey.
+  if (!eligible.includes("analytics")) {
+    try {
+      win.localStorage?.removeItem?.(`tot.analytics-continuity.v1:${encodeURIComponent(contextKey)}`);
+    } catch {
+      // Storage denial leaves nothing readable to clear.
+    }
+  }
   win[consentGlobal] = Object.freeze({
     schemaVersion: 2,
     snapshotId: snapshotIdFor(eligible, approved),

package/packages/public-runtime/src/integration/lifecycle-boot.ts

@@ -42,6 +42,7 @@ import type { NavigationCompletedEvent, NavigationKind } from "./events.js";
 import { CommerceEventBroker } from "./commerce-broker.js";
 import { validateBrowserEnvironment, BROWSER_ENVIRONMENT_GLOBAL, type BrowserEnvironment } from "./environment.js";
 import { makePlatformAdapterRuntimeLoader } from "./platform-adapter-runtime.js";
+import { createVisitorContinuity, type VisitorContinuityStorage } from "./native-amplitude.js";
 import { resolveNativeGa4SandboxUrl, type NativeGa4Transport } from "./native-ga4.js";
 import {
   createBrowserNativeGa4SandboxHost,
@@ -138,6 +139,11 @@ export interface BootLifecycleOptions {
    * queued in the transport. Injectable so a test can hold the mount.
    */
   scheduleGa4Sandbox?: NativeGa4SandboxScheduler;
+  /**
+   * The persistent store behind the Amplitude visitor id and session; defaults to the
+   * window's origin storage. Read lazily and only while analytics is eligible.
+   */
+  visitorStorage?: () => VisitorContinuityStorage | undefined;
 }
 
 /**
@@ -431,6 +437,10 @@ export function bootIntegrationLifecycle(
     fetchCapability: hostFetch ? deferFetchCapability(hostFetch, schedulePlatformAdapterStart) : hostFetch,
     importModule: options.importModule,
     fallback: ordinaryLoader,
+    visitorContinuity: createVisitorContinuity({
+      storage: options.visitorStorage ??
+        (() => win["localStorage"] as VisitorContinuityStorage | undefined),
+    }),
     nativeGa4Transport: () => {
       if (options.nativeGa4Transport) return options.nativeGa4Transport;
       if (typeof document === "undefined" || typeof MessageChannel === "undefined") {

package/packages/public-runtime/src/integration/native-amplitude.ts

@@ -2,10 +2,22 @@
  * Storefront-owned Amplitude HTTP API v2 adapter.
  *
  * This module intentionally uses no vendor SDK or browser discovery surface. It
- * consumes only validated commerce-broker events and sends a closed, anonymous
- * payload to one exact collection endpoint. The fixed device value groups events
- * as non-identifying storefront traffic; it is never derived from a browser,
- * person, account, persisted client value, network address, or device signal.
+ * consumes only validated commerce-broker events and sends a closed payload to one
+ * exact collection endpoint.
+ *
+ * VISITOR CONTINUITY. `device_id` is a pseudonymous browser id and `session_id` the
+ * epoch-ms start of a 30-minute-inactivity session, both from `VisitorContinuity`
+ * below. The id is a random UUID — never derived from a person, account, network
+ * address, or device signal, never joined to identity-verification records — with a
+ * fixed 90-day lifetime (no sliding renewal). It is scoped to one tenant, environment
+ * and site surface, so two tenants sharing an origin get independent, unlinkable ids.
+ * It is read or minted only while analytics is eligible; an update into ineligibility
+ * clears it, and the renderer's early consent boot clears it on every load where
+ * analytics is ineligible (denial, Global Privacy Control, tenant not approved).
+ * Storage is injected by the host and never touched by name here; when it is
+ * unavailable the id lives in memory for this document only and the event carries
+ * no session (`NO_SESSION_ID`), overcounting visitors rather than failing the event.
+ * There is no `user_id`.
  *
  * Page views also carry channel ATTRIBUTION (UTM tokens + the referrer's origin)
  * and the page LOCATION (`page_hostname` / `page_url`, from the server-stamped
@@ -14,10 +26,7 @@
  * mappings apply unchanged. These are labels about the page and the campaign, not
  * about the visitor: attribution is minimized and validated upstream
  * (`events.ts` `validatePageAttribution`) and re-screened for PII here, and the
- * host never comes from the browser. A persistent/session identity is a different thing entirely —
- * it stays out, on purpose: `device_id` remains the fixed, non-identifying value
- * below and there is still no `session_id`, `user_id`, or any persisted client
- * value anywhere in this file.
+ * host never comes from the browser.
  */
 import type { CommerceEventBroker, CommerceEventSubscription } from "./commerce-broker.js";
 import {
@@ -52,7 +61,18 @@ export const AMPLITUDE_COLLECTION_URL = `${AMPLITUDE_COLLECTION_ORIGIN}/2/httpap
 export const AMPLITUDE_HTTP_ENTRY_URL = "/platform/amplitude-http/v1/entry.mjs" as const;
 export const AMPLITUDE_HTTP_ADAPTER_VERSION = "1.0.0" as const;
 export const AMPLITUDE_HTTP_RUNTIME_ID = "native-amplitude-http-v1" as const;
+/** Sent only when the browser offers no randomness to mint a visitor id from. */
 const ANONYMOUS_DEVICE_ID = "storefront-anonymous" as const;
+/** Amplitude's documented "not in a session" value. */
+export const NO_SESSION_ID = -1 as const;
+/**
+ * Storage key prefix for the visitor record. The early consent boot
+ * (`consent-broker.ts` `applyEarlyViewerAnalyticsConsent`) removes the same key as a
+ * literal; a test pins the two together.
+ */
+export const VISITOR_CONTINUITY_STORAGE_KEY = "tot.analytics-continuity.v1" as const;
+export const VISITOR_ID_LIFETIME_MS = 90 * 24 * 60 * 60 * 1000;
+export const SESSION_INACTIVITY_MS = 30 * 60 * 1000;
 export const AMPLITUDE_HTTP_EVENT_TYPES = Object.freeze([
   "storefront.page.viewed.v1",
   "storefront.page.viewed.v2",
@@ -79,7 +99,10 @@ export interface AmplitudePageLocationProperties {
 
 export interface AmplitudeHttpEvent {
   event_type: "page_view" | (typeof APPROVED_MARKETING_ACTION_NAMES)[number];
-  device_id: typeof ANONYMOUS_DEVICE_ID;
+  /** Pseudonymous visitor UUID, or the anonymous value when no randomness exists. */
+  device_id: string;
+  /** Session start, epoch milliseconds, or `NO_SESSION_ID`. */
+  session_id: number;
   insert_id: string;
   /** Occurrence time, epoch milliseconds. */
   time: number;
@@ -134,6 +157,141 @@ class BoundedInsertIds {
   }
 }
 
+/** The host-supplied persistent store; the browser host passes its own origin storage. */
+export interface VisitorContinuityStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/** The consent context a visitor id belongs to: the consent broker's `contextKey` triple. */
+export interface VisitorContinuityScope {
+  tenantPublicId: string;
+  environment: string;
+  siteSurface: string;
+}
+
+export interface VisitorContinuityIds {
+  deviceId: string;
+  sessionId: number;
+}
+
+export interface VisitorContinuity {
+  /** Read the scope's visitor, minting or rolling it as needed, and record activity at `now`. */
+  readOrMint(scope: VisitorContinuityScope, now: number): VisitorContinuityIds;
+  /** Forget the scope's visitor, persisted and in memory. */
+  clear(scope: VisitorContinuityScope): void;
+}
+
+export interface CreateVisitorContinuityOptions {
+  /** Absent, or returning undefined, keeps the visitor in memory for this document only. */
+  storage?: () => VisitorContinuityStorage | undefined;
+  randomUUID?: () => string;
+}
+
+interface VisitorRecord {
+  schemaVersion: 1;
+  deviceId: string;
+  createdAt: number;
+  sessionStartedAt: number;
+  lastActivityAt: number;
+}
+
+const VISITOR_RECORD_KEYS = "createdAt,deviceId,lastActivityAt,schemaVersion,sessionStartedAt";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export function visitorContinuityStorageKey(scope: VisitorContinuityScope): string {
+  const contextKey = `${scope.tenantPublicId}:${scope.environment}:${scope.siteSurface}`;
+  return `${VISITOR_CONTINUITY_STORAGE_KEY}:${encodeURIComponent(contextKey)}`;
+}
+
+/** A stored record that is malformed, from the future, or past its fixed lifetime is not a visitor. */
+function liveVisitorRecord(raw: string | null, now: number): VisitorRecord | null {
+  if (!raw) return null;
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { return null; }
+  if (!isPlainObject(parsed) || Object.keys(parsed).sort().join(",") !== VISITOR_RECORD_KEYS) return null;
+  const { schemaVersion, deviceId, createdAt, sessionStartedAt, lastActivityAt } = parsed;
+  if (
+    schemaVersion !== 1 || typeof deviceId !== "string" || !UUID_PATTERN.test(deviceId) ||
+    typeof createdAt !== "number" || typeof sessionStartedAt !== "number" ||
+    typeof lastActivityAt !== "number" ||
+    !Number.isFinite(createdAt) || !Number.isFinite(sessionStartedAt) || !Number.isFinite(lastActivityAt) ||
+    createdAt > now || now - createdAt >= VISITOR_ID_LIFETIME_MS ||
+    sessionStartedAt < createdAt || lastActivityAt < sessionStartedAt
+  ) return null;
+  return { schemaVersion, deviceId, createdAt, sessionStartedAt, lastActivityAt };
+}
+
+function defaultRandomUUID(): string {
+  return globalThis.crypto.randomUUID();
+}
+
+/**
+ * The visitor/session store behind `device_id` + `session_id`. Every storage access is
+ * guarded: a store that is missing, blocked, full, or throwing degrades to a
+ * memory-only id for this document with no session, and never fails the event.
+ */
+export function createVisitorContinuity(options: CreateVisitorContinuityOptions = {}): VisitorContinuity {
+  const randomUUID = options.randomUUID ?? defaultRandomUUID;
+  const memory = new Map<string, string>();
+  const storage = (): VisitorContinuityStorage | undefined => {
+    try { return options.storage?.(); } catch { return undefined; }
+  };
+  const mint = (): string | null => {
+    try {
+      const id = randomUUID().toLowerCase();
+      return UUID_PATTERN.test(id) ? id : null;
+    } catch {
+      return null;
+    }
+  };
+
+  return {
+    readOrMint(scope, now) {
+      const key = visitorContinuityStorageKey(scope);
+      const store = storage();
+      if (store) {
+        try {
+          const existing = liveVisitorRecord(store.getItem(key), now);
+          let record: VisitorRecord | null = existing;
+          if (!record) {
+            const deviceId = mint();
+            if (deviceId) {
+              record = { schemaVersion: 1, deviceId, createdAt: now, sessionStartedAt: now, lastActivityAt: now };
+            }
+          } else {
+            const sessionStartedAt = now - record.lastActivityAt > SESSION_INACTIVITY_MS
+              ? now
+              : record.sessionStartedAt;
+            record = { ...record, sessionStartedAt, lastActivityAt: Math.max(now, record.lastActivityAt) };
+          }
+          if (record) {
+            store.setItem(key, JSON.stringify(record));
+            memory.delete(key);
+            return { deviceId: record.deviceId, sessionId: record.sessionStartedAt };
+          }
+        } catch {
+          // Blocked or full storage: fall through to this document's memory-only visitor.
+        }
+      }
+      let deviceId = memory.get(key);
+      if (!deviceId) {
+        const minted = mint();
+        if (!minted) return { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID };
+        deviceId = minted;
+        memory.set(key, deviceId);
+      }
+      return { deviceId, sessionId: NO_SESSION_ID };
+    },
+    clear(scope) {
+      const key = visitorContinuityStorageKey(scope);
+      memory.delete(key);
+      try { storage()?.removeItem(key); } catch { /* the early consent boot clears on the next load */ }
+    },
+  };
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -187,7 +345,9 @@ function opaqueEventTime(epochMs: number): string {
 /**
  * Reduce a broker event to the complete Amplitude allowlist. Returning null is
  * fail-closed for unknown events, invalid/extra data, consent loss, environment
- * disagreement, unsafe paths, or unapproved action names.
+ * disagreement, unsafe paths, or unapproved action names. The result carries the
+ * anonymous identity; the sending handler replaces it with the visitor's ids only
+ * after the event is admitted, so a refused event never reads or mints one.
  */
 export function mapCommerceEventToAmplitude(
   input: unknown,
@@ -220,6 +380,7 @@ export function mapCommerceEventToAmplitude(
   if (!Number.isFinite(time)) return null;
   const base = {
     device_id: ANONYMOUS_DEVICE_ID,
+    session_id: NO_SESSION_ID,
     insert_id: `${eventDedupeKey(event)}-${opaqueEventTime(time)}`,
     time,
   };
@@ -255,6 +416,8 @@ export interface RegisterAmplitudeHttpDestinationInput {
   environment: BrowserEnvironment;
   fetch: AmplitudeFetch;
   onDiagnostic?: AmplitudeDiagnosticObserver;
+  /** Defaults to a memory-only store: one visitor per document, no session. */
+  continuity?: VisitorContinuity;
   /** Test seam; production is clamped to the fixed default. */
   dedupeCapacity?: number;
 }
@@ -277,15 +440,27 @@ interface AmplitudeHandlerInput {
   fetcher: AmplitudeFetch;
   observer?: AmplitudeDiagnosticObserver;
   dedupe: BoundedInsertIds;
+  continuity: VisitorContinuity;
   isActive(): boolean;
 }
 
+function continuityScope(tenantPublicId: string, environment: BrowserEnvironment): VisitorContinuityScope {
+  return { tenantPublicId, environment: environment.environment, siteSurface: environment.siteSurface };
+}
+
 function createAmplitudeHandler(input: AmplitudeHandlerInput): (event: CommerceEvent) => void {
+  const scope = continuityScope(input.tenantPublicId, input.environment);
   return (event) => {
     if (!input.isActive()) return;
     const mapped = mapCommerceEventToAmplitude(event, input.environment, input.tenantPublicId);
     if (!mapped || input.dedupe.seenOrRemember(mapped.insert_id)) return;
-    const body = JSON.stringify({ api_key: input.destinationId, events: [mapped] });
+    let identity: VisitorContinuityIds;
+    try { identity = input.continuity.readOrMint(scope, mapped.time); }
+    catch { identity = { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID }; }
+    const body = JSON.stringify({
+      api_key: input.destinationId,
+      events: [{ ...mapped, device_id: identity.deviceId, session_id: identity.sessionId }],
+    });
     try {
       void input.fetcher(AMPLITUDE_COLLECTION_URL, {
         method: "POST",
@@ -352,6 +527,7 @@ export function registerAmplitudeHttpDestination(
         fetcher,
         observer,
         dedupe,
+        continuity: input.continuity ?? createVisitorContinuity(),
         isActive: () => !disposed,
       }),
     },
@@ -372,6 +548,8 @@ export function registerAmplitudeHttpDestination(
 export interface CreateAmplitudeLifecycleModuleOptions {
   fetch?: AmplitudeFetch;
   onDiagnostic?: AmplitudeDiagnosticObserver;
+  /** The host's visitor store; defaults to memory-only (one visitor per document, no session). */
+  continuity?: VisitorContinuity;
   /** Narrow test seam; every value is clamped to a finite production ceiling. */
   dedupeCapacity?: number;
 }
@@ -390,6 +568,7 @@ export function createAmplitudeLifecycleModule(
   const fetcher: AmplitudeFetch = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
   const observer = options.onDiagnostic;
   const dedupe = new BoundedInsertIds(options.dedupeCapacity ?? AMPLITUDE_DEDUPE_CAPACITY);
+  const continuity = options.continuity ?? createVisitorContinuity();
   let state: AmplitudeLifecycleState = "idle";
   let generation = 0;
   let unsubscribe: (() => void) | undefined;
@@ -407,7 +586,8 @@ export function createAmplitudeLifecycleModule(
     }
   };
 
-  const bind = (ctx: IntegrationLifecycleContext): void => {
+  /** `clearIfIneligible`: an update that loses analytics eligibility forgets the visitor. */
+  const bind = (ctx: IntegrationLifecycleContext, clearIfIneligible: boolean): void => {
     let subscribe: IntegrationEventSubscribe | undefined;
     let environment: ReturnType<typeof validateBrowserEnvironment>;
     let destinationId: string | null;
@@ -415,6 +595,12 @@ export function createAmplitudeLifecycleModule(
       environment = validateBrowserEnvironment(ctx.environment);
       const eligible = ctx.consent.unknownState === "block" &&
         ctx.consent.eligiblePurposes.includes("analytics");
+      if (
+        !eligible && clearIfIneligible && environment.ok &&
+        typeof ctx.tenantPublicId === "string" && ctx.tenantPublicId.length > 0
+      ) {
+        continuity.clear(continuityScope(ctx.tenantPublicId, environment.value));
+      }
       subscribe = ctx.subscribe;
       destinationId = environment.ok
         ? soleDestinationId(ctx.config, environment.value.environment)
@@ -436,6 +622,7 @@ export function createAmplitudeLifecycleModule(
       fetcher,
       observer,
       dedupe,
+      continuity,
       isActive: () => state === "initialized" && generation === ownGeneration,
     });
     try {
@@ -456,12 +643,12 @@ export function createAmplitudeLifecycleModule(
     init(ctx) {
       if (state !== "idle") return;
       state = "initialized";
-      bind(ctx);
+      bind(ctx, false);
     },
     update(_reason, ctx) {
       if (state !== "initialized") return;
       if (!teardown()) return;
-      bind(ctx);
+      bind(ctx, true);
     },
     dispose() {
       if (state === "disposed") return;

package/packages/public-runtime/src/integration/platform-adapter-runtime.ts

@@ -15,6 +15,7 @@ import {
   AMPLITUDE_HTTP_ENTRY_URL,
   AMPLITUDE_HTTP_RUNTIME_ID,
   createAmplitudeLifecycleModule,
+  type VisitorContinuity,
 } from "./native-amplitude.js";
 import {
   createNativeGa4Module,
@@ -40,6 +41,8 @@ export interface PlatformAdapterEntryMarker {
 export interface PlatformAdapterRuntimeHost {
   fetch?: typeof fetch;
   nativeGa4Transport?: NativeGa4Transport;
+  /** The host's persistent visitor store for Amplitude; absent keeps visitors memory-only. */
+  visitorContinuity?: VisitorContinuity;
 }
 
 export interface PlatformAdapterRuntimeRegistration {
@@ -78,9 +81,9 @@ export const PLATFORM_ADAPTER_RUNTIME_REGISTRY: readonly PlatformAdapterRuntimeR
   }),
   Object.freeze({
     marker: AMPLITUDE_MARKER,
-    create: ({ fetch: fetchCapability }: PlatformAdapterRuntimeHost) => {
+    create: ({ fetch: fetchCapability, visitorContinuity }: PlatformAdapterRuntimeHost) => {
       if (!fetchCapability) throw new Error("platform_adapter_fetch_unavailable");
-      return createAmplitudeLifecycleModule({ fetch: fetchCapability });
+      return createAmplitudeLifecycleModule({ fetch: fetchCapability, continuity: visitorContinuity });
     },
   }),
 ]);
@@ -88,6 +91,7 @@ export const PLATFORM_ADAPTER_RUNTIME_REGISTRY: readonly PlatformAdapterRuntimeR
 export interface PlatformAdapterRuntimeLoaderOptions {
   fetchCapability?: typeof fetch;
   nativeGa4Transport?: () => NativeGa4Transport;
+  visitorContinuity?: VisitorContinuity;
   importModule?: (url: string) => Promise<unknown>;
   fallback: IntegrationModuleLoader;
 }
@@ -150,6 +154,9 @@ export function makePlatformAdapterRuntimeLoader(
       nativeGa4Transport: registration.marker.appId === GOOGLE_MEASUREMENT_ADAPTER.adapterId
         ? options.nativeGa4Transport?.()
         : undefined,
+      visitorContinuity: registration.marker.appId === AMPLITUDE_HTTP_ADAPTER.adapterId
+        ? options.visitorContinuity
+        : undefined,
     });
   };
 }