@kreiseck/kasseneck-api 0.6.7

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