sinfactura-types 1.10.443 → 1.10.445

package/dist/cjs/webhook.js

@@ -74,6 +74,7 @@ exports.WEBHOOK_EVENT_TYPES = [
     'invoice.generated',
     'customer.created',
     'customer.imported',
+    'order.financial_status_changed',
 ];
 /** Terminal outcomes for a print job. Closed union — a job printed, or it failed. */
 exports.PRINT_JOB_SETTLED_OUTCOMES = ['printed', 'failed'];

package/dist/inventory.d.ts

@@ -758,12 +758,15 @@ declare global {
      * locations is therefore SHORT by everything in transit, and that is correct
      * rather than a bug.
      *
-     * ⚠️ **Do not repair that shortfall by reaching for `Product.stock`.** The two
-     * are separate books with separate writers and they diverge permanently by
-     * design — see `Warehouse` — so subtracting one from the other produces a
-     * number of which in-transit units are only a small and unidentifiable part. A
-     * consumer that captions that difference "in transit", or "shrinkage", is
-     * labelling a gap it has not measured.
+     * ⚠️ **On a store not cut over, do not repair that shortfall by reaching for
+     * `Product.stock`.** With `Store.stockAuthority` absent or `'store'` the two
+     * are separate books with separate writers and they diverge by design — see
+     * `Warehouse` — so subtracting one from the other produces a number of which
+     * in-transit units are only a small and unidentifiable part. A consumer that
+     * captions that difference "in transit", or "shrinkage", is labelling a gap it
+     * has not measured. On a store cut over (`stockAuthority: 'depositos'`),
+     * `Product.stock − Σ onHand` IS the units on open transfers; any remainder is
+     * drift the nightly reconciliation already reports as `STOCK_DEPOSITO_DRIFT`.
      *
      * ⚠️ **`received` does NOT mean the received quantities equal the sent
      * quantities.** A short arrival the operator accepts as final closes the

package/dist/subscription.d.ts

@@ -77,15 +77,15 @@ declare global {
      * `Record<>`, `Exclude<>` against a tuple, a switch, an array literal whose
      * length is asserted.
      *
-     * ⚠️ **And a new member can be a WIRE change, not merely a wider type.** A
-     * consumer that validates a seed payload against the key count — the api does,
-     * with an exact `.length(FEATURE_KEYS.length)` — starts rejecting every
-     * payload written against the previous length the moment this union grows.
-     * That is deliberate there (loud at the seeding call, rather than a tier
-     * quietly missing a feature), but it means the caller must be updated in the
-     * same change. Adding a key is never only additive downstream.
+     * ⚠️ **And a new member is never only additive downstream.** The api holds no
+     * seed payload to grow any more — grants are code (`FEATURE_DEFINITIONS` and
+     * the total `PLAN_FEATURES` matrix), so a missing grant fails its `typecheck`
+     * — but the shared authorizer resolves entitlements from that matrix, so the
+     * key reaches a tenant only once `PlatformStack` deploys. A consumer that
+     * exhausts this union (a `switch`, a `Record<FeatureKey, …>`) still has to
+     * handle the new member in the same change.
      */
-    type FeatureKey = 'maxOrdersMonth' | 'maxInvoicesMonth' | 'maxProducts' | 'maxUsers' | 'maxCustomers' | 'maxWarehouses' | 'priceListsMax' | 'afipInvoicing' | 'suppliers' | 'domesticPayments' | 'stripePayments' | 'cashManagement' | 'importExport' | 'advancedReports' | 'customBranding' | 'prioritySupport' | 'whatsappCommerce' | 'aiFeatures' | 'mobileApp' | 'customDomain' | 'advancedPricing' | 'marketplaceChannels' | 'storefront' | 'loyalty' | 'marketing' | 'mandatory2fa';
+    type FeatureKey = 'maxOrdersMonth' | 'maxInvoicesMonth' | 'maxProducts' | 'maxUsers' | 'maxCustomers' | 'maxWarehouses' | 'priceListsMax' | 'webhooks' | 'afipInvoicing' | 'suppliers' | 'domesticPayments' | 'stripePayments' | 'cashManagement' | 'importExport' | 'advancedReports' | 'customBranding' | 'prioritySupport' | 'whatsappCommerce' | 'aiFeatures' | 'mobileApp' | 'customDomain' | 'advancedPricing' | 'marketplaceChannels' | 'storefront' | 'loyalty' | 'marketing' | 'mandatory2fa';
     /** Resolved entitlements for a specific tenant (matrix + overrides applied). */
     type ResolvedEntitlements = Record<FeatureKey, Entitlement>;
     /**

package/dist/webhook.d.ts

@@ -10,7 +10,7 @@
  * immediately subscribable — and a store that subscribes to an event with no
  * emit site gets silence it cannot distinguish from "nothing happened".
  */
-export declare const WEBHOOK_EVENT_TYPES: readonly ["print.queued", "print.received", "print.printed", "print.failed", "print.agent.connected", "print.agent.disconnected", "print.printer.online", "print.printer.offline", "print.job.settled", "payment.received", "product.stock_low", "product.stock_out", "order.created", "order.status_changed", "invoice.generated", "customer.created", "customer.imported"];
+export declare const WEBHOOK_EVENT_TYPES: readonly ["print.queued", "print.received", "print.printed", "print.failed", "print.agent.connected", "print.agent.disconnected", "print.printer.online", "print.printer.offline", "print.job.settled", "payment.received", "product.stock_low", "product.stock_out", "order.created", "order.status_changed", "invoice.generated", "customer.created", "customer.imported", "order.financial_status_changed"];
 export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
 /** Terminal outcomes for a print job. Closed union — a job printed, or it failed. */
 export declare const PRINT_JOB_SETTLED_OUTCOMES: readonly ["printed", "failed"];
@@ -347,36 +347,38 @@ export interface OrderCreatedPayload {
  * those are opposite operational signals. The axis is what disambiguates them,
  * so it is REQUIRED and is never inferred from the status spelling.
  *
- * ── WHY `axis` HAS EXACTLY ONE MEMBER TODAY ──────────────────────────────
+ * ── WHY `axis` HAS EXACTLY ONE MEMBER ────────────────────────────────────
  *
- * Only the FULFILMENT axis is shipped. `'financial'` is deliberately NOT
- * declared here, and this is the line most likely to be "helpfully" widened by
- * someone who reads the three-axis description above and assumes the union was
- * simply left unfinished.
+ * This event carries the FULFILMENT axis only. `'financial'` is deliberately
+ * NOT declared here, and this is the line most likely to be "helpfully" widened
+ * by someone who reads the three-axis description above and assumes the union
+ * was simply left unfinished.
  *
  * Rule 3 above is the reason: a declared value means "this can occur on a real
- * event", never "we intend to emit this later". Declaring `'financial'` before
- * a financial seam emits would publish a value no subscriber can ever observe
- * — the union equivalent of publishing an event nothing emits, and it would
- * read to an integrator as a branch worth writing and testing against.
- *
- * ⚠️ Adding `'financial'` LATER is a BREAKING change under rule 1 (it widens a
- * union an integrator may exhaustively switch on) and it is breaking whether or
- * not it was pre-announced here — pre-declaring buys nothing and costs honesty.
- * The financial axis ships behind rule 2 instead: either an announced widen, or
- * a new `order.status_changed.v2`. That decision belongs to whoever builds the
- * financial seam, with the settlement and payment-linking writers in front of
- * them; it is not owed in advance.
+ * event", never "we intend to emit this later". A financial move never rides
+ * this event — it has its own — so `'financial'` here would publish a value no
+ * subscriber can ever observe, and it would read to an integrator as a branch
+ * worth writing and testing against.
+ *
+ * ⚠️ Adding `'financial'` is a BREAKING change under rule 1 (it widens a union
+ * an integrator may exhaustively switch on), and announcing it in advance would
+ * not make it any less breaking — rule 2 allows only a new event string. So the
+ * financial axis ships as its OWN event, {@link OrderFinancialStatusChangedPayload}
+ * (`order.financial_status_changed`), and this payload's `axis` stays
+ * `'fulfilment'` for good. That also spares fulfilment subscribers the
+ * migration an `order.status_changed.v2` would force on them.
  *
  * ── 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. Two writers
- * touch `fulfilmentStatus` and are deliberately SILENT, because neither is a
+ * delivery/un-delivery toggle, and the MercadoLibre shipment sync. Three writers
+ * touch `fulfilmentStatus` and are deliberately SILENT, because none is a
  * transition:
  *
  *   - the soft-delete hide path, which rewrites the field wholesale and
  *     deliberately writes no `statusHistory` entry either;
+ *   - the storefront customer's self-cancel, which retires the order the same
+ *     way the soft-delete does and recomputes the field to match;
  *   - the order-edit heal branch, which writes a status where none was stored.
  *     A back-catalogue row acquiring the field it always implied is a data
  *     repair, and announcing it as a status change would tell an integrator an
@@ -427,6 +429,69 @@ export interface OrderStatusChangedPayload {
      */
     occurredAt: number;
 }
+/**
+ * Payload for `order.financial_status_changed` — an existing order's FINANCIAL
+ * axis (`financialStatus`: `pending | partial | paid`) moved, and the move is
+ * durable.
+ *
+ * ── WHY A SEPARATE EVENT AND NOT AN `axis` ON `order.status_changed` ─────
+ *
+ * Widening {@link OrderStatusChangedPayload}'s `axis` is a breaking change
+ * under rule 1, and rule 2 answers a breaking change with a new event string.
+ * The event NAME carries the axis here, so there is no `axis` field: a
+ * subscriber that sees this event knows `'pending'` means UNPAID.
+ *
+ * ── WHICH MOVES REACH THE WIRE ───────────────────────────────────────────
+ *
+ * REAL moves only (`from !== to`), announced after the write commits, from
+ * every writer that moves the axis on an existing order: the counter tender,
+ * both provider settlement webhooks (Stripe, MercadoPago), the payment link
+ * (operator, MercadoLibre collection and MercadoPago movements auto-link), the
+ * payment unlink and the MercadoPago refund. A redelivered settlement, a top-up
+ * that leaves a `partial` order `partial`, and a link that is refused all
+ * announce nothing.
+ *
+ * ⚠️ **Order creation does not emit.** An order created with a tender carries
+ * its first `financialStatus`, which is not a transition; `order.created`
+ * already announces the row.
+ *
+ * ⚠️ **Downgrades are events too.** An unlink or a refund can move `paid` back
+ * to `partial` or `pending`; a subscriber that only handles `to: 'paid'` misses
+ * money given back.
+ *
+ * ⚠️ **Best-effort, like every business event.** A process can stop between
+ * the commit and the emit, and a failed subscription read or enqueue is warned
+ * and swallowed — it never fails the money write it follows. A redelivery after
+ * the commit is absorbed by the writer's idempotency claim or finds the axis
+ * already moved (a self-edge), so a move lost that way is never re-announced.
+ *
+ * ⚠️ **No `total` and no `currency`**, for the denomination reason set out on
+ * {@link OrderCreatedPayload}. The money itself lives on `payment.received`.
+ *
+ * ⚠️ **Enumerated, never spread from the row.** `getOrderById` does not delete
+ * `search`, which embeds the customer's `fullName` (Ley 25.326).
+ */
+export interface OrderFinancialStatusChangedPayload {
+    orderId: string;
+    /**
+     * The state moved FROM.
+     *
+     * ⚠️ **Genuinely optional.** An order written before `financialStatus`
+     * existed carries no such field and nothing backfills it, so its first real
+     * move has no prior state to name. The key is ABSENT then, never present
+     * holding `undefined`. Absent is never the same as equal to {@link to}: a
+     * self-edge does not emit at all.
+     */
+    from?: OrderFinancialStatus;
+    /** The state moved TO. Always the value the committed row now carries. */
+    to: OrderFinancialStatus;
+    /**
+     * Server-stamped Unix milliseconds, taken at the post-commit emit — same
+     * convention and reason as {@link OrderCreatedPayload.occurredAt}. NOT the
+     * `statusHistory` entry's own `timestamp`.
+     */
+    occurredAt: number;
+}
 /**
  * Payload for `invoice.generated` — ARCA authorised a fiscal voucher and its
  * `INVOICE#{storeId}` row is durable.

package/dist/webhook.js

@@ -71,6 +71,7 @@ export const WEBHOOK_EVENT_TYPES = [
     'invoice.generated',
     'customer.created',
     'customer.imported',
+    'order.financial_status_changed',
 ];
 /** Terminal outcomes for a print job. Closed union — a job printed, or it failed. */
 export const PRINT_JOB_SETTLED_OUTCOMES = ['printed', 'failed'];

package/package.json

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