@kreiseck/kasseneck-api 0.6.45 → 0.6.49

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

@@ -0,0 +1,156 @@
+import { HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, PREFLIGHT_CONNECT_CODES, } from './errors.js';
+import { isValidHpsTransactionId } from './transaction-id.js';
+import { parseHpsTransactionResponse } from './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;
+export 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 HpsConnectTransportError(`Kasseneck Connect nicht erreichbar (${baseUrl}): ${grund}`);
+            }
+        }
+        finally {
+            clearTimeout(wecker);
+        }
+        let huelle;
+        try {
+            huelle = text.trim() === '' ? null : JSON.parse(text);
+        }
+        catch {
+            throw new HpsConnectTransportError(`Antwort von Kasseneck Connect ist kein JSON (HTTP ${antwort.status})`);
+        }
+        if (huelle === null || typeof huelle !== 'object' || !('ok' in huelle)) {
+            throw new 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 && PREFLIGHT_CONNECT_CODES.has(code)) {
+            // Siehe errors.ts: diese Codes entstehen laut `kasseneck-connect`
+            // ausnahmslos VOR jedem Terminal-Kontakt -- beweisbar nichts gesendet.
+            throw new 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 HpsConnectTerminalError(code ?? 'unbekannt', message, terminalHttpStatus);
+    }
+    function checkedTransactionId(value) {
+        if (!isValidHpsTransactionId(value)) {
+            throw new 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 parseHpsTransactionResponse(antwort['hps']);
+        },
+        async status(o) {
+            const transactionId = checkedTransactionId(o.transactionId);
+            const antwort = await rufen('/v1/terminal/status', { ...target(o), transactionId }, shortTimeoutMs);
+            return parseHpsTransactionResponse(antwort['hps']);
+        },
+        async abort(o) {
+            const transactionId = checkedTransactionId(o.transactionId);
+            const antwort = await rufen('/v1/terminal/abort', { ...target(o), transactionId }, shortTimeoutMs);
+            return 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 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 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/esm/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/esm/payments/hobex-hps/errors.js

@@ -0,0 +1,149 @@
+import { TERMINAL_BUSY_HTTP_STATUS } from './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].
+ */
+export 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 class HpsPreflightError extends HpsConnectException {
+    name = 'HpsPreflightError';
+    connectCode;
+    constructor(reason, connectCode) {
+        super(reason);
+        this.connectCode = connectCode;
+    }
+}
+/**
+ * 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 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;
+    }
+}
+/**
+ * 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 const 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.
+ */
+export 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 === TERMINAL_BUSY_HTTP_STATUS;
+        }
+        return this.connectCode === 'terminal_error' && new RegExp(`\\(HTTP ${TERMINAL_BUSY_HTTP_STATUS}\\)`).test(this.message);
+    }
+}
+/**
+ * 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 class HpsConnectTransportError extends HpsConnectException {
+    name = 'HpsConnectTransportError';
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * 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 class HpsClarifyTimeoutError extends HpsConnectException {
+    name = 'HpsClarifyTimeoutError';
+    constructor(budgetMs) {
+        super(`Klaerbudget ueberschritten (${budgetMs} ms)`);
+    }
+}

package/dist/esm/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/esm/payments/hobex-hps/events.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/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';

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

@@ -0,0 +1,26 @@
+/**
+ * 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 { createHpsConnectClient, } from './connect-client.js';
+export { HpsClarifyTimeoutError, HpsConnectException, HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, PREFLIGHT_CONNECT_CODES, } from './errors.js';
+export { mayRetrySafely, } from './outcome.js';
+export { createHpsPayments, } from './payments.js';
+export { MAX_TRANSACTION_ID_LENGTH, createHpsTransactionIdGenerator, isValidHpsTransactionId, newHpsTransactionId, } 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, } from './transaction-response.js';
+export { hobexReceiptFromHps } from './receipt.js';

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

@@ -0,0 +1,31 @@
+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 letzte Antwort des Terminals, sofern eine schluessige ankam. */
+    readonly response?: 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/esm/payments/hobex-hps/outcome.js

@@ -0,0 +1,4 @@
+/** Nur bei `'declined'` steht fest, dass nichts belastet wurde. */
+export function mayRetrySafely(result) {
+    return result.outcome === 'declined';
+}