platform-types 1.10.747 → 1.10.748

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/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.748",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",