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

package/dist/esm/{rechnung → invoice}/vertrag.js

@@ -4,10 +4,10 @@
  * Aus dieser Datei entstehen drei Dinge, damit sie nicht auseinanderlaufen
  * koennen:
  *
- * 1. `fixtures/rechnung-api.schema.json` (`npm run fixtures:rechnung`) — das
+ * 1. `fixtures/invoice-api.schema.json` (`npm run fixtures:rechnung`) — das
  *    Backend liest es aus dem vendorierten Paket und vergleicht es in beide
  *    Richtungen mit seiner eigenen Pruefung; der Dart-Zwilling zieht es byteweise.
- * 2. Die Listen unter `rechnung` in `fixtures/oberflaeche.json` (Codes, Gruende,
+ * 2. Die Listen unter `rechnung` in `fixtures/surface.json` (Codes, Gruende,
  *    Enums) — ueber denselben Namensraum-Scan wie der Partner-Teil.
  * 3. Die TypeScript-Typen in `typen.ts`.
  *
@@ -17,8 +17,8 @@
  * Beschrieben wird die Anfrage. Was der Server daraus macht — Rechnungsdatum,
  * Nummer, Summen — ist bewusst **nicht** setzbar.
  */
-export const RECHNUNG_VERTRAG_VERSION = 1;
-export const RECHNUNG_AUFRUFE = [
+export const INVOICE_CONTRACT_VERSION = 2;
+export const INVOICE_ENDPOINTS = [
     'createCustomer',
     'getCustomer',
     'updateCustomer',
@@ -69,6 +69,38 @@ export const INVOICE_ERROR_CODES = [
     'einvoice_unavailable', // zu dieser Rechnung entsteht keine E-Rechnung, Grund in `reason`
     'amount_too_large', // Betrag ueber der Grenze des Ganzzahlkerns; erst ab dessen Umstieg gesendet
 ];
+/**
+ * Codes, die Anmeldung und Rand auf jedem Rechnungsaufruf erzeugen koennen,
+ * soweit sie nicht schon in [INVOICE_ERROR_CODES] stehen: `errorCodes.auth`
+ * ohne die sieben des Partner-Zugangs, `errorCodes.edge` (sortiert) und
+ * zuletzt `route_missing` (Code des Pakets). [INVOICE_ERROR_CODES] bleibt
+ * genau der Katalog des Servers (das Backend vergleicht ihn mit dem Schema);
+ * die Helfer in `./invoice` erkennen beide Listen.
+ */
+export const INVOICE_REQUEST_ERROR_CODES = [
+    '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',
+    'route_missing',
+];
 /** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
 export const CREDIT_NOTE_REASONS = [
     'cancellation',
@@ -81,12 +113,13 @@ export const CREDIT_NOTE_REASONS = [
  * Der Steuerfall einer Rechnung. Er wird vom Server **abgeleitet** (Kundenland,
  * Kundenart, UID, Ware oder Leistung); eine mitgeschickte Angabe muss dazu
  * passen, sonst `tax_scheme_mismatch`. Neue Faelle stehen hinten, damit
- * gespeicherte Reihenfolgen gueltig bleiben.
+ * gespeicherte Reihenfolgen gueltig bleiben. Unter `/v1` hiess `intraCommunitySupply` noch
+ * `igLieferung`; unter `/v3` weist der Server den alten Namen mit `validation` ab.
  *
  * - `normal`                oesterreichische Umsatzsteuer
  * - `smallBusiness`         Kleinunternehmer (§ 6 Abs. 1 Z 27 UStG)
  * - `reverseCharge`         Leistung an ein Unternehmen in der EU (Art. 196 MwSt-RL)
- * - `igLieferung`           Ware an ein Unternehmen in der EU (Art. 6 Abs. 1 UStG)
+ * - `intraCommunitySupply`  Ware an ein Unternehmen in der EU (Art. 6 Abs. 1 UStG)
  * - `exportThirdCountry`    Ware ins Drittland (§ 6 Abs. 1 Z 1 UStG)
  * - `domesticReverseCharge` Uebergang der Steuerschuld im Inland, Grund aus `REVERSE_CHARGE_REASONS`
  * - `oss`                   B2C in der EU ueber den One-Stop-Shop, Satz des Ziellandes
@@ -96,7 +129,7 @@ export const TAX_SCHEMES = [
     'normal',
     'smallBusiness',
     'reverseCharge',
-    'igLieferung',
+    'intraCommunitySupply',
     'exportThirdCountry',
     'domesticReverseCharge',
     'oss',
@@ -107,23 +140,23 @@ export const TAX_SCHEMES = [
  * kein `domesticReverseCharge`: die Bedingungen sind je Fall verschieden, und
  * keine davon laesst sich aus Betrag und Land erraten.
  *
- * `schwelleCents` ist das Entgelt, ab dem der Fall greift — maßgeblich ist das
+ * `thresholdCents` ist das Entgelt, ab dem der Fall greift – maßgeblich ist das
  * **in der Rechnung ausgewiesene** Entgelt, nicht der Einzelpreis; ein
  * einheitlicher Liefervorgang darf dafuer nicht auf mehrere Rechnungen
  * aufgeteilt werden (UStR Rz 2605d).
  */
 export const REVERSE_CHARGE_REASONS = Object.freeze({
-    construction: { stelle: '§ 19 Abs. 1a UStG', schwelleCents: null },
-    scrap: { stelle: 'Schrott-UStV, BGBl. II Nr. 129/2007', schwelleCents: null },
-    mobile_devices: { stelle: '§ 19 Abs. 1e lit. b UStG', schwelleCents: 500_000 },
-    it_devices: { stelle: '§ 2 Z 1 UStBBKV, BGBl. II Nr. 369/2013', schwelleCents: 500_000 },
-    metals: { stelle: '§ 2 Z 4 UStBBKV', schwelleCents: null },
-    emission_certificates: { stelle: '§ 19 Abs. 1e lit. a UStG', schwelleCents: null },
-    gas_electricity: { stelle: '§ 2 Z 2 UStBBKV', schwelleCents: null },
-    energy_certificates: { stelle: '§ 2 Z 3 UStBBKV', schwelleCents: null },
-    investment_gold: { stelle: '§ 2 Z 5 UStBBKV', schwelleCents: null },
-    security_transfer: { stelle: '§ 19 Abs. 1b UStG', schwelleCents: null },
-    foreign_supplier: { stelle: '§ 19 Abs. 1 zweiter Satz UStG', schwelleCents: null },
+    construction: { legalBasis: '§ 19 Abs. 1a UStG', thresholdCents: null },
+    scrap: { legalBasis: 'Schrott-UStV, BGBl. II Nr. 129/2007', thresholdCents: null },
+    mobile_devices: { legalBasis: '§ 19 Abs. 1e lit. b UStG', thresholdCents: 500_000 },
+    it_devices: { legalBasis: '§ 2 Z 1 UStBBKV, BGBl. II Nr. 369/2013', thresholdCents: 500_000 },
+    metals: { legalBasis: '§ 2 Z 4 UStBBKV', thresholdCents: null },
+    emission_certificates: { legalBasis: '§ 19 Abs. 1e lit. a UStG', thresholdCents: null },
+    gas_electricity: { legalBasis: '§ 2 Z 2 UStBBKV', thresholdCents: null },
+    energy_certificates: { legalBasis: '§ 2 Z 3 UStBBKV', thresholdCents: null },
+    investment_gold: { legalBasis: '§ 2 Z 5 UStBBKV', thresholdCents: null },
+    security_transfer: { legalBasis: '§ 19 Abs. 1b UStG', thresholdCents: null },
+    foreign_supplier: { legalBasis: '§ 19 Abs. 1 zweiter Satz UStG', thresholdCents: null },
 });
 /** Ware oder Leistung — ohne das laesst sich ig. Lieferung nicht von Reverse Charge trennen. */
 export const ITEM_KINDS = ['goods', 'service'];
@@ -131,8 +164,37 @@ export const PRICE_MODES = ['net', 'gross'];
 export const VAT_RATES = [0, 10, 13, 20];
 export const CUSTOMER_TYPES = ['private', 'company'];
 export const INVOICE_LIST_STATUS = ['final', 'paid', 'cancelled', 'open', 'overdue'];
-export const DOC_TYPES = ['RE', 'GU'];
+/**
+ * Belegart: Rechnung oder Gutschrift (unter `/v1` `RE` bzw. `GU`). Das Vorzeichen
+ * steht in der Belegart, nie im Betrag.
+ */
+export const DOC_TYPES = ['invoice', 'credit_note'];
 export const EINVOICE_FORMATS = ['ubl', 'cii'];
+/**
+ * Was einer EN-16931-konformen E-Rechnung fehlt: `einvoice.missing` jeder
+ * Rechnungssicht und `data.missing` bei `einvoice_incomplete` bzw.
+ * `invoice_requirements_missing`. Unter `/v1` standen hier deutsche Woerter
+ * (`Straße`, `PLZ`, …).
+ */
+export const EINVOICE_MISSING_CODES = [
+    'name',
+    'street',
+    'zip',
+    'city',
+    'country',
+    'vat_id',
+    'order_reference',
+    'order_reference_format',
+];
+/** Warum eine Rechnung abgeschrieben wurde (`writeOffReasonCode` in `getInvoice`). */
+export const WRITE_OFF_REASON_CODES = [
+    'uncollectible',
+    'time_barred',
+    'waived',
+    'disputed',
+    'settled_externally',
+    'other',
+];
 /**
  * Sprachen einer Rechnung. Die Sprache wird beim Festschreiben eingefroren;
  * fehlt sie an Kunde oder Rechnung, gilt `de`. Behoerden bekommen immer `de`
@@ -165,9 +227,9 @@ export const INVOICE_NOTICE_CODES = [
 ];
 /**
  * Einheiten einer Position. Die API nimmt nur diese Schluessel an; gedruckt
- * wird das Kuerzel in der Sprache der Rechnung (`RECHNUNG_TEXTE`,
- * `einheit.<schluessel>`), die E-Rechnung fuehrt den UN/ECE-Code
- * (`RECHNUNG_EINHEITEN_CODES`). Ohne Angabe gilt `piece`.
+ * wird das Kuerzel in der Sprache der Rechnung (`INVOICE_TEXTS`,
+ * `unit_symbol.<schluessel>`), die E-Rechnung fuehrt den UN/ECE-Code
+ * (`INVOICE_UNIT_CODES`). Ohne Angabe gilt `piece`.
  */
 export const INVOICE_UNITS = [
     'piece',
@@ -226,7 +288,7 @@ export const INVOICE_UNITS = [
  * Laufmeter; Lizenz, Benutzer, Geraet als Stueck). Die Validatoren der
  * E-Rechnung pruefen jeden Code im Backend (Beispiel `api-einheiten`).
  */
-export const RECHNUNG_EINHEITEN_CODES = Object.freeze({
+export const INVOICE_UNIT_CODES = Object.freeze({
     piece: 'C62',
     pair: 'PR',
     set: 'SET',
@@ -303,16 +365,16 @@ export const INVOICE_SETUP_REQUIREMENTS = [
     'bank_account',
     'number_format',
 ];
-const text = (max, pflicht = false, extra = {}) => ({ typ: 'string', pflicht, max, ...(pflicht && extra.min === undefined ? { min: 1 } : {}), ...extra });
-const idempotencyKey = (pflicht) => ({ typ: 'string', pflicht, min: 1, max: 120 });
-const id = { typ: 'string', pflicht: false, min: 1, max: 128 };
-const idPflicht = { typ: 'string', pflicht: true, min: 1, max: 128 };
-const datum = (pflicht = false) => ({ typ: 'string', pflicht, min: 10, max: 10, format: 'date' });
-const limit = { typ: 'integer', pflicht: false, min: 1, max: 100 };
-const cursor = { typ: 'string', pflicht: false, min: 1, max: 500 };
+const text = (max, required = false, extra = {}) => ({ type: 'string', required, max, ...(required && extra.min === undefined ? { min: 1 } : {}), ...extra });
+const idempotencyKey = (required) => ({ type: 'string', required, min: 1, max: 120 });
+const id = { type: 'string', required: false, min: 1, max: 128 };
+const idPflicht = { type: 'string', required: true, min: 1, max: 128 };
+const datum = (required = false) => ({ type: 'string', required, min: 10, max: 10, format: 'date' });
+const limit = { type: 'integer', required: false, min: 1, max: 100 };
+const cursor = { type: 'string', required: false, min: 1, max: 500 };
 /** Kunde, wie das Fremdsystem ihn schickt. `vatId` ist die UID-Nummer. */
-export const KUNDE_FELDER = Object.freeze({
-    type: { typ: 'enum', pflicht: true, werte: CUSTOMER_TYPES },
+export const CUSTOMER_FIELDS = Object.freeze({
+    type: { type: 'enum', required: true, values: CUSTOMER_TYPES },
     name: text(200, true),
     legalForm: text(40),
     email: text(254, false, { format: 'email' }),
@@ -324,14 +386,14 @@ export const KUNDE_FELDER = Object.freeze({
     country: text(2, true, { min: 2, format: 'country' }),
     vatId: text(20, false, { format: 'vatId' }),
     shortCode: text(8, false, { format: 'shortCode' }),
-    isAuthority: { typ: 'boolean', pflicht: false },
+    isAuthority: { type: 'boolean', required: false },
     note: text(1000),
-    externalId: { typ: 'string', pflicht: false, min: 1, max: 120 },
+    externalId: { type: 'string', required: false, min: 1, max: 120 },
     /** Sprache der Rechnungen an diesen Kunden; fehlt = `de`. */
-    language: { typ: 'enum', pflicht: false, werte: INVOICE_LANGUAGES },
+    language: { type: 'enum', required: false, values: INVOICE_LANGUAGES },
 });
 /** Beim Aendern ist jedes Kundenfeld optional. */
-const KUNDE_PATCH = Object.freeze(Object.fromEntries(Object.entries(KUNDE_FELDER).map(([name, feld]) => [name, { ...feld, pflicht: false }])));
+const CUSTOMER_PATCH = Object.freeze(Object.fromEntries(Object.entries(CUSTOMER_FIELDS).map(([name, feld]) => [name, { ...feld, required: false }])));
 /**
  * Eine Rechnungs- oder Gutschriftsposition.
  *
@@ -342,33 +404,33 @@ const KUNDE_PATCH = Object.freeze(Object.fromEntries(Object.entries(KUNDE_FELDER
  * unterhalb eines Cents (Verbrauchsabrechnung, Stueckpreise im Zehntelcent),
  * die bisher gerundet eingereicht werden mussten.
  */
-export const POSITION_FELDER = Object.freeze({
+export const ITEM_FIELDS = Object.freeze({
     description: text(300, true),
     subtitle: text(1000),
-    quantity: { typ: 'number', pflicht: true, min: 0, exklusivMin: true, max: 1_000_000_000, nachkomma: 3 },
+    quantity: { type: 'number', required: true, min: 0, exclusiveMin: true, max: 1_000_000_000, decimals: 3 },
     /** Einheit aus `INVOICE_UNITS`; ohne Angabe `piece`. */
-    unit: { typ: 'enum', pflicht: false, werte: INVOICE_UNITS },
+    unit: { type: 'enum', required: false, values: INVOICE_UNITS },
     /** Ware oder Leistung; ohne Angabe `goods`. Entscheidet ueber den Steuerfall. */
-    kind: { typ: 'enum', pflicht: false, werte: ITEM_KINDS },
+    kind: { type: 'enum', required: false, values: ITEM_KINDS },
     /** Einzelpreis in ganzen Cent. Alternative zu `unitPriceMicros`. */
-    unitPriceCents: { typ: 'integer', pflicht: false, min: 0, max: 100_000_000 },
+    unitPriceCents: { type: 'integer', required: false, min: 0, max: 100_000_000 },
     /** Einzelpreis in Mikro-Euro (10⁻⁶ €). Alternative zu `unitPriceCents`. */
-    unitPriceMicros: { typ: 'integer', pflicht: false, min: 0, max: 1_000_000_000_000 },
-    vatRate: { typ: 'enum', pflicht: true, werte: VAT_RATES },
-    discountPct: { typ: 'number', pflicht: false, min: 0, max: 100, nachkomma: 2 },
+    unitPriceMicros: { type: 'integer', required: false, min: 0, max: 1_000_000_000_000 },
+    vatRate: { type: 'enum', required: true, values: VAT_RATES },
+    discountPct: { type: 'number', required: false, min: 0, max: 100, decimals: 2 },
 });
 /** Genau einer der beiden Preise je Position (§ 9.1). */
-export const POSITION_PREIS_GENAU_EINS = Object.freeze([
+export const ITEM_PRICE_EXACTLY_ONE = Object.freeze([
     Object.freeze(['unitPriceCents']),
     Object.freeze(['unitPriceMicros']),
 ]);
 const positionen = {
-    typ: 'list',
-    pflicht: true,
+    type: 'list',
+    required: true,
     min: 1,
     max: 500,
-    eintrag: {
-        typ: 'object', pflicht: true, felder: POSITION_FELDER, genauEins: POSITION_PREIS_GENAU_EINS,
+    item: {
+        type: 'object', required: true, fields: ITEM_FIELDS, exactlyOne: ITEM_PRICE_EXACTLY_ONE,
     },
 };
 /**
@@ -378,9 +440,9 @@ const positionen = {
  * aber **nicht gedruckt**: die Rechnung wird aufbewahrt und vervielfaeltigt,
  * und dem Empfaenger nuetzt sie nichts.
  */
-export const PAYMENT_FELDER = Object.freeze({
-    method: { typ: 'enum', pflicht: true, werte: INVOICE_PAYMENT_METHODS },
-    amountCents: { typ: 'integer', pflicht: false, min: 1, max: 100_000_000 },
+export const PAYMENT_FIELDS = Object.freeze({
+    method: { type: 'enum', required: true, values: INVOICE_PAYMENT_METHODS },
+    amountCents: { type: 'integer', required: false, min: 1, max: 100_000_000 },
     paidAt: datum(),
     reference: text(100),
     /**
@@ -388,23 +450,23 @@ export const PAYMENT_FELDER = Object.freeze({
      * Zahlung per App am Tresen). Dann ist sie ein Barumsatz. Zu `transfer` passt
      * das nicht — eine Ueberweisung erfolgt nie vor Ort — und wird abgewiesen.
      */
-    onSite: { typ: 'boolean', pflicht: false },
+    onSite: { type: 'boolean', required: false },
 });
-export const RECHNUNG_ANFRAGEN = Object.freeze({
+export const INVOICE_REQUESTS = Object.freeze({
     createCustomer: {
-        customer: { typ: 'object', pflicht: true, felder: KUNDE_FELDER },
+        customer: { type: 'object', required: true, fields: CUSTOMER_FIELDS },
         idempotencyKey: idempotencyKey(false),
     },
     getCustomer: {
         customerId: id,
-        externalId: { typ: 'string', pflicht: false, min: 1, max: 120 },
+        externalId: { type: 'string', required: false, min: 1, max: 120 },
     },
     updateCustomer: {
         customerId: idPflicht,
-        customer: { typ: 'object', pflicht: true, felder: KUNDE_PATCH },
+        customer: { type: 'object', required: true, fields: CUSTOMER_PATCH },
     },
     searchCustomers: {
-        externalId: { typ: 'string', pflicht: false, min: 1, max: 120 },
+        externalId: { type: 'string', required: false, min: 1, max: 120 },
         vatId: text(20),
         email: text(254),
         name: text(200),
@@ -419,23 +481,23 @@ export const RECHNUNG_ANFRAGEN = Object.freeze({
          * muss passen (`tax_scheme_mismatch`) — so faellt eine falsche Zuordnung
          * im Fremdsystem auf, statt eine falsche Rechnung zu erzeugen.
          */
-        taxScheme: { typ: 'enum', pflicht: false, werte: TAX_SCHEMES },
+        taxScheme: { type: 'enum', required: false, values: TAX_SCHEMES },
         /** Pflicht bei `domesticReverseCharge`, sonst nicht erlaubt. */
-        reverseChargeReason: { typ: 'enum', pflicht: false, werte: Object.keys(REVERSE_CHARGE_REASONS) },
-        priceMode: { typ: 'enum', pflicht: true, werte: PRICE_MODES },
+        reverseChargeReason: { type: 'enum', required: false, values: Object.keys(REVERSE_CHARGE_REASONS) },
+        priceMode: { type: 'enum', required: true, values: PRICE_MODES },
         serviceStart: datum(true),
         serviceEnd: datum(),
-        paymentTermDays: { typ: 'integer', pflicht: false, min: 0, max: 365 },
+        paymentTermDays: { type: 'integer', required: false, min: 0, max: 365 },
         orderReference: text(200),
         intro: text(2000),
         note: text(2000),
         paymentReference: text(140),
-        girocode: { typ: 'boolean', pflicht: false },
-        tracking: { typ: 'boolean', pflicht: false },
+        girocode: { type: 'boolean', required: false },
+        tracking: { type: 'boolean', required: false },
         items: positionen,
-        metadata: { typ: 'map', pflicht: false, maxSchluessel: 20, schluesselMuster: '^[a-zA-Z0-9_]{1,40}$', wertMax: 500 },
+        metadata: { type: 'map', required: false, maxKeys: 20, keyPattern: '^[a-zA-Z0-9_]{1,40}$', valueMax: 500 },
         /** Sprache dieser Rechnung; sonst die des Kunden, sonst `de`. */
-        language: { typ: 'enum', pflicht: false, werte: INVOICE_LANGUAGES },
+        language: { type: 'enum', required: false, values: INVOICE_LANGUAGES },
         /** Marke (Kennung aus `listBrands`); sonst die Standardmarke. */
         brandId: id,
         /**
@@ -443,36 +505,36 @@ export const RECHNUNG_ANFRAGEN = Object.freeze({
          * Festschreiben. Sonst gaebe es einen Moment, in dem die Rechnung offen ist
          * und ein sofort geholtes PDF Zahlungsinformationen traegt.
          */
-        payment: { typ: 'object', pflicht: false, felder: PAYMENT_FELDER },
+        payment: { type: 'object', required: false, fields: PAYMENT_FIELDS },
         /**
          * Probelauf: alles pruefen und rechnen wie beim Ausstellen, aber nichts
          * festschreiben — keine Nummer, kein Dokument, keine Zahlung, kein
          * Idempotenz-Eintrag. Die Antwort traegt `preview` statt `invoice`.
          */
-        dryRun: { typ: 'boolean', pflicht: false },
+        dryRun: { type: 'boolean', required: false },
     },
     cancelInvoice: {
         idempotencyKey: idempotencyKey(true),
         invoiceId: idPflicht,
-        reason: { typ: 'enum', pflicht: true, werte: CREDIT_NOTE_REASONS },
+        reason: { type: 'enum', required: true, values: CREDIT_NOTE_REASONS },
         note: text(2000),
     },
     createCreditNote: {
         idempotencyKey: idempotencyKey(true),
         invoiceId: idPflicht,
-        reason: { typ: 'enum', pflicht: true, werte: CREDIT_NOTE_REASONS },
+        reason: { type: 'enum', required: true, values: CREDIT_NOTE_REASONS },
         note: text(2000),
         items: positionen,
     },
     getInvoice: {
         invoiceId: id,
-        number: { typ: 'string', pflicht: false, min: 1, max: 100 },
+        number: { type: 'string', required: false, min: 1, max: 100 },
     },
     listInvoices: {
         from: datum(),
         to: datum(),
-        status: { typ: 'enum', pflicht: false, werte: INVOICE_LIST_STATUS },
-        docType: { typ: 'enum', pflicht: false, werte: DOC_TYPES },
+        status: { type: 'enum', required: false, values: INVOICE_LIST_STATUS },
+        docType: { type: 'enum', required: false, values: DOC_TYPES },
         customerId: id,
         limit,
         cursor,
@@ -480,30 +542,30 @@ export const RECHNUNG_ANFRAGEN = Object.freeze({
     getInvoicePdf: {
         invoiceId: idPflicht,
         /** Andere Sprache als die der Rechnung: gekennzeichnete Uebersetzungskopie, keine eigene Rechnung. */
-        language: { typ: 'enum', pflicht: false, werte: INVOICE_LANGUAGES },
+        language: { type: 'enum', required: false, values: INVOICE_LANGUAGES },
     },
     getInvoiceXml: {
         invoiceId: idPflicht,
-        format: { typ: 'enum', pflicht: false, werte: EINVOICE_FORMATS },
+        format: { type: 'enum', required: false, values: EINVOICE_FORMATS },
     },
     getInvoiceSetupStatus: {},
     listBrands: {},
     recordInvoicePayment: {
         idempotencyKey: idempotencyKey(true),
         invoiceId: idPflicht,
-        method: { typ: 'enum', pflicht: true, werte: INVOICE_PAYMENT_METHODS },
-        amountCents: { typ: 'integer', pflicht: false, min: 1, max: 100_000_000 },
+        method: { type: 'enum', required: true, values: INVOICE_PAYMENT_METHODS },
+        amountCents: { type: 'integer', required: false, min: 1, max: 100_000_000 },
         paidAt: datum(),
         reference: text(100),
-        onSite: { typ: 'boolean', pflicht: false },
+        onSite: { type: 'boolean', required: false },
     },
 });
 /** Genau eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */
-export const RECHNUNG_GENAU_EINS = Object.freeze({
+export const INVOICE_EXACTLY_ONE = Object.freeze({
     getCustomer: [['customerId', 'externalId']],
     getInvoice: [['invoiceId', 'number']],
 });
 /** Mindestens eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */
-export const RECHNUNG_MINDESTENS_EINS = Object.freeze({
+export const INVOICE_AT_LEAST_ONE = Object.freeze({
     searchCustomers: [['externalId', 'vatId', 'email', 'name']],
 });

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

@@ -1,3 +1,4 @@
+import { KasseneckApiError } from '../client/errors.js';
 import type { Receipt } from './receipt.js';
 /**
  * Storno-Metadaten — Zwilling von `functions/storno-core.js`.
@@ -8,39 +9,53 @@ import type { Receipt } from './receipt.js';
  * 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 declare const CANCELLATION_REASONS: Readonly<{
-    readonly fehleingabe: "Fehleingabe";
-    readonly kunde_storniert: "Kunde hat storniert";
-    readonly falsche_zahlart: "Falsche Zahlart";
-    readonly doppelt_erfasst: "Doppelt erfasst";
-    readonly sonstiges: "Sonstiges";
+    readonly input_error: "Fehleingabe";
+    readonly customer_cancelled: "Kunde hat storniert";
+    readonly wrong_payment_method: "Falsche Zahlart";
+    readonly duplicate: "Doppelt erfasst";
+    readonly other: "Sonstiges";
 }>;
 export type CancellationReason = keyof typeof CANCELLATION_REASONS;
 export declare function isCancellationReason(value: unknown): value is CancellationReason;
 /**
- * Stabile Fehlercodes von `cancelReceipt` — Zwilling von
- * `functions/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_…`-Codes am Ende gehoeren zur Rueckzahlung je Zahlung
- * (mehrere Zahlungen je Beleg); Formfehler an `payments` selbst melden die
- * Codes aus [PAYMENT_ERROR_CODES].
- *
- * 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 declare const CANCELLATION_ERROR_CODES: readonly ["beleg_nicht_gefunden", "belegart_nicht_stornierbar", "trainingsbeleg", "bereits_storniert", "position_ungueltig", "menge_ueber_rest", "grund_unbekannt", "anmerkung_zu_lang", "items_ungueltig", "kasse_nicht_zugewiesen", "keine_berechtigung", "nur_eigene_belege", "kasse_unvollstaendig", "storno_fehlgeschlagen", "STORNO_PAYMENTS_REQUIRED", "STORNO_REFUND_EXCEEDS_PAYMENT", "STORNO_REFUND_REFERENCE_REQUIRED", "STORNO_REFUND_REFERENCE_UNKNOWN"];
+export declare const CANCELLATION_ERROR_CODES: readonly ["receipt_not_found", "receipt_type_not_cancellable", "training_receipt", "already_cancelled", "invalid_line", "quantity_exceeds_remaining", "unknown_reason", "note_too_long", "invalid_items", "cashregister_not_assigned", "not_permitted", "own_receipts_only", "cashregister_incomplete", "cancellation_failed", "cancellation_payments_required", "cancellation_refund_exceeds_payment", "cancellation_refund_reference_required", "cancellation_refund_reference_unknown", "cancellation_outcome_unknown", "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", "route_missing", "response_unreadable"];
 export type CancellationErrorCode = (typeof CANCELLATION_ERROR_CODES)[number];
 export declare function isCancellationErrorCode(value: unknown): value is CancellationErrorCode;
+/** Der Code eines geworfenen Fehlers, wenn er in [CANCELLATION_ERROR_CODES] steht; sonst `undefined`. */
+export declare function cancellationErrorCode(error: unknown): CancellationErrorCode | undefined;
+/**
+ * Kurzform fuer `catch (e) { if (isCancellationError(e, 'already_cancelled')) … }`.
+ * Ohne `code`: traegt der Fehler ueberhaupt einen Code aus [CANCELLATION_ERROR_CODES]?
+ */
+export declare function isCancellationError(error: unknown, code?: CancellationErrorCode): error is KasseneckApiError;
+/** Stornostand eines Belegs in der Belegliste (Katalog `STORNO_STAND`). */
+export declare const CANCELLATION_STATUSES: readonly ["none", "partial", "full"];
+export type CancellationStatus = (typeof CANCELLATION_STATUSES)[number];
 /** Bezug eines Storno-Belegs auf sein Original. */
 export interface CancellationOf {
     receiptId: string;
@@ -78,6 +93,16 @@ export interface Cancellation {
      * nichts gewaehrt (Altbestand vor dieser Regel) — der naechste Storno holt nach.
      */
     promoAdjustmentCents?: Record<string, number>;
+    /**
+     * Rueckzahlung je Zahlung, die DIESER Storno-Eintrag auf eine Zahlung des
+     * Originals verbucht hat (`refundOf`) -- Zahlungs-ID auf positive Cent,
+     * Zwilling von `functions/gemeinsam/storno-core.js` `refundedByPayment`.
+     * Ueber alle Eintraege darf je Zahlung nie mehr zurueck, als bezahlt wurde
+     * (siehe dort `restJeZahlung`). Ein Eintrag ohne das Feld (vor dieser Regel
+     * oder ohne Zahlungsmodell gebucht) zaehlt dabei 0 je Zahlung. Auch am
+     * `pending`-Eintrag vorhanden, sobald reserviert wird.
+     */
+    refundedByPayment?: Record<string, number>;
 }
 /** Ab wann eine liegengebliebene Reservierung nicht mehr zaehlt (wie im Backend). */
 export declare const CANCELLATION_RESERVATION_MS = 120000;
@@ -87,3 +112,10 @@ export declare const CANCELLATION_RESERVATION_MS = 120000;
  * (Reste anzeigen, bevor der Server gefragt wird). Die Wahrheit hat der Server.
  */
 export declare function remainingQuantities(receipt: Receipt, nowMs?: number): number[];
+/** Ein Feldfehler aus `data.errors[]` einer `validation`-Antwort von `cancelReceipt`. */
+export interface CancellationFieldError {
+    field: string;
+    message: string;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export declare function cancellationFieldErrors(error: unknown): CancellationFieldError[];