@kreiseck/kasseneck-api 0.31.0 → 1.0.0-rc.2

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,41 @@
  *   `'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 Aufruf mit Wirkung 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 Aufruf mit
+ *   Wirkung (signierend oder geldbewegend) 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
+ *   mit Wirkung (signierend: `createReceipt`, `cancelReceipt`,
+ *   `financeWebService`; geldbewegend: `hobexPayApi`, `hobexRefundApi`,
+ *   `stripeCaptureIntent`), 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 +104,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 Aufruf mit Wirkung 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 +141,38 @@ 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 Aufrufs mit Wirkung 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 Aufruf mit Wirkung (`createReceipt`,
+     * `cancelReceipt`, `financeWebService`, `hobexPayApi`, `hobexRefundApi`,
+     * `stripeCaptureIntent`) 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 +186,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 +240,28 @@ 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;
+/**
+ * Liest die Erfolgsantwort eines Aufrufs **mit Wirkung** (signierend oder
+ * geldbewegend). Scheitert das Lesen (fehlender Beleg, fehlender Bezug,
+ * unbrauchbares Feld oder ein Laufzeitfehler beim Umwandeln), hat der Server
+ * trotzdem Erfolg gemeldet: der Beleg ist signiert und im DEP, die Karte
+ * belastet bzw. der Einzug gelaufen. Das darf nie als gewoehnlicher Fehler
+ * enden, sonst kassiert die Kasse ein zweites Mal. Darum wird daraus
+ * `KasseneckApiError` mit Code `response_unreadable` und `outcome: 'unknown'`.
+ * Der Grund stammt vom Paket; aus der Antwort selbst wird nichts uebernommen.
+ *
+ * Paketintern (receipts.ts, payments/); nicht Teil der Paketoberflaeche.
+ */
+export declare function signiertGelesen<T>(functionName: string, lesen: () => T): T;

package/dist/esm/client/errors.js

@@ -11,24 +11,41 @@
  *   `'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 Aufruf mit Wirkung 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 Aufruf mit
+ *   Wirkung (signierend oder geldbewegend) 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
+ *   mit Wirkung (signierend: `createReceipt`, `cancelReceipt`,
+ *   `financeWebService`; geldbewegend: `hobexPayApi`, `hobexRefundApi`,
+ *   `stripeCaptureIntent`), 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 +204,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 Aufruf mit Wirkung 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 +254,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 Aufrufs mit Wirkung 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 +271,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 +280,33 @@ 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 Aufruf mit Wirkung (`createReceipt`,
+     * `cancelReceipt`, `financeWebService`, `hobexPayApi`, `hobexRefundApi`,
+     * `stripeCaptureIntent`) 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 +321,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 +388,49 @@ 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(error) {
+    return error instanceof KasseneckHttpError;
 }
-export function isKasseneckHttpError(fehler) {
-    return fehler instanceof KasseneckHttpError;
+export function isKasseneckNetworkError(error) {
+    return error instanceof KasseneckNetworkError;
 }
-export function isKasseneckNetworkError(fehler) {
-    return fehler instanceof KasseneckNetworkError;
+export function isKasseneckAuthError(error) {
+    return error instanceof KasseneckAuthError;
 }
-export function isKasseneckAuthError(fehler) {
-    return fehler instanceof KasseneckAuthError;
+export function isKasseneckValidationError(error) {
+    return error instanceof KasseneckValidationError;
 }
-export function isKasseneckValidationError(fehler) {
-    return fehler instanceof KasseneckValidationError;
+/**
+ * Liest die Erfolgsantwort eines Aufrufs **mit Wirkung** (signierend oder
+ * geldbewegend). Scheitert das Lesen (fehlender Beleg, fehlender Bezug,
+ * unbrauchbares Feld oder ein Laufzeitfehler beim Umwandeln), hat der Server
+ * trotzdem Erfolg gemeldet: der Beleg ist signiert und im DEP, die Karte
+ * belastet bzw. der Einzug gelaufen. Das darf nie als gewoehnlicher Fehler
+ * enden, sonst kassiert die Kasse ein zweites Mal. Darum wird daraus
+ * `KasseneckApiError` mit Code `response_unreadable` und `outcome: 'unknown'`.
+ * Der Grund stammt vom Paket; aus der Antwort selbst wird nichts uebernommen.
+ *
+ * Paketintern (receipts.ts, payments/); nicht Teil der Paketoberflaeche.
+ */
+export function signiertGelesen(functionName, lesen) {
+    try {
+        return lesen();
+    }
+    catch (ursache) {
+        const grund = ursache instanceof KasseneckValidationError ? ursache.reason : 'Antwort nicht lesbar';
+        throw new KasseneckApiError(functionName, `Erfolg gemeldet, Antwort aber unlesbar (${grund}). Der Vorgang kann ausgefuehrt sein: nicht wiederholen, sondern nachlesen.`, {}, 'response_unreadable');
+    }
 }

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;
+}