sinfactura-types 1.10.480 → 1.10.481

package/dist/audit.d.ts

@@ -122,6 +122,13 @@ declare global {
      * would leave every historical row outside the type.
      */
      | 'mercadopago.dynamicQr.create' | 'rma_requested' | 'rma_authorized' | 'rma_rejected' | 'rma_received' | 'rma_settled' | 'rma_tracking_updated'
+    /**
+     * A partial or completing shipment was recorded (`POST /orders { mode:
+     * 'shipment' }`); the completing one also writes `order_delivered`.
+     */
+     | 'order_shipment_created'
+    /** A shipment was voided; when the order was delivered, this un-delivered it. */
+     | 'order_shipment_voided'
     /** A customer rated the order. `after`: `surveyId`, `rating`, `comment` presence. */
      | 'survey_submitted'
     /** An operator changed `Order.comments`. Presence-only, both sides. */

package/dist/cjs/order.js

@@ -167,11 +167,13 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  *   `POST /invoices`, and the payment starts that carry no route tuple of their
  *   own (Stripe `POST /stripe`, the MercadoPago Preference and Point intent) —
  *   this is their catalogue. Nothing was written and no provider was contacted.
- * - `ORDER_HAS_SHIPMENTS` · 409 — the order carries at least one shipment, so
- *   edit, disable, whole-order delivery (either direction) and a `readyAt`
- *   change are refused. Nothing was written.
+ * - `ORDER_HAS_SHIPMENTS` · 409 — the order carries at least one live
+ *   (un-voided) shipment, so edit, disable, whole-order delivery (either
+ *   direction) and a `readyAt` change are refused. Voiding every shipment lifts
+ *   it. Nothing was written.
  * - `ORDER_HAS_RETURNS` · 409 — the order carries at least one return and can no
- *   longer be edited. Nothing was written.
+ *   longer be edited, and none of its shipments can be voided. Nothing was
+ *   written.
  * - `ORDER_CANCELLATION_NOT_PROTECTED` · 409 — `mode: 'cancel'` on an order with
  *   no cancel guard of the current generation, or with the switch off; `disable`
  *   is the escape. Nothing was written.
@@ -181,6 +183,25 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  *   `OrderLockReason` rides in `message` as `reason: <r>` and, from
  *   `mode: 'cancel'`, also as a `reason` key. Nothing was written.
  *
+ * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
+ * any of them:
+ * - `SHIPMENT_QUANTITY_EXCEEDED` · 409 — a line would exceed its ordered
+ *   quantity; `data.lines[{ index, requested, remaining }]`.
+ * - `SHIPMENT_LINE_MISMATCH` · 409 — an `index` out of range, a `productId`
+ *   that is not the one at that position, a line with nothing ordered, or an
+ *   integer quantity against a weighed (fractional) line, which ships only
+ *   whole; `data.index`. A FRACTIONAL quantity that is not exactly a weighed
+ *   line's whole ordered quantity is `400 VALIDATION_FAILED` instead.
+ * - `SHIPMENT_NOT_FOUND` · 404 · `SHIPMENT_LIMIT_REACHED` · 409 (50 live
+ *   shipments per order; a void frees its slot)
+ * - `SHIPMENT_TOO_LARGE` · 409 — the shipment's DynamoDB condition would pass
+ *   the 4 KB expression cap; only an order past 49 lines can reach it. Split
+ *   the shipment into smaller ones.
+ * - `ORDER_FULFILMENT_EXTERNAL` · 409 — a MercadoLibre order; its fulfilment
+ *   axis belongs to the marketplace sync.
+ * - `SHIPMENT_FAILED` · 502 — an unclassified write failure, logged.
+ * - `IDEMPOTENCY_KEY_REQUIRED` · 400 — both shipment modes require the header.
+ *
  * Idempotency refusals, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 409
  * - `IDEMPOTENCY_IN_PROGRESS` · 409 · `IDEMPOTENCY_LOCK_CONTENTION` · 409
@@ -212,6 +233,14 @@ exports.ORDER_ERROR_CODES = [
     'ORDER_CANCELLED',
     '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',
+    'IDEMPOTENCY_KEY_REQUIRED',
     'INVALID_IDEMPOTENCY_KEY',
     'IDEMPOTENCY_KEY_REUSE',
     'IDEMPOTENCY_IN_PROGRESS',

package/dist/customer.d.ts

@@ -671,7 +671,9 @@ declare global {
      *
      * Answered by `POST /account` (a movement), `DELETE /account`, `POST` and
      * `DELETE /payments/{source}/{paymentId}/link` (link with credit, unlink),
-     * and `POST /orders` (create, `mode: 'delivery'`, `mode: 'return'`).
+     * and `POST /orders` (create, `mode: 'delivery'`, `mode: 'return'`, and the
+     * `mode: 'shipment'` that completes an order or `mode: 'shipment-void'` that
+     * un-delivers one).
      *
      * HOW it is decided differs by writer, and only the first kind covers a merge
      * that lands after the handler's read:

package/dist/order.d.ts

@@ -194,7 +194,11 @@ declare global {
          */
         fulfilledQuantity?: number;
     }
-    /** A shipment's lifecycle: `voided` shipments stay listed but hand over nothing. */
+    /**
+     * A shipment's lifecycle. A void marks the SHIPMENT row `voided` (kept as
+     * history, listed by `GET /orders?mode=shipments`) and removes its summary
+     * from `Order.shipments`, so a summary on the order is always `active`.
+     */
     type OrderShipmentState = 'active' | 'voided';
     /** Carrier tracking an operator attaches to a shipment — every field optional. */
     interface OrderShipmentTracking {
@@ -203,9 +207,10 @@ declare global {
         trackingUrl?: string;
     }
     /**
-     * Bounded, embedded projection of one shipment on its order row. The
+     * Bounded, embedded projection of one LIVE shipment on its order row. The
      * canonical shipment row lives in its own partition; this summary is what
-     * the order-row locks read.
+     * the order-row locks read. A void removes it (`shipmentState` is therefore
+     * always `active` here); the voided row stays in the shipment partition.
      */
     interface OrderShipmentSummary {
         shipmentId: string;
@@ -216,6 +221,82 @@ declare global {
         units: number;
         tracking?: OrderShipmentTracking;
     }
+    /**
+     * One line of a shipment. `index` is the line's position in `Order.items`
+     * (the identity returns use too); `productId` pins that position to the
+     * product it held when the shipment was recorded.
+     */
+    interface OrderShipmentLine {
+        index: number;
+        productId: string;
+        /**
+         * Units handed over. A positive integer, except that a line whose ordered
+         * `quantity` is fractional (a weighed product) ships whole, in one
+         * shipment, with exactly its ordered quantity.
+         */
+        quantity: number;
+    }
+    /**
+     * The canonical shipment row, as `GET /orders?mode=shipments` returns it —
+     * operator-only. The customer sees only the `OrderShipmentSummary` on the
+     * order row and `items[].fulfilledQuantity`; `note`, `createdBy` and the void
+     * fields never leave this row.
+     */
+    interface OrderShipment {
+        shipmentId: string;
+        orderId: string;
+        storeId: string;
+        lines: OrderShipmentLine[];
+        tracking?: OrderShipmentTracking;
+        /** Operator-only free text. */
+        note?: string;
+        shipmentState: OrderShipmentState;
+        createdAt: number;
+        /** The operator's `userId`. */
+        createdBy: string;
+        voidedAt?: number;
+        voidedBy?: string;
+        voidReason?: string;
+    }
+    /**
+     * `POST /orders { mode: 'shipment' }` — record a (partial) hand-over.
+     * `Idempotency-Key` header REQUIRED. The shipment that brings every line to
+     * its ordered quantity IS the order's delivery: it stamps `deliveredAt` and
+     * moves the whole-order receivable, once. A shipment moves no stock and is
+     * not a sale or an invoice.
+     */
+    interface OrderShipmentRequest {
+        mode: 'shipment';
+        orderId: string;
+        /** 1..`MAX_ORDER_PRODUCT_LINES`, each `index` at most once. */
+        lines: OrderShipmentLine[];
+        tracking?: OrderShipmentTracking;
+        /** ≤ 500 chars, operator-only. */
+        note?: string;
+        /** SMS the customer when THIS shipment completes the order. */
+        sendSms?: boolean;
+    }
+    /**
+     * `POST /orders { mode: 'shipment-void' }` — the only reversal. ADMIN or
+     * MANAGER; `Idempotency-Key` header REQUIRED. Restores the shipment's lines,
+     * marks its row `voided` and REMOVES its summary from `Order.shipments`, so
+     * an order whose every shipment was voided carries an empty list and is no
+     * longer shipment-locked. Voiding a shipment of a completed order un-delivers
+     * it (same calendar day only).
+     */
+    interface OrderShipmentVoidRequest {
+        mode: 'shipment-void';
+        orderId: string;
+        shipmentId: string;
+        /** Trimmed, 1..500 chars. */
+        reason: string;
+    }
+    /** `200` body `data` of both shipment modes. */
+    interface OrderShipmentResult {
+        shipment: OrderShipment;
+        /** The order as re-read after the commit; absent only if that re-read failed. */
+        order?: Order;
+    }
     interface Order extends CurrencyRateProvenance, CurrencyRateFreshness {
         storeId: string;
         orderId: string;
@@ -811,8 +892,11 @@ declare global {
          */
         returns?: ReturnSummary[];
         /**
-         * Bounded, embedded projections of this order's shipments (partial
-         * fulfilment). Server-owned — stripped from every client body.
+         * Bounded, embedded projections of this order's LIVE shipments (partial
+         * fulfilment), at most 50. Server-owned — stripped from every client body.
+         * A void removes its shipment's entry, so the list never carries a voided
+         * shipment; the full history, voided rows included, is
+         * `GET /orders?mode=shipments`.
          *
          * ⚠️ **A NON-EMPTY list LOCKS the order**: edit, disable, whole-order
          * delivery (both directions), a `readyAt` change and the customer's own
@@ -1681,11 +1765,13 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  *   `POST /invoices`, and the payment starts that carry no route tuple of their
  *   own (Stripe `POST /stripe`, the MercadoPago Preference and Point intent) —
  *   this is their catalogue. Nothing was written and no provider was contacted.
- * - `ORDER_HAS_SHIPMENTS` · 409 — the order carries at least one shipment, so
- *   edit, disable, whole-order delivery (either direction) and a `readyAt`
- *   change are refused. Nothing was written.
+ * - `ORDER_HAS_SHIPMENTS` · 409 — the order carries at least one live
+ *   (un-voided) shipment, so edit, disable, whole-order delivery (either
+ *   direction) and a `readyAt` change are refused. Voiding every shipment lifts
+ *   it. Nothing was written.
  * - `ORDER_HAS_RETURNS` · 409 — the order carries at least one return and can no
- *   longer be edited. Nothing was written.
+ *   longer be edited, and none of its shipments can be voided. Nothing was
+ *   written.
  * - `ORDER_CANCELLATION_NOT_PROTECTED` · 409 — `mode: 'cancel'` on an order with
  *   no cancel guard of the current generation, or with the switch off; `disable`
  *   is the escape. Nothing was written.
@@ -1695,6 +1781,25 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  *   `OrderLockReason` rides in `message` as `reason: <r>` and, from
  *   `mode: 'cancel'`, also as a `reason` key. Nothing was written.
  *
+ * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
+ * any of them:
+ * - `SHIPMENT_QUANTITY_EXCEEDED` · 409 — a line would exceed its ordered
+ *   quantity; `data.lines[{ index, requested, remaining }]`.
+ * - `SHIPMENT_LINE_MISMATCH` · 409 — an `index` out of range, a `productId`
+ *   that is not the one at that position, a line with nothing ordered, or an
+ *   integer quantity against a weighed (fractional) line, which ships only
+ *   whole; `data.index`. A FRACTIONAL quantity that is not exactly a weighed
+ *   line's whole ordered quantity is `400 VALIDATION_FAILED` instead.
+ * - `SHIPMENT_NOT_FOUND` · 404 · `SHIPMENT_LIMIT_REACHED` · 409 (50 live
+ *   shipments per order; a void frees its slot)
+ * - `SHIPMENT_TOO_LARGE` · 409 — the shipment's DynamoDB condition would pass
+ *   the 4 KB expression cap; only an order past 49 lines can reach it. Split
+ *   the shipment into smaller ones.
+ * - `ORDER_FULFILMENT_EXTERNAL` · 409 — a MercadoLibre order; its fulfilment
+ *   axis belongs to the marketplace sync.
+ * - `SHIPMENT_FAILED` · 502 — an unclassified write failure, logged.
+ * - `IDEMPOTENCY_KEY_REQUIRED` · 400 — both shipment modes require the header.
+ *
  * Idempotency refusals, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 409
  * - `IDEMPOTENCY_IN_PROGRESS` · 409 · `IDEMPOTENCY_LOCK_CONTENTION` · 409
@@ -1710,6 +1815,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_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", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "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"];
+export declare const ORDER_ERROR_CODES: readonly ["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", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "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", "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"];
 export type OrderErrorCode = (typeof ORDER_ERROR_CODES)[number];
 export {};

package/dist/order.js

@@ -160,11 +160,13 @@ export const orderFulfilmentProgress = (order) => {
  *   `POST /invoices`, and the payment starts that carry no route tuple of their
  *   own (Stripe `POST /stripe`, the MercadoPago Preference and Point intent) —
  *   this is their catalogue. Nothing was written and no provider was contacted.
- * - `ORDER_HAS_SHIPMENTS` · 409 — the order carries at least one shipment, so
- *   edit, disable, whole-order delivery (either direction) and a `readyAt`
- *   change are refused. Nothing was written.
+ * - `ORDER_HAS_SHIPMENTS` · 409 — the order carries at least one live
+ *   (un-voided) shipment, so edit, disable, whole-order delivery (either
+ *   direction) and a `readyAt` change are refused. Voiding every shipment lifts
+ *   it. Nothing was written.
  * - `ORDER_HAS_RETURNS` · 409 — the order carries at least one return and can no
- *   longer be edited. Nothing was written.
+ *   longer be edited, and none of its shipments can be voided. Nothing was
+ *   written.
  * - `ORDER_CANCELLATION_NOT_PROTECTED` · 409 — `mode: 'cancel'` on an order with
  *   no cancel guard of the current generation, or with the switch off; `disable`
  *   is the escape. Nothing was written.
@@ -174,6 +176,25 @@ export const orderFulfilmentProgress = (order) => {
  *   `OrderLockReason` rides in `message` as `reason: <r>` and, from
  *   `mode: 'cancel'`, also as a `reason` key. Nothing was written.
  *
+ * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
+ * any of them:
+ * - `SHIPMENT_QUANTITY_EXCEEDED` · 409 — a line would exceed its ordered
+ *   quantity; `data.lines[{ index, requested, remaining }]`.
+ * - `SHIPMENT_LINE_MISMATCH` · 409 — an `index` out of range, a `productId`
+ *   that is not the one at that position, a line with nothing ordered, or an
+ *   integer quantity against a weighed (fractional) line, which ships only
+ *   whole; `data.index`. A FRACTIONAL quantity that is not exactly a weighed
+ *   line's whole ordered quantity is `400 VALIDATION_FAILED` instead.
+ * - `SHIPMENT_NOT_FOUND` · 404 · `SHIPMENT_LIMIT_REACHED` · 409 (50 live
+ *   shipments per order; a void frees its slot)
+ * - `SHIPMENT_TOO_LARGE` · 409 — the shipment's DynamoDB condition would pass
+ *   the 4 KB expression cap; only an order past 49 lines can reach it. Split
+ *   the shipment into smaller ones.
+ * - `ORDER_FULFILMENT_EXTERNAL` · 409 — a MercadoLibre order; its fulfilment
+ *   axis belongs to the marketplace sync.
+ * - `SHIPMENT_FAILED` · 502 — an unclassified write failure, logged.
+ * - `IDEMPOTENCY_KEY_REQUIRED` · 400 — both shipment modes require the header.
+ *
  * Idempotency refusals, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 409
  * - `IDEMPOTENCY_IN_PROGRESS` · 409 · `IDEMPOTENCY_LOCK_CONTENTION` · 409
@@ -205,6 +226,14 @@ export const ORDER_ERROR_CODES = [
     'ORDER_CANCELLED',
     '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',
+    'IDEMPOTENCY_KEY_REQUIRED',
     'INVALID_IDEMPOTENCY_KEY',
     'IDEMPOTENCY_KEY_REUSE',
     'IDEMPOTENCY_IN_PROGRESS',

package/dist/webhook.d.ts

@@ -469,8 +469,10 @@ export interface OrderCreatedPayload {
  *
  * ── WHICH MOVES REACH THE WIRE ───────────────────────────────────────────
  *
- * REAL moves only, from the two single-order fulfilment seams: the operator
- * delivery/un-delivery toggle, and the MercadoLibre shipment sync. Three writers
+ * REAL moves only, from the single-order fulfilment seams: the operator
+ * delivery/un-delivery toggle, the shipment that completes an order and the
+ * shipment void that un-delivers one (`POST /orders { mode: 'shipment' |
+ * 'shipment-void' }`), and the MercadoLibre shipment sync. Three writers
  * touch `fulfilmentStatus` and are deliberately SILENT, because none is a
  * transition:
  *

package/package.json

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