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

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

@@ -2,8 +2,9 @@ import type { Cashregister, HobexReceipt, Receipt, ReportMonth, StripeUrlSession
 import { type CreateStripeLinkOptions, type StripeCaptureResult } from '../payments/stripe.js';
 import { type HobexPayOptions, type HobexRefundOptions } from '../payments/hobex.js';
 import { type TransportOptions } from './transport.js';
+import { type ReportV2, type ReportV2Options } from './reports.js';
 import { type CashboxStatus, type SignatureStatus } from './status.js';
-import { type SendReceiptEmailOptions, type SendReceiptEmailResult, type ListMyReceiptsOptions, type ReceiptList, type ReceiptWithCompany, type SellReceiptOptions, type SellReceiptWithPaymentsOptions, type CancelReceiptOptions, type CancelReceiptResult, type CreateCancelReceiptOptions } from './receipts.js';
+import { type SendReceiptEmailOptions, type SendReceiptEmailResult, type ListMyReceiptsOptions, type ReceiptList, type ReceiptWithCompany, type SellReceiptOptions, type CancelReceiptOptions, type CancelReceiptResult } from './receipts.js';
 /**
  * Schlichte Factory ueber den Endpunkt-Funktionen: bindet einen Transport
  * einmal und liefert die Aufrufe ohne den wiederkehrenden ersten Parameter.
@@ -30,13 +31,11 @@ import { type SendReceiptEmailOptions, type SendReceiptEmailResult, type ListMyR
  */
 export interface KasseneckApi {
     /** Normalbeleg (Verkauf). */
-    sellReceipt(options: SellReceiptOptions | SellReceiptWithPaymentsOptions): Promise<Receipt>;
+    sellReceipt(options: SellReceiptOptions): Promise<Receipt>;
     /** Normalbeleg samt Firmen-/Druckdaten fuer den Belegdruck. */
-    sellReceiptWithCompany(options: SellReceiptOptions | SellReceiptWithPaymentsOptions): Promise<ReceiptWithCompany>;
+    sellReceiptWithCompany(options: SellReceiptOptions): Promise<ReceiptWithCompany>;
     /** Storno eines bestehenden Belegs — voll oder in Teilen, ueber den Storno-Endpunkt. */
     cancelReceipt(options: CancelReceiptOptions): Promise<CancelReceiptResult>;
-    /** Storno aus frei uebergebenen Positionen. */
-    createCancelReceipt(options: CreateCancelReceiptOptions): Promise<Receipt>;
     /** Nullbeleg (RKSV-Pruefbeleg). */
     zeroReceipt(): Promise<Receipt>;
     /** Einzelnen Beleg holen. */
@@ -53,6 +52,8 @@ export interface KasseneckApi {
     listMyReceipts(options: ListMyReceiptsOptions): Promise<ReceiptList>;
     /** Kassen des angemeldeten Benutzers (nur mit ID-Token, siehe cashregisters.ts). */
     listMyCashregisters(): Promise<Cashregister[]>;
+    /** Rohdaten eines Zeitraums: Belege und Firmendaten (`getReportV2`). */
+    getReportV2(options: ReportV2Options): Promise<ReportV2>;
     /** Tagesbericht als PDF (Kalendertag nach Wiener Zeit). */
     downloadDailyReport(date: Date): Promise<Uint8Array>;
     /** Monatsbericht als PDF (Endpunkt `downloadReport`). */
@@ -60,7 +61,7 @@ export interface KasseneckApi {
     /** Betriebsstatus der Kasse bei FinanzOnline. */
     getCashboxStatus(): Promise<CashboxStatus>;
     /** Status der Signatureinheit bei FinanzOnline. */
-    getSignatureStatus(zertifikatNrHex: string): Promise<SignatureStatus>;
+    getSignatureStatus(certificateSerialHex: string): Promise<SignatureStatus>;
     /** Stripe-Zahlungslink erzeugen (Endpunkt `createPaymentLinkStripe`). */
     createStripeLink(options: CreateStripeLinkOptions): Promise<StripeUrlSession>;
     /** Reservierte Stripe-Zahlung einziehen. */

package/dist/cjs/client/api.js

@@ -18,7 +18,6 @@ function createKasseneckApi(options) {
         sellReceipt: (o) => (0, receipts_js_1.sellReceipt)(rufen, o),
         sellReceiptWithCompany: (o) => (0, receipts_js_1.sellReceiptWithCompany)(rufen, o),
         cancelReceipt: (o) => (0, receipts_js_1.cancelReceipt)(rufen, o),
-        createCancelReceipt: (o) => (0, receipts_js_1.createCancelReceipt)(rufen, o),
         zeroReceipt: () => (0, receipts_js_1.zeroReceipt)(rufen),
         getReceipt: (receiptId) => (0, receipts_js_1.getReceipt)(rufen, receiptId),
         getReceiptWithCompany: (receiptId) => (0, receipts_js_1.getReceiptWithCompany)(rufen, receiptId),
@@ -27,10 +26,11 @@ function createKasseneckApi(options) {
         listMyReceipts: (o) => (0, receipts_js_1.listMyReceipts)(rufen, o),
         sendReceiptEmail: (o) => (0, receipts_js_1.sendReceiptEmail)(rufen, o),
         listMyCashregisters: () => (0, cashregisters_js_1.listMyCashregisters)(rufen),
+        getReportV2: (o) => (0, reports_js_1.getReportV2)(rufen, o),
         downloadDailyReport: (date) => (0, reports_js_1.downloadDailyReport)(rufenBinaer, date),
         downloadMonthlyReport: (reportMonth) => (0, reports_js_1.downloadMonthlyReport)(rufenBinaer, reportMonth),
         getCashboxStatus: () => (0, status_js_1.getCashboxStatus)(rufen),
-        getSignatureStatus: (zertifikatNrHex) => (0, status_js_1.getSignatureStatus)(rufen, zertifikatNrHex),
+        getSignatureStatus: (certificateSerialHex) => (0, status_js_1.getSignatureStatus)(rufen, certificateSerialHex),
         createStripeLink: (o) => (0, stripe_js_1.createStripeLink)(rufen, o),
         stripeCaptureIntent: (stripeSessionId) => (0, stripe_js_1.stripeCaptureIntent)(rufen, stripeSessionId),
         hobexPay: (o) => (0, hobex_js_1.hobexPay)(rufen, o),

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

@@ -2,7 +2,7 @@
  * Die Namen der Backend-Functions, die dieses Paket aufruft — als Daten, nicht
  * als Zeichenketten im Code verstreut. Zwei Gruende:
  *
- * 1. Der Vertrag (`fixtures/oberflaeche.json`) gibt die Liste aus, damit die
+ * 1. Der Vertrag (`fixtures/surface.json`) gibt die Liste aus, damit die
  *    Zwillinge pruefen koennen, ob sie denselben Aufruf kennen.
  * 2. Die paketinternen Module nehmen [InternerTransport] statt
  *    [KasseneckTransport] entgegen; ein Tippfehler im Aufrufnamen ist damit ein
@@ -13,9 +13,33 @@
  * umhuellt, muss ihn weiterhin absetzen koennen.
  */
 import type { TransportBodyFields } from './transport.js';
-export declare const AUFRUFE: readonly ["activateCashregister", "cancelInvoice", "cancelReceipt", "createCreditNote", "createCustomer", "createCustomerCashregister", "createPartnerCustomer", "checkPartnerCustomerEmail", "createPartnerWebhook", "createPaymentLinkStripe", "createPrintJob", "createReceipt", "deletePartnerWebhook", "downloadDailyReport", "downloadReport", "endRegisterSession", "financeWebService", "generateFullReceiptId", "getCustomer", "getCustomerCredentials", "getCustomerSignatureStatus", "getFirstReceiptDate", "getInvoice", "getInvoicePdf", "getInvoiceSetupStatus", "getInvoiceXml", "getKasseSettings", "getPartnerCustomer", "getPartnerInfo", "getPrintJob", "getReceipt", "hobexPayApi", "hobexRefundApi", "issueInvoice", "listCustomerCashregisters", "listInvoices", "listBrands", "listMyArticleGroups", "listMyArticles", "listMyCashregisters", "listMyPrinters", "listMyReceipts", "listMyTipRecipients", "listPartnerCustomers", "listPartnerWebhookDeliveries", "listPartnerWebhooks", "listRegisterUsersForDevice", "listRegisterSessionsForDevice", "pairRegisterDevice", "recordInvoicePayment", "registerPinLogin", "registerUserLogin", "renewRegisterSession", "requestCustomerSignature", "searchCustomers", "sendPartnerCustomerFonLink", "sendPartnerWebhookTest", "sendReceiptEmail", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "unpairRegisterDevice", "rotatePartnerWebhookSecret", "updateCustomer", "updatePartnerWebhook"];
-export type Aufruf = typeof AUFRUFE[number];
+export declare const ALL_CALLS: readonly ["activateCashregister", "cancelInvoice", "cancelReceipt", "createCreditNote", "createCustomer", "createCustomerCashregister", "createPartnerCustomer", "checkPartnerCustomerEmail", "createPartnerWebhook", "createPaymentLinkStripe", "createPrintJob", "createReceipt", "deletePartnerWebhook", "downloadDailyReport", "downloadReport", "endRegisterSession", "financeWebService", "generateFullReceiptId", "getCustomer", "getCustomerCredentials", "getCustomerSignatureStatus", "getFirstReceiptDate", "getInvoice", "getInvoicePdf", "getInvoiceSetupStatus", "getInvoiceXml", "getKasseSettings", "getPartnerCustomer", "getPartnerInfo", "getPrintJob", "getReceipt", "getReportV2", "hobexPayApi", "hobexRefundApi", "issueInvoice", "listCustomerCashregisters", "listInvoices", "listBrands", "listMyArticleGroups", "listMyArticles", "listMyCashregisters", "listMyPrinters", "listMyReceipts", "listMyTipRecipients", "listPartnerCustomers", "listPartnerWebhookDeliveries", "listPartnerWebhooks", "listRegisterUsersForDevice", "listRegisterSessionsForDevice", "pairRegisterDevice", "recordInvoicePayment", "registerPinLogin", "registerUserLogin", "renewRegisterSession", "reportCustomerContract", "requestCustomerSignature", "searchCustomers", "sendPartnerCustomerFonLink", "sendPartnerWebhookTest", "sendReceiptEmail", "setMyKasseLogo", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "unpairRegisterDevice", "rotatePartnerWebhookSecret", "updateCustomer", "updatePartnerWebhook"];
+export type ApiCall = typeof ALL_CALLS[number];
+/**
+ * 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 declare const PUBLIC_CALLS: readonly ["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 declare const POS_CALLS: readonly ["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"];
+export type PublicCall = typeof PUBLIC_CALLS[number];
+export type PosCall = typeof POS_CALLS[number];
+/** Einer der 25 Aufrufe des Kassenwegs. */
+export declare function isPosCall(name: string): boolean;
+/**
+ * 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 declare function isPosOnlyCall(name: string): boolean;
 /** Wie [KasseneckTransport], nur mit bekanntem Aufrufnamen. Nicht exportiert nach aussen. */
-export type InternerTransport = <T = unknown>(functionName: Aufruf, params?: Record<string, unknown>, extraBodyFields?: TransportBodyFields, secretParams?: readonly string[]) => Promise<T>;
+export type InternerTransport = <T = unknown>(functionName: ApiCall, params?: Record<string, unknown>, extraBodyFields?: TransportBodyFields, secretParams?: readonly string[]) => Promise<T>;
 /** Wie [KasseneckBinaryTransport], nur mit bekanntem Aufrufnamen. */
-export type InternerBinaerTransport = (functionName: Aufruf, params?: Record<string, unknown>) => Promise<Uint8Array>;
+export type InternerBinaerTransport = (functionName: ApiCall, params?: Record<string, unknown>) => Promise<Uint8Array>;

package/dist/cjs/client/aufrufe.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUFRUFE = void 0;
-exports.AUFRUFE = [
+exports.POS_CALLS = exports.PUBLIC_CALLS = exports.ALL_CALLS = void 0;
+exports.isPosCall = isPosCall;
+exports.isPosOnlyCall = isPosOnlyCall;
+exports.ALL_CALLS = [
     'activateCashregister',
     'cancelInvoice',
     'cancelReceipt',
@@ -33,6 +35,7 @@ exports.AUFRUFE = [
     'getPartnerInfo',
     'getPrintJob',
     'getReceipt',
+    'getReportV2',
     'hobexPayApi',
     'hobexRefundApi',
     'issueInvoice',
@@ -55,11 +58,13 @@ exports.AUFRUFE = [
     'registerPinLogin',
     'registerUserLogin',
     'renewRegisterSession',
+    'reportCustomerContract',
     'requestCustomerSignature',
     'searchCustomers',
     'sendPartnerCustomerFonLink',
     'sendPartnerWebhookTest',
     'sendReceiptEmail',
+    'setMyKasseLogo',
     'setMyKasseSettings',
     'setMyRegisterDeviceSettings',
     'stripeCaptureIntent',
@@ -68,3 +73,110 @@ exports.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.
+ */
+exports.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).
+ */
+exports.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(exports.PUBLIC_CALLS);
+const KASSENWEG = new Set(exports.POS_CALLS);
+const NUR_KASSE = new Set(exports.POS_CALLS.filter((name) => !OEFFENTLICH.has(name)));
+/** Einer der 25 Aufrufe des Kassenwegs. */
+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.
+ */
+function isPosOnlyCall(name) {
+    return NUR_KASSE.has(name);
+}

package/dist/cjs/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/cjs/client/auth.js

@@ -23,6 +23,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.apiKeyAuth = apiKeyAuth;
+exports.isRegisterUserAuth = isRegisterUserAuth;
 exports.registerUserAuth = registerUserAuth;
 const errors_js_1 = require("./errors.js");
 /** Anmeldung per API-Schluessel und Kassen-Token (Geraete, POS-Apps, Dritte). */
@@ -46,13 +47,26 @@ 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. */
+function isRegisterUserAuth(auth) {
+    return KASSENWEG.has(auth);
+}
 /** Anmeldung eines Kassen-Benutzers der Browser-Kasse (ID-Token + Sitzung). */
 function registerUserAuth(options) {
     if (!options.cashregisterId) {
         throw new errors_js_1.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) {
@@ -69,4 +83,6 @@ function registerUserAuth(options) {
             params: { cashregisterId },
         };
     };
+    KASSENWEG.add(anmeldung);
+    return anmeldung;
 }

package/dist/cjs/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/cjs/client/cashregisters.js

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

package/dist/cjs/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;