@kreiseck/kasseneck-api 0.30.0 → 1.0.0-rc.1

package/dist/esm/partner/endpunkte.js

@@ -11,7 +11,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
@@ -86,8 +86,8 @@ function pflicht(wert, vorgang, feld) {
  * Der guenstigste Selbsttest beim Hochfahren: er beweist Schluessel, Umgebung
  * und Rechte in einem Aufruf.
  */
-export async function getPartnerInfo(rufen) {
-    const daten = objekt(await rufen('getPartnerInfo'));
+export async function getPartnerInfo(transport) {
+    const daten = objekt(await transport('getPartnerInfo'));
     const partner = verlangt(daten['partner'], 'getPartnerInfo', 'partner');
     const key = objekt(daten['key']);
     return {
@@ -145,18 +145,18 @@ export async function getPartnerInfo(rufen) {
  * — auch dann, wenn der Rumpf inzwischen abweicht. Die eigene Kundennummer ist
  * der natuerliche Wert dafuer.
  */
-export async function createPartnerCustomer(rufen, optionen) {
-    const appId = pflicht(optionen?.appId, 'createPartnerCustomer', 'appId');
-    const betrieb = optionen?.business;
+export async function createPartnerCustomer(transport, options) {
+    const appId = pflicht(options?.appId, 'createPartnerCustomer', 'appId');
+    const betrieb = options?.business;
     if (betrieb === null || typeof betrieb !== 'object') {
         throw new 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) {
@@ -176,14 +176,14 @@ export async function createPartnerCustomer(rufen, optionen) {
     };
 }
 /** Betriebe dieses Partners, seitenweise. `cursor` aus der Antwort setzt fort. */
-export async function listPartnerCustomers(rufen, optionen = {}) {
-    if (optionen.limit !== undefined && (!Number.isInteger(optionen.limit) || optionen.limit < 1 || optionen.limit > 200)) {
+export async function listPartnerCustomers(transport, options = {}) {
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 200)) {
         throw new 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),
@@ -233,9 +233,9 @@ function avvStand(wert) {
     return { ...v, mode: textOderNull(wert['mode']) };
 }
 /** Ein Betrieb mit allem, was der Partner ueber ihn sehen darf — nie Geheimnisse. */
-export async function getPartnerCustomer(rufen, customerId) {
+export 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'];
@@ -280,16 +280,16 @@ export async function getPartnerCustomer(rufen, customerId) {
  * einem ganzen ausgefuellten Formular auf. Die Antwort sagt NUR ja oder nein —
  * nie, wem die Adresse gehoert.
  */
-export async function checkPartnerCustomerEmail(rufen, email) {
+export async function checkPartnerCustomerEmail(transport, email) {
     const adresse = typeof email === 'string' ? email.trim() : '';
     if (!adresse)
         throw new 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;
 }
-export async function sendPartnerCustomerFonLink(rufen, customerId) {
+export 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']),
@@ -346,12 +346,12 @@ function antrag(eintrag) {
  * Abschluss kommt als Ereignis `signature.ready`, nicht als Antwort auf diesen
  * Aufruf.
  */
-export async function requestCustomerSignature(rufen, customerId, optionen = {}) {
+export 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')),
@@ -385,9 +385,9 @@ function signaturEinzeln(eintrag) {
     };
 }
 /** Stand der Signatur eines Betriebs samt aller Signaturen, Antraege und des FON-Zugangs. */
-export async function getCustomerSignatureStatus(rufen, customerId) {
+export 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 {
@@ -447,12 +447,12 @@ function kasse(eintrag) {
  * Hoechstens 20 Kassen je Betrieb (`cashregister_limit`); ohne gebuchtes Modul
  * `module_inactive`.
  */
-export async function createCustomerCashregister(rufen, optionen) {
-    const id = pflicht(optionen?.customerId, 'createCustomerCashregister', 'customerId');
-    const daten = objekt(await rufen('createCustomerCashregister', {
+export 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 {
@@ -476,19 +476,19 @@ export async function createCustomerCashregister(rufen, optionen) {
  * veraendernde Aufruf dieses Clients, der ohne Idempotenzschluessel gefahrlos
  * wiederholbar ist — weil der Server ihn so gebaut hat.
  */
-export async function activateCashregister(rufen, customerId, cashregisterId) {
+export 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. */
-export async function listCustomerCashregisters(rufen, customerId) {
+export 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),
@@ -511,9 +511,9 @@ export async function listCustomerCashregisters(rufen, customerId) {
  * Zeichenketten-Umwandlung zeigen eine Maske, heraus kommt man nur ueber
  * `.reveal()`.
  */
-export async function getCustomerCredentials(rufen, customerId) {
+export 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']),
@@ -531,3 +531,43 @@ export 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.
+ */
+export 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 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 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/esm/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/esm/partner/fehler.js

@@ -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,15 +36,22 @@
  *
  * **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';
 /**
@@ -54,7 +61,7 @@ import { KasseneckApiError } from '../client/errors.js';
  *
  * Reihenfolge und Bestand wie im Abzug des Backends.
  */
-export const PARTNER_FEHLER_CODES = [
+export const PARTNER_ERROR_CODES = [
     // Eingabe, Konto und Takt
     'validation',
     'rate_limited',
@@ -84,8 +91,7 @@ export const 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',
@@ -109,7 +115,7 @@ export const PARTNER_FEHLER_CODES = [
  * Wer eine Katalogseite baut oder eine fremde Antwort einsortiert, findet
  * damit jeden Code des Backends wieder.
  */
-export const PARTNER_PORTAL_FEHLER_CODES = [
+export const PARTNER_PORTAL_ERROR_CODES = [
     'app_locked',
     'version_locked',
     'invalid_transition',
@@ -123,11 +129,40 @@ export const PARTNER_PORTAL_FEHLER_CODES = [
     'card_not_verified',
     'already_assigned',
 ];
-export function istPartnerFehlerCode(wert) {
-    return typeof wert === 'string' && 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.
+ */
+export const 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`.
+ */
+export function isPartnerErrorCode(value) {
+    return enthaelt(PARTNER_ERROR_CODES, value) || enthaelt(PARTNER_REQUEST_ERROR_CODES, value);
 }
-export function istPartnerPortalFehlerCode(wert) {
-    return typeof wert === 'string' && PARTNER_PORTAL_FEHLER_CODES.includes(wert);
+/** `true` fuer einen Code aus [PARTNER_PORTAL_ERROR_CODES]; alles andere ist `false`. */
+export function isPartnerPortalErrorCode(value) {
+    return enthaelt(PARTNER_PORTAL_ERROR_CODES, value);
 }
 /**
  * Was der Aufrufer tun muss. Ein Satz je Code, in der zweiten Person — nicht
@@ -164,10 +199,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.',
@@ -179,6 +211,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.',
@@ -194,23 +235,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.
  */
-export function partnerFehlerRat(code) {
+export 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. */
-export function partnerFehlerCode(error) {
+export function partnerErrorCode(error) {
     return error instanceof KasseneckApiError ? error.code : undefined;
 }
-/** Kurzform fuer `catch (e) { if (istPartnerFehler(e, 'signature_missing')) … }`. */
-export 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])?
+ */
+export 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. */
-export function partnerFeldFehler(error) {
+export function partnerFieldErrors(error) {
     if (!(error instanceof KasseneckApiError))
         return [];
     const roh = error.details['errors'];
@@ -230,8 +286,8 @@ export 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.
  */
-export function partnerWartezeitSek(error) {
-    if (partnerFehlerCode(error) !== 'rate_limited')
+export 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;

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

@@ -11,22 +11,23 @@
  * des Backends (`docs/api/partner.md`, kompakt `docs/api/partner.llms.txt`).
  * Was hier steht, ist die Benutzung dieses Clients.
  *
- * Reihenfolge der Kette: [PARTNER_ABLAUF].
+ * Reihenfolge der Kette: [PARTNER_FLOW].
  *
- * **Seit 0.28.0 spricht dieser Teil die englische `/v3`** ([PARTNER_BASE_URL]).
- * Alles andere im Paket (Belege, Rechnungen, Kasse, Druck, Zahlungen) bleibt
- * auf `/v1`, bis es dort eine `/v3` gibt.
+ * **Seit 0.28.0 spricht dieser Teil die englische `/v3`** ([PARTNER_BASE_URL]),
+ * seit 1.0 heissen auch seine Exporte englisch; die Tabelle alt/neu steht im
+ * CHANGELOG. Die Aliase aus 0.28 (`Rechtsform`, `Bundesland`, `KontaktRolle`)
+ * sind entfernt.
  */
 export { createPartnerApi, PARTNER_BASE_URL, type PartnerApi, type PartnerApiOptions } from './api.js';
 export { partnerKeyAuth, partnerKeyEnv, type PartnerKeyAuthOptions } from './auth.js';
-export { PARTNER_ABLAUF, naechsterSchritt, type AblaufSchritt, } from './ablauf.js';
-export { PARTNER_FEHLER_CODES, PARTNER_PORTAL_FEHLER_CODES, istPartnerFehlerCode, istPartnerPortalFehlerCode, istPartnerFehler, partnerFehlerCode, partnerFehlerRat, partnerFeldFehler, partnerWartezeitSek, type PartnerCode, type PartnerFehlerCode, type PartnerPortalFehlerCode, type PartnerFeldFehler, } from './fehler.js';
-export { BETRIEB_FELDER, unbekannteBetriebsfelder, type BetriebFeld, } from './betrieb.js';
-export { KasseneckSecret, SECRET_MASKE } from './secret.js';
-export { getPartnerInfo, createPartnerCustomer, listPartnerCustomers, checkPartnerCustomerEmail, getPartnerCustomer, sendPartnerCustomerFonLink, requestCustomerSignature, getCustomerSignatureStatus, createCustomerCashregister, activateCashregister, listCustomerCashregisters, getCustomerCredentials, } from './endpunkte.js';
-export { createPartnerWebhook, listPartnerWebhooks, rotatePartnerWebhookSecret, updatePartnerWebhook, deletePartnerWebhook, sendPartnerWebhookTest, listPartnerWebhookDeliveries, parseWebhookEvent, istPartnerWebhookEvent, PARTNER_WEBHOOK_EVENTS, WEBHOOK_UMSCHLAG_FELDER, type PartnerWebhookEvent, type PartnerWebhookEventType, type PartnerWebhook, type CreateWebhookOptions, type CreateWebhookResult, type DeleteWebhookResult, type WebhookApiVersion, type WebhookDeliveryStatus, type WebhookTestZustellung, type ContractKind, type ContractSource, type ContractAcceptedEventData, type WebhookPatch, type WebhookListe, type WebhookZustellung, type WebhookTestResult, type WebhookEventResult, } from './webhooks.js';
+export { PARTNER_FLOW, nextFlowStep, type FlowStep, } from './ablauf.js';
+export { PARTNER_ERROR_CODES, PARTNER_PORTAL_ERROR_CODES, PARTNER_REQUEST_ERROR_CODES, isPartnerErrorCode, isPartnerPortalErrorCode, isPartnerError, partnerErrorCode, partnerErrorAdvice, partnerFieldErrors, partnerRetryAfterSec, type PartnerCode, type PartnerErrorCode, type PartnerPortalErrorCode, type PartnerRequestErrorCode, type PartnerFieldError, } from './fehler.js';
+export { BUSINESS_FIELDS, unknownBusinessFields, type BusinessField, } from './betrieb.js';
+export { KasseneckSecret, SECRET_MASK } from './secret.js';
+export { getPartnerInfo, createPartnerCustomer, listPartnerCustomers, checkPartnerCustomerEmail, getPartnerCustomer, sendPartnerCustomerFonLink, requestCustomerSignature, getCustomerSignatureStatus, createCustomerCashregister, activateCashregister, listCustomerCashregisters, getCustomerCredentials, reportCustomerContract, } from './endpunkte.js';
+export { createPartnerWebhook, listPartnerWebhooks, rotatePartnerWebhookSecret, updatePartnerWebhook, deletePartnerWebhook, sendPartnerWebhookTest, listPartnerWebhookDeliveries, parseWebhookEvent, isPartnerWebhookEvent, PARTNER_WEBHOOK_EVENTS, WEBHOOK_ENVELOPE_FIELDS, WEBHOOK_DELIVERY_STATUSES, type PartnerWebhookEvent, type PartnerWebhookEventType, type PartnerWebhook, type CreateWebhookOptions, type CreateWebhookResult, type DeleteWebhookResult, type WebhookApiVersion, type WebhookDeliveryStatus, type WebhookTestDelivery, type ContractAcceptedEventData, type SignatureFailedEventData, type CashregisterFailedEventData, type WebhookPatch, type WebhookList, type WebhookDelivery, type WebhookTestResult, type WebhookEventResult, } from './webhooks.js';
 export { verifyWebhookSignature, parseSignatureHeader, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_TOLERANCE_SEC, WEBHOOK_RETRY_PLAN_SEC, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_TIMEOUT_MS, WEBHOOK_LIMIT, type VerifyWebhookOptions, type WebhookVerifyResult, type WebhookVerifyReason, } from './webhook-signatur.js';
-export { PARTNER_ENVS } from './typen.js';
-export type { PartnerEnv, PartnerScope, PartnerApp, PartnerInfo, LegalForm, AustrianState, ContactRole, AvvMode, FeeInterval, PartnerFee, SignatureHistoryReason, SignatureErrorCode, RequestSignatureOptions, CustomerSignature, Rechtsform, Bundesland, KontaktRolle, BetriebAdresse, BetriebSteuer, BetriebKontakt, BetriebSteuerberater, Betrieb, CreateCustomerOptions, CreateCustomerResult, KundenStatus, KundenZeile, AvvStand, VertragStand, KundenFonStand, ListCustomersOptions, KundenListe, Kunde, FonLinkResult, SignaturAntragStatus, SignaturHistorieEintrag, SignaturAntrag, RequestSignatureResult, SignaturStand, KassenSchritt, KassenStatus, Kasse, CreateCashregisterOptions, CreateCashregisterResult, ActivateCashregisterResult, KassenListe, CustomerCashregisterCredential, CustomerCredentials, } from './typen.js';
+export { PARTNER_ENVS, LEGAL_FORMS, AUSTRIAN_STATES, CONTACT_ROLES, AVV_MODES, FEE_INTERVALS, CONTRACT_KINDS, CONTRACT_SOURCES, SIGNATURE_HISTORY_REASONS, SIGNATURE_ERROR_CODES, } from './typen.js';
+export type { PartnerEnv, PartnerScope, PartnerApp, PartnerInfo, LegalForm, AustrianState, ContactRole, AvvMode, FeeInterval, PartnerFee, SignatureHistoryReason, SignatureErrorCode, RequestSignatureOptions, CustomerSignature, ContractKind, ContractSource, ReportCustomerContractOptions, ReportCustomerContractResult, BusinessAddress, BusinessTaxDetails, BusinessContact, BusinessTaxAdvisor, Business, CreateCustomerOptions, CreateCustomerResult, PartnerCustomerStatus, PartnerCustomerSummary, AvvStatus, ContractStatus, PartnerCustomerFonStatus, ListCustomersOptions, PartnerCustomerList, PartnerCustomer, FonLinkResult, SignatureRequestStatus, SignatureHistoryEntry, SignatureRequest, RequestSignatureResult, CustomerSignatureStatus, CashregisterActivationStep, CustomerCashregisterStatus, CustomerCashregister, CreateCashregisterOptions, CreateCashregisterResult, ActivateCashregisterResult, CustomerCashregisterList, CustomerCashregisterCredential, CustomerCredentials, } from './typen.js';
 /** `credentials:read` — nicht im Standardsatz, siehe typen.ts. */
 export { SCOPE_CREDENTIALS } from './typen.js';