sinfactura-types 1.10.113 → 1.10.115

package/dist/cart.d.ts

@@ -154,7 +154,7 @@ declare global {
      *   at the DynamoDB marshaller instead of at validation.
      * - `merge.items` is `min(1).max(50)`.
      */
-    type CartActionRequest = CartActionAddLine | CartActionChangeQuantity | CartActionRemoveLine | CartActionClear | CartActionMerge | CartActionSaveLine | CartActionRestoreLine;
+    type CartActionRequest = CartActionAddLine | CartActionChangeQuantity | CartActionRemoveLine | CartActionClear | CartActionMerge | CartActionSaveLine | CartActionRestoreLine | CartActionRemoveSavedLine;
     /**
      * WHICH cart an OPERATOR action acts on — the half of the operator request
      * that `CartActionRequest` cannot carry.
@@ -267,6 +267,37 @@ declare global {
         mode: 'restoreLine';
         lineId: string;
     }
+    /**
+     * Removes a line from `savedLines` OUTRIGHT — the shelf's own delete.
+     *
+     * ⚠️ It exists because `removeLine` does NOT reach a saved line. That verb
+     * filters `lines` only, so handing it a saved `lineId` is an idempotent no-op
+     * `200` and the shelf is untouched — which left restore-then-remove as the
+     * only path off `savedLines`, and that path is not always available:
+     *
+     * - On a cart at `MAX_CART_LINES` the restore is refused
+     *   `400 BASKET_LINE_LIMIT` and nothing is written, so a saved line on a full
+     *   ticket was unreachable by any sequence of actions.
+     * - Saved lines spend `MAX_CART_BYTES`, and once the row is over it `saveLine`
+     *   is refused too — so a shelf could become the thing consuming the budget
+     *   with no way to shrink it.
+     *
+     * This verb touches `savedLines` alone, so the LINE guard cannot refuse it
+     * (the active count does not change) and it is a genuine reduction against the
+     * BYTE guard. That makes it the shelf's recovery path, not merely its
+     * convenience.
+     *
+     * ⚠️ It does NOT return the line to the cart. `restoreLine` is that verb; this
+     * one discards. A UI must not offer them behind the same affordance.
+     *
+     * A `lineId` that is not in `savedLines` is a no-op `200`, matching
+     * `removeLine`, `saveLine` and `restoreLine`.
+     */
+    interface CartActionRemoveSavedLine extends CartActionBase {
+        mode: 'removeSavedLine';
+        /** Names a line in `savedLines` — NOT in `lines`. */
+        lineId: string;
+    }
     /**
      * Empties `lines` to `[]`.
      *
@@ -340,10 +371,60 @@ declare global {
         available: number;
         reason: 'insufficientStock' | 'notOffered';
     }
+    /**
+     * WHY a product the request named did not make it onto the cart.
+     *
+     * ⚠️ The distinction that matters is REMEDIABLE vs NOT. `cartFull` is the
+     * shopper's to fix — remove a line and send it again — while the other two are
+     * facts about the catalogue that retrying cannot change. `droppedSkus` alone
+     * could not express that, so every consumer rendered one message for all of
+     * them, and the one that told the shopper "product not found" for a cart that
+     * was merely full was both wrong and unactionable.
+     *
+     * ⚠️ `notOffered` deliberately shares its spelling with
+     * `CartLineAvailability.reason`, because it is the same fact — the product is
+     * hidden from this channel. Two half-aligned vocabularies for one condition is
+     * the outcome this naming exists to avoid.
+     *
+     * ⚠️ Treat an UNRECOGNISED reason as unremediable rather than discarding the
+     * entry: a reason added later must degrade, not vanish, and guessing
+     * "remediable" would invite a retry loop that cannot succeed.
+     */
+    interface CartLineDrop {
+        productId: string;
+        /**
+         * - `productUnavailable` — no product row resolved at all (deleted, or never
+         *   existed). Permanent from the caller's side.
+         * - `notOffered` — the product resolved but is `hiddenFromStorefront`, so it
+         *   is not sellable on this channel. Also permanent from the caller's side,
+         *   but a DIFFERENT fact: the product exists.
+         * - `cartFull` — the line was truncated because the resulting cart would
+         *   exceed the line cap. `merge` is the only action that truncates; every
+         *   other one refuses with `400 BASKET_LINE_LIMIT` instead. **Remediable.**
+         */
+        reason: 'productUnavailable' | 'notOffered' | 'cartFull';
+    }
     interface CartActionResponse {
         message: string;
         data: Cart;
+        /**
+         * ⚠️ KEPT, and kept as `string[]`. It is not replaced by `dropped` below
+         * and must not be: both consumers parse this as an array of strings today,
+         * and one of them filters non-strings out — so changing its element type
+         * would degrade that client to reporting NOTHING, silently, in the
+         * direction that hides the problem. The reason travels alongside instead.
+         */
         droppedSkus: string[];
+        /**
+         * The same drops as `droppedSkus`, each carrying WHY.
+         *
+         * ⚠️ REQUIRED and always present — an empty array when nothing dropped —
+         * for the same reason its two siblings are. One entry per entry in
+         * `droppedSkus`, in the same order, so a consumer that has already indexed
+         * one can zip them; new consumers should read this one and ignore
+         * `droppedSkus` entirely.
+         */
+        dropped: CartLineDrop[];
         availability: CartLineAvailability[];
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinfactura-types",
-  "version": "1.10.113",
+  "version": "1.10.115",
   "main": "dist/index.js",
   "type": "module",
   "types": "./dist/index.d.ts",