@kreiseck/kasseneck-api 0.9.4 → 0.11.0

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

@@ -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,98 +26,217 @@
  * schluessig und haette eine Zahlung, unter der tatsaechlich Geld geflossen
  * sein kann, als `declined` gemeldet.
  */
+/** Der Satz fuer den Bediener je Grund, deutsch. */
+export const HPS_REASON_HINTS = {
+    approved: 'Vom Terminal genehmigt.',
+    aborted: 'Der Vorgang wurde abgebrochen. Es wurde kein Geld bewegt.',
+    noCard: 'Es wurde keine Karte vorgehalten. Es wurde kein Geld bewegt — '
+        + 'bitte erneut versuchen.',
+    cardReadFailed: 'Die Karte konnte nicht gelesen werden. Es wurde kein Geld bewegt — '
+        + 'bitte erneut versuchen, notfalls die Karte stecken statt auflegen.',
+    cardDeclined: 'Die Karte wurde vom Terminal abgelehnt. Es wurde kein Geld bewegt '
+        + '— bitte eine andere Karte oder Zahlungsart verwenden.',
+    wrongPin: 'Die PIN war falsch. Es wurde kein Geld bewegt — bitte erneut '
+        + 'versuchen.',
+    amountInvalid: 'Das Terminal nimmt diesen Betrag nicht an. Es wurde kein Geld '
+        + 'bewegt.',
+    tipNotSelected: 'Das Trinkgeld wurde nicht rechtzeitig gewählt. Es wurde kein Geld '
+        + 'bewegt — bitte erneut versuchen.',
+    terminalBusy: 'Das Terminal ist noch mit einem anderen Vorgang beschäftigt. Es '
+        + 'wurde kein Geld bewegt — kurz warten und erneut versuchen.',
+    terminalBlocked: 'Das Terminal ist gesperrt. Es wurde kein Geld bewegt — bitte hobex '
+        + 'kontaktieren.',
+    terminalSetup: 'Das Terminal ist nicht richtig eingerichtet. Es wurde kein Geld '
+        + 'bewegt — bitte die Terminal-ID in den Einstellungen prüfen, sonst '
+        + 'hobex kontaktieren.',
+    terminalFault: 'Das Terminal meldet eine Störung. Es wurde kein Geld bewegt — '
+        + 'bitte das Terminal neu starten und erneut versuchen.',
+    requestRejected: 'Das Terminal hat die Anfrage abgewiesen. Es wurde kein Geld bewegt '
+        + '— tritt das wieder auf, bitte den Support kontaktieren.',
+    invalidTransaction: 'Das Terminal kennt die ursprüngliche Zahlung nicht. Es wurde kein '
+        + 'Geld bewegt.',
+    refundPassword: 'Das Passwort für die Gutschrift war falsch oder wurde nicht '
+        + 'eingegeben. Es wurde nichts ausgezahlt.',
+    refundDisabled: 'Gutschriften sind an diesem Terminal abgeschaltet. Es wurde nichts '
+        + 'ausgezahlt — bitte hobex kontaktieren.',
+    hostTimeoutReversed: 'hobex hat nicht rechtzeitig geantwortet, das Terminal hat den '
+        + 'Vorgang selbst storniert. Es wird kein Geld bewegt — bitte erneut '
+        + 'versuchen.',
+    hostFault: 'Die Verbindung zwischen Terminal und hobex ist gestört. Ob die '
+        + 'Karte belastet wurde, weiß das Terminal nicht — bitte nicht erneut '
+        + 'kassieren, bevor es geklärt ist.',
+    internalError: 'Das Terminal meldet einen internen Fehler. Ob die Karte belastet '
+        + 'wurde, ist unklar — bitte nicht erneut kassieren, bevor es geklärt '
+        + 'ist.',
+    canceled: 'Die Zahlung ist aufgehoben.',
+    notAbortable: 'Der Vorgang ist bereits abgeschlossen und lässt sich nicht mehr '
+        + 'abbrechen.',
+    noStatement: 'Das Terminal hat zu diesem Vorgang keine Auskunft.',
+    technicalError: 'Das Terminal meldet einen technischen Fehler; über den Vorgang '
+        + 'sagt das nichts.',
+    unknown: 'Das Terminal nennt einen Code, dessen Bedeutung nicht bekannt ist.',
+};
 /**
- * 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 beiden Gruende hinter einem Code mit `effect: 'hostUncertain'`: ob Geld
+ * geflossen ist, weiss das Terminal nicht.
+ */
+export function isHostUncertainReason(reason) {
+    return reason === 'hostFault' || reason === 'internalError';
+}
+function code(c, title, meaning, effect, reason, source, rejectsRequest = false) {
+    return { code: c, title, meaning, conclusive: effect === 'conclusive', effect, reason, source, rejectsRequest };
+}
+/**
+ * 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 const 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,
-    },
-    {
-        code: '55',
-        meaning: '"PIN falsch" -- Host-Ablehnung wegen falscher PIN, die erste '
-            + 'gemessene Host-Ablehnung ueberhaupt (02.09.2026 im Betrieb, TID '
-            + '3556988, HPS 1.11.4, Firmware 2.3.9): die Zahlung antwortete direkt '
-            + 'damit, die Statusabfrage danach elfmal in Folge ebenso -- eine '
-            + 'Host-Ablehnung bleibt am Terminal abrufbar; nichts belastet',
-        conclusive: true,
-    },
+export const HPS_CODES = [
+    code('0', 'Authorized', 'genehmigt', 'conclusive', 'approved', 'measuredAndDocumented'),
+    code('9002', 'Invalid Transaction', 'ungueltiger Vorgang -- das Terminal hat den Vorgang selbst als '
+        + 'unzulaessig verworfen, bevor irgendetwas in Bewegung kam', 'conclusive', 'invalidTransaction', 'measured', true),
+    code('9011', 'Transaction Canceled', 'aufgehoben ("Transaction Canceled") -- der Vorgang unter dieser '
+        + 'Kennung wurde storniert', 'conclusive', 'canceled', 'measured'),
+    code('9027', 'Original Tx not found', 'keine Aussage -- steht gleichermassen fuer "nie gesehen", "laeuft '
+        + 'gerade", "Karte nicht aufgelegt" und "abgebrochen"', 'noStatement', 'noStatement', 'measured'),
+    code('9900', 'Technical Error Database', '"Technical Error Database" -- gemessen im Zusammenhang mit einer '
+        + 'nicht rein numerischen Kennung; keine Aussage ueber den Vorgang '
+        + 'selbst', 'noStatement', 'technicalError', 'measured'),
+    code('9003', 'Invalid Amount', '"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', 'amountInvalid', 'measured'),
+    code('100002', 'Aborted', 'abgebrochen ("Aborted") -- ueber die Kasse oder am Terminal; '
+        + 'nichts belastet', 'conclusive', 'aborted', 'measuredAndDocumented'),
+    code('100003', 'Card not present', 'Karte nicht aufgelegt ("Card not present") -- innerhalb der Frist '
+        + '(gemessen rund 60 s) keine Karte; nichts belastet', 'conclusive', 'noCard', 'measuredAndDocumented'),
+    code('100010', 'Unable to abort transaction', 'nicht mehr abbrechbar -- der Vorgang ist bereits abgeschlossen', 'conclusive', 'notAbortable', 'measuredAndDocumented', true),
+    code('100019', 'Amount is not in a valid range', '"Amount is not in a valid range" -- Betrag ausserhalb des '
+        + 'zulaessigen Bereichs, gemessen mit negativem Betrag; Abweisung vor '
+        + 'dem Kartenfluss, nichts belastet', 'conclusive', 'amountInvalid', 'measuredAndDocumented'),
+    code('100108', 'Invalid TID', '"Invalid TID" -- die Terminal-Kennung gibt es an diesem Geraet '
+        + 'nicht; der Vorgang wird abgewiesen, bevor etwas geschieht', 'conclusive', 'terminalSetup', 'measured', true),
+    code('55', 'PIN falsch', '"PIN falsch" -- Host-Ablehnung wegen falscher PIN, die erste '
+        + 'gemessene Host-Ablehnung ueberhaupt (02.09.2026 im Betrieb, TID '
+        + '3556988, HPS 1.11.4, Firmware 2.3.9): die Zahlung antwortete '
+        + 'direkt damit, die Statusabfrage danach elfmal in Folge ebenso -- '
+        + 'eine Host-Ablehnung bleibt am Terminal abrufbar; nichts belastet', 'conclusive', 'wrongPin', 'measured'),
+    // ---- ab hier: Antwortcodeliste von hobex, erhalten 11.09.2026 ----
+    code('100001', 'Bad Request', 'fehlerhafte Anfrage der Kasse ("Bad Request") -- Abweisung vor dem '
+        + 'Kartenfluss; nichts belastet', 'conclusive', 'requestRejected', 'documented', true),
+    code('100004', 'Card read failed', 'Karte nicht lesbar ("Card read failed") -- Fehler beim Umgang mit '
+        + 'der Karte, vor jeder Autorisierung; im Betrieb (TID 3556988, '
+        + '28.08.2026) danach dauerhaft 9027; nichts belastet', 'conclusive', 'cardReadFailed', 'documented'),
+    code('100005', 'App select failed', 'Anwendungsauswahl gescheitert ("App select failed") -- die Karte '
+        + 'bietet keine passende Anwendung, vor jeder Autorisierung; im '
+        + 'Betrieb danach dauerhaft 9027; nichts belastet', 'conclusive', 'cardReadFailed', 'documented'),
+    code('100006', 'Communication with TecsXml failed', 'keine Verbindung zum hobex-Host ("Communication with TecsXml '
+        + 'failed") -- das Terminal storniert NICHT selbst; ob beim Host '
+        + 'etwas angekommen ist, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+    code('100007', 'Processing of TecsXml step failed', 'Schritt beim hobex-Host gescheitert ("Processing of TecsXml step '
+        + 'failed") -- das Terminal storniert NICHT selbst; ob beim Host '
+        + 'belastet wurde, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+    code('100008', 'Invalid TID', 'Terminal-Kennung passt nicht ("Invalid TID") -- die TID der '
+        + 'Anfrage ist nicht die eingerichtete; Abweisung vor dem '
+        + 'Kartenfluss, nichts belastet (am Geraet gemessen wurde dafuer '
+        + '100108)', 'conclusive', 'terminalSetup', 'documented', true),
+    code('100009', 'Invalid Tx Type', 'Vorgangstyp unbekannt oder nicht moeglich ("Invalid Tx Type") -- '
+        + 'Abweisung vor dem Kartenfluss; nichts belastet', 'conclusive', 'requestRejected', 'documented', true),
+    code('100011', 'Not Found', 'nicht gefunden ("Not Found") -- das Terminal kennt den Vorgang '
+        + 'nicht; keine Aussage ueber den Vorgang, anders als 9027 aber nie '
+        + 'gemessen und deshalb ohne dessen Schlussregel', 'noStatement', 'noStatement', 'documented'),
+    code('100012', 'Max retries exceeded', 'zu viele Kartenversuche ("Max retries exceeded") -- die Karte '
+        + 'wurde mehrfach (Vorgabe 3) erfolglos vorgehalten; nichts belastet', 'conclusive', 'cardReadFailed', 'documented'),
+    code('100013', 'Diagnosis failed', 'Diagnose gescheitert ("Diagnosis failed") -- das Terminal konnte '
+        + 'die Daten des EMV-Kernels nicht lesen; kein Kartenfluss, nichts '
+        + 'belastet', 'conclusive', 'terminalFault', 'documented', true),
+    code('100014', 'Card information wasn\'t entered', 'Kartendaten nicht eingegeben ("Card information wasn\'t entered") '
+        + '-- die MOTO-Eingabe kam nicht innerhalb der Frist; nichts belastet', 'conclusive', 'noCard', 'documented'),
+    code('100015', 'Card declined', 'Karte vom EMV-Kernel abgelehnt ("Card declined") -- Ablehnung im '
+        + 'Terminal, vor jeder Autorisierung beim Host; im Betrieb danach '
+        + 'dauerhaft 9027; nichts belastet', 'conclusive', 'cardDeclined', 'documented'),
+    code('100017', 'Card Not Supported', 'Karte nicht unterstuetzt ("Card Not Supported") -- der EMV-Kernel '
+        + 'kennt die Karte nicht; nichts belastet', 'conclusive', 'cardDeclined', 'documented'),
+    code('100018', 'Scep enrollment failed', 'Zertifikatsanmeldung gescheitert ("Scep enrollment failed") -- '
+        + 'falscher Code oder keine Verbindung; das Terminal kann den Host '
+        + 'nicht ansprechen, nichts belastet', 'conclusive', 'terminalSetup', 'documented', true),
+    code('100020', 'Refund password is invalid', 'Passwort fuer die Gutschrift falsch ("Refund password is invalid") '
+        + '-- die Gutschrift wird nicht ausgefuehrt, nichts ausgezahlt', 'conclusive', 'refundPassword', 'documented'),
+    code('100021', 'Failed to enter the password', 'Passwort nicht eingegeben ("Failed to enter the password") -- '
+        + 'nicht innerhalb der Frist; nichts ausgefuehrt', 'conclusive', 'refundPassword', 'documented'),
+    code('100022', 'Terminal is blocked', 'Terminal gesperrt ("Terminal is blocked") -- das Geraet ist nicht '
+        + 'IN_OPERATION; nichts belastet', 'conclusive', 'terminalBlocked', 'documented', true),
+    code('100023', 'Invalid message type', 'ungueltige Antwort des hobex-Hosts ("Invalid message type") -- '
+        + 'Nachricht und Antwortcode in den UserData ungueltig; ob beim Host '
+        + 'belastet wurde, weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+    code('100024', 'Transaction completion has failed', 'Abschluss des Online-Vorgangs gescheitert ("Transaction completion '
+        + 'has failed") -- NACH der Anfrage beim Host; ob belastet bleibt, '
+        + 'weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+    code('100025', 'Refund transactions are disabled', 'Gutschriften abgeschaltet ("Refund transactions are disabled") -- '
+        + 'in der Geraeteeinstellung; nichts ausgezahlt', 'conclusive', 'refundDisabled', 'documented'),
+    code('100026', 'Transaction was declined.', 'Host-Antwort passt nicht zur Karte ("Transaction was declined.") '
+        + '-- Chip-Daten fuer eine Karte ohne Chip; das Terminal lehnt ab, ob '
+        + 'der Host zuvor belastet hat, ist offen', 'hostUncertain', 'hostFault', 'documented'),
+    code('100027', 'Unsupported UserData in TecsXml Response', 'unbekannte Daten in der Antwort des hobex-Hosts ("Unsupported '
+        + 'UserData in TecsXml Response") -- ob beim Host belastet wurde, '
+        + 'weiss das Terminal nicht', 'hostUncertain', 'hostFault', 'documented'),
+    code('100028', 'Tip selection process has failed.', 'Trinkgeld nicht gewaehlt ("Tip selection process has failed.") -- '
+        + 'nicht innerhalb der Frist; nichts belastet', 'conclusive', 'tipNotSelected', 'documented'),
+    code('100029', 'Communication with TecsXml timeout', 'Zeitueberschreitung zum hobex-Host ("Communication with TecsXml '
+        + 'timeout") -- das Terminal storniert den Vorgang SELBST '
+        + '(auto-reversal); nichts belastet', 'conclusive', 'hostTimeoutReversed', 'documented'),
+    code('100998', 'Terminal is busy', 'Terminal beschaeftigt ("Terminal is busy") -- ein anderer Vorgang '
+        + 'laeuft oder das Geraet ist nicht bereit; die Anfrage wurde nicht '
+        + 'angenommen, nichts belastet', 'conclusive', 'terminalBusy', 'documented', true),
+    code('100999', 'Internal Error', 'interner Fehler des Terminals ("Internal Error") -- Sammelcode '
+        + 'fuer jeden sonst nicht benannten Fehler, an jeder Stelle des '
+        + 'Ablaufs moeglich; ob belastet wurde, ist offen', 'hostUncertain', 'internalError', 'documented'),
 ];
+/**
+ * @deprecated Seit 0.10.0 [HPS_CODES] -- die Tabelle fuehrt nicht mehr nur
+ * gemessene Codes. Gleicher Inhalt, bleibt fuer bestehende Aufrufer.
+ */
+export const HPS_MEASURED_CODES = HPS_CODES;
 /** `responseCode` einer genehmigten Zahlung. */
 export const APPROVED_CODE = '0';
-/** Siehe [HPS_MEASURED_CODES]: ungueltiger Vorgang, nichts passiert. */
+/** Siehe [HPS_CODES]: ungueltiger Vorgang, nichts passiert. */
 export const INVALID_TRANSACTION_CODE = '9002';
-/** Siehe [HPS_MEASURED_CODES]: aufgehoben. */
+/** Siehe [HPS_CODES]: aufgehoben. */
 export const TRANSACTION_CANCELED_CODE = '9011';
-/** Siehe [HPS_MEASURED_CODES]: keine Aussage. */
+/** Siehe [HPS_CODES]: keine Aussage. */
 export const NO_STATEMENT_CODE = '9027';
-/** Siehe [HPS_MEASURED_CODES]: Kennung nicht numerisch, keine Aussage. */
+/** Siehe [HPS_CODES]: Kennung nicht numerisch, keine Aussage. */
 export const TECHNICAL_ERROR_CODE = '9900';
-/** Siehe [HPS_MEASURED_CODES]: abgebrochen. */
+/** Siehe [HPS_CODES]: abgebrochen. */
 export const ABORTED_CODE = '100002';
-/** Siehe [HPS_MEASURED_CODES]: Karte nicht aufgelegt. */
+/** Siehe [HPS_CODES]: Karte nicht aufgelegt. */
 export const CARD_NOT_PRESENT_CODE = '100003';
-/** Siehe [HPS_MEASURED_CODES]: nicht mehr abbrechbar. */
+/** Siehe [HPS_CODES]: nicht mehr abbrechbar. */
 export const NOT_ABORTABLE_CODE = '100010';
-/** Siehe [HPS_MEASURED_CODES]: Betrag abgewiesen, vor dem Kartenfluss. */
+/** Siehe [HPS_CODES]: Betrag abgewiesen, vor dem Kartenfluss. */
 export const INVALID_AMOUNT_CODE = '9003';
-/** Siehe [HPS_MEASURED_CODES]: Betrag ausserhalb des zulaessigen Bereichs. */
+/** Siehe [HPS_CODES]: Betrag ausserhalb des zulaessigen Bereichs. */
 export const AMOUNT_OUT_OF_RANGE_CODE = '100019';
-/** Siehe [HPS_MEASURED_CODES]: Terminal-Kennung unbekannt. */
+/** Siehe [HPS_CODES]: Terminal-Kennung unbekannt. */
 export 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.
@@ -128,6 +247,61 @@ export const INVALID_TID_CODE = '100108';
  * dann nicht 9027 antwortet, sondern mit dem Code selbst.
  */
 export const WRONG_PIN_CODE = '55';
+// ---- Antwortcodeliste von hobex, erhalten 11.09.2026 ----
+// Bedeutung, Wirkung und Grund stehen in [HPS_CODES]; hier nur die Namen,
+// gleichlautend mit dem Dart-Zwilling (`TransactionResponse.*Code`).
+/** `100001` "Bad Request" -- nichts belastet. */
+export const BAD_REQUEST_CODE = '100001';
+/** `100004` "Card read failed" -- nichts belastet. Im Betrieb am 28.08.2026 gesehen. */
+export const CARD_READ_FAILED_CODE = '100004';
+/** `100005` "App select failed" -- nichts belastet. Im Betrieb am 28.08.2026 gesehen. */
+export const APP_SELECT_FAILED_CODE = '100005';
+/** `100006` "Communication with TecsXml failed" (No auto-reversal) -- ungewiss. */
+export const HOST_COMMUNICATION_FAILED_CODE = '100006';
+/** `100007` "Processing of TecsXml step failed" (No auto-reversal) -- ungewiss. */
+export const HOST_STEP_FAILED_CODE = '100007';
+/** `100008` "Invalid TID" laut hobex; gemessen wurde [INVALID_TID_CODE]. */
+export const INVALID_TID_DOCUMENTED_CODE = '100008';
+/** `100009` "Invalid Tx Type" -- nichts belastet. */
+export const INVALID_TX_TYPE_CODE = '100009';
+/** `100011` "Not Found" -- keine Aussage, aber ohne die Zwei-9027-Regel. */
+export const NOT_FOUND_CODE = '100011';
+/** `100012` "Max retries exceeded" -- nichts belastet. */
+export const MAX_RETRIES_EXCEEDED_CODE = '100012';
+/** `100013` "Diagnosis failed" -- nichts belastet. */
+export const DIAGNOSIS_FAILED_CODE = '100013';
+/** `100014` "Card information wasn't entered" (MOTO) -- nichts belastet. */
+export const CARD_INFO_NOT_ENTERED_CODE = '100014';
+/** `100015` "Card declined" (EMV-Kernel) -- nichts belastet. Im Betrieb am 28. und 31.08.2026 gesehen. */
+export const CARD_DECLINED_CODE = '100015';
+/** `100017` "Card Not Supported" -- nichts belastet. */
+export const CARD_NOT_SUPPORTED_CODE = '100017';
+/** `100018` "Scep enrollment failed" -- nichts belastet. */
+export const SCEP_ENROLLMENT_FAILED_CODE = '100018';
+/** `100020` "Refund password is invalid" -- nichts ausgezahlt. */
+export const REFUND_PASSWORD_INVALID_CODE = '100020';
+/** `100021` "Failed to enter the password" -- nichts ausgezahlt. */
+export const PASSWORD_NOT_ENTERED_CODE = '100021';
+/** `100022` "Terminal is blocked" -- nichts belastet. */
+export const TERMINAL_BLOCKED_CODE = '100022';
+/** `100023` "Invalid message type" -- ungewiss. */
+export const INVALID_MESSAGE_TYPE_CODE = '100023';
+/** `100024` "Transaction completion has failed" -- ungewiss. */
+export const COMPLETION_FAILED_CODE = '100024';
+/** `100025` "Refund transactions are disabled" -- nichts ausgezahlt. */
+export const REFUND_DISABLED_CODE = '100025';
+/** `100026` "Transaction was declined." (Chip-Daten fuer eine Karte ohne Chip) -- ungewiss. */
+export const CHIP_DATA_MISMATCH_CODE = '100026';
+/** `100027` "Unsupported UserData in TecsXml Response" -- ungewiss. */
+export const UNSUPPORTED_USER_DATA_CODE = '100027';
+/** `100028` "Tip selection process has failed." -- nichts belastet. */
+export const TIP_SELECTION_FAILED_CODE = '100028';
+/** `100029` "Communication with TecsXml timeout" (auto-reversal) -- nichts belastet. */
+export const HOST_TIMEOUT_REVERSED_CODE = '100029';
+/** `100998` "Terminal is busy" -- nichts belastet; gemessen als HTTP [TERMINAL_BUSY_HTTP_STATUS]. */
+export const TERMINAL_BUSY_CODE = '100998';
+/** `100999` "Internal Error" -- Sammelcode, ungewiss. */
+export 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:
@@ -135,13 +309,26 @@ export 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 const TERMINAL_BUSY_HTTP_STATUS = 409;
-const KNOWN_OUTCOME_CODES = new Set(HPS_MEASURED_CODES.filter((c) => c.conclusive).map((c) => c.code));
+const CODE_BY_ID = new Map(HPS_CODES.map((c) => [c.code, c]));
+/** Der Eintrag zu [code] in [HPS_CODES], oder `undefined`, wenn seine Bedeutung nicht feststeht. */
+export function hpsCodeInfo(code) {
+    return code === undefined ? undefined : CODE_BY_ID.get(code);
+}
+/**
+ * Der Grund zu [code] -- `'unknown'` fuer einen Code ausserhalb der Tabelle,
+ * `undefined` ohne Code.
+ */
+export function hpsCodeReason(code) {
+    if (code === undefined)
+        return undefined;
+    return hpsCodeInfo(code)?.reason ?? 'unknown';
+}
 /**
  * Liest eine Terminal-Antwort aus dem `hps`-Feld der Connect-Huelle.
  *
@@ -217,7 +404,13 @@ export function isInProgress(res) {
 export function isNotAbortable(res) {
     return res.responseCode === NOT_ABORTABLE_CODE;
 }
-/** `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 function isNoStatement(res) {
     return res.responseCode === NO_STATEMENT_CODE;
 }
@@ -238,17 +431,39 @@ export function isCanceled(res) {
 }
 /**
  * `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 function isConclusive(res) {
-    return res.responseCode !== undefined && KNOWN_OUTCOME_CODES.has(res.responseCode);
+    return hpsCodeInfo(res.responseCode)?.conclusive ?? false;
+}
+/**
+ * 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 function isConclusiveAsStatus(res) {
+    const info = hpsCodeInfo(res.responseCode);
+    return info !== undefined && info.conclusive && !info.rejectsRequest;
+}
+/**
+ * `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 function isHostUncertain(res) {
+    return hpsCodeInfo(res.responseCode)?.effect === 'hostUncertain';
 }
 /**
- * `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.
+ * `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 function isUnknownCode(res) {
-    return res.responseCode !== undefined && !isConclusive(res) && !isNoStatement(res) && !isTechnicalError(res);
+    return res.responseCode !== undefined && hpsCodeInfo(res.responseCode) === undefined;
 }

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

@@ -42,4 +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';
+export { type CardPaymentOutcome, type HpsConnectClient, type HpsConnectClientOptions, type HpsConnectFetch, type HpsConnectFetchResponse, type HpsConnectPaymentOptions, type HpsConnectTarget, type HpsConnectTransactionOptions, type HpsCode, type HpsCodeEffect, type HpsCodeReason, type HpsCodeSource, 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_CODES, HPS_MEASURED_CODES, HPS_REASON_HINTS, hpsCodeInfo, hpsCodeReason, HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, INVALID_TRANSACTION_CODE, isApproved, isConclusive, isConclusiveAsStatus, isHostUncertain, isHostUncertainResult, 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

@@ -42,4 +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';
+export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, createHpsConnectClient, createHpsPayments, createHpsTransactionIdGenerator, HPS_CODES, HPS_MEASURED_CODES, HPS_REASON_HINTS, hpsCodeInfo, hpsCodeReason, HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, INVALID_TRANSACTION_CODE, isApproved, isConclusive, isConclusiveAsStatus, isHostUncertain, isHostUncertainResult, 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/escpos.d.ts

@@ -27,6 +27,7 @@
  * Nicht enthalten (bewusst): Rasterbilder/Logos, Capability-Profile einzelner
  * Druckermodelle, Kassenlade, 1D-Barcodes.
  */
+import { type QrModulGroesse } from './qr-groesse.js';
 /** Papierbreite der Bonrolle. */
 export type PosPaperSize = 'mm58' | 'mm80';
 /** Ausrichtung einer Textzeile bzw. innerhalb einer Spalte. */
@@ -43,6 +44,14 @@ export type PosTextSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 export type QrSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 /** Fehlerkorrekturstufe des QR-Codes. */
 export type QrCorrection = 'L' | 'M' | 'Q' | 'H';
+/**
+ * Fertig gerechnetes QR-Raster, quadratisch, `true` = schwarzes Modul —
+ * **ohne** Ruhezone, die setzt der Drucker-Weg selbst.
+ *
+ * Dieses Paket rastert bewusst nicht selbst (keine Bildverarbeitung, siehe
+ * Kopf dieser Datei); wer den Bildweg braucht, bringt sein eigenes Raster mit.
+ */
+export type QrMatrix = readonly (readonly boolean[])[];
 /** Textstil. Fehlende Felder gelten als Vorgabewert (nicht als "unveraendert"). */
 export interface PosStyles {
     bold?: boolean;
@@ -88,8 +97,26 @@ export interface EscPosHrOptions {
 }
 export interface EscPosQrOptions {
     align?: PosAlign;
+    /**
+     * Feste Modulgroesse in Druckpunkten. Gesetzt schaltet sie die Rechnung ab —
+     * fuer Aufrufer, die genau wissen, was ihr Geraet kann. Ohne sie entscheidet
+     * die Regel in `qr-groesse.ts`.
+     */
     size?: QrSize;
     correction?: QrCorrection;
+    /** Deckel fuer die gerechnete Modulgroesse; wirkungslos neben `size`. */
+    groesse?: QrModulGroesse;
+    /** Modell 1 des Symbols ausdruecklich waehlen — siehe `qrCodeBytes`. */
+    modell1?: boolean;
+}
+export interface EscPosQrRasterOptions {
+    align?: PosAlign;
+    /** Feste Punkte je Modul; ohne Angabe gerechnet (mindestens 1). */
+    punkteJeModul?: number;
+    /** Deckel fuer die gerechnete Groesse. */
+    groesse?: QrModulGroesse;
+    /** Ruhezone je Seite in Modulen; Vorgabe `QR_RUHEZONE_MODULE` (4). */
+    ruhezoneModule?: number;
 }
 /** Interner Stilzustand — immer vollstaendig, nie teilbefuellt. */
 interface AktuelleStile {
@@ -111,6 +138,25 @@ interface AktuelleStile {
 export interface EscPosDocument {
     readonly paperSize: PosPaperSize;
     readonly spaceBetweenRows: number;
+    /**
+     * Der Beleg ging ohne QR hinaus — `null`, solange alles in Ordnung ist.
+     * Gesetzt, wenn das Symbol auch mit der Ausnahmegroesse nicht auf das Papier
+     * passt und kein Bildweg mitgegeben wurde. Auf einer oesterreichischen Kassa
+     * ist der QR die maschinenlesbare Signatur: das muss der Aufrufer erfahren,
+     * ohne den Bytestrom zu durchsuchen.
+     */
+    qrFehler: string | null;
+    /**
+     * Der QR steht auf dem Papier, aber nicht so wie eingestellt — `null`,
+     * solange nichts abgewichen ist. Zwei Faelle, beide mit Grund im Text: das
+     * Symbol war fuer den nativen Befehl zu breit und ging als Bild hinaus, oder
+     * es passte nur unter der Mindest-Modulgroesse.
+     *
+     * Getrennt von `qrFehler`, weil die Handlung eine andere ist: dort heisst es
+     * "Beleg ohne QR, nachdrucken oder elektronisch ausgeben", hier "gedruckt,
+     * aber der eingestellte Weg taugt fuer dieses Geraet nicht".
+     */
+    qrAusweich: string | null;
     /** intern: bisher erzeugte Bytes */
     readonly bytes: number[];
     /** intern: global gesetzte Codepage (ueberlebt `escPosReset`) */
@@ -213,7 +259,45 @@ export declare function escPosRow(doc: EscPosDocument, columns: readonly PosColu
 export declare function qrCodeBytes(text: string, options?: {
     size?: QrSize;
     correction?: QrCorrection;
+    modell1?: boolean;
 }): Uint8Array;
-/** Setzt die Ausrichtung und haengt den nativen QR-Befehl an. */
+/**
+ * Setzt die Ausrichtung und haengt den nativen QR-Befehl an — mit
+ * **gerechneter** Modulgroesse, sofern `options.size` sie nicht festlegt.
+ *
+ * Ohne `size` entscheidet die Regel aus `qr-groesse.ts`: so gross wie
+ * moeglich, gedeckelt durch `options.groesse` (Vorgabe `auto` = der
+ * Bestandswert 4 dieses Pakets). Passt das Symbol auch mit der
+ * Ausnahmegroesse nicht aufs Papier, geht **kein** QR-Befehl hinaus und
+ * `doc.qrFehler` sagt warum: der Drucker schneidet ein zu breites Symbol
+ * nicht ab, er laesst es weg — ein Befehl, von dem man weiss, dass er nichts
+ * druckt, taeuschte nur einen Ausdruck vor. Den Bildweg kennt diese Ebene
+ * nicht; den faehrt `escPosQrRaster` bzw. der Belegweg in `layout-escpos.ts`.
+ *
+ * Eine leere Nutzlast geht unveraendert durch (fester Bestandsweg, keine
+ * Rechnung): sie ist ein Datenfehler, kein Papierfehler, und der Aufrufer
+ * behandelt sie ohnehin schon.
+ */
 export declare function escPosQrCode(doc: EscPosDocument, text: string, options?: EscPosQrOptions): void;
+/**
+ * Der Bildweg: ein fertiges QR-Raster als Rasterbild (`GS v 0`) — der
+ * Notausgang, wenn der native Befehl das Symbol nicht auf das Papier bringt.
+ *
+ * Ein Pflichtbeleg ohne QR ist der schlechteste aller Ausgaenge; als Bild
+ * geht jedes Symbol hinaus, weil die Punkte je Modul hier bis auf 1 fallen
+ * duerfen. Dafuer ist das Bild langsamer und auf manchen Geraeten blasser.
+ *
+ * Das Raster selbst kommt vom Aufrufer (siehe `QrMatrix`): dieses Paket
+ * rechnet keine QR-Codes und verarbeitet keine Bilder.
+ */
+export declare function escPosQrRaster(doc: EscPosDocument, matrix: QrMatrix, options?: EscPosQrRasterOptions): void;
+/**
+ * Punkte je Modul, mit denen `escPosQrRaster` ein Raster dieser Groesse auf
+ * dieses Papier bringt — dieselbe Rechnung, nur ohne Untergrenze 3: ein Bild
+ * darf bis auf einen Punkt je Modul schrumpfen und passt darum immer.
+ */
+export declare function qrRasterPunkte(paperSize: PosPaperSize, moduleAnzahl: number, options?: {
+    groesse?: QrModulGroesse;
+    ruhezoneModule?: number;
+}): number;
 export {};