@kreiseck/kasseneck-api 0.6.45 → 0.7.0

package/dist/cjs/partner/webhooks.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Webhooks: Endpunkte verwalten und eingehende Zustellungen auswerten.
+ *
+ * Die Signaturpruefung liegt daneben in `webhook-signatur.ts` — sie braucht
+ * weder Transport noch Schluessel und laeuft in jedem Empfaenger, auch in
+ * einem, der sonst nichts von diesem Paket benutzt.
+ */
+import type { InternerTransport } from '../client/aufrufe.js';
+import { type VerifyWebhookOptions, type WebhookVerifyReason } from './webhook-signatur.js';
+/**
+ * Alle Ereignisse, die ein Webhook abonnieren **und proben** kann. Ein
+ * Endpunkt bekommt ausschliesslich die, die in seiner `events`-Liste stehen.
+ *
+ * Kasseneck fuehrt daneben interne Ereignisse (etwa den Abschluss eines
+ * Auftragsverarbeitungsvertrags). Sie stehen hier bewusst nicht: sie lassen
+ * sich weder abonnieren noch mit [sendPartnerWebhookTest] ausloesen, und ein
+ * Name in dieser Liste, den niemand bestellen kann, waere ein Versprechen ohne
+ * Deckung.
+ */
+export declare const PARTNER_WEBHOOK_EVENTS: readonly ["customer.created", "customer.updated", "customer.status_changed", "customer.fon_verified", "customer.live_enabled", "signature.requested", "signature.ready", "signature.failed", "cashregister.created", "cashregister.live", "cashregister.failed", "app.version.accepted", "app.version.rejected", "webhook.test"];
+export type PartnerWebhookEventType = typeof PARTNER_WEBHOOK_EVENTS[number];
+export declare function istPartnerWebhookEvent(wert: unknown): wert is PartnerWebhookEventType;
+/**
+ * Die Felder des Umschlags, so wie er auf der Leitung liegt.
+ *
+ * Als Liste, damit der Zwilling sie nachhaelt: `test` kam spaeter dazu, und
+ * genau ein solches Feld verschwindet sonst auf einer Seite, ohne dass etwas
+ * rot wird.
+ */
+export declare const WEBHOOK_UMSCHLAG_FELDER: readonly ["id", "type", "createdAt", "partnerId", "test", "data"];
+/**
+ * Die Huelle jeder Zustellung. `type` bleibt bewusst offen fuer unbekannte
+ * Werte (`(string & {})`): ein spaeter ergaenztes Ereignis soll einen
+ * Empfaenger nicht zum Absturz bringen, sondern in seinem `default`-Zweig
+ * landen.
+ */
+export interface PartnerWebhookEvent<T = Record<string, unknown>> {
+    /** `evt_…` — die Kennung, auf die **entdoppelt** wird. */
+    id: string;
+    type: PartnerWebhookEventType | (string & {});
+    createdAt: number;
+    partnerId: string;
+    /**
+     * **Probe oder Ernstfall.** Eine mit [sendPartnerWebhookTest] ausgeloeste
+     * Zustellung traegt `test: true` im Umschlag; ein echtes Ereignis fuehrt das
+     * Feld gar nicht, hier steht dann `false`.
+     *
+     * Diese Zeile gehoert an den Anfang jedes Handlers:
+     *
+     * ```ts
+     * if (ereignis.test) return;
+     * ```
+     *
+     * Ohne sie haelt jemand eine Probe fuer echt und schreibt seinem Kunden, die
+     * Kasse sei fertig. Eine Probe traegt eine erkennbar erfundene Nutzlast — nur
+     * sieht man das erst, wenn man hinsieht.
+     */
+    test: boolean;
+    data: T;
+}
+export type WebhookEventResult = {
+    ok: true;
+    event: PartnerWebhookEvent;
+    timestampSec: number;
+} | {
+    ok: false;
+    reason: WebhookVerifyReason | 'body-not-json' | 'body-not-event';
+};
+/**
+ * Prueft die Signatur **und** liest das Ereignis — in dieser Reihenfolge. Wer
+ * zuerst parst und dann prueft, hat den fremden Rumpf schon durch seinen Code
+ * laufen lassen.
+ *
+ * **Entdoppeln nicht vergessen:** dieselbe Zustellung kann mehrfach ankommen
+ * (Wiederholung nach einer Antwort, die unterwegs verloren ging). Massgeblich
+ * ist `event.id`, nicht der Kopf `X-Kasseneck-Delivery` — der ist bei
+ * Wiederholungen derselbe, aber er beantwortet die Frage "habe ich dieses
+ * Ereignis schon verarbeitet?" nur fuer genau diesen Endpunkt.
+ *
+ * Antworte innerhalb von 10 Sekunden mit 2xx und erledige die Arbeit danach.
+ * Eine ausbleibende Antwort wird bis zu fuenfmal wiederholt (1 min, 5 min,
+ * 30 min, 2 h, 12 h) und gilt dann als fehlgeschlagen.
+ */
+export declare function parseWebhookEvent(optionen: VerifyWebhookOptions): Promise<WebhookEventResult>;
+export interface PartnerWebhook {
+    webhookId: string;
+    url: string;
+    events: string[];
+    active: boolean;
+    description: string | null;
+    createdAt: number | null;
+    lastDelivery: number | null;
+    /** Fehlversuche in Folge — steigt der Wert, stimmt beim Empfaenger etwas nicht. */
+    consecutiveFailures: number;
+}
+export interface CreateWebhookOptions {
+    /** Vollstaendige `https://`-Adresse. */
+    url: string;
+    /** Mindestens eines; unbekannte Namen lehnt das Backend ab. */
+    events: (PartnerWebhookEventType | (string & {}))[];
+    /** Hoechstens 120 Zeichen. */
+    description?: string;
+    active?: boolean;
+}
+export interface CreateWebhookResult {
+    webhook: PartnerWebhook;
+    /**
+     * Das Secret fuer die Signaturpruefung. **Es kommt genau einmal** — beim
+     * Anlegen. Danach gibt das Backend es nie wieder aus; wer es verliert, legt
+     * einen neuen Endpunkt an.
+     *
+     * Bewusst ein `string` und kein [KasseneckSecret]: es gehoert dem Partner
+     * selbst und nicht einem fremden Betrieb, und es muss unveraendert in die
+     * eigene Konfiguration wandern. Verschluesselt speichern gilt trotzdem.
+     */
+    secret: string;
+}
+export interface WebhookPatch {
+    url?: string;
+    events?: (PartnerWebhookEventType | (string & {}))[];
+    description?: string;
+    active?: boolean;
+}
+export interface WebhookListe {
+    webhooks: PartnerWebhook[];
+    /** Der Katalog: Ereignisname und deutscher Text, so wie das Panel ihn zeigt. */
+    events: {
+        key: string;
+        text: string;
+    }[];
+}
+export interface WebhookZustellung {
+    deliveryId: string;
+    webhookId: string;
+    event: string;
+    eventId: string;
+    /** `offen`, `zugestellt` oder `fehlgeschlagen`. */
+    status: string;
+    attempts: number;
+    letzterVersuchAt: number | null;
+    naechsterVersuchAt: number | null;
+    statusCode: number | null;
+    /** Auszug der Antwort des Empfaengers, hoechstens 500 Zeichen. */
+    response: string | null;
+    createdAt: number | null;
+}
+/**
+ * Legt einen Webhook-Endpunkt an. Hoechstens [WEBHOOK_LIMIT] je Partner
+ * (`webhook_limit`).
+ *
+ * **Das Secret in der Antwort ist der einzige Weg dazu.** Es sofort dorthin
+ * schreiben, wo der Empfaenger es liest — nicht in ein Protokoll.
+ */
+export declare function createPartnerWebhook(rufen: InternerTransport, optionen: CreateWebhookOptions): Promise<CreateWebhookResult>;
+/**
+ * Ein neues Secret fuer denselben Endpunkt.
+ *
+ * Der Webhook behaelt seine `webhookId` und seine Ereignisse — nur das
+ * Geheimnis wechselt. Wer den Endpunkt stattdessen loescht und neu anlegt,
+ * verliert seine Zustellungshistorie und muss die Ereignisse neu ankreuzen.
+ *
+ * Das alte Secret gilt ab der Antwort NICHT mehr: die naechste Zustellung ist
+ * schon mit dem neuen signiert. Erst speichern, dann weiterarbeiten.
+ */
+export declare function rotatePartnerWebhookSecret(rufen: InternerTransport, webhookId: string): Promise<CreateWebhookResult>;
+/** Die Webhook-Endpunkte dieses Partners samt Ereignis-Katalog. */
+export declare function listPartnerWebhooks(rufen: InternerTransport): Promise<WebhookListe>;
+/**
+ * Aendert einen Endpunkt. Nur die genannten Felder — ein leeres `patch` lehnt
+ * das Backend ab (`validation`, Feld `patch`), statt stillschweigend nichts zu
+ * tun.
+ */
+export declare function updatePartnerWebhook(rufen: InternerTransport, webhookId: string, patch: WebhookPatch): Promise<PartnerWebhook>;
+/** Loescht einen Endpunkt. Danach kommt dort nichts mehr an. */
+export declare function deletePartnerWebhook(rufen: InternerTransport, webhookId: string): Promise<string>;
+export interface WebhookTestResult {
+    eventId: string;
+    /** Welches Ereignis geprobt wurde — ohne Angabe `webhook.test`. */
+    ereignis: string;
+    deliveries: unknown[];
+}
+/**
+ * Schickt eine Probe an genau diesen Endpunkt.
+ *
+ * Ohne `event` kommt `webhook.test` — der Nachweis, dass die Leitung steht und
+ * die eigene Signaturpruefung gegen echte Bytes laeuft. **Mit `event` kommt
+ * genau das Ereignis, das der Empfaenger behandeln soll**, mit einer
+ * glaubwuerdigen Nutzlast: wer auf `signature.ready` hin seinen Kunden
+ * benachrichtigt, probt das einmal, statt auf eine echte Karte zu warten. Eine
+ * Leitungsprobe beweist nichts ueber die Behandlung des Ernstfalls.
+ *
+ * Der Endpunkt muss das Ereignis abonnieren (`event_not_subscribed`) und aktiv
+ * sein (`webhook_inactive`); ein unbekannter Name ist ein `validation`-Fehler
+ * auf dem Feld `event`.
+ *
+ * **Jede Probe traegt `test: true` im Umschlag** ([PartnerWebhookEvent.test]).
+ *
+ * Der Backend-Endpunkt heisst `sendPartnerWebhookTest`; dieser Client behaelt
+ * den Namen bei, damit ein Leser der Doku und ein Leser des Codes dasselbe
+ * suchen.
+ */
+export declare function sendPartnerWebhookTest(rufen: InternerTransport, webhookId: string, event?: PartnerWebhookEventType | (string & {})): Promise<WebhookTestResult>;
+/**
+ * Die letzten Zustellversuche — mit `webhookId` fuer einen Endpunkt, ohne ihn
+ * fuer alle. Die Stelle, an der sich „mein Server bekommt nichts" klaeren
+ * laesst, ohne bei Kasseneck nachzufragen.
+ */
+export declare function listPartnerWebhookDeliveries(rufen: InternerTransport, optionen?: {
+    webhookId?: string;
+    limit?: number;
+}): Promise<WebhookZustellung[]>;

package/dist/cjs/partner/webhooks.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * Webhooks: Endpunkte verwalten und eingehende Zustellungen auswerten.
+ *
+ * Die Signaturpruefung liegt daneben in `webhook-signatur.ts` — sie braucht
+ * weder Transport noch Schluessel und laeuft in jedem Empfaenger, auch in
+ * einem, der sonst nichts von diesem Paket benutzt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_UMSCHLAG_FELDER = exports.PARTNER_WEBHOOK_EVENTS = void 0;
+exports.istPartnerWebhookEvent = istPartnerWebhookEvent;
+exports.parseWebhookEvent = parseWebhookEvent;
+exports.createPartnerWebhook = createPartnerWebhook;
+exports.rotatePartnerWebhookSecret = rotatePartnerWebhookSecret;
+exports.listPartnerWebhooks = listPartnerWebhooks;
+exports.updatePartnerWebhook = updatePartnerWebhook;
+exports.deletePartnerWebhook = deletePartnerWebhook;
+exports.sendPartnerWebhookTest = sendPartnerWebhookTest;
+exports.listPartnerWebhookDeliveries = listPartnerWebhookDeliveries;
+const errors_js_1 = require("../client/errors.js");
+const webhook_signatur_js_1 = require("./webhook-signatur.js");
+// ---------------------------------------------------------------------------
+// Ereignisse
+// ---------------------------------------------------------------------------
+/**
+ * Alle Ereignisse, die ein Webhook abonnieren **und proben** kann. Ein
+ * Endpunkt bekommt ausschliesslich die, die in seiner `events`-Liste stehen.
+ *
+ * Kasseneck fuehrt daneben interne Ereignisse (etwa den Abschluss eines
+ * Auftragsverarbeitungsvertrags). Sie stehen hier bewusst nicht: sie lassen
+ * sich weder abonnieren noch mit [sendPartnerWebhookTest] ausloesen, und ein
+ * Name in dieser Liste, den niemand bestellen kann, waere ein Versprechen ohne
+ * Deckung.
+ */
+exports.PARTNER_WEBHOOK_EVENTS = [
+    'customer.created',
+    'customer.updated',
+    'customer.status_changed',
+    'customer.fon_verified',
+    'customer.live_enabled',
+    'signature.requested',
+    'signature.ready',
+    'signature.failed',
+    'cashregister.created',
+    'cashregister.live',
+    'cashregister.failed',
+    'app.version.accepted',
+    'app.version.rejected',
+    'webhook.test',
+];
+function istPartnerWebhookEvent(wert) {
+    return typeof wert === 'string' && exports.PARTNER_WEBHOOK_EVENTS.includes(wert);
+}
+/**
+ * Die Felder des Umschlags, so wie er auf der Leitung liegt.
+ *
+ * Als Liste, damit der Zwilling sie nachhaelt: `test` kam spaeter dazu, und
+ * genau ein solches Feld verschwindet sonst auf einer Seite, ohne dass etwas
+ * rot wird.
+ */
+exports.WEBHOOK_UMSCHLAG_FELDER = ['id', 'type', 'createdAt', 'partnerId', 'test', 'data'];
+/**
+ * Prueft die Signatur **und** liest das Ereignis — in dieser Reihenfolge. Wer
+ * zuerst parst und dann prueft, hat den fremden Rumpf schon durch seinen Code
+ * laufen lassen.
+ *
+ * **Entdoppeln nicht vergessen:** dieselbe Zustellung kann mehrfach ankommen
+ * (Wiederholung nach einer Antwort, die unterwegs verloren ging). Massgeblich
+ * ist `event.id`, nicht der Kopf `X-Kasseneck-Delivery` — der ist bei
+ * Wiederholungen derselbe, aber er beantwortet die Frage "habe ich dieses
+ * Ereignis schon verarbeitet?" nur fuer genau diesen Endpunkt.
+ *
+ * Antworte innerhalb von 10 Sekunden mit 2xx und erledige die Arbeit danach.
+ * Eine ausbleibende Antwort wird bis zu fuenfmal wiederholt (1 min, 5 min,
+ * 30 min, 2 h, 12 h) und gilt dann als fehlgeschlagen.
+ */
+async function parseWebhookEvent(optionen) {
+    const geprueft = await (0, webhook_signatur_js_1.verifyWebhookSignature)(optionen);
+    if (!geprueft.ok)
+        return { ok: false, reason: geprueft.reason };
+    const text = typeof optionen.body === 'string' ? optionen.body : new TextDecoder('utf-8').decode(optionen.body);
+    let roh;
+    try {
+        roh = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: 'body-not-json' };
+    }
+    if (roh === null || typeof roh !== 'object' || Array.isArray(roh))
+        return { ok: false, reason: 'body-not-event' };
+    const e = roh;
+    if (typeof e['id'] !== 'string' || typeof e['type'] !== 'string')
+        return { ok: false, reason: 'body-not-event' };
+    return {
+        ok: true,
+        timestampSec: geprueft.timestampSec,
+        event: {
+            id: e['id'],
+            type: e['type'],
+            createdAt: typeof e['createdAt'] === 'number' ? e['createdAt'] : 0,
+            partnerId: typeof e['partnerId'] === 'string' ? e['partnerId'] : '',
+            // Nur ein ausdrueckliches `true` ist eine Probe. Alles andere — auch ein
+            // fehlendes Feld — ist der Ernstfall; im Zweifel lieber einmal zu viel
+            // gearbeitet als eine echte Kasse fuer eine Probe gehalten.
+            test: e['test'] === true,
+            data: e['data'] !== null && typeof e['data'] === 'object' && !Array.isArray(e['data'])
+                ? e['data']
+                : {},
+        },
+    };
+}
+function objekt(wert) {
+    return wert !== null && typeof wert === 'object' && !Array.isArray(wert) ? wert : {};
+}
+function webhook(eintrag) {
+    const w = objekt(eintrag);
+    return {
+        webhookId: typeof w['webhookId'] === 'string' ? w['webhookId'] : '',
+        url: typeof w['url'] === 'string' ? w['url'] : '',
+        events: Array.isArray(w['events']) ? w['events'].filter((e) => typeof e === 'string') : [],
+        active: w['active'] !== false,
+        description: typeof w['description'] === 'string' ? w['description'] : null,
+        createdAt: typeof w['createdAt'] === 'number' ? w['createdAt'] : null,
+        lastDelivery: typeof w['lastDelivery'] === 'number' ? w['lastDelivery'] : null,
+        consecutiveFailures: typeof w['consecutiveFailures'] === 'number' ? w['consecutiveFailures'] : 0,
+    };
+}
+/**
+ * Legt einen Webhook-Endpunkt an. Hoechstens [WEBHOOK_LIMIT] je Partner
+ * (`webhook_limit`).
+ *
+ * **Das Secret in der Antwort ist der einzige Weg dazu.** Es sofort dorthin
+ * schreiben, wo der Empfaenger es liest — nicht in ein Protokoll.
+ */
+async function createPartnerWebhook(rufen, optionen) {
+    const url = typeof optionen?.url === 'string' ? optionen.url.trim() : '';
+    if (!url)
+        throw new errors_js_1.KasseneckValidationError('createPartnerWebhook', 'url fehlt', 'request');
+    if (!Array.isArray(optionen.events) || optionen.events.length === 0) {
+        throw new errors_js_1.KasseneckValidationError('createPartnerWebhook', 'events ist leer — ein Endpunkt ohne Ereignis bekaeme nie etwas', 'request');
+    }
+    const daten = objekt(await rufen('createPartnerWebhook', {
+        url,
+        events: optionen.events,
+        description: optionen.description,
+        active: optionen.active,
+    }));
+    const secret = daten['secret'];
+    if (typeof secret !== 'string' || !secret) {
+        throw new errors_js_1.KasseneckValidationError('createPartnerWebhook', 'Antwort enthaelt kein secret — ohne es laesst sich keine Zustellung pruefen', 'response');
+    }
+    return { webhook: webhook(daten['webhook']), secret };
+}
+/**
+ * Ein neues Secret fuer denselben Endpunkt.
+ *
+ * Der Webhook behaelt seine `webhookId` und seine Ereignisse — nur das
+ * Geheimnis wechselt. Wer den Endpunkt stattdessen loescht und neu anlegt,
+ * verliert seine Zustellungshistorie und muss die Ereignisse neu ankreuzen.
+ *
+ * Das alte Secret gilt ab der Antwort NICHT mehr: die naechste Zustellung ist
+ * schon mit dem neuen signiert. Erst speichern, dann weiterarbeiten.
+ */
+async function rotatePartnerWebhookSecret(rufen, webhookId) {
+    const id = typeof webhookId === 'string' ? webhookId.trim() : '';
+    if (!id)
+        throw new errors_js_1.KasseneckValidationError('rotatePartnerWebhookSecret', 'webhookId fehlt', 'request');
+    const daten = objekt(await rufen('rotatePartnerWebhookSecret', { webhookId: id }));
+    const secret = daten['secret'];
+    if (typeof secret !== 'string' || !secret) {
+        throw new errors_js_1.KasseneckValidationError('rotatePartnerWebhookSecret', 'Antwort enthaelt kein secret — dann waere der Wechsel nicht nachvollziehbar', 'response');
+    }
+    return { webhook: webhook(daten['webhook']), secret };
+}
+/** Die Webhook-Endpunkte dieses Partners samt Ereignis-Katalog. */
+async function listPartnerWebhooks(rufen) {
+    const daten = objekt(await rufen('listPartnerWebhooks'));
+    return {
+        webhooks: (Array.isArray(daten['webhooks']) ? daten['webhooks'] : []).map(webhook),
+        events: (Array.isArray(daten['events']) ? daten['events'] : []).map((e) => ({
+            key: typeof objekt(e)['key'] === 'string' ? objekt(e)['key'] : '',
+            text: typeof objekt(e)['text'] === 'string' ? objekt(e)['text'] : '',
+        })),
+    };
+}
+/**
+ * Aendert einen Endpunkt. Nur die genannten Felder — ein leeres `patch` lehnt
+ * das Backend ab (`validation`, Feld `patch`), statt stillschweigend nichts zu
+ * tun.
+ */
+async function updatePartnerWebhook(rufen, webhookId, patch) {
+    const id = typeof webhookId === 'string' ? webhookId.trim() : '';
+    if (!id)
+        throw new errors_js_1.KasseneckValidationError('updatePartnerWebhook', 'webhookId fehlt', 'request');
+    if (patch === null || typeof patch !== 'object' || Object.keys(patch).length === 0) {
+        throw new errors_js_1.KasseneckValidationError('updatePartnerWebhook', 'patch nennt keine Aenderung', 'request');
+    }
+    const daten = objekt(await rufen('updatePartnerWebhook', { webhookId: id, patch }));
+    return webhook(daten['webhook']);
+}
+/** Loescht einen Endpunkt. Danach kommt dort nichts mehr an. */
+async function deletePartnerWebhook(rufen, webhookId) {
+    const id = typeof webhookId === 'string' ? webhookId.trim() : '';
+    if (!id)
+        throw new errors_js_1.KasseneckValidationError('deletePartnerWebhook', 'webhookId fehlt', 'request');
+    const daten = objekt(await rufen('deletePartnerWebhook', { webhookId: id }));
+    return typeof daten['webhookId'] === 'string' ? daten['webhookId'] : id;
+}
+/**
+ * Schickt eine Probe an genau diesen Endpunkt.
+ *
+ * Ohne `event` kommt `webhook.test` — der Nachweis, dass die Leitung steht und
+ * die eigene Signaturpruefung gegen echte Bytes laeuft. **Mit `event` kommt
+ * genau das Ereignis, das der Empfaenger behandeln soll**, mit einer
+ * glaubwuerdigen Nutzlast: wer auf `signature.ready` hin seinen Kunden
+ * benachrichtigt, probt das einmal, statt auf eine echte Karte zu warten. Eine
+ * Leitungsprobe beweist nichts ueber die Behandlung des Ernstfalls.
+ *
+ * Der Endpunkt muss das Ereignis abonnieren (`event_not_subscribed`) und aktiv
+ * sein (`webhook_inactive`); ein unbekannter Name ist ein `validation`-Fehler
+ * auf dem Feld `event`.
+ *
+ * **Jede Probe traegt `test: true` im Umschlag** ([PartnerWebhookEvent.test]).
+ *
+ * Der Backend-Endpunkt heisst `sendPartnerWebhookTest`; dieser Client behaelt
+ * den Namen bei, damit ein Leser der Doku und ein Leser des Codes dasselbe
+ * suchen.
+ */
+async function sendPartnerWebhookTest(rufen, webhookId, event) {
+    const id = typeof webhookId === 'string' ? webhookId.trim() : '';
+    if (!id)
+        throw new errors_js_1.KasseneckValidationError('sendPartnerWebhookTest', 'webhookId fehlt', 'request');
+    const ereignis = typeof event === 'string' ? event.trim() : '';
+    const daten = objekt(await rufen('sendPartnerWebhookTest', { webhookId: id, event: ereignis || undefined }));
+    return {
+        eventId: typeof daten['eventId'] === 'string' ? daten['eventId'] : '',
+        ereignis: typeof daten['ereignis'] === 'string' ? daten['ereignis'] : ereignis || 'webhook.test',
+        deliveries: Array.isArray(daten['deliveries']) ? daten['deliveries'] : [],
+    };
+}
+/**
+ * Die letzten Zustellversuche — mit `webhookId` fuer einen Endpunkt, ohne ihn
+ * fuer alle. Die Stelle, an der sich „mein Server bekommt nichts" klaeren
+ * laesst, ohne bei Kasseneck nachzufragen.
+ */
+async function listPartnerWebhookDeliveries(rufen, optionen = {}) {
+    if (optionen.limit !== undefined && (!Number.isInteger(optionen.limit) || optionen.limit < 1 || optionen.limit > 200)) {
+        throw new errors_js_1.KasseneckValidationError('listPartnerWebhookDeliveries', 'limit muss zwischen 1 und 200 liegen', 'request');
+    }
+    const daten = objekt(await rufen('listPartnerWebhookDeliveries', { webhookId: optionen.webhookId, limit: optionen.limit }));
+    return (Array.isArray(daten['deliveries']) ? daten['deliveries'] : []).map((eintrag) => {
+        const z = objekt(eintrag);
+        const zahl = (wert) => (typeof wert === 'number' && Number.isFinite(wert) ? wert : null);
+        const txt = (wert) => (typeof wert === 'string' ? wert : null);
+        return {
+            deliveryId: txt(z['deliveryId']) ?? '',
+            webhookId: txt(z['webhookId']) ?? '',
+            event: txt(z['event']) ?? '',
+            eventId: txt(z['eventId']) ?? '',
+            status: txt(z['status']) ?? '',
+            attempts: zahl(z['attempts']) ?? 0,
+            letzterVersuchAt: zahl(z['letzterVersuchAt']),
+            naechsterVersuchAt: zahl(z['naechsterVersuchAt']),
+            statusCode: zahl(z['statusCode']),
+            response: txt(z['response']),
+            createdAt: zahl(z['createdAt']),
+        };
+    });
+}

package/dist/cjs/register/pairing.d.ts

@@ -159,7 +159,14 @@ export interface RegisterUserPerms {
     tipAssign?: boolean;
     [weiteresRecht: string]: boolean | RegisterScope | undefined;
 }
-/** Alle Rechte-Schluessel, die dieses Paket kennt — die Zwillinge pruefen dagegen. */
+/**
+ * Alle Rechte-Schluessel, die dieses Paket kennt — die Zwillinge pruefen
+ * dagegen, und ueber `fixtures/oberflaeche.json` steht die Liste im Vertrag.
+ *
+ * `satisfies` schliesst die eine Richtung: ein Name, den [RegisterUserPerms]
+ * nicht fuehrt (Tippfehler, umbenanntes Recht), kommt hier nicht durch.
+ * Die Gegenrichtung schliesst [_RechteVollstaendig] direkt darunter.
+ */
 export declare const REGISTER_PERMS: readonly ["sell", "cancel", "articles", "layout", "reports", "takeover", "cancelScope", "receiptsScope", "drawer", "discount", "tipAssign"];
 /** Reichweite lesen, mit der Migration des Backends (register-auth.js). */
 export declare function cancelScopeOf(perms: RegisterUserPerms | null | undefined): RegisterScope;

package/dist/cjs/register/pairing.js

@@ -48,7 +48,14 @@ const settings_js_1 = require("../kasse/settings.js");
  * es auch halten.
  */
 const ohneAnmeldung = () => ({ headers: {}, params: {} });
-/** Alle Rechte-Schluessel, die dieses Paket kennt — die Zwillinge pruefen dagegen. */
+/**
+ * Alle Rechte-Schluessel, die dieses Paket kennt — die Zwillinge pruefen
+ * dagegen, und ueber `fixtures/oberflaeche.json` steht die Liste im Vertrag.
+ *
+ * `satisfies` schliesst die eine Richtung: ein Name, den [RegisterUserPerms]
+ * nicht fuehrt (Tippfehler, umbenanntes Recht), kommt hier nicht durch.
+ * Die Gegenrichtung schliesst [_RechteVollstaendig] direkt darunter.
+ */
 exports.REGISTER_PERMS = [
     'sell', 'cancel', 'articles', 'layout', 'reports', 'takeover',
     'cancelScope', 'receiptsScope', 'drawer', 'discount', 'tipAssign',

package/dist/esm/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/esm/client/aufrufe.js

@@ -1,31 +1,51 @@
 export const 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/esm/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';