@kreiseck/kasseneck-api 0.9.3 → 0.10.0

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;