@hw-connector/client 0.0.0-stage → 2.7.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @hw-connector/client
+
+Клиент HW agent (hw-connector) для браузера и Node.js 18+: ККТ, банковские терминалы, продажа одной операцией, печать
+(PDF, HTML, этикетки), весы, дисплеи и события. TypeScript-типы в комплекте, без зависимостей.
+
+```js
+import {HwConnector, item, kopecks} from '@hw-connector/client';
+
+const hw = new HwConnector();                     // http://localhost:7790
+
+const r = await hw.checkout({
+  registerId: 1, terminalId: 2,
+  receipt: {type: 'SELL', items: [item('Билет', kopecks(1500))], payments: [{type: 'CARD', amount: kopecks(1500)}]},
+}, {idempotencyKey: 'order-123', onStage: s => console.log(s)});   // «Приложите карту к терминалу»
+console.log(r.receipt.number, r.payment.paymentRef);
+```
+
+- **Операции** (`checkout`, `registers.*`, `terminals.*`, `print`, `labels.print`…) идут с ключом идемпотентности и ждут результат
+  (`Prefer: wait`, затем опрос). При обрыве связи запрос повторяется **с тем же ключом** — оплата и чек не пройдут дважды.
+  Свой ключ (`idempotencyKey: 'order-123'`) делает безопасным и повтор после перезагрузки страницы.
+- **Ошибки** — `HwError` с кодом агента: `PAYMENT_CANCELLED`, `PAYMENT_NOT_CANCELLED`, `DEVICE_ERROR`, `VALIDATION_ERROR`,
+  `SITE_NOT_ALLOWED` (сайт ждёт разрешения кассира), `AGENT_UNAVAILABLE` (агент не запущен).
+- **События**: `hw.events({barcode, weight, printer, operation, power, qr, card})` → функция отписки.
+- **Печать**: `hw.print({urls | document | images | raw | html | htmlUrl, printer | device | role, options})`, `hw.printHtml(html)`,
+  `hw.printers.status()`, `hw.printers.capabilities(name)`, `hw.printers.jobs()`, `cancel`, `retry`.
+- **Этикетки**: `hw.labels.print('price-zpl', {name, price, barcode}, {device: 4})`.
+- **Весы**: `hw.scales.weight(3)`; **компьютер**: `hw.computer()` (machineId для привязки кассы к ПК).
+- **Токен** агента: `new HwConnector({token})`; **подпись запросов** ключом сайта: `signer` — см. `examples/sign-server.mjs`.
+
+- **ККТ целиком**: `registers.shift/openShift/closeShift/xReport/calculationState/receipt/correction/cashIn/cashOut/text/openCashDrawer`,
+  ФН — `registers.fnStatus/fnDocument/printFnDocument`, `registers.counters`.
+- **Терминал**: `terminals.pay/cancel/refund/emergencyReversal/settlement/report/lastSlip`.
+- **Дисплей и прочее**: `displays.show/clear/qr/get`, `openCashDrawer(id)`, `exchange(id, {hex})`, `qrUrl(text)`, `files.*`,
+  `emulators.list/setMode` (режимы ответа для автотестов), `operations.list/get`, `labels.get/render`, `printers.queue/clearQueue`.
+
+Примеры: `examples/all-features.mjs` — все функции по порядку (на эмуляторах проходит целиком: `node examples/all-features.mjs`),
+`examples/plain.html` (без сборки), `examples/react.tsx`, `examples/vue.vue`, `examples/sign-server.mjs`.
+Общие правила API и клиенты для других языков — [../README.md](../README.md).
+
+Сборка и тесты: `npm install && npm test` (TypeScript → `dist/`). Публикация в npm — `npm publish --access public`
+(пакет пока не опубликован).

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+import type { CardPayment, CheckoutRequest, CheckoutResult, Computer, Device, Events, FiscalDocument, FnStatus, Label, MarkingCheckRequest, MarkingCheckResult, Operation, Operator, PrintJob, PrinterStatus, Receipt, TextLine, Weight } from './types.js';
+export * from './types.js';
+/**
+ * Подпись запроса для сайтов, чей ключ задан в агенте: строку подписывает сервер сайта закрытым ключом
+ * (SHA256withECDSA или SHA256withRSA) и возвращает подпись в base64. Закрытый ключ в браузер не попадает.
+ */
+export type Signer = (canonical: string) => Promise<string>;
+export interface HwConnectorOptions {
+    /** Адрес агента; по умолчанию http://localhost:7790 */
+    baseUrl?: string;
+    /** Токен API агента (Authorization: Bearer) */
+    token?: string;
+    /** Подпись запросов ключом сайта */
+    signer?: Signer;
+    /** Свой fetch (Node < 18, тесты) */
+    fetch?: typeof fetch;
+    /** Сколько раз повторять запрос при обрыве связи (с тем же ключом идемпотентности) */
+    retries?: number;
+    /** Сколько ждать результат операции, секунд; по умолчанию 240 (терминалу нужно время) */
+    operationTimeoutSec?: number;
+}
+/** Ошибка агента или операции: code — машинный код (DEVICE_ERROR, PAYMENT_CANCELLED, VALIDATION_ERROR, SITE_NOT_ALLOWED…) */
+export declare class HwError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly details?: unknown;
+    readonly operation?: Operation;
+    constructor(code: string, message: string, extra?: {
+        status?: number;
+        details?: unknown;
+        operation?: Operation;
+    });
+}
+export interface OperationCallOptions {
+    /** Свой ключ идемпотентности (например, номер заказа): повтор с ним вернёт ту же операцию */
+    idempotencyKey?: string;
+    /** Сколько ждать результат, секунд */
+    timeoutSec?: number;
+    /** Этапы для кассира: «Приложите карту к терминалу» */
+    onStage?: (stage: string, op: Operation) => void;
+}
+export declare class HwConnector {
+    readonly baseUrl: string;
+    private readonly token?;
+    private readonly signer?;
+    private readonly fetchFn;
+    private readonly retries;
+    private readonly operationTimeoutSec;
+    constructor(options?: HwConnectorOptions);
+    /**
+     * Запрос к API; ответ JSON. Ошибка HTTP — HwError с кодом из ответа агента (RFC 9457).
+     */
+    request<T>(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /**
+     * Операция: POST с ключом идемпотентности и ожиданием до её окончания.
+     */
+    operation<T = unknown>(path: string, body?: unknown, options?: OperationCallOptions): Promise<Operation<T>>;
+    /**
+     * Операция и сразу её результат; неудача — HwError с кодом операции (PAYMENT_CANCELLED, DEVICE_ERROR…).
+     */
+    run<T = unknown>(path: string, body?: unknown, options?: OperationCallOptions): Promise<T>;
+    health(): Promise<{
+        status: string;
+        version: string;
+        startedAt: string;
+        power?: unknown;
+    }>;
+    devices(): Promise<Device[]>;
+    computer(): Promise<Computer>;
+    /** Агент запущен? */
+    available(): Promise<boolean>;
+    readonly registers: {
+        shift: (id: number) => Promise<{
+            status: "OPENED" | "CLOSED" | "EXPIRED";
+            number?: number;
+        }>;
+        openShift: (id: number, operator?: Operator) => Promise<FiscalDocument>;
+        closeShift: (id: number, operator?: Operator) => Promise<FiscalDocument>;
+        xReport: (id: number, operator?: Operator) => Promise<void>;
+        cashIn: (id: number, amount: number, operator?: Operator) => Promise<FiscalDocument>;
+        cashOut: (id: number, amount: number, operator?: Operator) => Promise<FiscalDocument>;
+        receipt: (id: number, receipt: Receipt, options?: OperationCallOptions) => Promise<FiscalDocument>;
+        correction: (id: number, receipt: Receipt, correction: {
+            type: "SELF" | "INSTRUCTION";
+            baseDate: string;
+            baseNumber?: string;
+        }) => Promise<FiscalDocument>;
+        text: (id: number, lines: TextLine[]) => Promise<void>;
+        openCashDrawer: (id: number) => Promise<void>;
+        /** Отчёт о текущем состоянии расчётов */
+        calculationState: (id: number, operator?: Operator) => Promise<FiscalDocument>;
+        counters: (id: number) => Promise<Record<string, unknown>>;
+        /** Срок ФН и непереданные в ОФД */
+        fnStatus: (id: number) => Promise<FnStatus>;
+        /** Документ из ФН по номеру: теги */
+        fnDocument: (id: number, number: number) => Promise<Record<string, unknown>>;
+        /** Копия документа из ФН на ленте */
+        printFnDocument: (id: number, number: number) => Promise<void>;
+    };
+    /** Продажа или возврат целиком: карта → чек → слип; если чек не напечатан, оплата отменяется */
+    checkout(request: CheckoutRequest, options?: OperationCallOptions): Promise<CheckoutResult>;
+    readonly marking: {
+        /** «Проверь код → можно продать»: Честный знак через ТС ПИоТ, локальный модуль или ГИС МТ */
+        check: (request: MarkingCheckRequest) => Promise<MarkingCheckResult>;
+        status: () => Promise<Record<string, unknown>>;
+    };
+    readonly terminals: {
+        pay: (id: number, amount: number, options?: OperationCallOptions) => Promise<CardPayment>;
+        refund: (id: number, amount: number, paymentRef: string) => Promise<CardPayment>;
+        cancel: (id: number, amount: number, paymentRef: string) => Promise<CardPayment>;
+        settlement: (id: number) => Promise<CardPayment>;
+        emergencyReversal: (id: number, amount: number, paymentRef?: string) => Promise<CardPayment>;
+        /** Отчёт терминала: краткий или полный */
+        report: (id: number, full?: boolean) => Promise<CardPayment>;
+        /** Последний слип — если касса его потеряла */
+        lastSlip: (id: number) => Promise<{
+            operationId: string;
+            type: string;
+            finishedAt: string;
+            slip: string[];
+        }>;
+    };
+    print(job: PrintJob, options?: OperationCallOptions): Promise<Record<string, unknown>>;
+    /** Напечатать HTML-страницу (как из браузера) */
+    printHtml(html: string, target?: Pick<PrintJob, 'printer' | 'device' | 'role' | 'copies' | 'options'>): Promise<Record<string, unknown>>;
+    readonly printers: {
+        list: () => Promise<{
+            name: string;
+            isDefault: boolean;
+            roles: string[];
+        }[]>;
+        status: () => Promise<PrinterStatus[]>;
+        capabilities: (name: string) => Promise<Record<string, unknown>>;
+        jobs: (limit?: number) => Promise<Operation<unknown>[]>;
+        cancel: (id: string) => Promise<Operation<unknown>>;
+        retry: (id: string) => Promise<unknown>;
+        /** Очередь принтера в Windows */
+        queue: (name: string) => Promise<Record<string, unknown>[]>;
+        clearQueue: (name: string) => Promise<Record<string, unknown>>;
+    };
+    readonly labels: {
+        list: () => Promise<Label[]>;
+        get: (name: string) => Promise<Label>;
+        /** Подставить данные, не печатая: готовые команды принтера */
+        render: (name: string, data: Record<string, string>) => Promise<{
+            text: string;
+        }>;
+        print: (name: string, data: Record<string, string>, target?: {
+            device?: number;
+            printer?: string;
+            role?: string;
+            copies?: number;
+        }) => Promise<unknown>;
+    };
+    readonly scales: {
+        weight: (id: number) => Promise<Weight>;
+        zero: (id: number) => Promise<void>;
+    };
+    readonly displays: {
+        show: (id: number, lines: string[]) => Promise<unknown>;
+        clear: (id: number) => Promise<unknown>;
+        /** QR-код на дисплее (оплата по СБП) */
+        qr: (id: number, payload: string, top?: string, bottom?: string) => Promise<unknown>;
+        get: (id: number) => Promise<Record<string, unknown>>;
+    };
+    /** Отдельный денежный ящик (не через ККТ) */
+    openCashDrawer(drawerId: number): Promise<unknown>;
+    /** Порт устройства (COM, TCP, HID): отправить байты и прочитать ответ */
+    exchange(channelId: number, request: {
+        hex?: string;
+        base64?: string;
+        text?: string;
+        charset?: string;
+        readTimeoutMs?: number;
+        maxBytes?: number;
+        until?: string;
+        [k: string]: unknown;
+    }): Promise<{
+        bytes: number;
+        hex: string;
+        base64: string;
+        text?: string;
+        crcValid?: boolean;
+    }>;
+    /** Адрес картинки PNG с QR-кодом — для <img src> */
+    qrUrl(text: string, size?: number): string;
+    /** Файлы в разрешённой папке агента (hw.files.enabled) */
+    readonly files: {
+        list: (dir?: string) => Promise<{
+            path: string;
+            size: number;
+            modified: string;
+            directory: boolean;
+        }[]>;
+        read: (path: string) => Promise<{
+            path: string;
+            text?: string;
+            base64?: string;
+        }>;
+        write: (path: string, content: {
+            text?: string;
+            base64?: string;
+        }) => Promise<unknown>;
+        delete: (path: string) => Promise<unknown>;
+    };
+    /** Режимы ответа эмуляторов — для разработки и автотестов: NO_PAPER, OFFLINE, DECLINED, TIMEOUT… */
+    readonly emulators: {
+        list: () => Promise<{
+            number: number;
+            type: string;
+            name: string;
+            mode: {
+                mode: string;
+                once: boolean;
+                modes: {
+                    id: string;
+                    title: string;
+                    description: string;
+                }[];
+            };
+        }[]>;
+        setMode: (number: number, mode: string, once?: boolean) => Promise<unknown>;
+    };
+    /** Журнал операций */
+    readonly operations: {
+        list: (limit?: number) => Promise<Operation<unknown>[]>;
+        get: (id: string) => Promise<Operation<unknown>>;
+    };
+    /**
+     * Подписка на события агента: операции, сканер, весы, принтеры, питание. Браузер переподключается сам.
+     *
+     * @returns отписка
+     */
+    events(handlers: Events, EventSourceImpl?: typeof EventSource): () => void;
+}
+/** Рубли → копейки без ошибок округления: 1499.9 → 149990 */
+export declare function kopecks(rubles: number): number;
+/** Позиция чека: цена в копейках, стоимость считается сама */
+export declare function item(name: string, price: number, quantity?: number, extra?: Partial<import('./types.js').ReceiptItem>): import('./types.js').ReceiptItem;

package/dist/index.js

@@ -0,0 +1,299 @@
+// Клиент hw-connector: обёртка над REST /api/v1 и событиями (SSE) HW agent.
+// Операции (чек, оплата, печать) идут с ключом идемпотентности: при обрыве связи запрос повторяется с тем же ключом,
+// и агент не проведёт оплату и не пробьёт чек второй раз.
+export * from './types.js';
+/** Ошибка агента или операции: code — машинный код (DEVICE_ERROR, PAYMENT_CANCELLED, VALIDATION_ERROR, SITE_NOT_ALLOWED…) */
+export class HwError extends Error {
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.name = 'HwError';
+        this.code = code;
+        this.status = extra.status;
+        this.details = extra.details;
+        this.operation = extra.operation;
+    }
+}
+function uuid() {
+    const c = globalThis.crypto;
+    if (c && 'randomUUID' in c) {
+        return c.randomUUID();
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, ch => {
+        const r = Math.random() * 16 | 0;
+        return (ch === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+    });
+}
+async function sha256Hex(body) {
+    const data = new TextEncoder().encode(body);
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', data);
+    return Array.from(new Uint8Array(digest), b => b.toString(16).padStart(2, '0')).join('');
+}
+const finished = (s) => s === 'SUCCEEDED' || s === 'FAILED' || s === 'UNKNOWN';
+export class HwConnector {
+    constructor(options = {}) {
+        // ---------- ККТ ----------
+        this.registers = {
+            shift: (id) => this.request('GET', `/api/v1/registers/${id}/shift`),
+            openShift: (id, operator) => this.run(`/api/v1/registers/${id}/shift/open`, { operator }),
+            closeShift: (id, operator) => this.run(`/api/v1/registers/${id}/shift/close`, { operator }),
+            xReport: (id, operator) => this.run(`/api/v1/registers/${id}/reports/x`, { operator }),
+            cashIn: (id, amount, operator) => this.run(`/api/v1/registers/${id}/cash/in`, { operator, amount }),
+            cashOut: (id, amount, operator) => this.run(`/api/v1/registers/${id}/cash/out`, { operator, amount }),
+            receipt: (id, receipt, options) => this.run(`/api/v1/registers/${id}/receipts`, receipt, options),
+            correction: (id, receipt, correction) => this.run(`/api/v1/registers/${id}/corrections`, { receipt, correction }),
+            text: (id, lines) => this.run(`/api/v1/registers/${id}/documents`, { lines }),
+            openCashDrawer: (id) => this.run(`/api/v1/registers/${id}/cash-drawer/open`),
+            /** Отчёт о текущем состоянии расчётов */
+            calculationState: (id, operator) => this.run(`/api/v1/registers/${id}/reports/calculation-state`, { operator }),
+            counters: (id) => this.request('GET', `/api/v1/registers/${id}/counters`),
+            /** Срок ФН и непереданные в ОФД */
+            fnStatus: (id) => this.request('GET', `/api/v1/registers/${id}/fn-status`),
+            /** Документ из ФН по номеру: теги */
+            fnDocument: (id, number) => this.request('GET', `/api/v1/registers/${id}/fn-documents/${number}`),
+            /** Копия документа из ФН на ленте */
+            printFnDocument: (id, number) => this.run(`/api/v1/registers/${id}/fn-documents/${number}/print`),
+        };
+        // ---------- маркировка ----------
+        this.marking = {
+            /** «Проверь код → можно продать»: Честный знак через ТС ПИоТ, локальный модуль или ГИС МТ */
+            check: (request) => this.request('POST', '/api/v1/marking/check', request),
+            status: () => this.request('GET', '/api/v1/marking/status'),
+        };
+        // ---------- терминал ----------
+        this.terminals = {
+            pay: (id, amount, options) => this.run(`/api/v1/terminals/${id}/payments`, { amount }, options),
+            refund: (id, amount, paymentRef) => this.run(`/api/v1/terminals/${id}/refunds`, { amount, paymentRef }),
+            cancel: (id, amount, paymentRef) => this.run(`/api/v1/terminals/${id}/cancellations`, { amount, paymentRef }),
+            settlement: (id) => this.run(`/api/v1/terminals/${id}/settlements`),
+            emergencyReversal: (id, amount, paymentRef) => this.run(`/api/v1/terminals/${id}/emergency-reversals`, { amount, paymentRef }),
+            /** Отчёт терминала: краткий или полный */
+            report: (id, full = false) => this.run(`/api/v1/terminals/${id}/reports?full=${full}`),
+            /** Последний слип — если касса его потеряла */
+            lastSlip: (id) => this.request('GET', `/api/v1/terminals/${id}/last-slip`),
+        };
+        this.printers = {
+            list: () => this.request('GET', '/api/v1/printers'),
+            status: () => this.request('GET', '/api/v1/printers/status'),
+            capabilities: (name) => this.request('GET', '/api/v1/printers/capabilities?name=' + encodeURIComponent(name)),
+            jobs: (limit = 50) => this.request('GET', '/api/v1/print-jobs?limit=' + limit),
+            cancel: (id) => this.request('POST', `/api/v1/print-jobs/${id}/cancel`),
+            retry: (id) => this.run(`/api/v1/print-jobs/${id}/retry`),
+            /** Очередь принтера в Windows */
+            queue: (name) => this.request('GET', '/api/v1/printers/jobs?name=' + encodeURIComponent(name)),
+            clearQueue: (name) => this.request('DELETE', '/api/v1/printers/jobs?name=' + encodeURIComponent(name)),
+        };
+        // ---------- этикетки, весы, дисплей ----------
+        this.labels = {
+            list: () => this.request('GET', '/api/v1/labels'),
+            get: (name) => this.request('GET', `/api/v1/labels/${encodeURIComponent(name)}`),
+            /** Подставить данные, не печатая: готовые команды принтера */
+            render: (name, data) => this.request('POST', `/api/v1/labels/${encodeURIComponent(name)}/render`, data),
+            print: (name, data, target = {}) => this.run(`/api/v1/labels/${encodeURIComponent(name)}/print`, { ...target, data }),
+        };
+        this.scales = {
+            weight: (id) => this.request('GET', `/api/v1/scales/${id}/weight`),
+            zero: (id) => this.run(`/api/v1/scales/${id}/zero`),
+        };
+        this.displays = {
+            show: (id, lines) => this.request('POST', `/api/v1/displays/${id}`, { lines }),
+            clear: (id) => this.request('POST', `/api/v1/displays/${id}`, { lines: [] }),
+            /** QR-код на дисплее (оплата по СБП) */
+            qr: (id, payload, top, bottom) => this.request('POST', `/api/v1/displays/${id}/qr`, { payload, top, bottom }),
+            get: (id) => this.request('GET', `/api/v1/displays/${id}`),
+        };
+        /** Файлы в разрешённой папке агента (hw.files.enabled) */
+        this.files = {
+            list: (dir = '') => this.request('GET', '/api/v1/files' + (dir ? '?dir=' + encodeURIComponent(dir) : '')),
+            read: (path) => this.request('GET', '/api/v1/files/content?path=' + encodeURIComponent(path)),
+            write: (path, content) => this.request('PUT', '/api/v1/files/content?path=' + encodeURIComponent(path), content),
+            delete: (path) => this.request('DELETE', '/api/v1/files?path=' + encodeURIComponent(path)),
+        };
+        /** Режимы ответа эмуляторов — для разработки и автотестов: NO_PAPER, OFFLINE, DECLINED, TIMEOUT… */
+        this.emulators = {
+            list: () => this.request('GET', '/api/v1/emulators'),
+            setMode: (number, mode, once = false) => this.request('PUT', `/api/v1/emulators/${number}`, { mode, once }),
+        };
+        /** Журнал операций */
+        this.operations = {
+            list: (limit = 50) => this.request('GET', '/api/v1/operations?limit=' + limit),
+            get: (id) => this.request('GET', '/api/v1/operations/' + id),
+        };
+        this.baseUrl = (options.baseUrl ?? 'http://localhost:7790').replace(/\/+$/, '');
+        this.token = options.token;
+        this.signer = options.signer;
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f) {
+            throw new Error('Нет fetch: передайте options.fetch');
+        }
+        this.fetchFn = f.bind(globalThis);
+        this.retries = options.retries ?? 3;
+        this.operationTimeoutSec = options.operationTimeoutSec ?? 240;
+    }
+    // ---------- транспорт ----------
+    /**
+     * Запрос к API; ответ JSON. Ошибка HTTP — HwError с кодом из ответа агента (RFC 9457).
+     */
+    async request(method, path, body, headers = {}) {
+        const text = body === undefined ? undefined : JSON.stringify(body);
+        const h = { ...headers };
+        if (text !== undefined) {
+            h['Content-Type'] = 'application/json';
+        }
+        if (this.token) {
+            h['Authorization'] = 'Bearer ' + this.token;
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.retries; attempt++) {
+            // подпись заново на каждую попытку: агент не принимает одну подпись дважды
+            if (this.signer) {
+                const ts = String(Date.now());
+                const canonical = ts + '\n' + method.toUpperCase() + '\n' + path + '\n' + await sha256Hex(text ?? '');
+                h['X-HW-Timestamp'] = ts;
+                h['X-HW-Signature'] = await this.signer(canonical);
+            }
+            let res;
+            try {
+                res = await this.fetchFn(this.baseUrl + path, { method, headers: h, body: text });
+            }
+            catch (e) {
+                lastError = e;
+                // повторять безопасно только чтение и операции с ключом идемпотентности
+                if (method !== 'GET' && !h['Idempotency-Key']) {
+                    break;
+                }
+                await new Promise(r => setTimeout(r, 500 * (attempt + 1)));
+                continue;
+            }
+            const raw = await res.text();
+            const data = raw ? safeJson(raw) : undefined;
+            if (!res.ok) {
+                const p = (data ?? {});
+                throw new HwError(p.code ?? 'HTTP_' + res.status, p.detail ?? p.title ?? ('Ошибка агента ' + res.status), { status: res.status, details: data });
+            }
+            return data;
+        }
+        throw new HwError('AGENT_UNAVAILABLE', 'Агент hw-connector недоступен по адресу ' + this.baseUrl
+            + ': запущен ли он на этом компьютере?', { details: lastError });
+    }
+    /**
+     * Операция: POST с ключом идемпотентности и ожиданием до её окончания.
+     */
+    async operation(path, body, options = {}) {
+        const key = options.idempotencyKey ?? uuid();
+        const deadline = Date.now() + (options.timeoutSec ?? this.operationTimeoutSec) * 1000;
+        let op = await this.request('POST', path, body ?? {}, { 'Idempotency-Key': key, 'Prefer': 'wait=25' });
+        let stage = op.stage;
+        if (stage && options.onStage) {
+            options.onStage(stage, op);
+        }
+        while (!finished(op.status)) {
+            if (Date.now() > deadline) {
+                throw new HwError('TIMEOUT', 'Операция не закончилась вовремя: ' + op.id, { operation: op });
+            }
+            op = await this.request('GET', '/api/v1/operations/' + op.id, undefined, { 'Prefer': 'wait=25' });
+            if (op.stage && op.stage !== stage && options.onStage) {
+                stage = op.stage;
+                options.onStage(stage, op);
+            }
+        }
+        return op;
+    }
+    /**
+     * Операция и сразу её результат; неудача — HwError с кодом операции (PAYMENT_CANCELLED, DEVICE_ERROR…).
+     */
+    async run(path, body, options = {}) {
+        const op = await this.operation(path, body, options);
+        if (op.status !== 'SUCCEEDED') {
+            const e = op.error ?? { code: op.status, message: 'Операция ' + op.status };
+            throw new HwError(e.code, e.message, { details: e.details, operation: op });
+        }
+        return op.result;
+    }
+    // ---------- агент ----------
+    health() {
+        return this.request('GET', '/api/v1/health');
+    }
+    devices() {
+        return this.request('GET', '/api/v1/devices');
+    }
+    computer() {
+        return this.request('GET', '/api/v1/system/computer');
+    }
+    /** Агент запущен? */
+    async available() {
+        try {
+            await this.health();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Продажа или возврат целиком: карта → чек → слип; если чек не напечатан, оплата отменяется */
+    checkout(request, options) {
+        return this.run('/api/v1/checkouts', request, options);
+    }
+    // ---------- печать ----------
+    print(job, options) {
+        return this.run('/api/v1/print-jobs', job, options);
+    }
+    /** Напечатать HTML-страницу (как из браузера) */
+    printHtml(html, target = {}) {
+        return this.print({ ...target, html });
+    }
+    // ---------- ящик, порт, файлы, эмуляторы, журнал ----------
+    /** Отдельный денежный ящик (не через ККТ) */
+    openCashDrawer(drawerId) {
+        return this.request('POST', `/api/v1/cash-drawers/${drawerId}/open`);
+    }
+    /** Порт устройства (COM, TCP, HID): отправить байты и прочитать ответ */
+    exchange(channelId, request) {
+        return this.request('POST', `/api/v1/channels/${channelId}/exchange`, request);
+    }
+    /** Адрес картинки PNG с QR-кодом — для <img src> */
+    qrUrl(text, size = 300) {
+        return `${this.baseUrl}/api/v1/qr?text=${encodeURIComponent(text)}&size=${size}`;
+    }
+    // ---------- события ----------
+    /**
+     * Подписка на события агента: операции, сканер, весы, принтеры, питание. Браузер переподключается сам.
+     *
+     * @returns отписка
+     */
+    events(handlers, EventSourceImpl = globalThis.EventSource) {
+        if (!EventSourceImpl) {
+            throw new Error('Нет EventSource: передайте реализацию вторым параметром (в Node — пакет eventsource)');
+        }
+        const url = this.baseUrl + '/api/v1/events' + (this.token ? '?access_token=' + encodeURIComponent(this.token) : '');
+        const es = new EventSourceImpl(url);
+        for (const [name, fn] of Object.entries(handlers)) {
+            if (name === 'error') {
+                es.addEventListener('error', fn);
+            }
+            else if (fn) {
+                es.addEventListener(name, (e) => fn(safeJson(e.data)));
+            }
+        }
+        return () => es.close();
+    }
+}
+function safeJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+}
+// ---------- помощники для чека ----------
+/** Рубли → копейки без ошибок округления: 1499.9 → 149990 */
+export function kopecks(rubles) {
+    return Math.round(rubles * 100);
+}
+/** Позиция чека: цена в копейках, стоимость считается сама */
+export function item(name, price, quantity = 1, extra = {}) {
+    return {
+        name, price, quantity, amount: Math.round(price * quantity),
+        vat: 'NONE', paymentMethod: 'FULL_PAYMENT', paymentObject: 'SERVICE', ...extra,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,270 @@
+export type OperationStatus = 'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'UNKNOWN';
+export interface OperationError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface Operation<T = unknown> {
+    id: string;
+    type: string;
+    idempotencyKey?: string;
+    resources?: string[];
+    status: OperationStatus;
+    stage?: string;
+    createdAt?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    result?: T;
+    error?: OperationError;
+    warnings?: string[];
+}
+export interface Operator {
+    name: string;
+    inn?: string;
+}
+export type ReceiptType = 'SELL' | 'SELL_RETURN' | 'BUY' | 'BUY_RETURN';
+export type Taxation = 'OSN' | 'USN_INCOME' | 'USN_INCOME_OUTCOME' | 'ESHN' | 'PATENT';
+export type Vat = 'NONE' | 'VAT0' | 'VAT5' | 'VAT7' | 'VAT10' | 'VAT20' | 'VAT22' | 'VAT105' | 'VAT107' | 'VAT110' | 'VAT120' | 'VAT122';
+export type PaymentMethod = 'FULL_PREPAYMENT' | 'PREPAYMENT' | 'ADVANCE' | 'FULL_PAYMENT' | 'PARTIAL_PAYMENT' | 'CREDIT' | 'CREDIT_PAYMENT';
+export type PaymentObject = 'COMMODITY' | 'EXCISE' | 'JOB' | 'SERVICE' | 'GAMBLING_BET' | 'GAMBLING_PRIZE' | 'LOTTERY' | 'LOTTERY_PRIZE' | 'INTELLECTUAL_ACTIVITY' | 'PAYMENT' | 'AGENT_COMMISSION' | 'COMPOSITE' | 'ANOTHER';
+export type PaymentType = 'CASH' | 'CARD' | 'PREPAID' | 'CREDIT' | 'OTHER';
+export interface TextLine {
+    kind: 'TEXT' | 'PAIR' | 'SEPARATOR';
+    text?: string;
+    right?: string;
+    align?: 'LEFT' | 'CENTER' | 'RIGHT';
+}
+export interface ReceiptItem {
+    name: string;
+    /** Цена, копейки */
+    price: number;
+    quantity: number;
+    /** Стоимость = цена × количество, копейки */
+    amount: number;
+    vat: Vat;
+    paymentMethod: PaymentMethod;
+    paymentObject: PaymentObject;
+    department?: number;
+    /** Код маркировки (модуль маркировки) */
+    marking?: Marking;
+}
+/** Код маркировки позиции: агент проверит его в Честном знаке перед чеком, если нет industryProps */
+export interface Marking {
+    /** Код со сканера, с разделителями GS (символ 29) */
+    code: string;
+    /** Дробное количество из упаковки, «1/10» */
+    fraction?: string;
+    /** Мера количества (тег 2108); по умолчанию PIECE */
+    measure?: string;
+    /** Результат проверки из marking.check() — тогда агент не проверяет код второй раз */
+    industryProps?: string;
+}
+export interface MarkingCheckRequest {
+    /** Чек, в который пойдут коды; по умолчанию SELL */
+    type?: Receipt['type'];
+    registerId?: number;
+    codes: {
+        code: string; /** Цена за единицу, копейки */
+        price?: number;
+        fraction?: string;
+    }[];
+}
+export interface MarkingCheckResult {
+    /** Все коды можно продать */
+    allowed: boolean;
+    items: {
+        code: string;
+        cis: string;
+        gtin: string;
+        allowed: boolean;
+        reasons: string[];
+        warnings: string[];
+        /** piot, lm, online, emulator; пусто — никто не ответил */
+        source?: string;
+        offline: boolean;
+        industryProps?: string;
+        info?: Record<string, unknown>;
+    }[];
+}
+export interface Receipt {
+    type: ReceiptType;
+    taxation?: Taxation;
+    operator?: Operator;
+    customer?: {
+        contact?: string;
+        name?: string;
+        inn?: string;
+    };
+    header?: TextLine[];
+    items: ReceiptItem[];
+    payments: {
+        type: PaymentType;
+        amount: number;
+    }[];
+    footer?: TextLine[];
+    electronic?: boolean;
+    senderEmail?: string;
+    settlementPlace?: string;
+}
+export interface FiscalDocument {
+    number?: number;
+    fiscalSign?: string;
+    shiftNumber?: number;
+    receiptNumber?: number;
+    fnNumber?: string;
+    registrationNumber?: string;
+    dateTime?: string;
+    total?: number;
+    qrCode?: string;
+    fnsUrl?: string;
+    /** Лента чека для просмотра на экране */
+    tape?: string[];
+}
+export interface CardPayment {
+    /** Ссылка на оплату — для возврата и отмены; формат как UniversalID ККМ-Сервера */
+    paymentRef: string;
+    amount: number;
+    card?: string;
+    rrn?: string;
+    authCode?: string;
+    terminalId?: string;
+    dateTime?: string;
+    slip?: string[];
+}
+export interface CheckoutRequest {
+    registerId: number;
+    terminalId?: number;
+    receipt: Receipt;
+    originalPaymentRef?: string;
+    printSlip?: boolean;
+}
+export interface CheckoutResult {
+    receipt: FiscalDocument;
+    payment?: CardPayment;
+    tape?: string[];
+}
+export interface PrintOptions {
+    pages?: string;
+    duplex?: 'ONE_SIDED' | 'LONG_EDGE' | 'SHORT_EDGE';
+    tray?: string;
+    color?: 'COLOR' | 'MONOCHROME';
+    dpi?: number;
+    nUp?: 1 | 2 | 4 | 6 | 9 | 16;
+    collate?: boolean;
+    orientation?: 'AUTO' | 'PORTRAIT' | 'LANDSCAPE';
+    rotation?: 0 | 90 | 270;
+    scaling?: 'ACTUAL' | 'FIT' | 'SHRINK';
+    paperWidthMm?: number;
+    paperHeightMm?: number;
+    marginsMm?: string;
+    jobName?: string;
+}
+/** Ровно один источник: urls, document, images, raw, text, html или htmlUrl */
+export interface PrintJob {
+    urls?: string[];
+    /** PDF в base64 */
+    document?: string;
+    images?: string[];
+    /** Команды принтера в base64 */
+    raw?: string;
+    text?: TextLine[];
+    html?: string;
+    htmlUrl?: string;
+    printer?: string;
+    device?: number;
+    role?: 'tickets' | 'documents' | string;
+    copies?: number;
+    options?: PrintOptions;
+    expireAfterSec?: number;
+}
+export interface Device {
+    id: number;
+    code?: string;
+    kind: 'FISCAL_REGISTER' | 'PAYMENT_TERMINAL' | 'BARCODE_SCANNER' | 'PRINTER' | 'CASH_DRAWER' | 'CUSTOMER_DISPLAY' | 'CARD_READER' | 'CHANNEL' | 'SCALE' | 'SENSOR';
+    type: string;
+    name: string;
+    active: boolean;
+    info?: Record<string, unknown>;
+}
+export interface Weight {
+    deviceId: number;
+    /** Килограммы */
+    weight: number;
+    stable: boolean;
+    at: string;
+}
+export interface PrinterStatus {
+    name: string;
+    state: 'READY' | 'PRINTING' | 'OFFLINE' | 'ERROR' | 'UNKNOWN';
+    reasons?: string[];
+    jobs?: number;
+    at: string;
+}
+export interface Label {
+    name: string;
+    title?: string;
+    language: 'ZPL' | 'TSPL' | 'EZPL' | 'ESCPOS';
+    description?: string;
+    body: string;
+    sample?: Record<string, string>;
+    builtIn?: boolean;
+    fields?: string[];
+}
+export interface Computer {
+    machineId: string;
+    hostname: string;
+    user: string;
+    os: string;
+    osVersion: string;
+    arch: string;
+    agentVersion: string;
+    interfaces: {
+        name: string;
+        displayName: string;
+        mac?: string;
+        ipv4: string[];
+        ipv6: string[];
+        virtual: boolean;
+    }[];
+}
+/** События агента (SSE) */
+export interface Events {
+    operation?: (op: Operation) => void;
+    barcode?: (scan: {
+        deviceId: number;
+        code: string;
+        at: string;
+    }) => void;
+    card?: (tap: {
+        deviceId: number;
+        uid: string;
+        at: string;
+    }) => void;
+    weight?: (w: Weight) => void;
+    printer?: (s: PrinterStatus) => void;
+    power?: (p: {
+        source: string;
+        batteryPercent?: number;
+        minutesLeft?: number;
+    }) => void;
+    qr?: (qr: {
+        deviceId: number;
+        payload?: string;
+        amount: number;
+        bank: string;
+    }) => void;
+    display?: (d: unknown) => void;
+    'site-request'?: (r: {
+        origin: string;
+    }) => void;
+    /** Соединение с агентом потеряно (браузер переподключится сам) */
+    error?: (e: Event) => void;
+}
+/** Состояние ФН: срок и непереданные в ОФД */
+export interface FnStatus {
+    validUntil?: string;
+    daysLeft?: number;
+    notSent?: number;
+    firstNotSent?: number;
+    firstNotSentAt?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Типы API агента hw-connector (/api/v1). Суммы — в копейках.
+export {};

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@hw-connector/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.7.0",
+  "description": "Клиент hw-connector для браузера и Node.js: ККТ, банковские терминалы, печать, этикетки, весы — REST и события агента с повторами и идемпотентностью",
+  "homepage": "https://hw-connector.ru/docs/api/agent/",
+  "bugs": {
+    "email": "support@bigbilet.ru"
+  },
+  "author": "BigBilet",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/client.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "hw-connector",
+    "ккт",
+    "54-фз",
+    "атол",
+    "штрих-м",
+    "эквайринг",
+    "печать",
+    "zpl",
+    "весы",
+    "kkm-server",
+    "qz-tray"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}