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

package/dist/esm/models/cancellation.js

@@ -1,3 +1,4 @@
+import { bekannterCode, feldfehlerVon } from '../client/fehlercodes.js';
 /**
  * Storno-Metadaten — Zwilling von `functions/storno-core.js`.
  *
@@ -7,65 +8,105 @@
  * Storno-Beleg) und die Liste der Stornos am Original (`cancellations`), aus
  * der sich die Restmengen ergeben.
  */
-/** Grund-Katalog: Codes wie im Backend, Anzeigetext fuer Bon und Bedienung. */
+/**
+ * Grund-Katalog: Codes wie unter `/v3` (Katalog `STORNO_GRUND` des
+ * Backends), Anzeigetext fuer Bon und Bedienung. Der Anzeigetext bleibt
+ * deutsch, er steht so am Beleg.
+ */
 export const CANCELLATION_REASONS = Object.freeze({
-    fehleingabe: 'Fehleingabe',
-    kunde_storniert: 'Kunde hat storniert',
-    falsche_zahlart: 'Falsche Zahlart',
-    doppelt_erfasst: 'Doppelt erfasst',
-    sonstiges: 'Sonstiges',
+    input_error: 'Fehleingabe',
+    customer_cancelled: 'Kunde hat storniert',
+    wrong_payment_method: 'Falsche Zahlart',
+    duplicate: 'Doppelt erfasst',
+    other: 'Sonstiges',
 });
 export function isCancellationReason(value) {
     return typeof value === 'string' && Object.prototype.hasOwnProperty.call(CANCELLATION_REASONS, value);
 }
 /**
- * Stabile Fehlercodes von `cancelReceipt` — Zwilling von
- * `functions/gemeinsam/storno-core.js` STORNO_FEHLERCODES. Das Backend legt sie bei
+ * Stabile Fehlercodes von `cancelReceipt` unter `/v3` (Vokabular
+ * `errorCodes.cancellation`, gleiche Reihenfolge). Das Backend legt sie bei
  * jedem fachlichen Fehler als `code` neben die Meldung; das Paket reicht sie
- * als [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text** —
+ * als [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text:**
  * die deutsche Meldung darf sich aendern, der Code nicht.
  *
- * Nur Auth-/Parameterfehler (Sitzung abgelaufen, Pflichtfeld fehlt) kommen
- * ohne Code; dort bleibt `code` undefined.
+ * Formfehler an `payments` selbst melden die Codes aus
+ * [PAYMENT_ERROR_CODES]. `cancellation_outcome_unknown` heisst: der Storno
+ * ist moeglicherweise gebucht (`outcome: 'unknown'`). Nie wiederholen,
+ * sondern das Original nachlesen (`getReceipt`, `cancellations[]`).
  *
- * Die vier `STORNO_PAYMENTS_…`/`STORNO_REFUND_…`-Codes gehoeren zur
- * Rueckzahlung je Zahlung (mehrere Zahlungen je Beleg); Formfehler an
- * `payments` selbst melden die Codes aus [PAYMENT_ERROR_CODES].
- * `STORNO_OUTCOME_UNKNOWN` heisst: der Storno-Beleg kann schon signiert sein,
- * die Reservierung bleibt offen – nicht erneut stornieren, die Belegliste
- * nach ein paar Minuten neu laden (unter `/v3`: `cancellation_outcome_unknown`).
- *
- * Die Werte hier sind die von `/v1` und intern. Unter `/v3` heissen die
- * Storno-Codes nach dem /v3-Vokabular anders (`already_cancelled`,
- * `cancellation_payments_required`, functions/gemeinsam/api-vokabular-v3.js);
- * diese Namen kommen mit der Umstellung des Pakets auf `/v3`.
- * [isCancellationErrorCode] prueft darum exakt.
+ * Dahinter (ab 1.0) die Codes, die Anmeldung und Rand auf diesem Endpunkt
+ * erzeugen koennen: `errorCodes.auth` ohne die sieben des Partner-Zugangs und
+ * `errorCodes.edge` (`not_found`, `dialect_mismatch`, `response_translation_failed`
+ * ...), zuletzt die Codes des Pakets (`route_missing`, `response_unreadable`).
+ * Die Zahlungscodes (`payment_method_not_supported` ...) stehen in
+ * [PAYMENT_ERROR_CODES]. Ein Code ausserhalb bleibt ueber
+ * `KasseneckApiError.code` lesbar.
  */
-export const CANCELLATION_ERROR_CODES = [
-    'beleg_nicht_gefunden', // Original fehlt oder gehoert nicht zu dieser Kasse
-    'belegart_nicht_stornierbar', // Original ist selbst Storno-, Null- oder Startbeleg
-    'trainingsbeleg', // Trainingsbelege werden nicht storniert
-    'bereits_storniert', // keine Restmenge mehr (auch beim positionslosen Beleg)
-    'position_ungueltig', // Index unbekannt oder doppelt
-    'menge_ueber_rest', // Menge nicht ganzzahlig >= 1 oder groesser als der Rest
-    'grund_unbekannt', // reason fehlt oder nicht im Katalog
-    'anmerkung_zu_lang', // note laenger als 200 Zeichen
-    'items_ungueltig', // items ist keine Liste
-    'kasse_nicht_zugewiesen', // Register-Benutzer darf diese Kasse nicht
-    'keine_berechtigung', // Register-Benutzer ohne Storno-Recht
-    'nur_eigene_belege', // Recht "eigene", fremder Beleg
-    'kasse_unvollstaendig', // api_key/token fehlen am Konto bzw. an der Kasse
-    'storno_fehlgeschlagen', // der Storno-Beleg selbst wurde abgelehnt (z. B. Signatur)
-    // Mehrere Zahlungen je Beleg (Rueckzahlung je Zahlung):
-    'STORNO_PAYMENTS_REQUIRED', // Teilstorno eines Belegs mit mehreren Zahlungen ohne payments
-    'STORNO_REFUND_EXCEEDS_PAYMENT', // Rueckzahlungen auf eine Zahlung uebersteigen deren Rest
-    'STORNO_REFUND_REFERENCE_REQUIRED', // Karten-Rueckzahlung ohne refundOf einer Kartenzahlung
-    'STORNO_REFUND_REFERENCE_UNKNOWN', // refundOf nennt keine Zahlung des Originals
-    'STORNO_OUTCOME_UNKNOWN', // Ausgang offen: Storno-Beleg evtl. schon signiert, nicht wiederholen
-];
+export const CANCELLATION_ERROR_CODES = Object.freeze([
+    'receipt_not_found', // Original fehlt oder gehoert nicht zu dieser Kasse
+    'receipt_type_not_cancellable', // Original ist selbst Storno-, Null- oder Startbeleg
+    'training_receipt', // Trainingsbelege werden nicht storniert
+    'already_cancelled', // keine Restmenge mehr
+    'invalid_line', // Index unbekannt oder doppelt
+    'quantity_exceeds_remaining', // Menge nicht ganzzahlig >= 1 oder groesser als der Rest
+    'unknown_reason', // reason fehlt oder nicht im Katalog
+    'note_too_long', // note laenger als 200 Zeichen
+    'invalid_items', // items ist keine Liste
+    'cashregister_not_assigned', // Kassen-Benutzer darf diese Kasse nicht
+    'not_permitted', // Kassen-Benutzer ohne Storno-Recht
+    'own_receipts_only', // Recht "eigene", fremder Beleg
+    'cashregister_incomplete', // api_key/token fehlen am Konto bzw. an der Kasse
+    'cancellation_failed', // der Storno-Beleg selbst wurde abgelehnt (z. B. Signatur)
+    'cancellation_payments_required', // Teilstorno eines Belegs mit mehreren Zahlungen ohne payments
+    'cancellation_refund_exceeds_payment', // Rueckzahlungen auf eine Zahlung uebersteigen deren Rest
+    'cancellation_refund_reference_required', // Karten-Rueckzahlung ohne refundOf einer Kartenzahlung
+    'cancellation_refund_reference_unknown', // refundOf nennt keine Zahlung des Originals
+    'cancellation_outcome_unknown', // Ausgang unklar: nachlesen, nie wiederholen
+    // Anmeldung und Rand (errorCodes.auth ohne Partner-Zugang, errorCodes.edge)
+    'account_not_found',
+    'admin_required',
+    'cashregister_not_found',
+    'cashregister_token_invalid',
+    'cashregister_token_missing',
+    'dialect_mismatch',
+    'internal_translation_error',
+    'live_not_enabled',
+    'method_not_allowed',
+    'mfa_required',
+    'not_found',
+    'register_user_no_business',
+    'register_user_not_allowed',
+    'register_user_not_found',
+    'response_translation_failed',
+    'session_expired',
+    'session_other_cashregister',
+    'unauthorized',
+    'user_disabled',
+    'user_verification_failed',
+    'validation',
+    // Codes des Pakets (CLIENT_ERROR_CODES)
+    'route_missing',
+    'response_unreadable',
+]);
 export function isCancellationErrorCode(value) {
     return typeof value === 'string' && CANCELLATION_ERROR_CODES.includes(value);
 }
+const CANCELLATION_BEKANNT = new Set(CANCELLATION_ERROR_CODES);
+/** Der Code eines geworfenen Fehlers, wenn er in [CANCELLATION_ERROR_CODES] steht; sonst `undefined`. */
+export function cancellationErrorCode(error) {
+    return bekannterCode(error, CANCELLATION_BEKANNT);
+}
+/**
+ * Kurzform fuer `catch (e) { if (isCancellationError(e, 'already_cancelled')) … }`.
+ * Ohne `code`: traegt der Fehler ueberhaupt einen Code aus [CANCELLATION_ERROR_CODES]?
+ */
+export function isCancellationError(error, code) {
+    const gefunden = cancellationErrorCode(error);
+    return gefunden !== undefined && (code === undefined || gefunden === code);
+}
+/** Stornostand eines Belegs in der Belegliste (Katalog `STORNO_STAND`). */
+export const CANCELLATION_STATUSES = Object.freeze(['none', 'partial', 'full']);
 /** Ab wann eine liegengebliebene Reservierung nicht mehr zaehlt (wie im Backend). */
 export const CANCELLATION_RESERVATION_MS = 120_000;
 /**
@@ -86,3 +127,7 @@ export function remainingQuantities(receipt, nowMs = Date.now()) {
     }
     return rest;
 }
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export function cancellationFieldErrors(error) {
+    return feldfehlerVon(error);
+}

package/dist/esm/models/hobex-receipt.d.ts

@@ -51,13 +51,13 @@ export interface HobexReceiptPayload {
     tip: number;
     cvm: string | number;
 }
-export declare function toHobexReceiptPayload(beleg: HobexReceipt): HobexReceiptPayload;
+export declare function toHobexReceiptPayload(receipt: HobexReceipt): HobexReceiptPayload;
 export declare function fromHobexReceiptPayload(payload: HobexReceiptPayload): HobexReceipt;
 /**
  * Wandelt den Beleg in die `cardPaymentData`-Map, die auf dem Kasseneck-Beleg
  * landet (siehe [Receipt.cardPaymentData]). Bei HPS-Zahlungen kommen weitere
  * Felder dazu, die nur das lokale Terminal liefert.
  */
-export declare function hobexReceiptToCardPaymentData(beleg: HobexReceipt): Record<string, string>;
+export declare function hobexReceiptToCardPaymentData(receipt: HobexReceipt): Record<string, string>;
 /** Kartenzahlung erfordert eine Unterschrift (CVM-Code `"1"`). */
-export declare function hobexReceiptNeedsSignature(beleg: HobexReceipt): boolean;
+export declare function hobexReceiptNeedsSignature(receipt: HobexReceipt): boolean;

package/dist/esm/models/hobex-receipt.js

@@ -1,24 +1,24 @@
 import { CreditCardProvider } from '../enums/index.js';
 import { centsToEuro, euroToCents } from '../money.js';
-export function toHobexReceiptPayload(beleg) {
+export function toHobexReceiptPayload(receipt) {
     return {
-        transactionId: beleg.transactionId,
-        tid: beleg.tid,
-        receipt: beleg.receipt,
-        approvalCode: beleg.approvalCode,
-        reference: beleg.reference ?? null,
-        transactionDate: beleg.transactionDate,
-        cardNumber: beleg.cardNumber,
-        cardExpiry: beleg.cardExpiry,
-        brand: beleg.brand,
-        cardIssuer: beleg.cardIssuer,
-        responseCode: beleg.responseCode,
-        transactionType: beleg.transactionType,
-        currency: beleg.currency,
+        transactionId: receipt.transactionId,
+        tid: receipt.tid,
+        receipt: receipt.receipt,
+        approvalCode: receipt.approvalCode,
+        reference: receipt.reference ?? null,
+        transactionDate: receipt.transactionDate,
+        cardNumber: receipt.cardNumber,
+        cardExpiry: receipt.cardExpiry,
+        brand: receipt.brand,
+        cardIssuer: receipt.cardIssuer,
+        responseCode: receipt.responseCode,
+        transactionType: receipt.transactionType,
+        currency: receipt.currency,
         // Euro-Umwandlung nur hier, an der Terminal-API-Grenze — siehe Kommentar oben.
-        amount: centsToEuro(beleg.amountCents),
-        tip: centsToEuro(beleg.tipCents),
-        cvm: beleg.cvm,
+        amount: centsToEuro(receipt.amountCents),
+        tip: centsToEuro(receipt.tipCents),
+        cvm: receipt.cvm,
     };
 }
 export function fromHobexReceiptPayload(payload) {
@@ -60,28 +60,28 @@ export function fromHobexReceiptPayload(payload) {
  * landet (siehe [Receipt.cardPaymentData]). Bei HPS-Zahlungen kommen weitere
  * Felder dazu, die nur das lokale Terminal liefert.
  */
-export function hobexReceiptToCardPaymentData(beleg) {
+export function hobexReceiptToCardPaymentData(receipt) {
     const data = {
-        transactionId: beleg.transactionId,
-        date: beleg.transactionDate,
-        tid: beleg.tid,
-        no: beleg.receipt,
-        type: beleg.transactionType,
-        cardBrand: beleg.brand,
-        cardNumber: beleg.cardNumber,
-        responseCode: beleg.responseCode,
-        cvm: beleg.cvm,
+        transactionId: receipt.transactionId,
+        date: receipt.transactionDate,
+        tid: receipt.tid,
+        no: receipt.receipt,
+        type: receipt.transactionType,
+        cardBrand: receipt.brand,
+        cardNumber: receipt.cardNumber,
+        responseCode: receipt.responseCode,
+        cvm: receipt.cvm,
     };
-    if (beleg.creditCardProvider === CreditCardProvider.hobexHps) {
-        data.approvalCode = beleg.approvalCode;
-        data.cardExpiry = beleg.cardExpiry;
-        data.cardIssuer = beleg.cardIssuer;
-        data.amount = centsToEuro(beleg.amountCents).toFixed(2);
-        data.currency = beleg.currency;
+    if (receipt.creditCardProvider === CreditCardProvider.hobexHps) {
+        data.approvalCode = receipt.approvalCode;
+        data.cardExpiry = receipt.cardExpiry;
+        data.cardIssuer = receipt.cardIssuer;
+        data.amount = centsToEuro(receipt.amountCents).toFixed(2);
+        data.currency = receipt.currency;
     }
     return data;
 }
 /** Kartenzahlung erfordert eine Unterschrift (CVM-Code `"1"`). */
-export function hobexReceiptNeedsSignature(beleg) {
-    return beleg.cvm === '1';
+export function hobexReceiptNeedsSignature(receipt) {
+    return receipt.cvm === '1';
 }

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

@@ -1,13 +1,14 @@
 export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, isDiscountItem, } from './receipt-item.js';
 export { type Voucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid } from './voucher.js';
-export { type Receipt, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, } from './receipt.js';
-export { type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, remainingQuantities, } from './cancellation.js';
+export { type Receipt, type RegistrationInfo, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, readRegistrationInfo, receiptSubSumCents, receiptSumCents, } from './receipt.js';
+export { type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, type CancellationStatus, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, type CancellationFieldError, remainingQuantities, } from './cancellation.js';
 export { type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, } from './receipt-payment.js';
-export { type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode } from './payment-errors.js';
-export { type ReceiptEmailErrorCode, RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, } from './receipt-email.js';
+export { type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode, paymentErrorCode, isPaymentError, paymentFieldErrors, type PaymentFieldError } from './payment-errors.js';
+export { type ReceiptEmailErrorCode, type ReceiptEmailVia, RECEIPT_EMAIL_ERROR_CODES, RECEIPT_EMAIL_SEND_ERROR_CODES, type ReceiptEmailSendErrorCode, RECEIPT_EMAIL_VIAS, isReceiptEmailErrorCode, receiptEmailErrorCode, isReceiptEmailError, receiptEmailFieldErrors, type ReceiptEmailFieldError, } from './receipt-email.js';
+export { type ReceiptErrorCode, type ReceiptFieldError, RECEIPT_ERROR_CODES, isReceiptErrorCode, receiptErrorCode, isReceiptError, receiptFieldErrors, } from './receipt-errors.js';
 export { type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, } from './receipt-company.js';
 export { type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, fromCashregisterPayload, } from './cashregister.js';
-export { type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, istZeroKind } from './receipt-summary.js';
+export { type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, isZeroKind } from './receipt-summary.js';
 export { type ReportMonth, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, } from './report-month.js';
 export { type StripeUrlSession, type StripeUrlSessionPayload, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, } from './stripe-url-session.js';
 export { type HobexReceipt, type HobexReceiptPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './hobex-receipt.js';

package/dist/esm/models/index.js

@@ -1,13 +1,14 @@
 export { toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, isTipItem, isDiscountItem, } from './receipt-item.js';
 export { toVoucherPayload, fromVoucherPayload, voucherIsValid } from './voucher.js';
-export { toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, } from './receipt.js';
-export { CANCELLATION_REASONS, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, remainingQuantities, } from './cancellation.js';
+export { toReceiptPayload, fromReceiptPayload, readRegistrationInfo, receiptSubSumCents, receiptSumCents, } from './receipt.js';
+export { CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, remainingQuantities, } from './cancellation.js';
 export { fromReceiptPaymentPayload, toReceiptPaymentPayload, } from './receipt-payment.js';
-export { PAYMENT_ERROR_CODES, isPaymentErrorCode } from './payment-errors.js';
-export { RECEIPT_EMAIL_ERROR_CODES, isReceiptEmailErrorCode, } from './receipt-email.js';
+export { PAYMENT_ERROR_CODES, isPaymentErrorCode, paymentErrorCode, isPaymentError, paymentFieldErrors } from './payment-errors.js';
+export { RECEIPT_EMAIL_ERROR_CODES, RECEIPT_EMAIL_SEND_ERROR_CODES, RECEIPT_EMAIL_VIAS, isReceiptEmailErrorCode, receiptEmailErrorCode, isReceiptEmailError, receiptEmailFieldErrors, } from './receipt-email.js';
+export { RECEIPT_ERROR_CODES, isReceiptErrorCode, receiptErrorCode, isReceiptError, receiptFieldErrors, } from './receipt-errors.js';
 export { fromReceiptCompanyPayload, receiptCompanyTaxInfo, } from './receipt-company.js';
 export { fromCashregisterPayload, } from './cashregister.js';
-export { fromReceiptSummaryPayload, ZERO_KINDS, istZeroKind } from './receipt-summary.js';
+export { fromReceiptSummaryPayload, ZERO_KINDS, isZeroKind } from './receipt-summary.js';
 export { reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, } from './report-month.js';
 export { toStripeUrlSessionPayload, fromStripeUrlSessionPayload, } from './stripe-url-session.js';
 export { toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './hobex-receipt.js';

package/dist/esm/models/payment-errors.d.ts

@@ -1,22 +1,39 @@
+import { KasseneckApiError } from '../client/errors.js';
 /**
- * Mehrere Zahlungen je Beleg — Fehlercode-Katalog, Zwilling von
- * `functions/gemeinsam/zahlungen-core.js` ZAHLUNGS_FEHLERCODES (gleiche
- * Codes, gleiche Reihenfolge).
+ * Mehrere Zahlungen je Beleg: Fehlercodes unter `/v3` (Vokabular
+ * `errorCodes.payments`, gleiche Codes, gleiche Reihenfolge).
  *
  * `createReceipt` und `cancelReceipt` legen sie bei jedem Fehler rund um
- * `payments` (und bei den Aufrufer-Vorbedingungen wie `PAYMENTS_CONFLICT`)
- * als `code` neben die Meldung; das Paket reicht sie als
- * [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text** — die
+ * `payments` als `code` neben die Meldung; das Paket reicht sie als
+ * [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text:** die
  * deutsche Meldung darf sich aendern, der Code nicht.
  *
- * Schreibweise: auf `/v1`, `/v2` und intern kommen die Codes gross
- * (`PAYMENTS_SUM_MISMATCH`), unter `/v3` schreibt der Rand des Backends sie
- * klein (`payments_sum_mismatch`, functions/gemeinsam/api-vokabular-v3.js:
- * jeder dieser Codes 1:1 in Kleinschreibung, anders als die Storno-Codes).
- * [isPaymentErrorCode] erkennt beide; wer selbst vergleicht, vergleicht
- * `code.toUpperCase()`.
+ * `payments_sum_mismatch` traegt den Zahlbetrag des Servers in
+ * `details.expectedCents` (siehe [paymentsExpectedCents]). Der Fehler
+ * verbraucht keine Belegnummer; das Paket wiederholt trotzdem nie selbst,
+ * denn eine Kartenzahlung ist schon belastet.
+ *
+ * Dahinter (ab 1.0) die Codes, die Anmeldung und Rand auf diesem Endpunkt
+ * erzeugen koennen: `errorCodes.auth` ohne die sieben des Partner-Zugangs und
+ * `errorCodes.edge` (`not_found`, `dialect_mismatch`, `response_translation_failed`
+ * ...) und zuletzt `route_missing` (Code des Pakets). Ein Code ausserhalb
+ * bleibt ueber `KasseneckApiError.code` lesbar.
  */
-export declare const PAYMENT_ERROR_CODES: readonly ["PAYMENTS_INVALID", "PAYMENT_METHOD_INVALID", "PAYMENT_AMOUNT_INVALID", "PAYMENT_TENDERED_INVALID", "PAYMENT_PROVIDER_INVALID", "PAYMENT_PROVIDER_NOT_ALLOWED", "PAYMENTS_SUM_MISMATCH", "PAYMENTS_DUE_NEGATIVE", "PAYMENTS_NOT_ALLOWED", "PAYMENTS_CONFLICT", "PAYMENTS_REQUIRED", "PAYMENT_METHOD_NOT_SUPPORTED", "TIP_PAYMENT_METHOD_INVALID", "TIP_PAYMENT_METHOD_REQUIRED", "TIP_EXCEEDS_PAYMENT", "PAYMENT_REFUND_NOT_ALLOWED", "PAYMENT_TIP_INVALID", "TIP_CONFLICT"];
+export declare const PAYMENT_ERROR_CODES: readonly ["payments_invalid", "payment_method_invalid", "payment_amount_invalid", "payment_tendered_invalid", "payment_provider_invalid", "payment_provider_not_allowed", "payments_sum_mismatch", "payments_due_negative", "payments_not_allowed", "payments_conflict", "payments_required", "payment_method_not_supported", "tip_payment_method_invalid", "tip_payment_method_required", "tip_exceeds_payment", "payment_refund_not_allowed", "payment_tip_invalid", "tip_conflict", "account_not_found", "admin_required", "cashregister_not_assigned", "cashregister_not_found", "cashregister_token_invalid", "cashregister_token_missing", "dialect_mismatch", "internal_translation_error", "live_not_enabled", "method_not_allowed", "mfa_required", "not_found", "register_user_no_business", "register_user_not_allowed", "register_user_not_found", "response_translation_failed", "session_expired", "session_other_cashregister", "unauthorized", "user_disabled", "user_verification_failed", "validation", "route_missing"];
 export type PaymentErrorCode = (typeof PAYMENT_ERROR_CODES)[number];
-/** Erkennt einen Code aus [PAYMENT_ERROR_CODES] — gross (`/v1`) wie klein (`/v3`). */
-export declare function isPaymentErrorCode(value: unknown): value is PaymentErrorCode | Lowercase<PaymentErrorCode>;
+/** Erkennt einen Code aus [PAYMENT_ERROR_CODES], exakt (klein, wie unter `/v3`). */
+export declare function isPaymentErrorCode(value: unknown): value is PaymentErrorCode;
+/** Der Code eines geworfenen Fehlers, wenn er in [PAYMENT_ERROR_CODES] steht; sonst `undefined`. */
+export declare function paymentErrorCode(error: unknown): PaymentErrorCode | undefined;
+/**
+ * Kurzform fuer `catch (e) { if (isPaymentError(e, 'payments_sum_mismatch')) … }`.
+ * Ohne `code`: traegt der Fehler ueberhaupt einen Code aus [PAYMENT_ERROR_CODES]?
+ */
+export declare function isPaymentError(error: unknown, code?: PaymentErrorCode): error is KasseneckApiError;
+/** Ein Feldfehler aus `data.errors[]` einer `validation`-Antwort von `payments[]`. */
+export interface PaymentFieldError {
+    field: string;
+    message: string;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export declare function paymentFieldErrors(error: unknown): PaymentFieldError[];

package/dist/esm/models/payment-errors.js

@@ -1,42 +1,87 @@
+import { bekannterCode, feldfehlerVon } from '../client/fehlercodes.js';
 /**
- * Mehrere Zahlungen je Beleg — Fehlercode-Katalog, Zwilling von
- * `functions/gemeinsam/zahlungen-core.js` ZAHLUNGS_FEHLERCODES (gleiche
- * Codes, gleiche Reihenfolge).
+ * Mehrere Zahlungen je Beleg: Fehlercodes unter `/v3` (Vokabular
+ * `errorCodes.payments`, gleiche Codes, gleiche Reihenfolge).
  *
  * `createReceipt` und `cancelReceipt` legen sie bei jedem Fehler rund um
- * `payments` (und bei den Aufrufer-Vorbedingungen wie `PAYMENTS_CONFLICT`)
- * als `code` neben die Meldung; das Paket reicht sie als
- * [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text** — die
+ * `payments` als `code` neben die Meldung; das Paket reicht sie als
+ * [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text:** die
  * deutsche Meldung darf sich aendern, der Code nicht.
  *
- * Schreibweise: auf `/v1`, `/v2` und intern kommen die Codes gross
- * (`PAYMENTS_SUM_MISMATCH`), unter `/v3` schreibt der Rand des Backends sie
- * klein (`payments_sum_mismatch`, functions/gemeinsam/api-vokabular-v3.js:
- * jeder dieser Codes 1:1 in Kleinschreibung, anders als die Storno-Codes).
- * [isPaymentErrorCode] erkennt beide; wer selbst vergleicht, vergleicht
- * `code.toUpperCase()`.
+ * `payments_sum_mismatch` traegt den Zahlbetrag des Servers in
+ * `details.expectedCents` (siehe [paymentsExpectedCents]). Der Fehler
+ * verbraucht keine Belegnummer; das Paket wiederholt trotzdem nie selbst,
+ * denn eine Kartenzahlung ist schon belastet.
+ *
+ * Dahinter (ab 1.0) die Codes, die Anmeldung und Rand auf diesem Endpunkt
+ * erzeugen koennen: `errorCodes.auth` ohne die sieben des Partner-Zugangs und
+ * `errorCodes.edge` (`not_found`, `dialect_mismatch`, `response_translation_failed`
+ * ...) und zuletzt `route_missing` (Code des Pakets). Ein Code ausserhalb
+ * bleibt ueber `KasseneckApiError.code` lesbar.
  */
 export const PAYMENT_ERROR_CODES = Object.freeze([
-    'PAYMENTS_INVALID', // payments ist keine Liste oder hat mehr als 20 Eintraege
-    'PAYMENT_METHOD_INVALID', // Zahlart unbekannt oder mixed
-    'PAYMENT_AMOUNT_INVALID', // amountCents keine Ganzzahl, 0 oder falsches Vorzeichen
-    'PAYMENT_TENDERED_INVALID', // tenderedCents an Nicht-Bar-Zahlung, zu klein oder am Storno
-    'PAYMENT_PROVIDER_INVALID', // Karte ohne/mit unbekanntem provider, providerPaymentId fehlt
-    'PAYMENT_PROVIDER_NOT_ALLOWED', // Anbieterfelder an einer Zahlung, die weder Karte noch online ist
-    'PAYMENTS_SUM_MISMATCH', // Summe != Zahlbetrag (Antwort nennt data.expectedCents)
-    'PAYMENTS_DUE_NEGATIVE', // Zahlbetrag < 0 (Wertgutschein groesser als der Beleg)
-    'PAYMENTS_NOT_ALLOWED', // Null-/Startbeleg mit Zahlungen, alter Storno-Weg
-    'PAYMENTS_CONFLICT', // payments zusammen mit paymentMethod oder Kartenfeldern
-    'PAYMENTS_REQUIRED', // /v3 ohne payments
-    'PAYMENT_METHOD_NOT_SUPPORTED', // paymentMethod/Kartenfelder unter /v3
-    'TIP_PAYMENT_METHOD_INVALID', // Trinkgeld-Zahlart kommt in payments nicht vor
-    'TIP_PAYMENT_METHOD_REQUIRED', // mehrere Zahlarten, tip.paymentMethod fehlt
-    'TIP_EXCEEDS_PAYMENT', // Trinkgeld uebersteigt die Zahlungen seiner Zahlart
-    'PAYMENT_REFUND_NOT_ALLOWED', // refundOf ausserhalb eines Stornos oder kein String
-    'PAYMENT_TIP_INVALID', // tipCents keine Ganzzahl, <= 0, > amountCents oder nicht am Verkauf
-    'TIP_CONFLICT', // tip und payments[].tipCents zugleich
+    'payments_invalid', // payments ist keine Liste oder hat mehr als 20 Eintraege
+    'payment_method_invalid', // Zahlart unbekannt oder mixed
+    'payment_amount_invalid', // amountCents keine Ganzzahl, 0 oder falsches Vorzeichen
+    'payment_tendered_invalid', // tenderedCents an Nicht-Bar-Zahlung, zu klein oder am Storno
+    'payment_provider_invalid', // Karte ohne/mit unbekanntem provider, providerPaymentId fehlt
+    'payment_provider_not_allowed', // Anbieterfelder an einer Zahlung, die weder Karte noch online ist
+    'payments_sum_mismatch', // Summe != Zahlbetrag (details.expectedCents)
+    'payments_due_negative', // Zahlbetrag < 0 (Wertgutschein groesser als der Beleg)
+    'payments_not_allowed', // Null-/Startbeleg mit Zahlungen
+    'payments_conflict', // payments zusammen mit paymentMethod oder Kartenfeldern
+    'payments_required', // ohne payments
+    'payment_method_not_supported', // paymentMethod/Kartenfelder am Beleg
+    'tip_payment_method_invalid', // Trinkgeld-Zahlart kommt in payments nicht vor
+    'tip_payment_method_required', // mehrere Zahlarten, tip.paymentMethod fehlt
+    'tip_exceeds_payment', // Trinkgeld uebersteigt die Zahlungen seiner Zahlart
+    'payment_refund_not_allowed', // refundOf ausserhalb eines Stornos oder kein String
+    'payment_tip_invalid', // tipCents keine Ganzzahl, <= 0, > amountCents oder nicht am Verkauf
+    'tip_conflict', // tip und payments[].tipCents zugleich
+    // Anmeldung und Rand (errorCodes.auth ohne Partner-Zugang, errorCodes.edge)
+    'account_not_found',
+    'admin_required',
+    'cashregister_not_assigned',
+    'cashregister_not_found',
+    'cashregister_token_invalid',
+    'cashregister_token_missing',
+    'dialect_mismatch',
+    'internal_translation_error',
+    'live_not_enabled',
+    'method_not_allowed',
+    'mfa_required',
+    'not_found',
+    'register_user_no_business',
+    'register_user_not_allowed',
+    'register_user_not_found',
+    'response_translation_failed',
+    'session_expired',
+    'session_other_cashregister',
+    'unauthorized',
+    'user_disabled',
+    'user_verification_failed',
+    'validation',
+    // Code des Pakets (CLIENT_ERROR_CODES; response_unreadable nur an signierenden Aufrufen)
+    'route_missing',
 ]);
-/** Erkennt einen Code aus [PAYMENT_ERROR_CODES] — gross (`/v1`) wie klein (`/v3`). */
+/** Erkennt einen Code aus [PAYMENT_ERROR_CODES], exakt (klein, wie unter `/v3`). */
 export function isPaymentErrorCode(value) {
-    return typeof value === 'string' && PAYMENT_ERROR_CODES.includes(value.toUpperCase());
+    return typeof value === 'string' && PAYMENT_ERROR_CODES.includes(value);
+}
+const PAYMENT_BEKANNT = new Set(PAYMENT_ERROR_CODES);
+/** Der Code eines geworfenen Fehlers, wenn er in [PAYMENT_ERROR_CODES] steht; sonst `undefined`. */
+export function paymentErrorCode(error) {
+    return bekannterCode(error, PAYMENT_BEKANNT);
+}
+/**
+ * Kurzform fuer `catch (e) { if (isPaymentError(e, 'payments_sum_mismatch')) … }`.
+ * Ohne `code`: traegt der Fehler ueberhaupt einen Code aus [PAYMENT_ERROR_CODES]?
+ */
+export function isPaymentError(error, code) {
+    const gefunden = paymentErrorCode(error);
+    return gefunden !== undefined && (code === undefined || gefunden === code);
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export function paymentFieldErrors(error) {
+    return feldfehlerVon(error);
 }

package/dist/esm/models/receipt-company.d.ts

@@ -4,7 +4,8 @@
  * (`toMetadataJson`/`fromMetadata`).
  *
  * Das Backend liefert sie **neben** dem Beleg: `getReceipt` und `createReceipt`
- * legen Firma, Anschrift, Steuernummer, UID, Fusszeilen, Logo-Adresse und das
+ * legen Firma, Anschrift, Steuernummer (`taxNumber`), UID (`vatId`),
+ * Fusszeilen, Logo-Adresse und das
  * Kleinunternehmer-Kennzeichen direkt in die Antwort (functions/index.js).
  * Zum RKSV-Kernbeleg gehoeren sie nicht — sie betreffen ausschliesslich die
  * Darstellung. Deshalb stehen sie hier als eigenes Modell und nicht in
@@ -23,9 +24,9 @@ export interface ReceiptCompany {
     city: string;
     phone: string;
     /** UID (Umsatzsteuer-Identifikationsnummer); fehlt bei Kleinunternehmern. */
-    uid?: string;
+    vatId?: string;
     /** Steuernummer des Finanzamts. */
-    taxnr: string;
+    taxNumber: string;
     /** Kleinunternehmer nach § 6 Abs 1 Z 27 UStG (keine USt im Ausweis). */
     isSmallBusiness: boolean;
     footer1: string;
@@ -51,8 +52,8 @@ export interface ReceiptCompanyPayload {
     zip?: string | null;
     city?: string | null;
     phone?: string | null;
-    uid?: string | null;
-    taxnr?: string | null;
+    vatId?: string | null;
+    taxNumber?: string | null;
     is_small_business?: boolean | null;
     footer1?: string | null;
     footer2?: string | null;

package/dist/esm/models/receipt-company.js

@@ -20,7 +20,7 @@ export function fromReceiptCompanyPayload(payload) {
         zip: text(payload.zip),
         city: text(payload.city),
         phone: text(payload.phone),
-        taxnr: text(payload.taxnr),
+        taxNumber: text(payload.taxNumber),
         isSmallBusiness: payload.is_small_business === true,
         footer1: text(payload.footer1),
         footer2: text(payload.footer2),
@@ -29,8 +29,8 @@ export function fromReceiptCompanyPayload(payload) {
     };
     // Die vier Kann-Felder bleiben weg, wenn sie leer sind — ein leerer String
     // in `footer3` erzeugte sonst eine leere Zeile auf dem Beleg.
-    if (payload.uid)
-        firma.uid = payload.uid;
+    if (payload.vatId)
+        firma.vatId = payload.vatId;
     if (payload.footer3)
         firma.footer3 = payload.footer3;
     if (payload.footer4)
@@ -44,5 +44,5 @@ export function fromReceiptCompanyPayload(payload) {
  * wenn es eine gibt, sonst die Steuernummer.
  */
 export function receiptCompanyTaxInfo(company) {
-    return company.uid !== undefined && company.uid.length > 0 ? company.uid : company.taxnr;
+    return company.vatId !== undefined && company.vatId.length > 0 ? company.vatId : company.taxNumber;
 }

package/dist/esm/models/receipt-email.d.ts

@@ -1,22 +1,36 @@
+import { KasseneckApiError } from '../client/errors.js';
+/** Die Codes des Versands selbst (`errorCodes.receiptEmail`); jeder hat einen Satz im Textkatalog. */
+export declare const RECEIPT_EMAIL_SEND_ERROR_CODES: readonly ["invalid_address", "receipt_not_found", "too_many_requests", "send_failed"];
+export type ReceiptEmailSendErrorCode = (typeof RECEIPT_EMAIL_SEND_ERROR_CODES)[number];
 /**
- * Beleg per E-Mail — Zwilling von `functions/beleg-mail-core.js`.
- *
- * Hier steht nur der Fehlercode-Katalog: der Aufruf selbst ist
- * [sendReceiptEmail] (client/receipts.ts), und was verschickt wird, ist ein
- * **Link auf die oeffentliche Belegseite** — der Beleg selbst bleibt
- * unberuehrt (BAO §131/RKSV), das Versandprotokoll fuehrt das Backend in einer
- * Unter-Sammlung neben ihm.
+ * Fehlercodes von `sendReceiptEmail` unter `/v3`: die Versandcodes
+ * ([RECEIPT_EMAIL_SEND_ERROR_CODES]) und dahinter (ab 1.0) die Codes, die
+ * Anmeldung und Rand auf diesem Endpunkt erzeugen koennen: `errorCodes.auth`
+ * ohne die sieben des Partner-Zugangs und `errorCodes.edge` (`not_found`,
+ * `dialect_mismatch`, `response_translation_failed` ...). Das Paket reicht sie
+ * als [KasseneckApiError.code] durch; ein Code ausserhalb bleibt dort lesbar.
+ * Zuletzt `route_missing` (Code des Pakets).
  */
-/**
- * Stabile Fehlercodes von `sendReceiptEmail` — Zwilling von
- * `beleg-mail-core.js` FEHLERCODES. Das Backend legt sie bei jedem fachlichen
- * Fehler als `code` neben die Meldung; das Paket reicht sie als
- * [KasseneckApiError.code] durch. **Entscheide am Code, nie am Text** — die
- * deutsche Meldung darf sich aendern, der Code nicht.
- *
- * Nur Auth-/Parameterfehler (Sitzung abgelaufen, Pflichtfeld fehlt) kommen
- * ohne Code; dort bleibt `code` undefined.
- */
-export declare const RECEIPT_EMAIL_ERROR_CODES: readonly ["adresse_ungueltig", "beleg_nicht_gefunden", "zu_oft", "versand_fehlgeschlagen"];
+export declare const RECEIPT_EMAIL_ERROR_CODES: readonly ["invalid_address", "receipt_not_found", "too_many_requests", "send_failed", "account_not_found", "admin_required", "cashregister_not_assigned", "cashregister_not_found", "cashregister_token_invalid", "cashregister_token_missing", "dialect_mismatch", "internal_translation_error", "live_not_enabled", "method_not_allowed", "mfa_required", "not_found", "register_user_no_business", "register_user_not_allowed", "register_user_not_found", "response_translation_failed", "session_expired", "session_other_cashregister", "unauthorized", "user_disabled", "user_verification_failed", "validation", "route_missing"];
 export type ReceiptEmailErrorCode = (typeof RECEIPT_EMAIL_ERROR_CODES)[number];
 export declare function isReceiptEmailErrorCode(value: unknown): value is ReceiptEmailErrorCode;
+/** Der Code eines geworfenen Fehlers, wenn er in [RECEIPT_EMAIL_ERROR_CODES] steht; sonst `undefined`. */
+export declare function receiptEmailErrorCode(error: unknown): ReceiptEmailErrorCode | undefined;
+/**
+ * Kurzform fuer `catch (e) { if (isReceiptEmailError(e, 'too_many_requests')) … }`.
+ * Ohne `code`: traegt der Fehler ueberhaupt einen Code aus [RECEIPT_EMAIL_ERROR_CODES]?
+ */
+export declare function isReceiptEmailError(error: unknown, code?: ReceiptEmailErrorCode): error is KasseneckApiError;
+/**
+ * Versandweg der Belegmail (Katalog `MAILWEG`): Postfach des Betriebs,
+ * Plattform, oder Plattform als Rueckfall, weil das eigene Postfach scheiterte.
+ */
+export declare const RECEIPT_EMAIL_VIAS: readonly ["own", "platform", "platform_fallback"];
+export type ReceiptEmailVia = (typeof RECEIPT_EMAIL_VIAS)[number];
+/** Ein Feldfehler aus `data.errors[]` einer `validation`-Antwort von `sendReceiptEmail`. */
+export interface ReceiptEmailFieldError {
+    field: string;
+    message: string;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export declare function receiptEmailFieldErrors(error: unknown): ReceiptEmailFieldError[];