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

package/dist/cjs/partner/endpunkte.js

@@ -12,7 +12,7 @@
  * PLZ, Gericht) macht das Backend mit `@kreiseck/validator` — sie hier zu
  * wiederholen hiesse, zwei Wahrheiten zu haben, von denen eine veraltet.
  * Ein Formfehler kommt als `KasseneckApiError` mit `code:"validation"` zurueck;
- * `partnerFeldFehler(fehler)` macht `data.errors[]` daraus. **Es entsteht dabei
+ * `partnerFieldErrors(fehler)` macht `data.errors[]` daraus. **Es entsteht dabei
  * nichts** — der Aufruf ist folgenlos wiederholbar.
  *
  * Nach dem Senden wird nichts hart gecastet: fehlt ein zugesagtes Feld, wirft
@@ -32,6 +32,7 @@ exports.createCustomerCashregister = createCustomerCashregister;
 exports.activateCashregister = activateCashregister;
 exports.listCustomerCashregisters = listCustomerCashregisters;
 exports.getCustomerCredentials = getCustomerCredentials;
+exports.reportCustomerContract = reportCustomerContract;
 const errors_js_1 = require("../client/errors.js");
 const secret_js_1 = require("./secret.js");
 // ---------------------------------------------------------------------------
@@ -100,8 +101,8 @@ function pflicht(wert, vorgang, feld) {
  * Der guenstigste Selbsttest beim Hochfahren: er beweist Schluessel, Umgebung
  * und Rechte in einem Aufruf.
  */
-async function getPartnerInfo(rufen) {
-    const daten = objekt(await rufen('getPartnerInfo'));
+async function getPartnerInfo(transport) {
+    const daten = objekt(await transport('getPartnerInfo'));
     const partner = verlangt(daten['partner'], 'getPartnerInfo', 'partner');
     const key = objekt(daten['key']);
     return {
@@ -159,18 +160,18 @@ async function getPartnerInfo(rufen) {
  * — auch dann, wenn der Rumpf inzwischen abweicht. Die eigene Kundennummer ist
  * der natuerliche Wert dafuer.
  */
-async function createPartnerCustomer(rufen, optionen) {
-    const appId = pflicht(optionen?.appId, 'createPartnerCustomer', 'appId');
-    const betrieb = optionen?.business;
+async function createPartnerCustomer(transport, options) {
+    const appId = pflicht(options?.appId, 'createPartnerCustomer', 'appId');
+    const betrieb = options?.business;
     if (betrieb === null || typeof betrieb !== 'object') {
         throw new errors_js_1.KasseneckValidationError('createPartnerCustomer', 'business fehlt', 'request');
     }
-    const daten = objekt(await rufen('createPartnerCustomer', {
+    const daten = objekt(await transport('createPartnerCustomer', {
         appId,
         business: betrieb,
-        idempotencyKey: optionen.idempotencyKey,
-        access: optionen.access,
-        env: optionen.env,
+        idempotencyKey: options.idempotencyKey,
+        access: options.access,
+        env: options.env,
     }));
     const customerId = textOderNull(daten['customerId']);
     if (!customerId) {
@@ -190,14 +191,14 @@ async function createPartnerCustomer(rufen, optionen) {
     };
 }
 /** Betriebe dieses Partners, seitenweise. `cursor` aus der Antwort setzt fort. */
-async function listPartnerCustomers(rufen, optionen = {}) {
-    if (optionen.limit !== undefined && (!Number.isInteger(optionen.limit) || optionen.limit < 1 || optionen.limit > 200)) {
+async function listPartnerCustomers(transport, options = {}) {
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 200)) {
         throw new errors_js_1.KasseneckValidationError('listPartnerCustomers', 'limit muss zwischen 1 und 200 liegen', 'request');
     }
-    const daten = objekt(await rufen('listPartnerCustomers', {
-        status: optionen.status,
-        limit: optionen.limit,
-        cursor: optionen.cursor,
+    const daten = objekt(await transport('listPartnerCustomers', {
+        status: options.status,
+        limit: options.limit,
+        cursor: options.cursor,
     }));
     return {
         customers: liste(daten['customers']).map(kundenZeile),
@@ -247,9 +248,9 @@ function avvStand(wert) {
     return { ...v, mode: textOderNull(wert['mode']) };
 }
 /** Ein Betrieb mit allem, was der Partner ueber ihn sehen darf — nie Geheimnisse. */
-async function getPartnerCustomer(rufen, customerId) {
+async function getPartnerCustomer(transport, customerId) {
     const id = pflicht(customerId, 'getPartnerCustomer', 'customerId');
-    const daten = objekt(await rufen('getPartnerCustomer', { customerId: id }));
+    const daten = objekt(await transport('getPartnerCustomer', { customerId: id }));
     const k = verlangt(daten['customer'], 'getPartnerCustomer', 'customer');
     const fon = objekt(k['fon']);
     const zugang = k['access'];
@@ -294,16 +295,16 @@ async function getPartnerCustomer(rufen, customerId) {
  * einem ganzen ausgefuellten Formular auf. Die Antwort sagt NUR ja oder nein —
  * nie, wem die Adresse gehoert.
  */
-async function checkPartnerCustomerEmail(rufen, email) {
+async function checkPartnerCustomerEmail(transport, email) {
     const adresse = typeof email === 'string' ? email.trim() : '';
     if (!adresse)
         throw new errors_js_1.KasseneckValidationError('checkPartnerCustomerEmail', 'email fehlt', 'request');
-    const daten = objekt(await rufen('checkPartnerCustomerEmail', { email: adresse }));
+    const daten = objekt(await transport('checkPartnerCustomerEmail', { email: adresse }));
     return daten['available'] === true;
 }
-async function sendPartnerCustomerFonLink(rufen, customerId) {
+async function sendPartnerCustomerFonLink(transport, customerId) {
     const id = pflicht(customerId, 'sendPartnerCustomerFonLink', 'customerId');
-    const daten = objekt(await rufen('sendPartnerCustomerFonLink', { customerId: id }));
+    const daten = objekt(await transport('sendPartnerCustomerFonLink', { customerId: id }));
     return {
         customerId: text(daten['customerId'], id),
         sentTo: text(daten['sentTo']),
@@ -360,12 +361,12 @@ function antrag(eintrag) {
  * Abschluss kommt als Ereignis `signature.ready`, nicht als Antwort auf diesen
  * Aufruf.
  */
-async function requestCustomerSignature(rufen, customerId, optionen = {}) {
+async function requestCustomerSignature(transport, customerId, options = {}) {
     const id = pflicht(customerId, 'requestCustomerSignature', 'customerId');
-    const daten = objekt(await rufen('requestCustomerSignature', {
+    const daten = objekt(await transport('requestCustomerSignature', {
         customerId: id,
-        kind: optionen.kind,
-        additional: optionen.additional,
+        kind: options.kind,
+        additional: options.additional,
     }));
     return {
         request: antrag(verlangt(daten['request'], 'requestCustomerSignature', 'request')),
@@ -399,9 +400,9 @@ function signaturEinzeln(eintrag) {
     };
 }
 /** Stand der Signatur eines Betriebs samt aller Signaturen, Antraege und des FON-Zugangs. */
-async function getCustomerSignatureStatus(rufen, customerId) {
+async function getCustomerSignatureStatus(transport, customerId) {
     const id = pflicht(customerId, 'getCustomerSignatureStatus', 'customerId');
-    const daten = objekt(await rufen('getCustomerSignatureStatus', { customerId: id }));
+    const daten = objekt(await transport('getCustomerSignatureStatus', { customerId: id }));
     const signatur = objekt(daten['signature']);
     const fon = objekt(daten['fon']);
     return {
@@ -461,12 +462,12 @@ function kasse(eintrag) {
  * Hoechstens 20 Kassen je Betrieb (`cashregister_limit`); ohne gebuchtes Modul
  * `module_inactive`.
  */
-async function createCustomerCashregister(rufen, optionen) {
-    const id = pflicht(optionen?.customerId, 'createCustomerCashregister', 'customerId');
-    const daten = objekt(await rufen('createCustomerCashregister', {
+async function createCustomerCashregister(transport, options) {
+    const id = pflicht(options?.customerId, 'createCustomerCashregister', 'customerId');
+    const daten = objekt(await transport('createCustomerCashregister', {
         customerId: id,
-        automatic: optionen.automatic,
-        signatureRequestId: optionen.signatureRequestId,
+        automatic: options.automatic,
+        signatureRequestId: options.signatureRequestId,
     }));
     const ib = objekt(daten['activation']);
     return {
@@ -490,19 +491,19 @@ async function createCustomerCashregister(rufen, optionen) {
  * veraendernde Aufruf dieses Clients, der ohne Idempotenzschluessel gefahrlos
  * wiederholbar ist — weil der Server ihn so gebaut hat.
  */
-async function activateCashregister(rufen, customerId, cashregisterId) {
+async function activateCashregister(transport, customerId, cashregisterId) {
     const kunde = pflicht(customerId, 'activateCashregister', 'customerId');
     const kassenId = pflicht(cashregisterId, 'activateCashregister', 'cashregisterId');
-    const daten = objekt(await rufen('activateCashregister', { customerId: kunde, cashregisterId: kassenId }));
+    const daten = objekt(await transport('activateCashregister', { customerId: kunde, cashregisterId: kassenId }));
     return {
         cashregister: kasse(verlangt(daten['cashregister'], 'activateCashregister', 'cashregister')),
         unchanged: jaNein(daten['unchanged']),
     };
 }
 /** Die Kassen eines Betriebs samt Stand der Inbetriebnahme — **nie** Token. */
-async function listCustomerCashregisters(rufen, customerId) {
+async function listCustomerCashregisters(transport, customerId) {
     const id = pflicht(customerId, 'listCustomerCashregisters', 'customerId');
-    const daten = objekt(await rufen('listCustomerCashregisters', { customerId: id }));
+    const daten = objekt(await transport('listCustomerCashregisters', { customerId: id }));
     return {
         customerId: text(daten['customerId'], id),
         cashregisters: liste(daten['cashregisters']).map(kasse),
@@ -525,9 +526,9 @@ async function listCustomerCashregisters(rufen, customerId) {
  * Zeichenketten-Umwandlung zeigen eine Maske, heraus kommt man nur ueber
  * `.reveal()`.
  */
-async function getCustomerCredentials(rufen, customerId) {
+async function getCustomerCredentials(transport, customerId) {
     const id = pflicht(customerId, 'getCustomerCredentials', 'customerId');
-    const daten = objekt(await rufen('getCustomerCredentials', { customerId: id }));
+    const daten = objekt(await transport('getCustomerCredentials', { customerId: id }));
     return {
         customerId: text(daten['customerId'], id),
         companyName: text(daten['companyName']),
@@ -545,3 +546,43 @@ async function getCustomerCredentials(rufen, customerId) {
         note: text(daten['note']),
     };
 }
+// ---------------------------------------------------------------------------
+// Vertraege
+// ---------------------------------------------------------------------------
+/**
+ * Meldet eine Zustimmung des Betriebs, die der Partner **in Vollmacht**
+ * eingeholt hat (Endpunkt `reportCustomerContract`, unter `/v1`
+ * `reportCustomerVertrag`). Braucht die Berechtigung `customers:write`.
+ *
+ * Vor dem Senden prueft dieser Client nur, dass jede Pflichtangabe da ist und
+ * `acceptedAt` eine Zahl ist. Ob die Art erlaubt ist (`kind_not_allowed`), die
+ * Fassung gilt (`unknown_version`, `no_version`) und der Text derselbe ist
+ * (`text_changed`), entscheidet der Server. Eine schon bestaetigte Fassung
+ * kommt als `already_accepted` mit `data.contractId`; das ist kein Schaden,
+ * sondern die Bestaetigung, dass es sie gibt.
+ */
+async function reportCustomerContract(transport, options) {
+    const vorgang = 'reportCustomerContract';
+    const o = objekt(options);
+    const customerId = pflicht(o['customerId'], vorgang, 'customerId');
+    const kind = pflicht(o['kind'], vorgang, 'kind');
+    const version = pflicht(o['version'], vorgang, 'version');
+    const textHash = pflicht(o['textHash'], vorgang, 'textHash');
+    const name = pflicht(o['name'], vorgang, 'name');
+    const signerRole = pflicht(o['signerRole'], vorgang, 'signerRole');
+    const acceptedAt = o['acceptedAt'];
+    if (acceptedAt !== undefined && (typeof acceptedAt !== 'number' || !Number.isFinite(acceptedAt))) {
+        throw new errors_js_1.KasseneckValidationError(vorgang, 'acceptedAt muss eine Zahl sein (Unix-Millisekunden)', 'request');
+    }
+    const daten = objekt(await transport(vorgang, { customerId, kind, version, textHash, name, signerRole, acceptedAt }));
+    const contractId = daten['contractId'];
+    if (typeof contractId !== 'string' || !contractId) {
+        throw new errors_js_1.KasseneckValidationError(vorgang, 'Antwort enthaelt keine contractId', 'response');
+    }
+    return {
+        contractId,
+        confirmedAt: zahlOderNull(daten['confirmedAt']),
+        kind: text(daten['kind'], kind),
+        version: text(daten['version'], version),
+    };
+}

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

@@ -17,13 +17,13 @@
  * im Backend (Abzug aus `partner-core.FEHLER_KATALOG`); ein Code, den nur eine
  * Seite kennt, ist fuer einen Aufrufer nicht von „gibt es nicht" zu
  * unterscheiden. Deshalb stehen hier BEIDE Flaechen: die der Schnittstelle
- * ([PARTNER_FEHLER_CODES]) und die des Partner-Portals
- * ([PARTNER_PORTAL_FEHLER_CODES]).
+ * ([PARTNER_ERROR_CODES]) und die des Partner-Portals
+ * ([PARTNER_PORTAL_ERROR_CODES]).
  *
  * **Seit 0.29.0 englisch, wie der Rest von `/v3`.** Dieser Client spricht seit
  * 0.28.0 ausschliesslich `/v3` (`PARTNER_BASE_URL`): die paar deutschen Codes,
  * die der Server bis dahin noch roh durchreichte, kommen jetzt genauso englisch
- * an wie alle anderen. [PARTNER_FEHLER_CODES] fuehrt deshalb ausnahmslos die
+ * an wie alle anderen. [PARTNER_ERROR_CODES] fuehrt deshalb ausnahmslos die
  * `/v3`-Schreibweise aus `fehlercodes.json`s `v3`-Zuordnung (deutsch -> englisch);
  * ein Aufrufer bekommt vom Server nie mehr die deutsche Form.
  *
@@ -36,16 +36,24 @@
  *
  * **Die Vertrags-Codes (`kind_not_allowed`, `mode_not_allowed`,
  * `power_of_attorney_missing`, `not_found`, `no_version`,
- * `unknown_version`, `text_changed`, `already_accepted`) stehen hier, obwohl
- * dieses Paket `reportCustomerContract` nicht anbietet.** Der Katalog des
- * Backends fuehrt sie mit `flaeche: 'api'`/`'beide'`, dieselbe Regel wie bei
- * den Portal-Codes oben: vollstaendig heisst vollstaendig, auch fuer einen
- * Endpunkt, den (noch) kein Aufruf dieses Clients ausloest. Ein Server-Update,
- * das den Endpunkt ergaenzt, bräuchte dann keinen zweiten Fehlerkatalog-Umbau.
- * `not_required` fehlt bewusst: derselbe gemeinsame Server-Zweig wie die
- * anderen sechs, aber ueber die Partner-API nicht erreichbar (der Server hat
- * ihn aus `FEHLER_KATALOG` entfernt, siehe `partner-core.js` im Backend).
+ * `unknown_version`, `text_changed`, `already_accepted`)** kommen aus
+ * `reportCustomerContract` (seit 1.0 in diesem Paket). `not_required` fehlt
+ * bewusst: derselbe gemeinsame Server-Zweig, aber ueber die Partner-API nicht
+ * erreichbar (der Server hat ihn aus `FEHLER_KATALOG` entfernt, siehe
+ * `partner-core.js` im Backend).
+ *
+ * **Seit 1.0 ist [PARTNER_ERROR_CODES] genau `errorCodes.partner` des
+ * Vertrags-Exports** (`fixtures/v3/v3-vokabular.json`); ein Test haelt beide
+ * gleich. Dazu kommen die Anmelde- und Anfragecodes, die `/v3` seit
+ * 2026-09-27 auch an Partner-Aufrufen setzt ([PARTNER_REQUEST_ERROR_CODES]).
+ *
+ * **Ein unbekannter Code ist kein Fehler dieses Pakets.** Der Server darf
+ * Fehlern, die heute keinen Code tragen, spaeter einen geben (vorhandene Codes
+ * aendern sich nie). [partnerErrorAdvice] antwortet darauf mit einem
+ * Rueckfallsatz statt `undefined`, die Erkenner mit `false`; geworfen wird
+ * nie.
  */
+import { KasseneckApiError } from '../client/errors.js';
 /**
  * Alle Codes, die die **Schnittstelle** kennt. Als Liste und nicht nur als
  * Typ, damit ein Aufrufer sie zur Laufzeit durchgehen kann (Katalogseite,
@@ -53,7 +61,7 @@
  *
  * Reihenfolge und Bestand wie im Abzug des Backends.
  */
-export declare const PARTNER_FEHLER_CODES: readonly ["validation", "rate_limited", "app_not_found", "app_not_accepted", "live_not_allowed", "customer_exists", "customer_conflict", "customer_limit", "access_not_allowed", "email_taken", "no_email", "tax_number_missing", "fon_missing", "signature_pending", "signature_missing", "signature_unknown", "signature_ambiguous", "signature_not_ready", "signature_limit", "signature_failed", "module_inactive", "cashregister_limit", "cashregister_not_found", "contracts_pending", "kind_not_allowed", "mode_not_allowed", "power_of_attorney_missing", "not_found", "no_version", "unknown_version", "text_changed", "already_accepted", "activation_failed", "webhook_limit", "webhook_inactive", "event_not_subscribed"];
+export declare const PARTNER_ERROR_CODES: readonly ["validation", "rate_limited", "app_not_found", "app_not_accepted", "live_not_allowed", "customer_exists", "customer_conflict", "customer_limit", "access_not_allowed", "email_taken", "no_email", "tax_number_missing", "fon_missing", "signature_pending", "signature_missing", "signature_unknown", "signature_ambiguous", "signature_not_ready", "signature_limit", "signature_failed", "module_inactive", "cashregister_limit", "cashregister_not_found", "contracts_pending", "kind_not_allowed", "mode_not_allowed", "power_of_attorney_missing", "not_found", "no_version", "unknown_version", "text_changed", "already_accepted", "activation_failed", "webhook_limit", "webhook_inactive", "event_not_subscribed"];
 /**
  * Die Codes, die nur im **Partner-Portal** entstehen — beim Pflegen der App,
  * der Schluessel, der Mitglieder und der Signaturkarten.
@@ -63,25 +71,47 @@ export declare const PARTNER_FEHLER_CODES: readonly ["validation", "rate_limited
  * Wer eine Katalogseite baut oder eine fremde Antwort einsortiert, findet
  * damit jeden Code des Backends wieder.
  */
-export declare const PARTNER_PORTAL_FEHLER_CODES: readonly ["app_locked", "version_locked", "invalid_transition", "no_accepted_app", "consent", "key_limit", "last_owner", "auth_user_exists", "card_missing", "card_duplicate", "card_not_verified", "already_assigned"];
-export type PartnerFehlerCode = typeof PARTNER_FEHLER_CODES[number];
-export type PartnerPortalFehlerCode = typeof PARTNER_PORTAL_FEHLER_CODES[number];
-/** Ein Code aus einer der beiden Flaechen. */
-export type PartnerCode = PartnerFehlerCode | PartnerPortalFehlerCode;
-export declare function istPartnerFehlerCode(wert: unknown): wert is PartnerFehlerCode;
-export declare function istPartnerPortalFehlerCode(wert: unknown): wert is PartnerPortalFehlerCode;
+export declare const PARTNER_PORTAL_ERROR_CODES: readonly ["app_locked", "version_locked", "invalid_transition", "no_accepted_app", "consent", "key_limit", "last_owner", "auth_user_exists", "card_missing", "card_duplicate", "card_not_verified", "already_assigned"];
+/**
+ * Codes der Anmeldung und der Anfragepruefung, die `/v3` auch an
+ * Partner-Aufrufen setzt (Partner-Doku, Abschnitt Fehlercodes; im
+ * Vertrags-Export unter `errorCodes.auth`). Unter `/v1` kamen diese Fehler
+ * ohne Code. `validation` und `rate_limited` stehen schon in
+ * [PARTNER_ERROR_CODES]. Dahinter die Codes des Rands (`errorCodes.edge`,
+ * soweit nicht schon im Katalog; `not_found` und `validation` stehen dort)
+ * und `route_missing`, den das Paket selbst vergibt.
+ */
+export declare const PARTNER_REQUEST_ERROR_CODES: readonly ["method_not_allowed", "unauthorized", "partner_locked", "scope_missing", "internal_translation_error", "dialect_mismatch", "response_translation_failed", "route_missing"];
+export type PartnerErrorCode = typeof PARTNER_ERROR_CODES[number];
+export type PartnerPortalErrorCode = typeof PARTNER_PORTAL_ERROR_CODES[number];
+export type PartnerRequestErrorCode = typeof PARTNER_REQUEST_ERROR_CODES[number];
+/** Ein Code aus einer der Flaechen, die dieses Paket kennt. */
+export type PartnerCode = PartnerErrorCode | PartnerPortalErrorCode | PartnerRequestErrorCode;
 /**
- * Der Handlungssatz zu einem Code — aus beiden Flaechen. `undefined` fuer
- * einen Code, den dieses Paket nicht kennt; ein erfundener Satz waere
- * schlimmer als keiner.
+ * `true` fuer einen Code, den ein Partner-Aufruf liefern kann: aus
+ * [PARTNER_ERROR_CODES] (Katalog) oder [PARTNER_REQUEST_ERROR_CODES]
+ * (Anmeldung, Rand, Paket). Alles andere, auch Unsinn, ist `false`.
  */
-export declare function partnerFehlerRat(code: string): string | undefined;
+export declare function isPartnerErrorCode(value: unknown): value is PartnerErrorCode | PartnerRequestErrorCode;
+/** `true` fuer einen Code aus [PARTNER_PORTAL_ERROR_CODES]; alles andere ist `false`. */
+export declare function isPartnerPortalErrorCode(value: unknown): value is PartnerPortalErrorCode;
+/**
+ * Der Handlungssatz zu einem Code, aus allen Flaechen. Fuer einen Code, den
+ * dieses Paket nicht kennt (oder fuer Unsinn), kommt ein Rueckfallsatz; die
+ * Funktion wirft nie.
+ */
+export declare function partnerErrorAdvice(code: string): string;
 /** Der Fehlercode eines geworfenen Fehlers — `undefined`, wenn es keiner der unseren ist. */
-export declare function partnerFehlerCode(error: unknown): string | undefined;
-/** Kurzform fuer `catch (e) { if (istPartnerFehler(e, 'signature_missing')) … }`. */
-export declare function istPartnerFehler(error: unknown, code: PartnerCode): boolean;
+export declare function partnerErrorCode(error: unknown): string | undefined;
+/**
+ * Kurzform fuer `catch (e) { if (isPartnerError(e, 'signature_missing')) … }`.
+ * Mit `code` nimmt sie auch Codes, die dieses Paket (noch) nicht kennt.
+ * Ohne `code`: traegt der Fehler einen Code, den ein Partner-Aufruf liefern
+ * kann ([isPartnerErrorCode])?
+ */
+export declare function isPartnerError(error: unknown, code?: PartnerCode | (string & {})): error is KasseneckApiError;
 /** Ein Feldfehler aus `data.errors[]` einer `validation`-Antwort. */
-export interface PartnerFeldFehler {
+export interface PartnerFieldError {
     /**
      * Der Feldpfad, so wie er im gesendeten Betrieb steht — verschachtelt und je
      * Kontakt: `address.zip`, `taxDetails.taxNumber`, `contacts.0.email`.
@@ -90,9 +120,9 @@ export interface PartnerFeldFehler {
     message: string;
 }
 /** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
-export declare function partnerFeldFehler(error: unknown): PartnerFeldFehler[];
+export declare function partnerFieldErrors(error: unknown): PartnerFieldError[];
 /**
  * Wie lange `rate_limited` noch gilt, in Sekunden. `undefined`, wenn der
  * Fehler kein `rate_limited` ist oder das Backend keine Angabe macht.
  */
-export declare function partnerWartezeitSek(error: unknown): number | undefined;
+export declare function partnerRetryAfterSec(error: unknown): number | undefined;

package/dist/cjs/partner/fehler.js

@@ -18,13 +18,13 @@
  * im Backend (Abzug aus `partner-core.FEHLER_KATALOG`); ein Code, den nur eine
  * Seite kennt, ist fuer einen Aufrufer nicht von „gibt es nicht" zu
  * unterscheiden. Deshalb stehen hier BEIDE Flaechen: die der Schnittstelle
- * ([PARTNER_FEHLER_CODES]) und die des Partner-Portals
- * ([PARTNER_PORTAL_FEHLER_CODES]).
+ * ([PARTNER_ERROR_CODES]) und die des Partner-Portals
+ * ([PARTNER_PORTAL_ERROR_CODES]).
  *
  * **Seit 0.29.0 englisch, wie der Rest von `/v3`.** Dieser Client spricht seit
  * 0.28.0 ausschliesslich `/v3` (`PARTNER_BASE_URL`): die paar deutschen Codes,
  * die der Server bis dahin noch roh durchreichte, kommen jetzt genauso englisch
- * an wie alle anderen. [PARTNER_FEHLER_CODES] fuehrt deshalb ausnahmslos die
+ * an wie alle anderen. [PARTNER_ERROR_CODES] fuehrt deshalb ausnahmslos die
  * `/v3`-Schreibweise aus `fehlercodes.json`s `v3`-Zuordnung (deutsch -> englisch);
  * ein Aufrufer bekommt vom Server nie mehr die deutsche Form.
  *
@@ -37,25 +37,32 @@
  *
  * **Die Vertrags-Codes (`kind_not_allowed`, `mode_not_allowed`,
  * `power_of_attorney_missing`, `not_found`, `no_version`,
- * `unknown_version`, `text_changed`, `already_accepted`) stehen hier, obwohl
- * dieses Paket `reportCustomerContract` nicht anbietet.** Der Katalog des
- * Backends fuehrt sie mit `flaeche: 'api'`/`'beide'`, dieselbe Regel wie bei
- * den Portal-Codes oben: vollstaendig heisst vollstaendig, auch fuer einen
- * Endpunkt, den (noch) kein Aufruf dieses Clients ausloest. Ein Server-Update,
- * das den Endpunkt ergaenzt, bräuchte dann keinen zweiten Fehlerkatalog-Umbau.
- * `not_required` fehlt bewusst: derselbe gemeinsame Server-Zweig wie die
- * anderen sechs, aber ueber die Partner-API nicht erreichbar (der Server hat
- * ihn aus `FEHLER_KATALOG` entfernt, siehe `partner-core.js` im Backend).
+ * `unknown_version`, `text_changed`, `already_accepted`)** kommen aus
+ * `reportCustomerContract` (seit 1.0 in diesem Paket). `not_required` fehlt
+ * bewusst: derselbe gemeinsame Server-Zweig, aber ueber die Partner-API nicht
+ * erreichbar (der Server hat ihn aus `FEHLER_KATALOG` entfernt, siehe
+ * `partner-core.js` im Backend).
+ *
+ * **Seit 1.0 ist [PARTNER_ERROR_CODES] genau `errorCodes.partner` des
+ * Vertrags-Exports** (`fixtures/v3/v3-vokabular.json`); ein Test haelt beide
+ * gleich. Dazu kommen die Anmelde- und Anfragecodes, die `/v3` seit
+ * 2026-09-27 auch an Partner-Aufrufen setzt ([PARTNER_REQUEST_ERROR_CODES]).
+ *
+ * **Ein unbekannter Code ist kein Fehler dieses Pakets.** Der Server darf
+ * Fehlern, die heute keinen Code tragen, spaeter einen geben (vorhandene Codes
+ * aendern sich nie). [partnerErrorAdvice] antwortet darauf mit einem
+ * Rueckfallsatz statt `undefined`, die Erkenner mit `false`; geworfen wird
+ * nie.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PARTNER_PORTAL_FEHLER_CODES = exports.PARTNER_FEHLER_CODES = void 0;
-exports.istPartnerFehlerCode = istPartnerFehlerCode;
-exports.istPartnerPortalFehlerCode = istPartnerPortalFehlerCode;
-exports.partnerFehlerRat = partnerFehlerRat;
-exports.partnerFehlerCode = partnerFehlerCode;
-exports.istPartnerFehler = istPartnerFehler;
-exports.partnerFeldFehler = partnerFeldFehler;
-exports.partnerWartezeitSek = partnerWartezeitSek;
+exports.PARTNER_REQUEST_ERROR_CODES = exports.PARTNER_PORTAL_ERROR_CODES = exports.PARTNER_ERROR_CODES = void 0;
+exports.isPartnerErrorCode = isPartnerErrorCode;
+exports.isPartnerPortalErrorCode = isPartnerPortalErrorCode;
+exports.partnerErrorAdvice = partnerErrorAdvice;
+exports.partnerErrorCode = partnerErrorCode;
+exports.isPartnerError = isPartnerError;
+exports.partnerFieldErrors = partnerFieldErrors;
+exports.partnerRetryAfterSec = partnerRetryAfterSec;
 const errors_js_1 = require("../client/errors.js");
 /**
  * Alle Codes, die die **Schnittstelle** kennt. Als Liste und nicht nur als
@@ -64,7 +71,7 @@ const errors_js_1 = require("../client/errors.js");
  *
  * Reihenfolge und Bestand wie im Abzug des Backends.
  */
-exports.PARTNER_FEHLER_CODES = [
+exports.PARTNER_ERROR_CODES = [
     // Eingabe, Konto und Takt
     'validation',
     'rate_limited',
@@ -94,8 +101,7 @@ exports.PARTNER_FEHLER_CODES = [
     'cashregister_limit',
     'cashregister_not_found',
     'contracts_pending',
-    // Vertraege (reportCustomerContract: dieses Paket bietet den Endpunkt nicht
-    // an, der Katalog fuehrt die Codes trotzdem vollstaendig, siehe oben)
+    // Vertraege (reportCustomerContract)
     'kind_not_allowed',
     'mode_not_allowed',
     'power_of_attorney_missing',
@@ -119,7 +125,7 @@ exports.PARTNER_FEHLER_CODES = [
  * Wer eine Katalogseite baut oder eine fremde Antwort einsortiert, findet
  * damit jeden Code des Backends wieder.
  */
-exports.PARTNER_PORTAL_FEHLER_CODES = [
+exports.PARTNER_PORTAL_ERROR_CODES = [
     'app_locked',
     'version_locked',
     'invalid_transition',
@@ -133,11 +139,40 @@ exports.PARTNER_PORTAL_FEHLER_CODES = [
     'card_not_verified',
     'already_assigned',
 ];
-function istPartnerFehlerCode(wert) {
-    return typeof wert === 'string' && exports.PARTNER_FEHLER_CODES.includes(wert);
+/**
+ * Codes der Anmeldung und der Anfragepruefung, die `/v3` auch an
+ * Partner-Aufrufen setzt (Partner-Doku, Abschnitt Fehlercodes; im
+ * Vertrags-Export unter `errorCodes.auth`). Unter `/v1` kamen diese Fehler
+ * ohne Code. `validation` und `rate_limited` stehen schon in
+ * [PARTNER_ERROR_CODES]. Dahinter die Codes des Rands (`errorCodes.edge`,
+ * soweit nicht schon im Katalog; `not_found` und `validation` stehen dort)
+ * und `route_missing`, den das Paket selbst vergibt.
+ */
+exports.PARTNER_REQUEST_ERROR_CODES = [
+    'method_not_allowed',
+    'unauthorized',
+    'partner_locked',
+    'scope_missing',
+    // Rand (errorCodes.edge, soweit nicht im Katalog) und Code des Pakets
+    'internal_translation_error',
+    'dialect_mismatch',
+    'response_translation_failed',
+    'route_missing',
+];
+function enthaelt(liste, wert) {
+    return typeof wert === 'string' && liste.includes(wert);
+}
+/**
+ * `true` fuer einen Code, den ein Partner-Aufruf liefern kann: aus
+ * [PARTNER_ERROR_CODES] (Katalog) oder [PARTNER_REQUEST_ERROR_CODES]
+ * (Anmeldung, Rand, Paket). Alles andere, auch Unsinn, ist `false`.
+ */
+function isPartnerErrorCode(value) {
+    return enthaelt(exports.PARTNER_ERROR_CODES, value) || enthaelt(exports.PARTNER_REQUEST_ERROR_CODES, value);
 }
-function istPartnerPortalFehlerCode(wert) {
-    return typeof wert === 'string' && exports.PARTNER_PORTAL_FEHLER_CODES.includes(wert);
+/** `true` fuer einen Code aus [PARTNER_PORTAL_ERROR_CODES]; alles andere ist `false`. */
+function isPartnerPortalErrorCode(value) {
+    return enthaelt(exports.PARTNER_PORTAL_ERROR_CODES, value);
 }
 /**
  * Was der Aufrufer tun muss. Ein Satz je Code, in der zweiten Person — nicht
@@ -174,10 +209,7 @@ const RAT = {
     cashregister_not_found: 'Diese cashregisterId gibt es bei diesem Betrieb nicht.',
     contracts_pending: 'Nur live: der Betrieb hat Auftragsverarbeitungs- und Nutzungsvertrag noch nicht bestaetigt. An der Kasse aendert sich nichts. Den Betrieb ueber den Einrichtungs-Link bestaetigen lassen (sendPartnerCustomerFonLink, Stand in avv/terms von getPartnerCustomer), danach activateCashregister erneut.',
     // -- Vertraege (reportCustomerContract) ------------------------------------
-    // Dieser Client bietet den Endpunkt (noch) nicht an; die Codes stehen hier
-    // nur fuer die Katalogseite und fuer einen Aufrufer, der die rohe Antwort
-    // selbst auswertet (siehe Kopfkommentar der Datei).
-    kind_not_allowed: 'reportCustomerContract mit einer anderen Art als "avv". Der Vollmachtsweg nimmt nur den Auftragsverarbeitungsvertrag entgegen. Dieser Client bietet den Endpunkt nicht an.',
+    kind_not_allowed: 'reportCustomerContract mit einer anderen Art als "avv". Der Vollmachtsweg nimmt nur den Auftragsverarbeitungsvertrag entgegen; den Nutzungsvertrag bestaetigt der Betrieb selbst ueber den Einrichtungs-Link.',
     mode_not_allowed: 'Der Vollmachtsweg ist fuer dieses Partner-Konto nicht freigeschaltet. Kasseneck fragen (hello@kasseneck.at).',
     power_of_attorney_missing: 'Der Partnervertrag mit dem Vollmachts-Kapitel ist noch nicht bestaetigt. Erst danach nimmt der Vollmachtsweg Meldungen entgegen.',
     not_found: 'Die genannte customerId gehoert nicht zu diesem Partner-Konto oder existiert nicht. listPartnerCustomers nennt die eigenen.',
@@ -189,6 +221,15 @@ const RAT = {
     webhook_limit: 'Hoechstens 10 Webhook-Endpunkte je Partner. Einen ungenutzten loeschen.',
     webhook_inactive: 'Der Webhook steht auf active:false. Zuerst aktivieren, dann erneut proben.',
     event_not_subscribed: 'Der Endpunkt abonniert dieses Ereignis nicht — auch eine Probe bekommt nur, was in seiner events-Liste steht. events erweitern und erneut versuchen.',
+    // -- Anmeldung und Anfrage -----------------------------------------------
+    method_not_allowed: 'Die Anfrage war kein POST. Jeder Aufruf der Partner-API geht als POST mit JSON-Rumpf.',
+    unauthorized: 'Kein, ein ungueltiger oder ein widerrufener Partner-Schluessel. Den Schluessel im Partner-Portal pruefen bzw. einen neuen erzeugen.',
+    partner_locked: 'Das Partner-Konto ist gesperrt. Kasseneck fragen (hello@kasseneck.at).',
+    scope_missing: 'Dem Schluessel fehlt eine Berechtigung, die dieser Aufruf braucht (data.scope). Einen Schluessel mit dieser Berechtigung erzeugen.',
+    internal_translation_error: 'Der Server konnte die Anfrage nicht in seine innere Form uebersetzen. Nichts wurde ausgefuehrt; hello@kasseneck.at mit Aufruf und Zeitpunkt melden.',
+    dialect_mismatch: 'Die Antwort kam nicht vom /v3-Rand (Kennzeichen fehlt), der Ausgang ist unklar. Nicht blind wiederholen: den Stand mit getPartnerCustomer bzw. listCustomerCashregisters nachlesen.',
+    response_translation_failed: 'Der Server konnte seine Antwort nicht uebersetzen. Mit details.handled === false lief nichts; sonst kann der Aufruf ausgefuehrt sein, dann den Stand nachlesen statt wiederholen.',
+    route_missing: 'Statt des Backends kam eine HTML-Seite: die Basisadresse stimmt nicht (PARTNER_BASE_URL bzw. eigener Proxy). Der Aufruf kam nie an.',
     // -- Partner-Portal -------------------------------------------------------
     app_locked: 'Name, Verteilungen und Kontakt einer App sind fest, sobald eine Version geprueft wird. Aenderungen daran gehen ueber Kasseneck.',
     version_locked: 'Diese App-Version wird geprueft oder ist abgenommen. Fuer Aenderungen eine neue Version anlegen.',
@@ -204,23 +245,38 @@ const RAT = {
     already_assigned: 'Fuer diesen Antrag sind bereits Kartendaten eingetragen; ein zweiter Satz ueberschreibt nichts.',
 };
 /**
- * Der Handlungssatz zu einem Code — aus beiden Flaechen. `undefined` fuer
- * einen Code, den dieses Paket nicht kennt; ein erfundener Satz waere
- * schlimmer als keiner.
+ * Der Rueckfall fuer einen Code, den dieses Paket nicht kennt: kein geratener
+ * Handgriff, sondern der Hinweis, wo die Auskunft steht.
+ */
+const RUECKFALL = 'Dieser Code ist diesem Paket nicht bekannt (neuer als diese Fassung). Die Meldung des Servers (message) sagt, was geschah; im Zweifel wie einen Fehler ohne Code behandeln und hello@kasseneck.at fragen.';
+/**
+ * Der Handlungssatz zu einem Code, aus allen Flaechen. Fuer einen Code, den
+ * dieses Paket nicht kennt (oder fuer Unsinn), kommt ein Rueckfallsatz; die
+ * Funktion wirft nie.
  */
-function partnerFehlerRat(code) {
+function partnerErrorAdvice(code) {
+    if (typeof code !== 'string' || !Object.prototype.hasOwnProperty.call(RAT, code))
+        return RUECKFALL;
     return RAT[code];
 }
 /** Der Fehlercode eines geworfenen Fehlers — `undefined`, wenn es keiner der unseren ist. */
-function partnerFehlerCode(error) {
+function partnerErrorCode(error) {
     return error instanceof errors_js_1.KasseneckApiError ? error.code : undefined;
 }
-/** Kurzform fuer `catch (e) { if (istPartnerFehler(e, 'signature_missing')) … }`. */
-function istPartnerFehler(error, code) {
-    return partnerFehlerCode(error) === code;
+/**
+ * Kurzform fuer `catch (e) { if (isPartnerError(e, 'signature_missing')) … }`.
+ * Mit `code` nimmt sie auch Codes, die dieses Paket (noch) nicht kennt.
+ * Ohne `code`: traegt der Fehler einen Code, den ein Partner-Aufruf liefern
+ * kann ([isPartnerErrorCode])?
+ */
+function isPartnerError(error, code) {
+    const gefunden = partnerErrorCode(error);
+    if (gefunden === undefined)
+        return false;
+    return code === undefined ? isPartnerErrorCode(gefunden) : gefunden === code;
 }
 /** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
-function partnerFeldFehler(error) {
+function partnerFieldErrors(error) {
     if (!(error instanceof errors_js_1.KasseneckApiError))
         return [];
     const roh = error.details['errors'];
@@ -240,8 +296,8 @@ function partnerFeldFehler(error) {
  * Wie lange `rate_limited` noch gilt, in Sekunden. `undefined`, wenn der
  * Fehler kein `rate_limited` ist oder das Backend keine Angabe macht.
  */
-function partnerWartezeitSek(error) {
-    if (partnerFehlerCode(error) !== 'rate_limited')
+function partnerRetryAfterSec(error) {
+    if (partnerErrorCode(error) !== 'rate_limited')
         return undefined;
     const wert = error.details['retryAfterSec'];
     return typeof wert === 'number' && Number.isFinite(wert) && wert >= 0 ? wert : undefined;