@kreiseck/kasseneck-api 0.6.46 → 0.7.0

package/dist/esm/client/errors.js

@@ -85,6 +85,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.
+ */
+export 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. */
 export class KasseneckApiError extends Error {
     name = 'KasseneckApiError';
@@ -92,10 +170,28 @@ export 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;
     }
 }
 const GRUND_TEXT = {

package/dist/esm/client/transport.js

@@ -1,4 +1,4 @@
-import { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, causeDigest, } from './errors.js';
+import { KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, causeDigest, fehlerDetails, } from './errors.js';
 /**
  * Transport zum Kasseneck-Backend: ein Aufruf ist ein POST an
  * `<basis>/<funktionsname>` mit dem JSON-Rumpf `{ "params": { … } }` — wie im
@@ -129,7 +129,7 @@ function createCore(options) {
             if (antwort.status !== 200) {
                 throw new 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.
@@ -154,7 +154,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 KasseneckHttpError(functionName, statusCode, inhaltstyp, 'empty-body');
     }
@@ -176,7 +176,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
@@ -191,7 +191,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 KasseneckHttpError(functionName, statusCode, inhaltstyp, 'empty-body');
     }
@@ -222,7 +222,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) {
@@ -235,9 +235,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 KasseneckApiError(functionName, meldung);
+    return new KasseneckApiError(functionName, meldung, fehlerDetails(daten, geheimnisse));
 }
 /**
  * Nutzlast aus Auth- und Aufruferparametern. Auth-Parameter bilden die

package/dist/esm/partner/ablauf.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Der Weg vom Vertragsabschluss bis zum ersten Beleg — als Daten, nicht als
+ * Fliesstext.
+ *
+ * **Warum das im Paket steht und nicht nur in der Doku:** die Kette hat eine
+ * harte Reihenfolge, und jeder Schritt scheitert mit einem eigenen Code, wenn
+ * ein vorheriger fehlt (`fon_missing`, `signature_missing`,
+ * `signature_not_ready`).
+ * Wer die Reihenfolge nur aus einer Fehlermeldung lernt, lernt sie einmal je
+ * Fehler. Hier steht sie vorher — abfragbar, ausgebbar, und in
+ * [naechsterSchritt] auch beantwortbar.
+ *
+ * **Ohne Vertragsschritt.** Auftragsverarbeitungsvertraege wirken in diesem
+ * Weg nicht mehr (Stand 2026-08-31): kein Aufruf meldet einen, keine Kasse
+ * bleibt deswegen stehen.
+ *
+ * Zwei Dinge laufen bewusst **parallel**: der Signaturantrag und das Anlegen
+ * der Kasse. Eine mit `automatic:true` angelegte Kasse wartet, bis die
+ * Signatur bereit ist, und geht dann von selbst live. Der Kundenstatus nennt
+ * darum immer nur den **weitesten erreichten** Meilenstein, nicht die einzige
+ * laufende Arbeit.
+ */
+import type { KundenStatus } from './typen.js';
+/** Ein Schritt der Kette. */
+export interface AblaufSchritt {
+    key: string;
+    /** Was in diesem Schritt passiert. */
+    text: string;
+    /** Der Aufruf, der ihn ausloest — `null`, wenn hier nur gewartet wird. */
+    aufruf: string | null;
+    /** Das Ereignis, das seinen Abschluss meldet — `null`, wenn es sofort feststeht. */
+    wartetAuf: string | null;
+    /** Der Fehlercode, mit dem ein spaeterer Aufruf sich beschwert, wenn dieser Schritt fehlt. */
+    fehltCode: string | null;
+}
+/**
+ * Die Kette in ihrer Reihenfolge. Sie beschreibt den **Live-Weg**; mit einem
+ * `pk_test_`-Schluessel entfallen die FinanzOnline-Schritte, und die Signatur
+ * ist sofort bereit (AT100-Testkarte — die damit erzeugten Belege sind keine
+ * gueltigen RKSV-Belege).
+ */
+export declare const PARTNER_ABLAUF: readonly AblaufSchritt[];
+/**
+ * Der Schritt, an dem ein Betrieb mit diesem Status steht — `null` fuer
+ * `gesperrt` und fuer jeden Status, den dieses Paket nicht kennt.
+ */
+export declare function naechsterSchritt(status: KundenStatus): AblaufSchritt | null;

package/dist/esm/partner/ablauf.js

@@ -0,0 +1,95 @@
+/**
+ * Der Weg vom Vertragsabschluss bis zum ersten Beleg — als Daten, nicht als
+ * Fliesstext.
+ *
+ * **Warum das im Paket steht und nicht nur in der Doku:** die Kette hat eine
+ * harte Reihenfolge, und jeder Schritt scheitert mit einem eigenen Code, wenn
+ * ein vorheriger fehlt (`fon_missing`, `signature_missing`,
+ * `signature_not_ready`).
+ * Wer die Reihenfolge nur aus einer Fehlermeldung lernt, lernt sie einmal je
+ * Fehler. Hier steht sie vorher — abfragbar, ausgebbar, und in
+ * [naechsterSchritt] auch beantwortbar.
+ *
+ * **Ohne Vertragsschritt.** Auftragsverarbeitungsvertraege wirken in diesem
+ * Weg nicht mehr (Stand 2026-08-31): kein Aufruf meldet einen, keine Kasse
+ * bleibt deswegen stehen.
+ *
+ * Zwei Dinge laufen bewusst **parallel**: der Signaturantrag und das Anlegen
+ * der Kasse. Eine mit `automatic:true` angelegte Kasse wartet, bis die
+ * Signatur bereit ist, und geht dann von selbst live. Der Kundenstatus nennt
+ * darum immer nur den **weitesten erreichten** Meilenstein, nicht die einzige
+ * laufende Arbeit.
+ */
+/**
+ * Die Kette in ihrer Reihenfolge. Sie beschreibt den **Live-Weg**; mit einem
+ * `pk_test_`-Schluessel entfallen die FinanzOnline-Schritte, und die Signatur
+ * ist sofort bereit (AT100-Testkarte — die damit erzeugten Belege sind keine
+ * gueltigen RKSV-Belege).
+ */
+export const PARTNER_ABLAUF = [
+    {
+        key: 'business',
+        text: 'Betrieb anlegen (idempotencyKey = eigene Kundennummer).',
+        aufruf: 'createPartnerCustomer',
+        wartetAuf: 'customer.created',
+        fehltCode: null,
+    },
+    {
+        key: 'fon',
+        text: 'FinanzOnline einrichten: Link an den Betrieb, der Betrieb traegt seinen Zugang ein.',
+        aufruf: 'sendPartnerCustomerFonLink',
+        wartetAuf: 'customer.fon_verified',
+        fehltCode: 'fon_missing',
+    },
+    {
+        key: 'signature',
+        text: 'Signatureinheit beantragen. Kasseneck weist eine Karte zu und meldet sie bei FinanzOnline an.',
+        aufruf: 'requestCustomerSignature',
+        wartetAuf: 'signature.ready',
+        fehltCode: 'signature_missing',
+    },
+    {
+        key: 'cashregister',
+        text: 'Kasse anlegen. Mit automatic:true (Vorgabe) geht sie von selbst live, sobald die Signatur bereit ist — ' +
+            'sie darf deshalb schon vorher angelegt werden.',
+        aufruf: 'createCustomerCashregister',
+        wartetAuf: 'cashregister.live',
+        fehltCode: 'cashregister_not_found',
+    },
+    {
+        key: 'zugangsdaten',
+        text: 'Zugangsdaten des Betriebs holen (Scope credentials:read). Geheimnisse — nur verschluesselt speichern.',
+        aufruf: 'getCustomerCredentials',
+        wartetAuf: null,
+        fehltCode: null,
+    },
+    {
+        key: 'belege',
+        text: 'Belege signieren: Bearer = apiKey des Betriebs, Kopfzeile cashregister-token = Token der Kasse.',
+        aufruf: 'createReceipt',
+        wartetAuf: null,
+        fehltCode: null,
+    },
+];
+/**
+ * Welcher Meilenstein einem Kundenstatus entspricht. Die Zuordnung ist
+ * absichtlich grob: der Status nennt den weitesten erreichten Punkt, nicht die
+ * laufende Arbeit — fuer den genauen Verlauf sind die Ereignisse `signature.*`
+ * und `cashregister.*` da.
+ */
+const STATUS_SCHRITT = {
+    created: 'fon',
+    fon_configured: 'signature',
+    signature_requested: 'signature',
+    signature_ready: 'cashregister',
+    cashregister_created: 'cashregister',
+    live: 'zugangsdaten',
+};
+/**
+ * Der Schritt, an dem ein Betrieb mit diesem Status steht — `null` fuer
+ * `gesperrt` und fuer jeden Status, den dieses Paket nicht kennt.
+ */
+export function naechsterSchritt(status) {
+    const key = STATUS_SCHRITT[status];
+    return key ? PARTNER_ABLAUF.find((s) => s.key === key) ?? null : null;
+}

package/dist/esm/partner/api.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Fassade ueber den Partner-Aufrufen: Schluessel einmal binden, dann rufen.
+ *
+ * Wie [createKasseneckApi] bewusst **keine** Klasse — die Aufrufe sind freie
+ * Funktionen und bleiben einzeln importierbar.
+ */
+import { type FetchLike } from '../client/transport.js';
+import { type CreateWebhookOptions, type CreateWebhookResult, type PartnerWebhook, type WebhookListe, type PartnerWebhookEventType, type WebhookPatch, type WebhookTestResult, type WebhookZustellung } from './webhooks.js';
+import type { ActivateCashregisterResult, CreateCashregisterOptions, CreateCashregisterResult, CreateCustomerOptions, CreateCustomerResult, CustomerCredentials, FonLinkResult, KassenListe, Kunde, KundenListe, ListCustomersOptions, PartnerInfo, RequestSignatureResult, SignaturStand } from './typen.js';
+export interface PartnerApiOptions {
+    /** Partner-Schluessel `pk_test_…` / `pk_live_…`. Gehoert auf einen Server. */
+    partnerKey: string;
+    /** Abweichende Basis-URL; Vorgabe `https://api.kasseneck.at/v1`. */
+    baseUrl?: string;
+    /** Zeitlimit je Aufruf in Millisekunden. */
+    timeoutMs?: number;
+    /** Eigene `fetch`-Umsetzung (Tests, Proxys). */
+    fetch?: FetchLike;
+}
+export interface PartnerApi {
+    getPartnerInfo(): Promise<PartnerInfo>;
+    createPartnerCustomer(optionen: CreateCustomerOptions): Promise<CreateCustomerResult>;
+    listPartnerCustomers(optionen?: ListCustomersOptions): Promise<KundenListe>;
+    getPartnerCustomer(customerId: string): Promise<Kunde>;
+    sendPartnerCustomerFonLink(customerId: string): Promise<FonLinkResult>;
+    requestCustomerSignature(customerId: string, optionen?: {
+        art?: string;
+        additional?: boolean;
+    }): Promise<RequestSignatureResult>;
+    getCustomerSignatureStatus(customerId: string): Promise<SignaturStand>;
+    createCustomerCashregister(optionen: CreateCashregisterOptions): Promise<CreateCashregisterResult>;
+    activateCashregister(customerId: string, cashregisterId: string): Promise<ActivateCashregisterResult>;
+    listCustomerCashregisters(customerId: string): Promise<KassenListe>;
+    /** Geheimnisse des Betriebs — siehe `getCustomerCredentials` in endpunkte.ts. */
+    getCustomerCredentials(customerId: string): Promise<CustomerCredentials>;
+    /**
+     * Ist diese Adresse als Kasseneck-Zugang noch frei? Nur noetig, wenn der
+     * Betrieb einen eigenen Login bekommen soll — sonst faellt `email_taken`
+     * erst nach dem ganzen Formular auf.
+     */
+    checkPartnerCustomerEmail(email: string): Promise<boolean>;
+    createPartnerWebhook(optionen: CreateWebhookOptions): Promise<CreateWebhookResult>;
+    listPartnerWebhooks(): Promise<WebhookListe>;
+    updatePartnerWebhook(webhookId: string, patch: WebhookPatch): Promise<PartnerWebhook>;
+    deletePartnerWebhook(webhookId: string): Promise<string>;
+    /**
+     * Neues Secret fuer denselben Endpunkt — dieselbe `webhookId`, dieselben
+     * Ereignisse. Das alte gilt ab der Antwort nicht mehr.
+     */
+    rotatePartnerWebhookSecret(webhookId: string): Promise<CreateWebhookResult>;
+    /**
+     * Eine Probe an einen Endpunkt — ohne `event` die Leitungsprobe
+     * `webhook.test`, mit `event` genau der Fall, den der Empfaenger behandeln
+     * soll. Jede Probe traegt `test: true` im Umschlag.
+     */
+    sendPartnerWebhookTest(webhookId: string, event?: PartnerWebhookEventType | (string & {})): Promise<WebhookTestResult>;
+    listPartnerWebhookDeliveries(optionen?: {
+        webhookId?: string;
+        limit?: number;
+    }): Promise<WebhookZustellung[]>;
+    /**
+     * Der Handlungssatz zu einem beliebigen Fehlercode der Partner-API. Gehoert
+     * in die eigene Fehlermeldung, damit ein Anwender nicht in der Doku
+     * nachschlagen muss.
+     */
+    fehlerRat(code: string): string | undefined;
+}
+export declare function createPartnerApi(optionen: PartnerApiOptions): PartnerApi;

package/dist/esm/partner/api.js

@@ -0,0 +1,41 @@
+/**
+ * Fassade ueber den Partner-Aufrufen: Schluessel einmal binden, dann rufen.
+ *
+ * Wie [createKasseneckApi] bewusst **keine** Klasse — die Aufrufe sind freie
+ * Funktionen und bleiben einzeln importierbar.
+ */
+import { createTransport } from '../client/transport.js';
+import { partnerKeyAuth } from './auth.js';
+import { partnerFehlerRat } from './fehler.js';
+import { activateCashregister, createCustomerCashregister, createPartnerCustomer, getCustomerCredentials, getCustomerSignatureStatus, getPartnerCustomer, getPartnerInfo, checkPartnerCustomerEmail, listCustomerCashregisters, listPartnerCustomers, requestCustomerSignature, sendPartnerCustomerFonLink, } from './endpunkte.js';
+import { createPartnerWebhook, deletePartnerWebhook, listPartnerWebhookDeliveries, listPartnerWebhooks, rotatePartnerWebhookSecret, sendPartnerWebhookTest, updatePartnerWebhook, } from './webhooks.js';
+export function createPartnerApi(optionen) {
+    const rufen = createTransport({
+        auth: partnerKeyAuth({ partnerKey: optionen.partnerKey }),
+        baseUrl: optionen.baseUrl,
+        timeoutMs: optionen.timeoutMs,
+        fetch: optionen.fetch,
+    });
+    return {
+        getPartnerInfo: () => getPartnerInfo(rufen),
+        createPartnerCustomer: (o) => createPartnerCustomer(rufen, o),
+        listPartnerCustomers: (o) => listPartnerCustomers(rufen, o),
+        getPartnerCustomer: (id) => getPartnerCustomer(rufen, id),
+        sendPartnerCustomerFonLink: (id) => sendPartnerCustomerFonLink(rufen, id),
+        requestCustomerSignature: (id, o) => requestCustomerSignature(rufen, id, o),
+        getCustomerSignatureStatus: (id) => getCustomerSignatureStatus(rufen, id),
+        createCustomerCashregister: (o) => createCustomerCashregister(rufen, o),
+        activateCashregister: (kunde, kasse) => activateCashregister(rufen, kunde, kasse),
+        listCustomerCashregisters: (id) => listCustomerCashregisters(rufen, id),
+        getCustomerCredentials: (id) => getCustomerCredentials(rufen, id),
+        checkPartnerCustomerEmail: (email) => checkPartnerCustomerEmail(rufen, email),
+        createPartnerWebhook: (o) => createPartnerWebhook(rufen, o),
+        listPartnerWebhooks: () => listPartnerWebhooks(rufen),
+        updatePartnerWebhook: (id, patch) => updatePartnerWebhook(rufen, id, patch),
+        deletePartnerWebhook: (id) => deletePartnerWebhook(rufen, id),
+        rotatePartnerWebhookSecret: (id) => rotatePartnerWebhookSecret(rufen, id),
+        sendPartnerWebhookTest: (id, event) => sendPartnerWebhookTest(rufen, id, event),
+        listPartnerWebhookDeliveries: (o) => listPartnerWebhookDeliveries(rufen, o),
+        fehlerRat: (code) => partnerFehlerRat(code),
+    };
+}

package/dist/esm/partner/auth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Anmeldung eines Partner-Servers: der Partner-Schluessel als Bearer.
+ *
+ * Ein dritter Weg neben `apiKeyAuth` (Geraete) und `registerUserAuth`
+ * (Browser-Kasse) — und der einzige, mit dem die Partner-Endpunkte antworten.
+ * Er traegt **keine** Kopfzeile `cashregister-token`: ein Partner arbeitet nie
+ * an einer Kasse, sondern ueber Betriebe.
+ *
+ * **Der Schluessel gehoert auf einen Server.** Er kann Betriebe anlegen und —
+ * mit `credentials:read` — deren Geheimnisse holen. In einer Browser- oder
+ * Mobil-App ist er ausgeliefert, nicht hinterlegt.
+ */
+import type { KasseneckAuth } from '../client/auth.js';
+import type { PartnerEnv } from './typen.js';
+/**
+ * Die Umgebung eines Partner-Schluessels, ohne Netzaufruf — `null`, wenn es
+ * keiner ist. Nuetzlich fuer die Zusicherung „auf diesem Server laeuft nur
+ * `pk_live_`" beim Hochfahren.
+ */
+export declare function partnerKeyEnv(schluessel: string): PartnerEnv | null;
+export interface PartnerKeyAuthOptions {
+    /** Partner-Schluessel `pk_test_…` / `pk_live_…`. */
+    partnerKey: string;
+}
+/**
+ * Anmeldung per Partner-Schluessel.
+ *
+ * Die Form wird hier geprueft und nicht erst vom Server: ein vertauschter
+ * `kr_live_`-Schluessel (der eines Betriebs) faellt sonst als nichtssagendes
+ * „ungueltiger Schluessel" auf, obwohl er tadellos ist — nur eben fuer einen
+ * anderen Weg. Die Meldung nennt nie den Wert, nur seine Art.
+ */
+export declare function partnerKeyAuth(options: PartnerKeyAuthOptions): KasseneckAuth;

package/dist/esm/partner/auth.js

@@ -0,0 +1,48 @@
+/**
+ * Anmeldung eines Partner-Servers: der Partner-Schluessel als Bearer.
+ *
+ * Ein dritter Weg neben `apiKeyAuth` (Geraete) und `registerUserAuth`
+ * (Browser-Kasse) — und der einzige, mit dem die Partner-Endpunkte antworten.
+ * Er traegt **keine** Kopfzeile `cashregister-token`: ein Partner arbeitet nie
+ * an einer Kasse, sondern ueber Betriebe.
+ *
+ * **Der Schluessel gehoert auf einen Server.** Er kann Betriebe anlegen und —
+ * mit `credentials:read` — deren Geheimnisse holen. In einer Browser- oder
+ * Mobil-App ist er ausgeliefert, nicht hinterlegt.
+ */
+import { KasseneckAuthError } from '../client/errors.js';
+/**
+ * Form eines Partner-Schluessels: `pk_test_…` bzw. `pk_live_…`. Der Rest ist
+ * opak — die Laenge kann sich aendern, das Praefix nicht (an ihm haengt die
+ * Umgebung).
+ */
+const SCHLUESSEL_FORM = /^pk_(test|live)_[A-Za-z0-9_-]{16,}$/;
+/**
+ * Die Umgebung eines Partner-Schluessels, ohne Netzaufruf — `null`, wenn es
+ * keiner ist. Nuetzlich fuer die Zusicherung „auf diesem Server laeuft nur
+ * `pk_live_`" beim Hochfahren.
+ */
+export function partnerKeyEnv(schluessel) {
+    const treffer = SCHLUESSEL_FORM.exec(typeof schluessel === 'string' ? schluessel.trim() : '');
+    return treffer ? treffer[1] : null;
+}
+/**
+ * Anmeldung per Partner-Schluessel.
+ *
+ * Die Form wird hier geprueft und nicht erst vom Server: ein vertauschter
+ * `kr_live_`-Schluessel (der eines Betriebs) faellt sonst als nichtssagendes
+ * „ungueltiger Schluessel" auf, obwohl er tadellos ist — nur eben fuer einen
+ * anderen Weg. Die Meldung nennt nie den Wert, nur seine Art.
+ */
+export function partnerKeyAuth(options) {
+    const schluessel = typeof options?.partnerKey === 'string' ? options.partnerKey.trim() : '';
+    if (!schluessel) {
+        throw new KasseneckAuthError('partnerKeyAuth: partnerKey fehlt');
+    }
+    if (!partnerKeyEnv(schluessel)) {
+        throw new KasseneckAuthError('partnerKeyAuth: partnerKey hat nicht die Form pk_test_… / pk_live_… — ein Betriebsschluessel (kr_…) passt hier nicht');
+    }
+    // Pro Aufruf ein frisches Objekt: der Transport darf daran schreiben, ohne
+    // die naechste Anfrage zu vergiften (wie apiKeyAuth).
+    return () => ({ headers: { Authorization: `Bearer ${schluessel}` }, params: {} });
+}

package/dist/esm/partner/betrieb.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Was ein Betrieb ueber die Schnittstelle mitbringen darf — Feld fuer Feld.
+ *
+ * **Unbekannte Felder werden abgewiesen, nicht stillschweigend verworfen.**
+ * Vorher verschwand ein `iban` oder ein vertippter Feldname spurlos: der
+ * Partner glaubte, er habe die Steuernummer geschickt, und Kasseneck hatte
+ * nichts. Ein Feld, das man schickt und das nichts bewirkt, ist der teuerste
+ * Fehler in einer Schnittstelle, weil ihn niemand bemerkt.
+ *
+ * Seitdem antwortet `createPartnerCustomer` mit `validation` und dem genauen
+ * Feldpfad — verschachtelt und je Kontakt: `address.land`,
+ * `tax_details.ustid`, `contacts.1.abteilung`.
+ *
+ * Zwei Dinge halten diese Seite dagegen:
+ *
+ * - der Typ [Betrieb] (typen.ts) hat genau diese Felder, und TypeScript meldet
+ *   ein ueberzaehliges schon beim Tippen;
+ * - [unbekannteBetriebsfelder] beantwortet dieselbe Frage zur Laufzeit — fuer
+ *   Daten, die aus einer Datenbank oder einem Formular kommen und deshalb nie
+ *   durch die Typpruefung gelaufen sind.
+ *
+ * **Die Wahrheit bleibt der Server.** Dieser Client weist nichts von sich aus
+ * ab: eine spaetere Backend-Fassung darf ein Feld ergaenzen, ohne dass ein
+ * aelterer Client es blockiert. [unbekannteBetriebsfelder] ist die Vorschau,
+ * nicht das Tor.
+ *
+ * Quelle der Liste: `partner-core.BETRIEB_FELDER` im Backend.
+ */
+/**
+ * Jedes erlaubte Feld als Pfad. `[]` markiert eine Liste — im Fehlerpfad des
+ * Servers steht dort der Index (`contacts.0.name`).
+ *
+ * Bewusst flach und nicht verschachtelt: so ist es EINE Liste, die der
+ * Zwilling Zeile fuer Zeile nachhalten kann. Das Schema fuer die Pruefung
+ * entsteht daraus (siehe unten) und nicht daneben.
+ */
+export declare const BETRIEB_FELDER: readonly ["companyName", "legalForm", "state", "industry", "companyRegister", "court", "web", "phone", "email", "billingEmail", "address.street", "address.number", "address.zip", "address.city", "taxDetails.taxNumber", "taxDetails.vatId", "taxDetails.gln", "taxDetails.smallBusiness", "contacts[].name", "contacts[].email", "contacts[].phone", "contacts[].roles", "taxAdvisor.name", "taxAdvisor.email", "taxAdvisor.phone", "taxAdvisor.mayContact"];
+export type BetriebFeld = typeof BETRIEB_FELDER[number];
+/**
+ * Die Feldpfade eines Betriebs, die [BETRIEB_FELDER] nicht kennt — dieselbe
+ * Ableitung wie im Backend, also dieselben Pfade wie in `data.errors[].field`.
+ * Leer heisst: aus dieser Sicht ist nichts ueberzaehlig.
+ *
+ * Sagt **nichts** ueber die Werte: Steuernummer, UID, PLZ und Gericht prueft
+ * das Backend mit `@kreiseck/validator`. Diese Funktion beantwortet nur die
+ * Frage „schicke ich etwas, das dort niemand erwartet?".
+ */
+export declare function unbekannteBetriebsfelder(business: unknown): string[];