platform-types 1.10.794 → 1.10.796

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/paymentAttempt.js

@@ -19,7 +19,7 @@
  * no operator write can carry it back onto the order.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAYMENT_HOLD_MINUTES_DEFAULT = exports.PAYMENT_HOLD_MINUTES_MAX = exports.PAYMENT_HOLD_MINUTES_MIN = exports.PAYMENT_ATTEMPT_RESOLUTION_CAUSES = exports.ORDER_NOT_PAYABLE_REASONS = exports.PAYMENT_ATTEMPT_RESOLUTION_REASON_MAX = exports.PAYMENT_ATTEMPT_RESOLUTION_OUTCOMES = exports.PAYMENT_ATTEMPT_ERROR_CODES = exports.PAYMENT_ATTEMPT_STATES = void 0;
+exports.PAYMENT_HOLD_MINUTES_DEFAULT = exports.PAYMENT_HOLD_MINUTES_MAX = exports.PAYMENT_HOLD_MINUTES_MIN = exports.PAYMENT_ATTEMPT_RESOLUTION_CAUSES = exports.ORDER_NOT_PAYABLE_REASONS = exports.PAYMENT_ATTEMPT_RESOLUTION_REASON_MAX = exports.PAYMENT_ATTEMPT_RESOLUTION_OUTCOMES = exports.GUEST_PAYMENT_ERROR_CODES = exports.PAYMENT_ATTEMPT_ERROR_CODES = exports.PAYMENT_ATTEMPT_STATES = void 0;
 /** Every {@link PaymentAttemptState}, in lifecycle order. */
 exports.PAYMENT_ATTEMPT_STATES = [
     'created',
@@ -71,6 +71,20 @@ exports.PAYMENT_ATTEMPT_ERROR_CODES = [
     'PAYMENT_ATTEMPT_NOT_IN_RESOLUTION',
     'PAYMENT_ATTEMPT_CHANGED',
 ];
+/**
+ * The refusal the guest payment start (`POST /payments/attempts/guest`) answers
+ * itself, beside every {@link PAYMENT_ATTEMPT_ERROR_CODES} entry it shares with
+ * the signed-in start.
+ *
+ * - `GUEST_PAYMENT_GRANT_INVALID` · 401 — every reason the grant cannot be
+ *   honoured: missing, tampered, another version (a guest STATUS token
+ *   included), expired (7 days after it was issued), minted for another order
+ *   or another store, presented on another store's host, or naming an order
+ *   that is not — or is no longer — an unattached guest order (attached to an
+ *   account, its buyer then pays signed in). One identical body, so the grant is
+ *   never an oracle.
+ */
+exports.GUEST_PAYMENT_ERROR_CODES = ['GUEST_PAYMENT_GRANT_INVALID'];
 /**
  * Every `outcome` of {@link ResolvePaymentAttemptRequest}:
  *

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/order.d.ts

@@ -2494,6 +2494,24 @@ declare global {
         expectedCartId: string;
         expectedCartVersion: number;
     }
+    /**
+     * `data` of a successful Web `POST /orders/guest`: the placed order, as the
+     * signed-in checkout answers it (the storefront reads `orderId`), plus the
+     * guest's payment grant.
+     */
+    interface StorefrontGuestOrderCreateResponse extends Partial<Order> {
+        orderId: string;
+        /**
+         * The guest payment grant (`gp1.…`) for THIS order, valid 7 days: the
+         * credential `POST /payments/attempts/guest` takes
+         * ({@link StartGuestPaymentAttemptRequest}). Present only when the order
+         * can be paid online when the answer is built (its payment method row
+         * declares `storefront: 'mp-checkout-pro'`, pesos, something to charge) and
+         * the grant could be minted; absent otherwise. A replay of the checkout
+         * answers a freshly minted one. Keep it in memory or the URL fragment only.
+         */
+        paymentGrant?: string;
+    }
     interface ZebraTag {
         orderId: string;
         fullName: string;

package/dist/paymentAttempt.d.ts

@@ -57,6 +57,8 @@ declare global {
     type PaymentAttemptState = (typeof PAYMENT_ATTEMPT_STATES)[number];
     /** One of {@link PAYMENT_ATTEMPT_ERROR_CODES}. */
     type PaymentAttemptErrorCode = (typeof PAYMENT_ATTEMPT_ERROR_CODES)[number];
+    /** One of {@link GUEST_PAYMENT_ERROR_CODES}. */
+    type GuestPaymentErrorCode = (typeof GUEST_PAYMENT_ERROR_CODES)[number];
     /** One of {@link ORDER_NOT_PAYABLE_REASONS}. */
     type OrderNotPayableReason = (typeof ORDER_NOT_PAYABLE_REASONS)[number];
     /** One of {@link PAYMENT_ATTEMPT_RESOLUTION_CAUSES}. */
@@ -71,6 +73,22 @@ declare global {
     interface StartPaymentAttemptRequest {
         orderId: string;
     }
+    /**
+     * Web `POST /payments/attempts/guest` body: a buyer with NO account starts
+     * (or gets back the live) payment attempt of one guest order. Answers
+     * {@link StartPaymentAttemptResponse}, with every {@link PAYMENT_ATTEMPT_ERROR_CODES}
+     * refusal the signed-in start answers, plus {@link GUEST_PAYMENT_ERROR_CODES}.
+     */
+    interface StartGuestPaymentAttemptRequest {
+        orderId: string;
+        /**
+         * The guest payment grant (`gp1.…`) the guest checkout answered
+         * (`StorefrontGuestOrderCreateResponse.paymentGrant`) or the order email's
+         * "Pagar" link carried in its `#pagar=` fragment. A bearer credential:
+         * never put it in a URL a server or Mercado Pago sees, nor in `back_urls`.
+         */
+        paymentGrant: string;
+    }
     /** `data` of a successful start. A repeat start while the attempt is live answers the same `attemptId`. */
     interface StartPaymentAttemptResponse {
         attemptId: string;
@@ -237,6 +255,20 @@ export declare const PAYMENT_ATTEMPT_STATES: readonly ["created", "pending", "ap
  *   written; `data` is {@link PaymentAttemptChangedData}.
  */
 export declare const PAYMENT_ATTEMPT_ERROR_CODES: readonly ["PAYMENT_PROVIDER_NOT_CONNECTED", "PAYMENT_PROVIDER_TOKEN_EXPIRED", "ORDER_NOT_PAYABLE", "PAYMENT_ATTEMPT_EXPIRED", "PAYMENT_METHOD_UNAVAILABLE", "MP_PREFERENCE_CREATE_FAILED", "PAYMENT_ATTEMPT_NOT_FOUND", "PAYMENT_ATTEMPT_NOT_IN_RESOLUTION", "PAYMENT_ATTEMPT_CHANGED"];
+/**
+ * The refusal the guest payment start (`POST /payments/attempts/guest`) answers
+ * itself, beside every {@link PAYMENT_ATTEMPT_ERROR_CODES} entry it shares with
+ * the signed-in start.
+ *
+ * - `GUEST_PAYMENT_GRANT_INVALID` · 401 — every reason the grant cannot be
+ *   honoured: missing, tampered, another version (a guest STATUS token
+ *   included), expired (7 days after it was issued), minted for another order
+ *   or another store, presented on another store's host, or naming an order
+ *   that is not — or is no longer — an unattached guest order (attached to an
+ *   account, its buyer then pays signed in). One identical body, so the grant is
+ *   never an oracle.
+ */
+export declare const GUEST_PAYMENT_ERROR_CODES: readonly ["GUEST_PAYMENT_GRANT_INVALID"];
 /**
  * Every `outcome` of {@link ResolvePaymentAttemptRequest}:
  *

package/dist/paymentAttempt.js

@@ -68,6 +68,20 @@ export const PAYMENT_ATTEMPT_ERROR_CODES = [
     'PAYMENT_ATTEMPT_NOT_IN_RESOLUTION',
     'PAYMENT_ATTEMPT_CHANGED',
 ];
+/**
+ * The refusal the guest payment start (`POST /payments/attempts/guest`) answers
+ * itself, beside every {@link PAYMENT_ATTEMPT_ERROR_CODES} entry it shares with
+ * the signed-in start.
+ *
+ * - `GUEST_PAYMENT_GRANT_INVALID` · 401 — every reason the grant cannot be
+ *   honoured: missing, tampered, another version (a guest STATUS token
+ *   included), expired (7 days after it was issued), minted for another order
+ *   or another store, presented on another store's host, or naming an order
+ *   that is not — or is no longer — an unattached guest order (attached to an
+ *   account, its buyer then pays signed in). One identical body, so the grant is
+ *   never an oracle.
+ */
+export const GUEST_PAYMENT_ERROR_CODES = ['GUEST_PAYMENT_GRANT_INVALID'];
 /**
  * Every `outcome` of {@link ResolvePaymentAttemptRequest}:
  *

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.796",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",