import { KeckPaymentMethod, ReceiptType } from '../enums/index.js'; import { type CancellationReason, type CancellationStatus, type Receipt, type ReceiptPayment, type ZeroKind } from '../models/index.js'; import type { ReportV2Metadata } from './reports.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 = 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 '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 { receipts: Array>; /** 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; /** * Nur bei `view: 'full'`: Firmendaten fuer den Belegkopf (Nachdruck), dieselben Felder wie * `getReportV2().metadata`. Bei der Kurzansicht fehlt das Feld. */ metadata?: V extends 'full' ? ReportV2Metadata : never; } /** Zeile `view: summary` vom Draht. */ export declare function fromListReceiptsSummaryPayload(payload: Record): 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(transport: InternerTransport, options: ListReceiptsOptions): Promise>; /** * 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(transport: InternerTransport, options: ListReceiptsOptions): AsyncGenerator, void, undefined>;