@kreiseck/kasseneck-api 0.9.4 → 0.11.0

package/dist/esm/payments/hobex-hps/payments.js

@@ -1,6 +1,6 @@
 import { HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, HpsPreflightError, } from './errors.js';
 import { newHpsTransactionId } from './transaction-id.js';
-import { isApproved, isCanceled, isConclusive, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, NOT_ABORTABLE_CODE, TECHNICAL_ERROR_CODE, TRANSACTION_CANCELED_CODE, } from './transaction-response.js';
+import { hpsCodeInfo, hpsCodeReason, isApproved, isCanceled, isConclusive, isConclusiveAsStatus, isHostUncertain, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, NOT_ABORTABLE_CODE, NOT_FOUND_CODE, TECHNICAL_ERROR_CODE, TRANSACTION_CANCELED_CODE, } from './transaction-response.js';
 /** Teiler, mit dem das Abbruchbudget aus [HpsPaymentsOptions.resolveBudgetMs] entsteht. */
 const ABORT_BUDGET_DIVISOR = 6;
 export function createHpsPayments(client, target, options = {}) {
@@ -56,7 +56,34 @@ export function createHpsPayments(client, target, options = {}) {
             return null;
         steps.push('Terminal beschaeftigt (HTTP 409) -- die Anfrage wurde nicht angenommen, es ist nichts geschehen');
         emit('resolved', steps[steps.length - 1], id);
-        return { outcome: 'declined', transactionId: id, steps: [...steps] };
+        return { outcome: 'declined', transactionId: id, reason: 'terminalBusy', steps: [...steps] };
+    }
+    /**
+     * Benennt einen Code mit `effect: 'hostUncertain'` fuer den Nachweis: was
+     * das Terminal meldet, mit Code und hobex-Titel. Die Folgerung setzt der
+     * Aufrufer dazu.
+     */
+    function stoerung(res) {
+        const info = hpsCodeInfo(res.responseCode);
+        const was = info.reason === 'internalError'
+            ? 'interner Fehler des Terminals'
+            : 'Stoerung zwischen Terminal und hobex-Host, das Terminal storniert nicht selbst';
+        return `Terminal meldet ${was} (${info.code} "${info.title}")`;
+    }
+    /**
+     * Der Grund eines offenen Ausgangs. [antwort] ist die Antwort auf die
+     * ERZEUGENDE Anfrage (oder die zuerst gemeldete Stoerung), [letzte] die
+     * zuletzt gelesene Statusabfrage. Eine Stoerung beim Host geht vor; sonst
+     * erklaert der Code der erzeugenden Anfrage mehr als ein `9027` danach.
+     */
+    function offenerGrund(antwort, letzte) {
+        if (antwort && isHostUncertain(antwort))
+            return hpsCodeReason(antwort.responseCode);
+        if (letzte && isHostUncertain(letzte))
+            return hpsCodeReason(letzte.responseCode);
+        if (antwort?.responseCode !== undefined)
+            return hpsCodeReason(antwort.responseCode);
+        return hpsCodeReason(letzte?.responseCode);
     }
     /** Verlaufseintrag fuer eine direkte Antwort, die den Ausgang NICHT festschreibt. */
     function offeneAntwort(res) {
@@ -66,6 +93,12 @@ export function createHpsPayments(client, target, options = {}) {
         if (isTechnicalError(res)) {
             return `Antwort mit technischem Fehler (${TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang, Ausgang wird geklaert`;
         }
+        if (isHostUncertain(res)) {
+            return `${stoerung(res)} -- ob belastet wurde, weiss das Terminal nicht, Ausgang wird geklaert`;
+        }
+        if (res.responseCode === NOT_FOUND_CODE) {
+            return `Terminal kennt den Vorgang nicht (${res.responseCode} "Not Found") -- keine Aussage, Ausgang wird geklaert`;
+        }
         if (isUnknownCode(res)) {
             return `Terminal nennt einen unbekannten Code (${res.responseCode})${klartext(res)} -- Ausgang wird geklaert`;
         }
@@ -79,6 +112,22 @@ export function createHpsPayments(client, target, options = {}) {
         if (isTechnicalError(status)) {
             return `Status: technischer Fehler (${TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang`;
         }
+        if (isHostUncertain(status)) {
+            return `Status: ${stoerung(status)} -- keine Aussage`;
+        }
+        // Bewusst NICHT "keine Auskunft": das Wort steht fuer das gemessene 9027,
+        // und Aufrufer lesen es als solches (sastre, OpenCardPaymentService).
+        if (status.responseCode === NOT_FOUND_CODE) {
+            return `Status: Vorgang nicht gefunden (${status.responseCode}) -- keine Aussage`;
+        }
+        const info = hpsCodeInfo(status.responseCode);
+        if (info?.rejectsRequest) {
+            return `Status: Abfrage abgewiesen (${info.code} "${info.title}") -- keine Aussage ueber den Vorgang`;
+        }
+        if (info?.conclusive && !isApproved(status)) {
+            // Nur erreichbar nach einer Stoerung beim Host, siehe [resolve].
+            return `Status: abgelehnt (${info.code} "${info.title}") -- nach der Stoerung beim hobex-Host entscheidet nur eine Genehmigung`;
+        }
         if (isUnknownCode(status)) {
             return `Status: unbekannter Code (${status.responseCode})${klartext(status)} -- keine Aussage`;
         }
@@ -95,14 +144,27 @@ export function createHpsPayments(client, target, options = {}) {
         const text = res.responseText?.trim();
         return text ? ` "${text}"` : '';
     }
-    /** Ordnet eine Terminal-Antwort ein. `null`, wenn sie nichts entscheidet. */
-    function fromResponse(res, id, steps) {
+    /**
+     * Ordnet eine Terminal-Antwort ein. `null`, wenn sie nichts entscheidet.
+     *
+     * [aufhebung]: die Antwort gehoert zu [cancel]. Ein `'0'` heisst dort
+     * "aufgehoben", und der Grund ist `'canceled'` statt `'approved'`.
+     */
+    function fromResponse(res, id, steps, aufhebung = false) {
         if (!isConclusive(res))
             return null;
         const approved = res.responseCode === '0';
-        steps.push(approved ? 'Terminal: genehmigt' : `Terminal: abgelehnt (${res.responseCode})`);
+        steps.push(approved
+            ? 'Terminal: genehmigt'
+            : `Terminal: abgelehnt (${res.responseCode} "${hpsCodeInfo(res.responseCode).title}")`);
         emit('resolved', steps[steps.length - 1], id);
-        return { outcome: approved ? 'approved' : 'declined', transactionId: id, response: res, steps: [...steps] };
+        return {
+            outcome: approved ? 'approved' : 'declined',
+            transactionId: id,
+            response: res,
+            reason: approved && aufhebung ? 'canceled' : hpsCodeReason(res.responseCode),
+            steps: [...steps],
+        };
     }
     /**
      * Ordnet die DIREKTE Antwort auf einen Aufhebungs-Request ein. Fast dasselbe
@@ -128,7 +190,7 @@ export function createHpsPayments(client, target, options = {}) {
             steps.push(`Aufhebung mit ${TRANSACTION_CANCELED_CODE} beantwortet -- mehrdeutig, der Zustand der Originalzahlung wird abgefragt`);
             return null;
         }
-        return fromResponse(res, id, steps);
+        return fromResponse(res, id, steps, true);
     }
     /**
      * Ordnet die Statusabfrage einer OFFENEN AUFHEBUNG ein. `null`, wenn sie
@@ -183,7 +245,7 @@ export function createHpsPayments(client, target, options = {}) {
         if (voided) {
             steps.push(`Terminal: Aufhebung bestaetigt (${status.responseCode ?? status.state})`);
             emit('resolved', steps[steps.length - 1], id);
-            return { outcome: 'approved', transactionId: id, response: status, steps: [...steps] };
+            return { outcome: 'approved', transactionId: id, response: status, reason: 'canceled', steps: [...steps] };
         }
         if (isApproved(status)) {
             if (firstQuery) {
@@ -199,14 +261,15 @@ export function createHpsPayments(client, target, options = {}) {
     /**
      * [letzteAntwort] ist die letzte Antwort, die das Terminal in dieser
      * Klaerung gab -- als `lastResponse` fuer Anzeige und Katalog,
-     * ausdruecklich NICHT als `response`.
+     * ausdruecklich NICHT als `response`. [grund] siehe [offenerGrund].
      */
-    function open(id, steps, letzteAntwort) {
+    function open(id, steps, letzteAntwort, grund) {
         emit('resolved', steps[steps.length - 1], id);
         return {
             outcome: 'unresolved',
             transactionId: id,
             ...(letzteAntwort ? { lastResponse: letzteAntwort } : {}),
+            ...(grund ? { reason: grund } : {}),
             steps: [...steps],
         };
     }
@@ -271,26 +334,46 @@ export function createHpsPayments(client, target, options = {}) {
         }
         steps.push('Abbruch bestaetigt -- der Vorgang war noch abbrechbar, es ist nichts belastet');
         emit('resolved', steps[steps.length - 1], id);
-        return { outcome: 'declined', transactionId: id, response: res, steps: [...steps] };
+        return { outcome: 'declined', transactionId: id, response: res, reason: 'aborted', steps: [...steps] };
     }
-    /** Klaert einen offenen Ausgang: erst abbrechen, dann abfragen -- bis das Terminal etwas sagt oder das Budget aufgebraucht ist. */
     /**
-     * `antwortMitCode` heisst: das Terminal hat auf die ERZEUGENDE Anfrage eine
-     * Antwort MIT Ergebniscode geliefert, deren Bedeutung wir nur nicht kennen.
-     * Dann ist der Vorgang am Geraet abgeschlossen -- und erst dadurch bekommt
-     * [NO_STATEMENT_CODE] (`9027`) beim Pollen einen Aussagewert, den es sonst
-     * nicht hat. Siehe [ausGeschlossenerAntwort].
+     * Klaert einen offenen Ausgang: erst abbrechen, dann abfragen -- bis das
+     * Terminal etwas sagt oder das Budget aufgebraucht ist.
+     *
+     * [antwort] ist die Antwort auf die ERZEUGENDE Anfrage, sofern eine kam.
+     * Traegt sie einen Ergebniscode, dessen Bedeutung wir nur nicht kennen, ist
+     * der Vorgang am Geraet abgeschlossen -- und erst dadurch bekommt
+     * `9027` beim Pollen einen Aussagewert, den es sonst nicht hat. Siehe
+     * [ausGeschlossenerAntwort]. Meldet sie eine Stoerung beim Host
+     * ([isHostUncertain]), bekommt `9027` diesen Aussagewert gerade NICHT --
+     * siehe Klassendoku, "Stoerung beim Host".
      */
-    async function resolve(id, steps, antwortMitCode = false, letzteAntwort) {
+    async function resolve(id, steps, antwort) {
         emit('resolving', 'Ausgang offen, Klaerung laeuft', id);
         const start = now();
         const elapsedMs = () => now() - start;
-        const aborted = await tryAbort(id, steps, elapsedMs);
-        if (aborted)
-            return aborted;
+        const antwortMitCode = antwort?.responseCode !== undefined;
+        // Einmal gemeldet, bleibt die Stoerung stehen -- auch wenn erst die
+        // Statusabfrage sie nennt und danach 9027 kommt.
+        let stoerungsAntwort = antwort && isHostUncertain(antwort) ? antwort : undefined;
+        let letzteAntwort = antwort;
+        if (stoerungsAntwort === undefined) {
+            const aborted = await tryAbort(id, steps, elapsedMs);
+            if (aborted)
+                return aborted;
+        }
+        else {
+            // Der Vorgang ist am Terminal schon beendet -- mit einer Stoerung beim
+            // Host. Ein quittierter Abbruch bewiese nur, dass am Terminal nichts mehr
+            // laeuft, nicht, dass der Host nichts belastet hat.
+            steps.push('Kein Abbruchversuch -- das Terminal hat den Vorgang mit einer Stoerung beim hobex-Host beendet');
+        }
         let wait = 0;
         let transportFailures = 0;
         let ohneAuskunft = 0;
+        // Beantwortete Statusabfragen in Folge, die zu einem Vorgang mit
+        // Host-Stoerung nichts Neues sagen.
+        let stoerungOhneNeues = 0;
         while (elapsedMs() < resolveBudgetMs) {
             if (wait > 0) {
                 const left = resolveBudgetMs - elapsedMs();
@@ -315,23 +398,45 @@ export function createHpsPayments(client, target, options = {}) {
                 wait = nextWait(wait);
                 continue;
             }
-            const settled = fromResponse(status, id, steps);
-            if (settled)
-                return settled;
+            if (isHostUncertain(status))
+                stoerungsAntwort ??= status;
+            const hostUngewiss = stoerungsAntwort !== undefined;
+            // Auf die Statusabfrage entscheidet nur ein Code, der den gesuchten
+            // Vorgang beschreibt -- nicht einer, der diese Abfrage abweist
+            // ([isConclusiveAsStatus]). Nach einer Stoerung beim Host entscheidet nur
+            // noch eine Genehmigung: jede andere Aussage des Terminals betrifft seinen
+            // Speicher, nicht den des Hosts.
+            if (hostUngewiss ? isApproved(status) : isConclusiveAsStatus(status)) {
+                const settled = fromResponse(status, id, steps);
+                if (settled)
+                    return settled;
+            }
             if (isNoStatement(status)) {
                 ohneAuskunft += 1;
-                const geklaert = ausGeschlossenerAntwort(id, steps, status, antwortMitCode, ohneAuskunft);
-                if (geklaert)
-                    return geklaert;
+                if (!hostUngewiss) {
+                    const geklaert = ausGeschlossenerAntwort(id, steps, status, antwortMitCode ? antwort : undefined, ohneAuskunft);
+                    if (geklaert)
+                        return geklaert;
+                }
             }
             else {
                 ohneAuskunft = 0;
             }
+            // Nach einer Stoerung ist jede Antwort ausser '0' (die oben schon
+            // entschieden hat) "nichts Neues".
+            stoerungOhneNeues = hostUngewiss ? stoerungOhneNeues + 1 : 0;
             steps.push(statusOhneErgebnis(status) ?? 'Status: noch kein Ergebniscode');
+            if (stoerungOhneNeues >= 2) {
+                // Siehe Klassendoku, "Stoerung beim Host": das Terminal weiss es
+                // nicht, und es wird es auch nicht wissen, wenn wir weiterfragen.
+                steps.push('Statusabfrage zweimal ohne Neues nach einer Stoerung beim hobex-Host -- '
+                    + 'das Terminal kann nicht sagen, ob belastet wurde, Ausgang bleibt offen');
+                return open(id, steps, letzteAntwort, offenerGrund(stoerungsAntwort ?? antwort, letzteAntwort));
+            }
             wait = nextWait(wait);
         }
         steps.push('Ausgang bleibt offen');
-        return open(id, steps, letzteAntwort);
+        return open(id, steps, letzteAntwort, offenerGrund(stoerungsAntwort ?? antwort, letzteAntwort));
     }
     /**
      * Liest `9027` beim Pollen als "nicht genehmigt" -- aber NUR, wenn das
@@ -356,10 +461,15 @@ export function createHpsPayments(client, target, options = {}) {
      * entstuende die Doppelbelastung vom 24.08.2026 an einer neuen Stelle.
      * Dieselbe Absicherung traegt bereits [fromCancelStatus].
      *
+     * [antwort] ist die Antwort MIT Code auf die erzeugende Anfrage -- oder
+     * `undefined`, wenn keine kam; dann greift die Regel nicht. Ihr Code ergibt
+     * den `reason`: er erklaert den Ausgang, das `9027` danach nicht. Der
+     * Aufrufer ruft diese Regel NICHT fuer eine Stoerung beim Host.
+     *
      * `undefined` heisst: nicht entschieden, weiter pollen.
      */
-    function ausGeschlossenerAntwort(id, steps, status, antwortMitCode, ohneAuskunft) {
-        if (!antwortMitCode)
+    function ausGeschlossenerAntwort(id, steps, status, antwort, ohneAuskunft) {
+        if (!antwort)
             return undefined;
         if (ohneAuskunft < 2)
             return undefined;
@@ -371,6 +481,7 @@ export function createHpsPayments(client, target, options = {}) {
             outcome: 'declined',
             transactionId: id,
             response: status,
+            reason: hpsCodeReason(antwort.responseCode),
             steps: [...steps],
         };
     }
@@ -390,11 +501,17 @@ export function createHpsPayments(client, target, options = {}) {
      *
      * Budget, Backoff und Transportfehler-Deckelung sind unveraendert aus
      * [resolve] uebernommen.
+     *
+     * [antwort] ist die direkte Antwort auf den Aufhebungs-Request, sofern eine
+     * kam. Meldete sie eine Stoerung beim Host, entscheidet ein unveraendertes
+     * `'0'` nichts -- siehe Klassendoku, "Stoerung beim Host".
      */
-    async function resolveCancel(id, steps, letzteAntwort) {
+    async function resolveCancel(id, steps, antwort) {
         emit('resolving', 'Ausgang offen, Klaerung laeuft', id);
         const start = now();
         const elapsedMs = () => now() - start;
+        const hostUngewiss = antwort !== undefined && isHostUncertain(antwort);
+        let letzteAntwort = antwort;
         let wait = 0;
         let transportFailures = 0;
         // Zaehlt nur BEANTWORTETE Statusabfragen -- Grundlage der Karenz fuer den
@@ -425,6 +542,16 @@ export function createHpsPayments(client, target, options = {}) {
                 wait = nextWait(wait);
                 continue;
             }
+            if (hostUngewiss && isApproved(status) && answeredQueries >= 2) {
+                // Siehe Klassendoku, "Stoerung beim Host": das unveraenderte '0'
+                // spiegelt nur den Speicher des Terminals. "Hat nicht gegriffen"
+                // fuehrte nach dem Tagesabschluss zu einer Rueckerstattung, die der
+                // Kunde doppelt bekaeme, falls der Host die Aufhebung doch verbucht hat.
+                steps.push('Terminal: Originalzahlung steht unveraendert (0), aber die Aufhebung endete mit einer '
+                    + 'Stoerung beim hobex-Host -- ob sie dort gewirkt hat, kann das Terminal nicht sagen, '
+                    + 'Ausgang bleibt offen');
+                return open(id, steps, letzteAntwort, offenerGrund(antwort, letzteAntwort));
+            }
             const settled = fromCancelStatus(status, id, steps, answeredQueries === 1);
             if (settled)
                 return settled;
@@ -436,7 +563,7 @@ export function createHpsPayments(client, target, options = {}) {
             wait = nextWait(wait);
         }
         steps.push('Ausgang bleibt offen');
-        return open(id, steps, letzteAntwort);
+        return open(id, steps, letzteAntwort, offenerGrund(antwort, letzteAntwort));
     }
     async function pay(paymentOptions) {
         const id = paymentOptions.transactionId ?? newHpsTransactionId();
@@ -475,7 +602,7 @@ export function createHpsPayments(client, target, options = {}) {
                 return settled;
             steps.push(offeneAntwort(res));
         }
-        return resolve(id, steps, res?.responseCode !== undefined, res);
+        return resolve(id, steps, res);
     }
     /**
      * Gutschrift mit geklaertem Ausgang -- EXAKT derselbe Klaerweg wie [pay]
@@ -519,7 +646,7 @@ export function createHpsPayments(client, target, options = {}) {
         // Dieselbe Klaerfunktion wie [pay]: die Kennung ist die des NEUEN
         // Vorgangs, eine Statusabfrage darauf liefert also genau dessen Ausgang,
         // und der Abbruch ist derselbe Diskriminator wie bei einer Zahlung.
-        return resolve(id, steps, res?.responseCode !== undefined, res);
+        return resolve(id, steps, res);
     }
     /**
      * Aufhebung (Storno/Void) einer bestehenden Zahlung mit geklaertem Ausgang.

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

@@ -5,7 +5,7 @@
  * 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
+ * Beide Seiten pinnen dieselbe Codetabelle, siehe `HPS_CODES` unten
  * und `fixtures/hobex-hps-codes.json`.
  *
  * **`responseCode !== '0'` ist NICHT die Pruefung auf eine Ablehnung.** Genau
@@ -18,7 +18,7 @@
  *
  * [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 —
+ * feststeht und in [HPS_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
@@ -26,54 +26,121 @@
  * schluessig und haette eine Zahlung, unter der tatsaechlich Geld geflossen
  * sein kann, als `declined` gemeldet.
  */
-/** Ein Ergebniscode, dessen Bedeutung GEMESSEN und hier benannt ist. */
+/** Wie ein Ergebniscode den Ausgang eines Vorgangs bestimmt. */
+export type HpsCodeEffect = 
+/** Schreibt den Ausgang fest: `'0'` genehmigt, jeder andere abgelehnt. */
+'conclusive'
+/** Gemessen oder dokumentiert, aber KEINE Aussage (9027, 9900, 100011). */
+ | 'noStatement'
+/**
+ * Der Host war beteiligt, das Terminal storniert nicht selbst -- ob belastet
+ * wurde, weiss das Terminal nicht. Weiterklaeren, aber ohne dass ein
+ * spaeteres `9027` daraus "nichts belastet" machen darf (siehe `payments.ts`).
+ */
+ | 'hostUncertain';
+/** Woher die Bedeutung eines Codes stammt. */
+export type HpsCodeSource = 
+/** Am Geraet gemessen (`doc/kartenzahlung.md` im Dart-Zwilling). */
+'measured'
+/** Aus der Antwortcodeliste von hobex (erhalten 11.09.2026). */
+ | 'documented'
+/** Beides. */
+ | 'measuredAndDocumented';
+/**
+ * Worauf eine Kasse reagiert -- der Grund hinter einem Ergebniscode. Mehrere
+ * Codes teilen sich einen Grund, wenn am Tresen dasselbe zu tun ist
+ * (`100004`, `100005`, `100012`: "Karte nicht gelesen, noch einmal"). Der Satz
+ * fuer den Bediener steht in [HPS_REASON_HINTS]; eine Kasse mit eigener
+ * Uebersetzung schluesselt ueber den Grund selbst.
+ */
+export type HpsCodeReason = 'approved' | 'aborted' | 'noCard' | 'cardReadFailed' | 'cardDeclined' | 'wrongPin' | 'amountInvalid' | 'tipNotSelected' | 'terminalBusy' | 'terminalBlocked' | 'terminalSetup' | 'terminalFault' | 'requestRejected' | 'invalidTransaction' | 'refundPassword' | 'refundDisabled' | 'hostTimeoutReversed' | 'hostFault' | 'internalError' | 'canceled' | 'notAbortable' | 'noStatement' | 'technicalError' | 'unknown';
+/** Der Satz fuer den Bediener je Grund, deutsch. */
+export declare const HPS_REASON_HINTS: Readonly<Record<HpsCodeReason, string>>;
+/**
+ * Die beiden Gruende hinter einem Code mit `effect: 'hostUncertain'`: ob Geld
+ * geflossen ist, weiss das Terminal nicht.
+ */
+export declare function isHostUncertainReason(reason: HpsCodeReason | undefined): boolean;
+/** Ein Ergebniscode, dessen Bedeutung feststeht (gemessen oder dokumentiert). */
 export interface HpsMeasuredCode {
     /** Der Ergebniscode, wie ihn das Terminal im Feld `responseCode` sendet. */
     readonly code: string;
-    /** Bedeutung, wie gemessen — deutsch, ohne Umlaute (siehe Vorbild). */
+    /** Bedeutung — 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).
+     * siehe [isConclusive]). `false`: benannt, aber KEINE Aussage ueber den
+     * Vorgang -- oder ein ungewisser Host-Ausgang, siehe [HpsCode.effect].
      */
     readonly conclusive: boolean;
 }
+/** Ein Eintrag der vollstaendigen Codetabelle [HPS_CODES]. */
+export interface HpsCode extends HpsMeasuredCode {
+    /** Titel, wie hobex ihn fuehrt bzw. das Terminal als `responseText` sendet. */
+    readonly title: string;
+    readonly effect: HpsCodeEffect;
+    readonly reason: HpsCodeReason;
+    readonly source: HpsCodeSource;
+    /**
+     * Der Code weist die ANFRAGE selbst ab (TID, Form, Geraetezustand). Auf eine
+     * Zahlung ist das deren Ablehnung; auf eine STATUSABFRAGE heisst es nur, dass
+     * diese Abfrage nicht bedient wurde -- ueber den gesuchten Vorgang sagt es
+     * nichts (gemessen fuer `100108`). Siehe [isConclusiveAsStatus].
+     */
+    readonly rejectsRequest: 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).
+ * Die vollstaendige Codetabelle — Vertrag mit dem Dart-Zwilling
+ * (`HpsCodes.all` in `lib/src/hobex_hps/response_codes.dart`), ausgegeben als
+ * `fixtures/hobex-hps-codes.json`.
+ *
+ * Zwei Quellen: GEMESSEN an hobex-HPS-Geraeten (TID 3600335, HPS 1.10.0,
+ * Firmware 7.3.6, 26.–28.08.2026; TID 3556988 im Betrieb) und die
+ * Antwortcodeliste von hobex (erhalten 11.09.2026). Die Regel bleibt: nur ein
+ * Code mit feststehender Bedeutung schreibt einen Ausgang fest -- die Liste des
+ * Herstellers ist eine solche Feststellung, kein Raten aus der Codefamilie.
+ *
+ * Eingeordnet wird danach, WO im Ablauf ein dokumentierter Code entsteht:
+ * - vor dem Host (Anfrage, Karte, EMV-Kernel, Eingaben, Geraetezustand) ->
+ *   `conclusive`, also `declined`;
+ * - `100029`, Zeitueberschreitung zum Host MIT auto-reversal -> ebenfalls
+ *   `declined`, das Terminal storniert laut hobex selbst;
+ * - beim oder nach dem Host OHNE auto-reversal, dazu der Sammelcode `100999`
+ *   -> `hostUncertain`.
  *
- * 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.
+ * Reihenfolge: zuerst die gemessenen wie im Messprotokoll, dann die
+ * dokumentierten aufsteigend -- identisch mit dem Dart-Zwilling.
+ */
+export declare const HPS_CODES: readonly HpsCode[];
+/**
+ * @deprecated Seit 0.10.0 [HPS_CODES] -- die Tabelle fuehrt nicht mehr nur
+ * gemessene Codes. Gleicher Inhalt, bleibt fuer bestehende Aufrufer.
  */
 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. */
+/** Siehe [HPS_CODES]: ungueltiger Vorgang, nichts passiert. */
 export declare const INVALID_TRANSACTION_CODE = "9002";
-/** Siehe [HPS_MEASURED_CODES]: aufgehoben. */
+/** Siehe [HPS_CODES]: aufgehoben. */
 export declare const TRANSACTION_CANCELED_CODE = "9011";
-/** Siehe [HPS_MEASURED_CODES]: keine Aussage. */
+/** Siehe [HPS_CODES]: keine Aussage. */
 export declare const NO_STATEMENT_CODE = "9027";
-/** Siehe [HPS_MEASURED_CODES]: Kennung nicht numerisch, keine Aussage. */
+/** Siehe [HPS_CODES]: Kennung nicht numerisch, keine Aussage. */
 export declare const TECHNICAL_ERROR_CODE = "9900";
-/** Siehe [HPS_MEASURED_CODES]: abgebrochen. */
+/** Siehe [HPS_CODES]: abgebrochen. */
 export declare const ABORTED_CODE = "100002";
-/** Siehe [HPS_MEASURED_CODES]: Karte nicht aufgelegt. */
+/** Siehe [HPS_CODES]: Karte nicht aufgelegt. */
 export declare const CARD_NOT_PRESENT_CODE = "100003";
-/** Siehe [HPS_MEASURED_CODES]: nicht mehr abbrechbar. */
+/** Siehe [HPS_CODES]: nicht mehr abbrechbar. */
 export declare const NOT_ABORTABLE_CODE = "100010";
-/** Siehe [HPS_MEASURED_CODES]: Betrag abgewiesen, vor dem Kartenfluss. */
+/** Siehe [HPS_CODES]: Betrag abgewiesen, vor dem Kartenfluss. */
 export declare const INVALID_AMOUNT_CODE = "9003";
-/** Siehe [HPS_MEASURED_CODES]: Betrag ausserhalb des zulaessigen Bereichs. */
+/** Siehe [HPS_CODES]: Betrag ausserhalb des zulaessigen Bereichs. */
 export declare const AMOUNT_OUT_OF_RANGE_CODE = "100019";
-/** Siehe [HPS_MEASURED_CODES]: Terminal-Kennung unbekannt. */
+/** Siehe [HPS_CODES]: Terminal-Kennung unbekannt. */
 export declare const INVALID_TID_CODE = "100108";
 /**
- * Siehe [HPS_MEASURED_CODES]: Host-Ablehnung, falsche PIN -- nichts belastet.
+ * Siehe [HPS_CODES]: Host-Ablehnung, falsche PIN -- nichts belastet.
  *
  * Zweistellig, weil ein Antwortcode des HOSTS (ISO 8583, 55 = "Incorrect
  * PIN"), kein `9xxx`-Terminalcode und kein `100xxx`-Code der HPS-Anwendung.
@@ -84,6 +151,58 @@ export declare const INVALID_TID_CODE = "100108";
  * dann nicht 9027 antwortet, sondern mit dem Code selbst.
  */
 export declare const WRONG_PIN_CODE = "55";
+/** `100001` "Bad Request" -- nichts belastet. */
+export declare const BAD_REQUEST_CODE = "100001";
+/** `100004` "Card read failed" -- nichts belastet. Im Betrieb am 28.08.2026 gesehen. */
+export declare const CARD_READ_FAILED_CODE = "100004";
+/** `100005` "App select failed" -- nichts belastet. Im Betrieb am 28.08.2026 gesehen. */
+export declare const APP_SELECT_FAILED_CODE = "100005";
+/** `100006` "Communication with TecsXml failed" (No auto-reversal) -- ungewiss. */
+export declare const HOST_COMMUNICATION_FAILED_CODE = "100006";
+/** `100007` "Processing of TecsXml step failed" (No auto-reversal) -- ungewiss. */
+export declare const HOST_STEP_FAILED_CODE = "100007";
+/** `100008` "Invalid TID" laut hobex; gemessen wurde [INVALID_TID_CODE]. */
+export declare const INVALID_TID_DOCUMENTED_CODE = "100008";
+/** `100009` "Invalid Tx Type" -- nichts belastet. */
+export declare const INVALID_TX_TYPE_CODE = "100009";
+/** `100011` "Not Found" -- keine Aussage, aber ohne die Zwei-9027-Regel. */
+export declare const NOT_FOUND_CODE = "100011";
+/** `100012` "Max retries exceeded" -- nichts belastet. */
+export declare const MAX_RETRIES_EXCEEDED_CODE = "100012";
+/** `100013` "Diagnosis failed" -- nichts belastet. */
+export declare const DIAGNOSIS_FAILED_CODE = "100013";
+/** `100014` "Card information wasn't entered" (MOTO) -- nichts belastet. */
+export declare const CARD_INFO_NOT_ENTERED_CODE = "100014";
+/** `100015` "Card declined" (EMV-Kernel) -- nichts belastet. Im Betrieb am 28. und 31.08.2026 gesehen. */
+export declare const CARD_DECLINED_CODE = "100015";
+/** `100017` "Card Not Supported" -- nichts belastet. */
+export declare const CARD_NOT_SUPPORTED_CODE = "100017";
+/** `100018` "Scep enrollment failed" -- nichts belastet. */
+export declare const SCEP_ENROLLMENT_FAILED_CODE = "100018";
+/** `100020` "Refund password is invalid" -- nichts ausgezahlt. */
+export declare const REFUND_PASSWORD_INVALID_CODE = "100020";
+/** `100021` "Failed to enter the password" -- nichts ausgezahlt. */
+export declare const PASSWORD_NOT_ENTERED_CODE = "100021";
+/** `100022` "Terminal is blocked" -- nichts belastet. */
+export declare const TERMINAL_BLOCKED_CODE = "100022";
+/** `100023` "Invalid message type" -- ungewiss. */
+export declare const INVALID_MESSAGE_TYPE_CODE = "100023";
+/** `100024` "Transaction completion has failed" -- ungewiss. */
+export declare const COMPLETION_FAILED_CODE = "100024";
+/** `100025` "Refund transactions are disabled" -- nichts ausgezahlt. */
+export declare const REFUND_DISABLED_CODE = "100025";
+/** `100026` "Transaction was declined." (Chip-Daten fuer eine Karte ohne Chip) -- ungewiss. */
+export declare const CHIP_DATA_MISMATCH_CODE = "100026";
+/** `100027` "Unsupported UserData in TecsXml Response" -- ungewiss. */
+export declare const UNSUPPORTED_USER_DATA_CODE = "100027";
+/** `100028` "Tip selection process has failed." -- nichts belastet. */
+export declare const TIP_SELECTION_FAILED_CODE = "100028";
+/** `100029` "Communication with TecsXml timeout" (auto-reversal) -- nichts belastet. */
+export declare const HOST_TIMEOUT_REVERSED_CODE = "100029";
+/** `100998` "Terminal is busy" -- nichts belastet; gemessen als HTTP [TERMINAL_BUSY_HTTP_STATUS]. */
+export declare const TERMINAL_BUSY_CODE = "100998";
+/** `100999` "Internal Error" -- Sammelcode, ungewiss. */
+export declare const INTERNAL_ERROR_CODE = "100999";
 /**
  * HTTP `409` ("Terminal is busy"): das Terminal serialisiert und weist eine
  * zweite Anfrage ab, waehrend eine erste noch laeuft. Am 27.08.2026 gemessen:
@@ -91,12 +210,19 @@ export declare const WRONG_PIN_CODE = "55";
  * Spur (die Statusabfrage auf seine Kennung liefert weiterhin
  * [NO_STATEMENT_CODE]).
  *
- * Bewusst KEIN Eintrag in [HPS_MEASURED_CODES]: es ist ein HTTP-Status, kein
+ * Bewusst KEIN Eintrag in [HPS_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;
+/** Der Eintrag zu [code] in [HPS_CODES], oder `undefined`, wenn seine Bedeutung nicht feststeht. */
+export declare function hpsCodeInfo(code: string | undefined): HpsCode | undefined;
+/**
+ * Der Grund zu [code] -- `'unknown'` fuer einen Code ausserhalb der Tabelle,
+ * `undefined` ohne Code.
+ */
+export declare function hpsCodeReason(code: string | undefined): HpsCodeReason | undefined;
 /** Antwort des Terminals — Zahlung, Statusabfrage oder Abbruch. */
 export interface HpsTransactionResponse {
     /** Kennung dieser Transaktion, wie vom Terminal bestaetigt bzw. echoed. */
@@ -148,7 +274,13 @@ export declare function isApproved(res: Pick<HpsTransactionResponse, 'responseCo
 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). */
+/**
+ * `true`, wenn das Terminal zu dieser Kennung keine Auskunft gibt (9027).
+ *
+ * Bewusst NUR `9027`, nicht auch [NOT_FOUND_CODE] (`100011`): auf `9027` ruht
+ * die Zwei-9027-Regel in `payments.ts`, und die ist fuer genau diesen Code
+ * gemessen. `100011` ist dokumentiert, aber nie gesehen.
+ */
 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;
@@ -163,13 +295,30 @@ export declare function isTechnicalError(res: Pick<HpsTransactionResponse, 'resp
 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.
+ * traegt — ein Ergebniscode, der in [HPS_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.
+ * Wie [isConclusive], aber fuer die Antwort auf eine STATUSABFRAGE: ein Code,
+ * der die Anfrage selbst abweist (`rejectsRequest`, etwa `100022` "Terminal is
+ * blocked" oder `100108` "Invalid TID"), sagt dort nichts ueber den gesuchten
+ * Vorgang. Als `declined` gelesen, hiesse ein gesperrtes Terminal "die Zahlung
+ * ist nicht belastet".
+ */
+export declare function isConclusiveAsStatus(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/**
+ * `true`, wenn der Code einen Ausgang meldet, den das Terminal selbst nicht
+ * kennt: der hobex-Host war beteiligt, und das Terminal storniert nicht von
+ * sich aus (`effect: 'hostUncertain'`). Ein spaeteres `9027` auf die
+ * Statusabfrage heisst dann NICHT "nichts belastet" -- es spiegelt nur den
+ * Speicher des Terminals, nicht den des Hosts.
+ */
+export declare function isHostUncertain(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;
+/**
+ * `true`, wenn ein Ergebniscode VORHANDEN ist, dessen Bedeutung aber nicht
+ * feststeht -- er fehlt in [HPS_CODES]. Ein Code, den dieses Modell schlicht
+ * nicht kennt; anders als [isNoStatement], [isTechnicalError] und
+ * [isHostUncertain], die eine Wissensluecke ueber den VORGANG benennen.
  */
 export declare function isUnknownCode(res: Pick<HpsTransactionResponse, 'responseCode'>): boolean;