platform-types 1.10.764 → 1.10.766

package/dist/auth.d.ts

@@ -1,3 +1,4 @@
+import type { EmailSuppressionReason } from './emailSuppression.ts';
 declare global {
     interface Login {
         email: string;
@@ -1079,6 +1080,56 @@ declare global {
         /** Unix ms after which the code no longer redeems (mint + 60 s). */
         expiresAt: number;
     }
+    /**
+     * `POST /auth` (Web API) body for `send-otp`: mail a 6-digit code to the
+     * address STORED on the caller's customer row. Needs a Bearer customer ACCESS
+     * token (`Authorization: Bearer …`); the method has no API Gateway authorizer,
+     * so the handler verifies it. The body carries no address — one supplied is
+     * ignored.
+     *
+     * `200 { message }` with no `data` when a code was queued. Refusals: see
+     * {@link CUSTOMER_OTP_ERROR_CODES}. Timing: see {@link CUSTOMER_OTP_LIMITS}.
+     * Nothing is mailed automatically after the customer changes their address —
+     * call this.
+     */
+    interface CustomerSendOtpRequest {
+        mode: 'send-otp';
+    }
+    /**
+     * `POST /auth` (Web API) body for `verify-otp`, with the same Bearer customer
+     * ACCESS token as `send-otp`.
+     */
+    interface CustomerVerifyOtpRequest {
+        mode: 'verify-otp';
+        /** Exactly six ASCII digits; anything else is `400 VALIDATION_FAILED`. */
+        code: string;
+    }
+    /**
+     * `verify-otp` 200 `data`. Merge it into the cached `AuthCustomer`; the same
+     * pair also arrives as a `customers` socket frame (`data: { customerId,
+     * emailVerified, emailVerifiedAt }`) on every socket of this customer, so other
+     * open tabs update without a refresh.
+     */
+    interface CustomerVerifyOtpResponse {
+        emailVerified: true;
+        /** ms-epoch of the verification. */
+        emailVerifiedAt: number;
+    }
+    /**
+     * `verify-otp` `400 OTP_WRONG_CODE` body.
+     *
+     * ⚠️ `attemptsLeft` is TOP-LEVEL, beside `error`, not under `data`. `0` means
+     * the next guess answers `429 OTP_LOCKED`.
+     */
+    interface CustomerOtpWrongCodeBody {
+        error: 'OTP_WRONG_CODE';
+        message: string;
+        attemptsLeft: number;
+    }
+    /** `send-otp` `409 EMAIL_ADDRESS_SUPPRESSED` `data`: why the stored address cannot receive mail. */
+    interface CustomerOtpSuppressedData {
+        reason: EmailSuppressionReason;
+    }
     /**
      * `POST /auth` body for `social-bridge-redeem`. Public, captcha-exempt.
      *
@@ -1854,4 +1905,52 @@ export type PasskeyErrorCode = (typeof PASSKEY_ERROR_CODES)[number];
  */
 export declare const SESSION_ACTION_ERROR_CODES: readonly ["SESSION_LOOKUP_INCOMPLETE", "SESSION_UNKNOWN", "REVOKE_INCOMPLETE"];
 export type SessionActionErrorCode = (typeof SESSION_ACTION_ERROR_CODES)[number];
+/**
+ * `body.error` codes the two customer email-OTP modes (Web API `POST /auth`
+ * `send-otp` / `verify-otp`) refuse with. Match on `body.error`.
+ *
+ * NOT members, and answered by both modes before any of these: the shared
+ * customer-identity refusals — `MISSING_TOKEN`, `INVALID_TOKEN`,
+ * `REFRESH_TOKEN_NOT_ALLOWED` (401), `ROLE_NOT_ALLOWED`,
+ * `CUSTOMER_ACCESS_PENDING`, `CUSTOMER_ACCESS_REJECTED` (403),
+ * `CUSTOMER_NOT_FOUND` (404), `ACCOUNT_DISABLED` (400) — and, on `verify-otp`,
+ * `VALIDATION_FAILED` (400) for a `code` that is not six digits.
+ *
+ * - `OTP_COOLDOWN` · 429 — `send-otp` inside 60 s of the last live code.
+ * - `EMAIL_ADDRESS_SUPPRESSED` · 409 — `send-otp`; the address bounced.
+ *   `data` is {@link CustomerOtpSuppressedData}.
+ * - `EMAIL_ALREADY_VERIFIED` · 409 — `send-otp`; the stored address is already
+ *   verified, so nothing was mailed. Hide the resend action.
+ * - `OTP_INVALID` · 400 — `verify-otp`; no code outstanding for the CURRENT
+ *   address: none was sent, or the one sent went to an address the account no
+ *   longer holds. Ask for a new code.
+ * - `OTP_ALREADY_USED` · 400 — `verify-otp`; the code was consumed, or lost a
+ *   race (including a concurrent address change). Ask for a new code.
+ * - `OTP_EXPIRED` · 400 — `verify-otp`; past its 10-minute TTL.
+ * - `OTP_LOCKED` · 429 — `verify-otp`; 5 wrong guesses. Only a new `send-otp`
+ *   unlocks.
+ * - `OTP_WRONG_CODE` · 400 — `verify-otp`; {@link CustomerOtpWrongCodeBody},
+ *   `attemptsLeft` at the TOP level.
+ *
+ * ⚠️ Deliberately not the operator tree's vocabulary (`OTP_INVALID_OR_EXPIRED`,
+ * `OTP_TOO_MANY_ATTEMPTS`, `OTP_RESEND_TOO_SOON`); the two are not unified.
+ */
+export declare const CUSTOMER_OTP_ERROR_CODES: readonly ["OTP_COOLDOWN", "EMAIL_ADDRESS_SUPPRESSED", "EMAIL_ALREADY_VERIFIED", "OTP_INVALID", "OTP_ALREADY_USED", "OTP_EXPIRED", "OTP_LOCKED", "OTP_WRONG_CODE"];
+export type CustomerOtpErrorCode = (typeof CUSTOMER_OTP_ERROR_CODES)[number];
+/**
+ * The numbers the customer email OTP enforces, so a client countdown matches
+ * the server. The api's own OTP service reads them from here, for operators and
+ * customers alike.
+ *
+ * - `ttlSeconds` — a code expires this long after it was sent.
+ * - `resendCooldownSeconds` — `send-otp` answers `429 OTP_COOLDOWN` until this
+ *   long after the last live code.
+ * - `maxAttempts` — wrong guesses per code before `429 OTP_LOCKED`; a new code
+ *   starts the count again.
+ */
+export declare const CUSTOMER_OTP_LIMITS: {
+    readonly ttlSeconds: 600;
+    readonly resendCooldownSeconds: 60;
+    readonly maxAttempts: 5;
+};
 export {};

package/dist/auth.js

@@ -502,3 +502,55 @@ export const SESSION_ACTION_ERROR_CODES = [
     'SESSION_UNKNOWN',
     'REVOKE_INCOMPLETE',
 ];
+/**
+ * `body.error` codes the two customer email-OTP modes (Web API `POST /auth`
+ * `send-otp` / `verify-otp`) refuse with. Match on `body.error`.
+ *
+ * NOT members, and answered by both modes before any of these: the shared
+ * customer-identity refusals — `MISSING_TOKEN`, `INVALID_TOKEN`,
+ * `REFRESH_TOKEN_NOT_ALLOWED` (401), `ROLE_NOT_ALLOWED`,
+ * `CUSTOMER_ACCESS_PENDING`, `CUSTOMER_ACCESS_REJECTED` (403),
+ * `CUSTOMER_NOT_FOUND` (404), `ACCOUNT_DISABLED` (400) — and, on `verify-otp`,
+ * `VALIDATION_FAILED` (400) for a `code` that is not six digits.
+ *
+ * - `OTP_COOLDOWN` · 429 — `send-otp` inside 60 s of the last live code.
+ * - `EMAIL_ADDRESS_SUPPRESSED` · 409 — `send-otp`; the address bounced.
+ *   `data` is {@link CustomerOtpSuppressedData}.
+ * - `EMAIL_ALREADY_VERIFIED` · 409 — `send-otp`; the stored address is already
+ *   verified, so nothing was mailed. Hide the resend action.
+ * - `OTP_INVALID` · 400 — `verify-otp`; no code outstanding for the CURRENT
+ *   address: none was sent, or the one sent went to an address the account no
+ *   longer holds. Ask for a new code.
+ * - `OTP_ALREADY_USED` · 400 — `verify-otp`; the code was consumed, or lost a
+ *   race (including a concurrent address change). Ask for a new code.
+ * - `OTP_EXPIRED` · 400 — `verify-otp`; past its 10-minute TTL.
+ * - `OTP_LOCKED` · 429 — `verify-otp`; 5 wrong guesses. Only a new `send-otp`
+ *   unlocks.
+ * - `OTP_WRONG_CODE` · 400 — `verify-otp`; {@link CustomerOtpWrongCodeBody},
+ *   `attemptsLeft` at the TOP level.
+ *
+ * ⚠️ Deliberately not the operator tree's vocabulary (`OTP_INVALID_OR_EXPIRED`,
+ * `OTP_TOO_MANY_ATTEMPTS`, `OTP_RESEND_TOO_SOON`); the two are not unified.
+ */
+export const CUSTOMER_OTP_ERROR_CODES = [
+    'OTP_COOLDOWN',
+    'EMAIL_ADDRESS_SUPPRESSED',
+    'EMAIL_ALREADY_VERIFIED',
+    'OTP_INVALID',
+    'OTP_ALREADY_USED',
+    'OTP_EXPIRED',
+    'OTP_LOCKED',
+    'OTP_WRONG_CODE',
+];
+/**
+ * The numbers the customer email OTP enforces, so a client countdown matches
+ * the server. The api's own OTP service reads them from here, for operators and
+ * customers alike.
+ *
+ * - `ttlSeconds` — a code expires this long after it was sent.
+ * - `resendCooldownSeconds` — `send-otp` answers `429 OTP_COOLDOWN` until this
+ *   long after the last live code.
+ * - `maxAttempts` — wrong guesses per code before `429 OTP_LOCKED`; a new code
+ *   starts the count again.
+ */
+export const CUSTOMER_OTP_LIMITS = { ttlSeconds: 600, resendCooldownSeconds: 60, maxAttempts: 5 };

package/dist/cjs/auth.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_ACTION_ERROR_CODES = exports.PASSKEY_ERROR_CODES = exports.TWO_FACTOR_MANAGEMENT_ERROR_CODES = exports.LOGIN_2FA_ERROR_CODES = exports.LOGIN_ERROR_CODES = exports.STEP_UP_ERROR_CODES = exports.REFRESH_ERROR_CODES = exports.CUSTOMER_SOCIAL_REGISTER_ERROR_CODES = exports.SOCIAL_BRIDGE_ERROR_CODES = exports.SIGN_IN_METHOD_ERROR_CODES = void 0;
+exports.CUSTOMER_OTP_LIMITS = exports.CUSTOMER_OTP_ERROR_CODES = exports.SESSION_ACTION_ERROR_CODES = exports.PASSKEY_ERROR_CODES = exports.TWO_FACTOR_MANAGEMENT_ERROR_CODES = exports.LOGIN_2FA_ERROR_CODES = exports.LOGIN_ERROR_CODES = exports.STEP_UP_ERROR_CODES = exports.REFRESH_ERROR_CODES = exports.CUSTOMER_SOCIAL_REGISTER_ERROR_CODES = exports.SOCIAL_BRIDGE_ERROR_CODES = exports.SIGN_IN_METHOD_ERROR_CODES = void 0;
 /**
  * `body.error` codes the sign-in-method paths can refuse with.
  *
@@ -505,3 +505,55 @@ exports.SESSION_ACTION_ERROR_CODES = [
     'SESSION_UNKNOWN',
     'REVOKE_INCOMPLETE',
 ];
+/**
+ * `body.error` codes the two customer email-OTP modes (Web API `POST /auth`
+ * `send-otp` / `verify-otp`) refuse with. Match on `body.error`.
+ *
+ * NOT members, and answered by both modes before any of these: the shared
+ * customer-identity refusals — `MISSING_TOKEN`, `INVALID_TOKEN`,
+ * `REFRESH_TOKEN_NOT_ALLOWED` (401), `ROLE_NOT_ALLOWED`,
+ * `CUSTOMER_ACCESS_PENDING`, `CUSTOMER_ACCESS_REJECTED` (403),
+ * `CUSTOMER_NOT_FOUND` (404), `ACCOUNT_DISABLED` (400) — and, on `verify-otp`,
+ * `VALIDATION_FAILED` (400) for a `code` that is not six digits.
+ *
+ * - `OTP_COOLDOWN` · 429 — `send-otp` inside 60 s of the last live code.
+ * - `EMAIL_ADDRESS_SUPPRESSED` · 409 — `send-otp`; the address bounced.
+ *   `data` is {@link CustomerOtpSuppressedData}.
+ * - `EMAIL_ALREADY_VERIFIED` · 409 — `send-otp`; the stored address is already
+ *   verified, so nothing was mailed. Hide the resend action.
+ * - `OTP_INVALID` · 400 — `verify-otp`; no code outstanding for the CURRENT
+ *   address: none was sent, or the one sent went to an address the account no
+ *   longer holds. Ask for a new code.
+ * - `OTP_ALREADY_USED` · 400 — `verify-otp`; the code was consumed, or lost a
+ *   race (including a concurrent address change). Ask for a new code.
+ * - `OTP_EXPIRED` · 400 — `verify-otp`; past its 10-minute TTL.
+ * - `OTP_LOCKED` · 429 — `verify-otp`; 5 wrong guesses. Only a new `send-otp`
+ *   unlocks.
+ * - `OTP_WRONG_CODE` · 400 — `verify-otp`; {@link CustomerOtpWrongCodeBody},
+ *   `attemptsLeft` at the TOP level.
+ *
+ * ⚠️ Deliberately not the operator tree's vocabulary (`OTP_INVALID_OR_EXPIRED`,
+ * `OTP_TOO_MANY_ATTEMPTS`, `OTP_RESEND_TOO_SOON`); the two are not unified.
+ */
+exports.CUSTOMER_OTP_ERROR_CODES = [
+    'OTP_COOLDOWN',
+    'EMAIL_ADDRESS_SUPPRESSED',
+    'EMAIL_ALREADY_VERIFIED',
+    'OTP_INVALID',
+    'OTP_ALREADY_USED',
+    'OTP_EXPIRED',
+    'OTP_LOCKED',
+    'OTP_WRONG_CODE',
+];
+/**
+ * The numbers the customer email OTP enforces, so a client countdown matches
+ * the server. The api's own OTP service reads them from here, for operators and
+ * customers alike.
+ *
+ * - `ttlSeconds` — a code expires this long after it was sent.
+ * - `resendCooldownSeconds` — `send-otp` answers `429 OTP_COOLDOWN` until this
+ *   long after the last live code.
+ * - `maxAttempts` — wrong guesses per code before `429 OTP_LOCKED`; a new code
+ *   starts the count again.
+ */
+exports.CUSTOMER_OTP_LIMITS = { ttlSeconds: 600, resendCooldownSeconds: 60, maxAttempts: 5 };

package/dist/cjs/notification.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NotificationTypeEnum = void 0;
+exports.WEB_NOTIFICATIONS_MAX_LIMIT = exports.CUSTOMER_NOTIFICATION_TYPES = exports.NotificationTypeEnum = void 0;
 // Canonical notification taxonomy and keys for legacy/type × channel preferences.
 // Indexed producers resolve candidates through `getNotificationSubscribers`:
 // legacy opt-ins and explicit channel maps remain source data on USER rows.
@@ -200,3 +200,11 @@ var NotificationTypeEnum;
      */
     NotificationTypeEnum["PAYMENT_ATTEMPT_RESOLUTION"] = "PAYMENT_ATTEMPT_RESOLUTION";
 })(NotificationTypeEnum || (exports.NotificationTypeEnum = NotificationTypeEnum = {}));
+/**
+ * The notification types a CUSTOMER bell can carry today; each links through
+ * `orderId`. Adding one means a new {@link CustomerNotification} member with its
+ * own link field — the storefront maps type → route from this list.
+ */
+exports.CUSTOMER_NOTIFICATION_TYPES = [NotificationTypeEnum.ORDER];
+/** Web `GET /notifications` page ceiling and default (`?Limit=`). */
+exports.WEB_NOTIFICATIONS_MAX_LIMIT = 500;

package/dist/cjs/order.js

@@ -372,12 +372,26 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  *   Storefront checkout carries `data: {}` and refuses before the cart read.
  *
  * Storefront checkout business refusals. None allocates an order
- * id, redeems a coupon or writes an order; none is logged as an error:
+ * id, redeems a coupon or writes an order; none is logged as an error —
+ * except `CART_CHANGED_SINCE_CONFIRM` refused at commit, as its entry says:
  * - `DELIVERY_METHOD_NOT_FOUND` · 400 — `deliveryMethod` is not in the store's
  *   delivery catalogue, including an absent/empty catalogue. `data: {}`;
  *   refused before reading the cart.
  * - `ORDER_INVALID_CART` · 400 — the normalized cart has no finite numeric
  *   `totals.grandTotal`. `data: {}`; refused before repricing/allocation.
+ * - `CART_CHANGED_SINCE_CONFIRM` · 409 — the body sent `expectedCartId` /
+ *   `expectedCartVersion` and the stored cart is not the cart the shopper
+ *   confirmed (gone, replaced by another `cartId`, or at another `version`);
+ *   `data` is `CartChangedSinceConfirmData` and carries no cart. Distinct from
+ *   `ORDER_INVALID_CART` (a non-finite total) and from the operator's
+ *   `CART_REVISION_STALE` / `CART_VERSION_*` (whose `data.basket` keeps
+ *   `cost`). Decided at TWO points: right after the server's cart read, with
+ *   nothing written and nothing logged; and at the commit, when the cart moved
+ *   between the read and the write — then no order committed, but the order id
+ *   allocated before the commit is consumed, a coupon redeemed before the
+ *   commit is not released, and an ERROR row is logged.
+ *   Re-read the cart and confirm again under a new `Idempotency-Key`; on
+ *   `currentCartVersion: null` check the shopper's orders first.
  * - `ORDER_BELOW_MINIMUM_PURCHASE` · 400 — after repricing has confirmed the
  *   cart, its grand total is below a finite positive `Number(customer.minBuy)`.
  *   Equality passes. `data: OrderBelowMinimumPurchaseData` carries minBuy,
@@ -638,6 +652,8 @@ exports.ORDER_ERROR_CODES = [
     'DELIVERY_METHOD_NOT_FOUND',
     'ORDER_BELOW_MINIMUM_PURCHASE',
     'ORDER_INVALID_CART',
+    // The storefront's confirmed-cart pin (`StorefrontOrderCreateRequest.expectedCartId` / `expectedCartVersion`).
+    'CART_CHANGED_SINCE_CONFIRM',
     'EMAIL_VERIFICATION_REQUIRED',
     'ACCOUNT_DISABLED',
     'CUSTOMER_ACCESS_PENDING',

package/dist/customer.d.ts

@@ -302,8 +302,16 @@ declare global {
         email?: string;
         /**
          * Set `true` ONLY where the address is proven: by the customer OTP verify
-         * transaction, or at creation by a storefront `register-social`, whose
-         * provider verified the email (an unverified identity creates nothing).
+         * transaction; at creation by a storefront `register-social`, whose
+         * provider verified the email (an unverified identity creates nothing); or
+         * by a storefront social sign-in (`social`, `social-bridge-redeem`) or
+         * `link-sign-in-method` whose provider asserts a verified email equal,
+         * case-insensitively, to the stored one — never through an Apple Hide My
+         * Email relay, which is not the stored address. A sign-in then answers
+         * `true` in its body and the customer's own sockets get a `customers` frame.
+         * When that sign-in is the provider's FIRST on a row that held an unproven
+         * password, the password is removed and every earlier session revoked.
+         * Any move or clear of the address resets it to `false`.
          *
          * ⚠️ UNDEFINED MEANS **NOT** VERIFIED — deliberately the INVERSE of
          * `User.emailVerified`, which carries a grandfather clause telling apps to
@@ -314,8 +322,10 @@ declare global {
          */
         emailVerified?: boolean;
         /**
-         * ms-epoch of the proof: the OTP verification, or — for a `register-social`
-         * account — the row's `createdAt`. Absent whenever `emailVerified` is not `true`.
+         * ms-epoch of the proof: the OTP verification, the social sign-in or link
+         * that proved it, or — for a `register-social` account — the row's
+         * `createdAt`. Kept from the FIRST proof; a later social sign-in does not
+         * move it. Absent or `null` whenever `emailVerified` is not `true`.
          */
         emailVerifiedAt?: number;
         /**

package/dist/notification.d.ts

@@ -179,6 +179,14 @@ export declare enum NotificationTypeEnum {
      */
     PAYMENT_ATTEMPT_RESOLUTION = "PAYMENT_ATTEMPT_RESOLUTION"
 }
+/**
+ * The notification types a CUSTOMER bell can carry today; each links through
+ * `orderId`. Adding one means a new {@link CustomerNotification} member with its
+ * own link field — the storefront maps type → route from this list.
+ */
+export declare const CUSTOMER_NOTIFICATION_TYPES: readonly [NotificationTypeEnum.ORDER];
+/** Web `GET /notifications` page ceiling and default (`?Limit=`). */
+export declare const WEB_NOTIFICATIONS_MAX_LIMIT = 500;
 declare global {
     type CustomerNotificationPreferences = Partial<Record<'reminder-scheduled' | 'appointment-reminder', {
         email: boolean;
@@ -241,6 +249,7 @@ declare global {
         createdAt: number;
         type: NotificationTypeEnum;
         title: string;
+        /** `ORDER` links through `orderId` on both audiences (operator and customer). */
         orderId?: string;
         productId?: string;
         lotId?: string;
@@ -305,7 +314,8 @@ declare global {
     };
     /**
      * `GET /notifications` body on the operator host — the caller's own
-     * notifications, newest first, projected through an allow-list.
+     * notifications, newest first, projected through an allow-list. Operator
+     * host only; the web leg is {@link WebGetNotificationsResponse}.
      *
      * ⚠️ There is no `hasMore` on this leg: the ABSENCE of `LastEvaluatedKey` is
      * the end of the list. A client that waits for a `hasMore: false` never stops
@@ -337,6 +347,52 @@ declare global {
             hasMore: boolean;
         };
     }
+    type CustomerNotificationType = (typeof CUSTOMER_NOTIFICATION_TYPES)[number];
+    /**
+     * The customer projection: what web `GET`/`POST /notifications` and the
+     * customer socket carry — the stored row minus the operator-only pointers.
+     * A union keyed on `type`; `ORDER` is its only member today.
+     */
+    type CustomerNotification = Omit<NotificationInterface, 'cartRef' | 'pendingCustomerRef' | 'TableName' | 'type' | 'orderId'> & {
+        type: NotificationTypeEnum.ORDER;
+        /** Set on every customer row: the order the bell is about. */
+        orderId: string;
+    };
+    /**
+     * Web `GET /notifications`: the caller's own rows, newest first by
+     * `createdAt`. An `offSet` outside the caller's own key range is
+     * `400 INVALID_CURSOR`; one inside it resumes from that position, whether
+     * or not a row with that id still exists.
+     */
+    interface WebGetNotificationsResponse {
+        message: string;
+        data: CustomerNotification[];
+        /** The last row's `notificationId`; send it back as `?offSet=`. Absent = end of list. */
+        LastEvaluatedKey?: string;
+    }
+    /** Web `POST /notifications` (single, or `all: true`). */
+    interface WebPostNotificationsResponse {
+        message: string;
+        data: CustomerNotification[];
+        /** `all: true` only. */
+        updatedCount?: number;
+        /** `all: true` only — `true` means call again. */
+        hasMore?: boolean;
+    }
+    /**
+     * Customer socket frames, action `notifications`: one row as it is now
+     * stored (its `read` is the stored value, so a mark-unread reads `false`), or
+     * the mark-all summary.
+     */
+    type CustomerNotificationFrame = CustomerNotification | {
+        storeId: string;
+        customerId: string;
+        bulkRead: true;
+        updatedCount: number;
+        hasMore: boolean;
+        /** Every row this call marked read (their `notificationId`); patch these, no refetch needed. */
+        notificationIds: string[];
+    };
     /**
      * What the outbound seam (`notify()`) knew about one call the moment its
      * transport returned. It is never a delivery receipt: `enqueued` and

package/dist/notification.js

@@ -197,3 +197,11 @@ export var NotificationTypeEnum;
      */
     NotificationTypeEnum["PAYMENT_ATTEMPT_RESOLUTION"] = "PAYMENT_ATTEMPT_RESOLUTION";
 })(NotificationTypeEnum || (NotificationTypeEnum = {}));
+/**
+ * The notification types a CUSTOMER bell can carry today; each links through
+ * `orderId`. Adding one means a new {@link CustomerNotification} member with its
+ * own link field — the storefront maps type → route from this list.
+ */
+export const CUSTOMER_NOTIFICATION_TYPES = [NotificationTypeEnum.ORDER];
+/** Web `GET /notifications` page ceiling and default (`?Limit=`). */
+export const WEB_NOTIFICATIONS_MAX_LIMIT = 500;

package/dist/order.d.ts

@@ -2137,6 +2137,24 @@ declare global {
          */
         basket: Cart | null;
     }
+    /**
+     * `data` of the storefront's `409 CART_CHANGED_SINCE_CONFIRM` — a web
+     * `POST /orders` that sent {@link StorefrontOrderCreateRequest.expectedCartId}
+     * or {@link StorefrontOrderCreateRequest.expectedCartVersion} against a cart
+     * that is no longer the one the shopper confirmed. It carries no cart: re-read
+     * it (`GET /basket`) and confirm again under a NEW `Idempotency-Key`.
+     */
+    interface CartChangedSinceConfirmData {
+        /**
+         * The confirmed cart's stored `version` as the server now reads it — a
+         * row with no stored `version` reads as `0`. `null` when the confirmed cart
+         * is no longer the stored cart: it is gone, or a different cart replaced
+         * it. ⚠️ On `null` the order may already exist (the confirmed cart is
+         * deleted by its own checkout), so check the shopper's orders before
+         * letting them retry.
+         */
+        currentCartVersion: number | null;
+    }
     /**
      * `data` of `409 CART_CUSTOMER_MISMATCH` — a create that sent
      * {@link CreateOrderRequest.expectedCartVersion} for a cart that carries a
@@ -2358,6 +2376,25 @@ declare global {
         };
         /** Persist `deliveryAddress` as the customer's default. Directive only, never stored. */
         saveAsDefault?: boolean;
+        /**
+         * The `cartId` of the cart the shopper confirmed (`CART` + 6-10 digits).
+         * Omit it ONLY when that cart had none (a legacy cart). ⚠️ Compared
+         * together with {@link expectedCartVersion} as ONE cart identity: a body
+         * sending the version without this field means "the cart I confirmed had
+         * no `cartId`", so a stored cart that has one is refused. A checkout
+         * deletes its cart and the next add mints a NEW `cartId` at `version: 1`,
+         * so a version alone does not identify a cart — always send this when the
+         * rendered cart has one. A mismatch is `409 CART_CHANGED_SINCE_CONFIRM`.
+         */
+        expectedCartId?: string;
+        /**
+         * The `version` of the cart the shopper confirmed, an integer ≥ 1. Omit it
+         * when that cart had none. Refused `409 CART_CHANGED_SINCE_CONFIRM` when
+         * the stored cart's version (absent reads as `0`) differs, and re-asserted
+         * at the commit, so a write between the server's read and the order
+         * transaction refuses too.
+         */
+        expectedCartVersion?: number;
     }
     interface ZebraTag {
         orderId: string;
@@ -2730,12 +2767,26 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  *   Storefront checkout carries `data: {}` and refuses before the cart read.
  *
  * Storefront checkout business refusals. None allocates an order
- * id, redeems a coupon or writes an order; none is logged as an error:
+ * id, redeems a coupon or writes an order; none is logged as an error —
+ * except `CART_CHANGED_SINCE_CONFIRM` refused at commit, as its entry says:
  * - `DELIVERY_METHOD_NOT_FOUND` · 400 — `deliveryMethod` is not in the store's
  *   delivery catalogue, including an absent/empty catalogue. `data: {}`;
  *   refused before reading the cart.
  * - `ORDER_INVALID_CART` · 400 — the normalized cart has no finite numeric
  *   `totals.grandTotal`. `data: {}`; refused before repricing/allocation.
+ * - `CART_CHANGED_SINCE_CONFIRM` · 409 — the body sent `expectedCartId` /
+ *   `expectedCartVersion` and the stored cart is not the cart the shopper
+ *   confirmed (gone, replaced by another `cartId`, or at another `version`);
+ *   `data` is `CartChangedSinceConfirmData` and carries no cart. Distinct from
+ *   `ORDER_INVALID_CART` (a non-finite total) and from the operator's
+ *   `CART_REVISION_STALE` / `CART_VERSION_*` (whose `data.basket` keeps
+ *   `cost`). Decided at TWO points: right after the server's cart read, with
+ *   nothing written and nothing logged; and at the commit, when the cart moved
+ *   between the read and the write — then no order committed, but the order id
+ *   allocated before the commit is consumed, a coupon redeemed before the
+ *   commit is not released, and an ERROR row is logged.
+ *   Re-read the cart and confirm again under a new `Idempotency-Key`; on
+ *   `currentCartVersion: null` check the shopper's orders first.
  * - `ORDER_BELOW_MINIMUM_PURCHASE` · 400 — after repricing has confirmed the
  *   cart, its grand total is below a finite positive `Number(customer.minBuy)`.
  *   Equality passes. `data: OrderBelowMinimumPurchaseData` carries minBuy,
@@ -2873,6 +2924,6 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  * `SUBSCRIPTION_READONLY`) sit on the order CREATE leg only: an edit is not a new
  * order, so `bareOrderPostHandler` routes past `requireMetered` entirely.
  */
-export declare const ORDER_ERROR_CODES: readonly ["ORDER_COST_DENOMINATION_UNKNOWN", "SERVICE_ORDER_DELIVERY_MANAGED", "ORDER_NOT_FOUND", "ORDER_LOCKED", "ORDER_NOT_READY", "ORDER_DELIVERED_ANOTHER_DAY", "ORDER_DELIVERY_STATE_UNCHANGED", "ORDER_ILLEGAL_TRANSITION", "ORDER_VERSION_CONFLICT", "CUSTOMER_NOT_FOUND", "CUSTOMER_MERGED", "ORDER_HAS_NO_CUSTOMER", "CUSTOMER_ANONYMIZED", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "PAYMENT_SETTLED_ON_ANOTHER_ORDER", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "SHIPMENT_QUANTITY_EXCEEDED", "SHIPMENT_LINE_MISMATCH", "SHIPMENT_NOT_FOUND", "SHIPMENT_LIMIT_REACHED", "SHIPMENT_TOO_LARGE", "ORDER_FULFILMENT_EXTERNAL", "SHIPMENT_FAILED", "ADMIN_REQUIRED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENT_RESPONSE_NOT_CACHED", "ORDER_CANCELLATION_NOT_PROTECTED", "ORDER_CANCELLATION_COMMITTED", "ORDER_CANCELLATION_LOCKED", "ORDER_CANCELLATION_TOO_LARGE", "ORDER_CANCELLATION_FAILED", "SALE_LEDGER_RETRACTION_REFUSED", "SALE_LEDGER_ROW_NOT_OWNED", "PRODUCT_NOT_FOUND", "PRODUCT_SALE_LIMIT_EXCEEDED", "PRODUCT_SALE_LIMIT_INVALID", "DEPOSIT_SOURCE_NOT_ALLOWED", "DEPOSIT_CURRENCY_MISMATCH", "DEPOSIT_EXCEEDS_TOTAL", "DEPOSIT_FREEZE_REQUIRES_INVOICE", "DEPOSIT_FREEZE_INVOICE_PENDING", "DEPOSIT_CHARACTERIZATION_CONFLICT", "DEPOSIT_FREEZE_INVOICE_NOT_QUALIFYING", "DEPOSIT_INVOICED_ORDER_MUST_FREEZE", "DEPOSIT_FROZEN_ORDER_MUST_FREEZE", "DEPOSIT_REFERENCE_IS_LINKED_PAYMENT", "DEPOSIT_DUPLICATE_REFERENCE", "TILL_TENDER_REQUIRES_DEPOSIT", "PAYMENT_REFERENCED_BY_DEPOSIT", "ORDER_HAS_UNREFUNDED_DEPOSIT", "ORDER_PRICE_FROZEN", "DEPOSIT_NOT_FOUND", "DEPOSIT_ALREADY_REFUNDED", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_REVISION_STALE", "UNIT_QUANTITY_UNREPRESENTABLE", "KIT_RECIPE_CHANGED", "CART_PROMOTION_UNAVAILABLE", "ORDER_HAS_KIT_LINES", "ORDER_TARGET_REQUIRED", "ORDER_SOURCE_CONFLICT", "ORDER_CUSTOMER_REQUIRED", "BASKET_EMPTY", "BASKET_CHANGED_DURING_CHECKOUT", "CART_VERSION_CREATE_ONLY", "CART_VERSION_REQUIRES_CART_ID", "CART_REVISION_STALE", "CART_CUSTOMER_MISMATCH", "COUNTER_SALE_CREATE_ONLY", "SOLD_AT_CREATE_ONLY", "SOLD_AT_IN_FUTURE", "ORDER_TENDER_CREATE_ONLY", "CREDIT_OVERRIDE_CREATE_ONLY", "ON_ACCOUNT_CREATE_ONLY", "ON_ACCOUNT_WITH_TENDERS", "TENDERS_REQUIRE_COUNTER_SALE", "LINES_REQUIRE_COUNTER_SALE", "PRODUCT_COST_UNKNOWN", "PRICE_CHANGE_DISABLED", "LINE_DISCOUNT_EXCEEDS_MAX", "CUSTOMER_DISABLED", "SHIFT_NOT_AVAILABLE", "SOLD_AT_OUTSIDE_SHIFT", "ORDER_CURRENCY_NOT_SUBSCRIBED", "PAYMENT_METHODS_NOT_CONFIGURED", "PAYMENT_METHOD_NOT_FOUND", "PAYMENT_METHOD_UNAVAILABLE", "CART_PRICES_CHANGED", "ORDER_ID_COLLISION", "DELIVERY_METHOD_NOT_FOUND", "ORDER_BELOW_MINIMUM_PURCHASE", "ORDER_INVALID_CART", "EMAIL_VERIFICATION_REQUIRED", "ACCOUNT_DISABLED", "CUSTOMER_ACCESS_PENDING", "CUSTOMER_ACCESS_REJECTED", "CURRENCY_MISMATCH", "SHIFT_NOT_OPEN", "ORDER_DISCOUNT_AFTER_INVOICE", "ORDER_DISCOUNT_ON_SERVICE_ORDER", "ORDER_DISCOUNT_ON_MARKETPLACE_ORDER", "ORDER_INVOICE_METHOD_OUTSTANDING_FACTURA", "ORDER_SERVICE_PERIOD_AFTER_INVOICE", "ORDER_ATTEMPT_COMMITTED", "ORDER_ATTEMPT_ABANDONED", "ORDER_ATTEMPT_KEY_EXPIRED", "ORDER_ATTEMPT_KEY_SCOPE_MISMATCH", "ORDER_COMPLETION_ATTEMPT_COMMITTED", "ORDER_COMPLETION_ATTEMPT_ABANDONED"];
+export declare const ORDER_ERROR_CODES: readonly ["ORDER_COST_DENOMINATION_UNKNOWN", "SERVICE_ORDER_DELIVERY_MANAGED", "ORDER_NOT_FOUND", "ORDER_LOCKED", "ORDER_NOT_READY", "ORDER_DELIVERED_ANOTHER_DAY", "ORDER_DELIVERY_STATE_UNCHANGED", "ORDER_ILLEGAL_TRANSITION", "ORDER_VERSION_CONFLICT", "CUSTOMER_NOT_FOUND", "CUSTOMER_MERGED", "ORDER_HAS_NO_CUSTOMER", "CUSTOMER_ANONYMIZED", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "PAYMENT_SETTLED_ON_ANOTHER_ORDER", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "SHIPMENT_QUANTITY_EXCEEDED", "SHIPMENT_LINE_MISMATCH", "SHIPMENT_NOT_FOUND", "SHIPMENT_LIMIT_REACHED", "SHIPMENT_TOO_LARGE", "ORDER_FULFILMENT_EXTERNAL", "SHIPMENT_FAILED", "ADMIN_REQUIRED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENT_RESPONSE_NOT_CACHED", "ORDER_CANCELLATION_NOT_PROTECTED", "ORDER_CANCELLATION_COMMITTED", "ORDER_CANCELLATION_LOCKED", "ORDER_CANCELLATION_TOO_LARGE", "ORDER_CANCELLATION_FAILED", "SALE_LEDGER_RETRACTION_REFUSED", "SALE_LEDGER_ROW_NOT_OWNED", "PRODUCT_NOT_FOUND", "PRODUCT_SALE_LIMIT_EXCEEDED", "PRODUCT_SALE_LIMIT_INVALID", "DEPOSIT_SOURCE_NOT_ALLOWED", "DEPOSIT_CURRENCY_MISMATCH", "DEPOSIT_EXCEEDS_TOTAL", "DEPOSIT_FREEZE_REQUIRES_INVOICE", "DEPOSIT_FREEZE_INVOICE_PENDING", "DEPOSIT_CHARACTERIZATION_CONFLICT", "DEPOSIT_FREEZE_INVOICE_NOT_QUALIFYING", "DEPOSIT_INVOICED_ORDER_MUST_FREEZE", "DEPOSIT_FROZEN_ORDER_MUST_FREEZE", "DEPOSIT_REFERENCE_IS_LINKED_PAYMENT", "DEPOSIT_DUPLICATE_REFERENCE", "TILL_TENDER_REQUIRES_DEPOSIT", "PAYMENT_REFERENCED_BY_DEPOSIT", "ORDER_HAS_UNREFUNDED_DEPOSIT", "ORDER_PRICE_FROZEN", "DEPOSIT_NOT_FOUND", "DEPOSIT_ALREADY_REFUNDED", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_REVISION_STALE", "UNIT_QUANTITY_UNREPRESENTABLE", "KIT_RECIPE_CHANGED", "CART_PROMOTION_UNAVAILABLE", "ORDER_HAS_KIT_LINES", "ORDER_TARGET_REQUIRED", "ORDER_SOURCE_CONFLICT", "ORDER_CUSTOMER_REQUIRED", "BASKET_EMPTY", "BASKET_CHANGED_DURING_CHECKOUT", "CART_VERSION_CREATE_ONLY", "CART_VERSION_REQUIRES_CART_ID", "CART_REVISION_STALE", "CART_CUSTOMER_MISMATCH", "COUNTER_SALE_CREATE_ONLY", "SOLD_AT_CREATE_ONLY", "SOLD_AT_IN_FUTURE", "ORDER_TENDER_CREATE_ONLY", "CREDIT_OVERRIDE_CREATE_ONLY", "ON_ACCOUNT_CREATE_ONLY", "ON_ACCOUNT_WITH_TENDERS", "TENDERS_REQUIRE_COUNTER_SALE", "LINES_REQUIRE_COUNTER_SALE", "PRODUCT_COST_UNKNOWN", "PRICE_CHANGE_DISABLED", "LINE_DISCOUNT_EXCEEDS_MAX", "CUSTOMER_DISABLED", "SHIFT_NOT_AVAILABLE", "SOLD_AT_OUTSIDE_SHIFT", "ORDER_CURRENCY_NOT_SUBSCRIBED", "PAYMENT_METHODS_NOT_CONFIGURED", "PAYMENT_METHOD_NOT_FOUND", "PAYMENT_METHOD_UNAVAILABLE", "CART_PRICES_CHANGED", "ORDER_ID_COLLISION", "DELIVERY_METHOD_NOT_FOUND", "ORDER_BELOW_MINIMUM_PURCHASE", "ORDER_INVALID_CART", "CART_CHANGED_SINCE_CONFIRM", "EMAIL_VERIFICATION_REQUIRED", "ACCOUNT_DISABLED", "CUSTOMER_ACCESS_PENDING", "CUSTOMER_ACCESS_REJECTED", "CURRENCY_MISMATCH", "SHIFT_NOT_OPEN", "ORDER_DISCOUNT_AFTER_INVOICE", "ORDER_DISCOUNT_ON_SERVICE_ORDER", "ORDER_DISCOUNT_ON_MARKETPLACE_ORDER", "ORDER_INVOICE_METHOD_OUTSTANDING_FACTURA", "ORDER_SERVICE_PERIOD_AFTER_INVOICE", "ORDER_ATTEMPT_COMMITTED", "ORDER_ATTEMPT_ABANDONED", "ORDER_ATTEMPT_KEY_EXPIRED", "ORDER_ATTEMPT_KEY_SCOPE_MISMATCH", "ORDER_COMPLETION_ATTEMPT_COMMITTED", "ORDER_COMPLETION_ATTEMPT_ABANDONED"];
 export type OrderErrorCode = (typeof ORDER_ERROR_CODES)[number];
 export {};

package/dist/order.js

@@ -365,12 +365,26 @@ export const orderFulfilmentProgress = (order) => {
  *   Storefront checkout carries `data: {}` and refuses before the cart read.
  *
  * Storefront checkout business refusals. None allocates an order
- * id, redeems a coupon or writes an order; none is logged as an error:
+ * id, redeems a coupon or writes an order; none is logged as an error —
+ * except `CART_CHANGED_SINCE_CONFIRM` refused at commit, as its entry says:
  * - `DELIVERY_METHOD_NOT_FOUND` · 400 — `deliveryMethod` is not in the store's
  *   delivery catalogue, including an absent/empty catalogue. `data: {}`;
  *   refused before reading the cart.
  * - `ORDER_INVALID_CART` · 400 — the normalized cart has no finite numeric
  *   `totals.grandTotal`. `data: {}`; refused before repricing/allocation.
+ * - `CART_CHANGED_SINCE_CONFIRM` · 409 — the body sent `expectedCartId` /
+ *   `expectedCartVersion` and the stored cart is not the cart the shopper
+ *   confirmed (gone, replaced by another `cartId`, or at another `version`);
+ *   `data` is `CartChangedSinceConfirmData` and carries no cart. Distinct from
+ *   `ORDER_INVALID_CART` (a non-finite total) and from the operator's
+ *   `CART_REVISION_STALE` / `CART_VERSION_*` (whose `data.basket` keeps
+ *   `cost`). Decided at TWO points: right after the server's cart read, with
+ *   nothing written and nothing logged; and at the commit, when the cart moved
+ *   between the read and the write — then no order committed, but the order id
+ *   allocated before the commit is consumed, a coupon redeemed before the
+ *   commit is not released, and an ERROR row is logged.
+ *   Re-read the cart and confirm again under a new `Idempotency-Key`; on
+ *   `currentCartVersion: null` check the shopper's orders first.
  * - `ORDER_BELOW_MINIMUM_PURCHASE` · 400 — after repricing has confirmed the
  *   cart, its grand total is below a finite positive `Number(customer.minBuy)`.
  *   Equality passes. `data: OrderBelowMinimumPurchaseData` carries minBuy,
@@ -631,6 +645,8 @@ export const ORDER_ERROR_CODES = [
     'DELIVERY_METHOD_NOT_FOUND',
     'ORDER_BELOW_MINIMUM_PURCHASE',
     'ORDER_INVALID_CART',
+    // The storefront's confirmed-cart pin (`StorefrontOrderCreateRequest.expectedCartId` / `expectedCartVersion`).
+    'CART_CHANGED_SINCE_CONFIRM',
     'EMAIL_VERIFICATION_REQUIRED',
     'ACCOUNT_DISABLED',
     'CUSTOMER_ACCESS_PENDING',

package/dist/store.d.ts

@@ -1222,6 +1222,14 @@ declare global {
          * until they verify. That is the tenant's decision to make, but a
          * settings UI should say so rather than presenting it as a neutral
          * switch.
+         *
+         * Web `GET /store` (and the storefront preview's store frame) ALWAYS
+         * carries it as a boolean, `true` only when the stored value is exactly
+         * `true` — absent, `false` or any other stored value reads `false`, the
+         * same test checkout applies. A storefront reads it to prompt for
+         * verification before checkout rather than after the
+         * `403 EMAIL_VERIFICATION_REQUIRED`. It is not on the customer `stores`
+         * socket frame; the next `GET /store` picks up a change.
          */
         requireEmailVerification?: boolean;
     }

package/package.json

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