sinfactura-types 1.10.7 → 1.10.8

package/dist/cjs/socket.js

@@ -22,7 +22,7 @@
  * 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;
+exports.isSocketKeepAlive = exports.SOCKET_KEEPALIVE = exports.SOCKET_AUTH_FAIL_REASONS = exports.LIVE_CLIENT_SOCKET_ACTIONS = exports.CLIENT_SOCKET_ACTIONS = exports.DESTRUCTIVE_AGENT_COMMANDS = exports.isAgentCommand = exports.AGENT_COMMANDS = exports.isSocketAction = exports.SOCKET_ACTIONS = void 0;
 /* -------------------------------------------------------------------------- */
 /*  Server → client data frames                                               */
 /* -------------------------------------------------------------------------- */
@@ -109,6 +109,18 @@ exports.SOCKET_ACTIONS = [
     // operator's pause toggle (api#2028). Payload is `PrintersActiveData`.
     // Full replacement, never a delta; both unknowns fail OPEN (see that type).
     'printers_active',
+    // BE → agent, scoped to ONE agent's own connections (like `printers_active`,
+    // never fanned to the store): run a local diagnostic/recovery action
+    // (print#224). Payload is `AgentCommandData`.
+    //
+    // ⚠️ NOT understood by any released agent. The agent routes inbound frames
+    // through a closed control-frame switch (`request_printers`,
+    // `printers_active`) and then a 4-member print-job enum; anything else lands
+    // in its "Unhandled frame" warn and is never executed or acknowledged. As of
+    // v2.2.2 that includes this action — print#224's agent lane must add the case
+    // before a producer can rely on it. Publishing it here first is deliberate, so
+    // all three lanes build against one `.d.ts`.
+    'agent_command',
     // Operations / operator surfaces.
     'logs',
     'maintenance',
@@ -121,6 +133,55 @@ exports.SOCKET_ACTIONS = [
 const isSocketAction = (value) => typeof value === 'string' && exports.SOCKET_ACTIONS.includes(value);
 exports.isSocketAction = isSocketAction;
 /* -------------------------------------------------------------------------- */
+/*  Agent diagnostic commands (print#224)                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * The remote-triggerable diagnostic actions, in the agent's OWN spelling.
+ *
+ * **Kebab-case, verbatim from the agent's `DiagnosticActionId`** (print#223,
+ * shipped v2.2.2) — not the snake_case the rest of this file's ACTION names use.
+ * That is a deliberate trade. `sinfactura/print` does not depend on this package,
+ * so any renaming here has to be re-implemented as a mapping table on the agent
+ * side, where a drift is invisible to both ends until an operator reports that a
+ * button does nothing. Passing the agent's own ids through untouched removes the
+ * mapping layer entirely: the BE forwards a string the agent already keys on.
+ * The frame's ACTION (`agent_command`) stays snake_case like its siblings; this
+ * is the payload vocabulary, a different namespace.
+ *
+ * A command the agent does not recognise is safe by construction — its
+ * `runDiagnosticAction` returns a structured "unknown command" result instead of
+ * throwing — so an older agent degrades to a visible failure, not a crash.
+ *
+ * Two members of the originally-proposed set are absent on purpose:
+ *
+ * - **`view-logs`** exists on the agent but is not remotely meaningful. It opens
+ *   the log FOLDER on the agent's own machine and resolves `ok: true`, so a
+ *   remote operator would read "logs delivered" while a window opened on an
+ *   unattended PC. Shipping logs BACK to the backend is a genuinely different
+ *   capability that the agent does not have; it needs its own contract.
+ * - **`test_print`** is not an agent-local action at all. The backend dispatches
+ *   a real job to an explicit printer (api#2041, shipped), so routing it through
+ *   here would be a second way to do one thing — and the agent would reject it as
+ *   an unknown command.
+ */
+exports.AGENT_COMMANDS = ['redetect-printers', 'reconnect-socket', 'flush-acks', 'clear-queue'];
+/** Runtime guard — narrows an untrusted string to a known command. */
+const isAgentCommand = (value) => typeof value === 'string' && exports.AGENT_COMMANDS.includes(value);
+exports.isAgentCommand = isAgentCommand;
+/**
+ * Commands that destroy operator data and MUST be confirmed before dispatch.
+ *
+ * Mirrors the agent's own `destructive` flag. The agent deliberately does not
+ * prompt inside `run()` — its confirmation lives in the DOM layer, which a remote
+ * trigger never reaches — so the "are you sure?" is the CALLER's job. For a
+ * remote command that means the app, before it asks the backend to dispatch.
+ *
+ * `clear-queue` deletes queued work that then never prints. print#235 (agent
+ * v2.2.3) stopped it destroying in-flight ACKs, but queued jobs are still lost,
+ * and the operator who loses them is not the one who pressed the button.
+ */
+exports.DESTRUCTIVE_AGENT_COMMANDS = ['clear-queue'];
+/* -------------------------------------------------------------------------- */
 /*  Client → server frames                                                    */
 /* -------------------------------------------------------------------------- */
 /**
@@ -141,6 +202,14 @@ exports.isSocketAction = isSocketAction;
  * shipped in 1.10.x, but the action string was never added to these two arrays —
  * so `isClientSocketAction`-style checks and exhaustive switches keyed off
  * `ClientSocketAction` silently excluded a live action. Corrected in 1.10.5.
+ *
+ * `agent_command_result` is declared but **NOT live** (print#224, 1.10.8): no
+ * `$default` union entry or handler exists for it yet, so the api answers it with
+ * `400 Invalid message`. It is in this array — the full vocabulary — and out of
+ * `LIVE_CLIENT_SOCKET_ACTIONS` below, which is exactly the distinction the two
+ * arrays exist to carry. Do not "fix the inconsistency" by adding it there; that
+ * is the inverse of the 1.10.5 bug, and it would tell a consumer the frame is
+ * accepted when it is rejected.
  */
 exports.CLIENT_SOCKET_ACTIONS = [
     'auth',
@@ -149,8 +218,13 @@ exports.CLIENT_SOCKET_ACTIONS = [
     'ack',
     'register_printers',
     'export_local_rules',
+    'agent_command_result',
 ];
-/** Client→server actions the backend accepts **today**. */
+/**
+ * Client→server actions the backend accepts **today** — a strict subset of
+ * `CLIENT_SOCKET_ACTIONS`. Anything declared but absent here is published ahead
+ * of its handler and will be rejected `400 Invalid message` on the wire.
+ */
 exports.LIVE_CLIENT_SOCKET_ACTIONS = [
     'auth',
     'logs',

package/dist/mercadolibre.d.ts

@@ -70,66 +70,6 @@ declare global {
         currency: string;
         paidAt?: number;
     }
-    type GtinRequirementTag = "not_required" | "conditional_required" | "new_required";
-    interface MlAttribute {
-        id: string;
-        name?: string;
-        value_id?: string;
-        value_name?: string;
-        attribute_group_id?: string;
-        attribute_group_name?: string;
-    }
-    interface MlRequiredAttribute {
-        id: string;
-        name?: string;
-        required: boolean;
-        tags?: string[];
-    }
-    interface MlCategoryPrediction {
-        domainName: string;
-        categoryId: string;
-        categoryName: string;
-        attributes: MlAttribute[];
-        requiredAttributes: MlRequiredAttribute[];
-        immediatePayment?: "required" | "optional";
-        maxTitleLength?: number;
-        gtinRequirement: GtinRequirementTag;
-    }
-    interface MlCategoryCandidate {
-        domainId?: string;
-        domainName: string;
-        categoryId: string;
-        categoryName: string;
-    }
-    interface PublishPrediction extends MlCategoryPrediction {
-        isUpMigrated: boolean;
-        candidates: MlCategoryCandidate[];
-    }
-    interface MlCategoryAttributeSchema {
-        categoryId: string;
-        requiredAttributes: MlRequiredAttribute[];
-        gtinRequirement: GtinRequirementTag;
-        maxTitleLength?: number;
-        immediatePayment?: "required" | "optional";
-    }
-    interface MlPublishRequest {
-        productId: string;
-        categoryId: string;
-        attributes: MlAttribute[];
-        listingTypeId: string;
-        saleTerms?: Record<string, unknown>[];
-        pictures?: {
-            url: string;
-        }[];
-        description?: string;
-    }
-    interface MlPublishResponse {
-        productId: string;
-        itemId: string;
-        userProductId?: string;
-        isUpMigrated: boolean;
-        status: "linked";
-    }
     interface MlFieldError {
         field: string;
         code?: string;

package/dist/print.d.ts

@@ -1,6 +1,17 @@
 declare global {
     type PrintJobState = 'queued' | 'sent' | 'printed' | 'error';
     type PrintContentType = 'pdf_uri' | 'pdf_base64' | 'raw_uri' | 'raw_base64';
+    /**
+     * A raw (non-PDF) control language a printer can be sent.
+     *
+     * Deliberately NOT encoded into `PrintContentType`: that field says how the
+     * bytes ARRIVE (`raw_uri` vs `raw_base64`), not what dialect they are, and the
+     * two axes are independent — every format is transportable both ways. Widening
+     * `PrintContentType` to `raw_zpl_base64`-style members would multiply out to a
+     * member per (format × transport) pair and break every existing consumer that
+     * switches on it.
+     */
+    type PrintRawFormat = 'zpl' | 'escpos';
     interface PrintOptions {
         bin?: string;
         collate?: boolean;
@@ -157,6 +168,29 @@ declare global {
          * survive a re-registration that omits it. `false` = do not route jobs here.
          */
         active: boolean;
+        /**
+         * Raw control languages the OPERATOR declares this device understands.
+         * BE-owned and operator-set, exactly like `active` — never agent-reported.
+         *
+         * ⚠️ **Absent or empty means REFUSE all raw content.** This is the one field
+         * in the printer registry where absence is a "no" rather than a "not
+         * reported", and it inverts `PrintPrinterCapabilities`' core rule on purpose
+         * (`api/stacks/services/printRules.ts`: "Absent capabilities = not reported —
+         * accept everything"). That default is right for `paper`/`bins`/`dpis`, where
+         * guessing wrong wastes one job. Here, guessing wrong sends a ZPL stream to a
+         * laser printer, which does not error — it renders every command as text and
+         * puts a ream through the machine until someone physically cancels it. The
+         * spooler accepts the bytes, the agent ACKs `printed`, and the BE records
+         * success. So it cannot live in `capabilities`, or the next person to "fix
+         * the inconsistency" reopens the hole.
+         *
+         * It is also not something the agent could report honestly: it can read a
+         * driver string (`ZDesigner ZD420`), but a generic driver, a renamed queue or
+         * a shared network printer defeats that heuristic. And an agent-reported
+         * field is overwritten on every re-registration — the same bug `active` is
+         * shaped to avoid, with a worse outcome than an un-paused printer.
+         */
+        rawFormats?: PrintRawFormat[];
         /** ms epoch of the last `register_printers` report that included this printer. */
         reportedAt: number;
         /**
@@ -177,7 +211,7 @@ declare global {
      * wholesale would silently reset the operator's per-printer pause toggle on
      * every agent restart.
      */
-    type PrintPrinterReport = Omit<PrintPrinter, 'agentId' | 'active' | 'reportedAt' | 'online'>;
+    type PrintPrinterReport = Omit<PrintPrinter, 'agentId' | 'active' | 'reportedAt' | 'online' | 'rawFormats'>;
     /**
      * payload of the agent → BE `register_printers` WSS frame. ⚠️ That frame is
    * **FLAT** — `{ action, printers }`, NOT `{ action, data }` (api#2017); this type

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", "request_printers", "printers_changed", "print_rules_changed", "printers_active", "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", "printers_changed", "print_rules_changed", "printers_active", "agent_command", "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. */
@@ -50,6 +50,106 @@ export interface SocketMessage<T = unknown> {
     action: SocketAction;
     data: T;
 }
+/**
+ * The remote-triggerable diagnostic actions, in the agent's OWN spelling.
+ *
+ * **Kebab-case, verbatim from the agent's `DiagnosticActionId`** (print#223,
+ * shipped v2.2.2) — not the snake_case the rest of this file's ACTION names use.
+ * That is a deliberate trade. `sinfactura/print` does not depend on this package,
+ * so any renaming here has to be re-implemented as a mapping table on the agent
+ * side, where a drift is invisible to both ends until an operator reports that a
+ * button does nothing. Passing the agent's own ids through untouched removes the
+ * mapping layer entirely: the BE forwards a string the agent already keys on.
+ * The frame's ACTION (`agent_command`) stays snake_case like its siblings; this
+ * is the payload vocabulary, a different namespace.
+ *
+ * A command the agent does not recognise is safe by construction — its
+ * `runDiagnosticAction` returns a structured "unknown command" result instead of
+ * throwing — so an older agent degrades to a visible failure, not a crash.
+ *
+ * Two members of the originally-proposed set are absent on purpose:
+ *
+ * - **`view-logs`** exists on the agent but is not remotely meaningful. It opens
+ *   the log FOLDER on the agent's own machine and resolves `ok: true`, so a
+ *   remote operator would read "logs delivered" while a window opened on an
+ *   unattended PC. Shipping logs BACK to the backend is a genuinely different
+ *   capability that the agent does not have; it needs its own contract.
+ * - **`test_print`** is not an agent-local action at all. The backend dispatches
+ *   a real job to an explicit printer (api#2041, shipped), so routing it through
+ *   here would be a second way to do one thing — and the agent would reject it as
+ *   an unknown command.
+ */
+export declare const AGENT_COMMANDS: readonly ["redetect-printers", "reconnect-socket", "flush-acks", "clear-queue"];
+/** Union of every remote-triggerable diagnostic command. */
+export type AgentCommand = (typeof AGENT_COMMANDS)[number];
+/** Runtime guard — narrows an untrusted string to a known command. */
+export declare const isAgentCommand: (value: unknown) => value is AgentCommand;
+/**
+ * Commands that destroy operator data and MUST be confirmed before dispatch.
+ *
+ * Mirrors the agent's own `destructive` flag. The agent deliberately does not
+ * prompt inside `run()` — its confirmation lives in the DOM layer, which a remote
+ * trigger never reaches — so the "are you sure?" is the CALLER's job. For a
+ * remote command that means the app, before it asks the backend to dispatch.
+ *
+ * `clear-queue` deletes queued work that then never prints. print#235 (agent
+ * v2.2.3) stopped it destroying in-flight ACKs, but queued jobs are still lost,
+ * and the operator who loses them is not the one who pressed the button.
+ */
+export declare const DESTRUCTIVE_AGENT_COMMANDS: readonly AgentCommand[];
+/**
+ * `data` payload of the BE → agent `agent_command` frame — nested,
+ * `{ action: 'agent_command', data: AgentCommandData }`, like every other
+ * server→client frame.
+ *
+ * Declared here rather than beside `PrintersActiveData` in `print.ts` because it
+ * references `AgentCommand`, which is derived from the runtime `AGENT_COMMANDS`
+ * array above; re-declaring the vocabulary as an ambient type would give it two
+ * sources that drift independently.
+ */
+export interface AgentCommandData {
+    command: AgentCommand;
+    /**
+     * The target agent. Advisory for the agent itself — the BE has already scoped
+     * delivery to that agent's connections — but carried so the agent can drop a
+     * frame that reached it through a mis-scoped broadcast rather than acting on
+     * another machine's instruction.
+     */
+    agentId: string;
+    /**
+     * Stable per-dispatch id. **Required, never optional.**
+     *
+     * The wss `$default` route has a bare Lambda integration and no route
+     * response, so a frame the agent sends can never fail visibly to it. Delivery
+     * therefore has to be idempotent-and-repeatable rather than once-and-hope,
+     * and a re-dispatch needs a stable id for the agent to deduplicate on and for
+     * the backend to match a late result against.
+     */
+    commandId: string;
+}
+/**
+ * Agent → BE outcome of one `agent_command`.
+ *
+ * ⚠️ **A report, not an acknowledgement of delivery.** The agent cannot observe
+ * whether the backend received this frame (see `commandId`), so "did the command
+ * work" is a question the BACKEND answers by reconciling its own dispatch state —
+ * never one the agent can settle by sending this.
+ *
+ * Note that `ok: false` is not necessarily a failure of the action: the agent
+ * guards every command with a 3s per-action cooldown and an in-flight lock, and
+ * a refusal from either returns `ok: false` with an operator-facing message
+ * ("Esperá unos segundos…"). Surface `message`; do not translate `ok: false`
+ * into "the agent is broken".
+ */
+export interface SocketAgentCommandResultMessage {
+    action: 'agent_command_result';
+    /** Echoes `AgentCommandData.commandId` — the only way to match a result to its dispatch. */
+    commandId: string;
+    ok: boolean;
+    /** Operator-facing, Spanish voseo, always non-empty. Produced by the agent. */
+    message: string;
+    [key: string]: unknown;
+}
 /**
  * The client-driven actions the WSS `$default` route accepts.
  *
@@ -68,11 +168,23 @@ export interface SocketMessage<T = unknown> {
  * shipped in 1.10.x, but the action string was never added to these two arrays —
  * so `isClientSocketAction`-style checks and exhaustive switches keyed off
  * `ClientSocketAction` silently excluded a live action. Corrected in 1.10.5.
+ *
+ * `agent_command_result` is declared but **NOT live** (print#224, 1.10.8): no
+ * `$default` union entry or handler exists for it yet, so the api answers it with
+ * `400 Invalid message`. It is in this array — the full vocabulary — and out of
+ * `LIVE_CLIENT_SOCKET_ACTIONS` below, which is exactly the distinction the two
+ * arrays exist to carry. Do not "fix the inconsistency" by adding it there; that
+ * is the inverse of the 1.10.5 bug, and it would tell a consumer the frame is
+ * accepted when it is rejected.
  */
-export declare const CLIENT_SOCKET_ACTIONS: readonly ["auth", "logs", "heartbeat", "ack", "register_printers", "export_local_rules"];
+export declare const CLIENT_SOCKET_ACTIONS: readonly ["auth", "logs", "heartbeat", "ack", "register_printers", "export_local_rules", "agent_command_result"];
 /** Union of every client→server action. */
 export type ClientSocketAction = (typeof CLIENT_SOCKET_ACTIONS)[number];
-/** Client→server actions the backend accepts **today**. */
+/**
+ * Client→server actions the backend accepts **today** — a strict subset of
+ * `CLIENT_SOCKET_ACTIONS`. Anything declared but absent here is published ahead
+ * of its handler and will be rejected `400 Invalid message` on the wire.
+ */
 export declare const LIVE_CLIENT_SOCKET_ACTIONS: readonly ["auth", "logs", "heartbeat", "ack", "register_printers", "export_local_rules"];
 /** Authenticate the connection. Must be the first frame; see `AuthAckFrame`. */
 export interface SocketAuthMessage {
@@ -167,7 +279,7 @@ export interface SocketExportLocalRulesMessage {
     [key: string]: unknown;
 }
 /** Any client→server JSON frame. */
-export type ClientSocketMessage = SocketAuthMessage | SocketLogsMessage | SocketHeartbeatMessage | SocketAckMessage | SocketRegisterPrintersMessage | SocketExportLocalRulesMessage;
+export type ClientSocketMessage = SocketAuthMessage | SocketLogsMessage | SocketHeartbeatMessage | SocketAckMessage | SocketRegisterPrintersMessage | SocketExportLocalRulesMessage | SocketAgentCommandResultMessage;
 /**
  * Why the backend refused the handshake (api#977 / app#1353).
  *

package/dist/socket.js

@@ -106,6 +106,18 @@ export const SOCKET_ACTIONS = [
     // operator's pause toggle (api#2028). Payload is `PrintersActiveData`.
     // Full replacement, never a delta; both unknowns fail OPEN (see that type).
     'printers_active',
+    // BE → agent, scoped to ONE agent's own connections (like `printers_active`,
+    // never fanned to the store): run a local diagnostic/recovery action
+    // (print#224). Payload is `AgentCommandData`.
+    //
+    // ⚠️ NOT understood by any released agent. The agent routes inbound frames
+    // through a closed control-frame switch (`request_printers`,
+    // `printers_active`) and then a 4-member print-job enum; anything else lands
+    // in its "Unhandled frame" warn and is never executed or acknowledged. As of
+    // v2.2.2 that includes this action — print#224's agent lane must add the case
+    // before a producer can rely on it. Publishing it here first is deliberate, so
+    // all three lanes build against one `.d.ts`.
+    'agent_command',
     // Operations / operator surfaces.
     'logs',
     'maintenance',
@@ -117,6 +129,54 @@ export const SOCKET_ACTIONS = [
 /** Runtime guard — narrows an untrusted string to a known action. */
 export const isSocketAction = (value) => typeof value === 'string' && SOCKET_ACTIONS.includes(value);
 /* -------------------------------------------------------------------------- */
+/*  Agent diagnostic commands (print#224)                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * The remote-triggerable diagnostic actions, in the agent's OWN spelling.
+ *
+ * **Kebab-case, verbatim from the agent's `DiagnosticActionId`** (print#223,
+ * shipped v2.2.2) — not the snake_case the rest of this file's ACTION names use.
+ * That is a deliberate trade. `sinfactura/print` does not depend on this package,
+ * so any renaming here has to be re-implemented as a mapping table on the agent
+ * side, where a drift is invisible to both ends until an operator reports that a
+ * button does nothing. Passing the agent's own ids through untouched removes the
+ * mapping layer entirely: the BE forwards a string the agent already keys on.
+ * The frame's ACTION (`agent_command`) stays snake_case like its siblings; this
+ * is the payload vocabulary, a different namespace.
+ *
+ * A command the agent does not recognise is safe by construction — its
+ * `runDiagnosticAction` returns a structured "unknown command" result instead of
+ * throwing — so an older agent degrades to a visible failure, not a crash.
+ *
+ * Two members of the originally-proposed set are absent on purpose:
+ *
+ * - **`view-logs`** exists on the agent but is not remotely meaningful. It opens
+ *   the log FOLDER on the agent's own machine and resolves `ok: true`, so a
+ *   remote operator would read "logs delivered" while a window opened on an
+ *   unattended PC. Shipping logs BACK to the backend is a genuinely different
+ *   capability that the agent does not have; it needs its own contract.
+ * - **`test_print`** is not an agent-local action at all. The backend dispatches
+ *   a real job to an explicit printer (api#2041, shipped), so routing it through
+ *   here would be a second way to do one thing — and the agent would reject it as
+ *   an unknown command.
+ */
+export const AGENT_COMMANDS = ['redetect-printers', 'reconnect-socket', 'flush-acks', 'clear-queue'];
+/** Runtime guard — narrows an untrusted string to a known command. */
+export const isAgentCommand = (value) => typeof value === 'string' && AGENT_COMMANDS.includes(value);
+/**
+ * Commands that destroy operator data and MUST be confirmed before dispatch.
+ *
+ * Mirrors the agent's own `destructive` flag. The agent deliberately does not
+ * prompt inside `run()` — its confirmation lives in the DOM layer, which a remote
+ * trigger never reaches — so the "are you sure?" is the CALLER's job. For a
+ * remote command that means the app, before it asks the backend to dispatch.
+ *
+ * `clear-queue` deletes queued work that then never prints. print#235 (agent
+ * v2.2.3) stopped it destroying in-flight ACKs, but queued jobs are still lost,
+ * and the operator who loses them is not the one who pressed the button.
+ */
+export const DESTRUCTIVE_AGENT_COMMANDS = ['clear-queue'];
+/* -------------------------------------------------------------------------- */
 /*  Client → server frames                                                    */
 /* -------------------------------------------------------------------------- */
 /**
@@ -137,6 +197,14 @@ export const isSocketAction = (value) => typeof value === 'string' && SOCKET_ACT
  * shipped in 1.10.x, but the action string was never added to these two arrays —
  * so `isClientSocketAction`-style checks and exhaustive switches keyed off
  * `ClientSocketAction` silently excluded a live action. Corrected in 1.10.5.
+ *
+ * `agent_command_result` is declared but **NOT live** (print#224, 1.10.8): no
+ * `$default` union entry or handler exists for it yet, so the api answers it with
+ * `400 Invalid message`. It is in this array — the full vocabulary — and out of
+ * `LIVE_CLIENT_SOCKET_ACTIONS` below, which is exactly the distinction the two
+ * arrays exist to carry. Do not "fix the inconsistency" by adding it there; that
+ * is the inverse of the 1.10.5 bug, and it would tell a consumer the frame is
+ * accepted when it is rejected.
  */
 export const CLIENT_SOCKET_ACTIONS = [
     'auth',
@@ -145,8 +213,13 @@ export const CLIENT_SOCKET_ACTIONS = [
     'ack',
     'register_printers',
     'export_local_rules',
+    'agent_command_result',
 ];
-/** Client→server actions the backend accepts **today**. */
+/**
+ * Client→server actions the backend accepts **today** — a strict subset of
+ * `CLIENT_SOCKET_ACTIONS`. Anything declared but absent here is published ahead
+ * of its handler and will be rejected `400 Invalid message` on the wire.
+ */
 export const LIVE_CLIENT_SOCKET_ACTIONS = [
     'auth',
     'logs',

package/package.json

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