@kreiseck/kasseneck-api 0.6.7

package/dist/esm/client/errors.js

@@ -0,0 +1,212 @@
+/**
+ * Die fuenf Fehlerarten des Kasseneck-Clients — bewusst getrennt, weil ein
+ * Aufrufer auf jede anders reagieren muss:
+ *
+ * - `KasseneckValidationError` — die **Form** stimmt nicht: entweder ging
+ *   mangels brauchbarer Eingabe gar keine Anfrage raus, oder die Antwort war
+ *   nicht verwertbar. `scope` trennt die beiden Richtungen. `'request'`: die
+ *   Eingabe des Aufrufers verletzt eine Regel, die dieses Paket schon vor dem
+ *   Senden kennt (Beleg ohne Positionen, unmoegliche Gutscheinkombination) —
+ *   das ist ein Programmierfehler im Aufrufer, kein Betriebszustand.
+ *   `'response'`: das Backend meldete Erfolg, die Nutzlast enthielt aber
+ *   nicht, was der Aufruf zusagt.
+ *
+ * - `KasseneckApiError` — **fachlicher** Fehler. Das Backend antwortet immer
+ *   mit HTTP 200 und legt Erfolg/Misserfolg in den Rumpf
+ *   (`{status:'success'|'error', message, data}`, siehe `successResponse`/
+ *   `errorResponse` im Backend). Ein `status:'error'` heisst: die Anfrage kam
+ *   an und wurde abgelehnt (gesperrte Kasse, fehlendes Modul, ungueltiger
+ *   Parameter). Wiederholen hilft nicht.
+ * - `KasseneckHttpError` — die Antwort war **keine** verwertbare Huelle:
+ *   HTTP 500/404, leerer Rumpf, oder HTTP 200 mit HTML statt JSON (typisch,
+ *   wenn ein Aufruf mangels Rewrite auf der Single-Page-App landet). Beim
+ *   Bericht-Download gelten dieselben Gruende fuer alles, was kein PDF ist.
+ *   `reason` trennt die Faelle maschinenlesbar.
+ * - `KasseneckNetworkError` — die Antwort kam gar nicht: Netz weg, DNS,
+ *   abgebrochene Verbindung oder Zeitueberschreitung (`timedOut`).
+ * - `KasseneckAuthError` — es kam nicht einmal zur Anfrage, weil die Anmeldung
+ *   scheiterte (fehlende Zugangsdaten, oder der Token-/Sitzungsgeber warf).
+ *   In der Browser-Kasse mit ihrer 90-Sekunden-Sitzung ist das Alltag, kein
+ *   Sonderfall.
+ *
+ * **Geheimnisse gehoeren in keinen dieser Fehler.** Fehlermeldungen landen in
+ * Protokollen und Fehlerdiensten; weder `api_key`, Kassen-Token, Firebase-
+ * ID-Token noch Sitzungsbezeichner duerfen dorthin. Deshalb tragen die Fehler
+ * ausschliesslich Funktionsname, HTTP-Status/Inhaltstyp, den vom Paket
+ * formulierten Grund und die vom Backend formulierte Meldung — nie Kopfzeilen,
+ * nie den gesendeten Rumpf und auch nicht den empfangenen Rumpf (der koennte
+ * bei einem fremden Proxy alles Moegliche zurueckspiegeln).
+ *
+ * Aus demselben Grund haengt **keine fremde Ursache** als `cause` an diesen
+ * Fehlern: `console.error(err)` und `util.inspect` drucken die Ursachenkette
+ * mit, und fremde HTTP-Bibliotheken haengen ihre Anfrage an ihre Fehler (axios
+ * `config.headers`, got `options.headers`) — mit dem Bearer-Schluessel darin.
+ * Statt der Ursache selbst traegt `KasseneckNetworkError` ihre **verdichtete**
+ * Form: `causeName`/`causeCode`, beide nur, wenn sie wie ein Bezeichner
+ * aussehen **und** mit keinem der gesendeten Geheimnisse ueberlappen (siehe
+ * `causeDigest`).
+ *
+ * Der Formfilter allein traegt diese Zusage naemlich nicht: der
+ * Sitzungsbezeichner der Browser-Kasse ist selbst bezeichner-foermig und kaeme
+ * durch. Verdichtet werden darf nur, wo die gesendeten Geheimnisse bekannt
+ * sind — also nach dem Bauen der Anfrage. `KasseneckAuthError` traegt darum
+ * **gar keine** Ursachen-Verdichtung: dort ist noch nichts gesendet, es gibt
+ * keine Liste zum Abgleichen, und Diagnose ist an dieser Stelle weniger wert
+ * als die Zusage.
+ */
+// Bezeichner-artig: Buchstabe vorn, danach nur Bezeichnerzeichen, hoechstens
+// 64 Zeichen. Das laesst `TypeError`, `ECONNREFUSED` und `auth/internal-error`
+// durch, aber keinen Freitext und kein Firebase-ID-Token (~900 Zeichen).
+const BEZEICHNER = /^[A-Za-z][A-Za-z0-9_./-]{0,63}$/;
+/**
+ * Reduziert eine fremde Ursache auf Name und Code — und verwirft beides, wenn
+ * es kein Bezeichner ist oder mit einem der uebergebenen Geheimnisse
+ * ueberlappt (ein Sitzungsbezeichner sieht durchaus bezeichner-artig aus).
+ *
+ * `geheimnisse` hat bewusst **keinen** Vorgabewert: eine Verdichtung ohne
+ * Abgleichliste waere nur ein Formfilter und damit keine Zusage. Wo die
+ * gesendeten Werte nicht bekannt sind, wird gar nicht verdichtet.
+ */
+export function causeDigest(ursache, geheimnisse) {
+    const roh = ursache;
+    return {
+        causeName: unbedenklich(roh?.name, geheimnisse),
+        causeCode: unbedenklich(roh?.code, geheimnisse),
+    };
+}
+function unbedenklich(wert, geheimnisse) {
+    if (typeof wert !== 'string' || !BEZEICHNER.test(wert)) {
+        return undefined;
+    }
+    for (const geheim of geheimnisse) {
+        if (geheim && (geheim.includes(wert) || wert.includes(geheim))) {
+            return undefined;
+        }
+    }
+    return wert;
+}
+/** Fachlicher Fehler: HTTP 200, aber `status: 'error'` im Rumpf. */
+export class KasseneckApiError extends Error {
+    name = 'KasseneckApiError';
+    /** Aufgerufene Backend-Funktion, z. B. `createReceipt`. */
+    functionName;
+    /** Meldung des Backends, unveraendert (`message` aus der Huelle). */
+    serverMessage;
+    constructor(functionName, serverMessage) {
+        super(`${functionName} fehlgeschlagen: ${serverMessage}`);
+        this.functionName = functionName;
+        this.serverMessage = serverMessage;
+    }
+}
+const GRUND_TEXT = {
+    'server-error': 'Server-Fehler',
+    'empty-body': 'leere Antwort',
+    'not-json': 'Antwort ist kein JSON',
+    'missing-status': 'Antwort ohne Statusfeld',
+};
+/** Antwort ohne verwertbare Huelle (HTTP-Fehler, leerer Rumpf, HTML statt JSON). */
+export class KasseneckHttpError extends Error {
+    name = 'KasseneckHttpError';
+    functionName;
+    /** HTTP-Statuscode der Antwort (bei HTML-statt-JSON durchaus 200). */
+    statusCode;
+    /** Inhaltstyp der Antwort, falls die Gegenstelle einen gesetzt hat. */
+    contentType;
+    /** Maschinenlesbarer Grund — trennt den Rewrite-Fall vom 500er ohne Textparsen. */
+    reason;
+    constructor(functionName, statusCode, contentType, reason) {
+        const typHinweis = contentType ? `, Inhaltstyp ${contentType}` : '';
+        super(`${functionName} fehlgeschlagen: ${GRUND_TEXT[reason]} (HTTP ${statusCode}${typHinweis})`);
+        this.functionName = functionName;
+        this.statusCode = statusCode;
+        this.contentType = contentType;
+        this.reason = reason;
+    }
+}
+/** Es kam keine Antwort: Netzfehler oder Zeitueberschreitung. */
+export class KasseneckNetworkError extends Error {
+    name = 'KasseneckNetworkError';
+    functionName;
+    /** true = das Zeitlimit lief ab und die Anfrage wurde abgebrochen. */
+    timedOut;
+    /** Das geltende Zeitlimit in Millisekunden. */
+    timeoutMs;
+    /** Name der zugrunde liegenden Ursache, sofern unbedenklich (s. `causeDigest`). */
+    causeName;
+    /** Code der zugrunde liegenden Ursache, sofern unbedenklich (z. B. `ECONNREFUSED`). */
+    causeCode;
+    constructor(functionName, timedOut, timeoutMs, ursache = {}) {
+        const grund = timedOut ? `Zeitueberschreitung nach ${timeoutMs} ms` : 'Netzwerkfehler';
+        const codeHinweis = ursache.causeCode ? ` (${ursache.causeCode})` : '';
+        super(`${functionName} fehlgeschlagen: ${grund}${codeHinweis}`);
+        this.functionName = functionName;
+        this.timedOut = timedOut;
+        this.timeoutMs = timeoutMs;
+        this.causeName = ursache.causeName;
+        this.causeCode = ursache.causeCode;
+    }
+}
+/**
+ * Die Anmeldung scheiterte — es ging keine Anfrage raus.
+ *
+ * Dieser Fehler traegt **nichts** aus der fremden Ursache: weder ihre Meldung
+ * (ein Token-Geber fuehrt gern den Token mit, den er gerade nicht erneuern
+ * konnte) noch eine Verdichtung ihres Namens/Codes. Zum Zeitpunkt des
+ * Anmeldefehlers ist noch nichts gesendet, es gibt also keine Liste der
+ * Geheimnisse, gegen die verdichtete Werte geprueft werden koennten — und ein
+ * reiner Formfilter laesst genau die Form durch, die ein Sitzungsbezeichner
+ * hat.
+ */
+export class KasseneckAuthError extends Error {
+    name = 'KasseneckAuthError';
+    /** Betroffene Backend-Funktion, falls der Fehler bei einem Aufruf entstand. */
+    functionName;
+    /** Vom Paket formulierter Grund — geheimnisfrei, anders als fremde Meldungen. */
+    reason;
+    constructor(reason, options = {}) {
+        super(options.functionName ? `${options.functionName} fehlgeschlagen: ${reason}` : reason);
+        this.functionName = options.functionName;
+        this.reason = reason;
+    }
+}
+/**
+ * Die Form stimmt nicht — bei `scope: 'request'` ging deshalb keine Anfrage
+ * raus, bei `scope: 'response'` kam eine unbrauchbare zurueck.
+ *
+ * Es gilt dieselbe Zusage wie fuer die uebrigen Fehlerarten: `reason` ist vom
+ * Paket formuliert und geheimnisfrei. Bei `'response'` wird insbesondere
+ * **nichts aus der Antwort** uebernommen — ein fremder Proxy koennte dort
+ * alles Moegliche zurueckspiegeln.
+ */
+export class KasseneckValidationError extends Error {
+    name = 'KasseneckValidationError';
+    /**
+     * Betroffener Vorgang — meist die Backend-Funktion, bei Pruefungen ohne
+     * Aufruf der Name der Paketfunktion (z. B. `buildReceiptLayout`).
+     */
+    functionName;
+    /** Vom Paket formulierter Grund. */
+    reason;
+    scope;
+    constructor(functionName, reason, scope) {
+        super(`${functionName} fehlgeschlagen: ${reason}`);
+        this.functionName = functionName;
+        this.reason = reason;
+        this.scope = scope;
+    }
+}
+export function isKasseneckApiError(fehler) {
+    return fehler instanceof KasseneckApiError;
+}
+export function isKasseneckHttpError(fehler) {
+    return fehler instanceof KasseneckHttpError;
+}
+export function isKasseneckNetworkError(fehler) {
+    return fehler instanceof KasseneckNetworkError;
+}
+export function isKasseneckAuthError(fehler) {
+    return fehler instanceof KasseneckAuthError;
+}
+export function isKasseneckValidationError(fehler) {
+    return fehler instanceof KasseneckValidationError;
+}

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

@@ -0,0 +1,8 @@
+export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, } from './auth.js';
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type KasseneckTransport, type KasseneckBinaryTransport, createTransport, createBinaryTransport, } from './transport.js';
+export { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, } from './errors.js';
+export { type ReceiptCommonOptions, type SellReceiptOptions, type CancelReceiptOptions, type CreateCancelReceiptOptions, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, cancelReceipt, type CancelReceiptResult, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, checkVoucherCombinationError, } from './receipts.js';
+export { listMyCashregisters } from './cashregisters.js';
+export { downloadDailyReport, downloadMonthlyReport } from './reports.js';
+export { type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, } from './status.js';
+export { type KasseneckApi, createKasseneckApi } from './api.js';

package/dist/esm/client/index.js

@@ -0,0 +1,8 @@
+export { apiKeyAuth, registerUserAuth, } from './auth.js';
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, createTransport, createBinaryTransport, } from './transport.js';
+export { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, } from './errors.js';
+export { sellReceipt, sellReceiptWithCompany, cancelReceipt, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, checkVoucherCombinationError, } from './receipts.js';
+export { listMyCashregisters } from './cashregisters.js';
+export { downloadDailyReport, downloadMonthlyReport } from './reports.js';
+export { getCashboxStatus, getSignatureStatus, } from './status.js';
+export { createKasseneckApi } from './api.js';

package/dist/esm/client/receipts.d.ts

@@ -0,0 +1,245 @@
+import { ReceiptType, type ReceiptTypeKey, KeckPaymentMethod, type KeckPaymentMethodKey, CreditCardProvider } from '../enums/index.js';
+import { type Receipt, type ReceiptCompany, type ReceiptItem, type Voucher, type ReceiptSummary, type ReportMonth, type CancellationItem, type CancellationOf, type CancellationReason } from '../models/index.js';
+import type { KasseneckTransport } from './transport.js';
+import type { Pruefangaben, ReceiptLayout } from '../receipt/layout.js';
+/**
+ * Beleg-Endpunkte — Zwilling der Beleg-Aufrufe in
+ * kasseneck_api/lib/kasseneck_api.dart.
+ *
+ * **Verkauf, freier Storno und Nullbeleg laufen ueber einen einzigen
+ * Backend-Endpunkt `createReceipt`.** `sellReceipt`, `createCancelReceipt` und
+ * `zeroReceipt` sind — wie im Flutter-Vorbild — benannte Bequemlichkeits-
+ * schichten ueber [createReceipt]; sie legen den Belegtyp fest und reichen den
+ * Rest durch. **[cancelReceipt] geht an den eigenen Endpunkt `cancelReceipt`**:
+ * der Server negiert die Positionen des Originals, prueft Restmengen und
+ * Rechte und verkettet beide Belege (Storno-API).
+ *
+ * **Kein Wiederholen fehlgeschlagener Aufrufe** (siehe transport.ts): ein
+ * Beleg ist nicht folgenlos wiederholbar.
+ *
+ * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** Von den
+ * Endpunkten dieser Datei setzen [listMyReceipts], [getReceipt],
+ * [createReceipt] und [generateFullReceiptId] ein `allowRegisterUser` — der
+ * Browser-Kasse steht hier also alles offen ausser [getFirstReceiptDate];
+ * siehe den Hinweis dort. Dieses Paket bildet das **nicht** nach — wer darf,
+ * entscheidet allein das Backend. Der Hinweis steht hier, damit ein Leser
+ * nicht raten muss.
+ */
+/** Gemeinsame Zusatzangaben aller Belegarten (Nutzlast von `createReceipt`). */
+export interface ReceiptCommonOptions {
+    /** Kundendaten fuer den Belegkopf; gehen als `\n`-verbundene Zeichenkette raus. */
+    customerDetails?: string[];
+    /** Rechtshinweise (z. B. Reverse Charge); gehen als `\n`-verbundene Zeichenkette raus. */
+    legalMessage?: string[];
+    /** Kartenanbieter; ohne Angabe gilt `custom`. */
+    creditCardProvider?: CreditCardProvider;
+    /** Transaktionsbezeichner der Kartenzahlung. */
+    cardPaymentId?: string;
+    /** Freier Bezeichner des Aufrufers (Projekt, Auftrag, Schicht). */
+    customProjectId?: string;
+    /** Rohdaten der Kartenzahlung (Terminal-/Anbieterantwort). */
+    cardPaymentData?: Record<string, unknown>;
+}
+/** Belegtyp und Inhalt — die vollstaendige Eingabe von [createReceipt]. */
+export interface CreateReceiptOptions extends ReceiptCommonOptions {
+    receiptType: ReceiptType | ReceiptTypeKey;
+    /** Zahlungsart des Aufrufers — wird vor dem Senden geprueft. */
+    paymentMethod?: KeckPaymentMethod | KeckPaymentMethodKey;
+    /**
+     * Zahlungsart, die aus einer **Serverantwort** stammt (Storno eines
+     * gelesenen Belegs). Geht ungeprueft hinaus: der
+     * Server hat den Wert selbst vergeben und weist unbekannte selbst ab —
+     * ergaenzt er eine Zahlungsart vor dem naechsten Paket-Update, waeren sonst
+     * alle Belege damit unstornierbar. Nur fuer diesen einen Weg gedacht; eine
+     * ausdruecklich uebergebene `paymentMethod` sticht.
+     */
+    paymentMethodFromServer?: string;
+    items?: ReceiptItem[];
+    vouchers?: Voucher[];
+}
+export interface SellReceiptOptions extends ReceiptCommonOptions {
+    paymentMethod: KeckPaymentMethod | KeckPaymentMethodKey;
+    items?: ReceiptItem[];
+    vouchers?: Voucher[];
+}
+/**
+ * `customerDetails` fehlt hier absichtlich (wie im Flutter-Vorbild): die
+ * Kundendaten des Stornos sind die des stornierten Belegs, sonst stimmten
+ * Beleg und Storno nicht mehr ueberein.
+ */
+/**
+ * Storno ueber den Endpunkt `cancelReceipt` (Backend: storno-endpoints.js).
+ * Der Server negiert die Positionen, prueft Restmengen und Rechte, verkettet
+ * Original und Storno-Beleg. Bezug entweder als Beleg-Objekt (`receipt`) oder
+ * als Kasse + Beleg-ID.
+ */
+export type CancelReceiptOptions = {
+    /** Grund aus dem Katalog — Pflicht, nur der Anzeigetext landet am Bon. */
+    reason: CancellationReason;
+    /** Teilstorno: Positionen (Index im Original) und Mengen. Fehlt = Vollstorno der Restmengen. */
+    items?: CancellationItem[];
+    /** Interne Anmerkung (≤ 200 Zeichen), wird gespeichert, nie gedruckt. */
+    note?: string;
+    /** Rueckzahlweg; ohne Angabe die Zahlungsart des stornierten Belegs. */
+    paymentMethod?: KeckPaymentMethod | KeckPaymentMethodKey;
+} & ({
+    receipt: Receipt;
+    cashregisterId?: string;
+    originalReceiptId?: string;
+} | {
+    receipt?: undefined;
+    cashregisterId: string;
+    originalReceiptId: string;
+});
+/** Antwort von [cancelReceipt]: Storno-Beleg, Bezug, Restmengen des Originals danach. */
+export interface CancelReceiptResult {
+    receipt: Receipt;
+    cancellationOf: CancellationOf;
+    remaining: number[];
+}
+export interface CreateCancelReceiptOptions extends ReceiptCommonOptions {
+    paymentMethod: KeckPaymentMethod | KeckPaymentMethodKey;
+    /** Positionen, wie sie auf dem Storno stehen sollen — **nicht** negiert. */
+    items: ReceiptItem[];
+}
+/**
+ * Beleg **und** die Firmen-/Druckdaten derselben Antwort — das Ergebnis der
+ * `…WithCompany`-Varianten. Das Backend liefert beides in einem Aufruf
+ * (functions/index.js); wer den Beleg drucken oder anzeigen will, braucht
+ * beides und soll dafuer keinen zweiten Aufruf machen muessen.
+ */
+export interface ReceiptWithCompany {
+    receipt: Receipt;
+    /** Kopf/Fuss, wie sie fuer DIESEN Beleg gelten (eingefrorene Version des Backends). */
+    company: ReceiptCompany;
+    /** Beleg einer Testumgebung (Aufdruck TESTKASSE). */
+    testKasse: boolean;
+    /** Produktionskonto mit Test-Signatureinheit (Aufdruck TESTSIGNATUR). */
+    testSignatur: boolean;
+    /** Kennung der Kopf-Version; null bei altem Backend/Altbeleg ohne Zuordnung. */
+    kopfId: string | null;
+    /** Vom Backend gebautes Zeilenmodell (Regelwerk des Belegs); null, wenn nicht mitgeliefert. */
+    layout: ReceiptLayout | null;
+    /**
+     * Registrierdaten fuer den Block „Prüfangaben“ (Nullbelege, Regelwerk 2) --
+     * fuer Clients, die das Layout selbst bauen; null bei altem Backend.
+     */
+    pruefangaben: Pruefangaben | null;
+}
+/**
+ * Gemeinsame Umsetzung aller Belegarten (Zwilling von `_createReceipt`).
+ * Bewusst **nicht** Teil der Paketoberflaeche: der Belegtyp gehoert nicht in
+ * die Hand des Aufrufers, sondern zu einem der benannten Aufrufe darunter.
+ */
+export declare function createReceipt(rufen: KasseneckTransport, options: CreateReceiptOptions): Promise<Receipt>;
+/** Normalbeleg (Verkauf) nach RKSV. */
+export declare function sellReceipt(rufen: KasseneckTransport, options: SellReceiptOptions): Promise<Receipt>;
+/**
+ * Normalbeleg wie [sellReceipt], liefert zusaetzlich die Firmen-/Druckdaten
+ * aus derselben Antwort — alles, was ein Belegdruck braucht, in einem Aufruf.
+ */
+export declare function sellReceiptWithCompany(rufen: KasseneckTransport, options: SellReceiptOptions): Promise<ReceiptWithCompany>;
+/**
+ * Storno-Beleg zu einem bestehenden Beleg — voll oder in Teilen. Prueft die
+ * Eingabe, bevor etwas hinausgeht; der Server haelt die Restmengen und die
+ * Reichweite des Rechts (eigene/alle) und antwortet mit dem fertigen,
+ * signierten Storno-Beleg. Gutscheine des Originals wandern nicht mit.
+ */
+export declare function cancelReceipt(rufen: KasseneckTransport, options: CancelReceiptOptions): Promise<CancelReceiptResult>;
+/**
+ * Stornobeleg aus frei uebergebenen Positionen — fuer den Fall, dass der
+ * Originalbeleg nicht als Objekt vorliegt. Die Positionen gehen **unveraendert**
+ * hinaus; das Vorzeichen setzt der Aufrufer.
+ */
+export declare function createCancelReceipt(rufen: KasseneckTransport, options: CreateCancelReceiptOptions): Promise<Receipt>;
+/** Nullbeleg (RKSV-Pruefbeleg) — ohne Positionen und ohne Zahlungsart. */
+export declare function zeroReceipt(rufen: KasseneckTransport): Promise<Receipt>;
+/** Belegliste einer Kasse samt der Kennzahlen, die dieselbe Antwort mitliefert. */
+export interface ReceiptList {
+    /** Letzte Belege, neueste zuerst (Backend: nach `counter` absteigend). */
+    receipts: ReceiptSummary[];
+    stats: ReceiptListStats;
+}
+/**
+ * Kennzahlen zur Kasse, die `listMyReceipts` neben der Liste liefert. Sie
+ * kommen aus den Tages-Aggregaten des Backends, nicht aus den gelisteten
+ * Belegen — die Reihe umfasst sieben Tage, die Liste nur die letzten `limit`
+ * Belege.
+ */
+export interface ReceiptListStats {
+    /** Heutiger Umsatz in Cent und Belegzahl (Wiener Kalendertag). */
+    today: {
+        revenueCents: number;
+        count: number;
+    };
+    /** Veraenderung gegenueber gestern in Prozent; `null`, wenn gestern 0 war. */
+    trendPercent: number | null;
+    /** Sieben Tage, aeltester zuerst; `date` als `YYYY-MM-DD` (Wiener Kalender). */
+    days: Array<{
+        date: string;
+        revenueCents: number;
+    }>;
+}
+export interface ListMyReceiptsOptions {
+    /**
+     * Kasse, deren Belege gelistet werden. Geht als Parameter **`cashregisterid`**
+     * hinaus — klein geschrieben, anders als das `cashregisterId` der Anmeldung:
+     * so heisst der Pflichtparameter dieses Endpunkts im Backend, und ein
+     * Tippfehler faellt sonst erst im Betrieb auf.
+     */
+    cashregisterId: string;
+    /**
+     * Anzahl Belege; ohne Angabe nimmt das Backend 50. Es begrenzt den Wert
+     * selbst auf 1 bis 200 — ein groesserer Wunsch wird still gekappt.
+     */
+    limit?: number;
+    /** Zeitfenster (Wiener Wanduhr, `YYYY-MM-DD` oder voller Zeitstempel); der Server deckelt auf 90 Tage. */
+    from?: string;
+    to?: string;
+}
+/**
+ * Belege einer Kasse auflisten — die Grundlage jeder Belegliste in der
+ * Browser-Kasse (Nachdruck, Storno, Tagesuebersicht).
+ *
+ * Die Eintraege sind **Zusammenfassungen**, keine vollstaendigen Belege (siehe
+ * [ReceiptSummary]); fuer Nachdruck oder Storno gehoert der Beleg ueber
+ * [getReceipt] bzw. [getReceiptWithCompany] einzeln geholt.
+ *
+ * **Anmeldeweg:** Der Endpunkt laeuft im Backend unter
+ * `checkRequest(req, 'customer', …, {allowRegisterUser: true})`, der Bearer
+ * muss also ein Firebase-ID-Token sein — mit `apiKeyAuth` ist er nicht
+ * erreichbar. Ausserdem prueft das Backend die Kassenzuweisung hier im Rumpf
+ * (der Endpunkt laeuft mit `checkCashRegister: false`), ein Kassen-Benutzer
+ * bekommt also nur die ihm zugewiesenen Kassen.
+ */
+export declare function listMyReceipts(rufen: KasseneckTransport, options: ListMyReceiptsOptions): Promise<ReceiptList>;
+/** Einzelnen Beleg der angemeldeten Kasse holen. */
+export declare function getReceipt(rufen: KasseneckTransport, receiptId: string): Promise<Receipt>;
+/**
+ * Wie [getReceipt], liefert zusaetzlich die Firmen-/Druckdaten aus derselben
+ * Antwort (Firma, Anschrift, Steuernummer, UID, Fusszeilen, Logo-Adresse,
+ * Kleinunternehmer-Kennzeichen) — die Angaben, die ein Beleg im Kopf und Fuss
+ * traegt (siehe models/receipt-company.ts).
+ */
+export declare function getReceiptWithCompany(rufen: KasseneckTransport, receiptId: string): Promise<ReceiptWithCompany>;
+/**
+ * Verschluesselte Volltext-Belegnummer erzeugen — der Bezeichner, unter dem der
+ * Beleg oeffentlich abrufbar ist (Beleg-Download, Pruefportal).
+ */
+export declare function generateFullReceiptId(rufen: KasseneckTransport, receiptId: string): Promise<string>;
+/**
+ * Berichtsmonat des allerersten Belegs dieser Kasse — die untere Grenze aller
+ * Monatsberichte.
+ *
+ * **Nicht fuer den Kassen-Benutzer-Weg (`registerUserAuth`):** dieser Endpunkt
+ * fuehrt kein `allowRegisterUser`, das Backend weist die Browser-Kasse hier ab
+ * (siehe Modulkommentar oben). Mit `apiKeyAuth` ist er offen.
+ */
+export declare function getFirstReceiptDate(rufen: KasseneckTransport): Promise<ReportMonth>;
+/**
+ * Prueft die Gutschein-Kombination eines Belegs und liefert den ersten
+ * Regelverstoss als Text (oder `null`) — Zwilling von
+ * `checkVoucherCombinationError`. Bewusst als Rueckgabewert statt als Fehler:
+ * eine Kassenoberflaeche will das pruefen, **bevor** sie den Beleg abschickt.
+ */
+export declare function checkVoucherCombinationError(vouchers: Voucher[], items: ReceiptItem[]): string | null;