@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/packages/public-runtime/src/integration/events-catalog.ts

@@ -0,0 +1,186 @@
+/**
+ * The owner / purpose / sensitivity catalog and retention classes for the
+ * canonical commerce event contract (`./events.ts`).
+ *
+ * Every field a commerce event can carry has an entry here. The catalog is not
+ * decoration: the contract test asserts it covers EXACTLY the closed field set
+ * the validators enforce, so a field cannot exist without a declared owner,
+ * purpose, and sensitivity — that is what makes "every field has owner/purpose/
+ * sensitivity" a checkable property rather than a promise.
+ *
+ * Retention is a per-type CLASS, not a per-event field: browser telemetry is
+ * short-lived, correlation-bearing handoff data lives for the attribution window,
+ * and server-authoritative order events are financial records retained for
+ * reconciliation and compliance.
+ */
+import { COMMERCE_EVENT_TYPES, COMMERCE_EVENT_DATA_FIELDS } from "./events.js";
+import type { CommerceEventType } from "./events.js";
+
+/**
+ * Who sets a field:
+ *   - `platform` — stamped by the renderer/server from trusted context; a caller
+ *     cannot set or forge it.
+ *   - `emitter`  — supplied by the event producer, constrained to the allowlist.
+ */
+export type EventFieldOwner = "platform" | "emitter";
+
+/**
+ * How exposed a field's value is:
+ *   - `public`        — safe for any eligible destination; carries no personal data.
+ *   - `pseudonymous`  — opaque identifier; must not be used alone as a cross-site
+ *                       tracking key.
+ *   - `consent-gated` — measurement data deliverable only where the referenced
+ *                       consent snapshot permits the purpose.
+ *   - `server-owned`  — trusted-context fact (tenant/environment/surface/emitter);
+ *                       authoritative, never caller-settable.
+ */
+export type EventFieldSensitivity = "public" | "pseudonymous" | "consent-gated" | "server-owned";
+
+export interface CommerceEventFieldDescriptor {
+  path: string;
+  owner: EventFieldOwner;
+  purpose: string;
+  sensitivity: EventFieldSensitivity;
+}
+
+/** Envelope fields shared by every commerce event (CloudEvents core + server-owned context + refs). */
+export const COMMERCE_EVENT_ENVELOPE_CATALOG: readonly CommerceEventFieldDescriptor[] = [
+  { path: "specversion", owner: "platform", purpose: "CloudEvents envelope version.", sensitivity: "public" },
+  { path: "id", owner: "platform", purpose: "Opaque logical event identity; the dedupe/idempotency key across client and server delivery.", sensitivity: "pseudonymous" },
+  { path: "source", owner: "platform", purpose: "URN of the emitting storefront surface.", sensitivity: "public" },
+  { path: "type", owner: "emitter", purpose: "Semantic versioned event type from the reserved taxonomy.", sensitivity: "public" },
+  { path: "subject", owner: "emitter", purpose: "Opaque in-event subject (e.g. an anonymous cart/item-set handle).", sensitivity: "pseudonymous" },
+  { path: "time", owner: "platform", purpose: "Occurrence timestamp for ordering and windowing.", sensitivity: "public" },
+  { path: "datacontenttype", owner: "platform", purpose: "Fixed application/json payload encoding.", sensitivity: "public" },
+  { path: "dataschema", owner: "platform", purpose: "Optional URI of the versioned data schema.", sensitivity: "public" },
+  { path: "storefront.schemaVersion", owner: "platform", purpose: "Pinned storefront-context schema version; unknown fails closed.", sensitivity: "public" },
+  { path: "storefront.tenant", owner: "platform", purpose: "Public tenant id; scopes the event and blocks cross-tenant joins.", sensitivity: "server-owned" },
+  { path: "storefront.environment", owner: "platform", purpose: "Stage (local/candidate/staged/live) so non-live never reaches live destinations.", sensitivity: "server-owned" },
+  { path: "storefront.siteSurface", owner: "platform", purpose: "Document surface the event originated on.", sensitivity: "server-owned" },
+  { path: "storefront.emitter", owner: "platform", purpose: "Delivery channel of this instance; enforces server-only authorship of conversions.", sensitivity: "server-owned" },
+  { path: "storefront.sequence", owner: "platform", purpose: "Optional per-emitter monotonic counter for out-of-order detection.", sensitivity: "public" },
+  { path: "correlation.id", owner: "platform", purpose: "Bounded-lifetime attribution thread spanning handoff and verified order.", sensitivity: "pseudonymous" },
+  { path: "correlation.expiresAt", owner: "platform", purpose: "Correlation validity bound; an expired thread cannot attribute.", sensitivity: "public" },
+  { path: "consent.schemaVersion", owner: "platform", purpose: "Pinned consent-snapshot schema version; unknown fails closed.", sensitivity: "public" },
+  { path: "consent.snapshotId", owner: "platform", purpose: "Reference to the consent snapshot the payload was filtered against.", sensitivity: "pseudonymous" },
+  { path: "consent.eligiblePurposes", owner: "platform", purpose: "Purposes permitted at emit time; destinations filter by these.", sensitivity: "public" },
+];
+
+/** Per-type `data` field descriptors. Keyed paths are `data.<field>`. */
+export const COMMERCE_EVENT_DATA_CATALOG: Record<
+  CommerceEventType,
+  readonly CommerceEventFieldDescriptor[]
+> = {
+  "storefront.page.viewed.v1": [
+    { path: "data.path", owner: "emitter", purpose: "Viewed route path for pageview measurement.", sensitivity: "consent-gated" },
+    { path: "data.title", owner: "emitter", purpose: "Optional document title for reporting.", sensitivity: "consent-gated" },
+  ],
+  "storefront.page.viewed.v2": [
+    { path: "data.path", owner: "emitter", purpose: "Root-relative viewed route path without query or fragment.", sensitivity: "consent-gated" },
+    { path: "data.attribution", owner: "emitter", purpose: "Optional minimized referrer-origin and UTM object; never a full URL or browser state.", sensitivity: "consent-gated" },
+  ],
+  "storefront.action.activated.v1": [
+    { path: "data.name", owner: "emitter", purpose: "Stable semantic action name from the tenant's explicit action registry.", sensitivity: "consent-gated" },
+  ],
+  "storefront.product.viewed.v1": [
+    { path: "data.productId", owner: "emitter", purpose: "Public catalog product identifier.", sensitivity: "consent-gated" },
+    { path: "data.variantId", owner: "emitter", purpose: "Optional public variant identifier.", sensitivity: "consent-gated" },
+    { path: "data.listId", owner: "emitter", purpose: "Optional source list/collection for merchandising analysis.", sensitivity: "consent-gated" },
+    { path: "data.position", owner: "emitter", purpose: "Optional position within the list.", sensitivity: "consent-gated" },
+    { path: "data.currency", owner: "emitter", purpose: "Optional ISO currency for value context.", sensitivity: "consent-gated" },
+    { path: "data.unitPrice", owner: "emitter", purpose: "Optional decimal unit price for value context.", sensitivity: "consent-gated" },
+  ],
+  "storefront.cart.item_added.v1": [
+    { path: "data.productId", owner: "emitter", purpose: "Public catalog product identifier.", sensitivity: "consent-gated" },
+    { path: "data.variantId", owner: "emitter", purpose: "Optional public variant identifier.", sensitivity: "consent-gated" },
+    { path: "data.quantity", owner: "emitter", purpose: "Units added.", sensitivity: "consent-gated" },
+    { path: "data.unitPrice", owner: "emitter", purpose: "Optional decimal unit price.", sensitivity: "consent-gated" },
+    { path: "data.currency", owner: "emitter", purpose: "Optional ISO currency.", sensitivity: "consent-gated" },
+  ],
+  "storefront.cart.item_removed.v1": [
+    { path: "data.productId", owner: "emitter", purpose: "Public catalog product identifier.", sensitivity: "consent-gated" },
+    { path: "data.variantId", owner: "emitter", purpose: "Optional public variant identifier.", sensitivity: "consent-gated" },
+    { path: "data.quantity", owner: "emitter", purpose: "Units removed.", sensitivity: "consent-gated" },
+    { path: "data.unitPrice", owner: "emitter", purpose: "Optional decimal unit price.", sensitivity: "consent-gated" },
+    { path: "data.currency", owner: "emitter", purpose: "Optional ISO currency.", sensitivity: "consent-gated" },
+  ],
+  "storefront.cart.updated.v1": [
+    { path: "data.currency", owner: "emitter", purpose: "ISO currency of the cart total.", sensitivity: "consent-gated" },
+    { path: "data.value", owner: "emitter", purpose: "Decimal cart value for measurement.", sensitivity: "consent-gated" },
+    { path: "data.itemCount", owner: "emitter", purpose: "Total units in the cart.", sensitivity: "consent-gated" },
+    { path: "data.items", owner: "emitter", purpose: "Anonymous line items (product/variant/quantity/unitPrice).", sensitivity: "consent-gated" },
+  ],
+  "storefront.checkout.handoff.v1": [
+    { path: "data.currency", owner: "emitter", purpose: "ISO currency at handoff.", sensitivity: "consent-gated" },
+    { path: "data.value", owner: "emitter", purpose: "Decimal cart value handed off.", sensitivity: "consent-gated" },
+    { path: "data.itemCount", owner: "emitter", purpose: "Total units handed off.", sensitivity: "consent-gated" },
+    { path: "data.items", owner: "emitter", purpose: "Anonymous line items handed to the provider correlation.", sensitivity: "consent-gated" },
+  ],
+  "storefront.purchase.completed.v1": [
+    { path: "data.currency", owner: "emitter", purpose: "ISO currency of the completed purchase, for post-purchase measurement.", sensitivity: "consent-gated" },
+    { path: "data.value", owner: "emitter", purpose: "Decimal purchase value (anonymous analytics signal, not the authoritative order total).", sensitivity: "consent-gated" },
+    { path: "data.itemCount", owner: "emitter", purpose: "Total units in the completed purchase.", sensitivity: "consent-gated" },
+    { path: "data.items", owner: "emitter", purpose: "Anonymous line items (product/variant/quantity/unitPrice); no order id, identity, or payment data.", sensitivity: "consent-gated" },
+  ],
+  "storefront.consent.changed.v1": [
+    { path: "data.eligiblePurposes", owner: "emitter", purpose: "Purposes after the change; drives downstream eligibility.", sensitivity: "public" },
+    { path: "data.previousPurposes", owner: "emitter", purpose: "Optional prior purposes for diffing.", sensitivity: "public" },
+  ],
+  "storefront.order.created.v1": [
+    { path: "data.orderId", owner: "platform", purpose: "Provider external order id; server-authoritative conversion key.", sensitivity: "pseudonymous" },
+    { path: "data.currency", owner: "platform", purpose: "ISO currency of the order.", sensitivity: "public" },
+    { path: "data.value", owner: "platform", purpose: "Decimal order total.", sensitivity: "public" },
+    { path: "data.itemCount", owner: "platform", purpose: "Total units ordered.", sensitivity: "public" },
+    { path: "data.items", owner: "platform", purpose: "Anonymous line items (no customer identity or payment data).", sensitivity: "public" },
+  ],
+  "storefront.order.fulfilled.v1": [
+    { path: "data.orderId", owner: "platform", purpose: "Provider external order id; server-authoritative conversion key.", sensitivity: "pseudonymous" },
+    { path: "data.currency", owner: "platform", purpose: "ISO currency of the order.", sensitivity: "public" },
+    { path: "data.value", owner: "platform", purpose: "Decimal order total.", sensitivity: "public" },
+    { path: "data.itemCount", owner: "platform", purpose: "Total units fulfilled.", sensitivity: "public" },
+    { path: "data.items", owner: "platform", purpose: "Anonymous line items (no customer identity or payment data).", sensitivity: "public" },
+  ],
+};
+
+/**
+ * Retention class per event type:
+ *   - `ephemeral-telemetry` — browse/cart interaction signal; shortest retention.
+ *   - `attribution-window`  — correlation-bearing handoff; retained for the
+ *                             attribution window then expired with the correlation.
+ *   - `financial-record`    — server-authoritative order events and consent-change
+ *                             evidence; retained for reconciliation/compliance.
+ */
+export type EventRetentionClass = "ephemeral-telemetry" | "attribution-window" | "financial-record";
+
+export const EVENT_RETENTION: Record<CommerceEventType, EventRetentionClass> = {
+  "storefront.page.viewed.v1": "ephemeral-telemetry",
+  "storefront.page.viewed.v2": "ephemeral-telemetry",
+  "storefront.action.activated.v1": "ephemeral-telemetry",
+  "storefront.product.viewed.v1": "ephemeral-telemetry",
+  "storefront.cart.item_added.v1": "ephemeral-telemetry",
+  "storefront.cart.item_removed.v1": "ephemeral-telemetry",
+  "storefront.cart.updated.v1": "ephemeral-telemetry",
+  "storefront.checkout.handoff.v1": "attribution-window",
+  "storefront.purchase.completed.v1": "ephemeral-telemetry",
+  "storefront.consent.changed.v1": "financial-record",
+  "storefront.order.created.v1": "financial-record",
+  "storefront.order.fulfilled.v1": "financial-record",
+};
+
+/** Every field path the catalog documents for a given event type (envelope + data). */
+export function catalogFieldPathsFor(type: CommerceEventType): string[] {
+  return [
+    ...COMMERCE_EVENT_ENVELOPE_CATALOG.map((d) => d.path),
+    ...COMMERCE_EVENT_DATA_CATALOG[type].map((d) => d.path),
+  ];
+}
+
+/** The full closed field path set the validators enforce for a type (envelope + data). */
+export function enforcedFieldPathsFor(type: CommerceEventType): string[] {
+  const envelope = COMMERCE_EVENT_ENVELOPE_CATALOG.map((d) => d.path);
+  const data = COMMERCE_EVENT_DATA_FIELDS[type].map((k) => `data.${k}`);
+  return [...envelope, ...data];
+}
+
+/** All released commerce event types (re-exported for catalog consumers). */
+export const CATALOGUED_COMMERCE_EVENT_TYPES = COMMERCE_EVENT_TYPES;