sinfactura-types 1.9.0 → 1.10.0

package/dist/cjs/socket.js

@@ -89,6 +89,12 @@ exports.SOCKET_ACTIONS = [
     'print-product',
     'print-tag',
     'print_job_failed',
+    // BE → agent: re-send your COMPLETE printer set (api#2006). Carries only
+    // `storeId`; the agent already knows what to report. Exists because
+    // `register_printers` fires just on connect and on local printer change, so
+    // an agent that connected before the registry shipped stays invisible to it
+    // until it happens to reconnect — days, for a machine that is never restarted.
+    'request_printers',
     // Operations / operator surfaces.
     'logs',
     'maintenance',
@@ -109,15 +115,15 @@ exports.isSocketAction = isSocketAction;
  * 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.
+ * `register_printers` is **live**: api#2006 shipped its handler and the `$default`
+ * union, deployed and verified against a real agent on 2026-08-01. It was
+ * published ahead of that backend so the agent, api and app lanes could build
+ * against one `.d.ts` — which is exactly how api#2017 caught the frame being
+ * declared nested while every sibling is flat, before an agent shipped against it.
  */
 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'];
+exports.LIVE_CLIENT_SOCKET_ACTIONS = ['auth', 'logs', 'heartbeat', 'ack', 'register_printers'];
 /* -------------------------------------------------------------------------- */
 /*  Control frames                                                            */
 /* -------------------------------------------------------------------------- */

package/dist/print.d.ts

@@ -171,7 +171,10 @@ declare global {
      */
     type PrintPrinterReport = Omit<PrintPrinter, 'agentId' | 'active' | 'reportedAt' | 'online'>;
     /**
-     * agent → BE WSS payload: `{ action: 'register_printers', data: RegisterPrintersData }`.
+     * payload of the agent → BE `register_printers` WSS frame. ⚠️ That frame is
+   * **FLAT** — `{ action, printers }`, NOT `{ action, data }` (api#2017); this type
+   * describes the fields, not a nested envelope. `agentId` here is advisory: the api
+   * derives it from the authenticated SOCKET row and is not declared on the frame.
      */
     interface RegisterPrintersData {
         agentId: string;

package/dist/report.d.ts

@@ -32,5 +32,120 @@ declare global {
         /** `cost - returnCost`. */
         netCost: number;
     }
+    /**
+     * One FAC/NC/net bucket of the ventas IVA summary (api#2011).
+     *
+     * ⚠️ Every amount is a POSITIVE magnitude, including `credit`. The netting is
+     * expressed by the `net` bucket, never by a sign on `credit` — same
+     * convention the fiscal files use, where a credit-note row also stays
+     * positive and the `CbteTipo` carries the sign semantics.
+     */
+    interface ReportInvoicesAmounts {
+        /** Voucher count in this bucket. */
+        quantity: number;
+        /** Neto gravado summed over every declared alícuota. */
+        neto: number;
+        /** Débito fiscal (IVA) summed over every declared alícuota. */
+        iva: number;
+        /** `ImpTotal` sum. */
+        total: number;
+    }
+    /**
+     * One day of the `GET /reports?mode=invoices&date=YYYYMM` ventas summary
+     * (api#2011 / types#113).
+     *
+     * Covers only AUTHORIZED (deliverable) vouchers — `pending_cae` and
+     * `rejected` are excluded upstream, and legacy rows with no `fiscalStatus`
+     * count as authorized.
+     */
+    interface ReportInvoicesResume {
+        /**
+         * `YYYYMMDD` as a NUMBER.
+         *
+         * ⚠️ Was typed `string` in the app's local copy of this shape while the
+         * API has always returned `Invoice.dated`, a number. Canonicalizing here
+         * fixes that drift — the same class of bug as `ReportSales.date`.
+         */
+        date: number;
+        /** Count of ALL deliverable vouchers this day, credit notes included. */
+        quantity: number;
+        /**
+         * Legacy roll-up columns. These sum EVERY deliverable voucher with a
+         * POSITIVE sign — credit notes included — so `total` is a mixture of
+         * debits and credits rather than a meaningful sales figure. Retained
+         * unchanged for wire compatibility; prefer `gross`/`credit`/`net` below.
+         *
+         * `neto10`/`neto21`/`iva10`/`iva21` only ever covered AFIP `Iva[].Id` 4
+         * (10,5 %) and 5 (21 %); `neto`/`iva` are the all-alícuota roll-ups added
+         * by api#1961.
+         */
+        neto10: number;
+        neto21: number;
+        iva10: number;
+        iva21: number;
+        neto: number;
+        iva: number;
+        total: number;
+        /** Non-credit vouchers — facturas and notas de débito. */
+        gross: ReportInvoicesAmounts;
+        /**
+         * Notas de crédito only, as positive magnitudes. Classified via the
+         * canonical `NC_CBTE_TIPOS` family, NOT a hardcoded `[3, 8, 13]`.
+         *
+         * ⚠️ Notas de DÉBITO are deliberately NOT here — a débito increases what
+         * is owed, so it belongs in `gross`. Netting both would move the total in
+         * the wrong direction.
+         */
+        credit: ReportInvoicesAmounts;
+        /** `gross - credit`, field by field. The figure an operator should read. */
+        net: ReportInvoicesAmounts;
+    }
+    /**
+     * One voucher row of the ventas summary's spreadsheet export.
+     *
+     * ⚠️ Mixed string/number by design — the padded fiscal columns are strings
+     * while the amounts are numbers. The app's local copy typed this
+     * `Record<string, string>[]`, which was wrong for five of the ten fields.
+     */
+    interface ReportInvoicesVoucherRow {
+        FECHA: string;
+        CBTE_TIPO: string;
+        PTO_VTA: string;
+        CBTE_NUMERO: number;
+        RAZON_SOCIAL: string;
+        CUIT: string;
+        NETO: number;
+        NETO10: number;
+        NETO21: number;
+        TOTAL: number;
+    }
+    /**
+     * `GET /reports?mode=invoices&date=YYYYMM` response payload.
+     *
+     * Carries BOTH the operator-facing summary (`resume`, `period`) and the ARCA
+     * REGINFO_CV_VENTAS flat files (`customers`, `reg_alicuotas`, `reg_cbte`).
+     *
+     * ⚠️ The two are produced from the same voucher set but must never share sign
+     * semantics: the summary nets credit notes, the flat files keep every voucher
+     * a positive magnitude carrying its own `CbteTipo`. A sign leak into the
+     * fixed-width records corrupts a filing.
+     */
+    interface ReportInvoices {
+        /** Per-day rows, ascending by `date`. */
+        resume: ReportInvoicesResume[];
+        /** Same FAC/NC/net split aggregated over the whole selected period (api#2011). */
+        period: {
+            gross: ReportInvoicesAmounts;
+            credit: ReportInvoicesAmounts;
+            net: ReportInvoicesAmounts;
+        };
+        invoices: ReportInvoicesVoucherRow[];
+        /** REGINFO_CV_VENTAS fixed-width padrón de clientes. */
+        customers: string;
+        /** REGINFO_CV_VENTAS_ALICUOTAS.TXT — one record per declared alícuota. */
+        reg_alicuotas: string;
+        /** REGINFO_CV_VENTAS_CBTE.TXT — one record per voucher. */
+        reg_cbte: string;
+    }
 }
 export {};

package/dist/socket.d.ts

@@ -34,7 +34,7 @@
  * (`wsPostStore`). A client must ignore actions it does not own rather than
  * assume it receives all of them.
  */
-export declare const SOCKET_ACTIONS: readonly ["account", "baskets", "brands", "cash", "categories", "customers", "globals", "invoices", "literals", "orders", "products", "shifts", "stores", "suppliers", "supplier-invoice", "support", "surveys", "users", "favorites", "account-delete", "baskets-delete", "log-delete", "notifications", "support-message", "whatsapp-message", "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", "caea", "print", "print-order", "print-invoice", "print-product", "print-tag", "print_job_failed", "logs", "maintenance", "currency_auto_updated", "drain_progress", "integration_event_appended", "userActivityRecorded"];
+export declare const SOCKET_ACTIONS: readonly ["account", "baskets", "brands", "cash", "categories", "customers", "globals", "invoices", "literals", "orders", "products", "shifts", "stores", "suppliers", "supplier-invoice", "support", "surveys", "users", "favorites", "account-delete", "baskets-delete", "log-delete", "notifications", "support-message", "whatsapp-message", "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", "caea", "print", "print-order", "print-invoice", "print-product", "print-tag", "print_job_failed", "request_printers", "logs", "maintenance", "currency_auto_updated", "drain_progress", "integration_event_appended", "userActivityRecorded"];
 /** Union of every server→client data-frame action. */
 export type SocketAction = (typeof SOCKET_ACTIONS)[number];
 /** Runtime guard — narrows an untrusted string to a known action. */
@@ -56,17 +56,17 @@ export interface SocketMessage<T = unknown> {
  * 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.
+ * `register_printers` is **live**: api#2006 shipped its handler and the `$default`
+ * union, deployed and verified against a real agent on 2026-08-01. It was
+ * published ahead of that backend so the agent, api and app lanes could build
+ * against one `.d.ts` — which is exactly how api#2017 caught the frame being
+ * declared nested while every sibling is flat, before an agent shipped against it.
  */
 export declare const CLIENT_SOCKET_ACTIONS: readonly ["auth", "logs", "heartbeat", "ack", "register_printers"];
 /** Union of every client→server action. */
 export type ClientSocketAction = (typeof CLIENT_SOCKET_ACTIONS)[number];
 /** Client→server actions the backend accepts **today**. */
-export declare const LIVE_CLIENT_SOCKET_ACTIONS: readonly ["auth", "logs", "heartbeat", "ack"];
+export declare const LIVE_CLIENT_SOCKET_ACTIONS: readonly ["auth", "logs", "heartbeat", "ack", "register_printers"];
 /** Authenticate the connection. Must be the first frame; see `AuthAckFrame`. */
 export interface SocketAuthMessage {
     action: 'auth';
@@ -99,13 +99,30 @@ export interface SocketAckMessage {
     [key: string]: unknown;
 }
 /**
- * Agent → BE printer registry report (api#2005). `data` is the COMPLETE current
- * printer set for the agent, not a delta. Not accepted by the api until
- * api#2006 — see `CLIENT_SOCKET_ACTIONS`.
+ * Agent → BE printer registry report (api#2006). `printers` is the agent's
+ * COMPLETE current set, never a delta — the BE marks absent printers offline
+ * rather than deleting them, because deleting would orphan any `PrintRule`
+ * pointing at one.
+ *
+ * **FLAT, like every other client→server frame** (api#2017). 1.9.0–1.9.1
+ * declared this nested (`{ action, data }`) — the only nested client action —
+ * and that was wrong: the agent's sender builds `{ action, ...data }` by design,
+ * reserving nested payloads for server→client frames, and the api destructures
+ * `const { action, ...data }`. A union entry written to match the nested
+ * declaration would have rejected every real report with `400 Invalid message`
+ * and left the registry silently empty, presenting as an agent bug.
+ *
+ * `agentId` is deliberately **not declared**. The api derives it from the
+ * authenticated SOCKET row, because trusting a frame-supplied value would let
+ * one agent register printers under another's id. The open index signature still
+ * permits sending it, and the api treats it as advisory — falling back to it only
+ * when the connection has no `agentId` yet, since a report can arrive before the
+ * agent's first heartbeat.
  */
 export interface SocketRegisterPrintersMessage {
     action: 'register_printers';
-    data: RegisterPrintersData;
+    printers: PrintPrinterReport[];
+    [key: string]: unknown;
 }
 /** Any client→server JSON frame. */
 export type ClientSocketMessage = SocketAuthMessage | SocketLogsMessage | SocketHeartbeatMessage | SocketAckMessage | SocketRegisterPrintersMessage;

package/dist/socket.js

@@ -86,6 +86,12 @@ export const SOCKET_ACTIONS = [
     'print-product',
     'print-tag',
     'print_job_failed',
+    // BE → agent: re-send your COMPLETE printer set (api#2006). Carries only
+    // `storeId`; the agent already knows what to report. Exists because
+    // `register_printers` fires just on connect and on local printer change, so
+    // an agent that connected before the registry shipped stays invisible to it
+    // until it happens to reconnect — days, for a machine that is never restarted.
+    'request_printers',
     // Operations / operator surfaces.
     'logs',
     'maintenance',
@@ -105,15 +111,15 @@ export const isSocketAction = (value) => typeof value === 'string' && SOCKET_ACT
  * 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.
+ * `register_printers` is **live**: api#2006 shipped its handler and the `$default`
+ * union, deployed and verified against a real agent on 2026-08-01. It was
+ * published ahead of that backend so the agent, api and app lanes could build
+ * against one `.d.ts` — which is exactly how api#2017 caught the frame being
+ * declared nested while every sibling is flat, before an agent shipped against it.
  */
 export const CLIENT_SOCKET_ACTIONS = ['auth', 'logs', 'heartbeat', 'ack', 'register_printers'];
 /** Client→server actions the backend accepts **today**. */
-export const LIVE_CLIENT_SOCKET_ACTIONS = ['auth', 'logs', 'heartbeat', 'ack'];
+export const LIVE_CLIENT_SOCKET_ACTIONS = ['auth', 'logs', 'heartbeat', 'ack', 'register_printers'];
 /* -------------------------------------------------------------------------- */
 /*  Control frames                                                            */
 /* -------------------------------------------------------------------------- */

package/package.json

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