@kreiseck/kasseneck-api 0.6.7

package/dist/esm/payments/stripe.js

@@ -0,0 +1,153 @@
+import { StripeLinkMode } from '../enums/index.js';
+import { fromStripeUrlSessionPayload, toReceiptItemPayload, receiptItemIsValid, } from '../models/index.js';
+import { KasseneckValidationError } from '../client/errors.js';
+/**
+ * Stripe-Zahlungslinks — Zwilling der Stripe-Aufrufe in
+ * kasseneck_api/lib/kasseneck_api.dart (Zeilen 443-484).
+ *
+ * Zwei Aufrufe: [createStripeLink] erzeugt eine Checkout-Sitzung samt Kurzlink
+ * (`pay.kasseneck.at/…`), den der Gast oeffnet; [stripeCaptureIntent] zieht die
+ * zuvor nur reservierte Zahlung eines `authorization`-Links spaeter ein.
+ *
+ * **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.
+ */
+/** Endpunktname aus dem Vorbild — **nicht** `createStripeLink`. */
+const ENDPUNKT_LINK = 'createPaymentLinkStripe';
+const ENDPUNKT_CAPTURE = 'stripeCaptureIntent';
+/**
+ * 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 async function createStripeLink(rufen, options) {
+    const { items } = options;
+    // Vor dem Senden pruefen: ein Zahlungslink ist zwar folgenlos wiederholbar,
+    // eine abgewiesene Anfrage aber eine unnoetige Runde ueber das Netz — und der
+    // Backend-Fehlertext nennt den Grund weit weniger genau als diese Pruefung.
+    if (!Array.isArray(items) || items.length === 0) {
+        throw eingabefehler(ENDPUNKT_LINK, 'Positionen sind Pflicht und duerfen nicht leer sein.');
+    }
+    if (items.some((item) => !receiptItemIsValid(item))) {
+        throw eingabefehler(ENDPUNKT_LINK, 'Ungueltige Position uebergeben.');
+    }
+    const params = {
+        items: positionsNutzlast(items),
+        createReceiptAfterPayment: options.createReceiptAfterPayment,
+        // Im Vorbild `mode.name`; Schluessel und Wert sind hier identisch.
+        mode: gepruefterModus(options.mode),
+    };
+    // Die drei uebrigen Felder stehen im Vorbild unter `if (… != null)` — ohne
+    // Angabe geht kein leeres Feld raus.
+    if (options.webhookId != null) {
+        params['webhookId'] = options.webhookId;
+    }
+    // **Abweichung vom Vorbild, mit Absicht:** Dart sendet `customerPhone`/
+    // `customerEmail` in camelCase. Das Backend nimmt die beiden Felder aber
+    // ausschliesslich als `customer_phone`/`customer_email` entgegen (so stehen
+    // sie in den optionalParams von `createPaymentLinkStripe`, und nur so werden
+    // sie ausgewertet), und unbekannte Parameter weist `checkRequest` nicht ab —
+    // sie fallen still unter den Tisch. Wer die camelCase-Namen uebernaehme,
+    // gaebe dem Aufrufer zwei Felder, die nachweislich nichts bewirken.
+    if (options.customerPhone != null) {
+        params['customer_phone'] = options.customerPhone;
+    }
+    if (options.customerEmail != null) {
+        params['customer_email'] = options.customerEmail;
+    }
+    return sitzungAusNutzlast(await rufen(ENDPUNKT_LINK, params));
+}
+/**
+ * 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 async function stripeCaptureIntent(rufen, stripeSessionId) {
+    if (typeof stripeSessionId !== 'string' || !stripeSessionId.trim()) {
+        throw eingabefehler(ENDPUNKT_CAPTURE, 'stripeSessionId fehlt');
+    }
+    const daten = await rufen(ENDPUNKT_CAPTURE, { stripe_sessions_id: stripeSessionId });
+    return einzugAusNutzlast(daten);
+}
+/**
+ * Positionen in ihre Nutzlast wandeln und dabei die strenge Schreibpfad-
+ * Pruefung des Modells abfangen (unbekannter Steuersatz). Das Modell wirft dort
+ * ein nacktes `Error`; aus einem Endpunkt-Aufruf soll nur die Fehler-Union
+ * dieses Pakets herauskommen (dasselbe Vorgehen wie in client/receipts.ts).
+ */
+function positionsNutzlast(items) {
+    try {
+        return items.map(toReceiptItemPayload);
+    }
+    catch (ursache) {
+        throw eingabefehler(ENDPUNKT_LINK, ursache instanceof Error ? ursache.message : 'Ungueltige Nutzlast uebergeben.');
+    }
+}
+/**
+ * Modus aufloesen. Bleibt streng: der Modus kommt vom Aufrufer, und das Backend
+ * kennt genau zwei Werte — ein dritter waere ein Programmierfehler, der sonst
+ * still als `payment` durchginge (das Backend setzt `capture_method: 'manual'`
+ * nur bei genau 'authorization').
+ */
+function gepruefterModus(wert) {
+    if (!Object.prototype.hasOwnProperty.call(StripeLinkMode, wert)) {
+        throw eingabefehler(ENDPUNKT_LINK, `Stripe-Link-Modus: unbekannter Wert "${String(wert)}"`);
+    }
+    return StripeLinkMode[wert];
+}
+/**
+ * Zahlungslink-Sitzung aus der Antwort lesen. Alle vier Felder muessen da sein:
+ * eine Sitzung ohne `url` ist kein Zahlungslink, und ein unlesbares Ablaufdatum
+ * wuerde als `Invalid Date` weiterwandern und erst beim Anzeigen auffallen.
+ */
+function sitzungAusNutzlast(daten) {
+    const roh = daten;
+    if (roh == null ||
+        typeof roh !== 'object' ||
+        typeof roh.id !== 'string' ||
+        typeof roh.url !== 'string' ||
+        typeof roh.shorten_payment_url !== 'string' ||
+        typeof roh.expires_at !== 'string') {
+        throw antwortfehler(ENDPUNKT_LINK, 'Antwort enthaelt keine Zahlungslink-Sitzung');
+    }
+    const sitzung = fromStripeUrlSessionPayload(roh);
+    if (Number.isNaN(sitzung.expiresAt.getTime())) {
+        throw antwortfehler(ENDPUNKT_LINK, 'Antwort enthaelt kein lesbares Ablaufdatum');
+    }
+    return sitzung;
+}
+/** Ergebnis des Einzugs aus der Antwort lesen (Felder siehe [StripeCaptureResult]). */
+function einzugAusNutzlast(daten) {
+    const roh = daten;
+    if (roh == null ||
+        typeof roh !== 'object' ||
+        typeof roh.id !== 'string' ||
+        typeof roh.status !== 'string' ||
+        typeof roh.amount_received !== 'number' ||
+        typeof roh.currency !== 'string') {
+        throw antwortfehler(ENDPUNKT_CAPTURE, 'Antwort enthaelt kein eingezogenes Zahlungsversprechen');
+    }
+    return {
+        id: roh.id,
+        status: roh.status,
+        // Stripe fuehrt Betraege in der kleinsten Waehrungseinheit — hier bereits
+        // Cent, es wird also nichts umgerechnet (anders als bei Hobex).
+        amountReceivedCents: roh.amount_received,
+        currency: roh.currency,
+    };
+}
+/** 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/printing/escpos.d.ts

@@ -0,0 +1,219 @@
+/**
+ * ESC/POS-Bytefolgen fuer Bondrucker — Zwilling von
+ * `kasseneck_api/lib/src/printing/escpos/` (Flutter).
+ *
+ * Dieses Modul erzeugt **nur Bytes**. Es kennt keinen Transport: kein
+ * Bluetooth, kein WLAN, kein USB, keine Verbindung. Wer die Bytes wohin
+ * schickt, entscheidet der Aufrufer.
+ *
+ * Die Steuerbefehle sind wortwoertlich aus `commands.dart`, `generator.dart`
+ * und `qrcode.dart` uebernommen. Bei ESC/POS zaehlt jedes Byte: ein
+ * "ungefaehr richtiger" Befehl druckt Unsinn oder gar nichts. Reihenfolge und
+ * Bytefolge deshalb nicht anpassen, ohne die Erwartungswerte in
+ * `test/escpos.test.ts` gegen das Flutter-Vorbild neu abzugleichen.
+ *
+ * **Zeichenkodierung.** Bondrucker sprechen kein UTF-8, sondern eine
+ * Codepage. Dieses Modul kodiert Text wie das Vorbild nach Latin-1 (ein Byte
+ * je Zeichen) und meldet dem Drucker dazu die passende Codepage ueber
+ * `ESC t n`. Vorgabe ist CP1252: dort stehen alle deutschen Umlaute an
+ * denselben Stellen wie in Latin-1, "ä" ist also genau 0xE4 — ein Byte, nicht
+ * zwei. Waeren es zwei (UTF-8), verschoeben sich zusaetzlich alle
+ * Spaltenbreiten, weil die Spaltenrechnung mit Byte-Laengen arbeitet.
+ * CP437 ist ebenfalls waehlbar — manche (Bluetooth-)Drucker ignorieren
+ * `ESC t 16` und bleiben in CP437; dann werden die Umlaute auf ihre
+ * CP437-Plaetze umkodiert (ä = 0x84, ü = 0x81, ß = 0xE1, ...). Zeichen ohne
+ * CP437-Platz werden zu `?` — weiterhin ein Byte je Zeichen.
+ *
+ * Nicht enthalten (bewusst): Rasterbilder/Logos, Capability-Profile einzelner
+ * Druckermodelle, Kassenlade, 1D-Barcodes.
+ */
+/** Papierbreite der Bonrolle. */
+export type PosPaperSize = 'mm58' | 'mm80';
+/** Ausrichtung einer Textzeile bzw. innerhalb einer Spalte. */
+export type PosAlign = 'left' | 'center' | 'right';
+/** Druckerschrift: A ist breiter, B schmaler (mehr Zeichen je Zeile). */
+export type PosFont = 'fontA' | 'fontB';
+/** Voller oder teilweiser Papierschnitt. */
+export type PosCutMode = 'full' | 'partial';
+/** Vom Drucker zu verwendende Codepage. */
+export type PosCodeTable = 'CP437' | 'CP1252';
+/** Zeichenvergroesserung (1 = einfach, 2 = doppelt, ... bis 8). */
+export type PosTextSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/** Modulgroesse des QR-Codes (Punkte je Modul). */
+export type QrSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/** Fehlerkorrekturstufe des QR-Codes. */
+export type QrCorrection = 'L' | 'M' | 'Q' | 'H';
+/** Textstil. Fehlende Felder gelten als Vorgabewert (nicht als "unveraendert"). */
+export interface PosStyles {
+    bold?: boolean;
+    reverse?: boolean;
+    underline?: boolean;
+    turn90?: boolean;
+    align?: PosAlign;
+    height?: PosTextSize;
+    width?: PosTextSize;
+    fontType?: PosFont;
+    codeTable?: PosCodeTable;
+}
+/**
+ * Eine Spalte einer Zeile. `width` ist ein Zwoelftel-Anteil (1..12), die
+ * Breiten aller Spalten einer Zeile muessen zusammen 12 ergeben.
+ * Entweder `text` **oder** `textEncoded` angeben, nicht beides.
+ */
+export interface PosColumn {
+    text?: string;
+    textEncoded?: Uint8Array;
+    width: number;
+    styles?: PosStyles;
+}
+export interface EscPosOptions {
+    /** Papierbreite, Vorgabe `mm58`. */
+    paperSize?: PosPaperSize;
+    /** Globale Codepage, Vorgabe `CP1252`; `null` laesst die des Druckers stehen. */
+    codeTable?: PosCodeTable | null;
+    /** Abstand zwischen Spalten in Punkten, Vorgabe 5. */
+    spaceBetweenRows?: number;
+}
+export interface EscPosTextOptions {
+    styles?: PosStyles;
+    /** Zusaetzliche Leerzeilen nach dem Text (der eine Zeilenumbruch kommt immer). */
+    linesAfter?: number;
+}
+export interface EscPosHrOptions {
+    /** Fuellzeichen, Vorgabe `-`. */
+    ch?: string;
+    /** Laenge in Zeichen; ohne Angabe die volle Zeilenbreite. */
+    len?: number;
+    linesAfter?: number;
+}
+export interface EscPosQrOptions {
+    align?: PosAlign;
+    size?: QrSize;
+    correction?: QrCorrection;
+}
+/** Interner Stilzustand — immer vollstaendig, nie teilbefuellt. */
+interface AktuelleStile {
+    bold: boolean;
+    reverse: boolean;
+    underline: boolean;
+    turn90: boolean;
+    align: PosAlign;
+    height: PosTextSize;
+    width: PosTextSize;
+    fontType: PosFont | null;
+    codeTable: PosCodeTable | null;
+}
+/**
+ * Aufbauender Puffer. Die Felder ausser `paperSize`/`spaceBetweenRows` sind
+ * interner Zustand des Bytestroms — nicht von aussen aendern, sondern ueber
+ * die `escPos*`-Funktionen.
+ */
+export interface EscPosDocument {
+    readonly paperSize: PosPaperSize;
+    readonly spaceBetweenRows: number;
+    /** intern: bisher erzeugte Bytes */
+    readonly bytes: number[];
+    /** intern: global gesetzte Codepage (ueberlebt `escPosReset`) */
+    globalCodeTable: PosCodeTable | null;
+    /** intern: global gesetzte Schrift (ueberlebt `escPosReset`) */
+    globalFont: PosFont | null;
+    /** intern: Zeichen je Zeile aus der globalen Schrift */
+    maxCharsPerLine: number | null;
+    /** intern: zuletzt an den Drucker gesendeter Stil */
+    styles: AktuelleStile;
+}
+/**
+ * Kodiert Text so, wie ihn der Drucker erwartet: ein Byte je Zeichen nach
+ * Latin-1, vorher die vier Zeichenersetzungen des Vorbilds. Ein Umlaut wird
+ * damit zu genau einem Byte — Voraussetzung dafuer, dass die Spaltenrechnung
+ * stimmt.
+ */
+export declare function encodeEscPosText(text: string, codeTable?: PosCodeTable): Uint8Array;
+/** Zeichen je Zeile fuer Papier und Schrift (`fontA`, wenn nichts gesetzt ist). */
+export declare function escPosMaxCharsPerLine(paperSize: PosPaperSize, font?: PosFont | null): number;
+/** Legt einen leeren Bytepuffer an. Der erste Befehl ist ueblicherweise `escPosReset`. */
+export declare function createEscPosDocument(options?: EscPosOptions): EscPosDocument;
+/** Die bisher erzeugten Bytes als Kopie. */
+export declare function escPosBytes(doc: EscPosDocument): Uint8Array;
+/**
+ * `ESC @`: Drucker initialisieren und den gemerkten Stil verwerfen. Danach
+ * werden globale Codepage und Schrift erneut gesendet — der Drucker vergisst
+ * sie beim Initialisieren.
+ */
+export declare function escPosReset(doc: EscPosDocument): void;
+/**
+ * `ESC t n`: Codepage waehlen. Sie gilt bis zum naechsten `escPosReset` und
+ * wird von diesem erneut gesendet. `null` schaltet die Vorgabe ab; dann
+ * bleibt die Codepage des Druckers stehen und Umlaute werden unlesbar.
+ */
+export declare function escPosSetGlobalCodeTable(doc: EscPosDocument, codeTable: PosCodeTable | null): void;
+/**
+ * `ESC M n`: Schrift waehlen. Die Schrift bestimmt auch, wie viele Zeichen in
+ * eine Zeile passen (32/42 bei 58 mm, 48/64 bei 80 mm).
+ */
+export declare function escPosSetGlobalFont(doc: EscPosDocument, font: PosFont | null, options?: {
+    maxCharsPerLine?: number;
+}): void;
+/**
+ * Sendet die Stilbefehle, die sich gegenueber dem zuletzt gesendeten Stand
+ * geaendert haben. Fehlende Felder in [styles] gelten als Vorgabe: wer fett
+ * weglaesst, schaltet fett also ab.
+ */
+export declare function escPosSetStyles(doc: EscPosDocument, styles?: PosStyles): void;
+/**
+ * Interner Textdruck: absolute Position setzen (`ESC $`), Stil senden, Bytes
+ * ausgeben. [colInd]/[colWidth] beschreiben die Spalte im Zwoelftel-Raster.
+ */
+/**
+ * Wortweiser Umbruch von (kodierten) Text-Bytes auf hoechstens `max` Zeichen
+ * je Zeile: geschnitten wird am letzten Leerzeichen innerhalb der Grenze
+ * (das Leerzeichen selbst faellt weg); gibt es keines, hart bei `max` --
+ * sonst kaeme die Zeile nie voran. Ein Bondrucker bricht sonst hart mitten
+ * im Wort ("Kleinunter|nehmer", "0,7|9"); das soll nie aufs Papier.
+ */
+export declare function escPosWortzeilen(textBytes: Uint8Array, max: number): Uint8Array[];
+/**
+ * Dieselbe Regel fuer Zeichenketten -- fuer Bildschirm-Vorschauen, die das
+ * Papier nachstellen, und fuer das Zeichenraster. Zusaetzlich:
+ * - geschuetztes Leerzeichen (U+00A0) ist kein Umbruchpunkt ("je 0,79" bleibt
+ *   zusammen) und wird als normales Leerzeichen ausgegeben;
+ * - ein ueberlanges Wort bricht nach einem Bindestrich, wenn es einen hat
+ *   ("Bio-" / "Dinkelvollkornsemmel"), sonst hart.
+ */
+export declare function wortzeilenText(text: string, max: number): string[];
+/**
+ * Druckt Text und schliesst die Zeile ab. Nach dem Text folgt immer genau ein
+ * Zeilenumbruch, `linesAfter` haengt weitere an.
+ */
+export declare function escPosText(doc: EscPosDocument, text: string, options?: EscPosTextOptions): void;
+/** [n] Zeilenumbrueche (0x0A) — nicht der Vorschubbefehl, sondern echte Umbrueche. */
+export declare function escPosEmptyLines(doc: EscPosDocument, n: number): void;
+/** `ESC d n`: Papier um [n] Zeilen vorschieben. */
+export declare function escPosFeed(doc: EscPosDocument, n: number): void;
+/**
+ * Papierschnitt: fuenf Leerzeilen (damit der Text ueber der Schneide steht)
+ * und danach `GS V 0` bzw. `GS V 1`.
+ */
+export declare function escPosCut(doc: EscPosDocument, mode?: PosCutMode): void;
+/** Trennlinie ueber die volle Zeilenbreite (oder [len] Zeichen). */
+export declare function escPosHr(doc: EscPosDocument, options?: EscPosHrOptions): void;
+/**
+ * Druckt eine Zeile aus bis zu zwoelf Spalten. Die Breiten (Zwoelftel) muessen
+ * zusammen 12 ergeben. Passt der Inhalt einer Spalte nicht, laeuft der Rest in
+ * eine Folgezeile.
+ */
+export declare function escPosRow(doc: EscPosDocument, columns: readonly PosColumn[]): void;
+/**
+ * Bytes des nativen QR-Befehls (`GS ( k`, Funktionen 167/169/180/182/181) —
+ * ohne Ausrichtung, ohne Zeilenumbruch. Der Drucker zeichnet den Code selbst;
+ * es wird kein Bild uebertragen.
+ *
+ * Bei Kasseneck-Belegen steht hier der maschinenlesbare RKSV-Code.
+ */
+export declare function qrCodeBytes(text: string, options?: {
+    size?: QrSize;
+    correction?: QrCorrection;
+}): Uint8Array;
+/** Setzt die Ausrichtung und haengt den nativen QR-Befehl an. */
+export declare function escPosQrCode(doc: EscPosDocument, text: string, options?: EscPosQrOptions): void;
+export {};