@kreiseck/kasseneck-api 0.6.45 → 0.6.49

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

@@ -0,0 +1,104 @@
+import { type HpsTransactionResponse } from './transaction-response.js';
+/**
+ * Client fuer die Terminal-Endpunkte von **Kasseneck Connect** — dem lokalen
+ * Geraete-Agenten, der ueber HTTP erreichbar ist und mit dem hobex-HPS
+ * spricht (`kasseneck-connect/lib/src/api/routes_terminal.dart`). Connect
+ * reicht die Antwort des Terminals ROH durch und ordnet nichts ein; die
+ * Einordnung passiert in `transaction-response.ts` und `payments.ts`.
+ *
+ * **Kein direkter Terminal-Kontakt.** Ein Browser hat keine rohen
+ * TCP-Sockets — das ist der Unterschied zum Dart-Zwilling `HpsClient`, der
+ * das HPS-Terminal direkt anspricht. Dieser Client spricht ausschliesslich
+ * mit Connect, niemals mit dem Terminal selbst.
+ *
+ * **`payment`/`status`/`abort`/`refund`/`cancel`.** Seit
+ * `kasseneck-connect` Commit `1c8a003` traegt Connect auch die Gutschrift
+ * (`POST /v1/terminal/refund`) und die Aufhebung (`POST /v1/terminal/cancel`)
+ * — beide erben denselben Fehlerpfad wie `payment` (`error.detail.terminalHttpStatus`,
+ * siehe `HpsConnectTerminalError.isTerminalBusy`).
+ */
+/** Adresse des Ziel-Terminals — bei jedem Aufruf mitgegeben, Connect selbst ist zustandslos. */
+export interface HpsConnectTarget {
+    /** IP oder Hostname des Terminals im Kassen-Netz. */
+    host: string;
+    /** Vorgabe: `8080` (hobex-HPS-Standardport), siehe Connect. */
+    port?: number;
+    /** Terminal-ID, wie am Geraet angezeigt (fuehrende Nullen werden toleriert). */
+    tid: string;
+}
+export interface HpsConnectPaymentOptions extends HpsConnectTarget {
+    /** Kennung dieser Zahlung — MUSS vor diesem Aufruf feststehen, siehe `transaction-id.ts`. */
+    transactionId: string;
+    /** Zu belastender Betrag in **Cent** (ohne Trinkgeld). */
+    amountCents: number;
+    /** Trinkgeld in **Cent**; das Terminal belastet Betrag + Trinkgeld in einem. */
+    tipCents?: number;
+    reference?: string;
+    currency?: string;
+    language?: string;
+}
+export interface HpsConnectTransactionOptions extends HpsConnectTarget {
+    transactionId: string;
+}
+export interface HpsConnectRefundOptions extends HpsConnectTarget {
+    /** Kennung der Gutschrift SELBST — eine NEUE, nicht die der erstatteten Zahlung. */
+    transactionId: string;
+    /** Kennung der erstatteten Zahlung. Verlangt Connect zwingend, siehe `_handleRefund`. */
+    originalTransactionId: string;
+    /** Zu erstattender Betrag in **Cent**. */
+    amountCents: number;
+    reference?: string;
+    currency?: string;
+    language?: string;
+}
+export interface HpsConnectCancelOptions extends HpsConnectTarget {
+    /** Kennung der URSPRUENGLICHEN Zahlung — keine neue. */
+    transactionId: string;
+    /** Pflicht: das Terminal weist einen Void ohne Betrag mit `400 Missing amount` ab. */
+    amountCents: number;
+    currency?: string;
+    language?: string;
+}
+/** Austauschbare `fetch`-Umsetzung, minimal genug fuer eine Attrappe im Test. */
+export interface HpsConnectFetchResponse {
+    status: number;
+    text(): Promise<string>;
+}
+export type HpsConnectFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<HpsConnectFetchResponse>;
+export interface HpsConnectClientOptions {
+    /** Basisadresse des Agenten. Vorgabe `http://127.0.0.1:27182` (README `kasseneck-connect`). */
+    baseUrl?: string;
+    /** Kopplungstoken, geht als `Authorization: Bearer <token>` mit. */
+    token: string;
+    /**
+     * Zeitlimit fuer `status`/`abort`/`diagnosis` in ms. Vorgabe 30 s — deutlich
+     * ueber Connects eigenem `hpsKurzTimeout` (15 s), damit dieser Client nicht
+     * VOR Connect selbst aufgibt und dessen Fehlermeldung verschluckt.
+     */
+    shortTimeoutMs?: number;
+    /**
+     * Zeitlimit fuer `payment` in ms. Vorgabe 4,5 Minuten — ueber Connects
+     * eigenem `hpsZahlungTimeout` (4 Minuten): eine Zahlung blockiert, bis der
+     * Karteninhaber fertig ist, das darf nicht vorzeitig aufgegeben werden.
+     */
+    paymentTimeoutMs?: number;
+    /** Eigene `fetch`-Umsetzung (Tests). Vorgabe: globales `fetch`. */
+    fetch?: HpsConnectFetch;
+}
+export interface HpsConnectClient {
+    payment(options: HpsConnectPaymentOptions): Promise<HpsTransactionResponse>;
+    status(options: HpsConnectTransactionOptions): Promise<HpsTransactionResponse>;
+    abort(options: HpsConnectTransactionOptions): Promise<HpsTransactionResponse>;
+    /** Gutschrift — ein Kartenfluss wie [payment], deshalb dieselbe lange Frist. */
+    refund(options: HpsConnectRefundOptions): Promise<HpsTransactionResponse>;
+    /** Aufhebung (Storno/Void) — kurzer Aufruf, keine Karteninteraktion. */
+    cancel(options: HpsConnectCancelOptions): Promise<HpsTransactionResponse>;
+    /** Erreichbarkeits-/Firmware-Check, folgenlos. Rohe Nutzlast, Connect ordnet nichts ein. */
+    diagnosis(options: HpsConnectTarget): Promise<Record<string, unknown>>;
+}
+export declare function createHpsConnectClient(options: HpsConnectClientOptions): HpsConnectClient;

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

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHpsConnectClient = createHpsConnectClient;
+const errors_js_1 = require("./errors.js");
+const transaction_id_js_1 = require("./transaction-id.js");
+const transaction_response_js_1 = require("./transaction-response.js");
+const DEFAULT_BASE_URL = 'http://127.0.0.1:27182';
+const DEFAULT_SHORT_TIMEOUT_MS = 30_000;
+const DEFAULT_PAYMENT_TIMEOUT_MS = 4 * 60_000 + 30_000;
+function createHpsConnectClient(options) {
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const token = options.token;
+    const shortTimeoutMs = options.shortTimeoutMs ?? DEFAULT_SHORT_TIMEOUT_MS;
+    const paymentTimeoutMs = options.paymentTimeoutMs ?? DEFAULT_PAYMENT_TIMEOUT_MS;
+    const holen = options.fetch ?? globalHpsConnectFetch();
+    async function rufen(path, body, timeoutMs) {
+        const abbruch = new AbortController();
+        const wecker = setTimeout(() => abbruch.abort(), timeoutMs);
+        let antwort;
+        let text;
+        try {
+            try {
+                antwort = await holen(`${baseUrl}${path}`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+                    body: JSON.stringify(body),
+                    signal: abbruch.signal,
+                });
+                text = await antwort.text();
+            }
+            catch (ursache) {
+                // Connect selbst nicht erreichbar (Agent nicht gestartet, falscher
+                // Port, Zeitueberschreitung dieses Aufrufs). Kein Terminal-Kontakt
+                // versucht -- das entscheidet payments.ts aber nicht hier, sondern
+                // ueber die Fehlerart: [HpsConnectTransportError] wird dort wie jeder
+                // andere Transportfehler behandelt (klaeren, niemals `declined`).
+                const grund = abbruch.signal.aborted ? `Zeitueberschreitung nach ${timeoutMs} ms` : String(ursache);
+                throw new errors_js_1.HpsConnectTransportError(`Kasseneck Connect nicht erreichbar (${baseUrl}): ${grund}`);
+            }
+        }
+        finally {
+            clearTimeout(wecker);
+        }
+        let huelle;
+        try {
+            huelle = text.trim() === '' ? null : JSON.parse(text);
+        }
+        catch {
+            throw new errors_js_1.HpsConnectTransportError(`Antwort von Kasseneck Connect ist kein JSON (HTTP ${antwort.status})`);
+        }
+        if (huelle === null || typeof huelle !== 'object' || !('ok' in huelle)) {
+            throw new errors_js_1.HpsConnectTransportError(`Antwort von Kasseneck Connect ohne "ok"-Feld (HTTP ${antwort.status})`);
+        }
+        const h = huelle;
+        if (h.ok === true) {
+            return h;
+        }
+        const code = typeof h.error?.code === 'string' ? h.error.code : undefined;
+        const message = typeof h.error?.message === 'string' && h.error.message.trim() !== ''
+            ? h.error.message
+            : `Kasseneck Connect meldet einen Fehler (HTTP ${antwort.status})`;
+        if (code !== undefined && errors_js_1.PREFLIGHT_CONNECT_CODES.has(code)) {
+            // Siehe errors.ts: diese Codes entstehen laut `kasseneck-connect`
+            // ausnahmslos VOR jedem Terminal-Kontakt -- beweisbar nichts gesendet.
+            throw new errors_js_1.HpsPreflightError(message, code);
+        }
+        // terminal_error / timeout / terminal_offline -- oder ein Code, den
+        // dieses Paket nicht kennt. Bewusst dieselbe Klasse fuer beide: ein
+        // unbekannter Code ist keine bewiesene Nicht-Aussendung, siehe
+        // PREFLIGHT_CONNECT_CODES.
+        //
+        // `error.detail.terminalHttpStatus` reist seit `kasseneck-connect`
+        // Commit `0fb6f66` mit, wenn das TERMINAL selbst einen HTTP-Status
+        // genannt hat (nie bei einem Transportfehler -- der erfindet keinen
+        // Status). Siehe errors.ts, `HpsConnectTerminalError.isTerminalBusy`.
+        const detail = h.error?.detail;
+        const terminalHttpStatus = typeof detail?.terminalHttpStatus === 'number' ? detail.terminalHttpStatus : undefined;
+        throw new errors_js_1.HpsConnectTerminalError(code ?? 'unbekannt', message, terminalHttpStatus);
+    }
+    function checkedTransactionId(value) {
+        if (!(0, transaction_id_js_1.isValidHpsTransactionId)(value)) {
+            throw new errors_js_1.HpsTransactionIdError(value);
+        }
+        return value;
+    }
+    function target(t) {
+        return { host: t.host, port: t.port, tid: t.tid };
+    }
+    return {
+        async payment(o) {
+            const transactionId = checkedTransactionId(o.transactionId);
+            const antwort = await rufen('/v1/terminal/payment', {
+                ...target(o),
+                transactionId,
+                amountCents: o.amountCents,
+                tipCents: o.tipCents,
+                reference: o.reference,
+                currency: o.currency,
+                language: o.language,
+            }, paymentTimeoutMs);
+            return (0, transaction_response_js_1.parseHpsTransactionResponse)(antwort['hps']);
+        },
+        async status(o) {
+            const transactionId = checkedTransactionId(o.transactionId);
+            const antwort = await rufen('/v1/terminal/status', { ...target(o), transactionId }, shortTimeoutMs);
+            return (0, transaction_response_js_1.parseHpsTransactionResponse)(antwort['hps']);
+        },
+        async abort(o) {
+            const transactionId = checkedTransactionId(o.transactionId);
+            const antwort = await rufen('/v1/terminal/abort', { ...target(o), transactionId }, shortTimeoutMs);
+            return (0, transaction_response_js_1.parseHpsTransactionResponse)(antwort['hps']);
+        },
+        async refund(o) {
+            // Beide Kennungen gehen ans Terminal -- beide muessen die
+            // Ziffernpruefung bestehen, sonst ist der Vorgang spaeter dauerhaft
+            // unauffindbar (siehe HpsClient._checkTransactionId im Dart-Zwilling).
+            const transactionId = checkedTransactionId(o.transactionId);
+            const originalTransactionId = checkedTransactionId(o.originalTransactionId);
+            const antwort = await rufen('/v1/terminal/refund', {
+                ...target(o),
+                transactionId,
+                originalTransactionId,
+                amountCents: o.amountCents,
+                reference: o.reference,
+                currency: o.currency,
+                language: o.language,
+            }, 
+            // Gutschrift ist ein Kartenfluss wie die Zahlung -- dieselbe lange Frist.
+            paymentTimeoutMs);
+            return (0, transaction_response_js_1.parseHpsTransactionResponse)(antwort['hps']);
+        },
+        async cancel(o) {
+            // Hier ist [transactionId] die der URSPRUENGLICHEN Zahlung -- die
+            // Ziffernpruefung gilt trotzdem unveraendert, sonst liefe die
+            // anschliessende Statusabfrage darauf ins Leere.
+            const transactionId = checkedTransactionId(o.transactionId);
+            const antwort = await rufen('/v1/terminal/cancel', {
+                ...target(o),
+                transactionId,
+                amountCents: o.amountCents,
+                currency: o.currency,
+                language: o.language,
+            }, shortTimeoutMs);
+            return (0, transaction_response_js_1.parseHpsTransactionResponse)(antwort['hps']);
+        },
+        async diagnosis(o) {
+            const antwort = await rufen('/v1/terminal/diagnosis', target(o), shortTimeoutMs);
+            const hps = antwort['hps'];
+            return hps !== null && typeof hps === 'object' && !Array.isArray(hps) ? hps : {};
+        },
+    };
+}
+function globalHpsConnectFetch() {
+    const umgebung = globalThis;
+    if (typeof umgebung.fetch !== 'function') {
+        throw new Error('createHpsConnectClient: kein globales fetch vorhanden -- Node >= 20.18 verwenden oder eine fetch-Umsetzung uebergeben');
+    }
+    return (url, init) => umgebung.fetch(url, init);
+}

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

@@ -0,0 +1,122 @@
+/**
+ * Fehlerarten auf dem Weg ueber **Kasseneck Connect** zum hobex-HPS-Terminal.
+ *
+ * Drei Arten, bewusst getrennt, weil `payments.ts` auf jede anders reagiert —
+ * das ist die wichtigste Unterscheidung in diesem ganzen Vorhaben:
+ *
+ * - [HpsPreflightError] — es ist NACHWEISLICH nichts gesendet worden. Entweder
+ *   die Kennung selbst war unbrauchbar (siehe `connect-client.ts`), oder
+ *   Connect hat die Anfrage VOR dem Terminal-Kontakt abgelehnt (falscher
+ *   Host, keine Kopplung, ...). Wird von `payments.ts` unveraendert
+ *   weitergeworfen, niemals in einen Ausgang uebersetzt — Zwilling von
+ *   Dart's `ArgumentError`-Sonderfall in `HpsPayments.pay()`.
+ * - [HpsConnectTerminalError] — die Anfrage GING RAUS (oder der Versuch dazu
+ *   scheiterte am Transport), aber es kam keine schluessige Antwort. Das
+ *   umfasst ausdruecklich auch [isTerminalBusy]: HTTP `409` ist die einzige
+ *   dieser Lagen, die als [isTerminalBusy] eine POSITIVE Aussage traegt,
+ *   siehe dort.
+ * - [HpsConnectTransportError] — Connect selbst war nicht erreichbar oder
+ *   antwortete nicht in der erwarteten Form (kein JSON, keine Huelle).
+ *
+ * Beide letzteren werden von `payments.ts` in die Klaerung (Abbruch + Polling)
+ * geschickt, NIE in `declined` uebersetzt — mit der einen, gemessenen
+ * Ausnahme [isTerminalBusy].
+ */
+export declare abstract class HpsConnectException extends Error {
+}
+/**
+ * Nichts ist gesendet worden. `reason` ist deutscher Klartext, `connectCode`
+ * gesetzt, wenn die Ablehnung von Connect kam (statt von der lokalen
+ * Kennungspruefung).
+ */
+export declare class HpsPreflightError extends HpsConnectException {
+    readonly name: string;
+    readonly connectCode: string | undefined;
+    constructor(reason: string, connectCode?: string);
+}
+/**
+ * Die Transaktionskennung ist unbrauchbar (nicht rein numerisch, leer, oder
+ * laenger als 18 Stellen) — geprueft BEVOR irgendetwas an Connect geht, wie
+ * bei `HpsClient._checkTransactionId` im Dart-Zwilling.
+ *
+ * Eigene Klasse (statt nur [HpsPreflightError]) macht die Unterscheidung
+ * `instanceof`-pruefbar, ohne sich auf einen Text zu verlassen.
+ */
+export declare class HpsTransactionIdError extends HpsPreflightError {
+    readonly name = "HpsTransactionIdError";
+    readonly value: string;
+    constructor(value: string);
+}
+/**
+ * Bekannte Connect-Fehlercodes, die VOR jedem Terminal-Kontakt entstehen (aus
+ * `kasseneck-connect/lib/src/api/{auth,responses,routes_terminal}.dart`):
+ * Middleware (Herkunft, Token, Pfad, Rumpfgroesse) oder die Feldpruefung in
+ * `_ziel`/`_handlePayment`/`_mitTransaktion` laufen alle, BEVOR die Bruecke
+ * `HpsBridge` das Terminal ueberhaupt anspricht.
+ *
+ * Bewusst eine Positivliste: nur ein hier benannter Code gilt als "beweisbar
+ * nichts gesendet". Ein Code, den diese Liste nicht kennt, wird in
+ * `connect-client.ts` NICHT als [HpsPreflightError] gelesen, sondern als
+ * [HpsConnectTerminalError] — die sichere Richtung, falls Connect einmal um
+ * einen Fehlercode erweitert wird, der doch am Terminal entsteht.
+ */
+export declare const PREFLIGHT_CONNECT_CODES: ReadonlySet<string>;
+/**
+ * Die Anfrage ging (oder der Versuch dazu) in Richtung Terminal, aber es kam
+ * keine schluessige Antwort — Connect meldete `terminal_error`, `timeout`
+ * oder `terminal_offline` (`kasseneck-connect/lib/src/terminal/hps.dart`),
+ * oder einen Fehlercode, den dieses Paket nicht kennt.
+ */
+export declare class HpsConnectTerminalError extends HpsConnectException {
+    readonly name = "HpsConnectTerminalError";
+    /** Fehlercode von Connect, z. B. `terminal_error`, `timeout`, `terminal_offline`. */
+    readonly connectCode: string;
+    /**
+     * Der rohe HTTP-Status des Terminals, wenn Connect einen genannt hat
+     * (`error.detail.terminalHttpStatus`, seit `kasseneck-connect` Commit
+     * `0fb6f66`, "fix(terminal): den rohen HTTP-Status des Terminals mitgeben").
+     * `undefined` bei einem Transportfehler (Connect erfindet dort keinen) oder
+     * bei einer aelteren Connect-Fassung, die das Feld noch nicht sendet.
+     */
+    readonly terminalHttpStatus: number | undefined;
+    constructor(connectCode: string, message: string, terminalHttpStatus?: number);
+    /**
+     * `true`, wenn dies der gemessene "Terminal beschaeftigt"-Fall ist: das
+     * Terminal hat mit HTTP `409` geantwortet.
+     *
+     * Liest bevorzugt [terminalHttpStatus] — das strukturierte Feld, das
+     * Connect seit `0fb6f66` mitgibt. Nur wenn das Feld fehlt (aeltere
+     * Connect-Fassung im Feld, die es noch nicht kennt), faellt die Pruefung
+     * auf den Meldungstext zurueck (`_call` in
+     * `kasseneck-connect/lib/src/terminal/hps.dart` schrieb schon vor `0fb6f66`
+     * wortgleich `'Terminal meldet (HTTP ${response.statusCode}): ...'`).
+     *
+     * **Der Rueckfall ist eine Uebergangsloesung, kein Dauerzustand.** Sobald
+     * jede Kasse im Feld gegen einen Connect-Agenten mit `terminalHttpStatus`
+     * spricht, kann der Textabgleich entfallen — bis dahin bleibt er die
+     * einzige Absicherung fuer eine Installation, die noch nicht aktualisiert
+     * hat. Bricht auch das Textmuster (Formulierungsaenderung in Connect),
+     * faellt diese Erkennung auf `false` zurueck — die sichere Richtung: aus
+     * einem `409` wuerde dann `unresolved` statt des beweisbaren `declined`,
+     * niemals umgekehrt.
+     */
+    get isTerminalBusy(): boolean;
+}
+/**
+ * Connect selbst war nicht erreichbar, oder die Antwort hatte nicht die
+ * erwartete Form (kein JSON, keine `{ok, ...}`-Huelle, unerwarteter
+ * HTTP-Status ohne diese Huelle).
+ */
+export declare class HpsConnectTransportError extends HpsConnectException {
+    readonly name = "HpsConnectTransportError";
+    constructor(message: string);
+}
+/**
+ * Das Klaerbudget ist aufgebraucht, WAEHREND ein einzelner Abruf (Abbruch
+ * oder Statusabfrage) noch lief. Wird in `payments.ts` wie jeder andere
+ * Transportfehler behandelt — siehe `withinBudget`.
+ */
+export declare class HpsClarifyTimeoutError extends HpsConnectException {
+    readonly name = "HpsClarifyTimeoutError";
+    constructor(budgetMs: number);
+}

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

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HpsClarifyTimeoutError = exports.HpsConnectTransportError = exports.HpsConnectTerminalError = exports.PREFLIGHT_CONNECT_CODES = exports.HpsTransactionIdError = exports.HpsPreflightError = exports.HpsConnectException = void 0;
+const transaction_response_js_1 = require("./transaction-response.js");
+/**
+ * Fehlerarten auf dem Weg ueber **Kasseneck Connect** zum hobex-HPS-Terminal.
+ *
+ * Drei Arten, bewusst getrennt, weil `payments.ts` auf jede anders reagiert —
+ * das ist die wichtigste Unterscheidung in diesem ganzen Vorhaben:
+ *
+ * - [HpsPreflightError] — es ist NACHWEISLICH nichts gesendet worden. Entweder
+ *   die Kennung selbst war unbrauchbar (siehe `connect-client.ts`), oder
+ *   Connect hat die Anfrage VOR dem Terminal-Kontakt abgelehnt (falscher
+ *   Host, keine Kopplung, ...). Wird von `payments.ts` unveraendert
+ *   weitergeworfen, niemals in einen Ausgang uebersetzt — Zwilling von
+ *   Dart's `ArgumentError`-Sonderfall in `HpsPayments.pay()`.
+ * - [HpsConnectTerminalError] — die Anfrage GING RAUS (oder der Versuch dazu
+ *   scheiterte am Transport), aber es kam keine schluessige Antwort. Das
+ *   umfasst ausdruecklich auch [isTerminalBusy]: HTTP `409` ist die einzige
+ *   dieser Lagen, die als [isTerminalBusy] eine POSITIVE Aussage traegt,
+ *   siehe dort.
+ * - [HpsConnectTransportError] — Connect selbst war nicht erreichbar oder
+ *   antwortete nicht in der erwarteten Form (kein JSON, keine Huelle).
+ *
+ * Beide letzteren werden von `payments.ts` in die Klaerung (Abbruch + Polling)
+ * geschickt, NIE in `declined` uebersetzt — mit der einen, gemessenen
+ * Ausnahme [isTerminalBusy].
+ */
+class HpsConnectException extends Error {
+}
+exports.HpsConnectException = HpsConnectException;
+/**
+ * Nichts ist gesendet worden. `reason` ist deutscher Klartext, `connectCode`
+ * gesetzt, wenn die Ablehnung von Connect kam (statt von der lokalen
+ * Kennungspruefung).
+ */
+class HpsPreflightError extends HpsConnectException {
+    name = 'HpsPreflightError';
+    connectCode;
+    constructor(reason, connectCode) {
+        super(reason);
+        this.connectCode = connectCode;
+    }
+}
+exports.HpsPreflightError = HpsPreflightError;
+/**
+ * Die Transaktionskennung ist unbrauchbar (nicht rein numerisch, leer, oder
+ * laenger als 18 Stellen) — geprueft BEVOR irgendetwas an Connect geht, wie
+ * bei `HpsClient._checkTransactionId` im Dart-Zwilling.
+ *
+ * Eigene Klasse (statt nur [HpsPreflightError]) macht die Unterscheidung
+ * `instanceof`-pruefbar, ohne sich auf einen Text zu verlassen.
+ */
+class HpsTransactionIdError extends HpsPreflightError {
+    name = 'HpsTransactionIdError';
+    value;
+    constructor(value) {
+        super(`Transaktionskennung "${value}" ist unbrauchbar -- HPS erlaubt 1 bis 18 `
+            + 'Ziffern, rein numerisch');
+        this.value = value;
+    }
+}
+exports.HpsTransactionIdError = HpsTransactionIdError;
+/**
+ * Bekannte Connect-Fehlercodes, die VOR jedem Terminal-Kontakt entstehen (aus
+ * `kasseneck-connect/lib/src/api/{auth,responses,routes_terminal}.dart`):
+ * Middleware (Herkunft, Token, Pfad, Rumpfgroesse) oder die Feldpruefung in
+ * `_ziel`/`_handlePayment`/`_mitTransaktion` laufen alle, BEVOR die Bruecke
+ * `HpsBridge` das Terminal ueberhaupt anspricht.
+ *
+ * Bewusst eine Positivliste: nur ein hier benannter Code gilt als "beweisbar
+ * nichts gesendet". Ein Code, den diese Liste nicht kennt, wird in
+ * `connect-client.ts` NICHT als [HpsPreflightError] gelesen, sondern als
+ * [HpsConnectTerminalError] — die sichere Richtung, falls Connect einmal um
+ * einen Fehlercode erweitert wird, der doch am Terminal entsteht.
+ */
+exports.PREFLIGHT_CONNECT_CODES = new Set([
+    'bad_request',
+    'unauthorized',
+    'origin_forbidden',
+    'not_found',
+    'body_too_large',
+]);
+/**
+ * Die Anfrage ging (oder der Versuch dazu) in Richtung Terminal, aber es kam
+ * keine schluessige Antwort — Connect meldete `terminal_error`, `timeout`
+ * oder `terminal_offline` (`kasseneck-connect/lib/src/terminal/hps.dart`),
+ * oder einen Fehlercode, den dieses Paket nicht kennt.
+ */
+class HpsConnectTerminalError extends HpsConnectException {
+    name = 'HpsConnectTerminalError';
+    /** Fehlercode von Connect, z. B. `terminal_error`, `timeout`, `terminal_offline`. */
+    connectCode;
+    /**
+     * Der rohe HTTP-Status des Terminals, wenn Connect einen genannt hat
+     * (`error.detail.terminalHttpStatus`, seit `kasseneck-connect` Commit
+     * `0fb6f66`, "fix(terminal): den rohen HTTP-Status des Terminals mitgeben").
+     * `undefined` bei einem Transportfehler (Connect erfindet dort keinen) oder
+     * bei einer aelteren Connect-Fassung, die das Feld noch nicht sendet.
+     */
+    terminalHttpStatus;
+    constructor(connectCode, message, terminalHttpStatus) {
+        super(message);
+        this.connectCode = connectCode;
+        this.terminalHttpStatus = terminalHttpStatus;
+    }
+    /**
+     * `true`, wenn dies der gemessene "Terminal beschaeftigt"-Fall ist: das
+     * Terminal hat mit HTTP `409` geantwortet.
+     *
+     * Liest bevorzugt [terminalHttpStatus] — das strukturierte Feld, das
+     * Connect seit `0fb6f66` mitgibt. Nur wenn das Feld fehlt (aeltere
+     * Connect-Fassung im Feld, die es noch nicht kennt), faellt die Pruefung
+     * auf den Meldungstext zurueck (`_call` in
+     * `kasseneck-connect/lib/src/terminal/hps.dart` schrieb schon vor `0fb6f66`
+     * wortgleich `'Terminal meldet (HTTP ${response.statusCode}): ...'`).
+     *
+     * **Der Rueckfall ist eine Uebergangsloesung, kein Dauerzustand.** Sobald
+     * jede Kasse im Feld gegen einen Connect-Agenten mit `terminalHttpStatus`
+     * spricht, kann der Textabgleich entfallen — bis dahin bleibt er die
+     * einzige Absicherung fuer eine Installation, die noch nicht aktualisiert
+     * hat. Bricht auch das Textmuster (Formulierungsaenderung in Connect),
+     * faellt diese Erkennung auf `false` zurueck — die sichere Richtung: aus
+     * einem `409` wuerde dann `unresolved` statt des beweisbaren `declined`,
+     * niemals umgekehrt.
+     */
+    get isTerminalBusy() {
+        if (this.terminalHttpStatus !== undefined) {
+            return this.terminalHttpStatus === transaction_response_js_1.TERMINAL_BUSY_HTTP_STATUS;
+        }
+        return this.connectCode === 'terminal_error' && new RegExp(`\\(HTTP ${transaction_response_js_1.TERMINAL_BUSY_HTTP_STATUS}\\)`).test(this.message);
+    }
+}
+exports.HpsConnectTerminalError = HpsConnectTerminalError;
+/**
+ * Connect selbst war nicht erreichbar, oder die Antwort hatte nicht die
+ * erwartete Form (kein JSON, keine `{ok, ...}`-Huelle, unerwarteter
+ * HTTP-Status ohne diese Huelle).
+ */
+class HpsConnectTransportError extends HpsConnectException {
+    name = 'HpsConnectTransportError';
+    constructor(message) {
+        super(message);
+    }
+}
+exports.HpsConnectTransportError = HpsConnectTransportError;
+/**
+ * Das Klaerbudget ist aufgebraucht, WAEHREND ein einzelner Abruf (Abbruch
+ * oder Statusabfrage) noch lief. Wird in `payments.ts` wie jeder andere
+ * Transportfehler behandelt — siehe `withinBudget`.
+ */
+class HpsClarifyTimeoutError extends HpsConnectException {
+    name = 'HpsClarifyTimeoutError';
+    constructor(budgetMs) {
+        super(`Klaerbudget ueberschritten (${budgetMs} ms)`);
+    }
+}
+exports.HpsClarifyTimeoutError = HpsClarifyTimeoutError;

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

@@ -0,0 +1,22 @@
+/**
+ * Ereignisse der Klaerung — Zwilling von `HpsEventKind`/`HpsObserver`
+ * (`kasseneck_api/lib/src/hobex_hps/observer.dart`), hier nur fuer die
+ * Klaerungsphase in `payments.ts` (kein eigenes Ereignis je HTTP-Aufruf an
+ * Connect — die stehen bereits, mit Begruendung, in `HpsPaymentResult.steps`).
+ */
+export type HpsPaymentEventKind = 
+/** Der Ausgang ist nach der direkten Antwort offen, die Klaerung laeuft. */
+'resolving'
+/** Der Ausgang steht fest. */
+ | 'resolved'
+/** Ein Fehler beim Auswerten der Antwort, der KEIN erwarteter Connect-Fehler ist. */
+ | 'unexpectedError';
+/** Ein Ereignis der Klaerung. Bewusst schlank und ohne Kartendaten. */
+export interface HpsPaymentEvent {
+    readonly kind: HpsPaymentEventKind;
+    readonly message: string;
+    readonly transactionId: string;
+    readonly error?: unknown;
+}
+/** Empfaenger der Ereignisse — die App legt ihn typischerweise auf ihr Protokoll. */
+export type HpsPaymentObserver = (event: HpsPaymentEvent) => void;

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+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 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, 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 { hobexReceiptFromHps } from './receipt.js';