@kreiseck/kasseneck-api 0.6.45 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,154 @@
+# Änderungen
+
+Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
+es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
+nur der Grund überlebt den nächsten Umbau.
+
+## 0.7.0
+
+### Neu: Unterpfad `./partner` — die Partner-API
+
+Alles, was ein Partner-Softwarehaus über die Kasseneck-Schnittstelle tut, in
+einem eigenen Unterpfad. Er liegt bewusst **nicht** in der Wurzel: der
+Partner-Schlüssel gehört auf einen Server (er kann Betriebe anlegen und deren
+Geheimnisse holen), und die Kassen-Seite des Pakets soll ihn nicht in ein
+Browser-Bündel ziehen.
+
+Neue öffentliche Symbole:
+
+- **Anmeldung und Fassade** — `partnerKeyAuth`, `partnerKeyEnv`,
+  `createPartnerApi`, `PartnerApi`, `PartnerApiOptions`, `PartnerKeyAuthOptions`.
+- **Betriebe** — `createPartnerCustomer`, `listPartnerCustomers`,
+  `getPartnerCustomer`, `sendPartnerCustomerFonLink`, `getPartnerInfo`.
+- **Signatur und Kassen** — `requestCustomerSignature`,
+  `getCustomerSignatureStatus`, `createCustomerCashregister`,
+  `activateCashregister`, `listCustomerCashregisters`, `getCustomerCredentials`.
+- **Webhooks** — `createPartnerWebhook`, `listPartnerWebhooks`,
+  `updatePartnerWebhook`, `deletePartnerWebhook`, `sendPartnerWebhookTest`,
+  `listPartnerWebhookDeliveries`, `parseWebhookEvent`,
+  `verifyWebhookSignature`, `parseSignatureHeader`, `PARTNER_WEBHOOK_EVENTS`,
+  `istPartnerWebhookEvent`, `WEBHOOK_UMSCHLAG_FELDER` und die Konstanten
+  `WEBHOOK_SIGNATURE_HEADER`,
+  `WEBHOOK_EVENT_HEADER`, `WEBHOOK_DELIVERY_HEADER`, `WEBHOOK_TOLERANCE_SEC`,
+  `WEBHOOK_RETRY_PLAN_SEC`, `WEBHOOK_MAX_ATTEMPTS`, `WEBHOOK_TIMEOUT_MS`,
+  `WEBHOOK_LIMIT`.
+- **Ablauf und Fehler** — `PARTNER_ABLAUF`, `naechsterSchritt`,
+  `PARTNER_FEHLER_CODES`, `PARTNER_PORTAL_FEHLER_CODES`,
+  `istPartnerFehlerCode`, `istPartnerPortalFehlerCode`, `istPartnerFehler`,
+  `partnerFehlerCode`, `partnerFehlerRat`, `partnerFeldFehler`,
+  `partnerWartezeitSek`, `SCOPE_CREDENTIALS`.
+- **Betriebsdaten** — `BETRIEB_FELDER`, `unbekannteBetriebsfelder`,
+  `PARTNER_ENVS`.
+- **Geheimnisse** — `KasseneckSecret`, `SECRET_MASKE`.
+- Dazu die Typen der Nutzlasten (`Betrieb`, `Kunde`, `Kasse`, `SignaturAntrag`,
+  `CustomerCredentials`, …).
+
+Warum die einzelnen Entscheidungen so gefallen sind:
+
+- **`KasseneckSecret` statt `string` für die Zugangsdaten eines Betriebs.**
+  `getCustomerCredentials` liefert den `api_key` des Betriebs und die Token
+  seiner Kassen; wer sie hat, kann in seinem Namen Belege signieren, und ein
+  Beleg ist nach RKSV nicht zurücknehmbar. Ein `string` in einem Antwortobjekt
+  landet aber in `console.log`, in `JSON.stringify` und im Rumpf eines
+  Fehlerberichts. Der Klartext liegt deshalb in einer `WeakMap` neben der
+  Instanz — am Objekt hängt kein Feld, das ihn trägt — und `toString`,
+  `toJSON`, `Symbol.toPrimitive` sowie der Node-Inspektor zeigen eine Maske.
+  Heraus kommt man nur über `.reveal()`; genau diese Stellen findet eine Suche.
+- **Die Signaturprüfung liegt fertig im Paket, nicht als Beispiel in der Doku.**
+  Sie ist der Teil, den Integratoren am häufigsten falsch bauen, und ein Fehler
+  fällt dort nie auf: eine zu lasche Prüfung lässt jeden durch und meldet nichts.
+  Umgesetzt mit WebCrypto statt `node:crypto`, damit das Paket weiterhin ohne
+  Laufzeitabhängigkeit auskommt — deshalb ist sie asynchron.
+- **`env` bei `createPartnerCustomer`.** Ohne Angabe entscheidet der Schlüssel.
+  Ein **Live**-Schlüssel darf `env:"test"` verlangen — das ist der vorgesehene
+  Weg, die ganze Kette zu proben, ohne sich einen zweiten Schlüssel zu holen.
+  Umgekehrt nie: ein Test-Schlüssel mit `env:"live"` bekommt `live_not_allowed`,
+  und es entsteht nichts. Der Client prüft das **nicht** selbst vor: der Server
+  ist die eine Wahrheit, und ein zweiter Torwächter im Paket wäre der, der
+  irgendwann veraltet.
+- **Verträge wirken im Partner-Weg nicht mehr** (Backend-Stand 2026-08-31).
+  Keine Antwort führt `avv`, `naechsteSchritte` kennt keinen AVV-Schritt, und
+  bei der Inbetriebnahme gibt es kein `vertrag_offen` mehr. Weggefallen sind
+  deshalb `reportCustomerVertrag`, `vertragOffenRat`, `vertragOffenRatFuer`,
+  `AVV_MODI`, `AVV_STATUS`, `avvErfuellt`, `avvSperrt`, `avvStatusText`,
+  `istAvvModus`, die Option `avvModus` und der Ablaufschritt `avv`. Der Typ
+  `AvvStand` **bleibt** und wird weiterhin gelesen, wenn eine Antwort ihn doch
+  führt — vorausgesetzt wird er nirgends. `customer.avv_accepted` steht nicht
+  mehr in `PARTNER_WEBHOOK_EVENTS`: es ist ein internes Ereignis, das ein
+  Partner weder abonnieren noch proben kann, und ein Name in dieser Liste, den
+  niemand bestellen kann, ist ein Versprechen ohne Deckung.
+- **Der Fehlerkatalog ist vollständig** — 28 Codes der Schnittstelle
+  (`PARTNER_FEHLER_CODES`) und 12 des Partner-Portals
+  (`PARTNER_PORTAL_FEHLER_CODES`), jeder mit Handlungssatz. Quelle ist
+  `docs/api/fehlercodes.json` im Backend. Ein Code, den nur eine Seite kennt,
+  ist für einen Aufrufer nicht von „gibt es nicht" zu unterscheiden; eine halbe
+  Liste ist deshalb schlimmer als keine.
+- **`test: true` im Webhook-Umschlag.** `sendPartnerWebhookTest` nimmt jetzt ein
+  `event` und löst damit **jedes abonnierte Ereignis** mit glaubwürdiger
+  Nutzlast aus — eine Leitungsprobe beweist nichts über die Behandlung des
+  Ernstfalls. Damit eine Probe nicht für echt gehalten wird, trägt sie
+  `test: true` im Umschlag; `PartnerWebhookEvent.test` führt das Feld und ist
+  bei echten Ereignissen `false`. Die Zeile `if (ereignis.test) return;` gehört
+  an den Anfang jedes Handlers — ohne sie schreibt jemand seinem Kunden, die
+  Kasse sei fertig.
+- **Betriebsdaten werden streng geprüft.** Das Backend weist ein unbekanntes
+  Feld ab, statt es stillschweigend zu verwerfen, und nennt den vollen Pfad
+  (`address.land`, `contacts.0.rolle`). Der Typ `Betrieb` führt deshalb genau
+  die Liste aus `partner-core.BETRIEB_FELDER`, und `unbekannteBetriebsfelder`
+  beantwortet dieselbe Frage zur Laufzeit — für Daten aus Datenbank oder
+  Formular, die nie durch die Typprüfung gelaufen sind. Abgewiesen wird hier
+  nichts: die Wahrheit bleibt der Server, sonst blockierte ein alter Client ein
+  neues Feld.
+- **`createCustomerCashregister` ohne `name`, mit `signaturId`.** Kassennamen
+  vergibt Kasseneck (sie sind gleich der `cashregisterId`); ein gesendetes
+  `name` wäre ein `validation`-Fehler. Dafür bezieht sich **jede** Kasse auf
+  eine Signatur: ohne eine einzige `signature_missing`, bei mehreren
+  `signature_ambiguous` ohne `signaturId`. `requestCustomerSignature` nimmt
+  `weitere`, um eine zusätzliche Signatur zu beantragen (höchstens zehn,
+  `signature_limit`).
+- **`getPartnerInfo().partner.darfZugangEinrichten`** und `zugang.einladen` mit
+  Vorgabe **false**: ein Zugang zum Kundenpanel legt einen Login auf eine fremde
+  Adresse an und schickt eine Mail dorthin. Fehlt das Feld, gilt NEIN — eine
+  Berechtigung, die nicht ausdrücklich dasteht, hat man nicht.
+
+### Geändert: `KasseneckApiError` trägt `code` und `details`
+
+Bisher blieb vom `data` einer Fehlerantwort nichts übrig. Die Partner-API legt
+ihre Entscheidung aber nicht in den Text, sondern in `data.code`
+(`live_not_allowed`, `signature_not_ready`, `activation_failed` samt
+`data.schritt`); ohne diese Felder müsste ein Aufrufer die deutsche `message`
+nach Zeichenketten durchsuchen — die Art Kopplung, die beim nächsten
+Formulierungsschliff still bricht.
+
+Die Nutzlast wird dabei **gesiebt** (`fehlerDetails`) und nicht durchgereicht:
+höchstens vier Ebenen tief, 50 Einträge je Ebene, Zeichenketten bis 300 Zeichen,
+nur bezeichner-förmige Schlüssel — und kein Wert, der mit einem der gesendeten
+Geheimnisse überlappt. Damit gilt dieselbe Zusage wie für `causeDigest`.
+
+Additiv: der dritte Konstruktorparameter hat einen Vorgabewert, bestehende
+Aufrufer und `catch`-Zweige bleiben unverändert.
+
+### Vertrag
+
+`AUFRUFE` und damit `fixtures/oberflaeche.json` führen 18 Aufrufe mehr (die
+Partner-Endpunkte). Der Flutter-Zwilling `kasseneck_api` und die
+Hosting-Weiterleitungen in `kasseneck-web` lesen diese Liste — beide müssen
+nachziehen, sonst laufen die Aufrufe in Produktion auf die HTML-Seite statt auf
+die Function.
+
+**Neuer Abschnitt `partner` in der Vertragsdatei.** Der Partner-Teil wäre sonst
+als reine Namensliste über den Vertrag gegangen: die Aufrufe hätte er geführt,
+die Fehlercodes, die Webhook-Ereignisse, die Betriebsfelder, die Umgebungen,
+die Felder des Webhook-Umschlags und den Wiederholungsplan nicht — und genau
+die pflegt der Zwilling von Hand nach. Ein Fehlercode, den nur eine Seite kennt,
+hätte auf der anderen keinen Handlungssatz und wäre für einen Aufrufer nicht von
+„gibt es nicht" zu unterscheiden. `scripts/oberflaeche.mjs` liest den
+Partner-Namensraum genauso ab wie den Kassen-Namensraum; eine neu angelegte
+Liste landet damit von selbst im Vertrag statt still zu fehlen.
+
+**Und die Gegenrichtung: `test/fixtures/dart-partner.json`.** Der Vertrag in
+`fixtures/` wird drüben geprüft — dieses Repo sähe eine Lücke erst im nächsten
+Zwillingslauf im anderen Repo, an einem anderen Tag. Der eingecheckte Abzug der
+Dart-Seite (dasselbe Muster wie `dart-enums.json`, samt `_quelle`) macht
+`npm test` hier rot, sobald ein Fehlercode, ein Ereignis, ein Betriebsfeld, eine
+Umgebung oder die Marke `test` nur in einer der beiden Sprachen ankommt.

package/README.md

@@ -8,7 +8,8 @@ im Test gegengeprüft, damit die beiden Pakete nicht auseinanderdriften.
 Das Paket deckt ab: Belege ausstellen und stornieren, Belege und Kassen
 auflisten, Berichte herunterladen, Status bei FinanzOnline abfragen,
 Stripe-Zahllinks und Hobex-Cloud-Zahlungen, das Beleg-Layout und die
-ESC/POS-Erzeugung für den Bondrucker.
+ESC/POS-Erzeugung für den Bondrucker — und unter `./partner` die
+**Partner-API**: Betriebe anlegen und bis zur laufenden Kasse begleiten.
 
 **Es läuft im Browser und in Node.** ESM ist das Hauptformat, CommonJS liegt
 daneben; beides mit eigenen Typdeklarationen. Node ab 20.18 (`fetch` muss
@@ -167,6 +168,123 @@ sich nicht stornieren, ein voll stornierter Beleg nicht noch einmal. Am
 gelesenen Original liefert `remainingQuantities(receipt)` die Reste vorab (für
 den Storno-Dialog); die Wahrheit hat der Server.
 
+## Partner-API (`./partner`)
+
+Für Softwarehäuser, die Kasseneck in ihr eigenes Produkt einbauen: Betriebe
+anlegen, bis zur laufenden Kasse begleiten und danach in ihrem Namen Belege
+signieren.
+
+**Was die Endpunkte tun, steht in der Referenz** —
+`docs/api/partner.md` (ausführlich) und `docs/api/partner.llms.txt` (kompakt,
+für Werkzeuge und Sprachmodelle). Dieses README wiederholt sie nicht; hier
+steht, wie man den Client benutzt.
+
+Der Partner-Schlüssel (`pk_live_…`) gehört auf einen **Server**. Er kann
+Betriebe anlegen und — mit dem Zusatz-Scope `credentials:read` — deren
+Geheimnisse holen.
+
+```ts
+import { createPartnerApi, istPartnerFehler } from '@kreiseck/kasseneck-api/partner';
+
+const partner = createPartnerApi({ partnerKey: process.env.KASSENECK_PARTNER_KEY! });
+
+const { customerId } = await partner.createPartnerCustomer({
+  appId: 'app_…',
+  idempotencyKey: kundennummer,   // die eigene — schützt vor Doppelanlage
+  betrieb: { /* Stammdaten, siehe Referenz */ } as never,
+  // env: 'test' — auch mit einem LIVE-Schlüssel erlaubt: so probt man die
+  // ganze Kette, ohne sich einen zweiten Schlüssel zu holen. Umgekehrt nie.
+});
+
+await partner.sendPartnerCustomerFonLink(customerId);
+// … auf das Ereignis customer.fon_verified warten …
+await partner.requestCustomerSignature(customerId);
+// … auf signature.ready warten …
+await partner.createCustomerCashregister({ customerId });  // automatisch:true ist Vorgabe
+```
+
+Die Reihenfolge ist hart, und jeder Schritt beschwert sich mit einem eigenen
+Code, wenn ein vorheriger fehlt. Sie steht als Daten im Paket
+(`PARTNER_ABLAUF`), und zu jedem Code gibt es einen Handlungssatz:
+
+```ts
+try {
+  await partner.activateCashregister(customerId, cashregisterId);
+} catch (fehler) {
+  if (istPartnerFehler(fehler, 'signature_not_ready')) {
+    // Die Signatur DIESER Kasse ist noch nicht bereit — auf signature.ready warten.
+    console.error(partner.fehlerRat('signature_not_ready'));
+  }
+}
+```
+
+### Eine Probe ist keine Kasse
+
+`sendPartnerWebhookTest(webhookId, 'cashregister.live')` löst genau das
+Ereignis aus, das der eigene Handler behandeln soll — eine Leitungsprobe
+beweist nichts über die Behandlung des Ernstfalls. Damit niemand eine Probe
+für echt hält, trägt sie `test: true` im Umschlag:
+
+```ts
+const geprueft = await parseWebhookEvent({ secret, signatureHeader, body, });
+if (!geprueft.ok) return antwort(400);
+
+if (geprueft.event.test) return antwort(200);   // Probe: nichts weiter tun
+```
+
+Ohne diese Zeile schreibt jemand seinem Kunden, die Kasse sei fertig.
+
+### Zugangsdaten sind Geheimnisse eines Dritten
+
+`getCustomerCredentials` liefert den `api_key` des Betriebs und die Token
+seiner Kassen. Wer sie hat, kann in seinem Namen Belege signieren — und ein
+Beleg ist nach RKSV nicht zurücknehmbar. Sie kommen deshalb **nicht als
+`string`**, sondern in einer Hülle, die sich nicht versehentlich ausgeben
+lässt:
+
+```ts
+const zugang = await partner.getCustomerCredentials(customerId);
+
+console.log(zugang);                     // [apiKey «verborgen»] — kein Klartext
+JSON.stringify(zugang);                  // ebenso
+`${zugang.apiKey}`;                      // ebenso
+
+speichereVerschluesselt(zugang.apiKey.reveal());   // der einzige Weg heraus
+```
+
+Nur verschlüsselt speichern, nie protokollieren, nie in eine Mail oder einen
+Fehlerbericht. Jeder Abruf wird mitgeschrieben und ist für den Betrieb
+sichtbar.
+
+### Eingehende Webhooks prüfen
+
+Das ist die Stelle, an der Integrationen am häufigsten scheitern — deshalb
+liegt sie fertig im Paket. Vier Dinge müssen stimmen: der **rohe** Rumpf, das
+Zeitfenster gegen Wiedereinspielung, ein zeitkonstanter Vergleich, und jede
+Ausnahme als Ablehnung.
+
+```ts
+import express from 'express';
+import { parseWebhookEvent } from '@kreiseck/kasseneck-api/partner';
+
+const app = express();
+
+// express.raw VOR jedem JSON-Parser: signiert sind die Bytes, die ankommen.
+app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) => {
+  const ergebnis = await parseWebhookEvent({
+    secret: process.env.KASSENECK_WEBHOOK_SECRET!,
+    signatureHeader: req.header('X-Kasseneck-Signature'),
+    body: req.body,           // Buffer — nicht req.body nach JSON.parse
+  });
+  if (!ergebnis.ok) return res.status(400).send(ergebnis.reason);
+
+  // Innerhalb von 10 s antworten, Arbeit danach. Zustellungen können sich
+  // wiederholen: auf event.id entdoppeln.
+  res.sendStatus(200);
+  await verarbeite(ergebnis.event);
+});
+```
+
 ## Unterpfade
 
 | Unterpfad | Inhalt |
@@ -177,6 +295,7 @@ den Storno-Dialog); die Wahrheit hat der Server.
 | `…/payments` | Stripe-Zahllinks und Hobex-Cloud (beides HTTP-Endpunkte des Backends). |
 | `…/register` | Anmeldung der Browser-Kasse: Gerät koppeln und entkoppeln, Benutzer auflisten, per PIN anmelden, Sitzung erneuern und beenden. |
 | `…/kasse` | Kachel-Kasse: Kassen-Einstellungen (betriebsweit / je Gerät), Artikelgruppen und Artikel für Kacheln, Rabattverteilung je Steuersatz, Reichweiten der Kassen-Rechte |
+| `…/partner` | Partner-API: Betriebe anlegen, FinanzOnline-Link, Signatur, Kassen, Zugangsdaten, Webhooks samt Signaturprüfung. **Gehört auf einen Server.** |
 | `…/react` | Dünner React-Adapter, der ein Beleg-Layout zeichnet. Braucht React. |
 | `…/fixtures/*` | Golden-Belege (JSON): Eingaben `belege/<name>.json`, zugesagte Zeilenausgabe `erwartet/<name>.lines.json`, `manifest.json` mit Prüfsummen — dieselben Dateien prüfen Backend, Browser-Kasse und Flutter-Paket. |
 
@@ -199,12 +318,33 @@ PDF-Erzeugung.
 npm test              # Testsuite in drei Zeitzonen (Wien, UTC, Kiritimati)
 npm run build         # ESM- und CJS-Bau nach dist/, inkl. Prüfung der exports
 npm run check:consumer # baut den Tarball und übersetzt zwei Verbraucher (CJS/ESM)
+npm run check:erreichbar # fragt die öffentliche Adresse: antwortet dort zu jedem Aufruf eine Function?
 ```
 
 Die drei Zeitzonen sind kein Übereifer: Zeitfehler sind auf einer Wiener
 Maschine zufällig richtig. Belegzeiten werden konsequent als **Wiener
 Wanduhrzeit** gedeutet (`parseServerTimeStamp`), nie über `new Date(text)`.
 
+### `check:erreichbar` — spricht als einzige mit `api.kasseneck.at`
+
+Testsuite und `check:consumer` laufen gegen Attrappen bzw. gegen den Tarball;
+keine von beiden setzt je einen Aufruf ab. Fehlt einem Aufruf die
+Hosting-Weiterleitung, liefert die veröffentlichte Adresse die
+HTML-Auffangseite statt der Function — und das sieht keine Attrappe.
+
+Die Prüfung braucht **keine Zugangsdaten**. Ein Aufruf ohne Anmeldung
+antwortet, wenn dort eine Function steht, mit
+`{"status":"error","message":"Ungültiger Request: Authorization key erwartet."}`.
+Genau das ist der Beweis: Der Aufruf wurde angenommen und die Anmeldung
+geprüft. Eine HTML-Seite oder ein 404 ist der Beweis, dass dort keine Function
+steht. Deshalb prüft das Skript auf ein `status`-Feld und nicht auf Erfolg.
+
+Bewusst außerhalb von `npm test`: Sie braucht Netz. Ist keines da, sagt sie es
+und endet mit 0. Aufrufe, die unter `/v1` absichtlich keine Weiterleitung
+haben — der Kassen-Weg über `kasse.kasseneck.at/api`, die Aufrufe mit
+Firebase-ID-Token — stehen mit Grund in `scripts/erreichbarkeit-ausnahmen.json`.
+Wird eine Ausnahme erreichbar, schlägt die Prüfung an: Sonst sänke die Zahl nie.
+
 ## Vertragsdateien für die Zwillinge
 
 Dieses Paket ist die Quelle für das Dart-Paket `kasseneck_api` und den
@@ -214,7 +354,7 @@ im Tarball mit und sagen in Maschinenform, worauf sich alle drei geeinigt haben:
 | Datei | Inhalt |
 |---|---|
 | `kasse-settings-standard.json` | Feldnamen und Standardwerte der Kassen-Einstellungen |
-| `oberflaeche.json` | Aufrufnamen, Enum-Werte, Rechte-Schlüssel, Tasten-Aktionen |
+| `oberflaeche.json` | Aufrufnamen, Enum-Werte, Rechte-Schlüssel, Tasten-Aktionen, Partner-Listen |
 
 Beide werden erzeugt (`npm run fixtures:kasse`, `npm run fixtures:oberflaeche`)
 und nie von Hand geändert; die CI prüft nach jedem Lauf, dass sie zum Code passen.
@@ -222,6 +362,22 @@ und nie von Hand geändert; die CI prüft nach jedem Lauf, dass sie zum Code pas
 `oberflaeche.json` trägt die Paketversion. **Nach jedem `npm version` müssen deshalb beide
 Dateien neu erzeugt und mitcommittet werden**, sonst wird die CI rot.
 
+### Und die Gegenrichtung
+
+Der Vertrag in `fixtures/` wird **drüben** geprüft: das Dart-Repo zieht ihn und
+hält seine Listen dagegen. Eine Lücke fiele hier deshalb erst im nächsten
+Zwillingslauf im anderen Repo auf — an einem anderen Tag. Dagegen stehen zwei
+von Hand gepflegte Abzüge der Dart-Seite unter `test/fixtures/`, jeder mit
+`_quelle`:
+
+| Datei | prüft |
+|---|---|
+| `dart-enums.json` | Belegtyp, Steuersatz, Zahlungsart, Kartenanbieter, Gutschein, Stripe-Modus |
+| `dart-partner.json` | Umgebungen, Fehlercodes (API und Portal), Webhook-Ereignisse, Felder des Webhook-Umschlags samt der Marke `test`, Betriebsfelder, Wiederholungsplan |
+
+Sie machen `npm test` rot, sobald ein Wert nur in einer der beiden Sprachen
+ankommt.
+
 ## Lizenz
 
 Apache-2.0 — siehe `LICENSE` und `NOTICE`.

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

@@ -13,7 +13,7 @@
  * umhuellt, muss ihn weiterhin absetzen koennen.
  */
 import type { TransportBodyFields } from './transport.js';
-export declare const AUFRUFE: readonly ["cancelReceipt", "createPaymentLinkStripe", "createPrintJob", "createReceipt", "downloadDailyReport", "downloadReport", "endRegisterSession", "financeWebService", "generateFullReceiptId", "getFirstReceiptDate", "getKasseSettings", "getPrintJob", "getReceipt", "hobexPayApi", "hobexRefundApi", "listMyArticleGroups", "listMyArticles", "listMyCashregisters", "listMyPrinters", "listMyReceipts", "listRegisterUsersForDevice", "pairRegisterDevice", "registerPinLogin", "registerUserLogin", "renewRegisterSession", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "unpairRegisterDevice"];
+export declare const AUFRUFE: readonly ["activateCashregister", "cancelReceipt", "createCustomerCashregister", "createPartnerCustomer", "checkPartnerCustomerEmail", "createPartnerWebhook", "createPaymentLinkStripe", "createPrintJob", "createReceipt", "deletePartnerWebhook", "downloadDailyReport", "downloadReport", "endRegisterSession", "financeWebService", "generateFullReceiptId", "getCustomerCredentials", "getCustomerSignatureStatus", "getFirstReceiptDate", "getKasseSettings", "getPartnerCustomer", "getPartnerInfo", "getPrintJob", "getReceipt", "hobexPayApi", "hobexRefundApi", "listCustomerCashregisters", "listMyArticleGroups", "listMyArticles", "listMyCashregisters", "listMyPrinters", "listMyReceipts", "listMyTipRecipients", "listPartnerCustomers", "listPartnerWebhookDeliveries", "listPartnerWebhooks", "listRegisterUsersForDevice", "pairRegisterDevice", "registerPinLogin", "registerUserLogin", "renewRegisterSession", "requestCustomerSignature", "sendPartnerCustomerFonLink", "sendPartnerWebhookTest", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "unpairRegisterDevice", "rotatePartnerWebhookSecret", "updatePartnerWebhook"];
 export type Aufruf = typeof AUFRUFE[number];
 /** 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>;

package/dist/cjs/client/aufrufe.js

@@ -2,33 +2,53 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AUFRUFE = void 0;
 exports.AUFRUFE = [
+    'activateCashregister',
     'cancelReceipt',
+    'createCustomerCashregister',
+    'createPartnerCustomer',
+    'checkPartnerCustomerEmail',
+    'createPartnerWebhook',
     'createPaymentLinkStripe',
     'createPrintJob',
     'createReceipt',
+    'deletePartnerWebhook',
     'downloadDailyReport',
     'downloadReport',
     'endRegisterSession',
     'financeWebService',
     'generateFullReceiptId',
+    'getCustomerCredentials',
+    'getCustomerSignatureStatus',
     'getFirstReceiptDate',
     'getKasseSettings',
+    'getPartnerCustomer',
+    'getPartnerInfo',
     'getPrintJob',
     'getReceipt',
     'hobexPayApi',
     'hobexRefundApi',
+    'listCustomerCashregisters',
     'listMyArticleGroups',
     'listMyArticles',
     'listMyCashregisters',
     'listMyPrinters',
     'listMyReceipts',
+    'listMyTipRecipients',
+    'listPartnerCustomers',
+    'listPartnerWebhookDeliveries',
+    'listPartnerWebhooks',
     'listRegisterUsersForDevice',
     'pairRegisterDevice',
     'registerPinLogin',
     'registerUserLogin',
     'renewRegisterSession',
+    'requestCustomerSignature',
+    'sendPartnerCustomerFonLink',
+    'sendPartnerWebhookTest',
     'setMyKasseSettings',
     'setMyRegisterDeviceSettings',
     'stripeCaptureIntent',
     'unpairRegisterDevice',
+    'rotatePartnerWebhookSecret',
+    'updatePartnerWebhook',
 ];

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

@@ -69,6 +69,24 @@ export interface CauseDigest {
  * gesendeten Werte nicht bekannt sind, wird gar nicht verdichtet.
  */
 export declare function causeDigest(ursache: unknown, geheimnisse: readonly string[]): CauseDigest;
+/**
+ * Siebt das `data` einer Fehlerantwort zu einer Form, die man gefahrlos an
+ * einem Fehler mitfuehren kann.
+ *
+ * **Warum ueberhaupt:** die Partner-API legt ihre Entscheidung nicht in den
+ * Text, sondern in `data.code` (`vertrag_offen`, `signature_not_ready`,
+ * `activation_failed` samt `data.schritt`). Ohne diese Felder muesste ein
+ * Aufrufer die deutsche `message` nach Zeichenketten durchsuchen — genau die
+ * Kopplung, die beim naechsten Formulierungsschliff still bricht.
+ *
+ * **Warum gesiebt und nicht durchgereicht:** siehe Modulkommentar. Der Rumpf
+ * kommt ueber fremde Proxys, und ein Fehler landet in Protokollen. Deshalb
+ * ueberlebt nur, was flach, klein und bezeichner-foermig benannt ist — und
+ * kein Wert, der mit einem der gesendeten Geheimnisse ueberlappt. Damit gilt
+ * hier dieselbe Zusage wie fuer [causeDigest], und `geheimnisse` hat aus
+ * demselben Grund **keinen** Vorgabewert.
+ */
+export declare function fehlerDetails(daten: unknown, geheimnisse: readonly string[]): Record<string, unknown>;
 /** Fachlicher Fehler: HTTP 200, aber `status: 'error'` im Rumpf. */
 export declare class KasseneckApiError extends Error {
     readonly name = "KasseneckApiError";
@@ -76,7 +94,19 @@ export declare class KasseneckApiError extends Error {
     readonly functionName: string;
     /** Meldung des Backends, unveraendert (`message` aus der Huelle). */
     readonly serverMessage: string;
-    constructor(functionName: string, serverMessage: string);
+    /**
+     * Maschinenlesbarer Fehlercode aus `data.code`, sofern die Antwort einen
+     * fuehrt (`vertrag_offen`, `rate_limited`, …). Die aelteren Endpunkte des
+     * Backends antworten ohne Code — dann `undefined`.
+     */
+    readonly code: string | undefined;
+    /**
+     * Die uebrige Fehler-Nutzlast, gesiebt (siehe [fehlerDetails]): `schritt`,
+     * `rc`, `retryAfterSec`, `errors[]` und was der jeweilige Endpunkt sonst
+     * beilegt. Immer ein Objekt, notfalls ein leeres.
+     */
+    readonly details: Record<string, unknown>;
+    constructor(functionName: string, serverMessage: string, details?: Record<string, unknown>);
 }
 /** Warum die Antwort keine verwertbare Huelle war. */
 export type HttpFailureReason = 'server-error' | 'empty-body' | 'not-json' | 'missing-status';

package/dist/cjs/client/errors.js

@@ -58,6 +58,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KasseneckValidationError = exports.KasseneckAuthError = exports.KasseneckNetworkError = exports.KasseneckHttpError = exports.KasseneckApiError = void 0;
 exports.causeDigest = causeDigest;
+exports.fehlerDetails = fehlerDetails;
 exports.isKasseneckApiError = isKasseneckApiError;
 exports.isKasseneckHttpError = isKasseneckHttpError;
 exports.isKasseneckNetworkError = isKasseneckNetworkError;
@@ -94,6 +95,84 @@ function unbedenklich(wert, geheimnisse) {
     }
     return wert;
 }
+/**
+ * Grenzen fuer die gesiebte Fehler-Nutzlast (siehe [fehlerDetails]). Sie stehen
+ * als benannte Konstanten hier, weil ein Test sie namentlich prueft — eine
+ * spaeter heraufgesetzte Grenze soll auffallen und nicht als Zahl im Code
+ * untergehen.
+ */
+const DETAIL_TIEFE = 4;
+const DETAIL_EINTRAEGE = 50;
+const DETAIL_TEXT_MAX = 300;
+/** Schluessel eines Detail-Objekts: bezeichner-foermig, sonst faellt der Eintrag weg. */
+const DETAIL_SCHLUESSEL = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+/**
+ * Siebt das `data` einer Fehlerantwort zu einer Form, die man gefahrlos an
+ * einem Fehler mitfuehren kann.
+ *
+ * **Warum ueberhaupt:** die Partner-API legt ihre Entscheidung nicht in den
+ * Text, sondern in `data.code` (`vertrag_offen`, `signature_not_ready`,
+ * `activation_failed` samt `data.schritt`). Ohne diese Felder muesste ein
+ * Aufrufer die deutsche `message` nach Zeichenketten durchsuchen — genau die
+ * Kopplung, die beim naechsten Formulierungsschliff still bricht.
+ *
+ * **Warum gesiebt und nicht durchgereicht:** siehe Modulkommentar. Der Rumpf
+ * kommt ueber fremde Proxys, und ein Fehler landet in Protokollen. Deshalb
+ * ueberlebt nur, was flach, klein und bezeichner-foermig benannt ist — und
+ * kein Wert, der mit einem der gesendeten Geheimnisse ueberlappt. Damit gilt
+ * hier dieselbe Zusage wie fuer [causeDigest], und `geheimnisse` hat aus
+ * demselben Grund **keinen** Vorgabewert.
+ */
+function fehlerDetails(daten, geheimnisse) {
+    const gesiebt = sieben(daten, geheimnisse, 0);
+    return gesiebt !== null && typeof gesiebt === 'object' && !Array.isArray(gesiebt)
+        ? gesiebt
+        : {};
+}
+function sieben(wert, geheimnisse, tiefe) {
+    if (wert === null || typeof wert === 'boolean')
+        return wert;
+    // Nur endliche Zahlen: NaN und Infinity ueberstehen JSON.stringify nicht und
+    // staenden in einem Fehlerbericht als `null` ohne jede Aussage.
+    if (typeof wert === 'number')
+        return Number.isFinite(wert) ? wert : undefined;
+    if (typeof wert === 'string') {
+        if (wert.length > DETAIL_TEXT_MAX)
+            return undefined;
+        for (const geheim of geheimnisse) {
+            if (geheim && (geheim.includes(wert) || wert.includes(geheim)))
+                return undefined;
+        }
+        return wert;
+    }
+    if (tiefe >= DETAIL_TIEFE)
+        return undefined;
+    if (Array.isArray(wert)) {
+        const liste = [];
+        for (const eintrag of wert.slice(0, DETAIL_EINTRAEGE)) {
+            const s = sieben(eintrag, geheimnisse, tiefe + 1);
+            if (s !== undefined)
+                liste.push(s);
+        }
+        return liste;
+    }
+    if (typeof wert !== 'object')
+        return undefined;
+    const raus = {};
+    let gezaehlt = 0;
+    for (const [schluessel, eintrag] of Object.entries(wert)) {
+        if (gezaehlt >= DETAIL_EINTRAEGE)
+            break;
+        if (!DETAIL_SCHLUESSEL.test(schluessel))
+            continue;
+        const s = sieben(eintrag, geheimnisse, tiefe + 1);
+        if (s === undefined)
+            continue;
+        raus[schluessel] = s;
+        gezaehlt += 1;
+    }
+    return raus;
+}
 /** Fachlicher Fehler: HTTP 200, aber `status: 'error'` im Rumpf. */
 class KasseneckApiError extends Error {
     name = 'KasseneckApiError';
@@ -101,10 +180,28 @@ class KasseneckApiError extends Error {
     functionName;
     /** Meldung des Backends, unveraendert (`message` aus der Huelle). */
     serverMessage;
-    constructor(functionName, serverMessage) {
+    /**
+     * Maschinenlesbarer Fehlercode aus `data.code`, sofern die Antwort einen
+     * fuehrt (`vertrag_offen`, `rate_limited`, …). Die aelteren Endpunkte des
+     * Backends antworten ohne Code — dann `undefined`.
+     */
+    code;
+    /**
+     * Die uebrige Fehler-Nutzlast, gesiebt (siehe [fehlerDetails]): `schritt`,
+     * `rc`, `retryAfterSec`, `errors[]` und was der jeweilige Endpunkt sonst
+     * beilegt. Immer ein Objekt, notfalls ein leeres.
+     */
+    details;
+    constructor(functionName, serverMessage, details = {}) {
         super(`${functionName} fehlgeschlagen: ${serverMessage}`);
         this.functionName = functionName;
         this.serverMessage = serverMessage;
+        this.details = details;
+        // Der Code steht in `details` und zusaetzlich als eigenes Feld: das eine
+        // ist die Nutzlast, das andere die Frage, die ein Aufrufer wirklich
+        // stellt. Nur Bezeichner gelten — ein Freitext waere kein Code.
+        const code = details['code'];
+        this.code = typeof code === 'string' && BEZEICHNER.test(code) ? code : undefined;
     }
 }
 exports.KasseneckApiError = KasseneckApiError;

package/dist/cjs/client/transport.js

@@ -134,7 +134,7 @@ function createCore(options) {
             if (antwort.status !== 200) {
                 throw new errors_js_1.KasseneckHttpError(fehlerName, antwort.status, inhaltstyp, 'server-error');
             }
-            return auswerten(koerper, fehlerName, antwort.status, inhaltstyp);
+            return auswerten(koerper, fehlerName, antwort.status, inhaltstyp, geheimnisse);
         }
         finally {
             // Ohne Abraeumen haelt der Wecker den Node-Prozess bis zum Zeitlimit wach.
@@ -159,7 +159,7 @@ 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) {
+function jsonAuswerten(text, functionName, statusCode, inhaltstyp, geheimnisse) {
     if (!text.trim()) {
         throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'empty-body');
     }
@@ -181,7 +181,7 @@ function jsonAuswerten(text, functionName, statusCode, inhaltstyp) {
     }
     // Alles, was nicht ausdruecklich Erfolg ist, gilt als fachlicher Fehler —
     // ein unbekannter Statuswert darf nie stillschweigend als Erfolg durchgehen.
-    throw fachfehler(functionName, huelle.message);
+    throw fachfehler(functionName, huelle.message, huelle.data, geheimnisse);
 }
 /**
  * Auswertung des Binaerwegs. Der Kern der Zusage: **ein Aufrufer bekommt nie
@@ -196,7 +196,7 @@ function jsonAuswerten(text, functionName, statusCode, inhaltstyp) {
  * 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) {
+function pdfAuswerten(bytes, functionName, statusCode, inhaltstyp, geheimnisse) {
     if (bytes.length === 0) {
         throw new errors_js_1.KasseneckHttpError(functionName, statusCode, inhaltstyp, 'empty-body');
     }
@@ -227,7 +227,7 @@ function pdfAuswerten(bytes, functionName, statusCode, inhaltstyp) {
     }
     // Derselbe fachliche Fehler wie auf dem JSON-Weg — fuer den Aufrufer macht
     // es keinen Unterschied, ob er ein PDF oder eine Nutzlast erwartet hat.
-    throw fachfehler(functionName, huelle.message);
+    throw fachfehler(functionName, huelle.message, huelle.data, geheimnisse);
 }
 /** `%PDF` am Anfang — die Kennung jeder PDF-Datei. */
 function istPdf(bytes) {
@@ -240,9 +240,9 @@ function alsHuelle(wert) {
     }
     return wert;
 }
-function fachfehler(functionName, message) {
+function fachfehler(functionName, message, daten, geheimnisse) {
     const meldung = typeof message === 'string' && message.trim() ? message : 'Unbekannter Fehler';
-    return new errors_js_1.KasseneckApiError(functionName, meldung);
+    return new errors_js_1.KasseneckApiError(functionName, meldung, (0, errors_js_1.fehlerDetails)(daten, geheimnisse));
 }
 /**
  * Nutzlast aus Auth- und Aufruferparametern. Auth-Parameter bilden die

package/dist/cjs/kasse/index.d.ts

@@ -9,3 +9,4 @@ export { getKasseSettings, setMyKasseSettings, setMyRegisterDeviceSettings } fro
 export { verteileRabatt } from '../receipt/discount.js';
 export { cancelScopeOf, receiptsScopeOf, type RegisterScope, type RegisterUserPerms } from '../register/pairing.js';
 export { type NetzDrucker, type DruckJob, type DruckJobStatus, type CreatePrintJobOptions, listMyPrinters, createPrintJob, getPrintJob } from './drucker.js';
+export { listMyTipRecipients } from './trinkgeld.js';