sinfactura-types 1.8.5 → 1.9.0

package/dist/audit.d.ts

@@ -1,36 +1,63 @@
 declare global {
-    interface OrderAudit {
+    /**
+     * One entry of the generic order audit trail (api#548).
+     *
+     * ⚠️ **Reshaped in types#111.** The previous declaration invented its own
+     * columns (`auditId`, `changes[]`, `itemChanges`, `oldTotal`, `newTotal`)
+     * that did not match what the api's `writeAuditEntry`/`listAuditEntries`
+     * actually persist and return — so a handler could not satisfy both. This is
+     * now a faithful projection of the stored `AuditEntry`, which is the single
+     * storage shape for every audited entity.
+     *
+     * Safe to reshape: nothing imported the old declaration (it was referenced
+     * only inside this file), and the order audit read endpoint does not exist yet.
+     *
+     * Storage: `PK = AUDIT#ORDER#{storeId}#{orderId}`, `SK = {timestampMs}`
+     * zero-padded to 13 chars, newest-first on read. `PK`/`SK` are stripped
+     * before the row reaches the wire.
+     */
+    interface OrderAuditEntry {
+        entity: 'ORDER';
+        /** The `orderId`. */
+        entityId: string;
         storeId: string;
-        auditId: string;
-        orderId: string;
-        userId: string;
-        fullName?: string;
+        /** ms epoch; also the source of the sort key. */
+        timestamp: number;
+        actor: OrderAuditActor;
         action: OrderAuditAction;
+        /**
+         * Changed business fields only, before and after. Line-level detail
+         * (added/removed/modified lines, keyed by original order-array index) and
+         * totals live INSIDE these payloads rather than as extra top-level
+         * columns, because the generic writer has no such columns.
+         *
+         * Must be sanitized: no `PK`/`SK`, no secrets, no unnecessary customer PII.
+         */
+        before: Record<string, unknown>;
+        after: Record<string, unknown>;
+        /** Why the mutation happened. Required by the generic writer. */
+        reason: string;
         createdAt: number;
-        dated: number;
-        changes?: OrderAuditChange[];
-        itemChanges?: {
-            added: Partial<BasketItem>[];
-            removed: Partial<BasketItem>[];
-            modified: Array<{
-                productId: string;
-                name?: string;
-                oldQuantity: number;
-                newQuantity: number;
-                oldPrice: number;
-                newPrice: number;
-            }>;
-        };
-        oldTotal?: number;
-        newTotal?: number;
-        returnId?: string;
     }
-    interface OrderAuditChange {
-        field: string;
-        oldValue: unknown;
-        newValue: unknown;
+    /** Who performed an audited order mutation. `fullName` is denormalized at write time. */
+    interface OrderAuditActor {
+        userId: string;
+        fullName: string;
+    }
+    /**
+     * `GET /orders?mode=audit&orderId=…` response payload (api#548).
+     *
+     * `cursor` is an opaque base64url encoding of the underlying
+     * `LastEvaluatedKey`; raw DynamoDB keys are never exposed. Absent when there
+     * is no further page. An order with no history is `items: []`, not a 404.
+     */
+    interface OrderAuditPage {
+        items: OrderAuditEntry[];
+        cursor?: string;
     }
-    type OrderAuditAction = 'order_created' | 'order_edited' | 'order_ready' | 'order_delivered' | 'order_delivery_cancelled' | 'order_disabled' | 'order_enabled' | 'order_returned' | 'discount_changed' | 'payment_method_changed' | 'delivery_method_changed' | 'delivery_address_changed' | 'invoice_created' | 'credit_note_created';
+    type OrderAuditAction = 'order_created' | 'order_edited' | 'order_ready' | 'order_delivered' | 'order_delivery_cancelled' | 'order_disabled' | 'order_enabled' | 'order_returned'
+    /** Customer (or operator) cancellation — distinct from `order_disabled` (api#591). */
+     | 'order_cancelled' | 'discount_changed' | 'payment_method_changed' | 'delivery_method_changed' | 'delivery_address_changed' | 'invoice_created' | 'credit_note_created';
     /** One ARCA fiscal SOAP interaction (FECAESolicitar | FECompConsultar | ConstatarComprobante). Stored raw (CUIT unmasked) for 10y; masked at read. */
     interface FiscalAuditEvent {
         /** Schema version for forward-compat (start at 1). */

package/dist/cjs/index.js

@@ -14,43 +14,57 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./account"), exports);
-__exportStar(require("./afip"), exports);
-__exportStar(require("./ai"), exports);
-__exportStar(require("./api"), exports);
-__exportStar(require("./audit"), exports);
-__exportStar(require("./auth"), exports);
-__exportStar(require("./basket"), exports);
-__exportStar(require("./brands"), exports);
-__exportStar(require("./cash"), exports);
-__exportStar(require("./categories"), exports);
-__exportStar(require("./currency"), exports);
-__exportStar(require("./customer"), exports);
-__exportStar(require("./demo"), exports);
-__exportStar(require("./impersonation"), exports);
-__exportStar(require("./imports"), exports);
-__exportStar(require("./invoice"), exports);
-__exportStar(require("./log"), exports);
-__exportStar(require("./maintenance"), exports);
-__exportStar(require("./mercadolibre"), exports);
-__exportStar(require("./mercadopago"), exports);
-__exportStar(require("./notification"), exports);
-__exportStar(require("./order"), exports);
-__exportStar(require("./payment"), exports);
-__exportStar(require("./platform"), exports);
-__exportStar(require("./pricing"), exports);
-__exportStar(require("./print"), exports);
-__exportStar(require("./product"), exports);
-__exportStar(require("./return"), exports);
-__exportStar(require("./serviceOrder"), exports);
-__exportStar(require("./serviceTemplate"), exports);
-__exportStar(require("./stock"), exports);
-__exportStar(require("./store"), exports);
-__exportStar(require("./storefrontEvent"), exports);
-__exportStar(require("./subscription"), exports);
-__exportStar(require("./support"), exports);
-__exportStar(require("./supplier"), exports);
-__exportStar(require("./user"), exports);
-__exportStar(require("./userActivity"), exports);
-__exportStar(require("./whatsapp"), exports);
-__exportStar(require("./provinces"), exports);
+// Explicit `.js` specifiers are REQUIRED, not stylistic (types#107).
+//
+// This package is `"type": "module"`, so Node's ESM resolver applies to
+// `dist/index.js` and it does NOT do extensionless resolution — a bare
+// `export * from "./account"` throws ERR_MODULE_NOT_FOUND at import time.
+// That went unnoticed for the package's whole life because every module was
+// ambient-only (`declare global` + `export {}`): nothing ever imported a
+// runtime VALUE, so Node never actually loaded this file. `./socket.js` is the
+// first module exporting real values, which made the latent break reachable.
+//
+// TypeScript maps `./x.js` back to `./x.ts` at compile time, and the CJS build
+// resolves it fine too, so one spelling works for both targets.
+__exportStar(require("./account.js"), exports);
+__exportStar(require("./afip.js"), exports);
+__exportStar(require("./ai.js"), exports);
+__exportStar(require("./api.js"), exports);
+__exportStar(require("./audit.js"), exports);
+__exportStar(require("./auth.js"), exports);
+__exportStar(require("./basket.js"), exports);
+__exportStar(require("./brands.js"), exports);
+__exportStar(require("./cash.js"), exports);
+__exportStar(require("./categories.js"), exports);
+__exportStar(require("./currency.js"), exports);
+__exportStar(require("./customer.js"), exports);
+__exportStar(require("./demo.js"), exports);
+__exportStar(require("./impersonation.js"), exports);
+__exportStar(require("./imports.js"), exports);
+__exportStar(require("./invoice.js"), exports);
+__exportStar(require("./log.js"), exports);
+__exportStar(require("./maintenance.js"), exports);
+__exportStar(require("./mercadolibre.js"), exports);
+__exportStar(require("./mercadopago.js"), exports);
+__exportStar(require("./notification.js"), exports);
+__exportStar(require("./order.js"), exports);
+__exportStar(require("./payment.js"), exports);
+__exportStar(require("./platform.js"), exports);
+__exportStar(require("./pricing.js"), exports);
+__exportStar(require("./print.js"), exports);
+__exportStar(require("./product.js"), exports);
+__exportStar(require("./report.js"), exports);
+__exportStar(require("./return.js"), exports);
+__exportStar(require("./serviceOrder.js"), exports);
+__exportStar(require("./serviceTemplate.js"), exports);
+__exportStar(require("./socket.js"), exports);
+__exportStar(require("./stock.js"), exports);
+__exportStar(require("./store.js"), exports);
+__exportStar(require("./storefrontEvent.js"), exports);
+__exportStar(require("./subscription.js"), exports);
+__exportStar(require("./support.js"), exports);
+__exportStar(require("./supplier.js"), exports);
+__exportStar(require("./user.js"), exports);
+__exportStar(require("./userActivity.js"), exports);
+__exportStar(require("./whatsapp.js"), exports);
+__exportStar(require("./provinces.js"), exports);

package/dist/cjs/report.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/socket.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * WebSocket wire contract — the single source of truth for the SINFACTURA
+ * realtime protocol (types#107).
+ *
+ * ⚠️ This module is deliberately NOT `declare global`. Everything here is a
+ * REAL runtime export, because clients need the action names as *values* to
+ * validate an incoming frame and to key an exhaustive switch — an ambient type
+ * alone cannot do either. Import them:
+ *
+ * ```ts
+ * import { SOCKET_ACTIONS, type SocketAction } from 'sinfactura-types';
+ * ```
+ *
+ * Producers/consumers this contract binds:
+ * - `api` — `stacks/wss/lambdas/socket/default.ts` (client→server zod union)
+ *   and every `wsPost*` broadcast helper (server→client).
+ * - `app` / `storefront` — `Sockets.tsx` action dispatch.
+ * - `cloudprint` — the print agent's `websocket-client.ts`.
+ *
+ * Delivery path is always Lambda → SQS `ws-message` → WSS Lambda → API Gateway
+ * Management API → client. Nothing posts to a connection directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSocketKeepAlive = exports.SOCKET_KEEPALIVE = exports.SOCKET_AUTH_FAIL_REASONS = exports.LIVE_CLIENT_SOCKET_ACTIONS = exports.CLIENT_SOCKET_ACTIONS = exports.isSocketAction = exports.SOCKET_ACTIONS = void 0;
+/* -------------------------------------------------------------------------- */
+/*  Server → client data frames                                               */
+/* -------------------------------------------------------------------------- */
+/**
+ * Every `action` the backend broadcasts on a data frame.
+ *
+ * Derived from the api's actual producers: `postData: { action }` blocks, the
+ * `action` argument of `dynamoUpdate` (which auto-broadcasts via `wsPostStore`),
+ * and the payment/log call sites. Grouped for readability only — the wire
+ * treats them as one flat union.
+ *
+ * ⚠️ Audience is NOT encoded here. `print*` frames go to the print agent
+ * (`wsPostPrinter`), several ops frames go to admins/managers only
+ * (`wsPostAdmin`), and most entity frames go to all store users
+ * (`wsPostStore`). A client must ignore actions it does not own rather than
+ * assume it receives all of them.
+ */
+exports.SOCKET_ACTIONS = [
+    // Entity upserts — mostly emitted by `dynamoUpdate`'s auto-broadcast.
+    'account',
+    'baskets',
+    'brands',
+    'cash',
+    'categories',
+    'customers',
+    'globals',
+    'invoices',
+    'literals',
+    'orders',
+    'products',
+    'shifts',
+    'stores',
+    'suppliers',
+    'supplier-invoice',
+    'support',
+    'surveys',
+    'users',
+    'favorites',
+    // Explicit deletions — the row is gone, not updated.
+    'account-delete',
+    'baskets-delete',
+    'log-delete',
+    // Notifications & messaging.
+    'notifications',
+    'support-message',
+    'whatsapp-message',
+    // Payments & providers.
+    'payment_received',
+    'payment_linked',
+    'payment_unlinked',
+    'mercadopago',
+    'mercadopago_dynamic_qr_created',
+    'mercadopago_static_qr_created',
+    'mp_hook_log_appended',
+    'mp_ipn_log_appended',
+    'stripe',
+    'subscription',
+    // Fiscal.
+    'caea',
+    // Print agent audience (`wsPostPrinter`).
+    'print',
+    'print-order',
+    'print-invoice',
+    'print-product',
+    'print-tag',
+    'print_job_failed',
+    // Operations / operator surfaces.
+    'logs',
+    'maintenance',
+    'currency_auto_updated',
+    'drain_progress',
+    'integration_event_appended',
+    'userActivityRecorded',
+];
+/** Runtime guard — narrows an untrusted string to a known action. */
+const isSocketAction = (value) => typeof value === 'string' && exports.SOCKET_ACTIONS.includes(value);
+exports.isSocketAction = isSocketAction;
+/* -------------------------------------------------------------------------- */
+/*  Client → server frames                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * The client-driven actions the WSS `$default` route accepts.
+ *
+ * The first four mirror the zod discriminated union in
+ * `api/stacks/wss/lambdas/socket/default.ts` and are live today.
+ *
+ * ⚠️ `register_printers` is published AHEAD of the backend (api#2005 /
+ * api#2006 / sinfactura/print#156) so the agent, api, and app lanes can build
+ * against one `.d.ts` instead of discovering a mismatch at integration. The
+ * api's union does **not** accept it yet — sending it before api#2006 ships
+ * fails validation. Check the api lane before wiring it in an agent build.
+ */
+exports.CLIENT_SOCKET_ACTIONS = ['auth', 'logs', 'heartbeat', 'ack', 'register_printers'];
+/** Client→server actions the backend accepts **today**. */
+exports.LIVE_CLIENT_SOCKET_ACTIONS = ['auth', 'logs', 'heartbeat', 'ack'];
+/* -------------------------------------------------------------------------- */
+/*  Control frames                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Why the backend refused the handshake (api#977 / app#1353).
+ *
+ * These exist because API Gateway translates a server-side disconnect into an
+ * opaque 1006 close with no reason. Without an explicit frame the client cannot
+ * tell a rejection from a network blip and burns its retry budget.
+ */
+exports.SOCKET_AUTH_FAIL_REASONS = [
+    'no_token',
+    'invalid_role',
+    'invalid_token',
+    'not_authenticated',
+    'server_error',
+];
+/* -------------------------------------------------------------------------- */
+/*  Keep-alive                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * The keep-alive is **raw strings, not JSON** — the client sends the literal
+ * body `ping` and the backend replies with the literal body `pong`.
+ *
+ * `api/stacks/wss/lambdas/socket/default.ts` matches these before body
+ * parsing, precisely because `JSON.parse('ping')` throws. `live` is accepted as
+ * a legacy alias for `ping` from older clients; never send it from new code.
+ *
+ * Do not wrap these in a `SocketMessage`.
+ */
+exports.SOCKET_KEEPALIVE = {
+    /** Client → server. */
+    ping: 'ping',
+    /** Server → client. */
+    pong: 'pong',
+    /** Deprecated client → server alias for `ping`, still accepted. */
+    legacyPing: 'live',
+};
+/** Recognises either accepted keep-alive request body. */
+const isSocketKeepAlive = (body) => body === exports.SOCKET_KEEPALIVE.ping || body === exports.SOCKET_KEEPALIVE.legacyPing;
+exports.isSocketKeepAlive = isSocketKeepAlive;

package/dist/index.d.ts

@@ -1,40 +1,42 @@
-export * from "./account";
-export * from "./afip";
-export * from "./ai";
-export * from "./api";
-export * from "./audit";
-export * from "./auth";
-export * from "./basket";
-export * from "./brands";
-export * from "./cash";
-export * from "./categories";
-export * from "./currency";
-export * from "./customer";
-export * from "./demo";
-export * from "./impersonation";
-export * from "./imports";
-export * from "./invoice";
-export * from "./log";
-export * from "./maintenance";
-export * from "./mercadolibre";
-export * from "./mercadopago";
-export * from "./notification";
-export * from "./order";
-export * from "./payment";
-export * from "./platform";
-export * from "./pricing";
-export * from "./print";
-export * from "./product";
-export * from "./return";
-export * from "./serviceOrder";
-export * from "./serviceTemplate";
-export * from "./stock";
-export * from "./store";
-export * from "./storefrontEvent";
-export * from "./subscription";
-export * from "./support";
-export * from "./supplier";
-export * from "./user";
-export * from "./userActivity";
-export * from "./whatsapp";
-export * from "./provinces";
+export * from "./account.js";
+export * from "./afip.js";
+export * from "./ai.js";
+export * from "./api.js";
+export * from "./audit.js";
+export * from "./auth.js";
+export * from "./basket.js";
+export * from "./brands.js";
+export * from "./cash.js";
+export * from "./categories.js";
+export * from "./currency.js";
+export * from "./customer.js";
+export * from "./demo.js";
+export * from "./impersonation.js";
+export * from "./imports.js";
+export * from "./invoice.js";
+export * from "./log.js";
+export * from "./maintenance.js";
+export * from "./mercadolibre.js";
+export * from "./mercadopago.js";
+export * from "./notification.js";
+export * from "./order.js";
+export * from "./payment.js";
+export * from "./platform.js";
+export * from "./pricing.js";
+export * from "./print.js";
+export * from "./product.js";
+export * from "./report.js";
+export * from "./return.js";
+export * from "./serviceOrder.js";
+export * from "./serviceTemplate.js";
+export * from "./socket.js";
+export * from "./stock.js";
+export * from "./store.js";
+export * from "./storefrontEvent.js";
+export * from "./subscription.js";
+export * from "./support.js";
+export * from "./supplier.js";
+export * from "./user.js";
+export * from "./userActivity.js";
+export * from "./whatsapp.js";
+export * from "./provinces.js";

package/dist/index.js

@@ -1,40 +1,54 @@
-export * from "./account";
-export * from "./afip";
-export * from "./ai";
-export * from "./api";
-export * from "./audit";
-export * from "./auth";
-export * from "./basket";
-export * from "./brands";
-export * from "./cash";
-export * from "./categories";
-export * from "./currency";
-export * from "./customer";
-export * from "./demo";
-export * from "./impersonation";
-export * from "./imports";
-export * from "./invoice";
-export * from "./log";
-export * from "./maintenance";
-export * from "./mercadolibre";
-export * from "./mercadopago";
-export * from "./notification";
-export * from "./order";
-export * from "./payment";
-export * from "./platform";
-export * from "./pricing";
-export * from "./print";
-export * from "./product";
-export * from "./return";
-export * from "./serviceOrder";
-export * from "./serviceTemplate";
-export * from "./stock";
-export * from "./store";
-export * from "./storefrontEvent";
-export * from "./subscription";
-export * from "./support";
-export * from "./supplier";
-export * from "./user";
-export * from "./userActivity";
-export * from "./whatsapp";
-export * from "./provinces";
+// Explicit `.js` specifiers are REQUIRED, not stylistic (types#107).
+//
+// This package is `"type": "module"`, so Node's ESM resolver applies to
+// `dist/index.js` and it does NOT do extensionless resolution — a bare
+// `export * from "./account"` throws ERR_MODULE_NOT_FOUND at import time.
+// That went unnoticed for the package's whole life because every module was
+// ambient-only (`declare global` + `export {}`): nothing ever imported a
+// runtime VALUE, so Node never actually loaded this file. `./socket.js` is the
+// first module exporting real values, which made the latent break reachable.
+//
+// TypeScript maps `./x.js` back to `./x.ts` at compile time, and the CJS build
+// resolves it fine too, so one spelling works for both targets.
+export * from "./account.js";
+export * from "./afip.js";
+export * from "./ai.js";
+export * from "./api.js";
+export * from "./audit.js";
+export * from "./auth.js";
+export * from "./basket.js";
+export * from "./brands.js";
+export * from "./cash.js";
+export * from "./categories.js";
+export * from "./currency.js";
+export * from "./customer.js";
+export * from "./demo.js";
+export * from "./impersonation.js";
+export * from "./imports.js";
+export * from "./invoice.js";
+export * from "./log.js";
+export * from "./maintenance.js";
+export * from "./mercadolibre.js";
+export * from "./mercadopago.js";
+export * from "./notification.js";
+export * from "./order.js";
+export * from "./payment.js";
+export * from "./platform.js";
+export * from "./pricing.js";
+export * from "./print.js";
+export * from "./product.js";
+export * from "./report.js";
+export * from "./return.js";
+export * from "./serviceOrder.js";
+export * from "./serviceTemplate.js";
+export * from "./socket.js";
+export * from "./stock.js";
+export * from "./store.js";
+export * from "./storefrontEvent.js";
+export * from "./subscription.js";
+export * from "./support.js";
+export * from "./supplier.js";
+export * from "./user.js";
+export * from "./userActivity.js";
+export * from "./whatsapp.js";
+export * from "./provinces.js";

package/dist/invoice.d.ts

@@ -100,6 +100,15 @@ declare global {
          * Optional: forward-only, so rows written before api#1559 carry no ttl.
          */
         ttl?: number;
+        /**
+         * Expected payment due date, Unix ms (api#713 / types#110).
+         *
+         * Optional and forward-only. Unrelated to `ttl` above (a DDB cost boundary)
+         * and to `caeExpiration` (an ARCA authorization window) — this is a
+         * commercial payment term, and it is what the AR dunning chains schedule
+         * against. Inherited from the order or set independently at issuance.
+         */
+        dueDate?: number;
     }
     interface InvoiceItem {
         code: string;

package/dist/order.d.ts

@@ -14,6 +14,15 @@ declare global {
         currencyValue?: number;
         currencyValueAt?: number;
         paymentMethod: number;
+        /**
+         * Expected payment due date, Unix ms (api#713 / types#110).
+         *
+         * Optional and forward-only. Purely declarative in v1: nothing in the
+         * platform computes it from payment terms (Net 15/30, per-customer
+         * credit days) — that is a separate product decision. An Invoice issued
+         * against this order may inherit it or set its own independently.
+         */
+        dueDate?: number;
         deliveryMethod: number;
         invoiceMethod?: {
             condFiscal: number;
@@ -29,7 +38,29 @@ declare global {
         orderPrinted?: boolean;
         tagPrinted?: boolean;
         invoices?: Partial<Invoice>[];
-        returns?: Partial<Return>[];
+        /**
+         * Bounded, embedded projections of this order's returns (api#547),
+         * capped at 50. The canonical rows live under `RETURN#${storeId}`.
+         *
+         * ⚠️ Element type narrowed from `Partial<Return>` to `ReturnSummary` in
+         * types#111. Safe: the returns feature is unbuilt, so nothing produced or
+         * consumed this field at the time of the change.
+         */
+        returns?: ReturnSummary[];
+        /**
+         * Customer self-cancellation (api#591). Cancelled is a DISTINCT state
+         * from `disabled` (operator soft-delete) — do not conflate them, and note
+         * that `disabled` additionally stamps `readyAt`/`deliveredAt`/
+         * `deliveredDate`, which cancellation must NOT do.
+         *
+         * All four are absent on a non-cancelled order.
+         */
+        cancelledAt?: number;
+        /** Who cancelled: the customerId for a self-cancellation, else the userId. */
+        cancelledBy?: string;
+        cancellationSource?: OrderCancellationSource;
+        /** Bounded free text supplied by the canceller. */
+        cancellationReason?: string;
         mercadolibreCreditNote?: {
             creditNoteNumber?: number;
             emittedAt?: number;
@@ -68,6 +99,12 @@ declare global {
         mercadolibre?: OrderMercadolibre;
     }
     type OrderChannel = 'meli';
+    /**
+     * Who initiated a cancellation (api#591). `customer` is the storefront
+     * self-service path; `operator` is reserved for a future back-office
+     * cancellation that is still distinct from `disabled`.
+     */
+    type OrderCancellationSource = 'customer' | 'operator';
     interface MercadolibreCreditNoteStamp {
         creditNoteNumber?: number;
         emittedAt?: number;