platform-types 1.10.794 → 1.10.795

package/dist/cjs/index.js

@@ -110,6 +110,7 @@ __exportStar(require("./storefrontTheme.js"), exports);
 __exportStar(require("./storeNetwork.js"), exports);
 __exportStar(require("./storefrontAssets.js"), exports);
 __exportStar(require("./storefrontEvent.js"), exports);
+__exportStar(require("./storefrontIngest.js"), exports);
 __exportStar(require("./storefrontSeo.js"), exports);
 __exportStar(require("./storefrontProductMeta.js"), exports);
 __exportStar(require("./storefrontWebLiteralKeys.js"), exports);

package/dist/cjs/storefrontIngest.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Guest storefront telemetry ingest — the HTTP route a shopper who never signs
+ * in sends first-party storefront events through (the signed-in shopper keeps
+ * the WebSocket `logs` action).
+ *
+ * Web (public, bound origin only): `POST /events` (a batch) and
+ * `POST /events/consent` (an analytics-consent withdrawal for one journey).
+ *
+ * The tenant is the request's bound Origin (a slug host or a verified custom
+ * domain), never `x-store` and never an event's `tenant_store_id`. Nothing a
+ * guest sends can claim to be a customer: `customer_id` is not part of a guest
+ * event, and one that carries it is dropped and counted.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOREFRONT_INGEST_LIMITS = exports.STOREFRONT_INGEST_ERROR_CODES = void 0;
+/**
+ * The refusals of the guest ingest routes.
+ *
+ * - EVENTS_TENANT_UNRESOLVED (403): the request's Origin is bound to no shop.
+ *   Checked before the body is read; nothing is stored.
+ * - EVENTS_BATCH_TOO_LARGE (413): the raw body is over
+ *   {@link STOREFRONT_INGEST_LIMITS.maxBodyBytes} bytes, or `events` holds more
+ *   than {@link STOREFRONT_INGEST_LIMITS.maxEvents} entries. Nothing is stored.
+ * - VALIDATION_FAILED (400): the request as a WHOLE is malformed — not JSON, not
+ *   the envelope shape, or (withdrawal) `anonymousId` not a UUID. A single event
+ *   that does not validate is never a 400: it is a counted drop in `dropped`.
+ * - EVENTS_RATE_LIMITED (429): the source's budget is spent. Nothing is stored;
+ *   retry later.
+ */
+exports.STOREFRONT_INGEST_ERROR_CODES = [
+    'EVENTS_TENANT_UNRESOLVED',
+    'EVENTS_BATCH_TOO_LARGE',
+    'VALIDATION_FAILED',
+    'EVENTS_RATE_LIMITED',
+];
+/** Bounds of `POST /events`, enforced before any event is read. */
+exports.STOREFRONT_INGEST_LIMITS = {
+    /** The raw request body ceiling, in UTF-8 bytes, measured before parsing. */
+    maxBodyBytes: 32 * 1024,
+    /** At most this many events per request. */
+    maxEvents: 25,
+    /** The longest `analyticsConsent.version` accepted; a longer one never stores an event. */
+    consentVersionMaxLength: 64,
+};

package/dist/index.d.ts

@@ -86,6 +86,7 @@ export * from './storefrontTheme.ts';
 export * from './storeNetwork.ts';
 export * from './storefrontAssets.ts';
 export * from './storefrontEvent.ts';
+export * from './storefrontIngest.ts';
 export * from './storefrontSeo.ts';
 export * from './storefrontProductMeta.ts';
 export * from './storefrontWebLiteralKeys.ts';

package/dist/index.js

@@ -94,6 +94,7 @@ export * from "./storefrontTheme.js";
 export * from "./storeNetwork.js";
 export * from "./storefrontAssets.js";
 export * from "./storefrontEvent.js";
+export * from "./storefrontIngest.js";
 export * from "./storefrontSeo.js";
 export * from "./storefrontProductMeta.js";
 export * from "./storefrontWebLiteralKeys.js";

package/dist/storefrontEvent.d.ts

@@ -10,6 +10,13 @@ declare global {
         screen_type: 'desktop' | 'mobile';
         app_version: number;
         ts: string;
+        /**
+         * Server-stamped on a stored guest event (the unauthenticated `POST /events`
+         * ingest) from the request's analytics-consent block, so a later policy change
+         * can scope erasure. Never read from a client event: the validators drop it.
+         * Distinct from the signup contract's `consentVersion`.
+         */
+        analyticsConsentVersion?: string;
     }
     interface ProductViewedEvent extends StorefrontEventBase {
         event: 'Product Viewed';

package/dist/storefrontIngest.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Guest storefront telemetry ingest — the HTTP route a shopper who never signs
+ * in sends first-party storefront events through (the signed-in shopper keeps
+ * the WebSocket `logs` action).
+ *
+ * Web (public, bound origin only): `POST /events` (a batch) and
+ * `POST /events/consent` (an analytics-consent withdrawal for one journey).
+ *
+ * The tenant is the request's bound Origin (a slug host or a verified custom
+ * domain), never `x-store` and never an event's `tenant_store_id`. Nothing a
+ * guest sends can claim to be a customer: `customer_id` is not part of a guest
+ * event, and one that carries it is dropped and counted.
+ */
+/**
+ * The refusals of the guest ingest routes.
+ *
+ * - EVENTS_TENANT_UNRESOLVED (403): the request's Origin is bound to no shop.
+ *   Checked before the body is read; nothing is stored.
+ * - EVENTS_BATCH_TOO_LARGE (413): the raw body is over
+ *   {@link STOREFRONT_INGEST_LIMITS.maxBodyBytes} bytes, or `events` holds more
+ *   than {@link STOREFRONT_INGEST_LIMITS.maxEvents} entries. Nothing is stored.
+ * - VALIDATION_FAILED (400): the request as a WHOLE is malformed — not JSON, not
+ *   the envelope shape, or (withdrawal) `anonymousId` not a UUID. A single event
+ *   that does not validate is never a 400: it is a counted drop in `dropped`.
+ * - EVENTS_RATE_LIMITED (429): the source's budget is spent. Nothing is stored;
+ *   retry later.
+ */
+export declare const STOREFRONT_INGEST_ERROR_CODES: readonly ["EVENTS_TENANT_UNRESOLVED", "EVENTS_BATCH_TOO_LARGE", "VALIDATION_FAILED", "EVENTS_RATE_LIMITED"];
+/** Bounds of `POST /events`, enforced before any event is read. */
+export declare const STOREFRONT_INGEST_LIMITS: {
+    /** The raw request body ceiling, in UTF-8 bytes, measured before parsing. */
+    readonly maxBodyBytes: number;
+    /** At most this many events per request. */
+    readonly maxEvents: 25;
+    /** The longest `analyticsConsent.version` accepted; a longer one never stores an event. */
+    readonly consentVersionMaxLength: 64;
+};
+declare global {
+    type StorefrontIngestErrorCode = (typeof STOREFRONT_INGEST_ERROR_CODES)[number];
+    /** The storefront event variants a guest may send. Any other variant is a counted drop. */
+    type GuestStorefrontEventName = 'Product Viewed' | 'Product List Viewed' | 'Cart Item Added' | 'Cart Item Removed' | 'Cart Viewed' | 'Search Submitted' | 'Checkout Started' | 'Checkout Step Completed';
+    /**
+     * A guest event: an allowed variant of `StorefrontEvent` with no
+     * `customer_id` (and no server-stamped field). Distributive, so each variant
+     * keeps its own discriminated shape.
+     */
+    type GuestStorefrontEvent = Extract<StorefrontEvent, {
+        event: GuestStorefrontEventName;
+    }> extends infer Variant ? Variant extends unknown ? Omit<Variant, 'customer_id' | 'audit' | 'analyticsConsentVersion'> : never : never;
+    /**
+     * The analytics-consent state the storefront holds for this shopper, separate
+     * from advertising consent. `version` names the consent text the shopper saw;
+     * a persisted event records it as `analyticsConsentVersion`.
+     */
+    interface StorefrontAnalyticsConsent {
+        analytics: 'granted' | 'denied';
+        version: string;
+    }
+    /**
+     * Web `POST /events` body. At most 25 events and 32 KiB. With
+     * `analytics: 'denied'` no per-journey event is stored — only an aggregate
+     * count with no `anonymous_id`. Under the platform's opt-in mode (the
+     * default) only `'granted'` stores events, so an absent block stores none;
+     * under opt-out everything but `'denied'` stores, an absent block included.
+     */
+    interface StorefrontEventIngestRequest {
+        events: GuestStorefrontEvent[];
+        analyticsConsent?: StorefrontAnalyticsConsent;
+    }
+    /**
+     * Web `POST /events` 202 `data`: counts only, never an echo of the batch.
+     * `accepted` events were stored (or were already stored under the same
+     * `event_id`); `dropped` ones were refused one by one — invalid, a
+     * customer-only variant, carrying `customer_id`, another tenant, outside the
+     * time window, fenced, not consented, or over a budget.
+     */
+    interface StorefrontEventIngestResponse {
+        accepted: number;
+        dropped: number;
+    }
+    /**
+     * Web `POST /events/consent` body: withdraw analytics consent for one
+     * journey. Every later event of that `anonymousId` is refused, however late
+     * it arrives. Nothing is erased: its earlier events expire by retention
+     * (30-day hot rows, the 390-day `guest/` archive). Answers 202 with no data.
+     */
+    interface StorefrontConsentWithdrawalRequest {
+        /** The journey's `anonymous_id` (a UUID). */
+        anonymousId: string;
+        analytics: 'denied';
+    }
+}
+export {};

package/dist/storefrontIngest.js

@@ -0,0 +1,42 @@
+/**
+ * Guest storefront telemetry ingest — the HTTP route a shopper who never signs
+ * in sends first-party storefront events through (the signed-in shopper keeps
+ * the WebSocket `logs` action).
+ *
+ * Web (public, bound origin only): `POST /events` (a batch) and
+ * `POST /events/consent` (an analytics-consent withdrawal for one journey).
+ *
+ * The tenant is the request's bound Origin (a slug host or a verified custom
+ * domain), never `x-store` and never an event's `tenant_store_id`. Nothing a
+ * guest sends can claim to be a customer: `customer_id` is not part of a guest
+ * event, and one that carries it is dropped and counted.
+ */
+/**
+ * The refusals of the guest ingest routes.
+ *
+ * - EVENTS_TENANT_UNRESOLVED (403): the request's Origin is bound to no shop.
+ *   Checked before the body is read; nothing is stored.
+ * - EVENTS_BATCH_TOO_LARGE (413): the raw body is over
+ *   {@link STOREFRONT_INGEST_LIMITS.maxBodyBytes} bytes, or `events` holds more
+ *   than {@link STOREFRONT_INGEST_LIMITS.maxEvents} entries. Nothing is stored.
+ * - VALIDATION_FAILED (400): the request as a WHOLE is malformed — not JSON, not
+ *   the envelope shape, or (withdrawal) `anonymousId` not a UUID. A single event
+ *   that does not validate is never a 400: it is a counted drop in `dropped`.
+ * - EVENTS_RATE_LIMITED (429): the source's budget is spent. Nothing is stored;
+ *   retry later.
+ */
+export const STOREFRONT_INGEST_ERROR_CODES = [
+    'EVENTS_TENANT_UNRESOLVED',
+    'EVENTS_BATCH_TOO_LARGE',
+    'VALIDATION_FAILED',
+    'EVENTS_RATE_LIMITED',
+];
+/** Bounds of `POST /events`, enforced before any event is read. */
+export const STOREFRONT_INGEST_LIMITS = {
+    /** The raw request body ceiling, in UTF-8 bytes, measured before parsing. */
+    maxBodyBytes: 32 * 1024,
+    /** At most this many events per request. */
+    maxEvents: 25,
+    /** The longest `analyticsConsent.version` accepted; a longer one never stores an event. */
+    consentVersionMaxLength: 64,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.794",
+	"version": "1.10.795",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",