@kreiseck/kasseneck-api 0.30.0 → 1.0.0-rc.1

package/dist/esm/client/receipts.js

@@ -1,19 +1,50 @@
 import { ReceiptType, KeckPaymentMethod, CreditCardProvider, VoucherAction, VoucherType, } from '../enums/index.js';
-import { fromReceiptCompanyPayload, fromReceiptPayload, toReceiptItemPayload, toVoucherPayload, receiptItemIsValid, voucherIsValid, fromReceiptSummaryPayload, isCancellationReason, } from '../models/index.js';
+import { fromReceiptCompanyPayload, fromReceiptPayload, toReceiptItemPayload, toVoucherPayload, receiptItemIsValid, voucherIsValid, fromReceiptSummaryPayload, isCancellationReason, RECEIPT_EMAIL_VIAS, readRegistrationInfo, } from '../models/index.js';
 import { parseServerTimeStamp, toViennaWallClock } from '../vienna-time.js';
 import { euroToCents } from '../money.js';
-import { KasseneckValidationError } from './errors.js';
+import { KasseneckApiError, KasseneckValidationError, isKasseneckApiError } from './errors.js';
+import { buildReceiptLayout } from '../receipt/layout.js';
+/**
+ * Das Zeilenmodell zum Drucken und Anzeigen eines Belegs aus einer Antwort.
+ *
+ * **Ein Server-Layout gewinnt immer.** Liefert der Server `data.layout`, gilt
+ * genau dieses, in seiner Breite (80 mm): im oeffentlichen Kanal traegt nur
+ * es den Kartenblock (der Beleg selbst kommt dort ohne Anbieterdaten), und
+ * Bildschirm, Bon und PDF zeigen so denselben Beleg. Fehlt es, wird das
+ * Layout hier gebaut, mit den Angaben derselben Antwort (`testCashregister`,
+ * `testSignature`, `registrationInfo`) und in `fallbackPaperSize` (Vorgabe
+ * `mm58` wie in 0.x). Die Druckbreite waehlt allein der Druckweg
+ * (`paperSize` bei `escPosLayoutBytes`, `charsPerLine` bei ePOS und Blatt), nie
+ * dieser Helfer.
+ */
+export function receiptLayoutFromResult(result, options = {}) {
+    for (const name of Object.keys(options)) {
+        if (name !== 'fallbackPaperSize') {
+            throw new KasseneckValidationError('receiptLayoutFromResult', `Unbekannte Option "${name}" (die Druckbreite waehlt der Druckweg)`, 'request');
+        }
+    }
+    if (result.layout != null)
+        return result.layout;
+    return buildReceiptLayout(result.receipt, result.company, {
+        paperSize: options.fallbackPaperSize ?? 'mm58',
+        testCashregister: result.testCashregister,
+        testSignature: result.testSignature,
+        registrationInfo: result.registrationInfo,
+    });
+}
 /**
  * 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 async function createReceipt(rufen, options) {
-    return belegAusHuelle(await rufen('createReceipt', createReceiptParams(options)), 'createReceipt');
+    const daten = await rufen('createReceipt', createReceiptParams(options));
+    return signiertGelesen('createReceipt', () => belegAusHuelle(daten, 'createReceipt'));
 }
 /** Wie [createReceipt], liest aus derselben Antwort zusaetzlich die Firmendaten. */
 async function createReceiptWithCompany(rufen, options) {
-    return belegMitFirmaAusHuelle(await rufen('createReceipt', createReceiptParams(options)), 'createReceipt');
+    const daten = await rufen('createReceipt', createReceiptParams(options));
+    return signiertGelesen('createReceipt', () => belegMitFirmaAusHuelle(daten, 'createReceipt'));
 }
 /**
  * Baut die Nutzlast von `createReceipt` und prueft die Eingabe. Wirft, bevor
@@ -22,8 +53,17 @@ async function createReceiptWithCompany(rufen, options) {
 function createReceiptParams(options) {
     const typ = belegtyp(options.receiptType);
     const { items, vouchers } = options;
+    // Unter /v3 weist der Server diese Felder ab (payment_method_not_supported);
+    // ein Aufrufer ohne Typen erfaehrt es hier, bevor etwas hinausgeht.
+    const altfeld = ALTE_ZAHLFELDER.find((feld) => options[feld] != null);
+    if (altfeld != null) {
+        throw eingabefehler(`${altfeld} gibt es unter /v3 nicht mehr: Zahlungen und Kartenangaben gehen als payments hinaus.`);
+    }
+    if (typ.value === ReceiptType.cancellation.value) {
+        throw eingabefehler('Ein Storno geht nur ueber cancelReceipt (Bezug, Grund, Restmengen).');
+    }
     if (typ.needsItems) {
-        // Ein reiner Gutscheinverkauf ist ein Umsatz ohne Positionen — deshalb
+        // Ein reiner Gutscheinverkauf ist ein Umsatz ohne Positionen, deshalb
         // zaehlt er hier wie eine Position (wie im Flutter-Vorbild).
         const hatVerkaufsgutschein = vouchers?.some((v) => v.action === VoucherAction.sell) ?? false;
         if ((items == null || items.length === 0) && !hatVerkaufsgutschein) {
@@ -50,47 +90,20 @@ function createReceiptParams(options) {
     if (items != null && items.length > 0) {
         params['items'] = alsNutzlast(items, toReceiptItemPayload);
     }
-    // `payments: null` gilt wie im Backend (zahlungs-eingang.js) als nicht angegeben.
-    if (options.payments != null) {
-        // Der alte Storno-Weg und der Null-/Startbeleg nehmen keine Zahlungsliste
-        // (Backend: PAYMENTS_NOT_ALLOWED); ein Storno mit mehreren Zahlungen
-        // laeuft ueber cancelReceipt.
-        if (typ.value === ReceiptType.cancellation.value) {
-            throw eingabefehler('payments am Storno gehen nur ueber cancelReceipt.');
+    const umsatz = typ.value === ReceiptType.standard.value || typ.value === ReceiptType.training.value;
+    if (umsatz) {
+        // Pflicht unter /v3 (payments_required); eine leere Liste ist erlaubt,
+        // wenn nichts zu zahlen ist (Rabatt deckt alles).
+        if (options.payments == null) {
+            throw eingabefehler('payments fehlt: unter /v3 ist die Zahlungsliste Pflicht (Summe = receiptDueCents).');
         }
-        if (typ.value !== ReceiptType.standard.value && typ.value !== ReceiptType.training.value) {
-            throw eingabefehler(`payments sind bei receiptType "${typ.value}" nicht erlaubt.`);
-        }
-        const konflikt = zahlungsKonflikt(options);
-        if (konflikt != null)
-            throw eingabefehler(konflikt);
         params['payments'] = gepruefteZahlungen(options.payments, false, 'createReceipt');
     }
-    // Vom Aufrufer kommt sie geprueft, vom Server roh — siehe die beiden Felder
-    // in [CreateReceiptOptions]. Die Typpruefung allein reicht dafuer nicht: ein
-    // Verbraucher ohne Typen faellt durch dieses Netz, und ein Tippfehler in der
-    // Zahlungsart faellt sonst erst am Server auf.
-    const zahlungsart = options.paymentMethod != null ? gepruefteZahlungsart(options.paymentMethod) : options.paymentMethodFromServer;
-    if (zahlungsart != null) {
-        params['paymentMethod'] = zahlungsart;
-        const anbieter = options.creditCardProvider ?? CreditCardProvider.custom;
-        if (zahlungsart === KeckPaymentMethod.creditCard.value) {
-            if (options.cardPaymentId != null) {
-                params['cardPaymentId'] = options.cardPaymentId;
-                // Der Kartenanbieter kommt dagegen vom Aufrufer, nicht vom Server —
-                // hier bleibt der Schreibpfad streng.
-                params['creditCardProvider'] = kartenanbieter(anbieter);
-                // Bewusst auch als `null`, wenn der Anbieter keine Rohdaten liefert:
-                // das Feld gehoert zur Kartenzahlung und das Backend nimmt null an.
-                params['cardPaymentData'] = options.cardPaymentData ?? null;
-            }
-            else if (anbieter !== CreditCardProvider.custom) {
-                throw eingabefehler(`cardPaymentId ist Pflicht bei creditCardProvider "${anbieter}".`);
-            }
-        }
+    else if (options.payments != null) {
+        throw eingabefehler(`payments sind bei receiptType "${typ.value}" nicht erlaubt.`);
     }
     if (options.tip != null) {
-        if (typ.value !== ReceiptType.standard.value && typ.value !== ReceiptType.training.value) {
+        if (!umsatz) {
             throw eingabefehler(`Trinkgeld ist nur bei receiptType standard oder training moeglich, nicht bei "${typ.value}".`);
         }
         params['tip'] = gepruefterTip(options.tip);
@@ -106,16 +119,18 @@ function createReceiptParams(options) {
     }
     return params;
 }
+/** Felder des alten Einzel-Zahlungswegs; unter /v3 abgewiesen. */
+const ALTE_ZAHLFELDER = ['paymentMethod', 'paymentMethodFromServer', 'creditCardProvider', 'cardPaymentId', 'cardPaymentData'];
 /** Normalbeleg (Verkauf) nach RKSV. */
-export function sellReceipt(rufen, options) {
-    return createReceipt(rufen, { ...options, receiptType: ReceiptType.standard });
+export function sellReceipt(transport, options) {
+    return createReceipt(transport, { ...options, receiptType: ReceiptType.standard });
 }
 /**
  * Normalbeleg wie [sellReceipt], liefert zusaetzlich die Firmen-/Druckdaten
  * aus derselben Antwort — alles, was ein Belegdruck braucht, in einem Aufruf.
  */
-export function sellReceiptWithCompany(rufen, options) {
-    return createReceiptWithCompany(rufen, { ...options, receiptType: ReceiptType.standard });
+export function sellReceiptWithCompany(transport, options) {
+    return createReceiptWithCompany(transport, { ...options, receiptType: ReceiptType.standard });
 }
 const NOTE_MAX = 200;
 /**
@@ -124,7 +139,7 @@ const NOTE_MAX = 200;
  * Reichweite des Rechts (eigene/alle) und antwortet mit dem fertigen,
  * signierten Storno-Beleg. Gutscheine des Originals wandern nicht mit.
  */
-export async function cancelReceipt(rufen, options) {
+export async function cancelReceipt(transport, options) {
     const cashregisterId = options.receipt?.cashregisterId ?? options.cashregisterId;
     const originalReceiptId = options.receipt?.receiptId ?? options.originalReceiptId;
     if (typeof cashregisterId !== 'string' || cashregisterId.trim() === '') {
@@ -149,8 +164,14 @@ export async function cancelReceipt(rufen, options) {
     if (options.note !== undefined && options.note.length > NOTE_MAX) {
         throw new KasseneckValidationError('cancelReceipt', `Anmerkung ist zu lang (hoechstens ${NOTE_MAX} Zeichen)`, 'request');
     }
+    const altfeld = ALTE_ZAHLFELDER.find((feld) => options[feld] != null);
+    if (altfeld != null) {
+        throw new KasseneckValidationError('cancelReceipt', `${altfeld} gibt es unter /v3 nicht mehr: Rueckzahlungen gehen als payments hinaus.`, 'request');
+    }
     // `payments: null` gilt wie im Backend als nicht angegeben.
-    const zahlungen = options.payments != null ? gepruefteStornoZahlungen(options) : undefined;
+    const zahlungen = options.payments != null ? gepruefteZahlungen(options.payments, true, 'cancelReceipt') : undefined;
+    if (zahlungen !== undefined)
+        pruefeKartenRueckbuchung(zahlungen, options.receipt);
     const params = { cashregisterId, originalReceiptId, reason: options.reason };
     if (options.items !== undefined)
         params.items = options.items.map((p) => ({ index: p.index, quantity: p.quantity }));
@@ -158,27 +179,11 @@ export async function cancelReceipt(rufen, options) {
         params.note = options.note;
     if (zahlungen !== undefined)
         params.payments = zahlungen;
-    if (options.paymentMethod != null)
-        params.paymentMethod = gepruefteZahlungsart(options.paymentMethod);
-    const karte = options.creditCardProvider != null || options.cardPaymentId != null || options.cardPaymentData != null;
-    if (karte) {
-        // Ohne paymentMethod entscheidet das Backend an der Zahlungsart des
-        // Originals; ein ausdruecklich anderer Rueckzahlweg ist hier schon falsch.
-        if (params.paymentMethod != null && params.paymentMethod !== KeckPaymentMethod.creditCard.value) {
-            throw new KasseneckValidationError('cancelReceipt', 'Kartendaten gibt es nur bei paymentMethod creditCard', 'request');
-        }
-        if (options.creditCardProvider != null) {
-            if (!Object.prototype.hasOwnProperty.call(CreditCardProvider, options.creditCardProvider)) {
-                throw new KasseneckValidationError('cancelReceipt', `Kartenanbieter: unbekannter Schluessel "${options.creditCardProvider}"`, 'request');
-            }
-            params.creditCardProvider = options.creditCardProvider;
-        }
-        if (options.cardPaymentId != null && options.cardPaymentId !== '')
-            params.cardPaymentId = options.cardPaymentId;
-        if (options.cardPaymentData != null)
-            params.cardPaymentData = options.cardPaymentData;
-    }
-    const daten = await rufen('cancelReceipt', params);
+    const daten = await transport('cancelReceipt', params);
+    return signiertGelesen('cancelReceipt', () => stornoAusHuelle(daten));
+}
+/** Liest die Storno-Antwort `{ receipt, cancellationOf, remaining }`. */
+function stornoAusHuelle(daten) {
     const receipt = belegAusHuelle(daten, 'cancelReceipt');
     const huelle = daten;
     const bezug = huelle.cancellationOf;
@@ -190,27 +195,17 @@ export async function cancelReceipt(rufen, options) {
     }
     return {
         receipt,
-        cancellationOf: { receiptId: bezug.receiptId, fullReceiptId: typeof bezug.fullReceiptId === 'string' ? bezug.fullReceiptId : null },
+        cancellationOf: {
+            receiptId: bezug.receiptId,
+            fullReceiptId: typeof bezug.fullReceiptId === 'string' ? bezug.fullReceiptId : null,
+            ...(typeof bezug.timeStamp === 'string' && bezug.timeStamp !== '' ? { timeStamp: bezug.timeStamp } : {}),
+        },
         remaining: huelle.remaining,
     };
 }
-/**
- * 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.
- *
- * @deprecated Alter Storno-Weg ohne Bezug: kein Verweis auf das Original,
- * keine Restmengen, kein Schutz vor doppeltem Storno, Gutscheine werden nicht
- * zurueckgenommen. Das Backend nimmt ihn weiter an und legt `deprecation` in
- * die Antwort. Stattdessen [cancelReceipt] (Endpunkt `cancelReceipt`): Bezug,
- * Grund, Teilstorno, Fehlercodes.
- */
-export function createCancelReceipt(rufen, options) {
-    return createReceipt(rufen, { ...options, receiptType: ReceiptType.cancellation });
-}
 /** Nullbeleg (RKSV-Pruefbeleg) — ohne Positionen und ohne Zahlungsart. */
-export function zeroReceipt(rufen) {
-    return createReceipt(rufen, { receiptType: ReceiptType.zero });
+export function zeroReceipt(transport) {
+    return createReceipt(transport, { receiptType: ReceiptType.zero });
 }
 /**
  * Belege einer Kasse auflisten — die Grundlage jeder Belegliste in der
@@ -227,7 +222,7 @@ export function zeroReceipt(rufen) {
  * (der Endpunkt laeuft mit `checkCashRegister: false`), ein Kassen-Benutzer
  * bekommt also nur die ihm zugewiesenen Kassen.
  */
-export async function listMyReceipts(rufen, options) {
+export async function listMyReceipts(transport, options) {
     if (typeof options.cashregisterId !== 'string' || options.cashregisterId.trim() === '') {
         throw new KasseneckValidationError('listMyReceipts', 'cashregisterId fehlt', 'request');
     }
@@ -240,8 +235,8 @@ export async function listMyReceipts(rufen, options) {
             throw new KasseneckValidationError('listMyReceipts', `${feld} muss mit YYYY-MM-DD beginnen, war "${wert}"`, 'request');
         }
     }
-    const daten = await rufen('listMyReceipts', {
-        cashregisterid: options.cashregisterId,
+    const daten = await transport('listMyReceipts', {
+        cashregisterId: options.cashregisterId,
         limit: options.limit,
         ...(options.from !== undefined ? { from: options.from } : {}),
         ...(options.to !== undefined ? { to: options.to } : {}),
@@ -265,7 +260,7 @@ function kennzahlen(roh) {
     const tage = Array.isArray(quelle.days) ? quelle.days : [];
     return {
         today: {
-            revenueCents: euroToCents(quelle.today?.umsatz),
+            revenueCents: euroToCents(quelle.today?.revenue),
             count: typeof quelle.today?.count === 'number' ? quelle.today.count : 0,
         },
         trendPercent: typeof quelle.trendPct === 'number' ? quelle.trendPct : null,
@@ -273,14 +268,14 @@ function kennzahlen(roh) {
             const eintrag = (typeof tag === 'object' && tag !== null ? tag : {});
             return {
                 date: typeof eintrag.date === 'string' ? eintrag.date : '',
-                revenueCents: euroToCents(eintrag.umsatz),
+                revenueCents: euroToCents(eintrag.revenue),
             };
         }),
     };
 }
 /** Einzelnen Beleg der angemeldeten Kasse holen. */
-export async function getReceipt(rufen, receiptId) {
-    return belegAusHuelle(await rufen('getReceipt', { receiptId }), 'getReceipt');
+export async function getReceipt(transport, receiptId) {
+    return belegAusHuelle(await transport('getReceipt', { receiptId }), 'getReceipt');
 }
 /**
  * Wie [getReceipt], liefert zusaetzlich die Firmen-/Druckdaten aus derselben
@@ -288,15 +283,15 @@ export async function getReceipt(rufen, receiptId) {
  * Kleinunternehmer-Kennzeichen) — die Angaben, die ein Beleg im Kopf und Fuss
  * traegt (siehe models/receipt-company.ts).
  */
-export async function getReceiptWithCompany(rufen, receiptId) {
-    return belegMitFirmaAusHuelle(await rufen('getReceipt', { receiptId }), 'getReceipt');
+export async function getReceiptWithCompany(transport, receiptId) {
+    return belegMitFirmaAusHuelle(await transport('getReceipt', { receiptId }), 'getReceipt');
 }
 /**
  * Verschluesselte Volltext-Belegnummer erzeugen — der Bezeichner, unter dem der
  * Beleg oeffentlich abrufbar ist (Beleg-Download, Pruefportal).
  */
-export async function generateFullReceiptId(rufen, receiptId) {
-    const daten = await rufen('generateFullReceiptId', { receiptId });
+export async function generateFullReceiptId(transport, receiptId) {
+    const daten = await transport('generateFullReceiptId', { receiptId });
     const id = daten?.fullReceiptId;
     if (typeof id !== 'string') {
         throw antwortfehler('generateFullReceiptId', 'Antwort enthaelt keine fullReceiptId');
@@ -311,8 +306,8 @@ export async function generateFullReceiptId(rufen, receiptId) {
  * fuehrt kein `allowRegisterUser`, das Backend weist die Browser-Kasse hier ab
  * (siehe Modulkommentar oben). Mit `apiKeyAuth` ist er offen.
  */
-export async function getFirstReceiptDate(rufen) {
-    const roh = await rufen('getFirstReceiptDate');
+export async function getFirstReceiptDate(transport) {
+    const roh = await transport('getFirstReceiptDate');
     if (typeof roh !== 'string') {
         throw antwortfehler('getFirstReceiptDate', 'Antwort enthaelt keinen Zeitstempel');
     }
@@ -333,6 +328,8 @@ export async function getFirstReceiptDate(rufen) {
         throw antwortfehler('getFirstReceiptDate', 'Antwort enthaelt keinen lesbaren Zeitstempel');
     }
 }
+/** Felder von [SendReceiptEmailOptions]; jedes andere wirft vor dem Senden. */
+const MAIL_FELDER = ['fullReceiptId', 'to', 'language'];
 /**
  * Schickt einen bereits ausgestellten Beleg als **Link auf die oeffentliche
  * Belegseite** an eine Adresse (Endpunkt `sendReceiptEmail`, Backend
@@ -343,17 +340,23 @@ export async function getFirstReceiptDate(rufen) {
  * das Backend in einer Unter-Sammlung neben dem Beleg.
  *
  * **Am Code entscheiden, nie am Text:** fachliche Fehler kommen als
- * [KasseneckApiError] mit `code` aus [RECEIPT_EMAIL_ERROR_CODES] heraus —
- * `adresse_ungueltig`, `beleg_nicht_gefunden` (auch fuer einen Beleg einer
- * fremden Kasse: das Backend gibt darueber bewusst keine Auskunft), `zu_oft`
- * (5 Mails je Beleg in 24 Stunden, 30 je Kasse und Stunde) und
- * `versand_fehlgeschlagen`. Dieses Paket reicht sie unveraendert durch und
+ * [KasseneckApiError] mit `code` aus [RECEIPT_EMAIL_ERROR_CODES] heraus:
+ * `invalid_address`, `receipt_not_found` (auch fuer einen Beleg einer
+ * fremden Kasse: das Backend gibt darueber bewusst keine Auskunft),
+ * `too_many_requests` (5 Mails je Beleg in 24 Stunden, 30 je Kasse und
+ * Stunde) und `send_failed`. Dieses Paket reicht sie unveraendert durch und
  * legt keine eigenen Codes an.
  *
  * **Kein Wiederholen ohne Zutun des Bedieners:** ein zweiter Versuch schickt
  * eine zweite Mail und zaehlt auf die Schleuse.
  */
-export async function sendReceiptEmail(rufen, options) {
+export async function sendReceiptEmail(transport, options) {
+    // Ein unbekanntes Feld (etwa das alte `sprache`) ginge sonst still verloren,
+    // und die Mail kaeme in der falschen Sprache.
+    const fremd = Object.keys(options ?? {}).find((k) => !MAIL_FELDER.includes(k));
+    if (fremd != null) {
+        throw new KasseneckValidationError('sendReceiptEmail', `unbekanntes Feld "${fremd}"`, 'request');
+    }
     // Getrimmt, weil beides von Hand oder per Scanner ins Feld kommt und ein
     // angehaengtes Leerzeichen sonst als ungueltige Adresse zurueckkaeme --
     // nach einem Aufruf, der schon eine Zeile im Protokoll gekostet hat.
@@ -366,20 +369,21 @@ export async function sendReceiptEmail(rufen, options) {
         throw new KasseneckValidationError('sendReceiptEmail', 'to fehlt (Empfaengeradresse)', 'request');
     }
     // Die Adresse selbst wird hier NICHT geprueft: das Backend prueft sie mit
-    // kreiseck_validator und antwortet mit `adresse_ungueltig`. Eine zweite,
+    // kreiseck_validator und antwortet mit `invalid_address`. Eine zweite,
     // eigene Regel im Paket koennte strenger sein als die des Backends und eine
     // gueltige Adresse abweisen, ohne dass jemand die Abweichung bemerkt.
     const params = { fullReceiptId, to };
-    if (options.sprache !== undefined && options.sprache !== '')
-        params.sprache = options.sprache;
-    const daten = await rufen('sendReceiptEmail', params);
+    if (options.language !== undefined && options.language !== '')
+        params.language = options.language;
+    const daten = await transport('sendReceiptEmail', params);
     if (typeof daten?.to !== 'string' || daten.to === '') {
         throw antwortfehler('sendReceiptEmail', 'Antwort nennt keine Empfaengeradresse (data.to fehlt)');
     }
     if (typeof daten.at !== 'string' || daten.at === '') {
         throw antwortfehler('sendReceiptEmail', 'Antwort nennt keinen Zeitpunkt (data.at fehlt)');
     }
-    return { to: daten.to, at: daten.at, via: typeof daten.via === 'string' && daten.via !== '' ? daten.via : null };
+    const via = RECEIPT_EMAIL_VIAS.includes(daten.via) ? daten.via : null;
+    return { to: daten.to, at: daten.at, via };
 }
 /**
  * Prueft die Gutschein-Kombination eines Belegs und liefert den ersten
@@ -474,6 +478,11 @@ function gepruefterTip(tip) {
     if (tip == null || typeof tip !== 'object' || !istCentBetrag(tip.cents)) {
         throw eingabefehler('Trinkgeld: Betrag muss eine ganze Zahl in Cent > 0 sein.');
     }
+    // Ein unbekannter Schluessel (etwa das alte `sofortErhalten`) weist der
+    // Server unter /v3 ab; hier faellt er vor dem Senden.
+    const fremd = Object.keys(tip).find((k) => !TIP_FELDER.includes(k));
+    if (fremd != null)
+        throw eingabefehler(`Trinkgeld: unbekanntes Feld "${fremd}".`);
     const nutzlast = { cents: tip.cents };
     if (tip.paymentMethod != null)
         nutzlast['paymentMethod'] = gepruefteZahlungsart(tip.paymentMethod);
@@ -481,11 +490,11 @@ function gepruefterTip(tip) {
     // Voreinstellung des Betriebs. Ein `false` waere dort eine Aussage, kein
     // Weglassen. Der Wortlaut des Fehlers ist der des Backends
     // (tip-core.normalizeTip) -- wer ihn hier sieht, sieht denselben Satz.
-    if (tip.sofortErhalten != null) {
-        if (typeof tip.sofortErhalten !== 'boolean') {
-            throw eingabefehler('Trinkgeld: sofortErhalten muss true oder false sein.');
+    if (tip.receivedImmediately != null) {
+        if (typeof tip.receivedImmediately !== 'boolean') {
+            throw eingabefehler('Trinkgeld: receivedImmediately muss true oder false sein.');
         }
-        nutzlast['sofortErhalten'] = tip.sofortErhalten;
+        nutzlast['receivedImmediately'] = tip.receivedImmediately;
     }
     if (tip.recipients != null) {
         if (!Array.isArray(tip.recipients) || tip.recipients.length === 0) {
@@ -511,6 +520,7 @@ function gepruefterTip(tip) {
     }
     return nutzlast;
 }
+const TIP_FELDER = ['cents', 'paymentMethod', 'recipients', 'receivedImmediately'];
 /**
  * Zahlungsart des Aufrufers pruefen — unbekannt wirft, bevor etwas rausgeht.
  * `mixed` wirft ebenfalls: den Wert vergibt nur der Server (Beleg mit
@@ -534,18 +544,6 @@ function gepruefteZahlungsart(wert) {
 }
 /** Hoechstzahl der Zahlungen je Beleg (Backend: MAX_ZAHLUNGEN). */
 const MAX_ZAHLUNGEN = 20;
-/**
- * `payments` neben einer Einzel-Zahlungsart oder Kartenfeldern? Liefert den
- * Grund (Backend: PAYMENTS_CONFLICT), sonst null. Nie still eines bevorzugen.
- */
-function zahlungsKonflikt(options) {
-    for (const feld of ['paymentMethod', 'paymentMethodFromServer', 'creditCardProvider', 'cardPaymentId', 'cardPaymentData']) {
-        if (options[feld] != null) {
-            return `payments und ${feld} duerfen nicht gemeinsam gesendet werden – Kartenangaben gehoeren in die Zahlung.`;
-        }
-    }
-    return null;
-}
 /**
  * Zahlungsliste pruefen und in Nutzlast-Form bringen — Formpruefung wie
  * `pruefeZahlungen` im Backend, soweit sie ohne Beleg und Zahlbetrag geht
@@ -609,12 +607,53 @@ function gepruefteZahlungen(roh, storno, functionName) {
         return aus;
     });
 }
-/** `payments` am Storno: Konflikt mit Zahlungsart/Kartenfeldern, dann Form. */
-function gepruefteStornoZahlungen(options) {
-    const konflikt = zahlungsKonflikt(options);
-    if (konflikt != null)
-        throw new KasseneckValidationError('cancelReceipt', konflikt, 'request');
-    return gepruefteZahlungen(options.payments, true, 'cancelReceipt');
+/** Zahlarten mit Kartenterminal (Backend: KARTEN_ZAHLARTEN). */
+const KARTEN_ZAHLARTEN = new Set(['creditCard', 'uberCard', 'boltCard']);
+/**
+ * Kennung der Originalzahlung fuer die Rueckbuchung am Terminal (Hobex
+ * `originalTransactionId`, SumUp-Transaktion, ...): `providerPaymentId` der
+ * Zahlung `paymentId` des Originals. Die liefert nur der Kassenweg (Kanal
+ * `app`, `registerUserAuth`); am oeffentlichen Weg fehlt sie, und dann wirft
+ * dieser Aufruf, statt `undefined` an ein Terminal weiterzugeben.
+ */
+export function cardRefundReference(receipt, paymentId) {
+    const zahlung = receipt.payments?.find((z) => z.id === paymentId);
+    if (zahlung == null) {
+        throw new KasseneckValidationError('cancelReceipt', `Zahlung "${paymentId}" gibt es am Beleg nicht`, 'request');
+    }
+    const methode = typeof zahlung.method === 'object' ? zahlung.method.value : zahlung.method;
+    if (!KARTEN_ZAHLARTEN.has(methode)) {
+        throw new KasseneckValidationError('cancelReceipt', `Zahlung "${paymentId}" ist keine Kartenzahlung`, 'request');
+    }
+    if (typeof zahlung.providerPaymentId !== 'string' || zahlung.providerPaymentId === '') {
+        throw new KasseneckValidationError('cancelReceipt', `Kennung der Kartenzahlung "${paymentId}" fehlt: sie kommt nur ueber den Kassenweg (registerUserAuth, kasse.kasseneck.at/api/v3), nicht ueber den oeffentlichen Weg`, 'request');
+    }
+    return zahlung.providerPaymentId;
+}
+/**
+ * Karten-Rueckbuchung am Storno, geprueft vor dem Senden:
+ * - Sie nennt ihren Anbieter (`provider`; `custom` fuer eine Erstattung
+ *   ohne angebundenes Terminal). Ganz ohne Anbieterfelder faellt sie.
+ * - Ueber einen Anbieter (nicht `custom`) braucht sie einen Bezug: ihre eigene
+ *   Terminal-Kennung (`providerPaymentId` der Erstattung) oder, liegt das
+ *   Original vor, die Kennung der erstatteten Kartenzahlung dort. Erst wenn
+ *   beides fehlt, wirft sie.
+ */
+function pruefeKartenRueckbuchung(zahlungen, original) {
+    zahlungen.forEach((z, i) => {
+        if (!KARTEN_ZAHLARTEN.has(String(z['method'])))
+            return;
+        const anbieter = z['provider'];
+        if (anbieter == null && z['providerPaymentId'] == null) {
+            throw new KasseneckValidationError('cancelReceipt', `Zahlung ${i + 1}: Karten-Rueckbuchung ohne Anbieter und ohne Kennung (provider angeben, custom fuer eine Erstattung ohne angebundenes Terminal)`, 'request');
+        }
+        if (anbieter === CreditCardProvider.custom || z['providerPaymentId'] != null)
+            return;
+        const orig = original != null && typeof z['refundOf'] === 'string' ? original.payments?.find((o) => o.id === z['refundOf']) : undefined;
+        if (typeof orig?.providerPaymentId === 'string' && orig.providerPaymentId !== '')
+            return;
+        throw new KasseneckValidationError('cancelReceipt', `Zahlung ${i + 1}: Karten-Rueckbuchung ohne Bezug: providerPaymentId der Erstattung am Terminal angeben (oder das Original ueber den Kassenweg lesen, dort traegt es die Kennung der Kartenzahlung)`, 'request');
+    });
 }
 /** Kartenanbieter pruefen — er stammt vom Aufrufer, nicht aus Serverdaten. */
 function kartenanbieter(wert) {
@@ -627,6 +666,24 @@ function kartenanbieter(wert) {
 function eingabefehler(grund) {
     return new KasseneckValidationError('createReceipt', grund, 'request');
 }
+/**
+ * Liest die Erfolgsantwort eines **signierenden** Aufrufs. Scheitert das
+ * Lesen (fehlender Beleg, fehlender Bezug, unbrauchbares Feld oder ein
+ * Laufzeitfehler beim Umwandeln), hat der Server trotzdem Erfolg gemeldet:
+ * der Beleg ist signiert und im DEP. Das darf nie als gewoehnlicher Fehler
+ * enden, sonst kassiert die Kasse ein zweites Mal. Darum wird daraus
+ * `KasseneckApiError` mit Code `response_unreadable` und `outcome: 'unknown'`.
+ * Der Grund stammt vom Paket; aus der Antwort selbst wird nichts uebernommen.
+ */
+function signiertGelesen(functionName, lesen) {
+    try {
+        return lesen();
+    }
+    catch (ursache) {
+        const grund = ursache instanceof KasseneckValidationError ? ursache.reason : 'Antwort nicht lesbar';
+        throw new KasseneckApiError(functionName, `Erfolg gemeldet, Antwort aber unlesbar (${grund}). Der Vorgang kann ausgefuehrt sein: nicht wiederholen, sondern nachlesen.`, {}, 'response_unreadable');
+    }
+}
 /** Die Antwort meldete Erfolg, trug aber nicht, was der Aufruf zusagt. */
 function antwortfehler(functionName, grund) {
     return new KasseneckValidationError(functionName, grund, 'response');
@@ -638,8 +695,11 @@ function antwortfehler(functionName, grund) {
  * models/receipt.ts), und die bestehenden Aufrufe sollen ihre Zusage behalten.
  * Wer beides braucht, nimmt [belegMitFirmaAusHuelle] ueber die
  * `…WithCompany`-Varianten.
+ *
+ * Paketintern exportiert, damit `./stored` gespeicherte Belege mit demselben
+ * Leser liest; nicht Teil der Paketoberflaeche.
  */
-function belegAusHuelle(daten, functionName) {
+export function belegAusHuelle(daten, functionName) {
     const huelle = daten;
     if (huelle == null || typeof huelle !== 'object' || huelle.receipt == null) {
         throw antwortfehler(functionName, 'Antwort enthaelt keinen Beleg (data.receipt fehlt)');
@@ -667,21 +727,34 @@ function belegAusHuelle(daten, functionName) {
  * fehlt er, ist die Antwort unbrauchbar. Die Firmendaten duerfen dagegen
  * luecken haben — ein Kundendokument ohne gepflegte Fusszeile ist kein Grund,
  * einen ausgestellten Beleg nicht anzuzeigen (siehe models/receipt-company.ts).
+ * Paketintern exportiert wie [belegAusHuelle].
  */
-function belegMitFirmaAusHuelle(daten, functionName) {
+export function belegMitFirmaAusHuelle(daten, functionName) {
     const receipt = belegAusHuelle(daten, functionName);
     const d = (daten ?? {});
     const layout = d.layout && typeof d.layout === 'object' && Array.isArray(d.layout.lines) ? d.layout : null;
-    const pa = d.pruefangaben && typeof d.pruefangaben === 'object' ? d.pruefangaben : null;
-    const text = (v) => (typeof v === 'string' && v ? v : null);
+    const angaben = d.registrationInfo && typeof d.registrationInfo === 'object' ? readRegistrationInfo(d.registrationInfo) : null;
     return {
         receipt,
         company: fromReceiptCompanyPayload(daten),
-        testKasse: d.testKasse === true,
-        testSignatur: d.testSignatur === true,
-        kopfId: typeof d.kopfId === 'string' ? d.kopfId : null,
+        testCashregister: d.testCashregister === true,
+        testSignature: d.testSignature === true,
+        headerVersionId: typeof d.headerVersionId === 'string' && d.headerVersionId !== '' ? d.headerVersionId : null,
         layout,
-        pruefangaben: pa ? { karteRegistriertAm: text(pa.karteRegistriertAm), kasseRegistriertAm: text(pa.kasseRegistriertAm) } : null,
-        logoStufe: d.logo_skala === 'S' || d.logo_skala === 'M' || d.logo_skala === 'L' || d.logo_skala === 'XL' ? d.logo_skala : 'M',
+        registrationInfo: angaben,
+        logoScale: d.logo_scale === 'S' || d.logo_scale === 'M' || d.logo_scale === 'L' || d.logo_scale === 'XL' ? d.logo_scale : 'M',
     };
 }
+/**
+ * Zahlbetrag des Servers aus einem `payments_sum_mismatch`
+ * (`details.expectedCents`), sonst `undefined`. Das Paket wiederholt nie
+ * selbst mit diesem Betrag: eine Kartenzahlung ist schon belastet. Die Kasse
+ * entscheidet (Differenz nachkassieren oder erstatten) und schickt dann einen
+ * neuen Verkauf.
+ */
+export function paymentsExpectedCents(error) {
+    if (!isKasseneckApiError(error) || error.code !== 'payments_sum_mismatch')
+        return undefined;
+    const wert = error.details['expectedCents'];
+    return Number.isSafeInteger(wert) ? wert : undefined;
+}

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

@@ -1,5 +1,5 @@
-import type { ReportMonth } from '../models/index.js';
-import type { InternerBinaerTransport } from './aufrufe.js';
+import { type Receipt, type ReceiptCompany, type ReportMonth } from '../models/index.js';
+import type { InternerBinaerTransport, InternerTransport } from './aufrufe.js';
 /**
  * Bericht-Downloads — Zwilling von `downloadDailyReport`/`downloadMonthlyReport`
  * in kasseneck_api/lib/kasseneck_api.dart (Zeilen 113-128).
@@ -29,7 +29,7 @@ import type { InternerBinaerTransport } from './aufrufe.js';
  * Vortags holen (das Dart-Vorbild nimmt hier die Geraetezeit, was auf einer
  * oesterreichischen Kasse zufaellig stimmt).
  */
-export declare function downloadDailyReport(rufen: InternerBinaerTransport, date: Date): Promise<Uint8Array>;
+export declare function downloadDailyReport(transport: InternerBinaerTransport, date: Date): Promise<Uint8Array>;
 /**
  * Monatsbericht als PDF.
  *
@@ -40,4 +40,26 @@ export declare function downloadDailyReport(rufen: InternerBinaerTransport, date
  * `month` geht als **Zahl 1-12** raus (im Flutter-Paket `reportMonth.month.id`,
  * wo `KeckMonth.january.id === 1` ist) — kein Name, kein nullbasierter Index.
  */
-export declare function downloadMonthlyReport(rufen: InternerBinaerTransport, reportMonth: ReportMonth): Promise<Uint8Array>;
+export declare function downloadMonthlyReport(transport: InternerBinaerTransport, reportMonth: ReportMonth): Promise<Uint8Array>;
+/** Zeitfenster von [getReportV2]: Wiener Wanduhr, `YYYY-MM-DD` oder voller Zeitstempel, `end` ausschliesslich. */
+export interface ReportV2Options {
+    start: string;
+    end: string;
+}
+/** Firmendaten des Berichts: die Beleg-Firmendaten plus die Bezeichnung der Kasse. */
+export interface ReportV2Metadata extends ReceiptCompany {
+    /** Bezeichnung der Kasse; leer, wenn keine gepflegt ist. */
+    label: string;
+}
+export interface ReportV2 {
+    /** Alle Belege der angemeldeten Kasse mit `start <= timeStamp < end`. */
+    receipts: Receipt[];
+    metadata: ReportV2Metadata;
+}
+/**
+ * Rohdaten eines Zeitraums (`getReportV2`): alle Belege der Kasse und die
+ * Firmendaten fuer Kopf und Fuss. Der Server vergleicht die Zeitstempel als
+ * Text (`start <= timeStamp < end`), darum Wiener Wanduhr im Serverformat.
+ * Nur ueber den API-Schluessel-Weg (Kasse aus dem `cashregister-token`).
+ */
+export declare function getReportV2(transport: InternerTransport, options: ReportV2Options): Promise<ReportV2>;