sinfactura-types 1.10.439 → 1.10.441

package/dist/cjs/webhook.js

@@ -88,19 +88,12 @@ exports.WEBHOOK_DELIVERY_LOG_RETENTION_DAYS = 30;
 /**
  * Where an `order.created` event was minted.
  *
- * ⚠️ A CLOSED union, and rule 1 above applies to it with full force: a fifth
- * order-minting path cannot be added here without breaking every subscriber
- * that switches exhaustively — it mints `order.created.v2` instead. The four
- * members are the paths that EMIT — which is no longer the same thing as the
- * paths that WRITE an ORDER row.
- *
- * ⚠️ Converting an approved presupuesto (`convertPresupuestoToOrder`) mints an
- * ordinary order through the same `createOrder` every member above uses, and
- * emits nothing here — precisely BECAUSE adding a fifth member is the breaking
- * change the paragraph above forbids. The gap is known and deliberate, not an
- * oversight to be tidied: do not close it by quietly widening this tuple. The
- * rest of that path's fan-out (stock webhooks, notifications, the ML push) does
- * run; it is only this event that waits on the v2 decision.
+ * ⚠️ A CLOSED union: adding a source member breaks exhaustive subscribers and
+ * requires `order.created.v2` under rule 1. A new emit seam need not be a new
+ * source: `pos` means a counter sale, from `POST /orders` or a converted
+ * presupuesto. `presupuestoId` discriminates quote origin on the latter.
+ * Only POS, storefront and quote conversion use the shared `createOrder`;
+ * service delivery and MercadoLibre mint their rows through other calls.
  *
  * `service_delivery` is the repair-shop handover: a `ready` → `delivered`
  * transition mints an ordinary sale out of the counter lines the operator

package/dist/inventory.d.ts

@@ -57,25 +57,28 @@ declare global {
      * balance, cannot receive a transfer and is not addressable. A consumer that
      * treats the two as interchangeable will attribute stock to a string.
      *
-     * ⚠️ **Until a store is cut over, the per-location book does not converge on
-     * the store-wide one.** `Product.stock` is the store-wide scalar the order,
-     * sale and marketplace paths bump, alongside the store-wide income and sale
-     * ledgers those same paths append to. A store's `InventoryLevel` rows start at
-     * ZERO and, today, move only for the explicit inventory operations an operator
-     * runs — receipts, adjustments, write-offs, transfers, reservations and
-     * releases — so `Σ InventoryLevel.onHand` is not `Product.stock` and nothing
-     * reconciles the two. The api's ADR-0001 (`docs/DECISIONS.md`) makes the level
-     * the stock truth: behind the per-store `Store.stockAuthority` switch, each
-     * trading path moves over to updating the level in the same transaction as
-     * `Product.stock`, and a one-off seed at cutover puts the gap in the primary
-     * depósito. From then on `Product.stock = Σ onHand + units on open transfers`.
-     * Before it, the gap is expected and is not drift.
+     * ⚠️ **On a store not cut over (`Store.stockAuthority` absent or `'store'`),
+     * the per-location book does not converge on the store-wide one.**
+     * `Product.stock` is the store-wide scalar the order, sale and marketplace
+     * paths bump, alongside the store-wide income and sale ledgers those same
+     * paths append to. On such a store the `InventoryLevel` rows start at ZERO and
+     * move only for the explicit inventory operations an operator runs —
+     * receipts, adjustments, write-offs, transfers, reservations and releases — so
+     * `Σ InventoryLevel.onHand` is not `Product.stock`, nothing reconciles the
+     * two, and the gap is expected and is not drift. The api's ADR-0001
+     * (`docs/DECISIONS.md`) makes the level the stock truth: on a store cut over
+     * (`stockAuthority: 'depositos'`), the trading and ingress paths write the
+     * level in the same transaction as `Product.stock`, a one-off seed at cutover
+     * put the gap in the primary depósito, and the nightly stock reconciliation
+     * checks `Product.stock = Σ onHand + units on open transfers`.
      *
      * ⚠️ A consumer must not present a per-warehouse figure it cannot compute from
-     * the level rows themselves, and — more important now, not less — must not
-     * read an absent or zero level as "no stock". An absent cell is the NORMAL,
+     * the level rows themselves, and — on a store NOT cut over — must not read an
+     * absent or zero level as "no stock". There an absent cell is the NORMAL,
      * indefinite state for a product no operator has received into that location,
-     * while the store may be holding plenty of it. A screen that totals the levels
+     * while the store may be holding plenty of it. On a cut-over store every unit
+     * that moves writes its level, so an absent row IS zero units there — the
+     * storefront reads it that way. A screen that totals the levels
      * and captions the total "stock", or that subtracts that total from
      * `Product.stock` and captions the difference "missing", shows an operator a
      * shortfall with no cause and sends them hunting units nobody lost.

package/dist/webhook.d.ts

@@ -238,19 +238,12 @@ export interface ProductStockOutPayload {
 /**
  * Where an `order.created` event was minted.
  *
- * ⚠️ A CLOSED union, and rule 1 above applies to it with full force: a fifth
- * order-minting path cannot be added here without breaking every subscriber
- * that switches exhaustively — it mints `order.created.v2` instead. The four
- * members are the paths that EMIT — which is no longer the same thing as the
- * paths that WRITE an ORDER row.
- *
- * ⚠️ Converting an approved presupuesto (`convertPresupuestoToOrder`) mints an
- * ordinary order through the same `createOrder` every member above uses, and
- * emits nothing here — precisely BECAUSE adding a fifth member is the breaking
- * change the paragraph above forbids. The gap is known and deliberate, not an
- * oversight to be tidied: do not close it by quietly widening this tuple. The
- * rest of that path's fan-out (stock webhooks, notifications, the ML push) does
- * run; it is only this event that waits on the v2 decision.
+ * ⚠️ A CLOSED union: adding a source member breaks exhaustive subscribers and
+ * requires `order.created.v2` under rule 1. A new emit seam need not be a new
+ * source: `pos` means a counter sale, from `POST /orders` or a converted
+ * presupuesto. `presupuestoId` discriminates quote origin on the latter.
+ * Only POS, storefront and quote conversion use the shared `createOrder`;
+ * service delivery and MercadoLibre mint their rows through other calls.
  *
  * `service_delivery` is the repair-shop handover: a `ready` → `delivered`
  * transition mints an ordinary sale out of the counter lines the operator
@@ -262,14 +255,14 @@ export declare const ORDER_CREATED_SOURCES: readonly ["pos", "storefront", "serv
 export type OrderCreatedSource = (typeof ORDER_CREATED_SOURCES)[number];
 /**
  * Payload for `order.created` — an ORDER row is durable, emitted from the
- * post-commit fan-out of each of the four paths that mint one.
+ * best-effort post-commit fan-out of each minting path.
  *
  * ── WHY THERE IS NO `total` AND NO `currency` ────────────────────────────
  *
  * Both were considered and both are deliberately ABSENT, and this is the
  * decision most likely to be "fixed" by someone who finds the figure sitting
  * in scope at a seam. It is not an availability problem — a total is reachable
- * at all four. It is a DENOMINATION problem:
+ * at every seam. It is a DENOMINATION problem:
  *
  *   - `Order.currency` is a catalogId (lowercase, e.g. `'ars'`, an FK to
  *     `PlatformCurrency`), while {@link PaymentReceivedWebhookPayload}'s
@@ -295,9 +288,12 @@ export type OrderCreatedSource = (typeof ORDER_CREATED_SOURCES)[number];
  * consumer's `outcome: 'created'` branch, so a record that commits the order
  * and then dies before the fan-out is redelivered as `outcome: 'updated'` and
  * emits nothing. The store users' new-order notification carries exactly the
- * same exposure on exactly the same branch. The other three legs are
- * exactly-once: each sits past a committed transaction inside the request that
- * made it.
+ * same exposure on exactly the same branch. The synchronous tails, including
+ * quote conversion, are also best-effort: a process can stop between commit
+ * and emit, and subscription-read/enqueue failures are warned and swallowed.
+ * A converted quote is not re-announced on replay. Delivery transport retries
+ * can duplicate a delivered event; there is no exactly-once external delivery
+ * or durable recovery guarantee.
  *
  * ⚠️ **No order EDIT emits.** This fires on the write that creates the row and
  * never again — not on a line change, a discount, a tender, a fulfilment move
@@ -306,6 +302,8 @@ export type OrderCreatedSource = (typeof ORDER_CREATED_SOURCES)[number];
 export interface OrderCreatedPayload {
     orderId: string;
     source: OrderCreatedSource;
+    /** Quote origin on converted counter sales only; omitted on every other path. */
+    presupuestoId?: string;
     /**
      * Server-stamped Unix milliseconds, taken at the post-commit emit.
      *
@@ -323,7 +321,7 @@ export interface OrderCreatedPayload {
     /**
      * The order's customer.
      *
-     * Present on the three synchronous legs without exception — a POS walk-in
+     * Present on the synchronous legs without exception — a POS walk-in
      * has no NAMED customer but is minted against the store's system customer
      * row, so `Order.customerId` is never empty. Absent only on the
      * MercadoLibre leg when the post-write order re-read came back empty: that

package/dist/webhook.js

@@ -85,19 +85,12 @@ export const WEBHOOK_DELIVERY_LOG_RETENTION_DAYS = 30;
 /**
  * Where an `order.created` event was minted.
  *
- * ⚠️ A CLOSED union, and rule 1 above applies to it with full force: a fifth
- * order-minting path cannot be added here without breaking every subscriber
- * that switches exhaustively — it mints `order.created.v2` instead. The four
- * members are the paths that EMIT — which is no longer the same thing as the
- * paths that WRITE an ORDER row.
- *
- * ⚠️ Converting an approved presupuesto (`convertPresupuestoToOrder`) mints an
- * ordinary order through the same `createOrder` every member above uses, and
- * emits nothing here — precisely BECAUSE adding a fifth member is the breaking
- * change the paragraph above forbids. The gap is known and deliberate, not an
- * oversight to be tidied: do not close it by quietly widening this tuple. The
- * rest of that path's fan-out (stock webhooks, notifications, the ML push) does
- * run; it is only this event that waits on the v2 decision.
+ * ⚠️ A CLOSED union: adding a source member breaks exhaustive subscribers and
+ * requires `order.created.v2` under rule 1. A new emit seam need not be a new
+ * source: `pos` means a counter sale, from `POST /orders` or a converted
+ * presupuesto. `presupuestoId` discriminates quote origin on the latter.
+ * Only POS, storefront and quote conversion use the shared `createOrder`;
+ * service delivery and MercadoLibre mint their rows through other calls.
  *
  * `service_delivery` is the repair-shop handover: a `ready` → `delivered`
  * transition mints an ordinary sale out of the counter lines the operator

package/package.json

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