@kreiseck/kasseneck-api 1.19.0 → 1.21.0

package/dist/esm/client/dep-export.d.ts

@@ -0,0 +1,242 @@
+import { KasseneckValidationError } from './errors.js';
+import type { InternerDateiOderDatenTransport, InternerTransport } from './aufrufe.js';
+import type { FetchLike } from './transport.js';
+/**
+ * DEP-Export fuer die Kassennachschau (nur unter `/v3`): ein Export des
+ * Datenerfassungsprotokolls fuer einen vom Pruefungsorgan vorgegebenen
+ * Zeitraum (§ 19 Abs. 2 RKSV), Dateien zum Abholen und ein Pruefer-Link mit
+ * Code, ueber den das Pruefungsorgan die Dateien ohne Anmeldung laedt.
+ *
+ * **Anmeldung wie `listReceipts`:** API-Schluessel plus `cashregister-token`;
+ * die Kasse kommt aus dem Token, nie aus einem Parameter. Ein Export einer
+ * anderen Kasse ist `export_not_found`.
+ *
+ * **Ablauf:** `createDepExport` stellt den Export ein und antwortet sofort
+ * (`status: 'running'`; eine Wiederholung mit derselben `requestId` nennt den
+ * aktuellen Stand); er laeuft im Hintergrund. `waitForDepExport` fragt bis zum
+ * Ende, `getDepExportFile` holt eine Datei, `createDepHandoverLink` erzeugt den
+ * Link fuer das Pruefungsorgan.
+ */
+/** Zustand eines Exports: in Arbeit, fertig oder fehlgeschlagen. */
+export declare const DEP_EXPORT_STATUSES: readonly ["running", "done", "failed"];
+export type DepExportStatus = (typeof DEP_EXPORT_STATUSES)[number];
+/** Die Dateien eines Exports: DEP-JSON, Protokoll (PDF), Positionen (CSV) und alles zusammen als ZIP. */
+export declare const DEP_EXPORT_FILES: readonly ["dep", "protocol", "items", "zip"];
+export type DepExportFileKind = (typeof DEP_EXPORT_FILES)[number];
+/**
+ * Fehlercodes der fuenf Aufrufe (`code` des [KasseneckApiError]) wie im
+ * Vertrag des Backends (`errorCodes.depExport` in `fixtures/v3/v3-vokabular.json`,
+ * Katalog `dep_nachschau`), in dessen Reihenfolge; dazu kommen die gemeinsamen
+ * Codes von Anmeldung und Rand. Ein Code ausserhalb bleibt ueber
+ * `KasseneckApiError.code` lesbar.
+ */
+export declare const DEP_EXPORT_ERROR_CODES: readonly ["validation", "invalid_period", "idempotency_conflict", "export_running", "too_many_exports", "export_not_found", "export_not_ready", "export_failed", "invalid_file", "file_not_available", "too_many_links", "link_not_found", "manager_only", "server_error"];
+/**
+ * Warum ein Export fehlgeschlagen ist (`DepExport.error`): die Werte des
+ * Katalogs `DEP_EXPORT_FEHLER` im Vertrag. `export_stalled` = nach 35 Minuten
+ * nicht fertig.
+ */
+export declare const DEP_EXPORT_FAILURES: readonly ["export_failed", "export_stalled"];
+export type DepExportFailure = (typeof DEP_EXPORT_FAILURES)[number];
+/**
+ * Codes, die die DEP-Aufrufe als `KasseneckApiError.code` werfen:
+ * [DEP_EXPORT_ERROR_CODES] und, aus [waitForDepExport], die Gruende eines
+ * fehlgeschlagenen Exports ([DEP_EXPORT_FAILURES], also auch `export_stalled`).
+ */
+export type DepExportErrorCode = (typeof DEP_EXPORT_ERROR_CODES)[number] | DepExportFailure;
+/** Eingabe von [createDepExport]. Ohne `from`/`to` der ganze Bestand. */
+export interface CreateDepExportOptions {
+    /** Erster Tag (inklusive), `YYYY-MM-DD`, nicht in der Zukunft. */
+    from?: string;
+    /** Letzter Tag (inklusive), `YYYY-MM-DD`, nicht vor `from`. */
+    to?: string;
+    /**
+     * Wiederholungsschutz je Kasse: derselbe Wert mit demselben Zeitraum
+     * liefert denselben Export (mit seinem aktuellen Stand) statt eines zweiten;
+     * mit anderem Zeitraum `idempotency_conflict`. Hoechstens 64 Zeichen aus
+     * `A-Z a-z 0-9 _ -`. Bei unklarem Ausgang (Zeitlimit) mit **demselben** Wert
+     * und demselben Zeitraum wiederholen.
+     */
+    requestId?: string;
+}
+/** Antwort von [createDepExport]: Kennung und Zustand (bei einer wiederholten `requestId` auch `done`). */
+export interface CreateDepExportResult {
+    exportId: string;
+    status: DepExportStatus;
+    from: string | null;
+    to: string | null;
+}
+/** Eine Luecke in der Belegnummerierung: Zaehler von bis (einschliesslich). */
+export interface DepExportGap {
+    from: number;
+    to: number;
+}
+/** Erster Bruch der Signaturkette: am Zaehler `counter` erwartet, aber gefunden. */
+export interface DepExportChainBreak {
+    counter: number | null;
+    expected: unknown;
+    found: unknown;
+}
+/** Befund der Pruefung des Exports (`DepExport.findings`). */
+export interface DepExportFindings {
+    receiptCount: number | null;
+    counterFrom: number | null;
+    counterTo: number | null;
+    /** Fehlende Belegnummern als zusammenhaengende Bereiche. */
+    gaps: DepExportGap[];
+    /** Hoechstens ein Eintrag: der erste Bruch der Kette. */
+    chainBreaks: DepExportChainBreak[];
+    /** `receiptId` der Belege ohne Zaehler. */
+    withoutCounter: string[];
+    /** `receiptId` der Belege ohne Signatur. */
+    withoutSignature: string[];
+}
+/** Die Positionsdatei (CSV) eines Exports; `null` bei Exporten aus der Zeit davor. */
+export interface DepExportItems {
+    rowCount: number;
+    sha256: string;
+    size: number;
+}
+/** Ein Pruefer-Link, wie ihn der Export auffuehrt (ohne Adresse und Code). */
+export interface DepHandoverLinkInfo {
+    linkId: string;
+    createdAt: string | null;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    firstAccessAt: string | null;
+    accessCount: number;
+}
+/** Ein Export mit Zustand, Kennzahlen, Befund und Links (`getDepExport`). Zeiten ISO 8601 (UTC). */
+export interface DepExport {
+    exportId: string;
+    status: DepExportStatus;
+    from: string | null;
+    to: string | null;
+    createdAt: string | null;
+    finishedAt: string | null;
+    receiptCount: number | null;
+    counterFrom: number | null;
+    counterTo: number | null;
+    /** SHA-256 (hex) der DEP-JSON-Datei. */
+    sha256: string | null;
+    /** Groesse der DEP-JSON-Datei in Byte. */
+    size: number | null;
+    findings: DepExportFindings | null;
+    items: DepExportItems | null;
+    handoverLinks: DepHandoverLinkInfo[];
+    /** Nur bei `status: 'failed'`: `export_stalled` (haengend) oder `export_failed`. */
+    error?: DepExportFailure;
+}
+/** Eingabe von [waitForDepExport]. */
+export interface WaitForDepExportOptions {
+    exportId: string;
+    /** Hoechstdauer in Millisekunden (Vorgabe 600.000 = 10 Minuten). */
+    timeoutMs?: number;
+}
+/** Eingabe von [getDepExportFile]. */
+export interface GetDepExportFileOptions {
+    exportId: string;
+    file: DepExportFileKind;
+    /**
+     * Bekannte SHA-256-Pruefsumme (hex) der Datei, etwa `DepExport.sha256` fuer
+     * `dep` oder `DepExport.items.sha256` fuer `items`. Weicht die geladene Datei
+     * ab, wirft der Aufruf. Bei einem Lese-Link prueft der Aufruf ausserdem immer
+     * gegen die Pruefsumme, die der Server mit dem Link nennt.
+     */
+    sha256?: string;
+    /**
+     * Zeitlimit in Millisekunden (Vorgabe 600.000), je fuer den Aufruf selbst und
+     * fuer das Laden ueber einen Lese-Link. Der Aufruf liefert eine Datei bis
+     * 9 MiB direkt und braucht dafuer mehr als das allgemeine Zeitlimit des
+     * Transports (`timeoutMs`, Vorgabe 30 s); es gilt hier nicht.
+     */
+    downloadTimeoutMs?: number;
+}
+/** Eine geladene, gepruefte Datei. */
+export interface DepExportFile {
+    bytes: Uint8Array;
+    fileName: string;
+    contentType: string;
+    /** SHA-256 (hex) der Bytes, vom Paket berechnet. */
+    sha256: string;
+}
+/** Ein erzeugter Pruefer-Link (`createDepHandoverLink`). Adresse und Code nur jetzt, danach nie wieder. */
+export interface DepHandoverLink {
+    linkId: string;
+    /** Adresse fuer das Pruefungsorgan (Token im Fragment). */
+    url: string;
+    /** 6-stelliger Code, getrennt von der Adresse zu uebergeben. */
+    code: string;
+    expiresAt: string;
+}
+/** Antwort von [revokeDepHandoverLink]. */
+export interface RevokedDepHandoverLink {
+    linkId: string;
+    revokedAt: string | null;
+}
+/** Wartezeiten von [waitForDepExport]: 2 s, dann je x1,5, hoechstens 15 s. */
+export declare const DEP_EXPORT_POLL_START_MS = 2000;
+export declare const DEP_EXPORT_POLL_FACTOR = 1.5;
+export declare const DEP_EXPORT_POLL_MAX_MS = 15000;
+/** Vorgabe fuer `waitForDepExport.timeoutMs`. */
+export declare const DEP_EXPORT_WAIT_TIMEOUT_MS = 600000;
+/** Vorgabe fuer `getDepExportFile.downloadTimeoutMs`: der Aufruf selbst und das Laden ueber einen Lese-Link. */
+export declare const DEP_EXPORT_DOWNLOAD_TIMEOUT_MS = 600000;
+/**
+ * [waitForDepExport] gab auf, weil der Export nach `timeoutMs` weder fertig
+ * noch fehlgeschlagen war. Der Export laeuft serverseitig weiter: mit
+ * `getDepExport` (oder erneutem Warten) nachsehen, nicht neu anstossen.
+ */
+export declare class DepExportTimeoutError extends Error {
+    readonly name = "DepExportTimeoutError";
+    readonly exportId: string;
+    readonly timeoutMs: number;
+    /** Zustand bei der letzten Abfrage. */
+    readonly lastStatus: DepExportStatus;
+    constructor(exportId: string, timeoutMs: number, lastStatus: DepExportStatus);
+}
+/** Das Ergebnis stimmt nicht mit der Pruefsumme ueberein: die Datei ist nicht zu verwenden. */
+export declare class DepExportChecksumError extends KasseneckValidationError {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(exportId: string, file: DepExportFileKind, expected: string, actual: string);
+}
+/**
+ * Stellt einen DEP-Export ein (`createDepExport`) und antwortet sofort mit
+ * `status: 'running'`. Hoechstens ein laufender Export je Kasse
+ * (`export_running`, `details.exportId` nennt ihn). Mit `requestId` ist der
+ * Aufruf wiederholbar: dieselbe Kennung mit demselben Zeitraum liefert den
+ * bestehenden Export mit seinem aktuellen Stand (auch `done` oder `failed`),
+ * mit anderem Zeitraum `idempotency_conflict`.
+ */
+export declare function createDepExport(transport: InternerTransport, options?: CreateDepExportOptions): Promise<CreateDepExportResult>;
+/** Zustand, Kennzahlen, Befund und Links eines Exports (`getDepExport`). */
+export declare function getDepExport(transport: InternerTransport, options: {
+    exportId: string;
+}): Promise<DepExport>;
+/**
+ * Wartet, bis der Export fertig ist, und gibt ihn zurueck. Fragt mit
+ * [DEP_EXPORT_POLL_START_MS] Abstand, dann je x[DEP_EXPORT_POLL_FACTOR],
+ * hoechstens [DEP_EXPORT_POLL_MAX_MS]. Bei `failed` wirft er einen
+ * [KasseneckApiError] mit `code` `export_failed` oder `export_stalled`
+ * (haengender Export); nach `timeoutMs` einen [DepExportTimeoutError]. Ein
+ * Fehler beim Abfragen selbst bricht ab.
+ */
+export declare function waitForDepExport(transport: InternerTransport, options: WaitForDepExportOptions): Promise<DepExport>;
+/**
+ * Holt eine Datei eines fertigen Exports (`getDepExportFile`). Der Server
+ * liefert sie bis 9 MiB selbst, darueber als signierten Lese-Link (15 Minuten);
+ * dem Link folgt dieser Aufruf und laedt die Bytes. In beiden Faellen ist das
+ * Ergebnis dasselbe. Geprueft wird die SHA-256-Summe: beim Lese-Link immer
+ * gegen die Summe des Servers, sonst und zusaetzlich gegen `options.sha256`,
+ * wenn sie bekannt ist. Eine Abweichung wirft [DepExportChecksumError].
+ */
+export declare function getDepExportFile(transport: InternerDateiOderDatenTransport, fetchFn: FetchLike, options: GetDepExportFileOptions): Promise<DepExportFile>;
+/** Erzeugt einen Pruefer-Link zu einem fertigen Export (`createDepHandoverLink`). Gueltig 14 Tage. */
+export declare function createDepHandoverLink(transport: InternerTransport, options: {
+    exportId: string;
+}): Promise<DepHandoverLink>;
+/** Widerruft einen Pruefer-Link der eigenen Kasse (`revokeDepHandoverLink`). */
+export declare function revokeDepHandoverLink(transport: InternerTransport, options: {
+    linkId: string;
+}): Promise<RevokedDepHandoverLink>;

package/dist/esm/client/dep-export.js

@@ -0,0 +1,326 @@
+import { KasseneckApiError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError } from './errors.js';
+/**
+ * DEP-Export fuer die Kassennachschau (nur unter `/v3`): ein Export des
+ * Datenerfassungsprotokolls fuer einen vom Pruefungsorgan vorgegebenen
+ * Zeitraum (§ 19 Abs. 2 RKSV), Dateien zum Abholen und ein Pruefer-Link mit
+ * Code, ueber den das Pruefungsorgan die Dateien ohne Anmeldung laedt.
+ *
+ * **Anmeldung wie `listReceipts`:** API-Schluessel plus `cashregister-token`;
+ * die Kasse kommt aus dem Token, nie aus einem Parameter. Ein Export einer
+ * anderen Kasse ist `export_not_found`.
+ *
+ * **Ablauf:** `createDepExport` stellt den Export ein und antwortet sofort
+ * (`status: 'running'`; eine Wiederholung mit derselben `requestId` nennt den
+ * aktuellen Stand); er laeuft im Hintergrund. `waitForDepExport` fragt bis zum
+ * Ende, `getDepExportFile` holt eine Datei, `createDepHandoverLink` erzeugt den
+ * Link fuer das Pruefungsorgan.
+ */
+/** Zustand eines Exports: in Arbeit, fertig oder fehlgeschlagen. */
+export const DEP_EXPORT_STATUSES = Object.freeze(['running', 'done', 'failed']);
+/** Die Dateien eines Exports: DEP-JSON, Protokoll (PDF), Positionen (CSV) und alles zusammen als ZIP. */
+export const DEP_EXPORT_FILES = Object.freeze(['dep', 'protocol', 'items', 'zip']);
+/**
+ * Fehlercodes der fuenf Aufrufe (`code` des [KasseneckApiError]) wie im
+ * Vertrag des Backends (`errorCodes.depExport` in `fixtures/v3/v3-vokabular.json`,
+ * Katalog `dep_nachschau`), in dessen Reihenfolge; dazu kommen die gemeinsamen
+ * Codes von Anmeldung und Rand. Ein Code ausserhalb bleibt ueber
+ * `KasseneckApiError.code` lesbar.
+ */
+export const DEP_EXPORT_ERROR_CODES = Object.freeze([
+    'validation', // ungueltige requestId (Details in den Feldfehlern)
+    'invalid_period', // from/to kein Datum JJJJ-MM-TT, from in der Zukunft oder to vor from
+    'idempotency_conflict', // dieselbe requestId gehoert zu einem Export mit anderem Zeitraum
+    'export_running', // fuer diese Kasse laeuft schon ein Export (`details.exportId` nennt ihn)
+    'too_many_exports', // Tagesgrenze der Exporte erreicht
+    'export_not_found', // unbekannt oder einer anderen Kasse
+    'export_not_ready', // Datei oder Link nur zu einem fertigen Export
+    'export_failed', // der Export ist fehlgeschlagen
+    'invalid_file', // keine der Dateien dep, protocol, items, zip
+    'file_not_available', // diese Datei gibt es zu diesem Export nicht (etwa Positionen bei einem alten Export)
+    'too_many_links', // Grenze der aktiven Links je Export oder der neuen Links je Tag erreicht
+    'link_not_found', // unbekannt oder einer anderen Kasse (ein schon widerrufener Link ist kein Fehler: der Widerruf ist wiederholbar)
+    'manager_only', // Kassenweg: nur der Chef (Inhaber oder Recht layout) exportiert; ein Kassier sieht den Hinweis
+    'server_error',
+]);
+/**
+ * Warum ein Export fehlgeschlagen ist (`DepExport.error`): die Werte des
+ * Katalogs `DEP_EXPORT_FEHLER` im Vertrag. `export_stalled` = nach 35 Minuten
+ * nicht fertig.
+ */
+export const DEP_EXPORT_FAILURES = Object.freeze(['export_failed', 'export_stalled']);
+/** Wartezeiten von [waitForDepExport]: 2 s, dann je x1,5, hoechstens 15 s. */
+export const DEP_EXPORT_POLL_START_MS = 2_000;
+export const DEP_EXPORT_POLL_FACTOR = 1.5;
+export const DEP_EXPORT_POLL_MAX_MS = 15_000;
+/** Vorgabe fuer `waitForDepExport.timeoutMs`. */
+export const DEP_EXPORT_WAIT_TIMEOUT_MS = 600_000;
+/** Vorgabe fuer `getDepExportFile.downloadTimeoutMs`: der Aufruf selbst und das Laden ueber einen Lese-Link. */
+export const DEP_EXPORT_DOWNLOAD_TIMEOUT_MS = 600_000;
+/**
+ * [waitForDepExport] gab auf, weil der Export nach `timeoutMs` weder fertig
+ * noch fehlgeschlagen war. Der Export laeuft serverseitig weiter: mit
+ * `getDepExport` (oder erneutem Warten) nachsehen, nicht neu anstossen.
+ */
+export class DepExportTimeoutError extends Error {
+    name = 'DepExportTimeoutError';
+    exportId;
+    timeoutMs;
+    /** Zustand bei der letzten Abfrage. */
+    lastStatus;
+    constructor(exportId, timeoutMs, lastStatus) {
+        super(`waitForDepExport: Export ${exportId} nach ${timeoutMs} ms nicht fertig (Zustand ${lastStatus})`);
+        this.exportId = exportId;
+        this.timeoutMs = timeoutMs;
+        this.lastStatus = lastStatus;
+    }
+}
+/** Das Ergebnis stimmt nicht mit der Pruefsumme ueberein: die Datei ist nicht zu verwenden. */
+export class DepExportChecksumError extends KasseneckValidationError {
+    expected;
+    actual;
+    constructor(exportId, file, expected, actual) {
+        super('getDepExportFile', `Pruefsumme der Datei ${file} von ${exportId} stimmt nicht (erwartet ${expected}, berechnet ${actual})`, 'response');
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+// ---- Hilfen -------------------------------------------------------------------------------------
+const TAG = /^\d{4}-\d{2}-\d{2}$/;
+const ANFRAGE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const SHA256 = /^[0-9a-f]{64}$/i;
+const VORGABEN = {
+    dep: { fileName: (id) => `${id}.json`, contentType: 'application/json' },
+    protocol: { fileName: (id) => `${id}.pdf`, contentType: 'application/pdf' },
+    items: { fileName: (id) => `${id}_positionen.csv`, contentType: 'text/csv; charset=utf-8' },
+    zip: { fileName: (id) => `${id}.zip`, contentType: 'application/zip' },
+};
+function eingabefehler(name, grund) {
+    return new KasseneckValidationError(name, grund, 'request');
+}
+function antwortfehler(name, grund) {
+    return new KasseneckValidationError(name, grund, 'response');
+}
+const istObjekt = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function pruefeKennung(name, feld, wert) {
+    if (typeof wert !== 'string' || wert.trim() === '')
+        throw eingabefehler(name, `${feld} fehlt oder ist leer`);
+    return wert;
+}
+/** Ist das ein echter Kalendertag `JJJJ-MM-TT`? (Rechnung ohne Zeitzone.) */
+function istKalendertag(text) {
+    if (!TAG.test(text))
+        return false;
+    const [j, m, t] = text.split('-').map(Number);
+    const d = new Date(Date.UTC(j, m - 1, t));
+    return d.getUTCFullYear() === j && d.getUTCMonth() === m - 1 && d.getUTCDate() === t;
+}
+async function sha256Hex(bytes) {
+    const umgebung = globalThis;
+    const subtle = umgebung.crypto?.subtle;
+    if (!subtle)
+        throw new Error('getDepExportFile: kein globales crypto.subtle vorhanden — Node >= 20.18 verwenden');
+    const digest = new Uint8Array(await subtle.digest('SHA-256', bytes));
+    return Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+function exportAus(daten, name) {
+    if (!istObjekt(daten))
+        throw antwortfehler(name, 'Antwort enthaelt keine Daten (data fehlt)');
+    const status = daten['status'];
+    if (typeof daten['exportId'] !== 'string' || !DEP_EXPORT_STATUSES.includes(status)) {
+        throw antwortfehler(name, 'Antwort ohne exportId oder mit unbekanntem Zustand');
+    }
+    if (!Array.isArray(daten['handoverLinks']))
+        throw antwortfehler(name, 'Antwort ohne handoverLinks');
+    return daten;
+}
+// ---- Aufrufe ------------------------------------------------------------------------------------
+/**
+ * Stellt einen DEP-Export ein (`createDepExport`) und antwortet sofort mit
+ * `status: 'running'`. Hoechstens ein laufender Export je Kasse
+ * (`export_running`, `details.exportId` nennt ihn). Mit `requestId` ist der
+ * Aufruf wiederholbar: dieselbe Kennung mit demselben Zeitraum liefert den
+ * bestehenden Export mit seinem aktuellen Stand (auch `done` oder `failed`),
+ * mit anderem Zeitraum `idempotency_conflict`.
+ */
+export async function createDepExport(transport, options = {}) {
+    const name = 'createDepExport';
+    const params = {};
+    for (const feld of ['from', 'to']) {
+        const wert = options[feld];
+        if (wert === undefined)
+            continue;
+        if (typeof wert !== 'string' || !istKalendertag(wert))
+            throw eingabefehler(name, `${feld} muss ein Datum JJJJ-MM-TT sein`);
+        params[feld] = wert;
+    }
+    if (options.from !== undefined && options.to !== undefined && options.to < options.from) {
+        throw eingabefehler(name, 'to liegt vor from');
+    }
+    if (options.requestId !== undefined) {
+        if (typeof options.requestId !== 'string' || !ANFRAGE_ID.test(options.requestId)) {
+            throw eingabefehler(name, 'requestId: hoechstens 64 Zeichen aus A-Z, a-z, 0-9, _ und -');
+        }
+        params['requestId'] = options.requestId;
+    }
+    const daten = await transport(name, params);
+    if (!istObjekt(daten) || typeof daten['exportId'] !== 'string' || !DEP_EXPORT_STATUSES.includes(daten['status'])) {
+        throw antwortfehler(name, 'Antwort ohne exportId oder mit unbekanntem Zustand');
+    }
+    return daten;
+}
+/** Zustand, Kennzahlen, Befund und Links eines Exports (`getDepExport`). */
+export async function getDepExport(transport, options) {
+    const name = 'getDepExport';
+    const exportId = pruefeKennung(name, 'exportId', options?.exportId);
+    return exportAus(await transport(name, { exportId }), name);
+}
+/**
+ * Wartet, bis der Export fertig ist, und gibt ihn zurueck. Fragt mit
+ * [DEP_EXPORT_POLL_START_MS] Abstand, dann je x[DEP_EXPORT_POLL_FACTOR],
+ * hoechstens [DEP_EXPORT_POLL_MAX_MS]. Bei `failed` wirft er einen
+ * [KasseneckApiError] mit `code` `export_failed` oder `export_stalled`
+ * (haengender Export); nach `timeoutMs` einen [DepExportTimeoutError]. Ein
+ * Fehler beim Abfragen selbst bricht ab.
+ */
+export async function waitForDepExport(transport, options) {
+    const name = 'waitForDepExport';
+    const exportId = pruefeKennung(name, 'exportId', options?.exportId);
+    const timeoutMs = options.timeoutMs ?? DEP_EXPORT_WAIT_TIMEOUT_MS;
+    if (!(typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0)) {
+        throw eingabefehler(name, 'timeoutMs muss eine positive Zahl sein');
+    }
+    const ende = Date.now() + timeoutMs;
+    let abstand = DEP_EXPORT_POLL_START_MS;
+    for (;;) {
+        const stand = await getDepExport(transport, { exportId });
+        if (stand.status === 'done')
+            return stand;
+        if (stand.status === 'failed') {
+            throw new KasseneckApiError('getDepExport', stand.error === 'export_stalled' ? 'Der Export haengt (Stillstand).' : 'Der Export ist fehlgeschlagen.', { exportId, error: stand.error ?? 'export_failed' }, stand.error ?? 'export_failed');
+        }
+        const rest = ende - Date.now();
+        if (rest <= 0)
+            throw new DepExportTimeoutError(exportId, timeoutMs, stand.status);
+        await new Promise((weiter) => setTimeout(weiter, Math.min(abstand, rest)));
+        abstand = Math.min(abstand * DEP_EXPORT_POLL_FACTOR, DEP_EXPORT_POLL_MAX_MS);
+    }
+}
+function linkAus(name, wert) {
+    if (!istObjekt(wert))
+        throw antwortfehler(name, 'Antwort ist weder eine Datei noch ein Lese-Link (data.download fehlt)');
+    const { url, expiresAt, size, sha256, fileName, contentType } = wert;
+    if (typeof url !== 'string' || typeof expiresAt !== 'string' || typeof fileName !== 'string' || typeof contentType !== 'string' ||
+        typeof sha256 !== 'string' || !SHA256.test(sha256) || typeof size !== 'number' || !Number.isSafeInteger(size) || size < 0) {
+        throw antwortfehler(name, 'Lese-Link unvollstaendig (url, expiresAt, size, sha256, fileName, contentType)');
+    }
+    let adresse;
+    try {
+        adresse = new URL(url);
+    }
+    catch {
+        throw antwortfehler(name, 'Lese-Link ist keine Adresse');
+    }
+    const lokal = adresse.hostname === 'localhost' || adresse.hostname === '127.0.0.1' || adresse.hostname === '[::1]';
+    if (adresse.protocol !== 'https:' && !(adresse.protocol === 'http:' && lokal)) {
+        throw antwortfehler(name, 'Lese-Link ist keine https-Adresse');
+    }
+    return { url, expiresAt, size, sha256: sha256.toLowerCase(), fileName, contentType };
+}
+/** Laedt die Bytes hinter einem Lese-Link. Fehlertexte und Fehlerobjekte nennen die Adresse nie (sie traegt die Berechtigung). */
+async function ladeLink(fetchFn, url, timeoutMs) {
+    const name = 'getDepExportFile';
+    const abbruch = new AbortController();
+    let abgelaufen = false;
+    const wecker = setTimeout(() => {
+        abgelaufen = true;
+        abbruch.abort();
+    }, timeoutMs);
+    try {
+        // Ein GET ohne Rumpf und ohne eigene Kopfzeilen; FetchLike verlangt formal einen Rumpf, den ein GET nicht tragen darf.
+        const antwort = await fetchFn(url, { method: 'GET', headers: {}, signal: abbruch.signal });
+        if (antwort.status !== 200) {
+            throw new KasseneckHttpError(name, antwort.status, antwort.headers.get('content-type') ?? undefined, 'server-error', 'rejected');
+        }
+        return new Uint8Array(await antwort.arrayBuffer());
+    }
+    catch (ursache) {
+        if (ursache instanceof KasseneckHttpError)
+            throw ursache;
+        throw new KasseneckNetworkError(name, abgelaufen, timeoutMs, {}, 'rejected');
+    }
+    finally {
+        clearTimeout(wecker);
+    }
+}
+/**
+ * Holt eine Datei eines fertigen Exports (`getDepExportFile`). Der Server
+ * liefert sie bis 9 MiB selbst, darueber als signierten Lese-Link (15 Minuten);
+ * dem Link folgt dieser Aufruf und laedt die Bytes. In beiden Faellen ist das
+ * Ergebnis dasselbe. Geprueft wird die SHA-256-Summe: beim Lese-Link immer
+ * gegen die Summe des Servers, sonst und zusaetzlich gegen `options.sha256`,
+ * wenn sie bekannt ist. Eine Abweichung wirft [DepExportChecksumError].
+ */
+export async function getDepExportFile(transport, fetchFn, options) {
+    const name = 'getDepExportFile';
+    const exportId = pruefeKennung(name, 'exportId', options?.exportId);
+    if (!DEP_EXPORT_FILES.includes(options.file)) {
+        throw eingabefehler(name, 'file muss dep, protocol, items oder zip sein');
+    }
+    if (options.sha256 !== undefined && !(typeof options.sha256 === 'string' && SHA256.test(options.sha256))) {
+        throw eingabefehler(name, 'sha256 muss 64 Hexzeichen haben');
+    }
+    const frist = options.downloadTimeoutMs ?? DEP_EXPORT_DOWNLOAD_TIMEOUT_MS;
+    if (!(typeof frist === 'number' && Number.isFinite(frist) && frist > 0)) {
+        throw eingabefehler(name, 'downloadTimeoutMs muss eine positive Zahl sein');
+    }
+    const bekannt = options.sha256?.toLowerCase();
+    const vorgabe = VORGABEN[options.file];
+    // Eine direkte Datei (bis 9 MiB) kommt im Aufruf selbst: dieselbe Frist wie das Laden ueber den Link, nicht die 30 s
+    // des Transports.
+    const ergebnis = await transport(name, { exportId, file: options.file }, { timeoutMs: frist });
+    let bytes;
+    let fileName;
+    let contentType;
+    let vomServer;
+    if ('file' in ergebnis) {
+        bytes = ergebnis.file.bytes;
+        fileName = ergebnis.file.fileName ?? vorgabe.fileName(exportId);
+        contentType = ergebnis.file.contentType ?? vorgabe.contentType;
+    }
+    else {
+        const link = linkAus(name, istObjekt(ergebnis.data) ? ergebnis.data['download'] : undefined);
+        bytes = await ladeLink(fetchFn, link.url, frist);
+        if (bytes.length !== link.size) {
+            throw antwortfehler(name, `Die geladene Datei hat ${bytes.length} Byte, der Server nannte ${link.size}`);
+        }
+        fileName = link.fileName;
+        contentType = link.contentType;
+        vomServer = link.sha256;
+    }
+    const summe = await sha256Hex(bytes);
+    for (const erwartet of [vomServer, bekannt]) {
+        if (erwartet !== undefined && erwartet !== summe)
+            throw new DepExportChecksumError(exportId, options.file, erwartet, summe);
+    }
+    return { bytes, fileName, contentType, sha256: summe };
+}
+/** Erzeugt einen Pruefer-Link zu einem fertigen Export (`createDepHandoverLink`). Gueltig 14 Tage. */
+export async function createDepHandoverLink(transport, options) {
+    const name = 'createDepHandoverLink';
+    const exportId = pruefeKennung(name, 'exportId', options?.exportId);
+    const daten = await transport(name, { exportId });
+    if (!istObjekt(daten) || typeof daten['linkId'] !== 'string' || typeof daten['url'] !== 'string' ||
+        typeof daten['code'] !== 'string' || typeof daten['expiresAt'] !== 'string') {
+        throw antwortfehler(name, 'Antwort ohne linkId, url, code oder expiresAt');
+    }
+    return { linkId: daten['linkId'], url: daten['url'], code: daten['code'], expiresAt: daten['expiresAt'] };
+}
+/** Widerruft einen Pruefer-Link der eigenen Kasse (`revokeDepHandoverLink`). */
+export async function revokeDepHandoverLink(transport, options) {
+    const name = 'revokeDepHandoverLink';
+    const linkId = pruefeKennung(name, 'linkId', options?.linkId);
+    const daten = await transport(name, { linkId });
+    if (!istObjekt(daten) || typeof daten['linkId'] !== 'string')
+        throw antwortfehler(name, 'Antwort ohne linkId');
+    return { linkId: daten['linkId'], revokedAt: typeof daten['revokedAt'] === 'string' ? daten['revokedAt'] : null };
+}

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

@@ -1,10 +1,11 @@
 export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, } from './auth.js';
-export { DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type TransportCallOptions, type KasseneckTransport, type KasseneckBinaryTransport, type KasseneckPdfOrDataTransport, type PdfOrData, createTransport, createBinaryTransport, createPdfOrDataTransport, } from './transport.js';
+export { DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type TransportCallOptions, type KasseneckTransport, type KasseneckBinaryTransport, type KasseneckPdfOrDataTransport, type PdfOrData, createTransport, createBinaryTransport, createPdfOrDataTransport, createFileOrDataTransport, type FileOrData, type FileOrDataCallOptions, type KasseneckFileOrDataTransport, } from './transport.js';
 export { ALL_CALLS, type ApiCall, PUBLIC_CALLS, POS_CALLS, UNKNOWN_OUTCOME_CALLS, type PublicCall, type PosCall, } from './aufrufe.js';
 export { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, type ErrorOutcome, CLIENT_ERROR_CODES, type ClientErrorCode, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, isOutcomeUnknown, } from './errors.js';
 export { type ReceiptCommonOptions, type SellReceiptOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, paymentsExpectedCents, cardRefundReference, receiptLayoutFromResult, cancelReceipt, type CancelReceiptResult, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, type ReceiptOutputEntry, type LogReceiptOutputsOptions, type LogReceiptOutputsResult, type RejectedReceiptOutput, logReceiptOutputs, } from './receipts.js';
 export { listMyCashregisters } from './cashregisters.js';
 export { listReceipts, listAllReceipts, fromListReceiptsSummaryPayload, listedReceiptWithCompany, LIST_RECEIPTS_VIEWS, LIST_RECEIPTS_ORDERS, LIST_RECEIPTS_LIMIT_MAX, LIST_RECEIPTS_DAYS_MAX, LIST_ALL_RECEIPTS_MAX_PAGES, LIST_RECEIPTS_ERROR_CODES, type ListReceiptsErrorCode, type ListReceiptsView, type ListReceiptsOrder, type ListReceiptsOptions, type ListReceiptsWindow, type ListReceiptsGrossByRate, type ListReceiptsSummary, type ListReceiptsDaySummary, type ListReceiptsPage, type ListedReceipt, type ListedFullReceipt, type ListReceiptsHeader, } from './list-receipts.js';
+export { createDepExport, getDepExport, waitForDepExport, getDepExportFile, createDepHandoverLink, revokeDepHandoverLink, DepExportTimeoutError, DepExportChecksumError, DEP_EXPORT_STATUSES, DEP_EXPORT_FILES, DEP_EXPORT_ERROR_CODES, DEP_EXPORT_FAILURES, DEP_EXPORT_POLL_START_MS, DEP_EXPORT_POLL_FACTOR, DEP_EXPORT_POLL_MAX_MS, DEP_EXPORT_WAIT_TIMEOUT_MS, DEP_EXPORT_DOWNLOAD_TIMEOUT_MS, type DepExportStatus, type DepExportFileKind, type DepExportErrorCode, type DepExportFailure, type CreateDepExportOptions, type CreateDepExportResult, type DepExportGap, type DepExportChainBreak, type DepExportFindings, type DepExportItems, type DepHandoverLinkInfo, type DepExport, type WaitForDepExportOptions, type GetDepExportFileOptions, type DepExportFile, type DepHandoverLink, type RevokedDepHandoverLink, } from './dep-export.js';
 export { downloadDailyReport, downloadMonthlyReport, getCashregisterReport, getReportV2, type CashregisterReportPeriod, type ReportV2, type ReportV2Metadata, type ReportV2Options } from './reports.js';
 export { type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, } from './status.js';
 export { type KasseneckApi, createKasseneckApi } from './api.js';

package/dist/esm/client/index.js

@@ -1,10 +1,11 @@
 export { apiKeyAuth, registerUserAuth, } from './auth.js';
-export { DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, createTransport, createBinaryTransport, createPdfOrDataTransport, } from './transport.js';
+export { DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, createTransport, createBinaryTransport, createPdfOrDataTransport, createFileOrDataTransport, } from './transport.js';
 export { ALL_CALLS, PUBLIC_CALLS, POS_CALLS, UNKNOWN_OUTCOME_CALLS, } from './aufrufe.js';
 export { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, CLIENT_ERROR_CODES, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, isOutcomeUnknown, } from './errors.js';
 export { sellReceipt, sellReceiptWithCompany, paymentsExpectedCents, cardRefundReference, receiptLayoutFromResult, cancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, checkVoucherCombinationError, sendReceiptEmail, logReceiptOutputs, } from './receipts.js';
 export { listMyCashregisters } from './cashregisters.js';
 export { listReceipts, listAllReceipts, fromListReceiptsSummaryPayload, listedReceiptWithCompany, LIST_RECEIPTS_VIEWS, LIST_RECEIPTS_ORDERS, LIST_RECEIPTS_LIMIT_MAX, LIST_RECEIPTS_DAYS_MAX, LIST_ALL_RECEIPTS_MAX_PAGES, LIST_RECEIPTS_ERROR_CODES, } from './list-receipts.js';
+export { createDepExport, getDepExport, waitForDepExport, getDepExportFile, createDepHandoverLink, revokeDepHandoverLink, DepExportTimeoutError, DepExportChecksumError, DEP_EXPORT_STATUSES, DEP_EXPORT_FILES, DEP_EXPORT_ERROR_CODES, DEP_EXPORT_FAILURES, DEP_EXPORT_POLL_START_MS, DEP_EXPORT_POLL_FACTOR, DEP_EXPORT_POLL_MAX_MS, DEP_EXPORT_WAIT_TIMEOUT_MS, DEP_EXPORT_DOWNLOAD_TIMEOUT_MS, } from './dep-export.js';
 export { downloadDailyReport, downloadMonthlyReport, getCashregisterReport, getReportV2 } from './reports.js';
 export { getCashboxStatus, getSignatureStatus, } from './status.js';
 export { createKasseneckApi } from './api.js';

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

@@ -91,16 +91,16 @@ export interface TransportOptions {
     auth: KasseneckAuth;
     /**
      * Abweichende Basis der **oeffentlichen** Aufrufe (Vorgabe
-     * [DEFAULT_BASE_URL]): alles ausser den 33 Aufrufen des Kassenwegs, und die
-     * sechs oeffentlichen davon nur, wenn nicht mit `registerUserAuth`
+     * [DEFAULT_BASE_URL]): alles ausser den 47 Aufrufen des Kassenwegs, und die
+     * elf oeffentlichen davon nur, wenn nicht mit `registerUserAuth`
      * angemeldet. Muss auf `/v3` enden (eigene Proxys erlaubt), sonst wirft das
      * Anlegen; `/v1` oder `/api` gibt es in der 1.x-Linie nicht.
      */
     baseUrl?: string;
     /**
-     * Abweichende Basis des **Kassenwegs** (Vorgabe [POS_BASE_URL]): die 27
+     * Abweichende Basis des **Kassenwegs** (Vorgabe [POS_BASE_URL]): die 36
      * reinen Kassenaufrufe (Kopplung, Anmeldung, Einstellungen, Artikel,
-     * Drucker, ...) und mit `registerUserAuth` alle 33 Aufrufe des Kassenwegs.
+     * Drucker, ...) und mit `registerUserAuth` alle 47 Aufrufe des Kassenwegs.
      * Die Web-Kasse gibt `'/api/v3'` (gleicher Ursprung). Muss auf `/v3` enden
      * (in der Regel `/api/v3`), sonst wirft das Anlegen.
      */
@@ -217,3 +217,38 @@ export type KasseneckPdfOrDataTransport = (functionName: string, params?: Record
  * ist unlesbar mit denselben Gruenden wie dort.
  */
 export declare function createPdfOrDataTransport(options: TransportOptions): KasseneckPdfOrDataTransport;
+/**
+ * Ergebnis eines Aufrufs, der eine beliebige Datei **oder** eine Nutzlast
+ * liefert: die Datei mit Namen und Inhaltstyp aus den Kopfzeilen der Antwort
+ * (`Content-Disposition: attachment`), oder die `data` einer Erfolgshuelle
+ * (etwa ein Lese-Link, wenn die Datei zu gross fuer die Antwort ist).
+ */
+export type FileOrData = {
+    file: {
+        bytes: Uint8Array;
+        fileName: string | null;
+        contentType: string | undefined;
+    };
+} | {
+    data: unknown;
+};
+/** Optionen je Aufruf des Datei-oder-Daten-Wegs ([createFileOrDataTransport]). */
+export interface FileOrDataCallOptions {
+    /**
+     * Zeitlimit dieses Aufrufs in Millisekunden (Anmeldung, Anfrage und Lesen
+     * des Rumpfs); ohne Angabe `TransportOptions.timeoutMs` (Vorgabe 30 s). Eine
+     * Datei kommt im Rumpf und braucht dafuer laenger als eine Huelle.
+     */
+    timeoutMs?: number;
+}
+/** Ruft eine Backend-Funktion auf, die irgendeine Datei **oder** eine JSON-Nutzlast liefert. */
+export type KasseneckFileOrDataTransport = (functionName: string, params?: Record<string, unknown>, options?: FileOrDataCallOptions) => Promise<FileOrData>;
+/**
+ * Vierter Einstiegspunkt, fuer Aufrufe, deren Datei kein PDF ist (DEP-JSON,
+ * CSV, ZIP: `getDepExportFile`). Die Antwort wird nur als Bytes gelesen.
+ * Entschieden wird an der Kopfzeile `Content-Disposition: attachment` — eine
+ * Datei ist hier selbst JSON und liesse sich am Inhalt nicht von der
+ * Erfolgshuelle trennen. Ohne diese Kopfzeile gilt der Rumpf als Huelle
+ * (Erfolg: `{ data }`, Fehler: derselbe fachliche Fehler wie auf dem JSON-Weg).
+ */
+export declare function createFileOrDataTransport(options: TransportOptions): KasseneckFileOrDataTransport;