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

package/dist/esm/client/aufrufe.js

@@ -1,4 +1,4 @@
-export const AUFRUFE = [
+export const ALL_CALLS = [
     'activateCashregister',
     'cancelInvoice',
     'cancelReceipt',
@@ -30,6 +30,7 @@ export const AUFRUFE = [
     'getPartnerInfo',
     'getPrintJob',
     'getReceipt',
+    'getReportV2',
     'hobexPayApi',
     'hobexRefundApi',
     'issueInvoice',
@@ -52,11 +53,13 @@ export const AUFRUFE = [
     'registerPinLogin',
     'registerUserLogin',
     'renewRegisterSession',
+    'reportCustomerContract',
     'requestCustomerSignature',
     'searchCustomers',
     'sendPartnerCustomerFonLink',
     'sendPartnerWebhookTest',
     'sendReceiptEmail',
+    'setMyKasseLogo',
     'setMyKasseSettings',
     'setMyRegisterDeviceSettings',
     'stripeCaptureIntent',
@@ -65,3 +68,110 @@ export const AUFRUFE = [
     'updateCustomer',
     'updatePartnerWebhook',
 ];
+/**
+ * Die oeffentlichen Endpunkte unter `/v3` (`https://api.kasseneck.at/v3/<name>`),
+ * mit ihrem **aeusseren** Namen und in der Reihenfolge des Backend-Vertrags
+ * (`fixtures/v3/v3-vokabular.json`, `endpoints.public`, umbenannt nach
+ * `names`). Ein Test haelt beide Listen deckungsgleich.
+ */
+export const PUBLIC_CALLS = [
+    'createReceipt',
+    'getReceipt',
+    'cancelReceipt',
+    'sendReceiptEmail',
+    'generateFullReceiptId',
+    'downloadReceipt',
+    'getFirstReceiptDate',
+    'getReportV2',
+    'downloadReport',
+    'downloadDailyReport',
+    'createPaymentLinkStripe',
+    'stripeCaptureIntent',
+    'hobexPayApi',
+    'hobexRefundApi',
+    'hobexGetStatus',
+    'financeWebService',
+    'listMyTipRecipients',
+    'getPartnerInfo',
+    'createPartnerCustomer',
+    'checkPartnerCustomerEmail',
+    'listPartnerCustomers',
+    'getPartnerCustomer',
+    'sendPartnerCustomerFonLink',
+    'createPartnerWebhook',
+    'updatePartnerWebhook',
+    'deletePartnerWebhook',
+    'listPartnerWebhooks',
+    'sendPartnerWebhookTest',
+    'rotatePartnerWebhookSecret',
+    'listPartnerWebhookDeliveries',
+    'requestCustomerSignature',
+    'getCustomerSignatureStatus',
+    'createCustomerCashregister',
+    'activateCashregister',
+    'listCustomerCashregisters',
+    'getCustomerCredentials',
+    'reportCustomerContract',
+    'createCustomer',
+    'getCustomer',
+    'updateCustomer',
+    'searchCustomers',
+    'issueInvoice',
+    'cancelInvoice',
+    'createCreditNote',
+    'getInvoice',
+    'listInvoices',
+    'getInvoicePdf',
+    'getInvoiceXml',
+    'getInvoiceSetupStatus',
+    'listBrands',
+    'recordInvoicePayment',
+];
+/**
+ * Die Endpunkte des Kassenwegs (`https://kasse.kasseneck.at/api/v3/<name>`,
+ * Web-Kasse: gleicher Ursprung `/api/v3`), in der Reihenfolge von
+ * `endpoints.register`. Sechs davon sind zugleich oeffentlich; die Kasse ruft
+ * sie trotzdem ueber diesen Weg (ein Dialekt je Client, Nachtrag §5.2).
+ */
+export const POS_CALLS = [
+    'pairRegisterDevice',
+    'listRegisterUsersForDevice',
+    'listRegisterSessionsForDevice',
+    'registerUserLogin',
+    'registerPinLogin',
+    'renewRegisterSession',
+    'endRegisterSession',
+    'unpairRegisterDevice',
+    'listMyCashregisters',
+    'listMyReceipts',
+    'getReceipt',
+    'createReceipt',
+    'generateFullReceiptId',
+    'cancelReceipt',
+    'sendReceiptEmail',
+    'listMyArticleGroups',
+    'listMyArticles',
+    'getKasseSettings',
+    'setMyKasseSettings',
+    'setMyKasseLogo',
+    'setMyRegisterDeviceSettings',
+    'listMyPrinters',
+    'createPrintJob',
+    'getPrintJob',
+    'listMyTipRecipients',
+];
+const OEFFENTLICH = new Set(PUBLIC_CALLS);
+const KASSENWEG = new Set(POS_CALLS);
+const NUR_KASSE = new Set(POS_CALLS.filter((name) => !OEFFENTLICH.has(name)));
+/** Einer der 25 Aufrufe des Kassenwegs. */
+export function isPosCall(name) {
+    return KASSENWEG.has(name);
+}
+/**
+ * Nur ueber den Kassenweg erreichbar (19 Namen): unter `api.kasseneck.at/v3`
+ * gibt es sie nicht. Der Transport schickt sie darum ohne eigene Basis an
+ * [POS_BASE_URL] statt an die oeffentliche Basis.
+ */
+export function isPosOnlyCall(name) {
+    return NUR_KASSE.has(name);
+}

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

@@ -48,5 +48,7 @@ export interface RegisterUserAuthOptions {
 }
 /** Anmeldung per API-Schluessel und Kassen-Token (Geraete, POS-Apps, Dritte). */
 export declare function apiKeyAuth(options: ApiKeyAuthOptions): KasseneckAuth;
+/** Nur fuer den Transport; nicht Teil der oeffentlichen Oberflaeche. */
+export declare function isRegisterUserAuth(auth: KasseneckAuth): boolean;
 /** Anmeldung eines Kassen-Benutzers der Browser-Kasse (ID-Token + Sitzung). */
 export declare function registerUserAuth(options: RegisterUserAuthOptions): KasseneckAuth;

package/dist/esm/client/auth.js

@@ -42,13 +42,26 @@ export function apiKeyAuth(options) {
         params: {},
     });
 }
+/**
+ * Anmeldungen der Kassen-Benutzer. Ein Transport mit einer davon ruft ohne
+ * eigene Basis **jeden** Aufruf ueber den Kassenweg (`kasse.kasseneck.at/api/v3`,
+ * Kanal `app`), auch die sechs oeffentlichen: die Kasse spricht einen Dialekt
+ * und braucht am Beleg die Anbieterdaten der Kartenzahlung (Nachtrag §5.2, §8).
+ * Eine Menge statt eines Felds am Funktionsobjekt: niemand kann eine fremde
+ * Anmeldung von aussen zur Kassen-Anmeldung erklaeren.
+ */
+const KASSENWEG = new WeakSet();
+/** Nur fuer den Transport; nicht Teil der oeffentlichen Oberflaeche. */
+export function isRegisterUserAuth(auth) {
+    return KASSENWEG.has(auth);
+}
 /** Anmeldung eines Kassen-Benutzers der Browser-Kasse (ID-Token + Sitzung). */
 export function registerUserAuth(options) {
     if (!options.cashregisterId) {
         throw new KasseneckAuthError('registerUserAuth: cashregisterId fehlt');
     }
     const { getIdToken, getSessionId, cashregisterId } = options;
-    return async () => {
+    const anmeldung = async () => {
         // Beides bei JEDEM Aufruf frisch — siehe Modulkommentar (Ablaufzeiten).
         const [idToken, sessionId] = await Promise.all([getIdToken(), getSessionId()]);
         if (!idToken) {
@@ -65,4 +78,6 @@ export function registerUserAuth(options) {
             params: { cashregisterId },
         };
     };
+    KASSENWEG.add(anmeldung);
+    return anmeldung;
 }

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

@@ -18,4 +18,4 @@ import type { InternerTransport } from './aufrufe.js';
  *
  * Ohne diesen Aufruf kann eine Browser-Kasse ihre Kasse nicht auswaehlen.
  */
-export declare function listMyCashregisters(rufen: InternerTransport): Promise<Cashregister[]>;
+export declare function listMyCashregisters(transport: InternerTransport): Promise<Cashregister[]>;

package/dist/esm/client/cashregisters.js

@@ -18,8 +18,8 @@ import { KasseneckValidationError } from './errors.js';
  *
  * Ohne diesen Aufruf kann eine Browser-Kasse ihre Kasse nicht auswaehlen.
  */
-export async function listMyCashregisters(rufen) {
-    const daten = await rufen('listMyCashregisters');
+export async function listMyCashregisters(transport) {
+    const daten = await transport('listMyCashregisters');
     const liste = daten?.cashregisters;
     if (!Array.isArray(liste)) {
         throw new KasseneckValidationError('listMyCashregisters', 'Antwort enthaelt keine Kassenliste (data.cashregisters fehlt)', 'response');

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

@@ -11,24 +11,39 @@
  *   `'response'`: das Backend meldete Erfolg, die Nutzlast enthielt aber
  *   nicht, was der Aufruf zusagt.
  *
- * - `KasseneckApiError` — **fachlicher** Fehler. Das Backend antwortet immer
- *   mit HTTP 200 und legt Erfolg/Misserfolg in den Rumpf
- *   (`{status:'success'|'error', message, data}`, siehe `successResponse`/
- *   `errorResponse` im Backend). Ein `status:'error'` heisst: die Anfrage kam
- *   an und wurde abgelehnt (gesperrte Kasse, fehlendes Modul, ungueltiger
- *   Parameter). Wiederholen hilft nicht.
+ * - `KasseneckApiError`: **fachlicher** Fehler mit `code`. Das Backend legt
+ *   Erfolg/Misserfolg in den Rumpf (`{status:'success'|'error', message,
+ *   code, data}`, siehe `successResponse`/`errorResponse` im Backend), meist
+ *   unter HTTP 200, unter `/v3` bei unbekanntem Endpunkt auch unter HTTP 404
+ *   (`not_found`). Dazu kommen drei Codes des Pakets selbst:
+ *   `route_missing` (HTTP 200 mit HTML: die Auffangregel der
+ *   Single-Page-App hat geantwortet, der Aufruf kam nie an),
+ *   `dialect_mismatch` (Antwort ohne Kennzeichen `Kasseneck-Api-Version: v3`:
+ *   ein Rand ohne `/v3` hat geantwortet, **Ausgang unklar**) und
+ *   `response_unreadable` (ein signierender Aufruf meldete Erfolg, die
+ *   Antwort traegt aber nicht, was er zusagt: **Ausgang unklar**).
+ *   **Entscheidend ist `outcome`:** `'rejected'` heisst abgelehnt, nichts
+ *   geschehen, Wiederholen hilft nicht. `'unknown'` heisst: der Vorgang kann
+ *   ausgefuehrt sein (bei `createReceipt` ein signierter Beleg). Dann **nie
+ *   wiederholen**, sondern das Ergebnis nachlesen (Belegliste, `getReceipt`).
  * - `KasseneckHttpError` — die Antwort war **keine** verwertbare Huelle:
- *   HTTP 500/404, leerer Rumpf, oder HTTP 200 mit HTML statt JSON (typisch,
- *   wenn ein Aufruf mangels Rewrite auf der Single-Page-App landet). Beim
+ *   HTTP 500/404 ohne Huelle, leerer Rumpf oder Text statt JSON. Beim
  *   Bericht-Download gelten dieselben Gruende fuer alles, was kein PDF ist.
- *   `reason` trennt die Faelle maschinenlesbar.
+ *   `reason` trennt die Faelle maschinenlesbar. Auf einem signierenden
+ *   Aufruf hat HTTP 5xx `outcome: 'unknown'`, ebenso HTTP 200 mit
+ *   Kennzeichen, aber leerem oder unlesbarem Rumpf.
  * - `KasseneckNetworkError` — die Antwort kam gar nicht: Netz weg, DNS,
- *   abgebrochene Verbindung oder Zeitueberschreitung (`timedOut`).
+ *   abgebrochene Verbindung oder Zeitueberschreitung (`timedOut`). Auch hier
+ *   gilt `outcome`: war die Anfrage schon unterwegs und ist der Aufruf einer
+ *   der signierenden (`createReceipt`, `cancelReceipt`, `financeWebService`),
+ *   ist er `'unknown'`.
  * - `KasseneckAuthError` — es kam nicht einmal zur Anfrage, weil die Anmeldung
  *   scheiterte (fehlende Zugangsdaten, oder der Token-/Sitzungsgeber warf).
  *   In der Browser-Kasse mit ihrer 90-Sekunden-Sitzung ist das Alltag, kein
  *   Sonderfall.
  *
+ * [isOutcomeUnknown] fasst das fuer jede Fehlerart zusammen.
+ *
  * **Geheimnisse gehoeren in keinen dieser Fehler.** Fehlermeldungen landen in
  * Protokollen und Fehlerdiensten; weder `api_key`, Kassen-Token, ID-
  * ID-Token noch Sitzungsbezeichner duerfen dorthin. Deshalb tragen die Fehler
@@ -87,6 +102,21 @@ export declare function causeDigest(ursache: unknown, geheimnisse: readonly stri
  * demselben Grund **keinen** Vorgabewert.
  */
 export declare function fehlerDetails(daten: unknown, geheimnisse: readonly string[]): Record<string, unknown>;
+/**
+ * Ausgang eines gescheiterten Aufrufs. `'rejected'`: nichts geschehen.
+ * `'unknown'`: der Vorgang kann ausgefuehrt sein; nie wiederholen, sondern
+ * das Ergebnis nachlesen.
+ */
+export type ErrorOutcome = 'unknown' | 'rejected';
+/**
+ * Codes, die das Paket selbst vergibt, nicht der Server: `route_missing`
+ * (HTML statt Backend, der Aufruf kam nie an) und `response_unreadable`
+ * (ein signierender Aufruf meldete Erfolg, die Antwort ist aber unlesbar;
+ * Ausgang unklar). `dialect_mismatch` vergibt das Paket ebenfalls, der Code
+ * gehoert aber schon zum Rand des Servers (`errorCodes.edge`).
+ */
+export declare const CLIENT_ERROR_CODES: readonly ["route_missing", "response_unreadable"];
+export type ClientErrorCode = (typeof CLIENT_ERROR_CODES)[number];
 export declare class KasseneckApiError extends Error {
     readonly name = "KasseneckApiError";
     /** Aufgerufene Backend-Funktion, z. B. `createReceipt`. */
@@ -109,21 +139,37 @@ export declare class KasseneckApiError extends Error {
      * beilegt. Immer ein Objekt, notfalls ein leeres.
      */
     readonly details: Record<string, unknown>;
+    /**
+     * `'unknown'` bei `dialect_mismatch`, `receipt_outcome_unknown`,
+     * `cancellation_outcome_unknown`, `response_unreadable` (Erfolg gemeldet,
+     * Antwort eines signierenden Aufrufs aber unlesbar) und
+     * `response_translation_failed` (ausser mit `details.handled === false`);
+     * sonst `'rejected'`. Bei `'unknown'` nie wiederholen, sondern nachlesen.
+     */
+    readonly outcome: ErrorOutcome;
     constructor(functionName: string, serverMessage: string, details?: Record<string, unknown>, code?: string);
 }
 /** Warum die Antwort keine verwertbare Huelle war. */
 export type HttpFailureReason = 'server-error' | 'empty-body' | 'not-json' | 'missing-status';
-/** Antwort ohne verwertbare Huelle (HTTP-Fehler, leerer Rumpf, HTML statt JSON). */
+/** Antwort ohne verwertbare Huelle (HTTP-Fehler ohne Huelle, leerer Rumpf, Text statt JSON). */
 export declare class KasseneckHttpError extends Error {
     readonly name = "KasseneckHttpError";
     readonly functionName: string;
-    /** HTTP-Statuscode der Antwort (bei HTML-statt-JSON durchaus 200). */
+    /** HTTP-Statuscode der Antwort (bei Text statt JSON durchaus 200). */
     readonly statusCode: number;
     /** Inhaltstyp der Antwort, falls die Gegenstelle einen gesetzt hat. */
     readonly contentType: string | undefined;
     /** Maschinenlesbarer Grund — trennt den Rewrite-Fall vom 500er ohne Textparsen. */
     readonly reason: HttpFailureReason;
-    constructor(functionName: string, statusCode: number, contentType: string | undefined, reason: HttpFailureReason);
+    /**
+     * `'unknown'` auf einem signierenden Aufruf (`createReceipt`,
+     * `cancelReceipt`, `financeWebService`) bei HTTP 5xx und bei HTTP 200 mit
+     * Kennzeichen, aber unlesbarem Rumpf (`empty-body`, `not-json` auch bei
+     * `text/html`, `missing-status`): der Handler kann gelaufen sein, nie wiederholen,
+     * sondern nachlesen. Sonst `'rejected'` (auch 4xx).
+     */
+    readonly outcome: ErrorOutcome;
+    constructor(functionName: string, statusCode: number, contentType: string | undefined, reason: HttpFailureReason, outcome?: ErrorOutcome);
 }
 /** Es kam keine Antwort: Netzfehler oder Zeitueberschreitung. */
 export declare class KasseneckNetworkError extends Error {
@@ -137,7 +183,13 @@ export declare class KasseneckNetworkError extends Error {
     readonly causeName: string | undefined;
     /** Code der zugrunde liegenden Ursache, sofern unbedenklich (z. B. `ECONNREFUSED`). */
     readonly causeCode: string | undefined;
-    constructor(functionName: string, timedOut: boolean, timeoutMs: number, ursache?: CauseDigest);
+    /**
+     * `'unknown'`, wenn die Anfrage schon unterwegs war und der Aufruf signiert
+     * (`createReceipt`, `cancelReceipt`, `financeWebService`): dann nie
+     * wiederholen, sondern nachlesen. Sonst `'rejected'`.
+     */
+    readonly outcome: ErrorOutcome;
+    constructor(functionName: string, timedOut: boolean, timeoutMs: number, cause?: CauseDigest, outcome?: ErrorOutcome);
 }
 /**
  * Die Anmeldung scheiterte — es ging keine Anfrage raus.
@@ -185,8 +237,15 @@ export declare class KasseneckValidationError extends Error {
 }
 /** Alle Fehler, die dieses Paket wirft. */
 export type KasseneckError = KasseneckApiError | KasseneckHttpError | KasseneckNetworkError | KasseneckAuthError | KasseneckValidationError;
-export declare function isKasseneckApiError(fehler: unknown): fehler is KasseneckApiError;
-export declare function isKasseneckHttpError(fehler: unknown): fehler is KasseneckHttpError;
-export declare function isKasseneckNetworkError(fehler: unknown): fehler is KasseneckNetworkError;
-export declare function isKasseneckAuthError(fehler: unknown): fehler is KasseneckAuthError;
-export declare function isKasseneckValidationError(fehler: unknown): fehler is KasseneckValidationError;
+/**
+ * Ist der Ausgang dieses Fehlers unklar (`outcome === 'unknown'`)? Dann den
+ * Aufruf **nicht wiederholen**, sondern das Ergebnis nachlesen. Gilt fuer
+ * jede Fehlerart; nur [KasseneckApiError], [KasseneckHttpError] und
+ * [KasseneckNetworkError] koennen `'unknown'` sein.
+ */
+export declare function isOutcomeUnknown(error: unknown): boolean;
+export declare function isKasseneckApiError(error: unknown): error is KasseneckApiError;
+export declare function isKasseneckHttpError(error: unknown): error is KasseneckHttpError;
+export declare function isKasseneckNetworkError(error: unknown): error is KasseneckNetworkError;
+export declare function isKasseneckAuthError(error: unknown): error is KasseneckAuthError;
+export declare function isKasseneckValidationError(error: unknown): error is KasseneckValidationError;

package/dist/esm/client/errors.js

@@ -11,24 +11,39 @@
  *   `'response'`: das Backend meldete Erfolg, die Nutzlast enthielt aber
  *   nicht, was der Aufruf zusagt.
  *
- * - `KasseneckApiError` — **fachlicher** Fehler. Das Backend antwortet immer
- *   mit HTTP 200 und legt Erfolg/Misserfolg in den Rumpf
- *   (`{status:'success'|'error', message, data}`, siehe `successResponse`/
- *   `errorResponse` im Backend). Ein `status:'error'` heisst: die Anfrage kam
- *   an und wurde abgelehnt (gesperrte Kasse, fehlendes Modul, ungueltiger
- *   Parameter). Wiederholen hilft nicht.
+ * - `KasseneckApiError`: **fachlicher** Fehler mit `code`. Das Backend legt
+ *   Erfolg/Misserfolg in den Rumpf (`{status:'success'|'error', message,
+ *   code, data}`, siehe `successResponse`/`errorResponse` im Backend), meist
+ *   unter HTTP 200, unter `/v3` bei unbekanntem Endpunkt auch unter HTTP 404
+ *   (`not_found`). Dazu kommen drei Codes des Pakets selbst:
+ *   `route_missing` (HTTP 200 mit HTML: die Auffangregel der
+ *   Single-Page-App hat geantwortet, der Aufruf kam nie an),
+ *   `dialect_mismatch` (Antwort ohne Kennzeichen `Kasseneck-Api-Version: v3`:
+ *   ein Rand ohne `/v3` hat geantwortet, **Ausgang unklar**) und
+ *   `response_unreadable` (ein signierender Aufruf meldete Erfolg, die
+ *   Antwort traegt aber nicht, was er zusagt: **Ausgang unklar**).
+ *   **Entscheidend ist `outcome`:** `'rejected'` heisst abgelehnt, nichts
+ *   geschehen, Wiederholen hilft nicht. `'unknown'` heisst: der Vorgang kann
+ *   ausgefuehrt sein (bei `createReceipt` ein signierter Beleg). Dann **nie
+ *   wiederholen**, sondern das Ergebnis nachlesen (Belegliste, `getReceipt`).
  * - `KasseneckHttpError` — die Antwort war **keine** verwertbare Huelle:
- *   HTTP 500/404, leerer Rumpf, oder HTTP 200 mit HTML statt JSON (typisch,
- *   wenn ein Aufruf mangels Rewrite auf der Single-Page-App landet). Beim
+ *   HTTP 500/404 ohne Huelle, leerer Rumpf oder Text statt JSON. Beim
  *   Bericht-Download gelten dieselben Gruende fuer alles, was kein PDF ist.
- *   `reason` trennt die Faelle maschinenlesbar.
+ *   `reason` trennt die Faelle maschinenlesbar. Auf einem signierenden
+ *   Aufruf hat HTTP 5xx `outcome: 'unknown'`, ebenso HTTP 200 mit
+ *   Kennzeichen, aber leerem oder unlesbarem Rumpf.
  * - `KasseneckNetworkError` — die Antwort kam gar nicht: Netz weg, DNS,
- *   abgebrochene Verbindung oder Zeitueberschreitung (`timedOut`).
+ *   abgebrochene Verbindung oder Zeitueberschreitung (`timedOut`). Auch hier
+ *   gilt `outcome`: war die Anfrage schon unterwegs und ist der Aufruf einer
+ *   der signierenden (`createReceipt`, `cancelReceipt`, `financeWebService`),
+ *   ist er `'unknown'`.
  * - `KasseneckAuthError` — es kam nicht einmal zur Anfrage, weil die Anmeldung
  *   scheiterte (fehlende Zugangsdaten, oder der Token-/Sitzungsgeber warf).
  *   In der Browser-Kasse mit ihrer 90-Sekunden-Sitzung ist das Alltag, kein
  *   Sonderfall.
  *
+ * [isOutcomeUnknown] fasst das fuer jede Fehlerart zusammen.
+ *
  * **Geheimnisse gehoeren in keinen dieser Fehler.** Fehlermeldungen landen in
  * Protokollen und Fehlerdiensten; weder `api_key`, Kassen-Token, ID-
  * ID-Token noch Sitzungsbezeichner duerfen dorthin. Deshalb tragen die Fehler
@@ -187,6 +202,34 @@ function feldHinweis(details) {
     const mehr = teile.length > 5 ? ` (+${teile.length - 5} weitere)` : '';
     return ` [${teile.slice(0, 5).join('; ')}${mehr}]`;
 }
+/**
+ * Codes, deren Ausgang unklar ist. `response_translation_failed` nur, wenn
+ * der Rand nicht ausdruecklich `handled: false` meldet (Handler lief und
+ * lehnte ab); `handled: true` oder `null` heisst ausgefuehrt bzw. unbekannt.
+ */
+const AUSGANG_UNKLAR_CODES = new Set([
+    'dialect_mismatch',
+    'receipt_outcome_unknown',
+    'cancellation_outcome_unknown',
+    'response_unreadable',
+]);
+function ausgangAusCode(code, details) {
+    if (code === undefined)
+        return 'rejected';
+    if (AUSGANG_UNKLAR_CODES.has(code))
+        return 'unknown';
+    if (code === 'response_translation_failed' && details['handled'] !== false)
+        return 'unknown';
+    return 'rejected';
+}
+/**
+ * Codes, die das Paket selbst vergibt, nicht der Server: `route_missing`
+ * (HTML statt Backend, der Aufruf kam nie an) und `response_unreadable`
+ * (ein signierender Aufruf meldete Erfolg, die Antwort ist aber unlesbar;
+ * Ausgang unklar). `dialect_mismatch` vergibt das Paket ebenfalls, der Code
+ * gehoert aber schon zum Rand des Servers (`errorCodes.edge`).
+ */
+export const CLIENT_ERROR_CODES = Object.freeze(['route_missing', 'response_unreadable']);
 export class KasseneckApiError extends Error {
     name = 'KasseneckApiError';
     /** Aufgerufene Backend-Funktion, z. B. `createReceipt`. */
@@ -209,6 +252,14 @@ export class KasseneckApiError extends Error {
      * beilegt. Immer ein Objekt, notfalls ein leeres.
      */
     details;
+    /**
+     * `'unknown'` bei `dialect_mismatch`, `receipt_outcome_unknown`,
+     * `cancellation_outcome_unknown`, `response_unreadable` (Erfolg gemeldet,
+     * Antwort eines signierenden Aufrufs aber unlesbar) und
+     * `response_translation_failed` (ausser mit `details.handled === false`);
+     * sonst `'rejected'`. Bei `'unknown'` nie wiederholen, sondern nachlesen.
+     */
+    outcome;
     constructor(functionName, serverMessage, details = {}, code) {
         super(`${functionName} fehlgeschlagen: ${serverMessage}${feldHinweis(details)}`);
         this.functionName = functionName;
@@ -218,6 +269,7 @@ export class KasseneckApiError extends Error {
         // den Details. So bleibt die Klasse fuer beide Ablageorte dieselbe.
         const kandidat = code !== undefined ? code : details['code'];
         this.code = typeof kandidat === 'string' && BEZEICHNER.test(kandidat) ? kandidat : undefined;
+        this.outcome = ausgangAusCode(this.code, details);
     }
 }
 const GRUND_TEXT = {
@@ -226,23 +278,32 @@ const GRUND_TEXT = {
     'not-json': 'Antwort ist kein JSON',
     'missing-status': 'Antwort ohne Statusfeld',
 };
-/** Antwort ohne verwertbare Huelle (HTTP-Fehler, leerer Rumpf, HTML statt JSON). */
+/** Antwort ohne verwertbare Huelle (HTTP-Fehler ohne Huelle, leerer Rumpf, Text statt JSON). */
 export class KasseneckHttpError extends Error {
     name = 'KasseneckHttpError';
     functionName;
-    /** HTTP-Statuscode der Antwort (bei HTML-statt-JSON durchaus 200). */
+    /** HTTP-Statuscode der Antwort (bei Text statt JSON durchaus 200). */
     statusCode;
     /** Inhaltstyp der Antwort, falls die Gegenstelle einen gesetzt hat. */
     contentType;
     /** Maschinenlesbarer Grund — trennt den Rewrite-Fall vom 500er ohne Textparsen. */
     reason;
-    constructor(functionName, statusCode, contentType, reason) {
+    /**
+     * `'unknown'` auf einem signierenden Aufruf (`createReceipt`,
+     * `cancelReceipt`, `financeWebService`) bei HTTP 5xx und bei HTTP 200 mit
+     * Kennzeichen, aber unlesbarem Rumpf (`empty-body`, `not-json` auch bei
+     * `text/html`, `missing-status`): der Handler kann gelaufen sein, nie wiederholen,
+     * sondern nachlesen. Sonst `'rejected'` (auch 4xx).
+     */
+    outcome;
+    constructor(functionName, statusCode, contentType, reason, outcome = 'rejected') {
         const typHinweis = contentType ? `, Inhaltstyp ${contentType}` : '';
         super(`${functionName} fehlgeschlagen: ${GRUND_TEXT[reason]} (HTTP ${statusCode}${typHinweis})`);
         this.functionName = functionName;
         this.statusCode = statusCode;
         this.contentType = contentType;
         this.reason = reason;
+        this.outcome = outcome;
     }
 }
 /** Es kam keine Antwort: Netzfehler oder Zeitueberschreitung. */
@@ -257,15 +318,22 @@ export class KasseneckNetworkError extends Error {
     causeName;
     /** Code der zugrunde liegenden Ursache, sofern unbedenklich (z. B. `ECONNREFUSED`). */
     causeCode;
-    constructor(functionName, timedOut, timeoutMs, ursache = {}) {
+    /**
+     * `'unknown'`, wenn die Anfrage schon unterwegs war und der Aufruf signiert
+     * (`createReceipt`, `cancelReceipt`, `financeWebService`): dann nie
+     * wiederholen, sondern nachlesen. Sonst `'rejected'`.
+     */
+    outcome;
+    constructor(functionName, timedOut, timeoutMs, cause = {}, outcome = 'rejected') {
         const grund = timedOut ? `Zeitueberschreitung nach ${timeoutMs} ms` : 'Netzwerkfehler';
-        const codeHinweis = ursache.causeCode ? ` (${ursache.causeCode})` : '';
+        const codeHinweis = cause.causeCode ? ` (${cause.causeCode})` : '';
         super(`${functionName} fehlgeschlagen: ${grund}${codeHinweis}`);
         this.functionName = functionName;
         this.timedOut = timedOut;
         this.timeoutMs = timeoutMs;
-        this.causeName = ursache.causeName;
-        this.causeCode = ursache.causeCode;
+        this.causeName = cause.causeName;
+        this.causeCode = cause.causeCode;
+        this.outcome = outcome;
     }
 }
 /**
@@ -317,18 +385,28 @@ export class KasseneckValidationError extends Error {
         this.scope = scope;
     }
 }
-export function isKasseneckApiError(fehler) {
-    return fehler instanceof KasseneckApiError;
+/**
+ * Ist der Ausgang dieses Fehlers unklar (`outcome === 'unknown'`)? Dann den
+ * Aufruf **nicht wiederholen**, sondern das Ergebnis nachlesen. Gilt fuer
+ * jede Fehlerart; nur [KasseneckApiError], [KasseneckHttpError] und
+ * [KasseneckNetworkError] koennen `'unknown'` sein.
+ */
+export function isOutcomeUnknown(error) {
+    return ((error instanceof KasseneckApiError || error instanceof KasseneckHttpError || error instanceof KasseneckNetworkError)
+        && error.outcome === 'unknown');
+}
+export function isKasseneckApiError(error) {
+    return error instanceof KasseneckApiError;
 }
-export function isKasseneckHttpError(fehler) {
-    return fehler instanceof KasseneckHttpError;
+export function isKasseneckHttpError(error) {
+    return error instanceof KasseneckHttpError;
 }
-export function isKasseneckNetworkError(fehler) {
-    return fehler instanceof KasseneckNetworkError;
+export function isKasseneckNetworkError(error) {
+    return error instanceof KasseneckNetworkError;
 }
-export function isKasseneckAuthError(fehler) {
-    return fehler instanceof KasseneckAuthError;
+export function isKasseneckAuthError(error) {
+    return error instanceof KasseneckAuthError;
 }
-export function isKasseneckValidationError(fehler) {
-    return fehler instanceof KasseneckValidationError;
+export function isKasseneckValidationError(error) {
+    return error instanceof KasseneckValidationError;
 }

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

@@ -0,0 +1,9 @@
+/** Der Code des Fehlers, wenn er in `bekannt` steht; sonst `undefined`. */
+export declare function bekannterCode<C extends string>(error: unknown, bekannt: ReadonlySet<string>): C | undefined;
+/** Ein Feldfehler aus `data.errors[]` einer `validation`-Antwort. */
+export interface Feldfehler {
+    field: string;
+    message: string;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export declare function feldfehlerVon(error: unknown): Feldfehler[];

package/dist/esm/client/fehlercodes.js

@@ -0,0 +1,32 @@
+import { KasseneckApiError } from './errors.js';
+/*
+ * Gemeinsame Bausteine der Fehlerhelfer je Teilpfad (Belege, Storno,
+ * Zahlungen, Belegmail, Kasse, Anmeldung, Rechnung, Partner). Jeder Teilpfad
+ * bietet dieselbe Form: eine Codeliste, `isXErrorCode(wert)`,
+ * `xErrorCode(fehler)`, `isXError(fehler, code?)` und die Feldfehler einer
+ * `validation`-Antwort. Paketintern, nicht Teil der Oberflaeche.
+ */
+/** Der Code des Fehlers, wenn er in `bekannt` steht; sonst `undefined`. */
+export function bekannterCode(error, bekannt) {
+    if (!(error instanceof KasseneckApiError))
+        return undefined;
+    const code = error.code;
+    return code !== undefined && bekannt.has(code) ? code : undefined;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export function feldfehlerVon(error) {
+    if (!(error instanceof KasseneckApiError))
+        return [];
+    const roh = error.details['errors'];
+    if (!Array.isArray(roh))
+        return [];
+    const raus = [];
+    for (const eintrag of roh) {
+        if (eintrag === null || typeof eintrag !== 'object')
+            continue;
+        const { field, message } = eintrag;
+        if (typeof field === 'string' && typeof message === 'string')
+            raus.push({ field, message });
+    }
+    return raus;
+}

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

@@ -1,9 +1,9 @@
 export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, } from './auth.js';
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type KasseneckTransport, type KasseneckBinaryTransport, createTransport, createBinaryTransport, } from './transport.js';
-export { AUFRUFE, type Aufruf, } from './aufrufe.js';
-export { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, } from './errors.js';
-export { type ReceiptCommonOptions, type SellReceiptOptions, type SellReceiptWithPaymentsOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CreateCancelReceiptOptions, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, cancelReceipt, type CancelReceiptResult, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, } from './receipts.js';
+export { DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type KasseneckTransport, type KasseneckBinaryTransport, createTransport, createBinaryTransport, } from './transport.js';
+export { ALL_CALLS, type ApiCall, PUBLIC_CALLS, POS_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, } from './receipts.js';
 export { listMyCashregisters } from './cashregisters.js';
-export { downloadDailyReport, downloadMonthlyReport } from './reports.js';
+export { downloadDailyReport, downloadMonthlyReport, getReportV2, 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,9 +1,9 @@
 export { apiKeyAuth, registerUserAuth, } from './auth.js';
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, createTransport, createBinaryTransport, } from './transport.js';
-export { AUFRUFE, } from './aufrufe.js';
-export { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, } from './errors.js';
-export { sellReceipt, sellReceiptWithCompany, cancelReceipt, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, checkVoucherCombinationError, sendReceiptEmail, } from './receipts.js';
+export { DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, createTransport, createBinaryTransport, } from './transport.js';
+export { ALL_CALLS, PUBLIC_CALLS, POS_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, } from './receipts.js';
 export { listMyCashregisters } from './cashregisters.js';
-export { downloadDailyReport, downloadMonthlyReport } from './reports.js';
+export { downloadDailyReport, downloadMonthlyReport, getReportV2 } from './reports.js';
 export { getCashboxStatus, getSignatureStatus, } from './status.js';
 export { createKasseneckApi } from './api.js';