@kreiseck/kasseneck-api 1.13.0 → 1.15.0

package/dist/cjs/client/list-receipts.d.ts

@@ -0,0 +1,211 @@
+import { KeckPaymentMethod, ReceiptType } from '../enums/index.js';
+import { type CancellationReason, type CancellationStatus, type Receipt, type ReceiptPayment, type ZeroKind } from '../models/index.js';
+import type { InternerTransport } from './aufrufe.js';
+/**
+ * Belege einer Kasse auflisten (`listReceipts`, nur unter `/v3`): ein Tag oder
+ * ein Zeitraum von hoechstens 31 Kalendertagen, Seite fuer Seite ueber einen
+ * undurchsichtigen Cursor. Nachfolger von `getReportV2` fuer Listen;
+ * `getReportV2` bleibt fuer Berichte.
+ *
+ * **Anmeldung wie `getReportV2`:** API-Schluessel plus `cashregister-token`
+ * (`apiKeyAuth`); die Kasse kommt aus dem Token, nie aus einem Parameter.
+ * Kassen-Bediener (Geraet + PIN) weist der Server ab; die Kasse hat dafuer
+ * `listMyReceipts` am Kassenweg. Dieses Paket bildet das nicht nach, wer darf,
+ * entscheidet allein das Backend.
+ *
+ * Zeiten sind die **Wiener Wanduhr** als Text, wie `timeStamp` am Beleg; der
+ * Server vergleicht sie als Text. Ein Tag ist ein Kalendertag, auch an den
+ * Tagen der Zeitumstellung, und die Grenze von 31 Tagen zaehlt Kalendertage,
+ * nicht 31 x 24 Stunden. Die Pruefung hier rechnet darum ohne Zeitzone, genau
+ * wie der Server (`beleg-liste-core.js`).
+ */
+/** Ansicht einer Seite: `summary` eine schlanke Zeile je Beleg, `full` das gespeicherte Belegdokument. */
+export declare const LIST_RECEIPTS_VIEWS: readonly ["summary", "full"];
+export type ListReceiptsView = (typeof LIST_RECEIPTS_VIEWS)[number];
+/** Reihenfolge: `desc` neueste zuerst (Vorgabe des Servers), `asc` aelteste zuerst. */
+export declare const LIST_RECEIPTS_ORDERS: readonly ["desc", "asc"];
+export type ListReceiptsOrder = (typeof LIST_RECEIPTS_ORDERS)[number];
+/** Groesste Seite, die der Server liefert (`limit`); ohne Angabe nimmt er 100. */
+export declare const LIST_RECEIPTS_LIMIT_MAX = 500;
+/** Laengster Zeitraum in Kalendertagen (`to` hoechstens `from` + 31 Tage). */
+export declare const LIST_RECEIPTS_DAYS_MAX = 31;
+/**
+ * So viele Seiten holt [listAllReceipts] hoechstens, dann bricht er mit
+ * Fehler ab. Schutz gegen einen Cursor, der nie endet; mit der Seitengroesse
+ * des Helfers (500) sind das 50.000 Belege, mehr als jede Kasse in 31 Tagen
+ * ausstellt.
+ */
+export declare const LIST_ALL_RECEIPTS_MAX_PAGES = 100;
+/**
+ * Fehlercodes von `listReceipts` (`code` des [KasseneckApiError]), dazu die
+ * gemeinsamen Codes von Anmeldung und Rand (Kassen-Token, Live-Gate,
+ * API-Freigabe). Ein Code ausserhalb bleibt ueber `KasseneckApiError.code`
+ * lesbar. Die Regeln der ersten sieben prueft dieses Paket schon vor dem
+ * Senden (ausser `invalid_cursor`: ob ein Cursor zur Abfrage passt, weiss nur
+ * der Server).
+ */
+export declare const LIST_RECEIPTS_ERROR_CODES: readonly ["invalid_date", "invalid_range", "range_too_long", "invalid_limit", "invalid_order", "invalid_view", "invalid_cursor", "server_error"];
+export type ListReceiptsErrorCode = (typeof LIST_RECEIPTS_ERROR_CODES)[number];
+/**
+ * Eingabe von [listReceipts]. Genau eine Form des Zeitfensters: `date` ODER
+ * `from` + `to`.
+ *
+ * - `date`: ein Wiener Tag, `YYYY-MM-DD` (00:00:00 bis zum Beginn des
+ *   Folgetags). Nur mit `date` traegt die erste Seite `daySummary`.
+ * - `from` (einschliesslich) und `to` (ausschliesslich): `YYYY-MM-DD` oder
+ *   `YYYY-MM-DDTHH:mm:ss`, Wiener Wanduhr ohne Zone. Ein reines Datum heisst
+ *   Beginn dieses Tages; `to` liegt hoechstens 31 Kalendertage nach `from`.
+ *
+ * Mit `cursor` (dem `nextCursor` der Vorseite) muessen Zeitfenster, `order`
+ * und `view` gleich bleiben wie auf Seite 1, sonst antwortet der Server
+ * `invalid_cursor`; `limit` darf sich aendern.
+ */
+export type ListReceiptsOptions<V extends ListReceiptsView = ListReceiptsView> = ListReceiptsWindow & {
+    /** Seitengroesse, ganze Zahl 1-500; ohne Angabe 100. */
+    limit?: number;
+    /** Ohne Angabe `desc` (neueste zuerst). */
+    order?: ListReceiptsOrder;
+    /** Ohne Angabe `summary`. */
+    view?: V;
+    /** `nextCursor` der vorigen Seite. */
+    cursor?: string;
+};
+/** Zeitfenster von [ListReceiptsOptions]: ein Tag oder ein Zeitraum. */
+export type ListReceiptsWindow = {
+    date: string;
+    from?: undefined;
+    to?: undefined;
+} | {
+    from: string;
+    to: string;
+    date?: undefined;
+};
+/** Brutto je RKSV-Satzgruppe in Cent (`amountRateStandard` bis `amountRateSpecial` am Beleg). */
+export interface ListReceiptsGrossByRate {
+    standard: number;
+    reduced1: number;
+    reduced2: number;
+    zero: number;
+    special: number;
+}
+/**
+ * Zeile eines Belegs in [listReceipts] mit `view: 'summary'`. Betraege in
+ * ganzen Cent. Kein Layout, kein Kopf, keine Positionen und keine
+ * Pruefangaben: fuer die Detailansicht `getReceipt`, fuer die PDF
+ * `downloadReceipt` mit `fullReceiptId`.
+ *
+ * Nicht zu verwechseln mit [ReceiptSummary] von `listMyReceipts` (Kassenweg,
+ * andere Felder, Betrag dort aus Euro gerechnet).
+ *
+ * `receiptType` und `paymentMethod` sind wie ueberall beim Lesen der bekannte
+ * Enum-Eintrag oder der rohe Schluessel; ein Wert, den dieses Paket nicht
+ * kennt, laesst die Liste nicht scheitern.
+ */
+export interface ListReceiptsSummary {
+    receiptId: string | null;
+    /** Fortlaufender Belegzaehler der Kasse; `null` bei Alt-Belegen. */
+    counter: number | null;
+    receiptType: ReceiptType | string | null;
+    /** Nur am Nullbeleg: Anlass (`manual`, wenn der Beleg keinen nennt); sonst `null`. */
+    zeroKind: ZeroKind | string | null;
+    /** Roher Belegzeitstempel (Wiener Wanduhr); Deutung ueber `parseServerTimeStamp`. */
+    timeStamp: string | null;
+    /** Summe von `grossByRateCents`; negativ am Storno-Beleg. */
+    totalCents: number;
+    grossByRateCents: ListReceiptsGrossByRate;
+    /** `mixed` bei mehreren Zahlungen (die stehen dann in `payments`). */
+    paymentMethod: KeckPaymentMethod | string | null;
+    /** Nur wenn der Beleg eine Zahlungsliste traegt; ohne Anbieterdaten. */
+    payments?: ReceiptPayment[];
+    /** Nur wenn der Beleg Trinkgeld traegt. */
+    tipCents?: number;
+    /** Bediener (nur der Name), oder `null`. */
+    operator: {
+        name: string;
+    } | null;
+    /** Nur am Storno-Beleg: das Original. */
+    cancellationOf: {
+        receiptId: string | null;
+        timeStamp: string | null;
+    } | null;
+    cancellationReason: CancellationReason | string | null;
+    /**
+     * Storno-Stand: `none`, `partial` oder `full` (nur an Normalbelegen anders
+     * als `none`). Ein Wert, den dieses Paket nicht kennt, kommt als
+     * `'unknown'` an, nie still als `none`: dann keinen Storno anbieten, bis
+     * der Beleg einzeln gelesen ist.
+     */
+    cancellationStatus: CancellationStatus | 'unknown';
+    /** Mit funktionierender Signatureinheit ausgestellt (`signatureSuccess !== false`). */
+    signatureOk: boolean;
+    /** Eigene Referenz des Aufrufers am Beleg, oder `null`. */
+    customProjectId: string | null;
+    /** Schluessel fuer `downloadReceipt` und den Beleg-Link, oder `null`. */
+    fullReceiptId: string | null;
+}
+/** Ein Beleg der Liste je Ansicht: `full` das Belegdokument wie bei `getReportV2`, sonst die Zeile. */
+export type ListedReceipt<V extends ListReceiptsView = 'summary'> = V extends 'full' ? Receipt : ListReceiptsSummary;
+/**
+ * Tagessumme aus der Tagesstatistik der Kasse, nur bei `date` und nur auf
+ * der ersten Seite. **Nicht die Summe der Liste:** `receiptCount` zaehlt jeden
+ * Beleg des Tages (auch Null-, Start- und Trainingsbelege), `revenueCents`
+ * nur Normal- und Storno-Belege, ohne Mitarbeiter-Trinkgeld und nach
+ * Aktionsrabatt. Wer die Liste summieren will, summiert die Liste.
+ */
+export interface ListReceiptsDaySummary {
+    date: string;
+    receiptCount: number;
+    revenueCents: number;
+    /** Je Steuersatz (Basispunkte, 2000 = 20 %), hoechster zuerst; Saetze ohne Umsatz fehlen. */
+    revenueByRate: Array<{
+        rateBp: number;
+        grossCents: number;
+    }>;
+}
+/** Eine Seite von [listReceipts]. */
+export interface ListReceiptsPage<V extends ListReceiptsView = 'summary'> {
+    receipts: Array<ListedReceipt<V>>;
+    /** Es gibt weitere Belege: mit `cursor: nextCursor` weiterlesen. */
+    hasMore: boolean;
+    /** `null`, wenn `hasMore` false ist. */
+    nextCursor: string | null;
+    /**
+     * Nur bei `date` auf der ersten Seite (ohne `cursor`); `null`, wenn es fuer
+     * den Tag keine Statistik gibt. Auf allen anderen Seiten fehlt das Feld.
+     */
+    daySummary?: ListReceiptsDaySummary | null;
+}
+/** Zeile `view: summary` vom Draht. */
+export declare function fromListReceiptsSummaryPayload(payload: Record<string, unknown>): ListReceiptsSummary;
+/**
+ * Eine Seite Belege der angemeldeten Kasse (`listReceipts`). Die Eingabe wird
+ * vor dem Senden nach den Regeln des Servers geprueft (genau eine Form des
+ * Zeitfensters, Datumsformat, hoechstens 31 Kalendertage, `limit` 1-500,
+ * `order`, `view`); ein Verstoss wirft [KasseneckValidationError] mit
+ * `scope: 'request'`, ohne dass etwas hinausgeht.
+ *
+ * Mit `view: 'full'` sind die Belege das gespeicherte Belegdokument
+ * ([Receipt], dieselbe Form wie `getReportV2`), sonst [ListReceiptsSummary].
+ * Alle Seiten auf einmal: [listAllReceipts].
+ */
+export declare function listReceipts<V extends ListReceiptsView = 'summary'>(transport: InternerTransport, options: ListReceiptsOptions<V>): Promise<ListReceiptsPage<V>>;
+/**
+ * Alle Belege eines Tages oder Zeitraums, Seite fuer Seite: holt mit
+ * [listReceipts] die erste Seite, dann mit `cursor: nextCursor` und
+ * demselben Zeitfenster, `order` und `view` jede weitere, und liefert jeden
+ * Beleg einzeln, in der Reihenfolge des Servers. Jeder Beleg des Fensters
+ * kommt genau einmal.
+ *
+ * Ohne `limit` holt der Helfer Seiten zu 500 (weniger Aufrufe als die
+ * Vorgabe 100 des Servers). Mit `cursor` setzt er an dieser Stelle fort.
+ *
+ * Ein Fehler auf irgendeiner Seite bricht ab (der Fehler kommt im
+ * `for await` an); die bis dahin gelieferten Belege bleiben gueltig. Nach
+ * [LIST_ALL_RECEIPTS_MAX_PAGES] Seiten, oder wenn der Server denselben
+ * Cursor zweimal nennt, bricht er mit [KasseneckValidationError]
+ * (`scope: 'response'`) ab, statt endlos zu laufen.
+ *
+ * `daySummary` liefert der Helfer nicht; wer sie braucht, ruft die erste
+ * Seite mit [listReceipts].
+ */
+export declare function listAllReceipts<V extends ListReceiptsView = 'summary'>(transport: InternerTransport, options: ListReceiptsOptions<V>): AsyncGenerator<ListedReceipt<V>, void, undefined>;

package/dist/cjs/client/list-receipts.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_RECEIPTS_ERROR_CODES = exports.LIST_ALL_RECEIPTS_MAX_PAGES = exports.LIST_RECEIPTS_DAYS_MAX = exports.LIST_RECEIPTS_LIMIT_MAX = exports.LIST_RECEIPTS_ORDERS = exports.LIST_RECEIPTS_VIEWS = void 0;
+exports.fromListReceiptsSummaryPayload = fromListReceiptsSummaryPayload;
+exports.listReceipts = listReceipts;
+exports.listAllReceipts = listAllReceipts;
+const index_js_1 = require("../enums/index.js");
+const index_js_2 = require("../models/index.js");
+const enum_payload_js_1 = require("../models/enum-payload.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Belege einer Kasse auflisten (`listReceipts`, nur unter `/v3`): ein Tag oder
+ * ein Zeitraum von hoechstens 31 Kalendertagen, Seite fuer Seite ueber einen
+ * undurchsichtigen Cursor. Nachfolger von `getReportV2` fuer Listen;
+ * `getReportV2` bleibt fuer Berichte.
+ *
+ * **Anmeldung wie `getReportV2`:** API-Schluessel plus `cashregister-token`
+ * (`apiKeyAuth`); die Kasse kommt aus dem Token, nie aus einem Parameter.
+ * Kassen-Bediener (Geraet + PIN) weist der Server ab; die Kasse hat dafuer
+ * `listMyReceipts` am Kassenweg. Dieses Paket bildet das nicht nach, wer darf,
+ * entscheidet allein das Backend.
+ *
+ * Zeiten sind die **Wiener Wanduhr** als Text, wie `timeStamp` am Beleg; der
+ * Server vergleicht sie als Text. Ein Tag ist ein Kalendertag, auch an den
+ * Tagen der Zeitumstellung, und die Grenze von 31 Tagen zaehlt Kalendertage,
+ * nicht 31 x 24 Stunden. Die Pruefung hier rechnet darum ohne Zeitzone, genau
+ * wie der Server (`beleg-liste-core.js`).
+ */
+/** Ansicht einer Seite: `summary` eine schlanke Zeile je Beleg, `full` das gespeicherte Belegdokument. */
+exports.LIST_RECEIPTS_VIEWS = Object.freeze(['summary', 'full']);
+/** Reihenfolge: `desc` neueste zuerst (Vorgabe des Servers), `asc` aelteste zuerst. */
+exports.LIST_RECEIPTS_ORDERS = Object.freeze(['desc', 'asc']);
+/** Groesste Seite, die der Server liefert (`limit`); ohne Angabe nimmt er 100. */
+exports.LIST_RECEIPTS_LIMIT_MAX = 500;
+/** Laengster Zeitraum in Kalendertagen (`to` hoechstens `from` + 31 Tage). */
+exports.LIST_RECEIPTS_DAYS_MAX = 31;
+/**
+ * So viele Seiten holt [listAllReceipts] hoechstens, dann bricht er mit
+ * Fehler ab. Schutz gegen einen Cursor, der nie endet; mit der Seitengroesse
+ * des Helfers (500) sind das 50.000 Belege, mehr als jede Kasse in 31 Tagen
+ * ausstellt.
+ */
+exports.LIST_ALL_RECEIPTS_MAX_PAGES = 100;
+/**
+ * Fehlercodes von `listReceipts` (`code` des [KasseneckApiError]), dazu die
+ * gemeinsamen Codes von Anmeldung und Rand (Kassen-Token, Live-Gate,
+ * API-Freigabe). Ein Code ausserhalb bleibt ueber `KasseneckApiError.code`
+ * lesbar. Die Regeln der ersten sieben prueft dieses Paket schon vor dem
+ * Senden (ausser `invalid_cursor`: ob ein Cursor zur Abfrage passt, weiss nur
+ * der Server).
+ */
+exports.LIST_RECEIPTS_ERROR_CODES = Object.freeze([
+    'invalid_date', // kein Datum JJJJ-MM-TT bzw. Zeitpunkt JJJJ-MM-TTThh:mm:ss, oder unmoeglich (2026-02-30)
+    'invalid_range', // nicht genau eine Form (date ODER from + to), oder to nicht nach from
+    'range_too_long', // mehr als 31 Kalendertage
+    'invalid_limit', // keine ganze Zahl von 1 bis 500 (der Server kappt nie still)
+    'invalid_order', // weder desc noch asc
+    'invalid_view', // weder summary noch full
+    'invalid_cursor', // veraendert, fremde Kasse, oder Zeitfenster/order/view anders als auf Seite 1
+    'server_error',
+]);
+const TAG = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ZEIT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})$/;
+/** Kalendertag als UTC-Mitternacht (nur zum Rechnen mit Tagen; auch fuer Jahre unter 100). */
+function utcTag(jahr, monat, tag) {
+    const d = new Date(Date.UTC(2000, 0, 1));
+    d.setUTCFullYear(jahr, monat - 1, tag);
+    return d;
+}
+/** Ein echtes Kalenderdatum (2026-02-30 nicht)? */
+function kalendertag(jahr, monat, tag) {
+    const d = utcTag(jahr, monat, tag);
+    return d.getUTCFullYear() === jahr && d.getUTCMonth() === monat - 1 && d.getUTCDate() === tag;
+}
+const zwei = (n) => String(n).padStart(2, '0');
+/** Wanduhr-Text `YYYY-MM-DDTHH:mm:ss` aus einem Tag oder Zeitpunkt; sonst `null`. */
+function wanduhr(wert) {
+    if (typeof wert !== 'string')
+        return null;
+    const t = TAG.exec(wert);
+    if (t)
+        return kalendertag(+t[1], +t[2], +t[3]) ? `${wert}T00:00:00` : null;
+    const z = ZEIT.exec(wert);
+    if (z && kalendertag(+z[1], +z[2], +z[3]) && +z[4] <= 23 && +z[5] <= 59 && +z[6] <= 59)
+        return wert;
+    return null;
+}
+/** Wanduhr-Text plus ganze Kalendertage, Uhrzeit bleibt (ohne Zeitzone gerechnet). */
+function plusTage(zeit, tage) {
+    const [datum, uhr] = zeit.split('T');
+    const [j, m, t] = datum.split('-').map(Number);
+    const d = utcTag(j, m, t + tage);
+    return `${String(d.getUTCFullYear()).padStart(4, '0')}-${zwei(d.getUTCMonth() + 1)}-${zwei(d.getUTCDate())}T${uhr}`;
+}
+const gesetzt = (v) => v !== undefined && v !== null;
+/** Fehler in der Eingabe des Aufrufers: es geht keine Anfrage raus. */
+function eingabefehler(grund) {
+    return new errors_js_1.KasseneckValidationError('listReceipts', grund, 'request');
+}
+/** Antwort meldet Erfolg, traegt aber nicht, was der Aufruf zusagt. */
+function antwortfehler(grund) {
+    return new errors_js_1.KasseneckValidationError('listReceipts', grund, 'response');
+}
+/**
+ * Prueft die Eingabe nach den Regeln des Servers und gibt die Parameter
+ * zurueck, die hinausgehen (nur gesetzte Felder, Werte unveraendert, damit
+ * Folgeseiten dasselbe Fenster senden).
+ */
+function parameter(options) {
+    if (options == null || typeof options !== 'object')
+        throw eingabefehler('Optionen fehlen (date oder from und to)');
+    const o = options;
+    const raus = {};
+    if (gesetzt(o.date)) {
+        if (gesetzt(o.from) || gesetzt(o.to))
+            throw eingabefehler('entweder date oder from und to angeben, nicht beides');
+        if (typeof o.date !== 'string' || !TAG.test(o.date) || wanduhr(o.date) === null) {
+            throw eingabefehler(`date muss ein Datum YYYY-MM-DD sein, war "${String(o.date)}"`);
+        }
+        raus['date'] = o.date;
+    }
+    else {
+        if (!gesetzt(o.from) || !gesetzt(o.to))
+            throw eingabefehler('Zeitraum fehlt: date oder from und to angeben');
+        const von = wanduhr(o.from);
+        if (von === null)
+            throw eingabefehler(`from muss YYYY-MM-DD oder YYYY-MM-DDTHH:mm:ss sein, war "${String(o.from)}"`);
+        const bis = wanduhr(o.to);
+        if (bis === null)
+            throw eingabefehler(`to muss YYYY-MM-DD oder YYYY-MM-DDTHH:mm:ss sein, war "${String(o.to)}"`);
+        if (bis <= von)
+            throw eingabefehler('to muss nach from liegen (to ist ausschliesslich)');
+        if (bis > plusTage(von, exports.LIST_RECEIPTS_DAYS_MAX)) {
+            throw eingabefehler(`Zeitraum hoechstens ${exports.LIST_RECEIPTS_DAYS_MAX} Kalendertage (to hoechstens from + ${exports.LIST_RECEIPTS_DAYS_MAX} Tage)`);
+        }
+        raus['from'] = o.from;
+        raus['to'] = o.to;
+    }
+    if (gesetzt(o.limit)) {
+        if (!Number.isInteger(o.limit) || o.limit < 1 || o.limit > exports.LIST_RECEIPTS_LIMIT_MAX) {
+            throw eingabefehler(`limit muss eine ganze Zahl von 1 bis ${exports.LIST_RECEIPTS_LIMIT_MAX} sein, war "${String(o.limit)}"`);
+        }
+        raus['limit'] = o.limit;
+    }
+    if (gesetzt(o.order)) {
+        if (!exports.LIST_RECEIPTS_ORDERS.includes(o.order))
+            throw eingabefehler(`order muss desc oder asc sein, war "${String(o.order)}"`);
+        raus['order'] = o.order;
+    }
+    if (gesetzt(o.view)) {
+        if (!exports.LIST_RECEIPTS_VIEWS.includes(o.view))
+            throw eingabefehler(`view muss summary oder full sein, war "${String(o.view)}"`);
+        raus['view'] = o.view;
+    }
+    if (gesetzt(o.cursor)) {
+        if (typeof o.cursor !== 'string' || o.cursor === '')
+            throw eingabefehler('cursor muss der nextCursor der vorigen Seite sein (nicht leerer Text)');
+        raus['cursor'] = o.cursor;
+    }
+    return raus;
+}
+const istObjekt = (w) => w != null && typeof w === 'object' && !Array.isArray(w);
+const text = (w) => (typeof w === 'string' ? w : null);
+// Ganze Cent; ein einzelner unbrauchbarer Betrag laesst die Liste nicht scheitern.
+const cent = (w) => (typeof w === 'number' && Number.isInteger(w) ? w : 0);
+function istStornoStand(w) {
+    return typeof w === 'string' && index_js_2.CANCELLATION_STATUSES.includes(w);
+}
+/** Zeile `view: summary` vom Draht. */
+function fromListReceiptsSummaryPayload(payload) {
+    const brutto = istObjekt(payload['grossByRateCents']) ? payload['grossByRateCents'] : {};
+    const bediener = payload['operator'];
+    const bezug = payload['cancellationOf'];
+    return {
+        receiptId: text(payload['receiptId']),
+        counter: typeof payload['counter'] === 'number' ? payload['counter'] : null,
+        receiptType: typeof payload['receiptType'] === 'string' ? (0, enum_payload_js_1.readEnumKey)(index_js_1.ReceiptType, payload['receiptType']) : null,
+        zeroKind: text(payload['zeroKind']),
+        timeStamp: text(payload['timeStamp']),
+        totalCents: cent(payload['totalCents']),
+        grossByRateCents: {
+            standard: cent(brutto['standard']),
+            reduced1: cent(brutto['reduced1']),
+            reduced2: cent(brutto['reduced2']),
+            zero: cent(brutto['zero']),
+            special: cent(brutto['special']),
+        },
+        paymentMethod: typeof payload['paymentMethod'] === 'string' ? (0, enum_payload_js_1.readEnumKey)(index_js_1.KeckPaymentMethod, payload['paymentMethod']) : null,
+        ...(Array.isArray(payload['payments'])
+            ? { payments: payload['payments'].filter(istObjekt).map((z) => (0, index_js_2.fromReceiptPaymentPayload)(z)) }
+            : {}),
+        ...(typeof payload['tipCents'] === 'number' ? { tipCents: payload['tipCents'] } : {}),
+        operator: istObjekt(bediener) ? { name: typeof bediener['name'] === 'string' ? bediener['name'] : '' } : null,
+        cancellationOf: istObjekt(bezug) ? { receiptId: text(bezug['receiptId']), timeStamp: text(bezug['timeStamp']) } : null,
+        cancellationReason: text(payload['cancellationReason']),
+        cancellationStatus: istStornoStand(payload['cancellationStatus']) ? payload['cancellationStatus'] : 'unknown',
+        signatureOk: payload['signatureOk'] !== false,
+        customProjectId: text(payload['customProjectId']),
+        fullReceiptId: text(payload['fullReceiptId']),
+    };
+}
+function tagessumme(roh) {
+    if (roh === null)
+        return null;
+    if (!istObjekt(roh))
+        throw antwortfehler('daySummary ist weder ein Objekt noch null');
+    const saetze = Array.isArray(roh['revenueByRate']) ? roh['revenueByRate'] : [];
+    return {
+        date: typeof roh['date'] === 'string' ? roh['date'] : '',
+        receiptCount: cent(roh['receiptCount']),
+        revenueCents: cent(roh['revenueCents']),
+        revenueByRate: saetze.filter(istObjekt).map((z) => ({ rateBp: cent(z['rateBp']), grossCents: cent(z['grossCents']) })),
+    };
+}
+/**
+ * Eine Seite Belege der angemeldeten Kasse (`listReceipts`). Die Eingabe wird
+ * vor dem Senden nach den Regeln des Servers geprueft (genau eine Form des
+ * Zeitfensters, Datumsformat, hoechstens 31 Kalendertage, `limit` 1-500,
+ * `order`, `view`); ein Verstoss wirft [KasseneckValidationError] mit
+ * `scope: 'request'`, ohne dass etwas hinausgeht.
+ *
+ * Mit `view: 'full'` sind die Belege das gespeicherte Belegdokument
+ * ([Receipt], dieselbe Form wie `getReportV2`), sonst [ListReceiptsSummary].
+ * Alle Seiten auf einmal: [listAllReceipts].
+ */
+async function listReceipts(transport, options) {
+    const params = parameter(options);
+    const voll = params['view'] === 'full';
+    const daten = await transport('listReceipts', params);
+    if (!istObjekt(daten))
+        throw antwortfehler('Antwort enthaelt keine Daten (data fehlt)');
+    const liste = daten['receipts'];
+    if (!Array.isArray(liste) || liste.some((b) => !istObjekt(b))) {
+        throw antwortfehler('Antwort enthaelt keine Belegliste (data.receipts fehlt)');
+    }
+    if (typeof daten['hasMore'] !== 'boolean')
+        throw antwortfehler('Antwort ohne hasMore');
+    const weiter = daten['nextCursor'];
+    // Ein `hasMore` ohne Cursor liesse den Aufrufer ratlos (oder einen Blaetterer im Kreis laufen).
+    if (daten['hasMore'] ? typeof weiter !== 'string' || weiter === '' : weiter !== null) {
+        throw antwortfehler('nextCursor passt nicht zu hasMore (Text bei hasMore, sonst null)');
+    }
+    const receipts = (voll
+        ? liste.map((b) => (0, index_js_2.fromReceiptPayload)(b))
+        : liste.map((b) => fromListReceiptsSummaryPayload(b)));
+    return {
+        receipts,
+        hasMore: daten['hasMore'],
+        nextCursor: daten['hasMore'] ? weiter : null,
+        ...('daySummary' in daten ? { daySummary: tagessumme(daten['daySummary']) } : {}),
+    };
+}
+/**
+ * Alle Belege eines Tages oder Zeitraums, Seite fuer Seite: holt mit
+ * [listReceipts] die erste Seite, dann mit `cursor: nextCursor` und
+ * demselben Zeitfenster, `order` und `view` jede weitere, und liefert jeden
+ * Beleg einzeln, in der Reihenfolge des Servers. Jeder Beleg des Fensters
+ * kommt genau einmal.
+ *
+ * Ohne `limit` holt der Helfer Seiten zu 500 (weniger Aufrufe als die
+ * Vorgabe 100 des Servers). Mit `cursor` setzt er an dieser Stelle fort.
+ *
+ * Ein Fehler auf irgendeiner Seite bricht ab (der Fehler kommt im
+ * `for await` an); die bis dahin gelieferten Belege bleiben gueltig. Nach
+ * [LIST_ALL_RECEIPTS_MAX_PAGES] Seiten, oder wenn der Server denselben
+ * Cursor zweimal nennt, bricht er mit [KasseneckValidationError]
+ * (`scope: 'response'`) ab, statt endlos zu laufen.
+ *
+ * `daySummary` liefert der Helfer nicht; wer sie braucht, ruft die erste
+ * Seite mit [listReceipts].
+ */
+async function* listAllReceipts(transport, options) {
+    // Frueh pruefen: ein Eingabefehler kommt beim ersten Schritt an, vor jedem Aufruf.
+    parameter(options);
+    const grund = { ...options, limit: options.limit ?? exports.LIST_RECEIPTS_LIMIT_MAX };
+    let cursor = options.cursor;
+    const gesehen = new Set();
+    for (let seite = 1; seite <= exports.LIST_ALL_RECEIPTS_MAX_PAGES; seite++) {
+        const page = await listReceipts(transport, { ...grund, cursor });
+        yield* page.receipts;
+        if (!page.hasMore)
+            return;
+        const weiter = page.nextCursor;
+        if (gesehen.has(weiter) || weiter === cursor)
+            throw antwortfehler('Server nennt denselben Cursor erneut; Abbruch statt Endlosschleife');
+        gesehen.add(weiter);
+        cursor = weiter;
+    }
+    throw antwortfehler(`mehr als ${exports.LIST_ALL_RECEIPTS_MAX_PAGES} Seiten; Zeitfenster kleiner waehlen`);
+}

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

@@ -1,5 +1,6 @@
 import { ReceiptType, type ReceiptTypeKey, KeckPaymentMethod, type KeckPaymentMethodKey } from '../enums/index.js';
 import { type Receipt, type ReceiptCompany, type ReceiptItem, type Voucher, type ReceiptSummary, type ReportMonth, type CancellationItem, type CancellationOf, type CancellationReason, type TipRefundSource, type ReturnDisposition, type ReceiptPaymentInput, type RegistrationInfo, type ReceiptEmailVia } from '../models/index.js';
+import { type ReceiptOutput, type ReceiptOutputEntryErrorCode, type ReceiptOutputLogKind, type ReceiptOutputResult } from '../models/receipt-output.js';
 import type { InternerTransport } from './aufrufe.js';
 import { type ReceiptLayout } from '../receipt/layout.js';
 import type { PosPaperSize } from '../printing/escpos.js';
@@ -140,8 +141,9 @@ export type CancelReceiptOptions = {
     /**
      * Rueckzahlung je Zahlung (Betraege negativ, `refundOf` = `id` der
      * Originalzahlung). Ohne Angabe spiegelt der Server die Restbetraege jeder
-     * Originalzahlung; ein Teilstorno eines Belegs mit mehreren Zahlungen
-     * braucht sie (`cancellation_payments_required`).
+     * Originalzahlung (Ausnahme Storno einer Gutschein-Auszahlung: genau eine
+     * positive Barzahlung ohne `refundOf`); ein Teilstorno eines Belegs mit
+     * mehreren Zahlungen braucht sie (`cancellation_payments_required`).
      *
      * **Karten-Storno:** `provider`, `providerPaymentId` und `providerData`
      * beschreiben die ERSTATTUNG am Terminal, nie die Originalzahlung. Die
@@ -216,6 +218,13 @@ export interface ReceiptWithCompany {
      * setzen das Logo in genau dieser Stufe; fehlt der Wert, gilt `M`.
      */
     logoScale: SheetLogoSize;
+    /**
+     * Ausgaben des Belegs (`data.outputs`, nur `getReceipt` unter `/v3`): die
+     * neuesten 20, neueste zuerst. Fehlt, wenn die Antwort keine Liste traegt
+     * (Verkauf, `/api`). Gelesen nach [ReceiptOutput]; ein kaputter Eintrag
+     * faellt weg, der Beleg bleibt lesbar.
+     */
+    outputs?: ReceiptOutput[];
 }
 /**
  * Das Zeilenmodell zum Drucken und Anzeigen eines Belegs aus einer Antwort.
@@ -402,6 +411,80 @@ export interface SendReceiptEmailResult {
  * eine zweite Mail und zaehlt auf die Schleuse.
  */
 export declare function sendReceiptEmail(transport: InternerTransport, options: SendReceiptEmailOptions): Promise<SendReceiptEmailResult>;
+/**
+ * Eine Ausgabe, wie die Kasse sie puffert und meldet: ein Druck oder ein
+ * Teilen des Belegs. Siehe [logReceiptOutputs].
+ */
+export interface ReceiptOutputEntry {
+    /**
+     * Idempotenzschluessel des Eintrags, am Geraet beim Puffern vergeben und
+     * beim Nachsenden unveraendert: ein zweites Melden legt keinen zweiten
+     * Eintrag an. 8–64 Zeichen `[A-Za-z0-9_-]` (Regel des Servers); ein anderer
+     * Schluessel wirft vor dem Senden.
+     */
+    key: string;
+    /** Beleg in der Kasse der Anmeldung; ein Beleg einer anderen Kasse ist `receipt_not_found`. */
+    receiptId: string;
+    /** `print` (Erstdruck), `reprint` (Duplikat, gedruckt mit `markAsDuplicate`), `link_shared`, `pdf_shared`. */
+    kind: ReceiptOutputLogKind;
+    /**
+     * Zeitpunkt am Geraet: Millisekunden seit 1970 oder ISO 8601 **mit Zone**
+     * (`new Date().toISOString()`); Text ohne Zone wirft vor dem Senden. Eine
+     * falsch gehende Geraeteuhr lehnt der Server nicht ab: er klemmt die Zeit auf
+     * Belegzeit bis Eingang.
+     */
+    at: number | string;
+    /**
+     * Ergebnis eines Drucks: `ok`, `failed` (sicher nicht gedruckt) oder
+     * `unclear` (Ausgang offen). Pflicht bei `print` und `reprint` (sonst lehnt
+     * der Server den Eintrag mit `validation` ab); beim Teilen ohne Angabe `ok`.
+     */
+    result?: ReceiptOutputResult;
+}
+/** Eingabe von [logReceiptOutputs]. Die Kasse bindet die Anmeldung (wie bei [sendReceiptEmail]). */
+export interface LogReceiptOutputsOptions {
+    /** 1–50 Eintraege ([RECEIPT_OUTPUT_ENTRIES_MAX]); ein groesserer Puffer geht in mehreren Aufrufen hinaus. */
+    entries: ReceiptOutputEntry[];
+}
+/** Ein abgelehnter Eintrag: dauerhaft, aus dem Puffer nehmen und nicht noch einmal senden. */
+export interface RejectedReceiptOutput {
+    key: string;
+    /** Aus [RECEIPT_OUTPUT_ENTRY_ERROR_CODES]; ein Code, den das Paket nicht kennt, bleibt lesbar. */
+    code: ReceiptOutputEntryErrorCode | (string & {});
+}
+/** Antwort von [logReceiptOutputs]. */
+export interface LogReceiptOutputsResult {
+    /** Angenommene Eintraege, auch die schon frueher gemeldeten (gleicher Schluessel). */
+    accepted: number;
+    rejected: RejectedReceiptOutput[];
+}
+/**
+ * Meldet Drucke und das Teilen eines Belegs an das Protokoll „Ausgaben“
+ * (Endpunkt `logReceiptOutputs`, nur ueber den Kassenweg `/api/v3`; mit
+ * `registerUserAuth` und mit `apiKeyAuth`). Registrierkassen-Erlass
+ * BMF-AV Nr. 2/2026, Abschnitt 4.2: die Belegerteilung ist zu dokumentieren.
+ * Der Beleg selbst bleibt unberuehrt; das Protokoll steht nie im DEP.
+ *
+ * **Ein Eintrag scheitert nie die anderen.** Der Server nimmt jeden Eintrag
+ * einzeln an oder lehnt ihn mit Code ab (`rejected`, Codes
+ * [RECEIPT_OUTPUT_ENTRY_ERROR_CODES]); nach einer Erfolgsantwort ist jeder
+ * gesendete Eintrag erledigt. Die Kasse puffert die Eintraege (offline,
+ * Neustart) und sendet sie spaeter; der Puffer blockiert nie Druck oder Teilen.
+ *
+ * **Wiederholen ist gefahrlos:** jeder Eintrag traegt seinen Schluessel. Bei
+ * unklarem Ausgang (`outcome: 'unknown'`) dieselben Eintraege mit denselben
+ * Schluesseln noch einmal senden.
+ *
+ * **Vor dem Senden abgewiesen** wird nur, was die ganze Anfrage scheitern
+ * liesse oder ohne Netz sicher falsch ist: keine oder mehr als 50 Eintraege,
+ * ein unbekanntes Feld (oben oder im Eintrag), ein fehlender Beleg, ein
+ * Schluessel ausserhalb der Regel des Servers, eine Art oder ein Ergebnis
+ * ausserhalb des Katalogs, eine Zeit, die weder ganze Millisekunden noch
+ * ISO 8601 mit Zone ist. `email` und `opened` gehen hinaus und kommen als
+ * `invalid_output_kind` zurueck: so verwirft der Puffer genau diesen Eintrag.
+ * Fehler der ganzen Anfrage: [RECEIPT_OUTPUT_ERROR_CODES].
+ */
+export declare function logReceiptOutputs(transport: InternerTransport, options: LogReceiptOutputsOptions): Promise<LogReceiptOutputsResult>;
 /**
  * Prueft die Gutschein-Kombination eines Belegs und liefert den ersten
  * Regelverstoss als Text (oder `null`) — Zwilling von