@kreiseck/kasseneck-api 0.6.7

package/dist/esm/client/receipts.js

@@ -0,0 +1,438 @@
+import { ReceiptType, KeckPaymentMethod, CreditCardProvider, VoucherAction, VoucherType, } from '../enums/index.js';
+import { fromReceiptCompanyPayload, fromReceiptPayload, toReceiptItemPayload, toVoucherPayload, receiptItemIsValid, voucherIsValid, fromReceiptSummaryPayload, isCancellationReason, } from '../models/index.js';
+import { parseServerTimeStamp, toViennaWallClock } from '../vienna-time.js';
+import { euroToCents } from '../money.js';
+import { KasseneckValidationError } from './errors.js';
+/**
+ * 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');
+}
+/** Wie [createReceipt], liest aus derselben Antwort zusaetzlich die Firmendaten. */
+async function createReceiptWithCompany(rufen, options) {
+    return belegMitFirmaAusHuelle(await rufen('createReceipt', createReceiptParams(options)), 'createReceipt');
+}
+/**
+ * Baut die Nutzlast von `createReceipt` und prueft die Eingabe. Wirft, bevor
+ * irgendetwas rausgeht — ein Beleg ist nicht folgenlos wiederholbar.
+ */
+function createReceiptParams(options) {
+    const typ = belegtyp(options.receiptType);
+    const { items, vouchers } = options;
+    if (typ.needsItems) {
+        // 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) {
+            throw eingabefehler(`Positionen sind Pflicht bei receiptType "${typ.value}" und duerfen nicht leer sein.`);
+        }
+        if (items?.some((item) => !receiptItemIsValid(item)) ?? false) {
+            throw eingabefehler('Ungueltige Position uebergeben.');
+        }
+    }
+    const params = { receiptType: typ.value };
+    if (vouchers != null && vouchers.length > 0) {
+        if (!typ.allowsVouchers) {
+            throw eingabefehler(`Gutscheine sind nicht erlaubt bei receiptType "${typ.value}".`);
+        }
+        if (vouchers.some((voucher) => !voucherIsValid(voucher))) {
+            throw eingabefehler('Ungueltiger Gutschein uebergeben.');
+        }
+        const kombinationsfehler = checkVoucherCombinationError(vouchers, items ?? []);
+        if (kombinationsfehler != null) {
+            throw eingabefehler(kombinationsfehler);
+        }
+        params['vouchers'] = alsNutzlast(vouchers, toVoucherPayload);
+    }
+    if (items != null && items.length > 0) {
+        params['items'] = alsNutzlast(items, toReceiptItemPayload);
+    }
+    // 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}".`);
+            }
+        }
+    }
+    if (options.customProjectId != null) {
+        params['customProjectId'] = options.customProjectId;
+    }
+    if (options.customerDetails != null) {
+        params['customerDetails'] = options.customerDetails.join('\n');
+    }
+    if (options.legalMessage != null) {
+        params['legalMessage'] = options.legalMessage.join('\n');
+    }
+    return params;
+}
+/** Normalbeleg (Verkauf) nach RKSV. */
+export function sellReceipt(rufen, options) {
+    return createReceipt(rufen, { ...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 });
+}
+const NOTE_MAX = 200;
+/**
+ * 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 async function cancelReceipt(rufen, options) {
+    const cashregisterId = options.receipt?.cashregisterId ?? options.cashregisterId;
+    const originalReceiptId = options.receipt?.receiptId ?? options.originalReceiptId;
+    if (typeof cashregisterId !== 'string' || cashregisterId.trim() === '') {
+        throw new KasseneckValidationError('cancelReceipt', 'cashregisterId fehlt', 'request');
+    }
+    if (typeof originalReceiptId !== 'string' || originalReceiptId.trim() === '') {
+        throw new KasseneckValidationError('cancelReceipt', 'originalReceiptId fehlt', 'request');
+    }
+    if (!isCancellationReason(options.reason)) {
+        throw new KasseneckValidationError('cancelReceipt', 'Storno-Grund fehlt oder ist unbekannt', 'request');
+    }
+    if (options.items !== undefined) {
+        if (!Array.isArray(options.items) || options.items.length === 0) {
+            throw new KasseneckValidationError('cancelReceipt', 'items muss eine nicht leere Liste sein', 'request');
+        }
+        for (const pos of options.items) {
+            if (!Number.isInteger(pos.index) || pos.index < 0 || !Number.isInteger(pos.quantity) || pos.quantity < 1) {
+                throw new KasseneckValidationError('cancelReceipt', 'Storno-Menge muss eine ganze Zahl >= 1 sein', 'request');
+            }
+        }
+    }
+    if (options.note !== undefined && options.note.length > NOTE_MAX) {
+        throw new KasseneckValidationError('cancelReceipt', `Anmerkung ist zu lang (hoechstens ${NOTE_MAX} Zeichen)`, 'request');
+    }
+    const params = { cashregisterId, originalReceiptId, reason: options.reason };
+    if (options.items !== undefined)
+        params.items = options.items.map((p) => ({ index: p.index, quantity: p.quantity }));
+    if (options.note !== undefined && options.note !== '')
+        params.note = options.note;
+    if (options.paymentMethod != null)
+        params.paymentMethod = gepruefteZahlungsart(options.paymentMethod);
+    const daten = await rufen('cancelReceipt', params);
+    const receipt = belegAusHuelle(daten, 'cancelReceipt');
+    const huelle = daten;
+    const bezug = huelle.cancellationOf;
+    if (bezug == null || typeof bezug.receiptId !== 'string') {
+        throw antwortfehler('cancelReceipt', 'Antwort enthaelt keinen Bezug (data.cancellationOf fehlt)');
+    }
+    if (!Array.isArray(huelle.remaining) || !huelle.remaining.every((n) => Number.isInteger(n))) {
+        throw antwortfehler('cancelReceipt', 'Antwort enthaelt keine Restmengen (data.remaining fehlt)');
+    }
+    return {
+        receipt,
+        cancellationOf: { receiptId: bezug.receiptId, fullReceiptId: typeof bezug.fullReceiptId === 'string' ? bezug.fullReceiptId : null },
+        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.
+ */
+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 });
+}
+/**
+ * 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 async function listMyReceipts(rufen, options) {
+    if (typeof options.cashregisterId !== 'string' || options.cashregisterId.trim() === '') {
+        throw new KasseneckValidationError('listMyReceipts', 'cashregisterId fehlt', 'request');
+    }
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1)) {
+        throw new KasseneckValidationError('listMyReceipts', `limit muss eine ganze Zahl ab 1 sein, war "${options.limit}"`, 'request');
+    }
+    for (const feld of ['from', 'to']) {
+        const wert = options[feld];
+        if (wert !== undefined && !/^\d{4}-\d{2}-\d{2}/.test(wert)) {
+            throw new KasseneckValidationError('listMyReceipts', `${feld} muss mit YYYY-MM-DD beginnen, war "${wert}"`, 'request');
+        }
+    }
+    const daten = await rufen('listMyReceipts', {
+        cashregisterid: options.cashregisterId,
+        limit: options.limit,
+        ...(options.from !== undefined ? { from: options.from } : {}),
+        ...(options.to !== undefined ? { to: options.to } : {}),
+    });
+    const liste = daten?.receipts;
+    if (!Array.isArray(liste)) {
+        throw antwortfehler('listMyReceipts', 'Antwort enthaelt keine Belegliste (data.receipts fehlt)');
+    }
+    return {
+        receipts: liste.map((eintrag) => fromReceiptSummaryPayload((typeof eintrag === 'object' && eintrag !== null ? eintrag : {}))),
+        stats: kennzahlen(daten?.stats),
+    };
+}
+/**
+ * Kennzahlen aus der Antwort. Sie duerfen Luecken haben, ohne die Belegliste
+ * unbrauchbar zu machen — eine fehlende Wochenreihe ist kein Grund, dem
+ * Kassier die Belege vorzuenthalten.
+ */
+function kennzahlen(roh) {
+    const quelle = (typeof roh === 'object' && roh !== null ? roh : {});
+    const tage = Array.isArray(quelle.days) ? quelle.days : [];
+    return {
+        today: {
+            revenueCents: euroToCents(quelle.today?.umsatz),
+            count: typeof quelle.today?.count === 'number' ? quelle.today.count : 0,
+        },
+        trendPercent: typeof quelle.trendPct === 'number' ? quelle.trendPct : null,
+        days: tage.map((tag) => {
+            const eintrag = (typeof tag === 'object' && tag !== null ? tag : {});
+            return {
+                date: typeof eintrag.date === 'string' ? eintrag.date : '',
+                revenueCents: euroToCents(eintrag.umsatz),
+            };
+        }),
+    };
+}
+/** Einzelnen Beleg der angemeldeten Kasse holen. */
+export async function getReceipt(rufen, receiptId) {
+    return belegAusHuelle(await rufen('getReceipt', { receiptId }), 'getReceipt');
+}
+/**
+ * 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 async function getReceiptWithCompany(rufen, receiptId) {
+    return belegMitFirmaAusHuelle(await rufen('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 });
+    const id = daten?.fullReceiptId;
+    if (typeof id !== 'string') {
+        throw antwortfehler('generateFullReceiptId', 'Antwort enthaelt keine fullReceiptId');
+    }
+    return id;
+}
+/**
+ * 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 async function getFirstReceiptDate(rufen) {
+    const roh = await rufen('getFirstReceiptDate');
+    if (typeof roh !== 'string') {
+        throw antwortfehler('getFirstReceiptDate', 'Antwort enthaelt keinen Zeitstempel');
+    }
+    // Ueber die Wiener Wanduhrzeit statt ueber getMonth(): der erste Beleg eines
+    // Monats liegt gern kurz nach Mitternacht, und der eingebaute Monat waere der
+    // des ausfuehrenden Rechners (siehe vienna-time.ts).
+    //
+    // Die Deutung wirft ein gewoehnliches Error, wenn der Zeitstempel unlesbar
+    // ist. Das ist hier ein Antwortproblem und gehoert in die Fehler-Union, die
+    // dieser Endpunkt zusagt — sonst faellt der Aufrufer aus allen Waechtern.
+    try {
+        const wanduhr = toViennaWallClock(parseServerTimeStamp(roh));
+        return { month: wanduhr.month, year: wanduhr.year };
+    }
+    catch {
+        // Der Zeitstempel selbst wandert NICHT in die Meldung: er kommt aus einer
+        // fremden Antwort, und was dort steht, ist nicht unsere Zusage.
+        throw antwortfehler('getFirstReceiptDate', 'Antwort enthaelt keinen lesbaren Zeitstempel');
+    }
+}
+/**
+ * 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 function checkVoucherCombinationError(vouchers, items) {
+    let einloesenWert = 0;
+    let verkaufenWert = 0;
+    let einloesenPromo = 0;
+    let verkaufenPromo = 0;
+    for (const voucher of vouchers) {
+        if (voucher.type === VoucherType.value && voucher.action === VoucherAction.redeem) {
+            einloesenWert++;
+        }
+        else if (voucher.type === VoucherType.value && voucher.action === VoucherAction.sell) {
+            verkaufenWert++;
+        }
+        else if (voucher.type === VoucherType.promo && voucher.action === VoucherAction.redeem) {
+            einloesenPromo++;
+        }
+        else if (voucher.type === VoucherType.promo && voucher.action === VoucherAction.sell) {
+            verkaufenPromo++;
+        }
+    }
+    const einloesenGesamt = einloesenWert + einloesenPromo;
+    const verkaufenGesamt = verkaufenWert + verkaufenPromo;
+    if (verkaufenPromo > 0) {
+        return 'Ungueltige Daten: Gutscheine mit type promo duerfen nicht verkauft werden';
+    }
+    if (einloesenPromo > 1) {
+        return 'Ungueltige Daten: Es darf nur ein Gutschein mit type promo eingeloest werden';
+    }
+    if (einloesenPromo > 0 && einloesenGesamt > 1) {
+        return 'Ungueltige Daten: Ein Gutschein mit type promo darf nicht mit anderen Gutscheinen kombiniert werden';
+    }
+    if (einloesenPromo > 0 && verkaufenGesamt > 0) {
+        return 'Ungueltige Daten: Mit einem Gutschein mit type promo duerfen nicht andere Gutscheine verkauft werden';
+    }
+    if (einloesenGesamt > 0 && items.length === 0) {
+        return 'Ungueltige Daten: Gutscheine mit action redeem benoetigen mindestens ein item';
+    }
+    return null;
+}
+/**
+ * Belegtyp aufloesen. Anders als bei der Zahlungsart bleibt es hier streng:
+ * den Belegtyp setzt kein Aufrufer aus Serverdaten, er kommt aus einem der
+ * benannten Aufrufe — ein unbekannter Wert waere ein Programmierfehler.
+ */
+function belegtyp(wert) {
+    if (typeof wert === 'object') {
+        return wert;
+    }
+    if (!Object.prototype.hasOwnProperty.call(ReceiptType, wert)) {
+        throw eingabefehler(`Belegtyp: unbekannter Schluessel "${wert}"`);
+    }
+    return ReceiptType[wert];
+}
+/**
+ * Wandelt Positionen/Gutscheine in ihre Nutzlast und faengt dabei die strengen
+ * Schreibpfad-Pruefungen der Modelle ab (unbekannter Steuersatz, unbekannte
+ * Gutschein-Aktion). Die Modelle werfen dort ein nacktes `Error`; hier soll
+ * nur die Fehler-Union des Pakets herauskommen, damit ein Verbraucher, der
+ * nach den Waechtern verzweigt, nicht im "unbekannt"-Zweig landet.
+ */
+function alsNutzlast(werte, wandeln) {
+    try {
+        return werte.map(wandeln);
+    }
+    catch (ursache) {
+        // Die Meldungen der Modelle sind vom Paket formuliert und geheimnisfrei
+        // (sie nennen den unbekannten Steuersatz bzw. Schluessel, sonst nichts).
+        throw eingabefehler(ursache instanceof Error ? ursache.message : 'Ungueltige Nutzlast uebergeben.');
+    }
+}
+/** Zahlungsart des Aufrufers pruefen — unbekannt wirft, bevor etwas rausgeht. */
+function gepruefteZahlungsart(wert) {
+    if (typeof wert === 'object') {
+        return wert.value;
+    }
+    if (!Object.prototype.hasOwnProperty.call(KeckPaymentMethod, wert)) {
+        throw eingabefehler(`Zahlungsart: unbekannter Schluessel "${wert}"`);
+    }
+    return KeckPaymentMethod[wert].value;
+}
+/** Kartenanbieter pruefen — er stammt vom Aufrufer, nicht aus Serverdaten. */
+function kartenanbieter(wert) {
+    if (!Object.prototype.hasOwnProperty.call(CreditCardProvider, wert)) {
+        throw eingabefehler(`Kartenanbieter: unbekannter Schluessel "${wert}"`);
+    }
+    return wert;
+}
+/** Fehler in der Eingabe des Aufrufers — es geht keine Anfrage raus. */
+function eingabefehler(grund) {
+    return new KasseneckValidationError('createReceipt', grund, 'request');
+}
+/** Die Antwort meldete Erfolg, trug aber nicht, was der Aufruf zusagt. */
+function antwortfehler(functionName, grund) {
+    return new KasseneckValidationError(functionName, grund, 'response');
+}
+/**
+ * `createReceipt` und `getReceipt` liefern den Beleg unter `data.receipt`,
+ * daneben die Firmen-/Druckdaten (Firma, Anschrift, Fusszeilen). Diese Lesart
+ * nimmt nur den Beleg: die Druckdaten gehoeren nicht zum RKSV-Kernbeleg (siehe
+ * models/receipt.ts), und die bestehenden Aufrufe sollen ihre Zusage behalten.
+ * Wer beides braucht, nimmt [belegMitFirmaAusHuelle] ueber die
+ * `…WithCompany`-Varianten.
+ */
+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)');
+    }
+    const beleg = huelle.receipt;
+    if (typeof beleg !== 'object' || Array.isArray(beleg)) {
+        throw antwortfehler(functionName, 'Antwort enthaelt keinen Beleg (data.receipt ist kein Objekt)');
+    }
+    // Positionen und Gutscheine werden gleich mit `.map` gelesen. Eine Antwort,
+    // die dort etwas anderes als eine Liste fuehrt, ergab bis hierher einen
+    // nackten TypeError ("… .map is not a function") und fiel damit aus der
+    // Fehler-Union. Fehlend und `null` bleiben erlaubt: Nullbelege haben keine
+    // Positionen.
+    const roh = beleg;
+    for (const feld of ['items', 'vouchers']) {
+        const wert = roh[feld];
+        if (wert != null && !Array.isArray(wert)) {
+            throw antwortfehler(functionName, `Antwort enthaelt einen Beleg mit unbrauchbarem Feld "${feld}"`);
+        }
+    }
+    return fromReceiptPayload(beleg);
+}
+/**
+ * Beleg **und** Firmendaten aus derselben Huelle. Der Beleg entscheidet:
+ * 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).
+ */
+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);
+    return {
+        receipt,
+        company: fromReceiptCompanyPayload(daten),
+        testKasse: d.testKasse === true,
+        testSignatur: d.testSignatur === true,
+        kopfId: typeof d.kopfId === 'string' ? d.kopfId : null,
+        layout,
+        pruefangaben: pa ? { karteRegistriertAm: text(pa.karteRegistriertAm), kasseRegistriertAm: text(pa.kasseRegistriertAm) } : null,
+    };
+}

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

@@ -0,0 +1,43 @@
+import type { ReportMonth } from '../models/index.js';
+import type { KasseneckBinaryTransport } from './transport.js';
+/**
+ * Bericht-Downloads — Zwilling von `downloadDailyReport`/`downloadMonthlyReport`
+ * in kasseneck_api/lib/kasseneck_api.dart (Zeilen 113-128).
+ *
+ * **Beide liefern ein PDF, also Binaerdaten.** Das Flutter-Vorbild liest die
+ * Antwort als Zeichenkette und nimmt davon `codeUnits`; in JavaScript waere das
+ * schlicht falsch — `response.text()` deutet die Bytes als UTF-8 und ersetzt
+ * jedes Byte ueber 0x7F durch U+FFFD. Ein so "heruntergeladener" Tagesbericht
+ * liesse sich in keinem Betrachter oeffnen. Dieses Paket weicht daher bewusst
+ * ab: es liest `arrayBuffer()` und liefert `Uint8Array` (siehe
+ * [createBinaryTransport] in transport.ts).
+ *
+ * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** Keiner der
+ * beiden Download-Endpunkte setzt `allowRegisterUser`; sie funktionieren nur
+ * mit `apiKeyAuth`. Dieses Paket bildet das **nicht** nach; wer darf,
+ * entscheidet allein das Backend. Der Hinweis steht hier, damit ein Leser
+ * nicht raten muss.
+ */
+/**
+ * Tagesbericht als PDF.
+ *
+ * Der Kalendertag wird nach **Wiener** Wanduhrzeit bestimmt, nicht nach der
+ * Zeitzone des ausfuehrenden Rechners: der Geschaeftstag ist ein
+ * oesterreichischer Kalenderwert. Ein Zeitpunkt vom 1. Maerz 00:30 Wiener Zeit
+ * gehoert in den Tagesbericht vom 1. Maerz — die eingebauten
+ * `getDate()`/`getMonth()` wuerden auf einer UTC-Maschine den Bericht des
+ * Vortags holen (das Dart-Vorbild nimmt hier die Geraetezeit, was auf einer
+ * oesterreichischen Kasse zufaellig stimmt).
+ */
+export declare function downloadDailyReport(rufen: KasseneckBinaryTransport, date: Date): Promise<Uint8Array>;
+/**
+ * Monatsbericht als PDF.
+ *
+ * **Der Endpunkt heisst `downloadReport`**, nicht `downloadMonthlyReport` —
+ * Methodenname und Endpunktname fallen hier auseinander (so im Dart-Vorbild und
+ * so im Backend, `report-endpoints.js`).
+ *
+ * `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: KasseneckBinaryTransport, reportMonth: ReportMonth): Promise<Uint8Array>;

package/dist/esm/client/reports.js

@@ -0,0 +1,69 @@
+import { toViennaWallClock } from '../vienna-time.js';
+import { KasseneckValidationError } from './errors.js';
+/**
+ * Bericht-Downloads — Zwilling von `downloadDailyReport`/`downloadMonthlyReport`
+ * in kasseneck_api/lib/kasseneck_api.dart (Zeilen 113-128).
+ *
+ * **Beide liefern ein PDF, also Binaerdaten.** Das Flutter-Vorbild liest die
+ * Antwort als Zeichenkette und nimmt davon `codeUnits`; in JavaScript waere das
+ * schlicht falsch — `response.text()` deutet die Bytes als UTF-8 und ersetzt
+ * jedes Byte ueber 0x7F durch U+FFFD. Ein so "heruntergeladener" Tagesbericht
+ * liesse sich in keinem Betrachter oeffnen. Dieses Paket weicht daher bewusst
+ * ab: es liest `arrayBuffer()` und liefert `Uint8Array` (siehe
+ * [createBinaryTransport] in transport.ts).
+ *
+ * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):** Keiner der
+ * beiden Download-Endpunkte setzt `allowRegisterUser`; sie funktionieren nur
+ * mit `apiKeyAuth`. Dieses Paket bildet das **nicht** nach; wer darf,
+ * entscheidet allein das Backend. Der Hinweis steht hier, damit ein Leser
+ * nicht raten muss.
+ */
+/**
+ * Tagesbericht als PDF.
+ *
+ * Der Kalendertag wird nach **Wiener** Wanduhrzeit bestimmt, nicht nach der
+ * Zeitzone des ausfuehrenden Rechners: der Geschaeftstag ist ein
+ * oesterreichischer Kalenderwert. Ein Zeitpunkt vom 1. Maerz 00:30 Wiener Zeit
+ * gehoert in den Tagesbericht vom 1. Maerz — die eingebauten
+ * `getDate()`/`getMonth()` wuerden auf einer UTC-Maschine den Bericht des
+ * Vortags holen (das Dart-Vorbild nimmt hier die Geraetezeit, was auf einer
+ * oesterreichischen Kasse zufaellig stimmt).
+ */
+// `async`, damit auch die Eingabepruefung als abgelehntes Versprechen ankommt
+// und nicht als synchroner Wurf am `await` des Aufrufers vorbei.
+export async function downloadDailyReport(rufen, date) {
+    let wanduhr;
+    try {
+        wanduhr = toViennaWallClock(date);
+    }
+    catch {
+        // Ein Invalid Date ergaebe sonst `{year: null, month: null, day: null}` im
+        // Rumpf (JSON.stringify macht aus NaN null) und einen ratlosen Serverfehler.
+        throw eingabefehler('downloadDailyReport', 'Uebergebener Zeitpunkt ist unbrauchbar (Invalid Date)');
+    }
+    return rufen('downloadDailyReport', { year: wanduhr.year, month: wanduhr.month, day: wanduhr.day });
+}
+/**
+ * Monatsbericht als PDF.
+ *
+ * **Der Endpunkt heisst `downloadReport`**, nicht `downloadMonthlyReport` —
+ * Methodenname und Endpunktname fallen hier auseinander (so im Dart-Vorbild und
+ * so im Backend, `report-endpoints.js`).
+ *
+ * `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 async function downloadMonthlyReport(rufen, reportMonth) {
+    const { month, year } = reportMonth;
+    if (!Number.isInteger(month) || month < 1 || month > 12) {
+        throw eingabefehler('downloadReport', `Berichtsmonat: month muss 1-12 sein, war "${month}"`);
+    }
+    if (!Number.isInteger(year)) {
+        throw eingabefehler('downloadReport', `Berichtsmonat: year muss eine ganze Zahl sein, war "${year}"`);
+    }
+    return rufen('downloadReport', { month, year });
+}
+/** Fehler in der Eingabe des Aufrufers — es geht keine Anfrage raus. */
+function eingabefehler(functionName, grund) {
+    return new KasseneckValidationError(functionName, grund, 'request');
+}

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

@@ -0,0 +1,43 @@
+import type { KasseneckTransport } from './transport.js';
+/**
+ * Betriebsstatus von Kasse und Signatureinheit bei FinanzOnline — Zwilling von
+ * `getCashboxStatus`/`getSignatureStatus` in
+ * kasseneck_api/lib/kasseneck_api.dart (Zeilen 410-440).
+ *
+ * Beide laufen ueber den **einen** Backend-Endpunkt `financeWebService`, der
+ * seine Vorgangsart als `method` **neben** `params` im Rumpf erwartet (so das
+ * Dart-Vorbild `_financeWebServicePostRequest`, so die Auswertung `b.method` im
+ * Backend). Die Antwort ist die uebliche Erfolgshuelle; darin liegt die
+ * FinanzOnline-Meldung unter `data.rkdbMessage`.
+ *
+ * **Kassen-Benutzer-Weg (`registerUserAuth`, Browser-Kasse):**
+ * `financeWebService` setzt kein `allowRegisterUser`; beide Abfragen
+ * funktionieren nur mit `apiKeyAuth`. Dieses Paket bildet das **nicht** nach —
+ * wer darf, entscheidet allein das Backend.
+ */
+/**
+ * Betriebsstatus, den FinanzOnline meldet. Die vier bekannten Werte sind
+ * benannt; ein noch unbekannter Wert kommt **unveraendert** durch (`string`),
+ * statt wie im Dart-Vorbild still zu `null` zu werden. Lesen ist in diesem
+ * Paket tolerant: "unbekannter Status" und "kein Status" duerfen fuer den
+ * Aufrufer nicht dasselbe sein, sonst meldet eine Kasse mit einem neuen
+ * FON-Status genauso wie eine ohne Antwort.
+ */
+export type CashboxStatus = 'AKTIVIERT' | 'REGISTRIERT' | 'IN_BETRIEB' | 'AUSFALL' | (string & {});
+/**
+ * Status der Signatureinheit. Wie [CashboxStatus], zusaetzlich der
+ * **abgeleitete** Wert `NOT_REGISTERED`: er ist kein FON-Status, sondern die
+ * Uebersetzung des Returncodes `B33` ("Signatureinheit nicht registriert").
+ */
+export type SignatureStatus = CashboxStatus | 'NOT_REGISTERED';
+/** Betriebsstatus der Kasse bei FinanzOnline. */
+export declare function getCashboxStatus(rufen: KasseneckTransport): Promise<CashboxStatus>;
+/**
+ * Status der Signatureinheit mit der Zertifikatsseriennummer [zertifikatNrHex]
+ * (hexadezimal, z. B. `6F0404F0`).
+ *
+ * **Der Returncode wird vor dem Status gelesen** (wie im Dart-Vorbild): `B33`
+ * heisst "nicht registriert" und schlaegt jedes Statusfeld, das daneben stehen
+ * mag. Andersherum meldete eine nie registrierte Karte am Ende "in Betrieb".
+ */
+export declare function getSignatureStatus(rufen: KasseneckTransport, zertifikatNrHex: string): Promise<SignatureStatus>;

package/dist/esm/client/status.js

@@ -0,0 +1,43 @@
+import { KasseneckValidationError } from './errors.js';
+/**
+ * Vorgangsnamen, unter denen Fehler dieser beiden Abfragen erscheinen. Beide
+ * laufen ueber denselben Endpunkt `financeWebService`; ein Fehler, der nur den
+ * Endpunkt nennt, verschweigt dem Aufrufer, ob der Kassen- oder der
+ * Signaturstatus scheiterte. Der Transport bildet denselben Namen aus
+ * `<funktion>/<method>` — hier stehen die Konstanten fuer die Fehler, die schon
+ * vor dem Senden entstehen.
+ */
+const VORGANG_KASSE = 'financeWebService/status_cashbox';
+const VORGANG_SIGNATUR = 'financeWebService/status_signature';
+/** Betriebsstatus der Kasse bei FinanzOnline. */
+export async function getCashboxStatus(rufen) {
+    const daten = await rufen('financeWebService', {}, { method: 'status_cashbox' });
+    return statusAusMeldung(daten, VORGANG_KASSE);
+}
+/**
+ * Status der Signatureinheit mit der Zertifikatsseriennummer [zertifikatNrHex]
+ * (hexadezimal, z. B. `6F0404F0`).
+ *
+ * **Der Returncode wird vor dem Status gelesen** (wie im Dart-Vorbild): `B33`
+ * heisst "nicht registriert" und schlaegt jedes Statusfeld, das daneben stehen
+ * mag. Andersherum meldete eine nie registrierte Karte am Ende "in Betrieb".
+ */
+export async function getSignatureStatus(rufen, zertifikatNrHex) {
+    if (typeof zertifikatNrHex !== 'string' || !zertifikatNrHex.trim()) {
+        throw new KasseneckValidationError(VORGANG_SIGNATUR, 'zertifikatNrHex fehlt', 'request');
+    }
+    const daten = await rufen('financeWebService', { zertifikatnr_hex: zertifikatNrHex }, { method: 'status_signature' });
+    if (daten?.rkdbMessage?.rc === 'B33') {
+        return 'NOT_REGISTERED';
+    }
+    return statusAusMeldung(daten, VORGANG_SIGNATUR);
+}
+function statusAusMeldung(daten, functionName) {
+    const status = daten?.rkdbMessage?.status;
+    if (typeof status !== 'string' || !status) {
+        // Der Inhalt der Antwort wandert NICHT in die Meldung — er kommt von einer
+        // fremden Stelle, und was dort steht, ist nicht unsere Zusage.
+        throw new KasseneckValidationError(functionName, 'Antwort enthaelt keinen Status (data.rkdbMessage.status)', 'response');
+    }
+    return status;
+}