@kreiseck/kasseneck-api 0.7.0 → 0.7.2

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

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Hobex-**HPS**-Kartenzahlung ueber **Kasseneck Connect** — den lokalen
+ * Geraete-Agenten, der ueber HTTP erreichbar ist und mit dem physischen
+ * Terminal spricht. Siehe `payments.ts` fuer den Klaerweg (Doku dort ist der
+ * Maszstab) und `connect-client.ts` fuer die Abgrenzung zum Dart-Zwilling
+ * `HpsClient` (der das Terminal DIREKT anspricht, ohne Connect).
+ *
+ * `pay`/`refund`/`cancel` — seit `kasseneck-connect` Commit `1c8a003` traegt
+ * Connect auch Gutschrift und Aufhebung, die Luecke aus einer frueheren
+ * Fassung dieses Moduls ist geschlossen.
+ *
+ * **Verbleibt: keine Adress-/Port-Ermittlung fuer Connect.** Der Agent kann
+ * auf `127.0.0.1:27182` bis `27189` laufen (belegter Port faellt auf den
+ * naechsten zurueck, siehe `kasseneck-connect`s README). Dieses Modul nimmt
+ * eine FESTE `baseUrl` entgegen (`HpsConnectClientOptions.baseUrl`, Vorgabe
+ * `27182`) und probiert die Portreihe nicht selbst durch — das Aufloesen der
+ * tatsaechlichen Adresse (z. B. ueber `GET /v1/status` je Port) bleibt Sache
+ * 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;
+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");
+Object.defineProperty(exports, "HpsClarifyTimeoutError", { enumerable: true, get: function () { return errors_js_1.HpsClarifyTimeoutError; } });
+Object.defineProperty(exports, "HpsConnectException", { enumerable: true, get: function () { return errors_js_1.HpsConnectException; } });
+Object.defineProperty(exports, "HpsConnectTerminalError", { enumerable: true, get: function () { return errors_js_1.HpsConnectTerminalError; } });
+Object.defineProperty(exports, "HpsConnectTransportError", { enumerable: true, get: function () { return errors_js_1.HpsConnectTransportError; } });
+Object.defineProperty(exports, "HpsPreflightError", { enumerable: true, get: function () { return errors_js_1.HpsPreflightError; } });
+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, "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; } });
+var transaction_id_js_1 = require("./transaction-id.js");
+Object.defineProperty(exports, "MAX_TRANSACTION_ID_LENGTH", { enumerable: true, get: function () { return transaction_id_js_1.MAX_TRANSACTION_ID_LENGTH; } });
+Object.defineProperty(exports, "createHpsTransactionIdGenerator", { enumerable: true, get: function () { return transaction_id_js_1.createHpsTransactionIdGenerator; } });
+Object.defineProperty(exports, "isValidHpsTransactionId", { enumerable: true, get: function () { return transaction_id_js_1.isValidHpsTransactionId; } });
+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, "APPROVED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.APPROVED_CODE; } });
+Object.defineProperty(exports, "CARD_NOT_PRESENT_CODE", { enumerable: true, get: function () { return transaction_response_js_1.CARD_NOT_PRESENT_CODE; } });
+Object.defineProperty(exports, "HPS_MEASURED_CODES", { enumerable: true, get: function () { return transaction_response_js_1.HPS_MEASURED_CODES; } });
+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; } });
+Object.defineProperty(exports, "AMOUNT_OUT_OF_RANGE_CODE", { enumerable: true, get: function () { return transaction_response_js_1.AMOUNT_OUT_OF_RANGE_CODE; } });
+Object.defineProperty(exports, "INVALID_TID_CODE", { enumerable: true, get: function () { return transaction_response_js_1.INVALID_TID_CODE; } });
+Object.defineProperty(exports, "WRONG_PIN_CODE", { enumerable: true, get: function () { return transaction_response_js_1.WRONG_PIN_CODE; } });
+Object.defineProperty(exports, "NO_STATEMENT_CODE", { enumerable: true, get: function () { return transaction_response_js_1.NO_STATEMENT_CODE; } });
+Object.defineProperty(exports, "TECHNICAL_ERROR_CODE", { enumerable: true, get: function () { return transaction_response_js_1.TECHNICAL_ERROR_CODE; } });
+Object.defineProperty(exports, "TERMINAL_BUSY_HTTP_STATUS", { enumerable: true, get: function () { return transaction_response_js_1.TERMINAL_BUSY_HTTP_STATUS; } });
+Object.defineProperty(exports, "TRANSACTION_CANCELED_CODE", { enumerable: true, get: function () { return transaction_response_js_1.TRANSACTION_CANCELED_CODE; } });
+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, "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; } });
+Object.defineProperty(exports, "isTechnicalError", { enumerable: true, get: function () { return transaction_response_js_1.isTechnicalError; } });
+Object.defineProperty(exports, "isUnknownCode", { enumerable: true, get: function () { return transaction_response_js_1.isUnknownCode; } });
+Object.defineProperty(exports, "parseHpsTransactionResponse", { enumerable: true, get: function () { return transaction_response_js_1.parseHpsTransactionResponse; } });
+var receipt_js_1 = require("./receipt.js");
+Object.defineProperty(exports, "hobexReceiptFromHps", { enumerable: true, get: function () { return receipt_js_1.hobexReceiptFromHps; } });

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

@@ -0,0 +1,46 @@
+import type { HpsTransactionResponse } from './transaction-response.js';
+/**
+ * Ausgang eines Kartenzahlvorgangs — die einzige Frage, die ein Aufrufer
+ * wirklich hat: darf ich es nochmal versuchen?
+ *
+ * Drei Werte, nicht zwei: ein `boolean` oder ein `null` als Ergebnis einer
+ * Zahlung waere ein Fehler, kein Stil (Zwilling: `CardPaymentOutcome` in
+ * `kasseneck_api/lib/src/payments/card_payment_outcome.dart`).
+ */
+export type CardPaymentOutcome = 'approved' | 'declined' | 'unresolved';
+/**
+ * Ergebnis einer Kartenzahlung samt Kennung und Klaerungsverlauf.
+ *
+ * [transactionId] ist IMMER gesetzt, auch bei `outcome: 'unresolved'` — ohne
+ * sie sind Statusabfrage und weitere Klaerung unerreichbar, und genau daran
+ * ist der Vorfall vom 24.08.2026 gescheitert.
+ */
+export interface HpsPaymentResult {
+    readonly outcome: CardPaymentOutcome;
+    readonly transactionId: string;
+    /**
+     * Die Antwort des Terminals, die den Ausgang FESTGESCHRIEBEN hat -- nur
+     * bei `approved` und `declined`. Bei `unresolved` fehlt sie: eine
+     * Nicht-Aussage darf nicht als Beleg mitgegeben werden. Was das Terminal
+     * zuletzt gesagt hat, steht dann in [lastResponse].
+     */
+    readonly response?: HpsTransactionResponse;
+    /**
+     * Die letzte Antwort des Terminals bei `unresolved`, sofern ueberhaupt
+     * eine ankam -- auch wenn sie nichts entschied (9027, 9900, ein
+     * unbekannter Code). NIE ein Beleg, sondern Material fuer Anzeige und
+     * Katalog: am 02.09.2026 sah der Bediener bei einer Antwort `55`
+     * "PIN falsch" nur "Ausgang unklar", musste raten und buchte eine
+     * abgelehnte Zahlung als bezahlt. Der Klartext des Terminals haette die
+     * Entscheidung getragen. Bei schluessigem Ausgang nicht gesetzt.
+     */
+    readonly lastResponse?: HpsTransactionResponse;
+    /**
+     * Verlauf der Klaerung, in Reihenfolge — der Nachweis, der im
+     * Belastungsstreit gelesen wird. Behauptet nie eine Ursache, die nicht
+     * feststeht.
+     */
+    readonly steps: readonly string[];
+}
+/** Nur bei `'declined'` steht fest, dass nichts belastet wurde. */
+export declare function mayRetrySafely(result: Pick<HpsPaymentResult, 'outcome'>): boolean;

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

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mayRetrySafely = mayRetrySafely;
+/** Nur bei `'declined'` steht fest, dass nichts belastet wurde. */
+function mayRetrySafely(result) {
+    return result.outcome === 'declined';
+}

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

@@ -0,0 +1,149 @@
+import type { HpsConnectClient, HpsConnectTarget } from './connect-client.js';
+import type { HpsPaymentObserver } from './events.js';
+import type { HpsPaymentResult } from './outcome.js';
+/**
+ * Kartenzahlung ueber **Kasseneck Connect**, deren Ausgang IMMER bekannt ist.
+ *
+ * Zwilling von `HpsPayments` (`kasseneck_api/lib/src/hobex_hps/hps_payments.dart`)
+ * — Logik und Begruendungen sind von dort uebernommen, nicht neu erfunden.
+ * Was dort an Flutter/Dart-Spezifischem haengt, gehoert hier nicht hin; siehe
+ * `connect-client.ts` fuer den wesentlichen Unterschied (Connect statt
+ * direktem Terminal-Kontakt).
+ *
+ * [pay], [refund] und [cancel] -- seit `kasseneck-connect` Commit `1c8a003`
+ * traegt Connect auch die beiden letzteren, siehe `connect-client.ts`.
+ *
+ * Regel, von der nicht abgewichen wird: `outcome: 'declined'` entsteht
+ * ausschliesslich aus einer POSITIVEN Aussage — einem GEMESSENEN Ergebniscode
+ * des Terminals ungleich `'0'` ([isConclusive]), einem nachweislich
+ * gelungenen Abbruch, oder dem gemessenen "Terminal beschaeftigt"-Fall
+ * (HTTP 409 auf die ERZEUGENDE Anfrage, siehe `errors.ts`,
+ * `HpsConnectTerminalError.isTerminalBusy`). Ein Transportfehler, ein
+ * Zeitablauf oder eine Wissensluecke fuehren NIE dorthin: keines davon ist
+ * eine Aussage darueber, dass nichts belastet wurde. Genau diese
+ * Verwechslung hat am 24.08.2026 eine echte Belastung als unbelastet
+ * ausgewiesen und den Kunden ein zweites Mal belastet.
+ *
+ * ## Der Klaerweg, wie er am 26./27.08.2026 am hobex-HPS gemessen wurde
+ *
+ * Bleibt die Antwort auf eine Zahlung aus:
+ *
+ * 1. [HpsConnectClient.abort] einmalig versuchen.
+ * 2. `responseCode === '0'` -> der Vorgang war noch abbrechbar, also nicht
+ *    abgeschlossen -> `declined`, beweisbar.
+ * 3. Jeder andere Code (gemessen `100010`) -> der Vorgang ist ueber den
+ *    abbrechbaren Punkt hinaus -> JETZT die Statusabfrage pollen, sie liefert
+ *    nun eine echte Aussage.
+ * 4. Abbruch scheitert am Transport -> pollen wie in 3.
+ * 5. Beim Pollen ist `9027` KEIN Ergebnis, sondern ein Grund weiterzumachen.
+ *    Budget erschoepft -> `unresolved`.
+ *
+ * Der Abbruch VOR dem Pollen ist wesentlich: die Statusabfrage meldet
+ * "laeuft noch" nie (sie antwortet auf jeden nicht genehmigten Vorgang mit
+ * `9027`). Der Abbruchversuch ist auf einen Bruchteil des Klaerbudgets
+ * gedeckelt ([ABORT_BUDGET_DIVISOR]), sonst friesst ein haengender Abbruch
+ * die ganze Klaerung.
+ *
+ * Die Kennung ist in JEDEM Ergebnis gesetzt, auch bei `'unresolved'`.
+ *
+ * ## [refund] bekommt EXAKT denselben Klaerweg wie [pay]
+ *
+ * Abbruch eingeschlossen -- und das ist GEMESSEN, nicht analog geschlossen.
+ * Am 26.08.2026 nachgemessen: `abort` auf eine LAUFENDE Gutschrift antwortet
+ * ebenfalls mit `responseCode '0'`, und die Gutschrift endet daraufhin mit
+ * `100002` "Aborted". Der Abbruch ist dort also derselbe Diskriminator wie bei
+ * einer Zahlung. Die Kennung ist bei [refund] die des NEUEN Vorgangs (der
+ * Gutschrift selbst), eine Statusabfrage darauf liefert also genau deren
+ * Ausgang -- deshalb reicht dieselbe [resolve]-Funktion unveraendert. Ohne den
+ * Abbruch haette die Klaerung einer Gutschrift gar keinen Diskriminator mehr
+ * und endete fast immer bei `unresolved`, weil die Statusabfrage auch hier
+ * `9027` antwortet.
+ *
+ * ## [cancel] ist die Ausnahme, in beiden Richtungen
+ *
+ * Die uebergebene Kennung ist die der URSPRUENGLICHEN Zahlung, nicht die eines
+ * neuen Vorgangs -- und `'0'` bedeutet dort NICHT "genehmigt". Am 26. und
+ * 28.08.2026 gemessen (Statusabfrage auf die Original-Kennung, NACHDEM eine
+ * genehmigte Zahlung per Void aufgehoben wurde):
+ *
+ * | Antwort der Statusabfrage auf die Originalkennung | Bedeutung |
+ * |---|---|
+ * | `9011` "Transaction Canceled" | die Aufhebung hat GEWIRKT -> `approved` |
+ * | `'0'` | die Originalzahlung steht UNVERAENDERT -> die Aufhebung hat NICHT gegriffen -> `declined` |
+ * | `9027` und alles andere | weiter klaeren, am Ende `unresolved` |
+ *
+ * Zwei Sicherungen dagegen, `'0'` faelschlich fuer "nicht gegriffen" zu halten
+ * und damit den Kunden nach dem Tagesabschluss ueber eine Rueckerstattung ein
+ * zweites Mal zu bezahlen (siehe [fromCancelStatus]):
+ *
+ * 1. **`'0'` entscheidet erst ab der ZWEITEN beantworteten Statusabfrage.**
+ *    Die erste laeuft unmittelbar nachdem der Aufhebungs-Aufruf abgerissen
+ *    ist -- genau das Fenster, in dem die Aufhebung noch unterwegs sein kann.
+ *    Reicht das Budget nur fuer eine Abfrage, endet die Klaerung bei
+ *    `unresolved`.
+ * 2. **`9011` auf dem DIREKTEN Antwortweg von `cancel`** wird NICHT als
+ *    `declined` gelesen -- was es dort genau heisst, ist ungemessen (siehe
+ *    [fromCancelResponse]). Der Zustand der Originalzahlung wird abgefragt
+ *    statt geraten.
+ *
+ * Kein [tryAbort]-Versuch bei [cancel]: die Originalzahlung ist laengst
+ * abgeschlossen und antwortet gemessen mit `100010` -- ein Abbruch darauf
+ * waere sinnlos.
+ */
+export interface HpsPaymentsOptions {
+    /** Wie lange insgesamt geklaert wird, bevor der Ausgang offen bleibt. Vorgabe 90 s. */
+    resolveBudgetMs?: number;
+    /** Obergrenze fuer den Abstand zwischen zwei Statusabfragen. Vorgabe 10 s. */
+    maxBackoffMs?: number;
+    /** Nach so vielen Statusabfragen in Folge, die am Transport scheitern, wird abgebrochen. Vorgabe 3. */
+    maxTransportFailures?: number;
+    /** Pausenquelle — Naht fuer Tests. Vorgabe `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Uhr fuer das Budget in ms — Naht fuer Tests. Vorgabe `Date.now`. */
+    now?: () => number;
+    observer?: HpsPaymentObserver;
+}
+export interface HpsPaymentOptions {
+    /** Zu belastender Betrag in **Cent** (ohne Trinkgeld). */
+    amountCents: number;
+    tipCents?: number;
+    reference?: string;
+    currency?: string;
+    language?: string;
+    /**
+     * Kennung; wird ohne Angabe erzeugt und im Ergebnis zurueckgegeben. Vorgeben,
+     * um einen abgebrochenen Vorgang gezielt weiterzuverfolgen.
+     */
+    transactionId?: string;
+}
+export interface HpsRefundOptions {
+    /** Zu erstattender Betrag in **Cent**. */
+    amountCents: number;
+    /** Kennung der erstatteten Zahlung -- Connect verlangt sie zwingend. */
+    originalTransactionId: string;
+    reference?: string;
+    currency?: string;
+    language?: string;
+    /**
+     * Kennung der Gutschrift SELBST; wird ohne Angabe erzeugt und im Ergebnis
+     * zurueckgegeben. Vorgeben, um eine abgebrochene Gutschrift gezielt
+     * weiterzuverfolgen -- wie bei [HpsPaymentOptions.transactionId].
+     */
+    transactionId?: string;
+}
+export interface HpsCancelOptions {
+    /** Kennung der URSPRUENGLICHEN Zahlung -- keine neue, MUSS feststehen. */
+    transactionId: string;
+    /** Pflicht: ein Void ohne Betrag weist das Terminal mit `400 Missing amount` ab. */
+    amountCents: number;
+    currency?: string;
+    language?: string;
+}
+export interface HpsPayments {
+    pay(options: HpsPaymentOptions): Promise<HpsPaymentResult>;
+    /** Gutschrift, geklaert wie [pay] -- siehe Klassendoku oben. */
+    refund(options: HpsRefundOptions): Promise<HpsPaymentResult>;
+    /** Aufhebung (Storno/Void) einer bestehenden Zahlung -- eigener Klaerweg, siehe Klassendoku oben. */
+    cancel(options: HpsCancelOptions): Promise<HpsPaymentResult>;
+}
+export declare function createHpsPayments(client: HpsConnectClient, target: HpsConnectTarget, options?: HpsPaymentsOptions): HpsPayments;