@kreiseck/kasseneck-api 0.6.45 → 0.6.49

package/dist/cjs/payments/hobex-hps/transaction-id.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Erzeugung und Pruefung der HPS-Transaktionskennung.
+ *
+ * **Die Kennung steht VOR dem ersten Netzweg fest.** Kasseneck Connects
+ * eigene Doku sagt es woertlich: "`transactionId` MUSS die Kasse vergeben und
+ * sich merken" (`kasseneck-connect/lib/src/api/routes_terminal.dart`,
+ * `_handlePayment`). Ohne das ist ein abgerissener Vorgang unauffindbar — das
+ * ist der Kernfehler vom 24.08.2026.
+ *
+ * **Warum nicht `newHobexTransactionId` aus `../hobex.js`?** Diese Funktion
+ * erzeugt 19 Ziffern (Zeitanteil + Zufall) fuer die Hobex-CLOUD-API, die keine
+ * Laengengrenze dokumentiert. Das HPS-REST-Terminal dagegen erlaubt
+ * hoechstens **18** Ziffern (`kasseneck-connect`s eigene Pruefung,
+ * `_transactionId`-Regex in `routes_terminal.dart`, und `HpsClient`s
+ * `_maxTransactionIdLength` im Dart-Zwilling) — eine 19-stellige Kennung waere
+ * an dieser Schnittstelle bereits eine Formverletzung, VOR jeder Pruefung auf
+ * "rein numerisch". Sie taugt hier also nicht.
+ *
+ * Stattdessen **derselbe Ansatz wie `HpsClient.newTransactionId()`** im
+ * Dart-Zwilling: Millisekunden-Zeitstempel (13 Ziffern) plus ein 5-stelliger
+ * Zaehler je Millisekunde, macht genau 18 Ziffern. Der Zeitstempel beginnt
+ * bis zum Jahr 2286 nicht mit einer Null — das schliesst die Falle, vor der
+ * gewarnt wurde ("fuehrende Nullen werden am Terminal normalisiert, zwei
+ * Kennungen waeren sonst derselbe Vorgang"): zwei in dieser Millisekunde
+ * erzeugte Kennungen unterscheiden sich immer im Zaehler-Suffix, nie nur in
+ * einer fuehrenden Null.
+ */
+/** Laengengrenze der Kennung laut HPS-REST-Spezifikation (siehe oben). */
+export declare const MAX_TRANSACTION_ID_LENGTH = 18;
+/**
+ * `true`, wenn [value] als HPS-Transaktionskennung taugt: nicht leer,
+ * hoechstens [MAX_TRANSACTION_ID_LENGTH] Zeichen, rein numerisch.
+ *
+ * Bewusst KEINE Pruefung auf eine fuehrende Null bei einer selbst
+ * UEBERGEBENEN Kennung — weder Connects Formregel noch der Dart-Zwilling
+ * verlangen das von einem Aufrufer, der eine eigene Kennung mitbringt (siehe
+ * `HpsClient._checkTransactionId`). Die Falle betrifft nur die ERZEUGUNG,
+ * siehe [newHpsTransactionId].
+ */
+export declare function isValidHpsTransactionId(value: string): boolean;
+export interface HpsTransactionIdGeneratorOptions {
+    /** Uhr fuer die Kennung; Vorgabe `Date.now`. Einspeisbar fuer Tests. */
+    now?: () => number;
+}
+/**
+ * Erzeugt eine Funktion, die bei jedem Aufruf eine neue, innerhalb dieses
+ * Erzeugers eindeutige Kennung liefert.
+ *
+ * Eindeutigkeit ist eine LOGISCHE Uhr, angelehnt an das Snowflake-Verfahren:
+ * die zuletzt vergebene Millisekunde laeuft niemals rueckwaerts. Liefert die
+ * Uhr keinen groesseren Wert als beim letzten Aufruf — egal ob dieselbe
+ * Millisekunde oder eine zurueckspringende Uhr (Zeitumstellung,
+ * NTP-Korrektur) — bleibt die Millisekunde stehen und nur der Zaehler steigt.
+ * Ist der Zaehler einer Millisekunde ausgeschoepft (100000 Kennungen),
+ * schaltet die Millisekunde gedanklich um eins weiter.
+ *
+ * Die Garantie gilt nur INNERHALB des einen Erzeugers (eigener, gekapselter
+ * Zustand) — zwei getrennte Erzeuger oder Prozesse, die in derselben
+ * Millisekunde eine Kennung bilden, koennen kollidieren. Fuer den Einsatz
+ * hier passt das: eine Kasse erzeugt Kennungen aus genau einem laufenden
+ * Prozess.
+ */
+export declare function createHpsTransactionIdGenerator(options?: HpsTransactionIdGeneratorOptions): () => string;
+/** Bequeme Vorgabeinstanz fuer den Alltagsgebrauch — eigener, gekapselter Zustand. */
+export declare const newHpsTransactionId: () => string;

package/dist/cjs/payments/hobex-hps/transaction-id.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Erzeugung und Pruefung der HPS-Transaktionskennung.
+ *
+ * **Die Kennung steht VOR dem ersten Netzweg fest.** Kasseneck Connects
+ * eigene Doku sagt es woertlich: "`transactionId` MUSS die Kasse vergeben und
+ * sich merken" (`kasseneck-connect/lib/src/api/routes_terminal.dart`,
+ * `_handlePayment`). Ohne das ist ein abgerissener Vorgang unauffindbar — das
+ * ist der Kernfehler vom 24.08.2026.
+ *
+ * **Warum nicht `newHobexTransactionId` aus `../hobex.js`?** Diese Funktion
+ * erzeugt 19 Ziffern (Zeitanteil + Zufall) fuer die Hobex-CLOUD-API, die keine
+ * Laengengrenze dokumentiert. Das HPS-REST-Terminal dagegen erlaubt
+ * hoechstens **18** Ziffern (`kasseneck-connect`s eigene Pruefung,
+ * `_transactionId`-Regex in `routes_terminal.dart`, und `HpsClient`s
+ * `_maxTransactionIdLength` im Dart-Zwilling) — eine 19-stellige Kennung waere
+ * an dieser Schnittstelle bereits eine Formverletzung, VOR jeder Pruefung auf
+ * "rein numerisch". Sie taugt hier also nicht.
+ *
+ * Stattdessen **derselbe Ansatz wie `HpsClient.newTransactionId()`** im
+ * Dart-Zwilling: Millisekunden-Zeitstempel (13 Ziffern) plus ein 5-stelliger
+ * Zaehler je Millisekunde, macht genau 18 Ziffern. Der Zeitstempel beginnt
+ * bis zum Jahr 2286 nicht mit einer Null — das schliesst die Falle, vor der
+ * gewarnt wurde ("fuehrende Nullen werden am Terminal normalisiert, zwei
+ * Kennungen waeren sonst derselbe Vorgang"): zwei in dieser Millisekunde
+ * erzeugte Kennungen unterscheiden sich immer im Zaehler-Suffix, nie nur in
+ * einer fuehrenden Null.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newHpsTransactionId = exports.MAX_TRANSACTION_ID_LENGTH = void 0;
+exports.isValidHpsTransactionId = isValidHpsTransactionId;
+exports.createHpsTransactionIdGenerator = createHpsTransactionIdGenerator;
+/** Laengengrenze der Kennung laut HPS-REST-Spezifikation (siehe oben). */
+exports.MAX_TRANSACTION_ID_LENGTH = 18;
+const NUMERIC_TRANSACTION_ID = /^\d+$/;
+/**
+ * `true`, wenn [value] als HPS-Transaktionskennung taugt: nicht leer,
+ * hoechstens [MAX_TRANSACTION_ID_LENGTH] Zeichen, rein numerisch.
+ *
+ * Bewusst KEINE Pruefung auf eine fuehrende Null bei einer selbst
+ * UEBERGEBENEN Kennung — weder Connects Formregel noch der Dart-Zwilling
+ * verlangen das von einem Aufrufer, der eine eigene Kennung mitbringt (siehe
+ * `HpsClient._checkTransactionId`). Die Falle betrifft nur die ERZEUGUNG,
+ * siehe [newHpsTransactionId].
+ */
+function isValidHpsTransactionId(value) {
+    return value.length > 0 && value.length <= exports.MAX_TRANSACTION_ID_LENGTH && NUMERIC_TRANSACTION_ID.test(value);
+}
+/**
+ * Erzeugt eine Funktion, die bei jedem Aufruf eine neue, innerhalb dieses
+ * Erzeugers eindeutige Kennung liefert.
+ *
+ * Eindeutigkeit ist eine LOGISCHE Uhr, angelehnt an das Snowflake-Verfahren:
+ * die zuletzt vergebene Millisekunde laeuft niemals rueckwaerts. Liefert die
+ * Uhr keinen groesseren Wert als beim letzten Aufruf — egal ob dieselbe
+ * Millisekunde oder eine zurueckspringende Uhr (Zeitumstellung,
+ * NTP-Korrektur) — bleibt die Millisekunde stehen und nur der Zaehler steigt.
+ * Ist der Zaehler einer Millisekunde ausgeschoepft (100000 Kennungen),
+ * schaltet die Millisekunde gedanklich um eins weiter.
+ *
+ * Die Garantie gilt nur INNERHALB des einen Erzeugers (eigener, gekapselter
+ * Zustand) — zwei getrennte Erzeuger oder Prozesse, die in derselben
+ * Millisekunde eine Kennung bilden, koennen kollidieren. Fuer den Einsatz
+ * hier passt das: eine Kasse erzeugt Kennungen aus genau einem laufenden
+ * Prozess.
+ */
+function createHpsTransactionIdGenerator(options = {}) {
+    const now = options.now ?? Date.now;
+    let lastMs = null;
+    let counter = 0;
+    return function newHpsTransactionId() {
+        const current = Math.trunc(now());
+        let ms;
+        if (lastMs === null || current > lastMs) {
+            ms = current;
+            counter = 0;
+        }
+        else {
+            ms = lastMs;
+            counter += 1;
+            if (counter >= 100_000) {
+                ms += 1;
+                counter = 0;
+            }
+        }
+        lastMs = ms;
+        return `${ms}${String(counter).padStart(5, '0')}`;
+    };
+}
+/** Bequeme Vorgabeinstanz fuer den Alltagsgebrauch — eigener, gekapselter Zustand. */
+exports.newHpsTransactionId = createHpsTransactionIdGenerator();

package/dist/cjs/payments/hobex-hps/transaction-response.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Antwort des hobex-HPS-Terminals auf eine Zahlung oder eine Statusabfrage,
+ * durchgereicht von **Kasseneck Connect** (`POST /v1/terminal/payment`,
+ * `/status`, `/abort` — Feld `hps` im Erfolgsrumpf). Connect ordnet nichts
+ * ein, es reicht den Terminal-Rumpf roh durch — die Einordnung passiert hier.
+ *
+ * **Zwilling:** `kasseneck_api/lib/src/hobex_hps/transaction_response.dart`.
+ * Beide Seiten pinnen dieselbe Codetabelle, siehe `HPS_MEASURED_CODES` unten
+ * und `fixtures/hobex-hps-codes.json`.
+ *
+ * **`responseCode !== '0'` ist NICHT die Pruefung auf eine Ablehnung.** Genau
+ * diese Lesart hat am 24.08.2026 zur doppelten Belastung gefuehrt:
+ * [NO_STATEMENT_CODE] (`9027`) ist ein Code ungleich `'0'` und sagt trotzdem
+ * nichts aus — er steht am gemessenen Terminal gleichermassen fuer "laeuft
+ * gerade", "abgebrochen" und "nie gesehen". Wer ihn als Ablehnung liest,
+ * meldet fuer einen LAUFENDEN Vorgang "nichts belastet, Wiederholung
+ * gefahrlos".
+ *
+ * [isConclusive] ist die einzige Stelle, an der ein Code zu einem Ausgang
+ * wird — und sie ist eine ECHTE Positivliste: nur ein Code, dessen Bedeutung
+ * GEMESSEN und in [HPS_MEASURED_CODES] benannt ist, zaehlt. Jeder andere —
+ * auch ein neuer, heute noch unbekannter Code — ist eine Wissensluecke, siehe
+ * [isUnknownCode]. Am 27.08.2026 hat der Dart-Zwilling gemessen, warum die
+ * Gegenrichtung ("jeder Code ausser 9027 ist schluessig") gefaehrlich ist: ein
+ * bis dahin unbenannter Code ([TECHNICAL_ERROR_CODE], `9900`) war darueber
+ * schluessig und haette eine Zahlung, unter der tatsaechlich Geld geflossen
+ * sein kann, als `declined` gemeldet.
+ */
+/** Ein Ergebniscode, dessen Bedeutung GEMESSEN und hier benannt ist. */
+export interface HpsMeasuredCode {
+    /** Der Ergebniscode, wie ihn das Terminal im Feld `responseCode` sendet. */
+    readonly code: string;
+    /** Bedeutung, wie gemessen — deutsch, ohne Umlaute (siehe Vorbild). */
+    readonly meaning: string;
+    /**
+     * `true`: der Code schreibt einen Ausgang fest (Teil der Positivliste,
+     * siehe [isConclusive]). `false`: gemessen und benannt, aber ausdruecklich
+     * KEINE Aussage ueber den Vorgang (9027, 9900).
+     */
+    readonly conclusive: boolean;
+}
+/**
+ * Die gemessene Codetabelle — Vertrag mit dem Dart-Zwilling, siehe
+ * `fixtures/hobex-hps-codes.json`. Gemessen an einem hobex-HPS (TID 3600335,
+ * HPS 1.10.0, Firmware 7.3.6, 26.–28.08.2026).
+ *
+ * Reihenfolge ist die im Messprotokoll (`doc/kartenzahlung.md` im
+ * Dart-Zwilling) — numerisch aufsteigend zu sortieren wuerde beim Diff
+ * gegen die Vertragsdatei nichts gewinnen und macht Aenderungen schwerer
+ * nachzuverfolgen.
+ */
+export declare const HPS_MEASURED_CODES: readonly HpsMeasuredCode[];
+/** `responseCode` einer genehmigten Zahlung. */
+export declare const APPROVED_CODE = "0";
+/** Siehe [HPS_MEASURED_CODES]: ungueltiger Vorgang, nichts passiert. */
+export declare const INVALID_TRANSACTION_CODE = "9002";
+/** Siehe [HPS_MEASURED_CODES]: aufgehoben. */
+export declare const TRANSACTION_CANCELED_CODE = "9011";
+/** Siehe [HPS_MEASURED_CODES]: keine Aussage. */
+export declare const NO_STATEMENT_CODE = "9027";
+/** Siehe [HPS_MEASURED_CODES]: Kennung nicht numerisch, keine Aussage. */
+export declare const TECHNICAL_ERROR_CODE = "9900";
+/** Siehe [HPS_MEASURED_CODES]: abgebrochen. */
+export declare const ABORTED_CODE = "100002";
+/** Siehe [HPS_MEASURED_CODES]: Karte nicht aufgelegt. */
+export declare const CARD_NOT_PRESENT_CODE = "100003";
+/** Siehe [HPS_MEASURED_CODES]: nicht mehr abbrechbar. */
+export declare const NOT_ABORTABLE_CODE = "100010";
+/** Siehe [HPS_MEASURED_CODES]: Betrag abgewiesen, vor dem Kartenfluss. */
+export declare const INVALID_AMOUNT_CODE = "9003";
+/** Siehe [HPS_MEASURED_CODES]: Betrag ausserhalb des zulaessigen Bereichs. */
+export declare const AMOUNT_OUT_OF_RANGE_CODE = "100019";
+/** Siehe [HPS_MEASURED_CODES]: Terminal-Kennung unbekannt. */
+export declare const INVALID_TID_CODE = "100108";
+/**
+ * HTTP `409` ("Terminal is busy"): das Terminal serialisiert und weist eine
+ * zweite Anfrage ab, waehrend eine erste noch laeuft. Am 27.08.2026 gemessen:
+ * kommt nach 87 Millisekunden, der abgewiesene Vorgang hinterlaesst KEINE
+ * Spur (die Statusabfrage auf seine Kennung liefert weiterhin
+ * [NO_STATEMENT_CODE]).
+ *
+ * Bewusst KEIN Eintrag in [HPS_MEASURED_CODES]: es ist ein HTTP-Status, kein
+ * `responseCode` — er entsteht, bevor ueberhaupt ein Antwortrumpf gelesen
+ * wird. Siehe `errors.ts` (`HpsConnectTerminalError.isTerminalBusy`) fuer die
+ * getrennte Auswertung.
+ */
+export declare const TERMINAL_BUSY_HTTP_STATUS = 409;
+/** Antwort des Terminals — Zahlung, Statusabfrage oder Abbruch. */
+export interface HpsTransactionResponse {
+    /** Kennung dieser Transaktion, wie vom Terminal bestaetigt bzw. echoed. */
+    readonly transactionId: string | undefined;
+    /** Kennung der Original-Transaktion (Gutschrift, Aufhebung). */
+    readonly originalTransactionId: string | undefined;
+    readonly tid: string | undefined;
+    readonly receipt: string | undefined;
+    readonly approvalCode: string | undefined;
+    readonly reference: string | undefined;
+    readonly transactionDate: string | undefined;
+    readonly cardNumber: string | undefined;
+    readonly cardExpiry: string | undefined;
+    readonly brand: string | undefined;
+    readonly cardIssuer: string | undefined;
+    readonly transactionType: string | undefined;
+    readonly currency: string | undefined;
+    readonly amount: number | undefined;
+    readonly tip: number | undefined;
+    /**
+     * Ergebniscode. `undefined` (nur bei einer Statusabfrage moeglich) heisst
+     * "laeuft noch" — siehe [isInProgress]. Auf dieser Firmware ungemessen,
+     * bleibt aber ebenso eine Nicht-Aussage wie [NO_STATEMENT_CODE].
+     *
+     * Ein leerer String aus dem Rumpf wird beim Einlesen zu `undefined`
+     * normalisiert (siehe [parseHpsTransactionResponse]): er traegt keine
+     * Aussage, und `!== '0'` wuerde ihn sonst faelschlich als Ablehnung lesen.
+     */
+    readonly responseCode: string | undefined;
+    readonly responseText: string | undefined;
+    /** Nur Statusabfrage (v2). Auf der gemessenen Firmware durchgehend `undefined`. */
+    readonly state: string | undefined;
+    /** Der roh decodierte Rumpf, fuer Felder ohne eigenes Modell. */
+    readonly raw: Record<string, unknown>;
+}
+/**
+ * Liest eine Terminal-Antwort aus dem `hps`-Feld der Connect-Huelle.
+ *
+ * Wirft, wenn [raw] keine brauchbare Form hat (kein Objekt) — das ist ein
+ * Formfehler der Antwort, kein Ausgang der Zahlung, und wird vom Aufrufer
+ * (`payments.ts`) genauso behandelt wie jeder andere unerwartete Fehler: die
+ * Klaerung laeuft konservativ weiter, statt ihn stillschweigend als
+ * "laeuft noch" zu deuten.
+ */
+export declare function parseHpsTransactionResponse(raw: unknown): HpsTransactionResponse;
+/** `true`, wenn der Vorgang genehmigt ist. */
+export declare function isApproved(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/** `true`, wenn eine Statusabfrage meldet, der Vorgang laeuft noch (kein Code). */
+export declare function isInProgress(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/** `true`, wenn ein Abbruch daran scheiterte, dass der Vorgang nicht mehr abbrechbar war. */
+export declare function isNotAbortable(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/** `true`, wenn das Terminal zu dieser Kennung keine Auskunft gibt (9027). */
+export declare function isNoStatement(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/** `true`, wenn das Terminal einen technischen Fehler meldet (9900). */
+export declare function isTechnicalError(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/**
+ * `true`, wenn der Vorgang unter dieser Kennung aufgehoben wurde (9011).
+ *
+ * Vorsicht bei der Verwendung: fuer die DIREKTE Antwort auf eine Aufhebung
+ * bedeutet dieser Code etwas anderes als bei einer Statusabfrage auf die
+ * Originalzahlung -- siehe `payments.ts`, `fromCancelResponse` vs.
+ * `fromCancelStatus`.
+ */
+export declare function isCanceled(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/**
+ * `true`, wenn diese Antwort ueberhaupt eine Aussage ueber den Ausgang
+ * traegt — ein Ergebniscode, der in [HPS_MEASURED_CODES] als `conclusive`
+ * gefuehrt wird. Die einzige Stelle, an der ein Code zu einem Ausgang wird.
+ */
+export declare function isConclusive(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/**
+ * `true`, wenn ein Ergebniscode VORHANDEN ist, aber weder schluessig noch
+ * eine der beiden gemessenen Wissensluecken ([isNoStatement],
+ * [isTechnicalError]) — ein Code, den dieses Modell schlicht nicht kennt.
+ */
+export declare function isUnknownCode(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;

package/dist/cjs/payments/hobex-hps/transaction-response.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Antwort des hobex-HPS-Terminals auf eine Zahlung oder eine Statusabfrage,
+ * durchgereicht von **Kasseneck Connect** (`POST /v1/terminal/payment`,
+ * `/status`, `/abort` — Feld `hps` im Erfolgsrumpf). Connect ordnet nichts
+ * ein, es reicht den Terminal-Rumpf roh durch — die Einordnung passiert hier.
+ *
+ * **Zwilling:** `kasseneck_api/lib/src/hobex_hps/transaction_response.dart`.
+ * Beide Seiten pinnen dieselbe Codetabelle, siehe `HPS_MEASURED_CODES` unten
+ * und `fixtures/hobex-hps-codes.json`.
+ *
+ * **`responseCode !== '0'` ist NICHT die Pruefung auf eine Ablehnung.** Genau
+ * diese Lesart hat am 24.08.2026 zur doppelten Belastung gefuehrt:
+ * [NO_STATEMENT_CODE] (`9027`) ist ein Code ungleich `'0'` und sagt trotzdem
+ * nichts aus — er steht am gemessenen Terminal gleichermassen fuer "laeuft
+ * gerade", "abgebrochen" und "nie gesehen". Wer ihn als Ablehnung liest,
+ * meldet fuer einen LAUFENDEN Vorgang "nichts belastet, Wiederholung
+ * gefahrlos".
+ *
+ * [isConclusive] ist die einzige Stelle, an der ein Code zu einem Ausgang
+ * wird — und sie ist eine ECHTE Positivliste: nur ein Code, dessen Bedeutung
+ * GEMESSEN und in [HPS_MEASURED_CODES] benannt ist, zaehlt. Jeder andere —
+ * auch ein neuer, heute noch unbekannter Code — ist eine Wissensluecke, siehe
+ * [isUnknownCode]. Am 27.08.2026 hat der Dart-Zwilling gemessen, warum die
+ * Gegenrichtung ("jeder Code ausser 9027 ist schluessig") gefaehrlich ist: ein
+ * bis dahin unbenannter Code ([TECHNICAL_ERROR_CODE], `9900`) war darueber
+ * schluessig und haette eine Zahlung, unter der tatsaechlich Geld geflossen
+ * sein kann, als `declined` gemeldet.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TERMINAL_BUSY_HTTP_STATUS = exports.INVALID_TID_CODE = exports.AMOUNT_OUT_OF_RANGE_CODE = exports.INVALID_AMOUNT_CODE = exports.NOT_ABORTABLE_CODE = exports.CARD_NOT_PRESENT_CODE = exports.ABORTED_CODE = exports.TECHNICAL_ERROR_CODE = exports.NO_STATEMENT_CODE = exports.TRANSACTION_CANCELED_CODE = exports.INVALID_TRANSACTION_CODE = exports.APPROVED_CODE = exports.HPS_MEASURED_CODES = void 0;
+exports.parseHpsTransactionResponse = parseHpsTransactionResponse;
+exports.isApproved = isApproved;
+exports.isInProgress = isInProgress;
+exports.isNotAbortable = isNotAbortable;
+exports.isNoStatement = isNoStatement;
+exports.isTechnicalError = isTechnicalError;
+exports.isCanceled = isCanceled;
+exports.isConclusive = isConclusive;
+exports.isUnknownCode = isUnknownCode;
+/**
+ * Die gemessene Codetabelle — Vertrag mit dem Dart-Zwilling, siehe
+ * `fixtures/hobex-hps-codes.json`. Gemessen an einem hobex-HPS (TID 3600335,
+ * HPS 1.10.0, Firmware 7.3.6, 26.–28.08.2026).
+ *
+ * Reihenfolge ist die im Messprotokoll (`doc/kartenzahlung.md` im
+ * Dart-Zwilling) — numerisch aufsteigend zu sortieren wuerde beim Diff
+ * gegen die Vertragsdatei nichts gewinnen und macht Aenderungen schwerer
+ * nachzuverfolgen.
+ */
+exports.HPS_MEASURED_CODES = [
+    { code: '0', meaning: 'genehmigt', conclusive: true },
+    {
+        code: '9002',
+        meaning: 'ungueltiger Vorgang -- das Terminal hat den Vorgang selbst als '
+            + 'unzulaessig verworfen, bevor irgendetwas in Bewegung kam',
+        conclusive: true,
+    },
+    {
+        code: '9011',
+        meaning: "aufgehoben (\"Transaction Canceled\") -- der Vorgang unter dieser Kennung wurde storniert",
+        conclusive: true,
+    },
+    {
+        code: '9027',
+        meaning: 'keine Aussage -- steht gleichermassen fuer "nie gesehen", '
+            + '"laeuft gerade", "Karte nicht aufgelegt" und "abgebrochen"',
+        conclusive: false,
+    },
+    {
+        code: '9900',
+        meaning: '"Technical Error Database" -- gemessen im Zusammenhang mit '
+            + 'einer nicht rein numerischen Kennung; keine Aussage ueber den Vorgang selbst',
+        conclusive: false,
+    },
+    {
+        code: '9003',
+        meaning: '"Invalid Amount" -- der Betrag wird abgewiesen, BEVOR eine Karte '
+            + 'verlangt wird (28.08.2026: 99999,99 EUR, Antwort nach 15,7 s ohne '
+            + 'Kartenaufforderung); nichts belastet',
+        conclusive: true,
+    },
+    { code: '100002', meaning: 'abgebrochen ("Aborted")', conclusive: true },
+    { code: '100003', meaning: 'Karte nicht aufgelegt ("Card not present")', conclusive: true },
+    { code: '100010', meaning: 'nicht mehr abbrechbar -- der Vorgang ist bereits abgeschlossen', conclusive: true },
+    {
+        code: '100019',
+        meaning: '"Amount is not in a valid range" -- Betrag ausserhalb des '
+            + 'zulaessigen Bereichs, gemessen mit negativem Betrag; Abweisung vor '
+            + 'dem Kartenfluss, nichts belastet',
+        conclusive: true,
+    },
+    {
+        code: '100108',
+        meaning: '"Invalid TID" -- die Terminal-Kennung gibt es an diesem Geraet '
+            + 'nicht; der Vorgang wird abgewiesen, bevor etwas geschieht',
+        conclusive: true,
+    },
+];
+/** `responseCode` einer genehmigten Zahlung. */
+exports.APPROVED_CODE = '0';
+/** Siehe [HPS_MEASURED_CODES]: ungueltiger Vorgang, nichts passiert. */
+exports.INVALID_TRANSACTION_CODE = '9002';
+/** Siehe [HPS_MEASURED_CODES]: aufgehoben. */
+exports.TRANSACTION_CANCELED_CODE = '9011';
+/** Siehe [HPS_MEASURED_CODES]: keine Aussage. */
+exports.NO_STATEMENT_CODE = '9027';
+/** Siehe [HPS_MEASURED_CODES]: Kennung nicht numerisch, keine Aussage. */
+exports.TECHNICAL_ERROR_CODE = '9900';
+/** Siehe [HPS_MEASURED_CODES]: abgebrochen. */
+exports.ABORTED_CODE = '100002';
+/** Siehe [HPS_MEASURED_CODES]: Karte nicht aufgelegt. */
+exports.CARD_NOT_PRESENT_CODE = '100003';
+/** Siehe [HPS_MEASURED_CODES]: nicht mehr abbrechbar. */
+exports.NOT_ABORTABLE_CODE = '100010';
+/** Siehe [HPS_MEASURED_CODES]: Betrag abgewiesen, vor dem Kartenfluss. */
+exports.INVALID_AMOUNT_CODE = '9003';
+/** Siehe [HPS_MEASURED_CODES]: Betrag ausserhalb des zulaessigen Bereichs. */
+exports.AMOUNT_OUT_OF_RANGE_CODE = '100019';
+/** Siehe [HPS_MEASURED_CODES]: Terminal-Kennung unbekannt. */
+exports.INVALID_TID_CODE = '100108';
+/**
+ * HTTP `409` ("Terminal is busy"): das Terminal serialisiert und weist eine
+ * zweite Anfrage ab, waehrend eine erste noch laeuft. Am 27.08.2026 gemessen:
+ * kommt nach 87 Millisekunden, der abgewiesene Vorgang hinterlaesst KEINE
+ * Spur (die Statusabfrage auf seine Kennung liefert weiterhin
+ * [NO_STATEMENT_CODE]).
+ *
+ * Bewusst KEIN Eintrag in [HPS_MEASURED_CODES]: es ist ein HTTP-Status, kein
+ * `responseCode` — er entsteht, bevor ueberhaupt ein Antwortrumpf gelesen
+ * wird. Siehe `errors.ts` (`HpsConnectTerminalError.isTerminalBusy`) fuer die
+ * getrennte Auswertung.
+ */
+exports.TERMINAL_BUSY_HTTP_STATUS = 409;
+const KNOWN_OUTCOME_CODES = new Set(exports.HPS_MEASURED_CODES.filter((c) => c.conclusive).map((c) => c.code));
+/**
+ * Liest eine Terminal-Antwort aus dem `hps`-Feld der Connect-Huelle.
+ *
+ * Wirft, wenn [raw] keine brauchbare Form hat (kein Objekt) — das ist ein
+ * Formfehler der Antwort, kein Ausgang der Zahlung, und wird vom Aufrufer
+ * (`payments.ts`) genauso behandelt wie jeder andere unerwartete Fehler: die
+ * Klaerung laeuft konservativ weiter, statt ihn stillschweigend als
+ * "laeuft noch" zu deuten.
+ */
+function parseHpsTransactionResponse(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new TypeError('Terminal-Antwort ist kein JSON-Objekt');
+    }
+    const r = raw;
+    return {
+        transactionId: asString(r['transactionId']),
+        originalTransactionId: asString(r['originalTransactionId']),
+        tid: asString(r['tid']),
+        receipt: asString(r['receipt']),
+        approvalCode: asString(r['approvalCode']),
+        reference: asString(r['reference']),
+        transactionDate: asString(r['transactionDate']),
+        cardNumber: asString(r['cardNumber']),
+        cardExpiry: asString(r['cardExpiry']),
+        brand: asString(r['brand']),
+        cardIssuer: asString(r['cardIssuer']),
+        transactionType: asString(r['transactionType']),
+        currency: asString(r['currency']),
+        amount: asNumber(r['amount']),
+        tip: asNumber(r['tip']),
+        // responseCode kommt teils als Zahl, teils als Zeichenkette — siehe
+        // Zwilling. Ein leerer String traegt keine Aussage und wird wie ein
+        // fehlendes Feld behandelt.
+        responseCode: nonEmpty(stringify(r['responseCode'])),
+        responseText: asString(r['responseText']),
+        state: asString(r['state']),
+        raw: r,
+    };
+}
+function asString(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+function asNumber(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.trim() !== '') {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+function stringify(v) {
+    if (v === null || v === undefined)
+        return undefined;
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number')
+        return String(v);
+    return undefined;
+}
+function nonEmpty(v) {
+    return v === undefined || v === '' ? undefined : v;
+}
+/** `true`, wenn der Vorgang genehmigt ist. */
+function isApproved(res) {
+    return res.responseCode === exports.APPROVED_CODE;
+}
+/** `true`, wenn eine Statusabfrage meldet, der Vorgang laeuft noch (kein Code). */
+function isInProgress(res) {
+    return res.responseCode === undefined;
+}
+/** `true`, wenn ein Abbruch daran scheiterte, dass der Vorgang nicht mehr abbrechbar war. */
+function isNotAbortable(res) {
+    return res.responseCode === exports.NOT_ABORTABLE_CODE;
+}
+/** `true`, wenn das Terminal zu dieser Kennung keine Auskunft gibt (9027). */
+function isNoStatement(res) {
+    return res.responseCode === exports.NO_STATEMENT_CODE;
+}
+/** `true`, wenn das Terminal einen technischen Fehler meldet (9900). */
+function isTechnicalError(res) {
+    return res.responseCode === exports.TECHNICAL_ERROR_CODE;
+}
+/**
+ * `true`, wenn der Vorgang unter dieser Kennung aufgehoben wurde (9011).
+ *
+ * Vorsicht bei der Verwendung: fuer die DIREKTE Antwort auf eine Aufhebung
+ * bedeutet dieser Code etwas anderes als bei einer Statusabfrage auf die
+ * Originalzahlung -- siehe `payments.ts`, `fromCancelResponse` vs.
+ * `fromCancelStatus`.
+ */
+function isCanceled(res) {
+    return res.responseCode === exports.TRANSACTION_CANCELED_CODE;
+}
+/**
+ * `true`, wenn diese Antwort ueberhaupt eine Aussage ueber den Ausgang
+ * traegt — ein Ergebniscode, der in [HPS_MEASURED_CODES] als `conclusive`
+ * gefuehrt wird. Die einzige Stelle, an der ein Code zu einem Ausgang wird.
+ */
+function isConclusive(res) {
+    return res.responseCode !== undefined && KNOWN_OUTCOME_CODES.has(res.responseCode);
+}
+/**
+ * `true`, wenn ein Ergebniscode VORHANDEN ist, aber weder schluessig noch
+ * eine der beiden gemessenen Wissensluecken ([isNoStatement],
+ * [isTechnicalError]) — ein Code, den dieses Modell schlicht nicht kennt.
+ */
+function isUnknownCode(res) {
+    return res.responseCode !== undefined && !isConclusive(res) && !isNoStatement(res) && !isTechnicalError(res);
+}

package/dist/cjs/payments/hobex.js

@@ -17,12 +17,15 @@ const money_js_1 = require("../money.js");
  * functions/payment-endpoints.js) — sie ist deshalb kein Schmuck, sondern die
  * Absicherung gegen eine doppelte Belastung.
  *
- * **Nur der Cloud-Weg ist hier drin, und das bleibt so.** Hobex **HPS** ist ein
- * physisches Terminal, mit dem die Kasse **lokal ueber TCP** spricht; **myPOS**
- * und **SumUp** sind **Android-SDKs**. Ein Browser hat weder rohe TCP-Sockets
- * noch eine Android-Laufzeit — das ist keine fehlende Umsetzung und kein
- * Buendler-Problem, sondern eine Grenze der Umgebung. Wer diese drei Wege
- * braucht, braucht die Flutter-App, nicht dieses Paket.
+ * **Nur der Cloud-Weg ist hier drin.** Hobex **HPS** ist ein physisches
+ * Terminal, mit dem eine Kasse **lokal ueber TCP** spricht — dafuer hat ein
+ * Browser weiterhin keine rohen Sockets. Anders als hier frueher vermerkt,
+ * heisst das aber NICHT mehr "unerreichbar ohne Flutter": `../hobex-hps.js`
+ * spricht mit dem Terminal ueber **Kasseneck Connect**, einen lokalen
+ * Geraete-Agenten mit gewoehnlicher HTTP-Schnittstelle. **myPOS** und
+ * **SumUp** bleiben Android-SDKs ohne Entsprechung hier. Wer am HPS-Terminal
+ * eine Gutschrift oder ein Storno braucht, braucht weiterhin die Flutter-App:
+ * Connect exponiert dafuer (noch) keinen Endpunkt.
  *
  * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** Keiner der
  * beiden Endpunkte dieser Datei setzt `allowRegisterUser`; beide laufen nur

package/dist/cjs/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';