platform-types 1.10.747 → 1.10.749

package/dist/cjs/print.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LABEL_TEMPLATE_IDS = void 0;
+exports.PRINT_DISPATCH_SKIP_REASONS = exports.LABEL_TEMPLATE_IDS = void 0;
 /**
  * The five label footprints the app's `LABEL_TEMPLATES` ships; `^PW`/`^LL`
  * presets on the api's ZPL producer.
@@ -19,3 +19,39 @@ exports.LABEL_TEMPLATE_IDS = void 0;
  * consumer; treat it as a set. `producto` is the default template.
  */
 exports.LABEL_TEMPLATE_IDS = ['producto', 'precio', 'estante', 'envio', 'inventario'];
+/**
+ * Why the BE dispatch did not hand a print job to a connection — the four codes
+ * `wsPostPrinter` writes as `PrintJobSummary.errorCode` and reports per job in
+ * {@link PrintDispatchOutcome}.
+ *
+ * - `AGENT_OFFLINE` — the connection exists but its agent stopped heartbeating;
+ *   or the agent has no connection at all although the job named it (a targeted
+ *   agent's socket vanished before dispatch, or none of the agents a job was
+ *   narrowed to is connected — one entry per named agent).
+ * - `PRINTER_INACTIVE` — the resolved rule names a printer the operator paused, the
+ *   registry no longer holds, or the agent's latest printer report left out
+ *   (unplugged or renamed).
+ * - `PRINTER_RAW_UNSUPPORTED` — a raw job (ESC/POS, ZPL) resolved to a printer
+ *   that never declared that dialect, or resolved no rule at all; routing fails
+ *   CLOSED rather than send a control stream to an unknown printer. The two
+ *   causes are told apart by `printerId` — see {@link PrintDispatchOutcome}.
+ * - `NO_PRINTER_CONNECTED` — emitted only when the job reached nobody and skipped
+ *   nobody without naming an agent: the store has no printer connection at all
+ *   (or the job was narrowed to an empty agent list). A job that named its agents
+ *   and found none of them connected is `AGENT_OFFLINE` instead.
+ *
+ * A runtime value, not `declare global`, for the same reason as
+ * `LABEL_TEMPLATE_IDS`: a client switches on these codes and may need to
+ * enumerate them. The api's `printRouting.ts` constants are checked against this
+ * tuple with `satisfies`, so a code cannot be spelled two ways.
+ *
+ * ```ts
+ * import { PRINT_DISPATCH_SKIP_REASONS, type PrintDispatchSkipReason } from 'platform-types';
+ * ```
+ */
+exports.PRINT_DISPATCH_SKIP_REASONS = [
+    'AGENT_OFFLINE',
+    'PRINTER_INACTIVE',
+    'PRINTER_RAW_UNSUPPORTED',
+    'NO_PRINTER_CONNECTED',
+];

package/dist/order.d.ts

@@ -1641,24 +1641,21 @@ declare global {
     interface LinkedPaymentEntry {
         source: 'mp' | 'stripe' | 'mp_movement';
         /**
-         * The amount this store CURRENTLY holds for this payment, net of refunds
-         * — **not** the amount originally settled. It is what
+         * The amount this payment counts toward the order. It is what
          * `deriveOrderFinancialAxis` sums, so it has to mean money the order can
          * still count.
          *
-         * ⚠️ It SHRINKS. A partial refund against the payment lowers it to the
-         * un-refunded remainder (`payment total − every refund so far`) and
-         * restates the order's `financialStatus` in the same write; a refund that
-         * exhausts the payment removes the entry from the map outright. It never
-         * grows — no writer on the refund path may raise it — so a reader may
-         * treat it as monotonically non-increasing after the link is created.
-         *
-         * ⚠️ **FORWARD-ONLY, and that is the reading that matters for anything
-         * historical.** Entries written before refunds began shrinking this field
-         * still carry their PRE-REFUND figure, and nothing is backfilled: an order
-         * partially refunded earlier reads as if the store kept the whole payment.
-         * A consumer reconciling against provider refund history will find those
-         * rows disagree, and the disagreement is the back catalogue, not a bug.
+         * ⚠️ **No writer shrinks it on a refund.** A refund or settled chargeback
+         * MercadoPago reports later is detected and recorded on the payment's
+         * status observation, never here: the entry keeps its linked figure until
+         * the operator mirrors the refund by hand (an unlink removes the entry).
+         * Entries on HISTORICAL orders may carry a smaller figure (or be gone):
+         * the removed outbound MercadoPago refund lowered a partially refunded
+         * entry to its un-refunded remainder and removed an exhausted one, and
+         * those rows keep what it wrote. Entries written before that refund
+         * existed carry their pre-refund figure; nothing is backfilled either way,
+         * so a consumer reconciling against provider refund history will find
+         * rows that disagree, and the disagreement is the back catalogue, not a bug.
          *
          * ⚠️ Denominated in `currency` below — the PAYMENT's denomination, not the
          * order's. Never sum this field across entries without converting.

package/dist/payment.d.ts

@@ -35,6 +35,41 @@ declare global {
             source: PaymentReceivedSource;
             paidAt: number;
         };
+        /**
+         * MercadoPago's CUMULATIVE refunded amount for this payment, in its own currency
+         * (`transaction_amount_refunded`, else the sum of `refunds[]` with status
+         * `approved`; never less than the full `amount` on `providerStatus: 'refunded'`). Written by
+         * the payment status service (`mercadopagoPaymentStatus.ts`) on every observation
+         * — the webhook and the poller's re-check alike. Absent means none observed, never
+         * an unknown. Present ⇒ a link refuses the payment (`LINK_LOCKED` `refunded-payment`).
+         */
+        refundedAmount?: number;
+        /**
+         * MercadoPago's `refunds[]` as last observed, same writer: `id` is MercadoPago's
+         * numeric refund id as a string, `amount` in the payment's currency, `status` as
+         * MercadoPago states it (`approved` once the money moved, `in_process` before), and
+         * `at` its `date_created` in epoch ms. Absent when MercadoPago listed none.
+         */
+        refunds?: {
+            id: string;
+            amount: number;
+            status: string;
+            at: number;
+        }[];
+        /**
+         * A dispute on the payment, same writer: present while `providerStatus` is
+         * `charged_back` or `in_mediation`. A later observation that shows neither clears it,
+         * except a SETTLED chargeback, which is kept through a later `approved`. On
+         * `charged_back`, `statusDetail` says what happened to the money: `settled` (taken for
+         * the full amount — reported for the operator to mirror by hand; the books are not
+         * changed), `reimbursed` (MercadoPago covered the seller) or `in_process` (still
+         * open). Any other detail, and a mediation, reads as still open. Present ⇒ a link
+         * refuses the payment.
+         */
+        chargeback?: {
+            status: string;
+            statusDetail?: string;
+        };
     }
     /** GET /payments/pending returns this page inside the standard data envelope. */
     interface MpPaymentObservationPage {

package/dist/print.d.ts

@@ -17,6 +17,113 @@
  */
 export declare const LABEL_TEMPLATE_IDS: readonly ["producto", "precio", "estante", "envio", "inventario"];
 export type LabelTemplateId = (typeof LABEL_TEMPLATE_IDS)[number];
+/**
+ * Why the BE dispatch did not hand a print job to a connection — the four codes
+ * `wsPostPrinter` writes as `PrintJobSummary.errorCode` and reports per job in
+ * {@link PrintDispatchOutcome}.
+ *
+ * - `AGENT_OFFLINE` — the connection exists but its agent stopped heartbeating;
+ *   or the agent has no connection at all although the job named it (a targeted
+ *   agent's socket vanished before dispatch, or none of the agents a job was
+ *   narrowed to is connected — one entry per named agent).
+ * - `PRINTER_INACTIVE` — the resolved rule names a printer the operator paused, the
+ *   registry no longer holds, or the agent's latest printer report left out
+ *   (unplugged or renamed).
+ * - `PRINTER_RAW_UNSUPPORTED` — a raw job (ESC/POS, ZPL) resolved to a printer
+ *   that never declared that dialect, or resolved no rule at all; routing fails
+ *   CLOSED rather than send a control stream to an unknown printer. The two
+ *   causes are told apart by `printerId` — see {@link PrintDispatchOutcome}.
+ * - `NO_PRINTER_CONNECTED` — emitted only when the job reached nobody and skipped
+ *   nobody without naming an agent: the store has no printer connection at all
+ *   (or the job was narrowed to an empty agent list). A job that named its agents
+ *   and found none of them connected is `AGENT_OFFLINE` instead.
+ *
+ * A runtime value, not `declare global`, for the same reason as
+ * `LABEL_TEMPLATE_IDS`: a client switches on these codes and may need to
+ * enumerate them. The api's `printRouting.ts` constants are checked against this
+ * tuple with `satisfies`, so a code cannot be spelled two ways.
+ *
+ * ```ts
+ * import { PRINT_DISPATCH_SKIP_REASONS, type PrintDispatchSkipReason } from 'platform-types';
+ * ```
+ */
+export declare const PRINT_DISPATCH_SKIP_REASONS: readonly ["AGENT_OFFLINE", "PRINTER_INACTIVE", "PRINTER_RAW_UNSUPPORTED", "NO_PRINTER_CONNECTED"];
+export type PrintDispatchSkipReason = (typeof PRINT_DISPATCH_SKIP_REASONS)[number];
+/**
+ * What the BE dispatch of ONE print job did, as of the moment the handler
+ * answered. Written by `wsPostPrinter` and returned by the handlers that queue
+ * jobs: `POST /orders {mode:'receipt'}` and `POST /products {mode:'tag'}`.
+ *
+ * ⚠️ `reached > 0` means the frame was queued to that many live agent
+ * connections — NOT that paper came out. The agent's ack settles the job
+ * (`printed`/`error`) later, on the job's state timeline.
+ *
+ * `reached === 0` always comes with at least one `skipped` entry. A job narrowed
+ * to agents none of which is connected carries one `{ reason: 'AGENT_OFFLINE', agentId }`
+ * per named agent; any other job that reached nobody and skipped nobody carries
+ * one `{ reason: 'NO_PRINTER_CONNECTED' }`. Either way it is the same code the
+ * job's terminal `error` row records. A job can also be mixed — reached some
+ * connections and skipped others.
+ */
+export interface PrintDispatchOutcome {
+    jobId: string;
+    /** How many printer connections the frame was queued to. */
+    reached: number;
+    /**
+     * One entry per connection the dispatch deliberately left out (or per named
+     * agent that had no connection), each with ONE reason (never the `+`-joined
+     * form `PrintJobSummary.errorCode` can carry). `agentId`/`printerId` are
+     * present when known: `printerId` is the printer the rule resolved to, and
+     * both are absent on `NO_PRINTER_CONNECTED`.
+     *
+     * `PRINTER_RAW_UNSUPPORTED` WITHOUT `printerId`: no rule could be resolved for
+     * the job's use case on that agent — no `PrintRule` for it, a connection with
+     * no `agentId` yet, or a job sent with no use case — so no printer could be
+     * verified (fix: add a rule). WITH `printerId`: a rule routed the job to that
+     * printer, which does not declare the raw format (fix: declare the format on
+     * the printer).
+     */
+    skipped: {
+        reason: PrintDispatchSkipReason;
+        agentId?: string;
+        printerId?: string;
+    }[];
+}
+/**
+ * The `data` shape of the handlers that report each queued print job's dispatch
+ * outcome: the order receipt, the invoice ESC/POS receipt and the product tag.
+ * Other print endpoints (`POST /print`, the invoice PDF print, the test page)
+ * still answer `{ jobId }` without `outcomes`. `OrderReceiptPrintData`,
+ * `InvoiceReceiptPrintData` and `ProductTagPrintData` are this shape under the name
+ * of the endpoint that returns it — aliases rather than empty `extends`, which
+ * `@typescript-eslint/no-empty-object-type` refuses.
+ */
+export interface PrintJobsQueuedData {
+    /** `jobIds[0]` — kept for clients that read a single id. */
+    jobId: string;
+    jobIds: string[];
+    /** One per job, index-aligned with `jobIds`. */
+    outcomes: PrintDispatchOutcome[];
+}
+/**
+ * `data` of `POST /orders {mode:'receipt'}`, written by `orders/_receipt.ts`.
+ * One job per distinct printer render profile, so a store whose printers
+ * disagree on `columns`/`drawerKick` gets several.
+ */
+export type OrderReceiptPrintData = PrintJobsQueuedData;
+/**
+ * `data` of the invoice ESC/POS receipt (`POST /invoices {mode:'printEscpos'}`),
+ * written by `invoices/_printEscpos.ts` — one job per printer render profile, as
+ * for the order receipt.
+ */
+export type InvoiceReceiptPrintData = PrintJobsQueuedData;
+/**
+ * `data` of `POST /products {mode:'tag', notifyCloudPrint: true}`, written by
+ * `products/_tag.ts`: the ZPL job (when the store has a `zpl` agent) first, then
+ * one PDF job per requested item — unless the store has `zpl` agents and no PDF
+ * agent, when there is no PDF job at all.
+ */
+export type ProductTagPrintData = PrintJobsQueuedData;
 declare global {
     type PrintJobState = 'queued' | 'sent' | 'printed' | 'error' | 'cancelled';
     type PrintContentType = 'pdf_uri' | 'pdf_base64' | 'raw_uri' | 'raw_base64';
@@ -83,8 +190,11 @@ declare global {
     interface PrintAgentSummary {
         /**
          * Stable per-install id the agent mints on first run and reuses. The right
-         * handle for list keys and future per-agent actions. Absent on
-         * pre-heartbeat builds, so a UI needs a fallback label.
+         * handle for list keys and future per-agent actions. Resolved the way
+         * dispatch resolves it: a connection whose listing copy carries none gets a
+         * consistent read of its own SOCKET row. Absent only when that leaves it
+         * unresolved — a pre-heartbeat build that never reported one, or a failed
+         * read — so a UI still needs a fallback label.
          */
         agentId?: string;
         /** This connection's own liveness — NOT the store-wide aggregate. */
@@ -444,8 +554,10 @@ declare global {
         detail?: string;
         /**
          * Machine-readable failure classification, when one is recognised. BE-side
-         * dispatch skips write `PRINTER_INACTIVE` / `AGENT_OFFLINE` (or both joined
-         * by `+`); an agent `ACK_FAILED` can classify to `PRINTER_PAUSED` /
+         * dispatch (`wsPostPrinter`) writes one of `PrintDispatchSkipReason` —
+         * `AGENT_OFFLINE` / `PRINTER_INACTIVE` / `PRINTER_RAW_UNSUPPORTED` /
+         * `NO_PRINTER_CONNECTED` — or, when skips disagree, the distinct codes
+         * sorted and joined by `+`; an agent `ACK_FAILED` can classify to `PRINTER_PAUSED` /
          * `NO_PRINTER_ASSIGNED` / `PRINTER_NOT_FOUND`. Unrecognised agent
          * text stays in `detail` only, so absence of a code does NOT mean success.
          */

package/dist/print.js

@@ -16,3 +16,39 @@
  * consumer; treat it as a set. `producto` is the default template.
  */
 export const LABEL_TEMPLATE_IDS = ['producto', 'precio', 'estante', 'envio', 'inventario'];
+/**
+ * Why the BE dispatch did not hand a print job to a connection — the four codes
+ * `wsPostPrinter` writes as `PrintJobSummary.errorCode` and reports per job in
+ * {@link PrintDispatchOutcome}.
+ *
+ * - `AGENT_OFFLINE` — the connection exists but its agent stopped heartbeating;
+ *   or the agent has no connection at all although the job named it (a targeted
+ *   agent's socket vanished before dispatch, or none of the agents a job was
+ *   narrowed to is connected — one entry per named agent).
+ * - `PRINTER_INACTIVE` — the resolved rule names a printer the operator paused, the
+ *   registry no longer holds, or the agent's latest printer report left out
+ *   (unplugged or renamed).
+ * - `PRINTER_RAW_UNSUPPORTED` — a raw job (ESC/POS, ZPL) resolved to a printer
+ *   that never declared that dialect, or resolved no rule at all; routing fails
+ *   CLOSED rather than send a control stream to an unknown printer. The two
+ *   causes are told apart by `printerId` — see {@link PrintDispatchOutcome}.
+ * - `NO_PRINTER_CONNECTED` — emitted only when the job reached nobody and skipped
+ *   nobody without naming an agent: the store has no printer connection at all
+ *   (or the job was narrowed to an empty agent list). A job that named its agents
+ *   and found none of them connected is `AGENT_OFFLINE` instead.
+ *
+ * A runtime value, not `declare global`, for the same reason as
+ * `LABEL_TEMPLATE_IDS`: a client switches on these codes and may need to
+ * enumerate them. The api's `printRouting.ts` constants are checked against this
+ * tuple with `satisfies`, so a code cannot be spelled two ways.
+ *
+ * ```ts
+ * import { PRINT_DISPATCH_SKIP_REASONS, type PrintDispatchSkipReason } from 'platform-types';
+ * ```
+ */
+export const PRINT_DISPATCH_SKIP_REASONS = [
+    'AGENT_OFFLINE',
+    'PRINTER_INACTIVE',
+    'PRINTER_RAW_UNSUPPORTED',
+    'NO_PRINTER_CONNECTED',
+];

package/package.json

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