@kreiseck/kasseneck-api 0.9.4 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 0.10.0
+
+### Die Antwortcodeliste von hobex — jeder Code eingeordnet, jeder Ausgang mit Grund
+
+**Anlass:** hobex hat am 11.09.2026 die Antwortcodeliste der HPS-Anwendung
+geschickt. Drei der Codes kamen seit dem 28.08.2026 im Betrieb vor (`100004`,
+`100005`, `100015`) und waren bis jetzt ungedeutet. Jede Zahlung damit lief in
+die Klaerung und endete erst ueber die Zwei-9027-Regel. Zwilling:
+`kasseneck_api` 6.9.0, Begruendungen dort in `doc/kartenzahlung.md`.
+
+- **`HPS_CODES`** fuehrt alle 31 Codes der Liste zusammen mit den gemessenen:
+  Code, hobex-Titel, Bedeutung, Wirkung (`effect`), Grund (`reason`) und
+  Quelle (`source`). `isConclusive` liest seine Positivliste daraus.
+  `HPS_MEASURED_CODES` bleibt als abgekuendigter Name fuer dieselbe Tabelle.
+- **Was vor dem Host scheitert, ist eine Ablehnung** (Kartenlesen, EMV-Kernel,
+  Eingaben am Geraet, Geraetezustand, fehlerhafte Anfrage) -- `declined`, ohne
+  Abbruch und ohne Statusabfrage. Dazu `100029`: das Terminal storniert laut
+  hobex selbst.
+- **Neu: `effect: 'hostUncertain'`** (`isHostUncertain`) fuer `100006`,
+  `100007`, `100023`, `100024`, `100026`, `100027`, `100999`. Der Host war
+  beteiligt, das Terminal storniert nicht selbst. Die Zwei-9027-Regel greift
+  hier **nicht**; die Klaerung endet nach zwei Abfragen ohne Neues als
+  `unresolved`, nur ein `'0'` entscheidet danach noch, und ein Abbruchversuch
+  entfaellt. Bei einer Aufhebung entscheidet ein unveraendertes `'0'` auf die
+  Originalzahlung dann ebenfalls nichts.
+- **`rejectsRequest` / `isConclusiveAsStatus`:** zehn Codes weisen die Anfrage
+  selbst ab (`9002`, `100001`, `100008`, `100108`, `100009`, `100010`,
+  `100013`, `100018`, `100022`, `100998`). Auf eine Zahlung sind sie deren
+  Ablehnung, auf eine Statusabfrage sagen sie nichts ueber den gesuchten
+  Vorgang (gemessen fuer `100108`). Die Klaerung liest den Status deshalb
+  ueber `isConclusiveAsStatus` -- sonst haette ein gesperrtes Terminal eine
+  verlorene Zahlung als "nicht belastet" ausgewiesen.
+- **`HpsPaymentResult.reason`** traegt fuer jeden Ausgang den Grund, den Satz
+  fuer den Bediener gibt `HPS_REASON_HINTS`. Gesetzt, wo entschieden wurde:
+  bestaetigter Abbruch `aborted`, HTTP 409 `terminalBusy`, eine ueber die
+  Zwei-9027-Regel geklaerte Zahlung mit dem Grund ihres eigenen Codes.
+  `isHostUncertainResult` sagt einer spaeteren Nachfrage, dass ein `9027` dort
+  nicht "nicht belastet" heisst.
+- `hpsCodeInfo`, `hpsCodeReason` und die Namen aller neuen Codes
+  (`CARD_READ_FAILED_CODE` usw.) sind exportiert.
+- Der Nachweis nennt bei einer Ablehnung den hobex-Titel mit
+  (`Terminal: abgelehnt (100015 "Card declined")`).
+- `fixtures/hobex-hps-codes.json` fuehrt je Code zusaetzlich `title`,
+  `effect`, `reason`, `source` und die Saetze je Grund (`gruende`).
+
 ## 0.9.4
 
 ### `qrModus` faengt bei `auto` an — sonst stellte die Vorgabe den Altbestand um

package/dist/cjs/payments/hobex-hps/index.d.ts

@@ -20,8 +20,8 @@
 export { type HpsConnectCancelOptions, type HpsConnectClient, type HpsConnectClientOptions, type HpsConnectFetch, type HpsConnectFetchResponse, type HpsConnectPaymentOptions, type HpsConnectRefundOptions, type HpsConnectTarget, type HpsConnectTransactionOptions, createHpsConnectClient, } from './connect-client.js';
 export { HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, PREFLIGHT_CONNECT_CODES, } from './errors.js';
 export { type HpsPaymentEvent, type HpsPaymentEventKind, type HpsPaymentObserver, } from './events.js';
-export { type CardPaymentOutcome, type HpsPaymentResult, mayRetrySafely, } from './outcome.js';
+export { type CardPaymentOutcome, type HpsPaymentResult, isHostUncertainResult, mayRetrySafely, } from './outcome.js';
 export { type HpsCancelOptions, type HpsPaymentOptions, type HpsPayments, type HpsPaymentsOptions, type HpsRefundOptions, createHpsPayments, } from './payments.js';
 export { MAX_TRANSACTION_ID_LENGTH, createHpsTransactionIdGenerator, isValidHpsTransactionId, newHpsTransactionId, type HpsTransactionIdGeneratorOptions, } from './transaction-id.js';
-export { ABORTED_CODE, APPROVED_CODE, CARD_NOT_PRESENT_CODE, HPS_MEASURED_CODES, INVALID_TRANSACTION_CODE, NOT_ABORTABLE_CODE, INVALID_AMOUNT_CODE, AMOUNT_OUT_OF_RANGE_CODE, INVALID_TID_CODE, WRONG_PIN_CODE, NO_STATEMENT_CODE, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, isApproved, isCanceled, isConclusive, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, parseHpsTransactionResponse, type HpsMeasuredCode, type HpsTransactionResponse, } from './transaction-response.js';
+export { ABORTED_CODE, APP_SELECT_FAILED_CODE, APPROVED_CODE, BAD_REQUEST_CODE, CARD_DECLINED_CODE, CARD_INFO_NOT_ENTERED_CODE, CARD_NOT_PRESENT_CODE, CARD_NOT_SUPPORTED_CODE, CARD_READ_FAILED_CODE, CHIP_DATA_MISMATCH_CODE, COMPLETION_FAILED_CODE, DIAGNOSIS_FAILED_CODE, HOST_COMMUNICATION_FAILED_CODE, HOST_STEP_FAILED_CODE, HOST_TIMEOUT_REVERSED_CODE, HPS_CODES, HPS_MEASURED_CODES, HPS_REASON_HINTS, INTERNAL_ERROR_CODE, INVALID_MESSAGE_TYPE_CODE, INVALID_TID_DOCUMENTED_CODE, INVALID_TX_TYPE_CODE, MAX_RETRIES_EXCEEDED_CODE, NOT_FOUND_CODE, PASSWORD_NOT_ENTERED_CODE, REFUND_DISABLED_CODE, REFUND_PASSWORD_INVALID_CODE, SCEP_ENROLLMENT_FAILED_CODE, TERMINAL_BLOCKED_CODE, TERMINAL_BUSY_CODE, TIP_SELECTION_FAILED_CODE, UNSUPPORTED_USER_DATA_CODE, hpsCodeInfo, hpsCodeReason, isHostUncertain, isHostUncertainReason, INVALID_TRANSACTION_CODE, NOT_ABORTABLE_CODE, INVALID_AMOUNT_CODE, AMOUNT_OUT_OF_RANGE_CODE, INVALID_TID_CODE, WRONG_PIN_CODE, NO_STATEMENT_CODE, TECHNICAL_ERROR_CODE, TERMINAL_BUSY_HTTP_STATUS, TRANSACTION_CANCELED_CODE, isApproved, isCanceled, isConclusive, isConclusiveAsStatus, isInProgress, isNoStatement, isNotAbortable, isTechnicalError, isUnknownCode, parseHpsTransactionResponse, type HpsCode, type HpsCodeEffect, type HpsCodeReason, type HpsCodeSource, type HpsMeasuredCode, type HpsTransactionResponse, } from './transaction-response.js';
 export { hobexReceiptFromHps } from './receipt.js';

package/dist/cjs/payments/hobex-hps/index.js

@@ -19,7 +19,8 @@
  * des Aufrufers.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hobexReceiptFromHps = exports.parseHpsTransactionResponse = exports.isUnknownCode = exports.isTechnicalError = exports.isNotAbortable = exports.isNoStatement = exports.isInProgress = exports.isConclusive = exports.isCanceled = exports.isApproved = exports.TRANSACTION_CANCELED_CODE = exports.TERMINAL_BUSY_HTTP_STATUS = exports.TECHNICAL_ERROR_CODE = exports.NO_STATEMENT_CODE = exports.WRONG_PIN_CODE = exports.INVALID_TID_CODE = exports.AMOUNT_OUT_OF_RANGE_CODE = exports.INVALID_AMOUNT_CODE = exports.NOT_ABORTABLE_CODE = exports.INVALID_TRANSACTION_CODE = exports.HPS_MEASURED_CODES = exports.CARD_NOT_PRESENT_CODE = exports.APPROVED_CODE = exports.ABORTED_CODE = exports.newHpsTransactionId = exports.isValidHpsTransactionId = exports.createHpsTransactionIdGenerator = exports.MAX_TRANSACTION_ID_LENGTH = exports.createHpsPayments = exports.mayRetrySafely = exports.PREFLIGHT_CONNECT_CODES = exports.HpsTransactionIdError = exports.HpsPreflightError = exports.HpsConnectTransportError = exports.HpsConnectTerminalError = exports.HpsConnectException = exports.HpsClarifyTimeoutError = exports.createHpsConnectClient = void 0;
+exports.isHostUncertain = exports.hpsCodeReason = exports.hpsCodeInfo = exports.UNSUPPORTED_USER_DATA_CODE = exports.TIP_SELECTION_FAILED_CODE = exports.TERMINAL_BUSY_CODE = exports.TERMINAL_BLOCKED_CODE = exports.SCEP_ENROLLMENT_FAILED_CODE = exports.REFUND_PASSWORD_INVALID_CODE = exports.REFUND_DISABLED_CODE = exports.PASSWORD_NOT_ENTERED_CODE = exports.NOT_FOUND_CODE = exports.MAX_RETRIES_EXCEEDED_CODE = exports.INVALID_TX_TYPE_CODE = exports.INVALID_TID_DOCUMENTED_CODE = exports.INVALID_MESSAGE_TYPE_CODE = exports.INTERNAL_ERROR_CODE = exports.HPS_REASON_HINTS = exports.HPS_MEASURED_CODES = exports.HPS_CODES = exports.HOST_TIMEOUT_REVERSED_CODE = exports.HOST_STEP_FAILED_CODE = exports.HOST_COMMUNICATION_FAILED_CODE = exports.DIAGNOSIS_FAILED_CODE = exports.COMPLETION_FAILED_CODE = exports.CHIP_DATA_MISMATCH_CODE = exports.CARD_READ_FAILED_CODE = exports.CARD_NOT_SUPPORTED_CODE = exports.CARD_NOT_PRESENT_CODE = exports.CARD_INFO_NOT_ENTERED_CODE = exports.CARD_DECLINED_CODE = exports.BAD_REQUEST_CODE = exports.APPROVED_CODE = exports.APP_SELECT_FAILED_CODE = exports.ABORTED_CODE = exports.newHpsTransactionId = exports.isValidHpsTransactionId = exports.createHpsTransactionIdGenerator = exports.MAX_TRANSACTION_ID_LENGTH = exports.createHpsPayments = exports.mayRetrySafely = exports.isHostUncertainResult = exports.PREFLIGHT_CONNECT_CODES = exports.HpsTransactionIdError = exports.HpsPreflightError = exports.HpsConnectTransportError = exports.HpsConnectTerminalError = exports.HpsConnectException = exports.HpsClarifyTimeoutError = exports.createHpsConnectClient = void 0;
+exports.hobexReceiptFromHps = exports.parseHpsTransactionResponse = exports.isUnknownCode = exports.isTechnicalError = exports.isNotAbortable = exports.isNoStatement = exports.isInProgress = exports.isConclusiveAsStatus = exports.isConclusive = exports.isCanceled = exports.isApproved = exports.TRANSACTION_CANCELED_CODE = exports.TERMINAL_BUSY_HTTP_STATUS = exports.TECHNICAL_ERROR_CODE = exports.NO_STATEMENT_CODE = exports.WRONG_PIN_CODE = exports.INVALID_TID_CODE = exports.AMOUNT_OUT_OF_RANGE_CODE = exports.INVALID_AMOUNT_CODE = exports.NOT_ABORTABLE_CODE = exports.INVALID_TRANSACTION_CODE = exports.isHostUncertainReason = void 0;
 var connect_client_js_1 = require("./connect-client.js");
 Object.defineProperty(exports, "createHpsConnectClient", { enumerable: true, get: function () { return connect_client_js_1.createHpsConnectClient; } });
 var errors_js_1 = require("./errors.js");
@@ -31,6 +32,7 @@ Object.defineProperty(exports, "HpsPreflightError", { enumerable: true, get: fun
 Object.defineProperty(exports, "HpsTransactionIdError", { enumerable: true, get: function () { return errors_js_1.HpsTransactionIdError; } });
 Object.defineProperty(exports, "PREFLIGHT_CONNECT_CODES", { enumerable: true, get: function () { return errors_js_1.PREFLIGHT_CONNECT_CODES; } });
 var outcome_js_1 = require("./outcome.js");
+Object.defineProperty(exports, "isHostUncertainResult", { enumerable: true, get: function () { return outcome_js_1.isHostUncertainResult; } });
 Object.defineProperty(exports, "mayRetrySafely", { enumerable: true, get: function () { return outcome_js_1.mayRetrySafely; } });
 var payments_js_1 = require("./payments.js");
 Object.defineProperty(exports, "createHpsPayments", { enumerable: true, get: function () { return payments_js_1.createHpsPayments; } });
@@ -41,9 +43,41 @@ Object.defineProperty(exports, "isValidHpsTransactionId", { enumerable: true, ge
 Object.defineProperty(exports, "newHpsTransactionId", { enumerable: true, get: function () { return transaction_id_js_1.newHpsTransactionId; } });
 var transaction_response_js_1 = require("./transaction-response.js");
 Object.defineProperty(exports, "ABORTED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.ABORTED_CODE; } });
+Object.defineProperty(exports, "APP_SELECT_FAILED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.APP_SELECT_FAILED_CODE; } });
 Object.defineProperty(exports, "APPROVED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.APPROVED_CODE; } });
+Object.defineProperty(exports, "BAD_REQUEST_CODE", { enumerable: true, get: function () { return transaction_response_js_1.BAD_REQUEST_CODE; } });
+Object.defineProperty(exports, "CARD_DECLINED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.CARD_DECLINED_CODE; } });
+Object.defineProperty(exports, "CARD_INFO_NOT_ENTERED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.CARD_INFO_NOT_ENTERED_CODE; } });
 Object.defineProperty(exports, "CARD_NOT_PRESENT_CODE", { enumerable: true, get: function () { return transaction_response_js_1.CARD_NOT_PRESENT_CODE; } });
+Object.defineProperty(exports, "CARD_NOT_SUPPORTED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.CARD_NOT_SUPPORTED_CODE; } });
+Object.defineProperty(exports, "CARD_READ_FAILED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.CARD_READ_FAILED_CODE; } });
+Object.defineProperty(exports, "CHIP_DATA_MISMATCH_CODE", { enumerable: true, get: function () { return transaction_response_js_1.CHIP_DATA_MISMATCH_CODE; } });
+Object.defineProperty(exports, "COMPLETION_FAILED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.COMPLETION_FAILED_CODE; } });
+Object.defineProperty(exports, "DIAGNOSIS_FAILED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.DIAGNOSIS_FAILED_CODE; } });
+Object.defineProperty(exports, "HOST_COMMUNICATION_FAILED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.HOST_COMMUNICATION_FAILED_CODE; } });
+Object.defineProperty(exports, "HOST_STEP_FAILED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.HOST_STEP_FAILED_CODE; } });
+Object.defineProperty(exports, "HOST_TIMEOUT_REVERSED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.HOST_TIMEOUT_REVERSED_CODE; } });
+Object.defineProperty(exports, "HPS_CODES", { enumerable: true, get: function () { return transaction_response_js_1.HPS_CODES; } });
 Object.defineProperty(exports, "HPS_MEASURED_CODES", { enumerable: true, get: function () { return transaction_response_js_1.HPS_MEASURED_CODES; } });
+Object.defineProperty(exports, "HPS_REASON_HINTS", { enumerable: true, get: function () { return transaction_response_js_1.HPS_REASON_HINTS; } });
+Object.defineProperty(exports, "INTERNAL_ERROR_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INTERNAL_ERROR_CODE; } });
+Object.defineProperty(exports, "INVALID_MESSAGE_TYPE_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INVALID_MESSAGE_TYPE_CODE; } });
+Object.defineProperty(exports, "INVALID_TID_DOCUMENTED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INVALID_TID_DOCUMENTED_CODE; } });
+Object.defineProperty(exports, "INVALID_TX_TYPE_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INVALID_TX_TYPE_CODE; } });
+Object.defineProperty(exports, "MAX_RETRIES_EXCEEDED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.MAX_RETRIES_EXCEEDED_CODE; } });
+Object.defineProperty(exports, "NOT_FOUND_CODE", { enumerable: true, get: function () { return transaction_response_js_1.NOT_FOUND_CODE; } });
+Object.defineProperty(exports, "PASSWORD_NOT_ENTERED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.PASSWORD_NOT_ENTERED_CODE; } });
+Object.defineProperty(exports, "REFUND_DISABLED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.REFUND_DISABLED_CODE; } });
+Object.defineProperty(exports, "REFUND_PASSWORD_INVALID_CODE", { enumerable: true, get: function () { return transaction_response_js_1.REFUND_PASSWORD_INVALID_CODE; } });
+Object.defineProperty(exports, "SCEP_ENROLLMENT_FAILED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.SCEP_ENROLLMENT_FAILED_CODE; } });
+Object.defineProperty(exports, "TERMINAL_BLOCKED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.TERMINAL_BLOCKED_CODE; } });
+Object.defineProperty(exports, "TERMINAL_BUSY_CODE", { enumerable: true, get: function () { return transaction_response_js_1.TERMINAL_BUSY_CODE; } });
+Object.defineProperty(exports, "TIP_SELECTION_FAILED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.TIP_SELECTION_FAILED_CODE; } });
+Object.defineProperty(exports, "UNSUPPORTED_USER_DATA_CODE", { enumerable: true, get: function () { return transaction_response_js_1.UNSUPPORTED_USER_DATA_CODE; } });
+Object.defineProperty(exports, "hpsCodeInfo", { enumerable: true, get: function () { return transaction_response_js_1.hpsCodeInfo; } });
+Object.defineProperty(exports, "hpsCodeReason", { enumerable: true, get: function () { return transaction_response_js_1.hpsCodeReason; } });
+Object.defineProperty(exports, "isHostUncertain", { enumerable: true, get: function () { return transaction_response_js_1.isHostUncertain; } });
+Object.defineProperty(exports, "isHostUncertainReason", { enumerable: true, get: function () { return transaction_response_js_1.isHostUncertainReason; } });
 Object.defineProperty(exports, "INVALID_TRANSACTION_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INVALID_TRANSACTION_CODE; } });
 Object.defineProperty(exports, "NOT_ABORTABLE_CODE", { enumerable: true, get: function () { return transaction_response_js_1.NOT_ABORTABLE_CODE; } });
 Object.defineProperty(exports, "INVALID_AMOUNT_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INVALID_AMOUNT_CODE; } });
@@ -57,6 +91,7 @@ Object.defineProperty(exports, "TRANSACTION_CANCELED_CODE", { enumerable: true,
 Object.defineProperty(exports, "isApproved", { enumerable: true, get: function () { return transaction_response_js_1.isApproved; } });
 Object.defineProperty(exports, "isCanceled", { enumerable: true, get: function () { return transaction_response_js_1.isCanceled; } });
 Object.defineProperty(exports, "isConclusive", { enumerable: true, get: function () { return transaction_response_js_1.isConclusive; } });
+Object.defineProperty(exports, "isConclusiveAsStatus", { enumerable: true, get: function () { return transaction_response_js_1.isConclusiveAsStatus; } });
 Object.defineProperty(exports, "isInProgress", { enumerable: true, get: function () { return transaction_response_js_1.isInProgress; } });
 Object.defineProperty(exports, "isNoStatement", { enumerable: true, get: function () { return transaction_response_js_1.isNoStatement; } });
 Object.defineProperty(exports, "isNotAbortable", { enumerable: true, get: function () { return transaction_response_js_1.isNotAbortable; } });

package/dist/cjs/payments/hobex-hps/outcome.d.ts

@@ -1,4 +1,4 @@
-import type { HpsTransactionResponse } from './transaction-response.js';
+import { type HpsCodeReason, type HpsTransactionResponse } from './transaction-response.js';
 /**
  * Ausgang eines Kartenzahlvorgangs — die einzige Frage, die ein Aufrufer
  * wirklich hat: darf ich es nochmal versuchen?
@@ -35,6 +35,18 @@ export interface HpsPaymentResult {
      * Entscheidung getragen. Bei schluessigem Ausgang nicht gesetzt.
      */
     readonly lastResponse?: HpsTransactionResponse;
+    /**
+     * Worauf die Kasse reagiert -- der Grund hinter dem Ausgang, mit dem Satz
+     * fuer den Bediener in `HPS_REASON_HINTS`.
+     *
+     * Gesetzt an der Stelle, die den Ausgang entschieden hat, nicht aus
+     * [response] abgeleitet: ein bestaetigter Abbruch antwortet `'0'` und ist
+     * trotzdem `'aborted'`, und wenn die Zwei-9027-Regel eine Zahlung als
+     * abgelehnt klaert, zaehlt der Code der ZAHLUNG, nicht das `9027` danach.
+     * Fehlt, wenn kein Code etwas erklaert (die Leitung riss ab, bevor das
+     * Terminal etwas sagte) und bei einer Aufhebung, die nicht gegriffen hat.
+     */
+    readonly reason?: HpsCodeReason;
     /**
      * Verlauf der Klaerung, in Reihenfolge — der Nachweis, der im
      * Belastungsstreit gelesen wird. Behauptet nie eine Ursache, die nicht
@@ -44,3 +56,10 @@ export interface HpsPaymentResult {
 }
 /** Nur bei `'declined'` steht fest, dass nichts belastet wurde. */
 export declare function mayRetrySafely(result: Pick<HpsPaymentResult, 'outcome'>): boolean;
+/**
+ * `true`, wenn der Ausgang offen ist, weil das Terminal eine Stoerung beim
+ * oder nach dem hobex-Host meldete (`effect: 'hostUncertain'`). Wichtig fuer
+ * jede SPAETERE Nachfrage: antwortet die Statusabfrage dann `9027`, heisst das
+ * hier NICHT "nichts belastet".
+ */
+export declare function isHostUncertainResult(result: Pick<HpsPaymentResult, 'outcome' | 'reason'>): boolean;

package/dist/cjs/payments/hobex-hps/outcome.js

@@ -1,7 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mayRetrySafely = mayRetrySafely;
+exports.isHostUncertainResult = isHostUncertainResult;
+const transaction_response_js_1 = require("./transaction-response.js");
 /** Nur bei `'declined'` steht fest, dass nichts belastet wurde. */
 function mayRetrySafely(result) {
     return result.outcome === 'declined';
 }
+/**
+ * `true`, wenn der Ausgang offen ist, weil das Terminal eine Stoerung beim
+ * oder nach dem hobex-Host meldete (`effect: 'hostUncertain'`). Wichtig fuer
+ * jede SPAETERE Nachfrage: antwortet die Statusabfrage dann `9027`, heisst das
+ * hier NICHT "nichts belastet".
+ */
+function isHostUncertainResult(result) {
+    return result.outcome === 'unresolved' && (0, transaction_response_js_1.isHostUncertainReason)(result.reason);
+}

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

@@ -89,6 +89,25 @@ import type { HpsPaymentResult } from './outcome.js';
  * Kein [tryAbort]-Versuch bei [cancel]: die Originalzahlung ist laengst
  * abgeschlossen und antwortet gemessen mit `100010` -- ein Abbruch darauf
  * waere sinnlos.
+ *
+ * ## Stoerung beim Host: die Klaerung darf nichts schliessen (11.09.2026)
+ *
+ * Die Antwortcodeliste von hobex benennt Codes, bei denen der Host beteiligt
+ * war und das Terminal NICHT selbst storniert (`effect: 'hostUncertain'`,
+ * etwa `100007`). Fuer sie gilt zweierlei:
+ *
+ * 1. Die Zwei-9027-Regel ([ausGeschlossenerAntwort]) greift nicht. Sie
+ *    schliesst aus "das Terminal hat geantwortet und nichts gespeichert" auf
+ *    "nichts belastet" -- das stimmt fuer einen Vorgang, der am Terminal
+ *    endete, aber nicht fuer einen, dessen Ausgang beim Host liegt. Dasselbe
+ *    gilt sinngemaess fuer [cancel]: ein unveraendertes `'0'` auf die
+ *    Originalzahlung beweist dann nicht, dass die Aufhebung beim Host nicht
+ *    ankam.
+ * 2. Die Klaerung wartet trotzdem nicht das ganze Budget ab. Sagt die
+ *    Statusabfrage zweimal in Folge nichts Neues (`9027` oder erneut ein
+ *    solcher Code), endet sie sofort als `unresolved` -- das Terminal wird es
+ *    auch in 90 Sekunden nicht wissen. Meldet sie dagegen `'0'`, ist die
+ *    Zahlung genehmigt, ganz normal.
  */
 export interface HpsPaymentsOptions {
     /** Wie lange insgesamt geklaert wird, bevor der Ausgang offen bleibt. Vorgabe 90 s. */

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

@@ -59,7 +59,34 @@ 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 = (0, transaction_response_js_1.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 && (0, transaction_response_js_1.isHostUncertain)(antwort))
+            return (0, transaction_response_js_1.hpsCodeReason)(antwort.responseCode);
+        if (letzte && (0, transaction_response_js_1.isHostUncertain)(letzte))
+            return (0, transaction_response_js_1.hpsCodeReason)(letzte.responseCode);
+        if (antwort?.responseCode !== undefined)
+            return (0, transaction_response_js_1.hpsCodeReason)(antwort.responseCode);
+        return (0, transaction_response_js_1.hpsCodeReason)(letzte?.responseCode);
     }
     /** Verlaufseintrag fuer eine direkte Antwort, die den Ausgang NICHT festschreibt. */
     function offeneAntwort(res) {
@@ -69,6 +96,12 @@ function createHpsPayments(client, target, options = {}) {
         if ((0, transaction_response_js_1.isTechnicalError)(res)) {
             return `Antwort mit technischem Fehler (${transaction_response_js_1.TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang, Ausgang wird geklaert`;
         }
+        if ((0, transaction_response_js_1.isHostUncertain)(res)) {
+            return `${stoerung(res)} -- ob belastet wurde, weiss das Terminal nicht, Ausgang wird geklaert`;
+        }
+        if (res.responseCode === transaction_response_js_1.NOT_FOUND_CODE) {
+            return `Terminal kennt den Vorgang nicht (${res.responseCode} "Not Found") -- keine Aussage, Ausgang wird geklaert`;
+        }
         if ((0, transaction_response_js_1.isUnknownCode)(res)) {
             return `Terminal nennt einen unbekannten Code (${res.responseCode})${klartext(res)} -- Ausgang wird geklaert`;
         }
@@ -82,6 +115,22 @@ function createHpsPayments(client, target, options = {}) {
         if ((0, transaction_response_js_1.isTechnicalError)(status)) {
             return `Status: technischer Fehler (${transaction_response_js_1.TECHNICAL_ERROR_CODE}) -- keine Aussage ueber den Vorgang`;
         }
+        if ((0, transaction_response_js_1.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 === transaction_response_js_1.NOT_FOUND_CODE) {
+            return `Status: Vorgang nicht gefunden (${status.responseCode}) -- keine Aussage`;
+        }
+        const info = (0, transaction_response_js_1.hpsCodeInfo)(status.responseCode);
+        if (info?.rejectsRequest) {
+            return `Status: Abfrage abgewiesen (${info.code} "${info.title}") -- keine Aussage ueber den Vorgang`;
+        }
+        if (info?.conclusive && !(0, transaction_response_js_1.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 ((0, transaction_response_js_1.isUnknownCode)(status)) {
             return `Status: unbekannter Code (${status.responseCode})${klartext(status)} -- keine Aussage`;
         }
@@ -98,14 +147,27 @@ 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 (!(0, transaction_response_js_1.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} "${(0, transaction_response_js_1.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' : (0, transaction_response_js_1.hpsCodeReason)(res.responseCode),
+            steps: [...steps],
+        };
     }
     /**
      * Ordnet die DIREKTE Antwort auf einen Aufhebungs-Request ein. Fast dasselbe
@@ -131,7 +193,7 @@ function createHpsPayments(client, target, options = {}) {
             steps.push(`Aufhebung mit ${transaction_response_js_1.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
@@ -186,7 +248,7 @@ 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 ((0, transaction_response_js_1.isApproved)(status)) {
             if (firstQuery) {
@@ -202,14 +264,15 @@ 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],
         };
     }
@@ -274,26 +337,46 @@ 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 && (0, transaction_response_js_1.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();
@@ -318,23 +401,45 @@ function createHpsPayments(client, target, options = {}) {
                 wait = nextWait(wait);
                 continue;
             }
-            const settled = fromResponse(status, id, steps);
-            if (settled)
-                return settled;
+            if ((0, transaction_response_js_1.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 ? (0, transaction_response_js_1.isApproved)(status) : (0, transaction_response_js_1.isConclusiveAsStatus)(status)) {
+                const settled = fromResponse(status, id, steps);
+                if (settled)
+                    return settled;
+            }
             if ((0, transaction_response_js_1.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
@@ -359,10 +464,15 @@ 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;
@@ -374,6 +484,7 @@ function createHpsPayments(client, target, options = {}) {
             outcome: 'declined',
             transactionId: id,
             response: status,
+            reason: (0, transaction_response_js_1.hpsCodeReason)(antwort.responseCode),
             steps: [...steps],
         };
     }
@@ -393,11 +504,17 @@ 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 && (0, transaction_response_js_1.isHostUncertain)(antwort);
+        let letzteAntwort = antwort;
         let wait = 0;
         let transportFailures = 0;
         // Zaehlt nur BEANTWORTETE Statusabfragen -- Grundlage der Karenz fuer den
@@ -428,6 +545,16 @@ function createHpsPayments(client, target, options = {}) {
                 wait = nextWait(wait);
                 continue;
             }
+            if (hostUngewiss && (0, transaction_response_js_1.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;
@@ -439,7 +566,7 @@ 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 ?? (0, transaction_id_js_1.newHpsTransactionId)();
@@ -478,7 +605,7 @@ 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]
@@ -522,7 +649,7 @@ 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.