@kreiseck/kasseneck-api 0.7.0 → 0.7.2

package/dist/esm/payments/index.d.ts

@@ -1,28 +1,39 @@
 /**
  * Unterpfad `@kreiseck/kasseneck-api/payments` — die Zahlungswege, die ein
  * Browser oder ein Node-Prozess wirklich gehen kann: **Stripe-Zahlungslinks**
- * (Fernzahlung per Link/QR-Code) und die **Hobex-Cloud-API** (Kartenzahlung
- * ueber ein bei Hobex registriertes Terminal, gesteuert ueber das Netz).
+ * (Fernzahlung per Link/QR-Code), die **Hobex-Cloud-API** (Kartenzahlung
+ * ueber ein bei Hobex registriertes Terminal, gesteuert ueber das Netz) und
+ * **Hobex HPS ueber Kasseneck Connect** (`./hobex-hps.js`) — ein physisches
+ * Terminal im Kassen-Netz, angesprochen ueber den lokalen Geraete-Agenten.
  *
  * **Was hier bewusst fehlt — und warum es auch nicht nachgeruestet wird:**
  *
- * - **Hobex HPS** spricht **lokal ueber TCP** mit einem angeschlossenen
- *   Terminal (roher Socket auf eine Geraete-IP im selben Netz).
  * - **myPOS** und **SumUp** sind **Android-SDKs**; sie laufen als
  *   Bibliothek in einer Android-App und reden ueber Bluetooth bzw. das
- *   Hersteller-Geraet mit dem Terminal.
+ *   Hersteller-Geraet mit dem Terminal. Ein Browser hat keine
+ *   Android-Laufzeit — das ist keine Luecke in diesem Paket und auch nichts,
+ *   was ein Buendler, ein Polyfill oder WebAssembly aufloest.
  *
- * Ein Browser hat weder rohe TCP-Sockets noch eine Android-Laufzeit. Das ist
- * keine Luecke in diesem Paket und auch nichts, was ein anderer Buendler,
- * ein Polyfill oder eine WebAssembly-Schicht aufloest — es ist eine Grenze der
- * Umgebung. Diese drei Wege gibt es im Flutter-Paket `kasseneck_api`, und dort
- * bleiben sie.
+ * **Frueherer Stand, ueberholt:** hier stand einmal, Hobex HPS sei mangels
+ * roher TCP-Sockets im Browser unerreichbar. Das galt fuer den DIREKTEN
+ * Terminal-Kontakt (Zwilling: `HpsClient` in `kasseneck_api`) und gilt dafuer
+ * weiterhin — aber **Kasseneck Connect** ist ein lokaler Geraete-Agent, der
+ * ueber gewoehnliches HTTP erreichbar ist und **fuer** die Kasse mit dem
+ * Terminal spricht. Das ist kein Widerspruch zur Umgebungsgrenze, sondern ein
+ * zweiter, seit `hobex-hps.js` genutzter Weg um sie herum.
+ *
+ * Wer Gutschrift oder Storno am HPS-Terminal braucht, braucht weiterhin die
+ * Flutter-App: Connect exponiert dafuer (noch) keinen Endpunkt, siehe
+ * `hobex-hps/connect-client.ts`.
  *
  * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** **Keiner** der
- * vier Zahlungs-Endpunkte setzt `allowRegisterUser`; sie laufen alle ueber
- * `checkRequest(req, 'user', …)` und damit nur mit `apiKeyAuth`. Dieses Paket
- * bildet das **nicht** nach — wer darf, entscheidet allein das Backend. Der
- * Hinweis steht **hier** und gilt fuer beide Dateien dieses Unterpfads.
+ * vier Cloud-Zahlungs-Endpunkte (Stripe, Hobex-Cloud) setzt `allowRegisterUser`;
+ * sie laufen alle ueber `checkRequest(req, 'user', …)` und damit nur mit
+ * `apiKeyAuth`. Dieses Paket bildet das **nicht** nach — wer darf, entscheidet
+ * allein das Backend. Der Hinweis steht **hier** und gilt fuer die beiden
+ * Cloud-Dateien dieses Unterpfads; `hobex-hps.js` spricht kein Kasseneck-Backend
+ * und kennt diese Unterscheidung nicht — dort entscheidet allein der
+ * Kopplungstoken von Kasseneck Connect.
  *
  * Welche **anderen** Endpunkte den Weg offen haben, steht bewusst nirgends in
  * diesem Paket: eine abgeschriebene Liste veraltet still, und sie hat hier
@@ -31,3 +42,4 @@
 export { StripeLinkMode, type StripeLinkModeKey } from '../enums/index.js';
 export { type CreateStripeLinkOptions, type StripeCaptureResult, createStripeLink, stripeCaptureIntent, } from './stripe.js';
 export { type HobexPayOptions, type HobexRefundOptions, type HobexTransactionIdOptions, hobexPay, hobexRefund, newHobexTransactionId, } from './hobex.js';
+export { type CardPaymentOutcome, type HpsConnectClient, type HpsConnectClientOptions, type HpsConnectFetch, type HpsConnectFetchResponse, type HpsConnectPaymentOptions, type HpsConnectTarget, type HpsConnectTransactionOptions, type HpsMeasuredCode, type HpsPaymentEvent, type HpsPaymentEventKind, type HpsPaymentObserver, type HpsPaymentOptions, type HpsPayments, type HpsPaymentResult, type HpsPaymentsOptions, type HpsTransactionIdGeneratorOptions, type HpsTransactionResponse, ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, createHpsConnectClient, createHpsPayments, createHpsTransactionIdGenerator, HPS_MEASURED_CODES, HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, INVALID_TRANSACTION_CODE, isApproved, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, isValidHpsTransactionId, mayRetrySafely, MAX_TRANSACTION_ID_LENGTH, newHpsTransactionId, NOT_ABORTABLE_CODE, NO_STATEMENT_CODE, parseHpsTransactionResponse, PREFLIGHT_CONNECT_CODES, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, } from './hobex-hps/index.js';

package/dist/esm/payments/index.js

@@ -1,28 +1,39 @@
 /**
  * Unterpfad `@kreiseck/kasseneck-api/payments` — die Zahlungswege, die ein
  * Browser oder ein Node-Prozess wirklich gehen kann: **Stripe-Zahlungslinks**
- * (Fernzahlung per Link/QR-Code) und die **Hobex-Cloud-API** (Kartenzahlung
- * ueber ein bei Hobex registriertes Terminal, gesteuert ueber das Netz).
+ * (Fernzahlung per Link/QR-Code), die **Hobex-Cloud-API** (Kartenzahlung
+ * ueber ein bei Hobex registriertes Terminal, gesteuert ueber das Netz) und
+ * **Hobex HPS ueber Kasseneck Connect** (`./hobex-hps.js`) — ein physisches
+ * Terminal im Kassen-Netz, angesprochen ueber den lokalen Geraete-Agenten.
  *
  * **Was hier bewusst fehlt — und warum es auch nicht nachgeruestet wird:**
  *
- * - **Hobex HPS** spricht **lokal ueber TCP** mit einem angeschlossenen
- *   Terminal (roher Socket auf eine Geraete-IP im selben Netz).
  * - **myPOS** und **SumUp** sind **Android-SDKs**; sie laufen als
  *   Bibliothek in einer Android-App und reden ueber Bluetooth bzw. das
- *   Hersteller-Geraet mit dem Terminal.
+ *   Hersteller-Geraet mit dem Terminal. Ein Browser hat keine
+ *   Android-Laufzeit — das ist keine Luecke in diesem Paket und auch nichts,
+ *   was ein Buendler, ein Polyfill oder WebAssembly aufloest.
  *
- * Ein Browser hat weder rohe TCP-Sockets noch eine Android-Laufzeit. Das ist
- * keine Luecke in diesem Paket und auch nichts, was ein anderer Buendler,
- * ein Polyfill oder eine WebAssembly-Schicht aufloest — es ist eine Grenze der
- * Umgebung. Diese drei Wege gibt es im Flutter-Paket `kasseneck_api`, und dort
- * bleiben sie.
+ * **Frueherer Stand, ueberholt:** hier stand einmal, Hobex HPS sei mangels
+ * roher TCP-Sockets im Browser unerreichbar. Das galt fuer den DIREKTEN
+ * Terminal-Kontakt (Zwilling: `HpsClient` in `kasseneck_api`) und gilt dafuer
+ * weiterhin — aber **Kasseneck Connect** ist ein lokaler Geraete-Agent, der
+ * ueber gewoehnliches HTTP erreichbar ist und **fuer** die Kasse mit dem
+ * Terminal spricht. Das ist kein Widerspruch zur Umgebungsgrenze, sondern ein
+ * zweiter, seit `hobex-hps.js` genutzter Weg um sie herum.
+ *
+ * Wer Gutschrift oder Storno am HPS-Terminal braucht, braucht weiterhin die
+ * Flutter-App: Connect exponiert dafuer (noch) keinen Endpunkt, siehe
+ * `hobex-hps/connect-client.ts`.
  *
  * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** **Keiner** der
- * vier Zahlungs-Endpunkte setzt `allowRegisterUser`; sie laufen alle ueber
- * `checkRequest(req, 'user', …)` und damit nur mit `apiKeyAuth`. Dieses Paket
- * bildet das **nicht** nach — wer darf, entscheidet allein das Backend. Der
- * Hinweis steht **hier** und gilt fuer beide Dateien dieses Unterpfads.
+ * vier Cloud-Zahlungs-Endpunkte (Stripe, Hobex-Cloud) setzt `allowRegisterUser`;
+ * sie laufen alle ueber `checkRequest(req, 'user', …)` und damit nur mit
+ * `apiKeyAuth`. Dieses Paket bildet das **nicht** nach — wer darf, entscheidet
+ * allein das Backend. Der Hinweis steht **hier** und gilt fuer die beiden
+ * Cloud-Dateien dieses Unterpfads; `hobex-hps.js` spricht kein Kasseneck-Backend
+ * und kennt diese Unterscheidung nicht — dort entscheidet allein der
+ * Kopplungstoken von Kasseneck Connect.
  *
  * Welche **anderen** Endpunkte den Weg offen haben, steht bewusst nirgends in
  * diesem Paket: eine abgeschriebene Liste veraltet still, und sie hat hier
@@ -31,3 +42,4 @@
 export { StripeLinkMode } from '../enums/index.js';
 export { createStripeLink, stripeCaptureIntent, } from './stripe.js';
 export { hobexPay, hobexRefund, newHobexTransactionId, } from './hobex.js';
+export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, createHpsConnectClient, createHpsPayments, createHpsTransactionIdGenerator, HPS_MEASURED_CODES, HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, INVALID_TRANSACTION_CODE, isApproved, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, isValidHpsTransactionId, mayRetrySafely, MAX_TRANSACTION_ID_LENGTH, newHpsTransactionId, NOT_ABORTABLE_CODE, NO_STATEMENT_CODE, parseHpsTransactionResponse, PREFLIGHT_CONNECT_CODES, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, } from './hobex-hps/index.js';

package/dist/esm/printing/index.d.ts

@@ -1,3 +1,3 @@
 export { type PosPaperSize, type PosAlign, type PosFont, type PosCutMode, type PosCodeTable, type PosTextSize, type QrSize, type QrCorrection, type PosStyles, type PosColumn, type EscPosOptions, type EscPosTextOptions, type EscPosHrOptions, type EscPosQrOptions, type EscPosDocument, createEscPosDocument, escPosBytes, escPosReset, escPosSetGlobalCodeTable, escPosSetGlobalFont, escPosSetStyles, escPosText, escPosEmptyLines, escPosFeed, escPosCut, escPosHr, escPosRow, escPosQrCode, encodeEscPosText, qrCodeBytes, escPosMaxCharsPerLine, escPosWortzeilen, wortzeilenText, } from './escpos.js';
 export { escPosPrintableText } from './printable.js';
-export { type UsbEndpointLike, type UsbAlternateLike, type UsbInterfaceLike, type UsbConfigurationLike, type UsbTransferOutResultLike, type UsbWriterLike, type UsbIdentityLike, type UsbDeviceLike, type UsbPrinterEndpoint, type UsbPrinterConnection, USB_VENDOR_EPSON, USB_CLASS_PRINTER, usbDeviceKey, usbFindPrinterEndpoint, usbWriteAll, usbConnectPrinter, usbPrint, usbDisconnect, } from './webusb.js';
+export { type UsbEndpointLike, type UsbAlternateLike, type UsbInterfaceLike, type UsbConfigurationLike, type UsbTransferOutResultLike, type UsbWriterLike, type UsbIdentityLike, type UsbDeviceLike, type UsbPrinterEndpoint, type UsbPrinterConnection, USB_VENDOR_EPSON, USB_CLASS_PRINTER, UsbTimeoutError, usbDeviceKey, usbFindPrinterEndpoint, usbWriteAll, usbConnectPrinter, usbPrint, usbDisconnect, } from './webusb.js';

package/dist/esm/printing/index.js

@@ -1,3 +1,3 @@
 export { createEscPosDocument, escPosBytes, escPosReset, escPosSetGlobalCodeTable, escPosSetGlobalFont, escPosSetStyles, escPosText, escPosEmptyLines, escPosFeed, escPosCut, escPosHr, escPosRow, escPosQrCode, encodeEscPosText, qrCodeBytes, escPosMaxCharsPerLine, escPosWortzeilen, wortzeilenText, } from './escpos.js';
 export { escPosPrintableText } from './printable.js';
-export { USB_VENDOR_EPSON, USB_CLASS_PRINTER, usbDeviceKey, usbFindPrinterEndpoint, usbWriteAll, usbConnectPrinter, usbPrint, usbDisconnect, } from './webusb.js';
+export { USB_VENDOR_EPSON, USB_CLASS_PRINTER, UsbTimeoutError, usbDeviceKey, usbFindPrinterEndpoint, usbWriteAll, usbConnectPrinter, usbPrint, usbDisconnect, } from './webusb.js';

package/dist/esm/printing/webusb.d.ts

@@ -75,15 +75,45 @@ export declare function usbDeviceKey(d: UsbIdentityLike): string;
 export declare function usbFindPrinterEndpoint(d: {
     configuration: UsbConfigurationLike | null;
 }): UsbPrinterEndpoint | null;
-/** Bytes blockweise an den OUT-Endpunkt; liefert die geschriebene Gesamtzahl, wirft bei Fehlstatus. */
-export declare function usbWriteAll(dev: UsbWriterLike, endpointNumber: number, bytes: Uint8Array, blockSize?: number): Promise<number>;
+/**
+ * Ein USB-Schritt kam nicht innerhalb der Frist zurueck. Anders als bei einem
+ * HTTP-Aufruf (siehe `receipt/epos.ts`, `EposConnectionError`) kennt WebUSB
+ * fuer diese Methoden kein Abbruchsignal -- der zugrunde liegende Transfer
+ * kann am Geraet WEITERLAUFEN, auch nachdem dieser Fehler geworfen wurde. Was
+ * hier begrenzt wird, ist NUR das Warten dieses Aufrufers, nicht der Transfer
+ * selbst. Dieselbe ehrliche Einschraenkung wie beim Dart-Zwilling
+ * `HpsPayments` (`_abortBudget`-Kommentar): ein weicher Zeitablauf ist besser
+ * als gar keiner, aber kein echtes Abbrechen.
+ */
+export declare class UsbTimeoutError extends Error {
+    readonly name = "UsbTimeoutError";
+    readonly schritt: string;
+    readonly timeoutMs: number;
+    constructor(schritt: string, timeoutMs: number);
+}
+/**
+ * Bytes blockweise an den OUT-Endpunkt; liefert die geschriebene Gesamtzahl,
+ * wirft bei Fehlstatus. [timeoutMs] gilt JE Block, nicht fuer den gesamten
+ * Druckauftrag -- ein grosser Beleg darf laenger brauchen, ein EINZELNER
+ * haengender Block soll trotzdem auffallen, statt den ganzen Aufruf
+ * unbegrenzt festzuhalten (genau das Muster, das im Flutter-Paket einen
+ * Verkauf angehalten hat).
+ */
+export declare function usbWriteAll(dev: UsbWriterLike, endpointNumber: number, bytes: Uint8Array, blockSize?: number, timeoutMs?: number): Promise<number>;
 /**
  * Geraet oeffnen, Konfiguration waehlen, Druckerschnittstelle belegen. Wirft
  * verstaendlich, wenn ein Treiber das Geraet haelt oder kein Drucker-Endpunkt
- * da ist -- und schliesst das Geraet dann wieder.
+ * da ist -- und schliesst das Geraet dann wieder. Jeder Schritt steht unter
+ * [timeoutMs] (siehe [UsbTimeoutError]).
  */
-export declare function usbConnectPrinter(device: UsbDeviceLike): Promise<UsbPrinterConnection>;
+export declare function usbConnectPrinter(device: UsbDeviceLike, timeoutMs?: number): Promise<UsbPrinterConnection>;
 /** Bytes an eine bestehende Verbindung. */
-export declare function usbPrint(c: UsbPrinterConnection, bytes: Uint8Array): Promise<number>;
-/** Schnittstelle freigeben und schliessen; Fehler dabei sind egal (Geraet ist ohnehin weg). */
-export declare function usbDisconnect(c: UsbPrinterConnection): Promise<void>;
+export declare function usbPrint(c: UsbPrinterConnection, bytes: Uint8Array, timeoutMs?: number): Promise<number>;
+/**
+ * Schnittstelle freigeben und schliessen; Fehler dabei sind egal (Geraet ist
+ * ohnehin weg) -- ABER ein haengender Aufruf ist etwas anderes als ein Fehler:
+ * ein `catch` faengt nur eine ABLEHNUNG ab, nicht ein Versprechen, das nie
+ * aufloest. Ohne die Frist haette ein steckengebliebenes `releaseInterface`
+ * `usbDisconnect` selbst unbegrenzt haengen lassen, trotz des `try/catch`.
+ */
+export declare function usbDisconnect(c: UsbPrinterConnection, timeoutMs?: number): Promise<void>;

package/dist/esm/printing/webusb.js

@@ -35,15 +35,57 @@ export function usbFindPrinterEndpoint(d) {
     kandidaten.sort((a, b) => a.rang - b.rang);
     return kandidaten[0]?.e ?? null;
 }
-/** Bytes blockweise an den OUT-Endpunkt; liefert die geschriebene Gesamtzahl, wirft bei Fehlstatus. */
-export async function usbWriteAll(dev, endpointNumber, bytes, blockSize = 16384) {
+/**
+ * Ein USB-Schritt kam nicht innerhalb der Frist zurueck. Anders als bei einem
+ * HTTP-Aufruf (siehe `receipt/epos.ts`, `EposConnectionError`) kennt WebUSB
+ * fuer diese Methoden kein Abbruchsignal -- der zugrunde liegende Transfer
+ * kann am Geraet WEITERLAUFEN, auch nachdem dieser Fehler geworfen wurde. Was
+ * hier begrenzt wird, ist NUR das Warten dieses Aufrufers, nicht der Transfer
+ * selbst. Dieselbe ehrliche Einschraenkung wie beim Dart-Zwilling
+ * `HpsPayments` (`_abortBudget`-Kommentar): ein weicher Zeitablauf ist besser
+ * als gar keiner, aber kein echtes Abbrechen.
+ */
+export class UsbTimeoutError extends Error {
+    name = 'UsbTimeoutError';
+    schritt;
+    timeoutMs;
+    constructor(schritt, timeoutMs) {
+        super(`USB-Drucker antwortet nicht (${schritt}, Zeitlimit ${timeoutMs} ms überschritten) — Kabel/Gerät prüfen.`);
+        this.schritt = schritt;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** Vorgabe-Zeitlimit je USB-Schritt. Ein einzelner Block/Schritt braucht Millisekunden; alles darueber ist ein haengendes Geraet. */
+const USB_ZEITLIMIT_VORGABE_MS = 15000;
+/** Begrenzt das WARTEN auf [promise] -- siehe [UsbTimeoutError] fuer die Einschraenkung. */
+function mitZeitlimit(promise, ms, schritt) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new UsbTimeoutError(schritt, ms)), ms);
+        promise.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+/**
+ * Bytes blockweise an den OUT-Endpunkt; liefert die geschriebene Gesamtzahl,
+ * wirft bei Fehlstatus. [timeoutMs] gilt JE Block, nicht fuer den gesamten
+ * Druckauftrag -- ein grosser Beleg darf laenger brauchen, ein EINZELNER
+ * haengender Block soll trotzdem auffallen, statt den ganzen Aufruf
+ * unbegrenzt festzuhalten (genau das Muster, das im Flutter-Paket einen
+ * Verkauf angehalten hat).
+ */
+export async function usbWriteAll(dev, endpointNumber, bytes, blockSize = 16384, timeoutMs = USB_ZEITLIMIT_VORGABE_MS) {
     const groesse = Math.max(1, Math.floor(blockSize));
     let n = 0;
     for (let von = 0; von < bytes.length; von += groesse) {
         // eigener ArrayBuffer je Block (BufferSource verlangt kein SharedArrayBuffer)
         const block = new Uint8Array(Math.min(groesse, bytes.length - von));
         block.set(bytes.subarray(von, von + block.length));
-        const r = await dev.transferOut(endpointNumber, block);
+        const r = await mitZeitlimit(dev.transferOut(endpointNumber, block), timeoutMs, 'transferOut');
         if (r.status !== 'ok')
             throw new Error(`USB-Übertragung: ${r.status} nach ${n} Byte`);
         n += r.bytesWritten;
@@ -53,49 +95,64 @@ export async function usbWriteAll(dev, endpointNumber, bytes, blockSize = 16384)
 /**
  * Geraet oeffnen, Konfiguration waehlen, Druckerschnittstelle belegen. Wirft
  * verstaendlich, wenn ein Treiber das Geraet haelt oder kein Drucker-Endpunkt
- * da ist -- und schliesst das Geraet dann wieder.
+ * da ist -- und schliesst das Geraet dann wieder. Jeder Schritt steht unter
+ * [timeoutMs] (siehe [UsbTimeoutError]).
  */
-export async function usbConnectPrinter(device) {
+export async function usbConnectPrinter(device, timeoutMs = USB_ZEITLIMIT_VORGABE_MS) {
     if (!device.opened)
-        await device.open();
+        await mitZeitlimit(device.open(), timeoutMs, 'open');
     try {
         if (!device.configuration)
-            await device.selectConfiguration(1);
+            await mitZeitlimit(device.selectConfiguration(1), timeoutMs, 'selectConfiguration');
         const ep = usbFindPrinterEndpoint(device);
         if (!ep)
             throw new Error('Kein Drucker-Endpunkt am USB-Gerät gefunden — ist das ein Bondrucker?');
         try {
-            await device.claimInterface(ep.interfaceNumber);
+            await mitZeitlimit(device.claimInterface(ep.interfaceNumber), timeoutMs, 'claimInterface');
         }
         catch (e) {
+            // Ein Zeitablauf ist etwas anderes als ein abgelehnter Claim: Ersterer
+            // sagt "das Geraet antwortet gar nicht", Letzterer "ein Treiber haelt
+            // es". Beide unter derselben Meldung zu verstecken, waere dieselbe
+            // Verwechslung, die an anderer Stelle in diesem Vorhaben schon einmal
+            // Kartendaten falsch eingeordnet hat -- hier nur mit einem Drucker
+            // statt eines Terminals.
+            if (e instanceof UsbTimeoutError)
+                throw e;
             const grund = e instanceof Error && e.message ? ` (${e.message})` : '';
             throw new Error(`USB-Schnittstelle belegt${grund} — ein Treiber hält den Drucker. Windows: Epson-Treiber entfernen oder mit Zadig auf WinUSB umstellen.`);
         }
         if (ep.alternateSetting !== 0)
-            await device.selectAlternateInterface(ep.interfaceNumber, ep.alternateSetting);
+            await mitZeitlimit(device.selectAlternateInterface(ep.interfaceNumber, ep.alternateSetting), timeoutMs, 'selectAlternateInterface');
         const name = [device.manufacturerName, device.productName].filter((t) => !!t).join(' ') || 'USB-Drucker';
         return { device, name, interfaceNumber: ep.interfaceNumber, endpointNumber: ep.endpointNumber, key: usbDeviceKey(device) };
     }
     catch (e) {
         try {
-            await device.close();
+            await mitZeitlimit(device.close(), timeoutMs, 'close');
         }
-        catch { /* schon zu */ }
+        catch { /* schon zu, oder haengt ebenfalls -- egal, wir werfen ohnehin schon */ }
         throw e;
     }
 }
 /** Bytes an eine bestehende Verbindung. */
-export function usbPrint(c, bytes) {
-    return usbWriteAll(c.device, c.endpointNumber, bytes);
+export function usbPrint(c, bytes, timeoutMs = USB_ZEITLIMIT_VORGABE_MS) {
+    return usbWriteAll(c.device, c.endpointNumber, bytes, undefined, timeoutMs);
 }
-/** Schnittstelle freigeben und schliessen; Fehler dabei sind egal (Geraet ist ohnehin weg). */
-export async function usbDisconnect(c) {
+/**
+ * Schnittstelle freigeben und schliessen; Fehler dabei sind egal (Geraet ist
+ * ohnehin weg) -- ABER ein haengender Aufruf ist etwas anderes als ein Fehler:
+ * ein `catch` faengt nur eine ABLEHNUNG ab, nicht ein Versprechen, das nie
+ * aufloest. Ohne die Frist haette ein steckengebliebenes `releaseInterface`
+ * `usbDisconnect` selbst unbegrenzt haengen lassen, trotz des `try/catch`.
+ */
+export async function usbDisconnect(c, timeoutMs = USB_ZEITLIMIT_VORGABE_MS) {
     try {
-        await c.device.releaseInterface(c.interfaceNumber);
+        await mitZeitlimit(c.device.releaseInterface(c.interfaceNumber), timeoutMs, 'releaseInterface');
     }
     catch { /* egal */ }
     try {
-        await c.device.close();
+        await mitZeitlimit(c.device.close(), timeoutMs, 'close');
     }
     catch { /* egal */ }
 }

package/dist/esm/receipt/epos.d.ts

@@ -47,6 +47,24 @@ export interface EposResponse {
 export declare function eposServiceUrl(ip: string, devid?: string, timeoutMs?: number): string;
 export declare function eposSoapEnvelope(innerXml: string): string;
 export declare function eposParseResponse(text: string): EposResponse;
+/**
+ * Ob ein Aufruf an [eposDirectSend] an einem ZEITABLAUF scheiterte oder an
+ * einer sonst abgelehnten/nie zustande gekommenen Verbindung -- ein Aufrufer
+ * muss das unterscheiden koennen. Ein Zeitablauf heisst "der Drucker koennte
+ * noch antworten, spaeter nochmal versuchen"; eine Ablehnung heisst "unter
+ * dieser Adresse ist niemand" (falsche IP, Kabel raus, Zertifikat nicht
+ * akzeptiert). Vor dieser Klasse trug die eine Fehlermeldung fuer beide
+ * Faelle keine maschinenlesbare Unterscheidung -- ein Aufrufer haette sie nur
+ * am Text erraten koennen, und genau diese Art von Kopplung an einen Text hat
+ * sich an anderer Stelle in diesem Vorhaben schon als brueckig erwiesen.
+ */
+export declare class EposConnectionError extends Error {
+    readonly name = "EposConnectionError";
+    readonly ip: string;
+    /** `true`, wenn das Zeitlimit ablief, BEVOR eine Antwort da war. */
+    readonly timedOut: boolean;
+    constructor(ip: string, timedOut: boolean);
+}
 /** Beleg direkt drucken; wirft bei Netz-/Zertifikatsproblemen, sonst die Drucker-Antwort. */
 export declare function eposDirectPrint(layout: ReceiptLayout, o: EposDirectOptions, fetchFn?: typeof fetch): Promise<EposResponse>;
 /** Verbindungstest: leeres Dokument, druckt nichts, liefert den Druckerstatus. */

package/dist/esm/receipt/epos.js

@@ -61,19 +61,89 @@ export function eposParseResponse(text) {
     const attr = (n) => new RegExp(`\\b${n}="([^"]*)"`).exec(m[1] ?? '')?.[1] ?? '';
     return { success: attr('success') === 'true', code: attr('code'), status: attr('status') };
 }
+/**
+ * Ob ein Aufruf an [eposDirectSend] an einem ZEITABLAUF scheiterte oder an
+ * einer sonst abgelehnten/nie zustande gekommenen Verbindung -- ein Aufrufer
+ * muss das unterscheiden koennen. Ein Zeitablauf heisst "der Drucker koennte
+ * noch antworten, spaeter nochmal versuchen"; eine Ablehnung heisst "unter
+ * dieser Adresse ist niemand" (falsche IP, Kabel raus, Zertifikat nicht
+ * akzeptiert). Vor dieser Klasse trug die eine Fehlermeldung fuer beide
+ * Faelle keine maschinenlesbare Unterscheidung -- ein Aufrufer haette sie nur
+ * am Text erraten koennen, und genau diese Art von Kopplung an einen Text hat
+ * sich an anderer Stelle in diesem Vorhaben schon als brueckig erwiesen.
+ */
+export class EposConnectionError extends Error {
+    name = 'EposConnectionError';
+    ip;
+    /** `true`, wenn das Zeitlimit ablief, BEVOR eine Antwort da war. */
+    timedOut;
+    constructor(ip, timedOut) {
+        const grund = timedOut ? 'antwortet nicht (Zeitlimit überschritten)' : 'nicht erreichbar';
+        super(`Drucker ${grund}. Einmal https://${ip.trim()} im Browser öffnen und das Zertifikat akzeptieren, ` +
+            'Zugriff aufs lokale Netz erlauben, ePOS-Print am Drucker auf Enable.');
+        this.ip = ip;
+        this.timedOut = timedOut;
+    }
+}
+/** Lehnt ab, sobald [signal] abbricht -- die Naht fuer die Frist in [eposDirectSend]. */
+function alsAbbruchAbgelehnt(signal) {
+    return new Promise((_erfuellen, ablehnen) => {
+        if (signal.aborted) {
+            ablehnen(new Error('abgebrochen'));
+            return;
+        }
+        signal.addEventListener('abort', () => ablehnen(new Error('abgebrochen')), { once: true });
+    });
+}
 async function eposDirectSend(innerXml, o, fetchFn) {
-    const url = eposServiceUrl(o.ip, o.devid ?? EPOS_DEVID_VORGABE, o.timeoutMs ?? 10000);
+    const zeitlimitMs = o.timeoutMs ?? 10000;
+    const url = eposServiceUrl(o.ip, o.devid ?? EPOS_DEVID_VORGABE, zeitlimitMs);
+    // `zeitlimitMs` geht zweifach ein -- als `timeout=`-Parameter in der URL
+    // (ein Hinweis FUER DEN DRUCKER, wie lange ER intern auf den Kartenfluss/
+    // Druckvorgang wartet) UND als AbortController-Frist HIER (die Grenze fuer
+    // DIESEN Aufruf). Das ist keine Dopplung, sondern zwei verschiedene Dinge,
+    // die zufaellig denselben Wert teilen: ohne die zweite Haelfte begrenzt
+    // NICHTS den `fetch()`-Aufruf selbst. Ein Drucker, der die TCP-Verbindung
+    // annimmt und nie antwortet (ein reales Fehlerbild bei einem eingebetteten
+    // HTTP-Server), liesse den Aufruf dann NIE zurueckkehren und NIE werfen --
+    // genau dieses Muster hat im Flutter-Paket einen ganzen Verkauf angehalten:
+    // der Beleg stand in der Signaturkette, der Bildschirm zeigte nichts, und
+    // ein Neustart mit erneutem Kassieren erzeugte einen zweiten Umsatz.
+    const abbruch = new AbortController();
+    const wecker = setTimeout(() => abbruch.abort(), zeitlimitMs);
     let antwort;
+    let text;
     try {
-        antwort = await fetchFn(url, { method: 'POST', headers: { 'Content-Type': 'text/xml; charset=utf-8', SOAPAction: '""' }, body: eposSoapEnvelope(innerXml) });
+        try {
+            antwort = await Promise.race([
+                fetchFn(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'text/xml; charset=utf-8', SOAPAction: '""' },
+                    body: eposSoapEnvelope(innerXml),
+                    signal: abbruch.signal,
+                }),
+                alsAbbruchAbgelehnt(abbruch.signal),
+            ]);
+            // Die Frist deckt auch das Auslesen des Rumpfes, nicht nur den
+            // Antwortkopf -- ein Drucker, der den Kopf schickt und den Rumpf offen
+            // laesst, haelt den Aufruf sonst trotzdem unbegrenzt fest (dasselbe
+            // Muster wie `client/transport.ts`).
+            text = await Promise.race([antwort.text(), alsAbbruchAbgelehnt(abbruch.signal)]);
+        }
+        catch {
+            // `abbruch.signal.aborted` ist hier zuverlaessig: der EINZIGE Ausloeser
+            // fuer den Abbruch in dieser Funktion ist der `wecker` oben -- jeder
+            // andere Fehlschlag (Netz weg, Zertifikat abgelehnt, DNS) laesst das
+            // Signal unangetastet.
+            throw new EposConnectionError(o.ip, abbruch.signal.aborted);
+        }
     }
-    catch {
-        throw new Error(`Drucker nicht erreichbar. Einmal https://${o.ip.trim()} im Browser öffnen und das Zertifikat akzeptieren, ` +
-            'Zugriff aufs lokale Netz erlauben, ePOS-Print am Drucker auf Enable.');
+    finally {
+        clearTimeout(wecker);
     }
     if (!antwort.ok)
         throw new Error(`Drucker antwortet mit HTTP ${antwort.status}.`);
-    return eposParseResponse(await antwort.text());
+    return eposParseResponse(text);
 }
 /** Beleg direkt drucken; wirft bei Netz-/Zertifikatsproblemen, sonst die Drucker-Antwort. */
 export function eposDirectPrint(layout, o, fetchFn = fetch) {

package/dist/esm/receipt/index.d.ts

@@ -1,4 +1,4 @@
 export { type LayoutAlign, type LayoutColumn, type LayoutTextLine, type LayoutColumnsLine, type LayoutRuleLine, type LayoutSpaceLine, type LayoutQrLine, type LayoutLine, type ReceiptLayout, type BuildReceiptLayoutOptions, buildReceiptLayout, receiptSignatureFailed, receiptSignatureIsTest, receiptIsZero, receiptAmountsAreZero, receiptIsSmallBusinessConsistent, receiptZdaText, type Pruefangaben, AKTUELLES_REGELWERK, type LayoutBannerLine, type LayoutRegelwerk, SMALL_BUSINESS_NOTICE, formatCents, } from './layout.js';
 export { type EscPosLayoutOptions, escPosLayoutBytes } from './layout-escpos.js';
 export { type GridLine, type GridLineKind, type ReceiptGrid, type RenderReceiptGridOptions, renderReceiptGrid, gridSpaltenBreiten, gridAlsText, ZEICHEN_JE_PAPIER, } from './grid.js';
-export { type EposPrintXmlOptions, type EposDirectOptions, type EposResponse, eposPrintXml, eposXmlEscape, eposServiceUrl, eposSoapEnvelope, eposParseResponse, eposDirectPrint, eposDirectStatus } from './epos.js';
+export { type EposPrintXmlOptions, type EposDirectOptions, type EposResponse, EposConnectionError, eposPrintXml, eposXmlEscape, eposServiceUrl, eposSoapEnvelope, eposParseResponse, eposDirectPrint, eposDirectStatus } from './epos.js';

package/dist/esm/receipt/index.js

@@ -1,4 +1,4 @@
 export { buildReceiptLayout, receiptSignatureFailed, receiptSignatureIsTest, receiptIsZero, receiptAmountsAreZero, receiptIsSmallBusinessConsistent, receiptZdaText, AKTUELLES_REGELWERK, SMALL_BUSINESS_NOTICE, formatCents, } from './layout.js';
 export { escPosLayoutBytes } from './layout-escpos.js';
 export { renderReceiptGrid, gridSpaltenBreiten, gridAlsText, ZEICHEN_JE_PAPIER, } from './grid.js';
-export { eposPrintXml, eposXmlEscape, eposServiceUrl, eposSoapEnvelope, eposParseResponse, eposDirectPrint, eposDirectStatus } from './epos.js';
+export { EposConnectionError, eposPrintXml, eposXmlEscape, eposServiceUrl, eposSoapEnvelope, eposParseResponse, eposDirectPrint, eposDirectStatus } from './epos.js';

package/dist/esm/receipt/layout.js

@@ -37,6 +37,21 @@ function belegZeit(timeStamp) {
     const zwei = (n) => String(n).padStart(2, '0');
     return `${zwei(t.day)}.${zwei(t.month)}.${t.year} ${zwei(t.hour)}:${zwei(t.minute)}:${zwei(t.second)}`;
 }
+/**
+ * Datum des stornierten Originals fuer den Kopfblock: „11.08.2026, 09:02 Uhr".
+ * Ein unlesbarer Zeitstempel am BEZUG ist kein Grund, den Storno-Bon zu
+ * verweigern (der Beleg selbst ist gueltig) — dann bleibt die Zeile weg.
+ */
+function originalDatum(timeStamp) {
+    try {
+        const t = toViennaWallClock(parseServerTimeStamp(timeStamp));
+        const zwei = (n) => String(n).padStart(2, '0');
+        return `${zwei(t.day)}.${zwei(t.month)}.${t.year}, ${zwei(t.hour)}:${zwei(t.minute)} Uhr`;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Zahlungsart als Anzeigetext. Drei Faelle, und alle drei kommen vor:
  * bekannter Eintrag (Beschriftung), unbekannter Schluessel (roh — besser als
@@ -404,6 +419,10 @@ function belegartBlock(receipt) {
     if (t === 'cancellation') {
         aus.push(bannerZeile('STORNOBELEG'));
         aus.push(textZeile(receipt.cancellationOf ? `Stornobuchung zu Beleg ${receipt.cancellationOf.receiptId}` : 'Stornobuchung', 'center'));
+        // Datum des Originals, wenn der Bezug es traegt (Backend seit 2026-09-04).
+        const datum = receipt.cancellationOf?.timeStamp ? originalDatum(receipt.cancellationOf.timeStamp) : null;
+        if (datum)
+            aus.push(textZeile(`vom ${datum}`, 'center'));
         const grund = stornoGrundText(typeof receipt.cancellationReason === 'string' ? receipt.cancellationReason : undefined);
         if (grund)
             aus.push(textZeile(`Grund: ${grund}`, 'center'));

package/dist/esm/register/index.d.ts

@@ -47,5 +47,5 @@
  * daraus entstehende ID-Token und `sitzung.sessionId` ergeben zusammen
  * `registerUserAuth` — ab da laeuft alles Weitere ueber den ueblichen Weg.
  */
-export { type RegisterDeviceConnection, type RegisterDeviceCredentials, type PairRegisterDeviceOptions, type PairedRegisterDevice, type RegisterUserKind, type RegisterUserSummary, type RegisterUserPerms, REGISTER_PERMS, type RegisterScope, type RegisterUser, type RegisterUserSession, type ListRegisterUsersForDeviceOptions, type RegisterUserLoginOptions, type RegisterPinLoginOptions, type RegisterPinPolicy, type RegisterLoginMode, type RegisterDeviceUsers, type RegisterClientInfo, type RegisterGeo, type RegisterGeraeteAngaben, pairRegisterDevice, listRegisterUsersForDevice, unpairRegisterDevice, registerUserLogin, registerPinLogin, } from './pairing.js';
+export { type RegisterDeviceConnection, type RegisterDeviceCredentials, type PairRegisterDeviceOptions, type PairedRegisterDevice, type RegisterUserKind, type RegisterUserSummary, type RegisterUserPerms, REGISTER_PERMS, type RegisterScope, type RegisterUser, type RegisterUserSession, type ListRegisterUsersForDeviceOptions, type RegisterUserLoginOptions, type RegisterPinLoginOptions, type RegisterPinPolicy, type RegisterLoginMode, type RegisterDeviceUsers, type RegisterClientInfo, type RegisterGeo, type RegisterGeraeteAngaben, type RegisterSession, type RegisterSessionsStand, type ListRegisterSessionsForDeviceOptions, pairRegisterDevice, listRegisterUsersForDevice, listRegisterSessionsForDevice, unpairRegisterDevice, registerUserLogin, registerPinLogin, } from './pairing.js';
 export { renewRegisterSession, endRegisterSession } from './session.js';

package/dist/esm/register/index.js

@@ -47,5 +47,5 @@
  * daraus entstehende ID-Token und `sitzung.sessionId` ergeben zusammen
  * `registerUserAuth` — ab da laeuft alles Weitere ueber den ueblichen Weg.
  */
-export { REGISTER_PERMS, pairRegisterDevice, listRegisterUsersForDevice, unpairRegisterDevice, registerUserLogin, registerPinLogin, } from './pairing.js';
+export { REGISTER_PERMS, pairRegisterDevice, listRegisterUsersForDevice, listRegisterSessionsForDevice, unpairRegisterDevice, registerUserLogin, registerPinLogin, } from './pairing.js';
 export { renewRegisterSession, endRegisterSession } from './session.js';

package/dist/esm/register/pairing.d.ts

@@ -27,6 +27,14 @@ export interface RegisterClientInfo {
         w: number;
         h: number;
     };
+    /**
+     * Welcher Build der Anwendung gerade laeuft (frei, z. B. "0.6.46+3120").
+     * Bei einer Stoerungsmeldung die entscheidende Angabe: ohne sie laesst sich
+     * ein alter Build im Browser-Cache weder belegen noch ausschliessen -- und
+     * genau der steckt oft hinter "bei mir geht es aber". Das Backend kuerzt auf
+     * 80 Zeichen (register-geraetedaten.js, clientAusParams).
+     */
+    app?: string;
 }
 /** Standort aus der Browser-Ortung (freiwillig); Grundlage der Standortsperre. */
 export interface RegisterGeo {
@@ -214,6 +222,15 @@ export interface RegisterUserLoginOptions extends RegisterDeviceConnection, Regi
      * es bei der Abweisung "Kasse wird gerade auf … verwendet".
      */
     takeover?: boolean;
+    /**
+     * Welche Sitzung soll weichen? Kennung aus [listRegisterSessionsForDevice].
+     * Ohne Angabe verdraengt das Backend die aelteste -- so wie bisher.
+     *
+     * Eine Kennung, die nicht mehr laeuft, wird ABGEWIESEN statt still durch die
+     * aelteste ersetzt: Wer waehlt, bekommt seine Wahl oder eine Fehlermeldung,
+     * nie einen Unbeteiligten.
+     */
+    takeoverSessionId?: string;
 }
 export interface RegisterPinLoginOptions extends RegisterDeviceConnection, RegisterDeviceCredentials, RegisterGeraeteAngaben {
     /**
@@ -227,6 +244,8 @@ export interface RegisterPinLoginOptions extends RegisterDeviceConnection, Regis
     cashregisterId: string;
     /** Wie [RegisterUserLoginOptions.takeover]. */
     takeover?: boolean;
+    /** Wie [RegisterUserLoginOptions.takeoverSessionId]. */
+    takeoverSessionId?: string;
 }
 /**
  * Geraet koppeln: der Kopplungs-Code wird gegen den dauerhaften Ausweis dieses
@@ -252,6 +271,46 @@ export declare function pairRegisterDevice(options: PairRegisterDeviceOptions):
  * Geraet meldet Erfolg. Danach das Geraet lokal vergessen.
  */
 export declare function unpairRegisterDevice(options: ListRegisterUsersForDeviceOptions): Promise<void>;
+/** Eine laufende Sitzung an einer Kasse -- Zeile in der Auswahl. */
+export interface RegisterSession {
+    id: string;
+    deviceId: string | null;
+    /** Name des Geraets; „Kasse", wenn keiner gesetzt wurde. */
+    deviceLabel: string;
+    startedAt: number | null;
+    expiresAt: number | null;
+    /** Laeuft diese Sitzung auf DIESEM Geraet? */
+    selbst: boolean;
+    /**
+     * Wer angemeldet ist. Fehlt an einem nur-PIN-Geraet: Dort zeigt schon die
+     * Benutzerliste keine Namen, und was dort nicht steht, darf hier nicht
+     * durch die Hintertuer kommen. `undefined` heisst „wird nicht genannt",
+     * nicht „hat keinen Namen".
+     */
+    userName?: string;
+}
+/** Was eine Kasse gerade haelt -- Lizenzzahl und laufende Sitzungen. */
+export interface RegisterSessionsStand {
+    /** Wie viele Sitzungen gleichzeitig laufen duerfen. */
+    licenses: number;
+    /** Aelteste zuerst: oben steht, was das Backend ohne Wahl verdraengen wuerde. */
+    sessions: RegisterSession[];
+}
+export interface ListRegisterSessionsForDeviceOptions extends RegisterDeviceConnection, RegisterDeviceCredentials {
+}
+/**
+ * Welche Sitzungen haelt diese Kasse gerade?
+ *
+ * Fuer den Anmeldebildschirm: Sind alle Lizenzplaetze belegt, muss eine
+ * weichen -- und der Kassier soll sehen, WELCHE, statt dass das Backend still
+ * die aelteste nimmt. Die Wahl geht dann als
+ * [RegisterUserLoginOptions.takeoverSessionId] mit.
+ *
+ * Ausgewiesen wird sich ueber das Geraete-Geheimnis, wie bei
+ * [listRegisterUsersForDevice]: An diesem Punkt gibt es weder Sitzung noch
+ * Token. Die Kasse bestimmt das Backend aus dem Geraet, nicht aus dem Aufruf.
+ */
+export declare function listRegisterSessionsForDevice(options: ListRegisterSessionsForDeviceOptions): Promise<RegisterSessionsStand>;
 export declare function listRegisterUsersForDevice(options: ListRegisterUsersForDeviceOptions): Promise<RegisterDeviceUsers>;
 /**
  * Kassen-Benutzer per PIN anmelden. **Ohne Anmeldung** — dieser Aufruf