@kreiseck/kasseneck-api 0.6.7

package/dist/esm/models/stripe-url-session.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Stripe-Zahlungslink-Sitzung — Zwilling von `StripeUrlSession` in
+ * kasseneck_api/lib/models/stripe_url_seesion.dart.
+ */
+export interface StripeUrlSession {
+    id: string;
+    url: string;
+    shortenUrl: string;
+    expiresAt: Date;
+}
+export interface StripeUrlSessionPayload {
+    id: string;
+    url: string;
+    shorten_payment_url: string;
+    expires_at: string;
+}
+export declare function toStripeUrlSessionPayload(session: StripeUrlSession): StripeUrlSessionPayload;
+export declare function fromStripeUrlSessionPayload(payload: StripeUrlSessionPayload): StripeUrlSession;

package/dist/esm/models/stripe-url-session.js

@@ -0,0 +1,16 @@
+export function toStripeUrlSessionPayload(session) {
+    return {
+        id: session.id,
+        url: session.url,
+        shorten_payment_url: session.shortenUrl,
+        expires_at: session.expiresAt.toISOString(),
+    };
+}
+export function fromStripeUrlSessionPayload(payload) {
+    return {
+        id: payload.id,
+        url: payload.url,
+        shortenUrl: payload.shorten_payment_url,
+        expiresAt: new Date(payload.expires_at),
+    };
+}

package/dist/esm/models/voucher.d.ts

@@ -0,0 +1,41 @@
+import { VoucherAction, VoucherType } from '../enums/index.js';
+/**
+ * Gutschein — Zwilling von `KeckVoucher` in
+ * kasseneck_api/lib/models/keck_voucher.dart.
+ *
+ * `valueCents` ist der Gutscheinwert in **Cent** (exakte Integer-Arithmetik).
+ *
+ * `action`/`type` sind schon im Dart-Vorbild reine Strings (keine
+ * Zusatzfelder) — beim Lesen bleibt ein unbekannter Wert deshalb ebenfalls
+ * einfach der rohe Nutzlast-String (siehe [readEnumKey]); ob er zu den
+ * bekannten Werten gehoert, entscheidet sich erst beim Schreiben.
+ */
+export interface Voucher {
+    name?: string;
+    code?: string;
+    action: VoucherAction | string;
+    type: VoucherType | string;
+    valueCents?: number;
+}
+/**
+ * Nutzlast: traegt **beide** Felder, `value` (Euro) und `valueCents` (Cent).
+ * Das Backend erwartet das Euro-Feld weiterhin (Altkompatibilitaet) — die
+ * Umwandlung passiert nur hier, an dieser einen Stelle.
+ */
+export interface VoucherPayload {
+    name: string | null;
+    code: string | null;
+    action: string;
+    type: string;
+    value: number | null;
+    valueCents: number | null;
+}
+export declare function toVoucherPayload(voucher: Voucher): VoucherPayload;
+/**
+ * Ist der Gutschein an das Backend sendbar? Zwilling von `KeckVoucher.isValid`
+ * im Flutter-Vorbild: Wert- und Promotionsgutscheine brauchen einen Wert,
+ * Promotionsgutscheine duerfen nur eingeloest (nicht verkauft) werden, und ein
+ * gesetzter Wert muss positiv sein.
+ */
+export declare function voucherIsValid(voucher: Voucher): boolean;
+export declare function fromVoucherPayload(payload: VoucherPayload): Voucher;

package/dist/esm/models/voucher.js

@@ -0,0 +1,51 @@
+import { VoucherAction, VoucherType } from '../enums/index.js';
+import { readEnumKey, requireEnumKey } from './enum-payload.js';
+export function toVoucherPayload(voucher) {
+    return {
+        name: voucher.name ?? null,
+        code: voucher.code ?? null,
+        // Schreibpfad bleibt streng: action/type sehen fuer bekannte und
+        // unbekannte Werte gleich aus (reine Strings) — erst der Lookup hier
+        // entscheidet, ob geschrieben werden darf.
+        action: requireEnumKey(VoucherAction, voucher.action, 'Gutschein-Aktion'),
+        type: requireEnumKey(VoucherType, voucher.type, 'Gutscheinart'),
+        // Euro-Feld nur fuer Altbestand-Konsumenten des Backends — siehe Kommentar oben.
+        value: voucher.valueCents == null ? null : voucher.valueCents / 100,
+        valueCents: voucher.valueCents ?? null,
+    };
+}
+/**
+ * Ist der Gutschein an das Backend sendbar? Zwilling von `KeckVoucher.isValid`
+ * im Flutter-Vorbild: Wert- und Promotionsgutscheine brauchen einen Wert,
+ * Promotionsgutscheine duerfen nur eingeloest (nicht verkauft) werden, und ein
+ * gesetzter Wert muss positiv sein.
+ */
+export function voucherIsValid(voucher) {
+    if (voucher.type === VoucherType.value && voucher.valueCents == null) {
+        return false;
+    }
+    if (voucher.type === VoucherType.promo && voucher.action !== VoucherAction.redeem) {
+        return false;
+    }
+    if (voucher.type === VoucherType.promo && voucher.valueCents == null) {
+        return false;
+    }
+    if (voucher.valueCents != null && voucher.valueCents <= 0) {
+        return false;
+    }
+    return true;
+}
+export function fromVoucherPayload(payload) {
+    const valueCents = payload.valueCents != null
+        ? payload.valueCents
+        : payload.value != null
+            ? Math.round(payload.value * 100)
+            : undefined;
+    return {
+        name: payload.name ?? undefined,
+        code: payload.code ?? undefined,
+        action: readEnumKey(VoucherAction, payload.action),
+        type: readEnumKey(VoucherType, payload.type),
+        valueCents,
+    };
+}

package/dist/esm/money.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Die Grenze zwischen Euro und Cent — an genau einer Stelle.
+ *
+ * Dieses Paket rechnet ausnahmslos in ganzen Cent (siehe README). Euro treten
+ * nur dort auf, wo eine fremde Schnittstelle sie verlangt oder liefert: die
+ * Belegliste des Backends sendet `total`/`umsatz` in Euro, das Hobex-Terminal
+ * nimmt `amount`/`tip` in Euro entgegen. Beide Richtungen stehen hier, damit
+ * die Umrechnung nicht in jeder Datei erneut auftaucht — und damit die
+ * Rundungsregel nur einmal entschieden ist.
+ */
+/** Cent -> Euro, fuer die Schnittstellen, die Euro verlangen. */
+export declare function centsToEuro(cents: number): number;
+/**
+ * Euro -> ganze Cent, fuer Betraege, die aus einer fremden Antwort kommen.
+ *
+ * Unbrauchbare Werte (fehlend, `null`, keine Zahl, NaN, Unendlich) ergeben 0:
+ * eine Belegliste darf nicht daran scheitern, dass ein einzelner Betrag fehlt.
+ *
+ * Gerundet wird **von der Null weg**, nicht mit `Math.round` — das schoebe
+ * `.5` immer Richtung +unendlich, und dann heben sich ein Beleg und sein
+ * Storno im Cent nicht mehr auf (dieselbe Regel wie in receipt/layout.ts).
+ */
+export declare function euroToCents(euro: unknown): number;

package/dist/esm/money.js

@@ -0,0 +1,31 @@
+/**
+ * Die Grenze zwischen Euro und Cent — an genau einer Stelle.
+ *
+ * Dieses Paket rechnet ausnahmslos in ganzen Cent (siehe README). Euro treten
+ * nur dort auf, wo eine fremde Schnittstelle sie verlangt oder liefert: die
+ * Belegliste des Backends sendet `total`/`umsatz` in Euro, das Hobex-Terminal
+ * nimmt `amount`/`tip` in Euro entgegen. Beide Richtungen stehen hier, damit
+ * die Umrechnung nicht in jeder Datei erneut auftaucht — und damit die
+ * Rundungsregel nur einmal entschieden ist.
+ */
+/** Cent -> Euro, fuer die Schnittstellen, die Euro verlangen. */
+export function centsToEuro(cents) {
+    return cents / 100;
+}
+/**
+ * Euro -> ganze Cent, fuer Betraege, die aus einer fremden Antwort kommen.
+ *
+ * Unbrauchbare Werte (fehlend, `null`, keine Zahl, NaN, Unendlich) ergeben 0:
+ * eine Belegliste darf nicht daran scheitern, dass ein einzelner Betrag fehlt.
+ *
+ * Gerundet wird **von der Null weg**, nicht mit `Math.round` — das schoebe
+ * `.5` immer Richtung +unendlich, und dann heben sich ein Beleg und sein
+ * Storno im Cent nicht mehr auf (dieselbe Regel wie in receipt/layout.ts).
+ */
+export function euroToCents(euro) {
+    if (typeof euro !== 'number' || !Number.isFinite(euro)) {
+        return 0;
+    }
+    const cents = Math.round(Math.abs(euro) * 100);
+    return euro < 0 ? -cents : cents;
+}

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

@@ -0,0 +1,87 @@
+import { type HobexReceipt } from '../models/index.js';
+import type { KasseneckTransport } from '../client/transport.js';
+/**
+ * Cent -> Euro. **Die einzige Umrechnungsstelle dieses Moduls.** Betraege
+ * werden im ganzen Paket in Cent gefuehrt (exakte Ganzzahl-Arithmetik); die
+ * Hobex-Schnittstelle erwartet dagegen Euro als Gleitkommazahl (`amount`,
+ * `tip`), und das Backend reicht sie unveraendert an Hobex weiter. Das
+ * Gegenstueck fuer die Antwortrichtung steht in models/hobex-receipt.ts.
+ *
+ * **Geerbte Ungenauigkeit, hier nicht behebbar:** das Backend addiert die
+ * beiden Euro-Werte serverseitig (`check.params.amount + check.params.tip`,
+ * functions/payment-endpoints.js) — aus 10,10 EUR und 0,20 EUR wird dort
+ * `10.299999999999999`. Jede Rundung auf dieser Seite wuerde daran nichts
+ * aendern, weil die Addition erst danach passiert; die saubere Loesung waere
+ * ein Cent-Feld am Backend.
+ */
+export interface HobexPayOptions {
+    /** Kennung der Zahlung — siehe [newHobexTransactionId]. */
+    transactionId: string;
+    /** Zu belastender Betrag in **Cent** (ohne Trinkgeld). */
+    amountCents: number;
+    /** Trinkgeld in **Cent**; Hobex belastet Betrag + Trinkgeld in einem. */
+    tipCents?: number;
+    /** Freier Verwendungszweck, den Hobex mitfuehrt (z. B. Tischnummer). */
+    reference?: string;
+}
+export interface HobexRefundOptions {
+    /** Kennung der zu erstattenden Zahlung. */
+    transactionId: string;
+    /** Zu erstattender Betrag in **Cent** (ohne Trinkgeld). */
+    amountCents: number;
+    /** Zu erstattendes Trinkgeld in **Cent**. */
+    tipCents?: number;
+}
+/** Zeit- und Zufallsquelle von [newHobexTransactionId] — fuer Tests einspeisbar. */
+export interface HobexTransactionIdOptions {
+    /** Zeitpunkt der Kennung; ohne Angabe jetzt. */
+    now?: Date;
+    /** Zufallsquelle in `[0, 1)` wie `Math.random`; ohne Angabe `Math.random`. */
+    random?: () => number;
+}
+/**
+ * Belastet eine Karte ueber die **Hobex-Cloud-API** und liefert den
+ * entstandenen [HobexReceipt].
+ *
+ * **Der Endpunkt heisst `hobexPayApi`** — mit Suffix; ohne ihn gibt es ihn
+ * nicht.
+ */
+export declare function hobexPay(rufen: KasseneckTransport, options: HobexPayOptions): Promise<HobexReceipt>;
+/**
+ * Erstattet eine zuvor ueber die Hobex-Cloud getaetigte Zahlung. Das Backend
+ * storniert zuerst (Void, solange der Tagesabschluss aussteht) und erstattet
+ * erst danach.
+ *
+ * **Ohne Rueckgabewert, mit Absicht.** Das Vorbild liefert
+ * `resJson['status'] == 'success'`; in diesem Paket wirft die Fehlerhuelle
+ * schon im Transport, sobald der Status nicht ausdruecklich Erfolg ist. Ein
+ * Wahrheitswert waere hier also immer `true` — eine Luege ueber den
+ * Informationsgehalt, an der ein Aufrufer ein `if` aufhaengt, das nie greift.
+ * Misserfolg kommt als geworfener Fehler.
+ *
+ * **Der Endpunkt heisst `hobexRefundApi`** — mit Suffix.
+ */
+export declare function hobexRefund(rufen: KasseneckTransport, options: HobexRefundOptions): Promise<void>;
+/**
+ * Erzeugt eine neue Hobex-Transaktionskennung: 19 Ziffern aus Zeitanteil und
+ * Zufall (Zwilling von `newHobexTransactionId` im Vorbild, Zeile 522).
+ *
+ * Zwei bewusste Abweichungen:
+ *
+ * 1. **Wiener Wanduhrzeit statt Geraetezeit.** Das Vorbild nimmt
+ *    `DateTime.now()` in der Zeitzone des Geraets; damit haetten zwei Kassen
+ *    desselben Betriebs in verschiedenen Zeitzonen Kennungen, die sich um
+ *    Stunden unterscheiden, und der Tageswechsel in der Kennung faende nicht
+ *    zum Geschaeftstag statt. Fachlich ist Wien die Zeitzone (siehe
+ *    vienna-time.ts) — und eine Browser-Kasse laeuft in der Zeitzone des Gasts,
+ *    nicht des Betriebs.
+ * 2. **Millisekunden statt Mikrosekunden.** JavaScript hat keine
+ *    Mikrosekunden-Uhr. Das Vorbild fuellt mit sechs Bruchteilsstellen auf und
+ *    haengt zwei Zufallsziffern an, von denen die Laengenbegrenzung eine wieder
+ *    abschneidet; hier stehen drei Bruchteilsstellen und vier Zufallsziffern.
+ *    Laenge und Form (nur Ziffern, 19 Stellen, `JJMMTThhmmss` voran) bleiben
+ *    gleich.
+ *
+ * Zeit- und Zufallsquelle sind einspeisbar, damit die Kennung pruefbar ist.
+ */
+export declare function newHobexTransactionId(options?: HobexTransactionIdOptions): string;

package/dist/esm/payments/hobex.js

@@ -0,0 +1,162 @@
+import { fromHobexReceiptPayload } from '../models/index.js';
+import { KasseneckValidationError } from '../client/errors.js';
+import { toViennaWallClock } from '../vienna-time.js';
+import { centsToEuro } from '../money.js';
+/**
+ * Hobex-Kartenzahlung ueber die **Cloud-API** — Zwilling der Hobex-Aufrufe in
+ * kasseneck_api/lib/kasseneck_api.dart (Zeilen 491-526).
+ *
+ * Der Ablauf hat zwei Schritte: eine Kennung erzeugen ([newHobexTransactionId])
+ * und damit belasten ([hobexPay]). Die Kennung ist der Faden, an dem das
+ * Backend eine haengende Zahlung wiederfindet (`getHobexStatusWithTimeout`,
+ * functions/payment-endpoints.js) — sie ist deshalb kein Schmuck, sondern die
+ * Absicherung gegen eine doppelte Belastung.
+ *
+ * **Nur der Cloud-Weg ist hier drin, und das bleibt so.** Hobex **HPS** ist ein
+ * physisches Terminal, mit dem die Kasse **lokal ueber TCP** spricht; **myPOS**
+ * und **SumUp** sind **Android-SDKs**. Ein Browser hat weder rohe TCP-Sockets
+ * noch eine Android-Laufzeit — das ist keine fehlende Umsetzung und kein
+ * Buendler-Problem, sondern eine Grenze der Umgebung. Wer diese drei Wege
+ * braucht, braucht die Flutter-App, nicht dieses Paket.
+ *
+ * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** Keiner der
+ * beiden Endpunkte dieser Datei setzt `allowRegisterUser`; beide laufen nur
+ * mit `apiKeyAuth`. Ausgefuehrt steht das in payments/index.ts — an einer
+ * Stelle statt an dreien.
+ */
+/** Endpunktnamen aus dem Vorbild — beide mit Suffix `Api`. */
+const ENDPUNKT_PAY = 'hobexPayApi';
+const ENDPUNKT_REFUND = 'hobexRefundApi';
+/**
+ * Belastet eine Karte ueber die **Hobex-Cloud-API** und liefert den
+ * entstandenen [HobexReceipt].
+ *
+ * **Der Endpunkt heisst `hobexPayApi`** — mit Suffix; ohne ihn gibt es ihn
+ * nicht.
+ */
+export async function hobexPay(rufen, options) {
+    const params = zahlungsNutzlast(ENDPUNKT_PAY, options);
+    // `reference` steht im Vorbild **unbedingt** in der Nutzlast: ohne Angabe
+    // geht sie als null raus, nicht gar nicht. Der Transport wirft nur
+    // `undefined` weg, `null` bleibt erhalten — genau diese Unterscheidung.
+    params['reference'] = options.reference ?? null;
+    return belegAusNutzlast(await rufen(ENDPUNKT_PAY, params));
+}
+/**
+ * Erstattet eine zuvor ueber die Hobex-Cloud getaetigte Zahlung. Das Backend
+ * storniert zuerst (Void, solange der Tagesabschluss aussteht) und erstattet
+ * erst danach.
+ *
+ * **Ohne Rueckgabewert, mit Absicht.** Das Vorbild liefert
+ * `resJson['status'] == 'success'`; in diesem Paket wirft die Fehlerhuelle
+ * schon im Transport, sobald der Status nicht ausdruecklich Erfolg ist. Ein
+ * Wahrheitswert waere hier also immer `true` — eine Luege ueber den
+ * Informationsgehalt, an der ein Aufrufer ein `if` aufhaengt, das nie greift.
+ * Misserfolg kommt als geworfener Fehler.
+ *
+ * **Der Endpunkt heisst `hobexRefundApi`** — mit Suffix.
+ */
+export async function hobexRefund(rufen, options) {
+    // Anders als die Zahlung sendet der Refund im Vorbild **keine** reference.
+    await rufen(ENDPUNKT_REFUND, zahlungsNutzlast(ENDPUNKT_REFUND, options));
+}
+/**
+ * Erzeugt eine neue Hobex-Transaktionskennung: 19 Ziffern aus Zeitanteil und
+ * Zufall (Zwilling von `newHobexTransactionId` im Vorbild, Zeile 522).
+ *
+ * Zwei bewusste Abweichungen:
+ *
+ * 1. **Wiener Wanduhrzeit statt Geraetezeit.** Das Vorbild nimmt
+ *    `DateTime.now()` in der Zeitzone des Geraets; damit haetten zwei Kassen
+ *    desselben Betriebs in verschiedenen Zeitzonen Kennungen, die sich um
+ *    Stunden unterscheiden, und der Tageswechsel in der Kennung faende nicht
+ *    zum Geschaeftstag statt. Fachlich ist Wien die Zeitzone (siehe
+ *    vienna-time.ts) — und eine Browser-Kasse laeuft in der Zeitzone des Gasts,
+ *    nicht des Betriebs.
+ * 2. **Millisekunden statt Mikrosekunden.** JavaScript hat keine
+ *    Mikrosekunden-Uhr. Das Vorbild fuellt mit sechs Bruchteilsstellen auf und
+ *    haengt zwei Zufallsziffern an, von denen die Laengenbegrenzung eine wieder
+ *    abschneidet; hier stehen drei Bruchteilsstellen und vier Zufallsziffern.
+ *    Laenge und Form (nur Ziffern, 19 Stellen, `JJMMTThhmmss` voran) bleiben
+ *    gleich.
+ *
+ * Zeit- und Zufallsquelle sind einspeisbar, damit die Kennung pruefbar ist.
+ */
+export function newHobexTransactionId(options = {}) {
+    const wand = toViennaWallClock(options.now ?? new Date());
+    const zufall = options.random ?? Math.random;
+    const zeitanteil = zweistellig(wand.year % 100) +
+        zweistellig(wand.month) +
+        zweistellig(wand.day) +
+        zweistellig(wand.hour) +
+        zweistellig(wand.minute) +
+        zweistellig(wand.second) +
+        String(wand.millisecond).padStart(3, '0');
+    // Vier Ziffern, immer vierstellig: eine kuerzere Zahl wuerde die Kennung
+    // verkuerzen und damit ihre Form verlassen. Der Wert wird auf [0, 1)
+    // begrenzt — eine fremde Zufallsquelle koennte 1 liefern.
+    const zufallsanteil = String(Math.floor(begrenzt(zufall()) * 10_000)).padStart(4, '0');
+    return zeitanteil + zufallsanteil;
+}
+/**
+ * Gemeinsame Nutzlast beider Hobex-Aufrufe: Kennung und die beiden Betraege in
+ * Euro. Prueft, bevor irgendetwas rausgeht — hier bewegt sich Geld auf einer
+ * fremden Karte, und ein NaN-Betrag oder eine leere Kennung ist an einem
+ * Zahlungsterminal nichts, was man dem Backend zum Ausprobieren schickt.
+ */
+function zahlungsNutzlast(functionName, options) {
+    if (typeof options.transactionId !== 'string' || !options.transactionId.trim()) {
+        throw eingabefehler(functionName, 'transactionId fehlt');
+    }
+    const amountCents = gepruefterBetrag(functionName, options.amountCents, 'amountCents', 1);
+    const tipCents = gepruefterBetrag(functionName, options.tipCents ?? 0, 'tipCents', 0);
+    return {
+        transactionId: options.transactionId,
+        // Euro-Umrechnung genau hier, an der Hobex-Grenze.
+        amount: centsToEuro(amountCents),
+        tip: centsToEuro(tipCents),
+    };
+}
+/**
+ * Ganzzahliger Cent-Betrag ab [mindestens]. `Number.isInteger` faengt NaN,
+ * Unendlich und Bruchteils-Cent in einem — ein halber Cent ergibt bei der
+ * Euro-Umrechnung eine dritte Nachkommastelle, die Hobex nicht kennt.
+ */
+function gepruefterBetrag(functionName, cents, feld, mindestens) {
+    if (!Number.isInteger(cents)) {
+        throw eingabefehler(functionName, `${feld} muss eine ganze Zahl in Cent sein.`);
+    }
+    if (cents < mindestens) {
+        throw eingabefehler(functionName, `${feld} muss mindestens ${mindestens} Cent betragen.`);
+    }
+    return cents;
+}
+/**
+ * Hobex-Beleg aus der Antwort lesen. Geprueft werden die beiden Felder, ohne
+ * die der Beleg nichts wert ist: die Kennung der Zahlung und der Zeitstempel
+ * (an ihm scheitert die Lesart des Modells sonst mit einem nackten TypeError,
+ * weil sie ihn zerlegt). Die uebrigen Felder bleiben so tolerant wie im
+ * Vorbild — ein Beleg, dem Hobex den Kartenaussteller schuldig bleibt, ist
+ * trotzdem eine erfolgte Zahlung.
+ */
+function belegAusNutzlast(daten) {
+    const roh = daten;
+    if (roh == null ||
+        typeof roh !== 'object' ||
+        typeof roh.transactionId !== 'string' ||
+        typeof roh.transactionDate !== 'string') {
+        throw antwortfehler(ENDPUNKT_PAY, 'Antwort enthaelt keinen Hobex-Beleg');
+    }
+    return fromHobexReceiptPayload(roh);
+}
+const zweistellig = (wert) => String(wert).padStart(2, '0');
+/** Auf `[0, 1)` begrenzen — eine fremde Zufallsquelle haelt sich nicht daran. */
+const begrenzt = (wert) => (Number.isFinite(wert) ? Math.min(Math.max(wert, 0), 0.999_999_9) : 0);
+/** Fehler in der Eingabe des Aufrufers — es geht keine Anfrage raus. */
+function eingabefehler(functionName, grund) {
+    return new KasseneckValidationError(functionName, grund, 'request');
+}
+/** Die Antwort meldete Erfolg, trug aber nicht, was der Aufruf zusagt. */
+function antwortfehler(functionName, grund) {
+    return new KasseneckValidationError(functionName, grund, 'response');
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Unterpfad `@kreiseck/kasseneck-api/payments` — die Zahlungswege, die ein
+ * Browser oder ein Node-Prozess wirklich gehen kann: **Stripe-Zahlungslinks**
+ * (Fernzahlung per Link/QR-Code) und die **Hobex-Cloud-API** (Kartenzahlung
+ * ueber ein bei Hobex registriertes Terminal, gesteuert ueber das Netz).
+ *
+ * **Was hier bewusst fehlt — und warum es auch nicht nachgeruestet wird:**
+ *
+ * - **Hobex HPS** spricht **lokal ueber TCP** mit einem angeschlossenen
+ *   Terminal (roher Socket auf eine Geraete-IP im selben Netz).
+ * - **myPOS** und **SumUp** sind **Android-SDKs**; sie laufen als
+ *   Bibliothek in einer Android-App und reden ueber Bluetooth bzw. das
+ *   Hersteller-Geraet mit dem Terminal.
+ *
+ * Ein Browser hat weder rohe TCP-Sockets noch eine Android-Laufzeit. Das ist
+ * keine Luecke in diesem Paket und auch nichts, was ein anderer Buendler,
+ * ein Polyfill oder eine WebAssembly-Schicht aufloest — es ist eine Grenze der
+ * Umgebung. Diese drei Wege gibt es im Flutter-Paket `kasseneck_api`, und dort
+ * bleiben sie.
+ *
+ * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** **Keiner** der
+ * vier Zahlungs-Endpunkte setzt `allowRegisterUser`; sie laufen alle ueber
+ * `checkRequest(req, 'user', …)` und damit nur mit `apiKeyAuth`. Dieses Paket
+ * bildet das **nicht** nach — wer darf, entscheidet allein das Backend. Der
+ * Hinweis steht **hier** und gilt fuer beide Dateien dieses Unterpfads.
+ *
+ * Welche **anderen** Endpunkte den Weg offen haben, steht bewusst nirgends in
+ * diesem Paket: eine abgeschriebene Liste veraltet still, und sie hat hier
+ * nichts zu entscheiden.
+ */
+export { StripeLinkMode, type StripeLinkModeKey } from '../enums/index.js';
+export { type CreateStripeLinkOptions, type StripeCaptureResult, createStripeLink, stripeCaptureIntent, } from './stripe.js';
+export { type HobexPayOptions, type HobexRefundOptions, type HobexTransactionIdOptions, hobexPay, hobexRefund, newHobexTransactionId, } from './hobex.js';

package/dist/esm/payments/index.js

@@ -0,0 +1,33 @@
+/**
+ * Unterpfad `@kreiseck/kasseneck-api/payments` — die Zahlungswege, die ein
+ * Browser oder ein Node-Prozess wirklich gehen kann: **Stripe-Zahlungslinks**
+ * (Fernzahlung per Link/QR-Code) und die **Hobex-Cloud-API** (Kartenzahlung
+ * ueber ein bei Hobex registriertes Terminal, gesteuert ueber das Netz).
+ *
+ * **Was hier bewusst fehlt — und warum es auch nicht nachgeruestet wird:**
+ *
+ * - **Hobex HPS** spricht **lokal ueber TCP** mit einem angeschlossenen
+ *   Terminal (roher Socket auf eine Geraete-IP im selben Netz).
+ * - **myPOS** und **SumUp** sind **Android-SDKs**; sie laufen als
+ *   Bibliothek in einer Android-App und reden ueber Bluetooth bzw. das
+ *   Hersteller-Geraet mit dem Terminal.
+ *
+ * Ein Browser hat weder rohe TCP-Sockets noch eine Android-Laufzeit. Das ist
+ * keine Luecke in diesem Paket und auch nichts, was ein anderer Buendler,
+ * ein Polyfill oder eine WebAssembly-Schicht aufloest — es ist eine Grenze der
+ * Umgebung. Diese drei Wege gibt es im Flutter-Paket `kasseneck_api`, und dort
+ * bleiben sie.
+ *
+ * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** **Keiner** der
+ * vier Zahlungs-Endpunkte setzt `allowRegisterUser`; sie laufen alle ueber
+ * `checkRequest(req, 'user', …)` und damit nur mit `apiKeyAuth`. Dieses Paket
+ * bildet das **nicht** nach — wer darf, entscheidet allein das Backend. Der
+ * Hinweis steht **hier** und gilt fuer beide Dateien dieses Unterpfads.
+ *
+ * Welche **anderen** Endpunkte den Weg offen haben, steht bewusst nirgends in
+ * diesem Paket: eine abgeschriebene Liste veraltet still, und sie hat hier
+ * nichts zu entscheiden.
+ */
+export { StripeLinkMode } from '../enums/index.js';
+export { createStripeLink, stripeCaptureIntent, } from './stripe.js';
+export { hobexPay, hobexRefund, newHobexTransactionId, } from './hobex.js';

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

@@ -0,0 +1,61 @@
+import { StripeLinkMode, type StripeLinkModeKey } from '../enums/index.js';
+import { type ReceiptItem, type StripeUrlSession } from '../models/index.js';
+import type { KasseneckTransport } from '../client/transport.js';
+export interface CreateStripeLinkOptions {
+    /** Positionen des Zahlungslinks; mindestens eine, alle gueltig. */
+    items: ReceiptItem[];
+    /** Soll das Backend nach bezahltem Link selbsttaetig einen Beleg erzeugen? */
+    createReceiptAfterPayment: boolean;
+    /** Sofort einziehen (`payment`) oder nur reservieren (`authorization`). */
+    mode: StripeLinkMode | StripeLinkModeKey;
+    /** Eigener Bezeichner fuer den Zahlungs-Webhook des Aufrufers. */
+    webhookId?: string;
+    /** Telefonnummer des Gasts (landet in den Stripe-Metadaten). */
+    customerPhone?: string;
+    /** E-Mail des Gasts (Stripe schickt die Zahlungsbestaetigung dorthin). */
+    customerEmail?: string;
+}
+/**
+ * Ergebnis von [stripeCaptureIntent] — das eingezogene Zahlungsversprechen
+ * (Stripe PaymentIntent), **nicht** noch einmal die Zahlungslink-Sitzung.
+ *
+ * Das ist eine bewusste Abweichung vom Dart-Vorbild: dort steht
+ * `StripeUrlSession.fromJson(resJson['data'])`, das Backend antwortet an dieser
+ * Stelle aber mit `{id, status, amount_received, currency}` (successResponse in
+ * functions/payment-endpoints.js). Weder `url` noch `shorten_payment_url` noch
+ * `expires_at` sind darin — die Sitzungs-Lesart kann hier gar nicht gelingen.
+ */
+export interface StripeCaptureResult {
+    /** Bezeichner des PaymentIntent (`pi_…`), nicht der der Sitzung (`cs_…`). */
+    id: string;
+    /** Stripe-Status des Einzugs, z. B. `succeeded`. */
+    status: string;
+    /**
+     * Tatsaechlich eingezogener Betrag in Cent. Stripe fuehrt Betraege in der
+     * kleinsten Waehrungseinheit; der Name unterstellt damit eine
+     * zweistellige Waehrung. Fuer diese Anlage stimmt das — das Backend legt
+     * `currency: 'eur'` fest (functions/payment-endpoints.js). Bei einer
+     * nullstelligen Waehrung (JPY) waere „Cent" der falsche Name; dann gehoert
+     * die Einheit aus `currency` abgeleitet und nicht in den Feldnamen.
+     */
+    amountReceivedCents: number;
+    /** Waehrungscode, wie Stripe ihn fuehrt (klein geschrieben, z. B. `eur`). */
+    currency: string;
+}
+/**
+ * Erzeugt einen Stripe-Zahlungslink fuer [items] (Fernzahlung: Link per
+ * Nachricht, QR-Code oder Kurzlink).
+ *
+ * **Der Endpunkt heisst `createPaymentLinkStripe`**, nicht wie diese Funktion —
+ * Methodenname und Endpunktname fallen wie schon beim Monatsbericht
+ * auseinander (siehe client/reports.ts).
+ */
+export declare function createStripeLink(rufen: KasseneckTransport, options: CreateStripeLinkOptions): Promise<StripeUrlSession>;
+/**
+ * Zieht die zuvor nur reservierte Zahlung einer `authorization`-Sitzung ein.
+ *
+ * **Der Parameter heisst `stripe_sessions_id`** — mit "sessions" im Plural, so
+ * das Vorbild und so das Backend. Der naheliegende Singular waere ein fehlender
+ * Pflichtparameter.
+ */
+export declare function stripeCaptureIntent(rufen: KasseneckTransport, stripeSessionId: string): Promise<StripeCaptureResult>;