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

package/dist/cjs/client/reports.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.downloadDailyReport = downloadDailyReport;
 exports.downloadMonthlyReport = downloadMonthlyReport;
+exports.getReportV2 = getReportV2;
+const index_js_1 = require("../models/index.js");
 const vienna_time_js_1 = require("../vienna-time.js");
 const errors_js_1 = require("./errors.js");
 /**
@@ -35,7 +37,7 @@ const errors_js_1 = require("./errors.js");
  */
 // `async`, damit auch die Eingabepruefung als abgelehntes Versprechen ankommt
 // und nicht als synchroner Wurf am `await` des Aufrufers vorbei.
-async function downloadDailyReport(rufen, date) {
+async function downloadDailyReport(transport, date) {
     let wanduhr;
     try {
         wanduhr = (0, vienna_time_js_1.toViennaWallClock)(date);
@@ -45,7 +47,7 @@ async function downloadDailyReport(rufen, date) {
         // Rumpf (JSON.stringify macht aus NaN null) und einen ratlosen Serverfehler.
         throw eingabefehler('downloadDailyReport', 'Uebergebener Zeitpunkt ist unbrauchbar (Invalid Date)');
     }
-    return rufen('downloadDailyReport', { year: wanduhr.year, month: wanduhr.month, day: wanduhr.day });
+    return transport('downloadDailyReport', { year: wanduhr.year, month: wanduhr.month, day: wanduhr.day });
 }
 /**
  * Monatsbericht als PDF.
@@ -57,7 +59,7 @@ async function downloadDailyReport(rufen, date) {
  * `month` geht als **Zahl 1-12** raus (im Flutter-Paket `reportMonth.month.id`,
  * wo `KeckMonth.january.id === 1` ist) — kein Name, kein nullbasierter Index.
  */
-async function downloadMonthlyReport(rufen, reportMonth) {
+async function downloadMonthlyReport(transport, reportMonth) {
     const { month, year } = reportMonth;
     if (!Number.isInteger(month) || month < 1 || month > 12) {
         throw eingabefehler('downloadReport', `Berichtsmonat: month muss 1-12 sein, war "${month}"`);
@@ -65,7 +67,38 @@ async function downloadMonthlyReport(rufen, reportMonth) {
     if (!Number.isInteger(year)) {
         throw eingabefehler('downloadReport', `Berichtsmonat: year muss eine ganze Zahl sein, war "${year}"`);
     }
-    return rufen('downloadReport', { month, year });
+    return transport('downloadReport', { month, year });
+}
+/**
+ * Rohdaten eines Zeitraums (`getReportV2`): alle Belege der Kasse und die
+ * Firmendaten fuer Kopf und Fuss. Der Server vergleicht die Zeitstempel als
+ * Text (`start <= timeStamp < end`), darum Wiener Wanduhr im Serverformat.
+ * Nur ueber den API-Schluessel-Weg (Kasse aus dem `cashregister-token`).
+ */
+async function getReportV2(transport, options) {
+    for (const feld of ['start', 'end']) {
+        const wert = options?.[feld];
+        if (typeof wert !== 'string' || !/^\d{4}-\d{2}-\d{2}/.test(wert)) {
+            throw eingabefehler('getReportV2', `${feld} muss mit YYYY-MM-DD beginnen, war "${String(wert)}"`);
+        }
+    }
+    if (options.start >= options.end) {
+        throw eingabefehler('getReportV2', 'end muss nach start liegen (end ist ausschliesslich)');
+    }
+    const daten = await transport('getReportV2', { start: options.start, end: options.end });
+    const liste = daten?.receipts;
+    if (!Array.isArray(liste) || liste.some((b) => b == null || typeof b !== 'object' || Array.isArray(b))) {
+        throw new errors_js_1.KasseneckValidationError('getReportV2', 'Antwort enthaelt keine Belegliste (data.receipts fehlt)', 'response');
+    }
+    const meta = daten.metadata;
+    if (meta == null || typeof meta !== 'object' || Array.isArray(meta)) {
+        throw new errors_js_1.KasseneckValidationError('getReportV2', 'Antwort enthaelt keine Firmendaten (data.metadata fehlt)', 'response');
+    }
+    const label = meta.label;
+    return {
+        receipts: liste.map((b) => (0, index_js_1.fromReceiptPayload)(b)),
+        metadata: { ...(0, index_js_1.fromReceiptCompanyPayload)(meta), label: typeof label === 'string' ? label : '' },
+    };
 }
 /** Fehler in der Eingabe des Aufrufers — es geht keine Anfrage raus. */
 function eingabefehler(functionName, grund) {

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

@@ -31,13 +31,13 @@ export type CashboxStatus = 'AKTIVIERT' | 'REGISTRIERT' | 'IN_BETRIEB' | 'AUSFAL
  */
 export type SignatureStatus = CashboxStatus | 'NOT_REGISTERED';
 /** Betriebsstatus der Kasse bei FinanzOnline. */
-export declare function getCashboxStatus(rufen: InternerTransport): Promise<CashboxStatus>;
+export declare function getCashboxStatus(transport: InternerTransport): Promise<CashboxStatus>;
 /**
- * Status der Signatureinheit mit der Zertifikatsseriennummer [zertifikatNrHex]
+ * Status der Signatureinheit mit der Zertifikatsseriennummer [certificateSerialHex]
  * (hexadezimal, z. B. `6F0404F0`).
  *
  * **Der Returncode wird vor dem Status gelesen** (wie im Dart-Vorbild): `B33`
  * heisst "nicht registriert" und schlaegt jedes Statusfeld, das daneben stehen
  * mag. Andersherum meldete eine nie registrierte Karte am Ende "in Betrieb".
  */
-export declare function getSignatureStatus(rufen: InternerTransport, zertifikatNrHex: string): Promise<SignatureStatus>;
+export declare function getSignatureStatus(transport: InternerTransport, certificateSerialHex: string): Promise<SignatureStatus>;

package/dist/cjs/client/status.js

@@ -14,23 +14,23 @@ const errors_js_1 = require("./errors.js");
 const VORGANG_KASSE = 'financeWebService/status_cashbox';
 const VORGANG_SIGNATUR = 'financeWebService/status_signature';
 /** Betriebsstatus der Kasse bei FinanzOnline. */
-async function getCashboxStatus(rufen) {
-    const daten = await rufen('financeWebService', {}, { method: 'status_cashbox' });
+async function getCashboxStatus(transport) {
+    const daten = await transport('financeWebService', {}, { method: 'status_cashbox' });
     return statusAusMeldung(daten, VORGANG_KASSE);
 }
 /**
- * Status der Signatureinheit mit der Zertifikatsseriennummer [zertifikatNrHex]
+ * Status der Signatureinheit mit der Zertifikatsseriennummer [certificateSerialHex]
  * (hexadezimal, z. B. `6F0404F0`).
  *
  * **Der Returncode wird vor dem Status gelesen** (wie im Dart-Vorbild): `B33`
  * heisst "nicht registriert" und schlaegt jedes Statusfeld, das daneben stehen
  * mag. Andersherum meldete eine nie registrierte Karte am Ende "in Betrieb".
  */
-async function getSignatureStatus(rufen, zertifikatNrHex) {
-    if (typeof zertifikatNrHex !== 'string' || !zertifikatNrHex.trim()) {
-        throw new errors_js_1.KasseneckValidationError(VORGANG_SIGNATUR, 'zertifikatNrHex fehlt', 'request');
+async function getSignatureStatus(transport, certificateSerialHex) {
+    if (typeof certificateSerialHex !== 'string' || !certificateSerialHex.trim()) {
+        throw new errors_js_1.KasseneckValidationError(VORGANG_SIGNATUR, 'certificateSerialHex fehlt', 'request');
     }
-    const daten = await rufen('financeWebService', { zertifikatnr_hex: zertifikatNrHex }, { method: 'status_signature' });
+    const daten = await transport('financeWebService', { zertifikatnr_hex: certificateSerialHex }, { method: 'status_signature' });
     if (daten?.rkdbMessage?.rc === 'B33') {
         return 'NOT_REGISTERED';
     }

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

@@ -1,4 +1,4 @@
-import type { KasseneckAuth } from './auth.js';
+import { type KasseneckAuth } from './auth.js';
 /**
  * Transport zum Kasseneck-Backend: ein Aufruf ist ein POST an
  * `<basis>/<funktionsname>` mit dem JSON-Rumpf `{ "params": { … } }` — wie im
@@ -15,12 +15,32 @@ import type { KasseneckAuth } from './auth.js';
  * Fehlerarten sind bei beiden dieselben; sie unterscheiden sich nur darin, wie
  * der Antwortrumpf gelesen und ausgewertet wird.
  *
+ * **Nur `/v3`, fail closed.** Jede Antwort muss das Kennzeichen
+ * `Kasseneck-Api-Version: v3` tragen; fehlt es, wirft der Transport
+ * `dialect_mismatch`, **bevor** er den Rumpf liest, und tut nichts weiter
+ * (Nachtrag §5.4, Risiko R1: eine Route auf eine Function mit altem Rand
+ * haette die englischen Parameter deutsch gedeutet). Eine HTML-Antwort ist
+ * `route_missing`: die Hosting-Auffangregel hat den Aufruf abgefangen, bevor
+ * ihn eine Function sah.
+ *
+ * **Kasseneck-Kopfzeilen nur an Kasseneck-Basen** (Nachtrag §6, Risiko R3):
+ * `Kasseneck-Api-Version: v3` und `Kasseneck-Client: <produkt>/<version>`
+ * setzt der Transport selbst, abhaengig von der Basis, und nie ueber die
+ * `fetch`-Umsetzung. Dieselbe Umsetzung darf darum auch Connect, ePOS-Drucker
+ * und Terminals bedienen, ohne dass dort eine fremde Kopfzeile den Vorflug
+ * scheitern laesst.
+ *
  * **Kein Wiederholen fehlgeschlagener Aufrufe.** Ein Beleg ist nicht folgenlos
  * wiederholbar; ohne entschiedene Idempotenz waere ein automatischer zweiter
  * Versuch ein zweiter Beleg.
  */
-/** Basis-URL der Produktion. */
-export declare const DEFAULT_BASE_URL = "https://api.kasseneck.at/v1";
+/** Basis-URL der oeffentlichen API (Produktion). */
+export declare const DEFAULT_BASE_URL = "https://api.kasseneck.at/v3";
+/**
+ * Basis-URL des Kassenwegs (Kanal `app`, Nachtrag §5.2). Die Web-Kasse ruft
+ * denselben Weg im gleichen Ursprung als `/api/v3`.
+ */
+export declare const POS_BASE_URL = "https://kasse.kasseneck.at/api/v3";
 /**
  * Zeitlimit je Aufruf (wie im Flutter-Zwilling). Ohne Zeitlimit bleibt eine
  * haengende Anfrage fuer immer offen — der Aufrufer bekaeme weder Ergebnis
@@ -63,12 +83,44 @@ export type FetchLike = (url: string, init: HttpRequestInit) => Promise<HttpResp
 export interface TransportOptions {
     /** Anmeldung; wird pro Aufruf befragt. */
     auth: KasseneckAuth;
-    /** Abweichende Basis-URL (z. B. eigene Rewrites der Browser-Kasse). */
+    /**
+     * Abweichende Basis der **oeffentlichen** Aufrufe (Vorgabe
+     * [DEFAULT_BASE_URL]): alles ausser den 25 Aufrufen des Kassenwegs, und die
+     * sechs oeffentlichen davon nur, wenn nicht mit `registerUserAuth`
+     * angemeldet. Muss auf `/v3` enden (eigene Proxys erlaubt), sonst wirft das
+     * Anlegen; `/v1` oder `/api` gibt es in der 1.x-Linie nicht.
+     */
     baseUrl?: string;
+    /**
+     * Abweichende Basis des **Kassenwegs** (Vorgabe [POS_BASE_URL]): die 19
+     * reinen Kassenaufrufe (Kopplung, Anmeldung, Einstellungen, Artikel,
+     * Drucker, ...) und mit `registerUserAuth` alle 25 Aufrufe des Kassenwegs.
+     * Die Web-Kasse gibt `'/api/v3'` (gleicher Ursprung). Muss auf `/v3` enden
+     * (in der Regel `/api/v3`), sonst wirft das Anlegen.
+     */
+    posBaseUrl?: string;
     /** Zeitlimit je Aufruf in Millisekunden. */
     timeoutMs?: number;
     /** Eigene `fetch`-Umsetzung (Tests, Proxys). */
     fetch?: FetchLike;
+    /**
+     * Wert der Kopfzeile `Kasseneck-Client`, Vorgabe `kasseneck-api/<version>`.
+     * Eine App nennt sich selbst (`kasse-web/<build>`, `kasse-app/<version+build>`).
+     * Erlaubt sind nur die Produkte `kasse-web`, `kasse-app`, `kasseneck-api`,
+     * `kasseneck_api` mit einer Version aus `[0-9A-Za-z.+-]` (hoechstens 40
+     * Zeichen, gesamt hoechstens 64); sonst wirft das Anlegen.
+     */
+    clientHeader?: string;
+    /**
+     * `true` laesst `Kasseneck-Api-Version` und `Kasseneck-Client` auch an
+     * Kasseneck-Basen weg. Fuer Browser, die die oeffentliche API von einem
+     * fremden Ursprung aus rufen: solange der Vorflug unter `/v3` die beiden
+     * Kopfzeilen nicht erlaubt, scheiterte sonst jeder Aufruf schon dort. Die
+     * Pruefung des Kennzeichens in der **Antwort** bleibt unberuehrt; es entfaellt
+     * nur die Gegenpruefung des Rands (`createReceipt`/`cancelReceipt` weisen
+     * eine als v3 gekennzeichnete Anfrage auf einem Nicht-v3-Pfad ab).
+     */
+    omitKasseneckHeaders?: boolean;
 }
 /**
  * Ruft eine Backend-Funktion auf und liefert deren Nutzlast **ohne Huelle**.

package/dist/cjs/client/transport.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_BASE_URL = void 0;
+exports.DEFAULT_TIMEOUT_MS = exports.POS_BASE_URL = exports.DEFAULT_BASE_URL = void 0;
 exports.createTransport = createTransport;
 exports.createBinaryTransport = createBinaryTransport;
+const auth_js_1 = require("./auth.js");
+const aufrufe_js_1 = require("./aufrufe.js");
+const version_js_1 = require("../version.js");
 const errors_js_1 = require("./errors.js");
 /**
  * Transport zum Kasseneck-Backend: ein Aufruf ist ein POST an
@@ -20,12 +23,69 @@ const errors_js_1 = require("./errors.js");
  * Fehlerarten sind bei beiden dieselben; sie unterscheiden sich nur darin, wie
  * der Antwortrumpf gelesen und ausgewertet wird.
  *
+ * **Nur `/v3`, fail closed.** Jede Antwort muss das Kennzeichen
+ * `Kasseneck-Api-Version: v3` tragen; fehlt es, wirft der Transport
+ * `dialect_mismatch`, **bevor** er den Rumpf liest, und tut nichts weiter
+ * (Nachtrag §5.4, Risiko R1: eine Route auf eine Function mit altem Rand
+ * haette die englischen Parameter deutsch gedeutet). Eine HTML-Antwort ist
+ * `route_missing`: die Hosting-Auffangregel hat den Aufruf abgefangen, bevor
+ * ihn eine Function sah.
+ *
+ * **Kasseneck-Kopfzeilen nur an Kasseneck-Basen** (Nachtrag §6, Risiko R3):
+ * `Kasseneck-Api-Version: v3` und `Kasseneck-Client: <produkt>/<version>`
+ * setzt der Transport selbst, abhaengig von der Basis, und nie ueber die
+ * `fetch`-Umsetzung. Dieselbe Umsetzung darf darum auch Connect, ePOS-Drucker
+ * und Terminals bedienen, ohne dass dort eine fremde Kopfzeile den Vorflug
+ * scheitern laesst.
+ *
  * **Kein Wiederholen fehlgeschlagener Aufrufe.** Ein Beleg ist nicht folgenlos
  * wiederholbar; ohne entschiedene Idempotenz waere ein automatischer zweiter
  * Versuch ein zweiter Beleg.
  */
-/** Basis-URL der Produktion. */
-exports.DEFAULT_BASE_URL = 'https://api.kasseneck.at/v1';
+/** Basis-URL der oeffentlichen API (Produktion). */
+exports.DEFAULT_BASE_URL = 'https://api.kasseneck.at/v3';
+/**
+ * Basis-URL des Kassenwegs (Kanal `app`, Nachtrag §5.2). Die Web-Kasse ruft
+ * denselben Weg im gleichen Ursprung als `/api/v3`.
+ */
+exports.POS_BASE_URL = 'https://kasse.kasseneck.at/api/v3';
+/** Kennzeichen der `/v3`-Antworten und -Anfragen. */
+const VERSION_KOPF = 'Kasseneck-Api-Version';
+const CLIENT_KOPF = 'Kasseneck-Client';
+const VERSION_WERT = 'v3';
+/**
+ * Hosts, die als Kasseneck-Basis gelten, nur ueber https und ohne eigenen
+ * Port. Alles andere (Proxys, Emulator, `127.0.0.1` fuer Connect) bekommt die
+ * Kasseneck-Kopfzeilen nicht.
+ */
+const KASSENECK_HOSTS = new Set(['api.kasseneck.at', 'kasse.kasseneck.at']);
+/** Die 1.x-Linie spricht nur `/v3`: jede Basis endet so (`/v3` oder `/api/v3`). */
+const V3_ENDE = /\/v3$/;
+/**
+ * Aufrufe mit Wirkung, die nie blind wiederholt werden duerfen: sie signieren
+ * (`createReceipt`, `cancelReceipt`), loesen bei FinanzOnline etwas aus
+ * (`financeWebService`) oder bewegen Geld (`hobexPayApi` belastet eine Karte,
+ * `hobexRefundApi` erstattet, `stripeCaptureIntent` zieht eine vorgemerkte
+ * Zahlung ein). Scheitert einer, nachdem die Anfrage unterwegs war (Netz,
+ * Zeitlimit, HTTP 5xx, unlesbare Erfolgsantwort, HTML mit Kennzeichen), ist
+ * sein Ausgang offen.
+ */
+const UNKNOWN_OUTCOME_CALLS = new Set([
+    'createReceipt',
+    'cancelReceipt',
+    'financeWebService',
+    'hobexPayApi',
+    'hobexRefundApi',
+    'stripeCaptureIntent',
+]);
+/**
+ * Produkte, die das Backend in `Kasseneck-Client` zaehlt (Positivliste,
+ * Nachtrag §6); alles andere zaehlte dort als `ungueltig`. Das Paket weist
+ * es darum schon beim Anlegen des Transports ab.
+ */
+const CLIENT_PRODUKTE = new Set(['kasse-web', 'kasse-app', 'kasseneck-api', 'kasseneck_api']);
+const CLIENT_VERSION = /^[0-9A-Za-z.+-]{1,40}$/;
+const CLIENT_MAX = 64;
 /**
  * Zeitlimit je Aufruf (wie im Flutter-Zwilling). Ohne Zeitlimit bleibt eine
  * haengende Anfrage fuer immer offen — der Aufrufer bekaeme weder Ergebnis
@@ -54,9 +114,22 @@ function createBinaryTransport(options) {
  * `auswerten`.
  */
 function createCore(options) {
-    const basis = (options.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const oeffentlicheBasis = v3Basis('baseUrl', options.baseUrl) ?? exports.DEFAULT_BASE_URL;
+    const kassenBasis = v3Basis('posBaseUrl', options.posBaseUrl) ?? exports.POS_BASE_URL;
+    const kassenweg = (0, auth_js_1.isRegisterUserAuth)(options.auth);
     const zeitlimitMs = options.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
     const holen = options.fetch ?? globalesFetch();
+    const kennung = options.clientHeader ?? `kasseneck-api/${version_js_1.PACKAGE_VERSION}`;
+    pruefeKennung(kennung);
+    const kopfzeilenSenden = options.omitKasseneckHeaders !== true;
+    /**
+     * Basis je Aufruf. Die 19 reinen Kassenaufrufe gehen immer an den
+     * Kassenweg (unter der oeffentlichen Basis gibt es sie nicht), und die
+     * Kassen-Anmeldung ruft alle 25 Aufrufe des Kassenwegs dort, auch die sechs
+     * oeffentlichen (Kanal `app`). Was der Kassenweg gar nicht fuehrt
+     * (Berichte, Zahlungen, FinanzOnline), geht an die oeffentliche Basis.
+     */
+    const basisFuer = (functionName) => (0, aufrufe_js_1.isPosOnlyCall)(functionName) || (kassenweg && (0, aufrufe_js_1.isPosCall)(functionName)) ? kassenBasis : oeffentlicheBasis;
     return async function aufrufen(functionName, params = {}, extraBodyFields, secretParams, lesen, auswerten) {
         // Die URL nennt die Backend-Funktion, die Fehler nennen den **Vorgang**:
         // `financeWebService` fuehrt ein Dutzend verschiedener Vorgaenge unter einem
@@ -92,13 +165,26 @@ function createCore(options) {
             // Geraetegeheimnis, PIN). Ohne die zweite Haelfte greift die Zusage genau
             // dort nicht, wo es gar keine Kopfzeilen gibt.
             const geheimnisse = [...Object.values(anmeldung.headers), ...(secretParams ?? [])];
+            // Bis zur ersten Antwort (bzw. beim Lesen des Rumpfs) ist alles Scheitern
+            // Netz oder Zeitlimit.
+            const netzfehler = (ursache) => {
+                // Ein Formfehler des Pakets ist kein Netzfehler und behaelt seine Art
+                // (der Binaerweg wirft ihn, wenn die fetch-Antwort keine Bytes liefert).
+                if (ursache instanceof errors_js_1.KasseneckValidationError) {
+                    return ursache;
+                }
+                // Bis hierher kam keine verwertbare Antwort: Netz weg oder Zeitlimit.
+                // Die Anfrage war schon unterwegs: bei einem Aufruf mit Wirkung kann
+                // der Beleg bzw. die Zahlung entstanden sein (Ausgang unklar, nachlesen).
+                return new errors_js_1.KasseneckNetworkError(fehlerName, abbruch.signal.aborted, zeitlimitMs, (0, errors_js_1.causeDigest)(ursache, geheimnisse), UNKNOWN_OUTCOME_CALLS.has(functionName) ? 'unknown' : 'rejected');
+            };
+            const basis = basisFuer(functionName);
             const url = `${basis}/${encodeURIComponent(functionName)}`;
             // `params` steht ZULETZT: so kann kein Zusatzfeld die Nutzlast (und mit
             // ihr die Kassenbindung aus der Anmeldung) verdraengen — auch nicht von
             // einem Verbraucher, der ohne Typen an TransportBodyFields vorbeikommt.
             const rumpf = JSON.stringify({ ...extraBodyFields, params: nutzlast(anmeldung.params, params) });
             let antwort;
-            let koerper;
             try {
                 // Auch der Aufruf laeuft gegen den Abbruch — nicht nur die Anmeldung.
                 // Das `AbortSignal` geht zwar mit, aber ob eine fetch-Umsetzung es
@@ -111,30 +197,69 @@ function createCore(options) {
                 antwort = await Promise.race([
                     holen(url, {
                         method: 'POST',
-                        headers: { 'Content-Type': 'application/json', ...anmeldung.headers },
+                        headers: {
+                            'Content-Type': 'application/json',
+                            ...ohneKasseneckKopfzeilen(anmeldung.headers),
+                            ...(kopfzeilenSenden && istKasseneckBasis(basis)
+                                ? { [VERSION_KOPF]: VERSION_WERT, [CLIENT_KOPF]: kennung }
+                                : {}),
+                        },
                         body: rumpf,
                         signal: abbruch.signal,
                     }),
                     abbruchAlsAblehnung(abbruch.signal),
                 ]);
-                koerper = await Promise.race([lesen(antwort, fehlerName), abbruchAlsAblehnung(abbruch.signal)]);
             }
             catch (ursache) {
-                // Ein Formfehler des Pakets ist kein Netzfehler und behaelt seine Art
-                // (der Binaerweg wirft ihn, wenn die fetch-Antwort keine Bytes liefert).
-                if (ursache instanceof errors_js_1.KasseneckValidationError) {
-                    throw ursache;
-                }
-                // Bis hierher kam keine verwertbare Antwort: Netz weg oder Zeitlimit.
-                throw new errors_js_1.KasseneckNetworkError(fehlerName, abbruch.signal.aborted, zeitlimitMs, (0, errors_js_1.causeDigest)(ursache, geheimnisse));
+                throw netzfehler(ursache);
             }
+            // Alles Folgende entscheidet an den Kopfzeilen, **bevor** der Rumpf
+            // gelesen wird: was nicht vom `/v3`-Rand kommt, wird nicht gedeutet.
             const inhaltstyp = antwort.headers.get('content-type') ?? undefined;
             // Das Backend antwortet auf jeden fachlichen Ausgang mit HTTP 200; alles
-            // andere kommt nicht von ihm (Proxy, Rewrite-Luecke, Infrastruktur).
+            // andere kommt nicht von ihm (Proxy, Rewrite-Luecke, Infrastruktur). Das
+            // steht VOR der HTML-Pruefung: eine 500er-Fehlerseite ist auch HTML, aber
+            // dort kann eine Function gelaufen sein; `route_missing` sagt das Gegenteil.
             if (antwort.status !== 200) {
-                throw new errors_js_1.KasseneckHttpError(fehlerName, antwort.status, inhaltstyp, 'server-error');
+                // Ausnahme: der `/v3`-Rand antwortet auf einen unbekannten Endpunkt mit
+                // HTTP 404, Kennzeichen und Huelle samt Code (`not_found`). Nur mit
+                // Kennzeichen wird dieser Rumpf gelesen.
+                if (antwort.status === 404 && traegtKennzeichen(antwort)) {
+                    const fehler = await randFehler404(antwort, fehlerName, geheimnisse, abbruch.signal);
+                    if (fehler)
+                        throw fehler;
+                }
+                // 5xx auf einem Aufruf mit Wirkung: der Handler kann gelaufen sein.
+                const ausgang = antwort.status >= 500 && UNKNOWN_OUTCOME_CALLS.has(functionName) ? 'unknown' : 'rejected';
+                throw new errors_js_1.KasseneckHttpError(fehlerName, antwort.status, inhaltstyp, 'server-error', ausgang);
+            }
+            // HTTP 200 mit HTML: die Auffangregel der Single-Page-App hat den Aufruf
+            // bedient, keine Function hat ihn gesehen (Nachtrag §5.4, R15).
+            if (inhaltstyp !== undefined && /^\s*text\/html\b/i.test(inhaltstyp)) {
+                // Mit Kennzeichen hat der `/v3`-Rand den Aufruf gesehen (etwa ein
+                // Proxy, der nur den Inhaltstyp umschreibt). Bei einem Aufruf mit
+                // Wirkung kann der Beleg bzw. die Zahlung dann entstanden sein: unlesbarer Rumpf,
+                // Ausgang unklar, statt `route_missing`.
+                if (UNKNOWN_OUTCOME_CALLS.has(functionName) && traegtKennzeichen(antwort)) {
+                    throw new errors_js_1.KasseneckHttpError(fehlerName, antwort.status, inhaltstyp, 'not-json', 'unknown');
+                }
+                throw new errors_js_1.KasseneckApiError(fehlerName, 'Route fehlt: die Antwort ist eine HTML-Seite statt des Backends', {}, 'route_missing');
+            }
+            if (!traegtKennzeichen(antwort)) {
+                throw new errors_js_1.KasseneckApiError(fehlerName, 'Server spricht nicht /v3 (Kennzeichen Kasseneck-Api-Version fehlt); Antwort verworfen', {}, 'dialect_mismatch');
+            }
+            let koerper;
+            try {
+                koerper = await Promise.race([lesen(antwort, fehlerName), abbruchAlsAblehnung(abbruch.signal)]);
             }
-            return auswerten(koerper, fehlerName, antwort.status, inhaltstyp, geheimnisse);
+            catch (ursache) {
+                throw netzfehler(ursache);
+            }
+            // Ab hier kam HTTP 200 mit Kennzeichen: der `/v3`-Rand hat den Aufruf
+            // gesehen. Ist der Rumpf dann unlesbar (gekuerzt von einem Proxy,
+            // abgebrochene Verbindung), kann ein Handler mit Wirkung gelaufen sein.
+            const unlesbar = UNKNOWN_OUTCOME_CALLS.has(functionName) ? 'unknown' : 'rejected';
+            return auswerten(koerper, fehlerName, antwort.status, inhaltstyp, geheimnisse, unlesbar);
         }
         finally {
             // Ohne Abraeumen haelt der Wecker den Node-Prozess bis zum Zeitlimit wach.
@@ -142,6 +267,90 @@ function createCore(options) {
         }
     };
 }
+/** Traegt die Antwort das Kennzeichen `Kasseneck-Api-Version: v3`? */
+function traegtKennzeichen(antwort) {
+    return (antwort.headers.get(VERSION_KOPF) ?? '').trim().toLowerCase() === VERSION_WERT;
+}
+/**
+ * Liest die 404-Huelle des `/v3`-Rands. Liefert den fachlichen Fehler, wenn
+ * es eine Fehlerhuelle mit Code ist, sonst `null` (dann bleibt es beim
+ * HTTP-Fehler). Ein Lesefehler zaehlt ebenfalls als `null`.
+ */
+async function randFehler404(antwort, functionName, geheimnisse, signal) {
+    try {
+        const text = await Promise.race([antwort.text(), abbruchAlsAblehnung(signal)]);
+        const huelle = alsHuelle(JSON.parse(text));
+        if (huelle === null || huelle.status === 'success')
+            return null;
+        const fehler = fachfehler(functionName, huelle.message, huelle.data, geheimnisse, huelle.code);
+        return fehler.code === undefined ? null : fehler;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Prueft eine abweichende Basis beim Anlegen: die 1.x-Linie spricht nur
+ * `/v3`. Liefert sie ohne abschliessende Schraegstriche, oder `undefined`
+ * ohne Angabe.
+ */
+function v3Basis(option, basis) {
+    if (basis === undefined)
+        return undefined;
+    const ohne = typeof basis === 'string' ? basis.replace(/\/+$/, '') : '';
+    if (!V3_ENDE.test(ohne)) {
+        const beispiel = option === 'posBaseUrl' ? "'/api/v3' bzw. POS_BASE_URL" : 'DEFAULT_BASE_URL';
+        throw new errors_js_1.KasseneckValidationError('createTransport', `${option} muss auf /v3 oder /api/v3 enden (1.x spricht nur /v3; z. B. ${beispiel} statt /api oder /v1)`, 'request');
+    }
+    return ohne;
+}
+/**
+ * Ist `basis` eine Kasseneck-Basis? Relativ (gleicher Ursprung) immer,
+ * ausser `//host` (fremder Host ohne Schema); absolut nur
+ * `https://api.kasseneck.at` bzw. `https://kasse.kasseneck.at` ohne Port und
+ * ohne Zugangsdaten.
+ */
+function istKasseneckBasis(basis) {
+    if (basis.startsWith('//'))
+        return false;
+    let adresse;
+    try {
+        adresse = new URL(basis);
+    }
+    catch {
+        // Keine absolute Adresse: relativ zum eigenen Ursprung.
+        return true;
+    }
+    return adresse.protocol === 'https:'
+        && adresse.port === ''
+        && adresse.username === ''
+        && adresse.password === ''
+        && KASSENECK_HOSTS.has(adresse.hostname);
+}
+/**
+ * Die beiden Kasseneck-Kopfzeilen setzt allein der Transport. Liefert die
+ * Anmeldung sie mit (in beliebiger Schreibweise), fallen sie weg: sonst kaeme
+ * ein zweiter Wert daneben, oder eine fremde Basis bekaeme sie doch.
+ */
+function ohneKasseneckKopfzeilen(kopfzeilen) {
+    const gesperrt = new Set([VERSION_KOPF.toLowerCase(), CLIENT_KOPF.toLowerCase()]);
+    const ergebnis = {};
+    for (const [name, wert] of Object.entries(kopfzeilen)) {
+        if (!gesperrt.has(name.toLowerCase()))
+            ergebnis[name] = wert;
+    }
+    return ergebnis;
+}
+/** Prueft `Kasseneck-Client` gegen Positivliste und Form (Nachtrag §6). */
+function pruefeKennung(kennung) {
+    const text = typeof kennung === 'string' ? kennung : '';
+    const trenner = text.indexOf('/');
+    const produkt = trenner > 0 ? text.slice(0, trenner) : '';
+    const version = trenner > 0 ? text.slice(trenner + 1) : '';
+    if (text.length > CLIENT_MAX || !CLIENT_PRODUKTE.has(produkt) || !CLIENT_VERSION.test(version)) {
+        throw new errors_js_1.KasseneckValidationError('createTransport', 'clientHeader muss <produkt>/<version> sein (Produkt: kasse-web, kasse-app, kasseneck-api, kasseneck_api)', 'request');
+    }
+}
 /** JSON-Weg: der Rumpf ist Text. */
 const alsText = (antwort) => antwort.text();
 /**
@@ -159,9 +368,9 @@ const alsBytes = async (antwort, functionName) => {
     return new Uint8Array(await antwort.arrayBuffer());
 };
 /** Auswertung des JSON-Wegs: Huelle aufloesen, Nutzlast zurueckgeben. */
-function jsonAuswerten(text, functionName, statusCode, inhaltstyp, geheimnisse) {
+function jsonAuswerten(text, functionName, statusCode, inhaltstyp, geheimnisse, unlesbar) {
     if (!text.trim()) {
-        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'empty-body');
+        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'empty-body', unlesbar);
     }
     let roh;
     try {
@@ -170,11 +379,11 @@ function jsonAuswerten(text, functionName, statusCode, inhaltstyp, geheimnisse)
     catch {
         // Typischer Fall: der Aufruf landete mangels Rewrite auf der HTML-Seite
         // der Single-Page-App — HTTP 200, aber kein JSON.
-        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'not-json');
+        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'not-json', unlesbar);
     }
     const huelle = alsHuelle(roh);
     if (huelle === null) {
-        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'missing-status');
+        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'missing-status', unlesbar);
     }
     if (huelle.status === 'success') {
         return huelle.data;
@@ -196,9 +405,9 @@ function jsonAuswerten(text, functionName, statusCode, inhaltstyp, geheimnisse)
  * das Backend hier erzeugt (pdf-lib). Alles, was nicht so anfaengt, ist kein
  * Bericht — und wird dann daraufhin angesehen, ob es die Fehlerhuelle ist.
  */
-function pdfAuswerten(bytes, functionName, statusCode, inhaltstyp, geheimnisse) {
+function pdfAuswerten(bytes, functionName, statusCode, inhaltstyp, geheimnisse, unlesbar) {
     if (bytes.length === 0) {
-        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'empty-body');
+        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'empty-body', unlesbar);
     }
     if (istPdf(bytes)) {
         return bytes;
@@ -214,11 +423,11 @@ function pdfAuswerten(bytes, functionName, statusCode, inhaltstyp, geheimnisse)
         roh = JSON.parse(new TextDecoder('utf-8').decode(bytes));
     }
     catch {
-        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'not-json');
+        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'not-json', unlesbar);
     }
     const huelle = alsHuelle(roh);
     if (huelle === null) {
-        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'missing-status');
+        throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'missing-status', unlesbar);
     }
     if (huelle.status === 'success') {
         // Erfolg gemeldet, aber kein PDF geliefert: die Antwort traegt nicht, was

package/dist/cjs/enums/vat-rate.d.ts

@@ -10,8 +10,8 @@ export declare const VatRate: {
         readonly rate: 0;
         readonly category: "D";
     };
-    readonly vat4komma9: {
-        readonly value: "vat4komma9";
+    readonly vat4_9: {
+        readonly value: "vat4_9";
         readonly rate: 4.9;
         readonly category: "G";
     };

package/dist/cjs/enums/vat-rate.js

@@ -11,7 +11,7 @@ const define_enum_js_1 = require("./define-enum.js");
 exports.VatRate = (0, define_enum_js_1.defineEnum)({
     vat0: { value: 'vat0', rate: 0, category: 'D' },
     // Grundnahrungsmittel ab 01.07.2026 -> Betrag-Satz-Besonders (BMF/RKSV)
-    vat4komma9: { value: 'vat4komma9', rate: 4.9, category: 'G' },
+    vat4_9: { value: 'vat4_9', rate: 4.9, category: 'G' },
     vat10: { value: 'vat10', rate: 10, category: 'B' },
     vat13: { value: 'vat13', rate: 13, category: 'C' },
     vat19: { value: 'vat19', rate: 19, category: 'E' },

package/dist/cjs/index.d.ts

@@ -1,5 +1,6 @@
 export { ReceiptType, type ReceiptTypeKey, VatRate, type VatRateKey, KeckPaymentMethod, type KeckPaymentMethodKey, CreditCardProvider, type CreditCardProviderKey, VoucherType, type VoucherTypeKey, VoucherAction, type VoucherActionKey, StripeLinkMode, type StripeLinkModeKey, } from './enums/index.js';
-export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, type Voucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, type Receipt, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode, type ReceiptEmailErrorCode, RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, remainingQuantities, type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, fromCashregisterPayload, type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, istZeroKind, type ReportMonth, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, type StripeUrlSession, type StripeUrlSessionPayload, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, type HobexReceipt, type HobexReceiptPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
-export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type KasseneckTransport, type KasseneckBinaryTransport, AUFRUFE, type Aufruf, createTransport, createBinaryTransport, KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, type ReceiptCommonOptions, type SellReceiptOptions, type SellReceiptWithPaymentsOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CancelReceiptResult, type CreateCancelReceiptOptions, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, cancelReceipt, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, listMyCashregisters, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, downloadDailyReport, downloadMonthlyReport, type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, type KasseneckApi, createKasseneckApi, } from './client/index.js';
+export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, type Voucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, type Receipt, type RegistrationInfo, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, type CancellationStatus, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, type CancellationFieldError, type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode, paymentErrorCode, isPaymentError, paymentFieldErrors, type PaymentFieldError, type ReceiptEmailErrorCode, type ReceiptEmailVia, RECEIPT_EMAIL_ERROR_CODES, RECEIPT_EMAIL_SEND_ERROR_CODES, type ReceiptEmailSendErrorCode, RECEIPT_EMAIL_VIAS, isReceiptEmailErrorCode, receiptEmailErrorCode, isReceiptEmailError, receiptEmailFieldErrors, type ReceiptEmailFieldError, type ReceiptErrorCode, type ReceiptFieldError, RECEIPT_ERROR_CODES, isReceiptErrorCode, receiptErrorCode, isReceiptError, receiptFieldErrors, remainingQuantities, type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, fromCashregisterPayload, type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, isZeroKind, type ReportMonth, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, type StripeUrlSession, type StripeUrlSessionPayload, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, type HobexReceipt, type HobexReceiptPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
+export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type KasseneckTransport, type KasseneckBinaryTransport, ALL_CALLS, type ApiCall, PUBLIC_CALLS, POS_CALLS, type PublicCall, type PosCall, createTransport, createBinaryTransport, 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, type ReceiptCommonOptions, type SellReceiptOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CancelReceiptResult, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, paymentsExpectedCents, cardRefundReference, receiptLayoutFromResult, cancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, listMyCashregisters, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, downloadDailyReport, downloadMonthlyReport, getReportV2, type ReportV2, type ReportV2Metadata, type ReportV2Options, type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, type KasseneckApi, createKasseneckApi, } from './client/index.js';
+export { type ReceiptDueTip, type ReceiptDueTipRecipient, type ReceiptDueOptions, type ReceiptDueBuckets, type ReceiptDueBreakdown, receiptDueCents, receiptDueBreakdown, } from './receipt/due.js';
 export { parseServerTimeStamp, toViennaWallClock, type ViennaWallClock } from './vienna-time.js';
-export { type KasseSettingsBetrieb, type KasseSettingsGeraet, type KasseSettings, type ArticleGroup, type KasseArtikel, KASSE_BETRIEB_STANDARD, KASSE_GERAET_STANDARD, mergeKasseSettings, fromArticleGroupPayload, fromKasseArtikelPayload, listMyArticleGroups, listMyArticles, getKasseSettings, setMyKasseSettings, setMyRegisterDeviceSettings, verteileRabatt, cancelScopeOf, receiptsScopeOf, } from './kasse/index.js';
+export { type PosBusinessSettings, type PosDeviceSettings, type PosSettings, type ArticleGroup, type PosArticle, POS_BUSINESS_DEFAULTS, POS_DEVICE_DEFAULTS, mergePosSettings, fromArticleGroupPayload, fromPosArticlePayload, listMyArticleGroups, listMyArticles, getPosSettings, setMyPosSettings, setMyRegisterDeviceSettings, distributeDiscount, cancelScopeOf, receiptsScopeOf, } from './pos/index.js';