platform-types 1.10.718 → 1.10.719

package/dist/basket.d.ts

@@ -76,4 +76,27 @@ declare global {
  */
 export declare const BASKET_ERROR_CODES: readonly ["VALIDATION_FAILED", "FOREIGN_INDEX_KEY_ATTRIBUTE", "CART_TARGET_REQUIRED", "CART_NOT_FOUND", "CART_REVIEW_INCOMPLETE", "CART_REVIEW_UNAVAILABLE", "CART_NOT_PARKED", "CART_ALREADY_PARKED", "TERMINAL_INDEX_UNAVAILABLE", "PRODUCT_NOT_FOUND", "PRODUCT_COST_UNKNOWN", "UNIT_QUANTITY_NOT_WHOLE", "BASKET_VERSION_CONFLICT", "BASKET_LINE_LIMIT", "BASKET_SIZE_LIMIT", "UNKNOWN_LINE", "INVALID_PRICE", "LINE_DISCOUNT_NOT_ALLOWED", "LINE_DISCOUNT_EXCEEDS_MAX", "FX_CONVERSION_UNAVAILABLE", "COUPON_NOT_FOUND", "COUPON_NOT_ACTIVE", "COUPON_EXPIRED", "COUPON_EXHAUSTED", "COUPON_MIN_SUBTOTAL", "COUPON_REQUIRES_CUSTOMER", "COUPON_BUDGET_EXHAUSTED", "COUPON_RATE_LIMITED", "COUPON_CURRENCY_MISMATCH", "PROMOTION_NOT_FOUND", "PROMOTION_NOT_ACTIVE", "PROMOTION_NOT_STARTED", "PROMOTION_EXPIRED", "PROMOTION_NOT_CART_APPLICABLE"];
 export type BasketErrorCode = (typeof BASKET_ERROR_CODES)[number];
+/**
+ * The refusals the storefront's POST /basket { mode: 'resume', token } handler
+ * itself answers (an abandoned-cart recovery link). Middleware refusals
+ * (GATING_ERROR_CODES, STOREFRONT_UNAVAILABLE, validation) are separate, and so
+ * are the cart resolver's BasketErrorCode refusals, which the fold or
+ * reinstatement write forwards unchanged once ownership is proven (for example
+ * 409 BASKET_VERSION_CONFLICT, or 404 CART_NOT_FOUND carrying data.cartId when
+ * the fold target was deleted mid-request).
+ *
+ * - CART_RESUME_UNAVAILABLE (404): every reason the link cannot be honoured —
+ *   invalid or expired token, another store, a cart that is gone, converted,
+ *   owned by someone else, held by a till, or already folded into a cart that
+ *   has since gone — with one identical body, so a
+ *   forwarded email is never an existence oracle. Render one neutral message.
+ * - CART_RESUME_INCOMPLETE (503): the caller owns the cart, but whether a live
+ *   cart should receive the recovered lines could not be proven — the read of
+ *   the caller's carts stopped at its row ceiling (200 or more carts) or its
+ *   time budget, or the strong re-read contradicted the index's pick. Nothing
+ *   was written. A ceiling stop repeats until carts are reaped; the others
+ *   clear on retry.
+ */
+export declare const BASKET_RESUME_ERROR_CODES: readonly ["CART_RESUME_UNAVAILABLE", "CART_RESUME_INCOMPLETE"];
+export type BasketResumeErrorCode = (typeof BASKET_RESUME_ERROR_CODES)[number];
 export {};

package/dist/basket.js

@@ -46,3 +46,25 @@ export const BASKET_ERROR_CODES = [
     'PROMOTION_EXPIRED',
     'PROMOTION_NOT_CART_APPLICABLE',
 ];
+/**
+ * The refusals the storefront's POST /basket { mode: 'resume', token } handler
+ * itself answers (an abandoned-cart recovery link). Middleware refusals
+ * (GATING_ERROR_CODES, STOREFRONT_UNAVAILABLE, validation) are separate, and so
+ * are the cart resolver's BasketErrorCode refusals, which the fold or
+ * reinstatement write forwards unchanged once ownership is proven (for example
+ * 409 BASKET_VERSION_CONFLICT, or 404 CART_NOT_FOUND carrying data.cartId when
+ * the fold target was deleted mid-request).
+ *
+ * - CART_RESUME_UNAVAILABLE (404): every reason the link cannot be honoured —
+ *   invalid or expired token, another store, a cart that is gone, converted,
+ *   owned by someone else, held by a till, or already folded into a cart that
+ *   has since gone — with one identical body, so a
+ *   forwarded email is never an existence oracle. Render one neutral message.
+ * - CART_RESUME_INCOMPLETE (503): the caller owns the cart, but whether a live
+ *   cart should receive the recovered lines could not be proven — the read of
+ *   the caller's carts stopped at its row ceiling (200 or more carts) or its
+ *   time budget, or the strong re-read contradicted the index's pick. Nothing
+ *   was written. A ceiling stop repeats until carts are reaped; the others
+ *   clear on retry.
+ */
+export const BASKET_RESUME_ERROR_CODES = ['CART_RESUME_UNAVAILABLE', 'CART_RESUME_INCOMPLETE'];

package/dist/cart.d.ts

@@ -56,15 +56,17 @@ declare global {
         parkedBy?: string;
         /**
          * Epoch ms this ABANDONED cart's lines were folded into another cart by
-         * `POST /basket` `{ mode: 'resume' }`. Set once and never cleared.
+         * `POST /basket` `{ mode: 'resume' }`. Set once; cleared again only when the
+         * fold it was claimed for was REFUSED before writing anything (so the link
+         * can fold the lines on retry).
          *
          * ⚠️ **It is a CONSUMPTION marker, not a timestamp anyone should render.**
          * The fold uses `merge`, which SUMS, and the abandoned row survives with
          * its lines for as long as the recovery link does — so without a marker a
          * refresh, a back-navigation or a component that mounts twice would re-add
          * every quantity, for days. The resume write sets this under
-         * `attribute_not_exists(resumedAt)`, so exactly one caller can ever win and
-         * every replay answers the cart the shopper already has.
+         * `attribute_not_exists(resumedAt)`, so exactly one caller wins each claim
+         * and every replay answers the cart the shopper already has.
          *
          * ⚠️ Absent on the OTHER resume path — a shopper with no second cart has
          * their own cart reinstated in place, which adds nothing and needs no
@@ -806,12 +808,23 @@ declare global {
      * an email, is HMAC-signed, expires, and carries `{ storeId, cartId }` and
      * nothing about a person.
      *
-     * ⚠️ **Every refusal is the SAME 4xx and the same bare code** — an invalid or
-     * expired token, a cart that no longer exists, a cart already converted to an
-     * order, and a cart belonging to a DIFFERENT customer are indistinguishable on
-     * the wire, deliberately. A recovery email gets forwarded; the response must
-     * never tell the reader whether the cart is real. A consumer must therefore
-     * render exactly one neutral message and must not try to explain the failure.
+     * ⚠️ **Every refusal about the LINK is the SAME 404 and the same bare code**
+     * (`CART_RESUME_UNAVAILABLE`) — an invalid or expired token, a cart that no
+     * longer exists, a cart already converted to an order or already folded into
+     * a cart since gone, and a cart belonging to a DIFFERENT customer are
+     * indistinguishable on the wire, deliberately. A recovery email gets
+     * forwarded; the response must never tell the reader whether the cart is
+     * real. A consumer must therefore render exactly one neutral message for it
+     * and must not try to explain the failure.
+     *
+     * Only AFTER ownership is proven can two other kinds of refusal appear, and a
+     * consumer may treat them as retryable: `503 CART_RESUME_INCOMPLETE` (the
+     * caller's other carts could not all be read, so no fold-or-reinstate choice
+     * was made and nothing was written) and the cart resolver's own
+     * {@link BasketErrorCode} refusals, forwarded unchanged from the fold or
+     * reinstatement write (e.g. `409 BASKET_VERSION_CONFLICT`, `404
+     * CART_NOT_FOUND` for a target deleted mid-request). See
+     * `BASKET_RESUME_ERROR_CODES`.
      *
      * ⚠️ On success it answers the ordinary {@link CartActionResponse}. If the
      * caller already holds another cart with lines, the recovered lines are FOLDED

package/dist/cjs/basket.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BASKET_ERROR_CODES = void 0;
+exports.BASKET_RESUME_ERROR_CODES = exports.BASKET_ERROR_CODES = void 0;
 /**
  * Domain refusals from POST /baskets (replacement, named actions and park/resume)
  * and GET /baskets?mode=review. Check GATING_ERROR_CODES separately for middleware
@@ -49,3 +49,25 @@ exports.BASKET_ERROR_CODES = [
     'PROMOTION_EXPIRED',
     'PROMOTION_NOT_CART_APPLICABLE',
 ];
+/**
+ * The refusals the storefront's POST /basket { mode: 'resume', token } handler
+ * itself answers (an abandoned-cart recovery link). Middleware refusals
+ * (GATING_ERROR_CODES, STOREFRONT_UNAVAILABLE, validation) are separate, and so
+ * are the cart resolver's BasketErrorCode refusals, which the fold or
+ * reinstatement write forwards unchanged once ownership is proven (for example
+ * 409 BASKET_VERSION_CONFLICT, or 404 CART_NOT_FOUND carrying data.cartId when
+ * the fold target was deleted mid-request).
+ *
+ * - CART_RESUME_UNAVAILABLE (404): every reason the link cannot be honoured —
+ *   invalid or expired token, another store, a cart that is gone, converted,
+ *   owned by someone else, held by a till, or already folded into a cart that
+ *   has since gone — with one identical body, so a
+ *   forwarded email is never an existence oracle. Render one neutral message.
+ * - CART_RESUME_INCOMPLETE (503): the caller owns the cart, but whether a live
+ *   cart should receive the recovered lines could not be proven — the read of
+ *   the caller's carts stopped at its row ceiling (200 or more carts) or its
+ *   time budget, or the strong re-read contradicted the index's pick. Nothing
+ *   was written. A ceiling stop repeats until carts are reaped; the others
+ *   clear on retry.
+ */
+exports.BASKET_RESUME_ERROR_CODES = ['CART_RESUME_UNAVAILABLE', 'CART_RESUME_INCOMPLETE'];

package/package.json

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