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

package/dist/cjs/{rechnung/rechnen.js → invoice/calc.js}

@@ -20,48 +20,48 @@
  * Spec: docs/specs/2026-09-17-rechnung-ganzzahlen-design.md § 5.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RechenFehler = exports.STEUERFREIE_FAELLE = exports.BETRAG_GRENZE_CENTS = void 0;
-exports.rund = rund;
-exports.rechnungRechnen = rechnungRechnen;
-exports.positionAusEuro = positionAusEuro;
-exports.anteiligerPreis = anteiligerPreis;
-exports.satzSchluessel = satzSchluessel;
-exports.satzText = satzText;
-exports.preisText = preisText;
+exports.CalcError = exports.ZERO_RATED_TAX_SCHEMES = exports.MAX_AMOUNT_CENTS = void 0;
+exports.roundDiv = roundDiv;
+exports.calculateInvoice = calculateInvoice;
+exports.itemFromEuro = itemFromEuro;
+exports.proratedPriceMicros = proratedPriceMicros;
+exports.vatRateMapKey = vatRateMapKey;
+exports.formatVatRate = formatVatRate;
+exports.formatUnitPrice = formatUnitPrice;
 /** Skala des Zeilenbruchs: 10⁻¹⁷ Cent. */
 const E = 10n ** 17n;
 /** Hoechster Betrag je Zeile und je Rechnung: 999.999.999,99 €. */
-exports.BETRAG_GRENZE_CENTS = 99_999_999_999;
+exports.MAX_AMOUNT_CENTS = 99_999_999_999;
 /** Steuerfaelle, in denen die Rechnung keine Steuer ausweist: jede Zeile zaehlt zu 0 %. */
-exports.STEUERFREIE_FAELLE = Object.freeze([
+exports.ZERO_RATED_TAX_SCHEMES = Object.freeze([
     'smallBusiness',
     'reverseCharge',
-    'igLieferung',
+    'intraCommunitySupply',
     'exportThirdCountry',
     'domesticReverseCharge',
     'outsideScope',
 ]);
 /** Fehler des Kerns — mit Code, Feld und Index, damit die API daraus einen Feldfehler machen kann. */
-class RechenFehler extends Error {
+class CalcError extends Error {
     code;
-    feld;
+    field;
     index;
-    constructor(code, nachricht, feld, index) {
-        super(nachricht);
-        this.name = 'RechenFehler';
+    constructor(code, message, field, index) {
+        super(message);
+        this.name = 'CalcError';
         this.code = code;
-        this.feld = feld;
+        this.field = field;
         this.index = index;
     }
 }
-exports.RechenFehler = RechenFehler;
+exports.CalcError = CalcError;
 /**
  * `a / b` kaufmaennisch gerundet, halbe Einheit vom Nullpunkt weg; `b` > 0.
  *
  * Ohne Gleitkomma: `(2·|a| + b) / (2·b)` ist genau dann eins groesser, wenn der
  * Rest mindestens die halbe Einheit betraegt.
  */
-function rund(a, b) {
+function roundDiv(a, b) {
     const negativ = a < 0n;
     const betrag = negativ ? -a : a;
     const ganz = (2n * betrag + b) / (2n * b);
@@ -75,11 +75,11 @@ const GRENZEN = {
 };
 function ganzzahl(wert, feld, index) {
     if (typeof wert !== 'number' || !Number.isInteger(wert)) {
-        throw new RechenFehler('kein_ganzzahlwert', `items[${index}].${feld} muss eine ganze Zahl sein`, feld, index);
+        throw new CalcError('not_integer', `items[${index}].${feld} muss eine ganze Zahl sein`, feld, index);
     }
     const [min, max] = GRENZEN[feld];
     if (wert < min || wert > max) {
-        throw new RechenFehler('ausserhalb', `items[${index}].${feld} liegt ausserhalb von ${min} … ${max}`, feld, index);
+        throw new CalcError('out_of_range', `items[${index}].${feld} liegt ausserhalb von ${min} … ${max}`, feld, index);
     }
     return wert;
 }
@@ -95,7 +95,7 @@ function ganzzahl(wert, feld, index) {
 function verteile(gruppe, feld, faktor, nenner, ziel) {
     const werte = gruppe.map((z) => {
         const zaehler = z.L * faktor;
-        return { z, zaehler, wert: rund(zaehler, nenner) };
+        return { z, zaehler, wert: roundDiv(zaehler, nenner) };
     });
     let rest = ziel - werte.reduce((s, w) => s + w.wert, 0n);
     if (rest !== 0n) {
@@ -117,18 +117,18 @@ function verteile(gruppe, feld, faktor, nenner, ziel) {
     for (const w of werte)
         w.z[feld] = Number(w.wert);
 }
-function rechnungRechnen(positionen, optionen) {
-    const steuerfrei = exports.STEUERFREIE_FAELLE.includes(optionen.taxScheme ?? 'normal');
-    const bruttoPreise = optionen.priceMode === 'gross' && !steuerfrei;
-    const grenze = BigInt(exports.BETRAG_GRENZE_CENTS) * E;
-    const zeilen = positionen.map((p, index) => {
+function calculateInvoice(items, options) {
+    const steuerfrei = exports.ZERO_RATED_TAX_SCHEMES.includes(options.taxScheme ?? 'normal');
+    const bruttoPreise = options.priceMode === 'gross' && !steuerfrei;
+    const grenze = BigInt(exports.MAX_AMOUNT_CENTS) * E;
+    const zeilen = items.map((p, index) => {
         const preis = BigInt(ganzzahl(p.unitPriceMicros, 'unitPriceMicros', index));
         const menge = BigInt(ganzzahl(p.quantityMilli, 'quantityMilli', index));
         const rabatt = BigInt(ganzzahl(p.discountBp ?? 0, 'discountBp', index));
         const satz = ganzzahl(p.vatRateBp ?? 0, 'vatRateBp', index);
         const L = preis * menge * (10000n - rabatt) * 1000000n;
         if ((L < 0n ? -L : L) > grenze) {
-            throw new RechenFehler('amount_too_large', `items[${index}] uebersteigt ${exports.BETRAG_GRENZE_CENTS} Cent`, 'unitPriceMicros', index);
+            throw new CalcError('amount_too_large', `items[${index}] uebersteigt ${exports.MAX_AMOUNT_CENTS} Cent`, 'unitPriceMicros', index);
         }
         return { index, rateBp: steuerfrei ? 0 : satz, L, netCents: 0, grossCents: 0 };
     });
@@ -148,13 +148,13 @@ function rechnungRechnen(positionen, optionen) {
         let vatCents;
         let grossCents;
         if (bruttoPreise) {
-            grossCents = rund(S, E);
-            netCents = rund(grossCents * 10000n, 10000n + r);
+            grossCents = roundDiv(S, E);
+            netCents = roundDiv(grossCents * 10000n, 10000n + r);
             vatCents = grossCents - netCents;
         }
         else {
-            netCents = rund(S, E);
-            vatCents = rund(S * r, E * 10000n);
+            netCents = roundDiv(S, E);
+            vatCents = roundDiv(S * r, E * 10000n);
             grossCents = netCents + vatCents;
         }
         if (bruttoPreise) {
@@ -182,8 +182,8 @@ function rechnungRechnen(positionen, optionen) {
         lines: zeilen.map((z) => ({ netCents: z.netCents, grossCents: z.grossCents, rateBp: z.rateBp })),
     };
     for (const feld of ['netCents', 'vatCents', 'grossCents']) {
-        if (Math.abs(ergebnis[feld]) > exports.BETRAG_GRENZE_CENTS) {
-            throw new RechenFehler('amount_too_large', `Die Rechnung uebersteigt ${exports.BETRAG_GRENZE_CENTS} Cent (${feld})`);
+        if (Math.abs(ergebnis[feld]) > exports.MAX_AMOUNT_CENTS) {
+            throw new CalcError('amount_too_large', `Die Rechnung uebersteigt ${exports.MAX_AMOUNT_CENTS} Cent (${feld})`);
         }
     }
     return ergebnis;
@@ -235,47 +235,47 @@ const EURO_FELDER = ['unitPrice', 'quantity', 'vatRate', 'discountPct'];
  * abgerechnet hat. Ein fehlender Preis dagegen ist NIE 0: sonst wuerde eine
  * Position, der nur der Preis fehlt, still zur 0-€-Zeile.
  */
-function positionAusEuro(item) {
+function itemFromEuro(item) {
     if (typeof item.unitPriceMicros === 'number') {
-        return { ok: true, position: item };
+        return { ok: true, item: item };
     }
     const roh = item.unitPrice;
     if (typeof roh !== 'number' || !Number.isFinite(roh)) {
-        return { ok: false, feld: 'unitPrice', grund: 'kein_zahlwert' };
+        return { ok: false, field: 'unitPrice', reason: 'not_a_number' };
     }
     const micros = ganzAusDezimaltext(Math.abs(roh), 6);
     if (micros === null)
-        return { ok: false, feld: 'unitPrice', grund: 'nachkommastellen' };
+        return { ok: false, field: 'unitPrice', reason: 'too_many_decimals' };
     if (micros > GRENZEN.unitPriceMicros[1])
-        return { ok: false, feld: 'unitPrice', grund: 'ausserhalb' };
+        return { ok: false, field: 'unitPrice', reason: 'out_of_range' };
     const zahl = (feld, stellen, max) => {
         const w = item[feld];
         if (w === undefined || w === null)
             return { ok: true, wert: 0 };
         if (typeof w !== 'number' || !Number.isFinite(w))
-            return { ok: false, grund: 'kein_zahlwert' };
+            return { ok: false, grund: 'not_a_number' };
         const ganz = ganzAusDezimaltext(w, stellen);
         if (ganz === null)
-            return { ok: false, grund: 'nachkommastellen' };
+            return { ok: false, grund: 'too_many_decimals' };
         if (ganz < (feld === 'quantity' ? -max : 0) || ganz > max)
-            return { ok: false, grund: 'ausserhalb' };
+            return { ok: false, grund: 'out_of_range' };
         return { ok: true, wert: ganz };
     };
     const menge = zahl('quantity', 3, GRENZEN.quantityMilli[1]);
     if (!menge.ok)
-        return { ok: false, feld: 'quantity', grund: menge.grund };
+        return { ok: false, field: 'quantity', reason: menge.grund };
     const satz = zahl('vatRate', 2, 10_000);
     if (!satz.ok)
-        return { ok: false, feld: 'vatRate', grund: satz.grund };
+        return { ok: false, field: 'vatRate', reason: satz.grund };
     const rabatt = zahl('discountPct', 2, 10_000);
     if (!rabatt.ok)
-        return { ok: false, feld: 'discountPct', grund: rabatt.grund };
+        return { ok: false, field: 'discountPct', reason: rabatt.grund };
     const rest = { ...item };
     for (const feld of EURO_FELDER)
         delete rest[feld];
     return {
         ok: true,
-        position: {
+        item: {
             ...rest,
             unitPriceMicros: micros,
             quantityMilli: roh < 0 ? -menge.wert : menge.wert,
@@ -290,32 +290,32 @@ function positionAusEuro(item) {
  * stuende auf der ersten Rechnung ein Preis mit sechs Stellen, wo bisher zwei
  * standen.
  */
-function anteiligerPreis(unitPriceMicros, monate, intervall) {
+function proratedPriceMicros(unitPriceMicros, months, interval) {
     const micros = BigInt(unitPriceMicros);
-    const anteil = rund(micros * BigInt(monate), BigInt(intervall));
+    const anteil = roundDiv(micros * BigInt(months), BigInt(interval));
     if (unitPriceMicros % 10_000 !== 0)
         return Number(anteil);
-    return Number(rund(anteil, 10000n) * 10000n);
+    return Number(roundDiv(anteil, 10000n) * 10000n);
 }
 /**
  * Schluessel eines USt-Satzes in den gespeicherten Maps (`creditedCents.byRate`,
  * `invoice_stats.vatByRate`): der Prozenttext mit Punkt, genau wie
  * `String(satz)` ihn bisher gebildet hat. NICHT fuer die Anzeige — dafuer gibt
- * es `satzText`.
+ * es `formatVatRate`.
  */
-function satzSchluessel(rateBp) {
+function vatRateMapKey(rateBp) {
     return String(rateBp / 100);
 }
 /** Ein USt-Satz fuer die Anzeige: oesterreichisch mit Komma, ohne nachlaufende Nullen. */
-function satzText(rateBp) {
-    return satzSchluessel(rateBp).replace('.', ',');
+function formatVatRate(rateBp) {
+    return vatRateMapKey(rateBp).replace('.', ',');
 }
 /**
  * Ein Einzelpreis fuer die Anzeige: mindestens zwei, hoechstens sechs
  * Nachkommastellen, Tausenderpunkt, Komma als Trennzeichen — in jeder Sprache
  * oesterreichisch, wie die Betraege auf dem Blatt.
  */
-function preisText(unitPriceMicros) {
+function formatUnitPrice(unitPriceMicros) {
     const negativ = unitPriceMicros < 0;
     const betrag = Math.abs(unitPriceMicros);
     const ganz = Math.trunc(betrag / 1_000_000);

package/dist/{esm/rechnung → cjs/invoice}/endpunkte.d.ts

@@ -2,7 +2,7 @@
  * Die Aufrufe der Rechnungs-API — Kunden, Rechnungen, Gutschriften, Dateien.
  *
  * Jede Funktion nimmt den Transport als ersten Parameter und ist einzeln
- * importierbar; die Fassade [createRechnungApi] bindet ihn nur einmal.
+ * importierbar; die Fassade [createInvoiceApi] bindet ihn nur einmal.
  *
  * **Geprueft wird hier nichts Fachliches.** Die Anfrage geht unveraendert an
  * das Backend, das sie gegen denselben Vertrag prueft (`vertrag.ts`) und einen
@@ -17,19 +17,19 @@
  * der Aufruf `KasseneckValidationError` mit `scope:'response'`.
  */
 import type { InternerBinaerTransport, InternerTransport } from '../client/aufrufe.js';
-import type { EInvoiceFormat, InvoiceLanguage } from './vertrag.js';
-import type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, IssueInvoiceRequest, IssueResult, PreviewResult, RecordPaymentRequest, RecordPaymentResult } from './typen.js';
-export declare function createCustomer(rufen: InternerTransport, customer: CustomerInput, optionen?: {
+import { type EInvoiceFormat, type InvoiceLanguage } from './vertrag.js';
+import type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, InvoiceXml, IssueInvoiceRequest, IssueResult, PreviewResult, RecordPaymentRequest, RecordPaymentResult } from './typen.js';
+export declare function createCustomer(transport: InternerTransport, customer: CustomerInput, options?: {
     idempotencyKey?: string;
 }): Promise<Customer>;
-export declare function getCustomer(rufen: InternerTransport, kennung: {
+export declare function getCustomer(transport: InternerTransport, ref: {
     customerId: string;
 } | {
     externalId: string;
 }): Promise<Customer>;
-export declare function updateCustomer(rufen: InternerTransport, customerId: string, patch: Partial<CustomerInput>): Promise<Customer>;
-export declare function searchCustomers(rufen: InternerTransport, suche: CustomerSearch): Promise<CustomerPage>;
-export declare function issueInvoice(rufen: InternerTransport, anfrage: IssueInvoiceRequest): Promise<IssueResult>;
+export declare function updateCustomer(transport: InternerTransport, customerId: string, patch: Partial<CustomerInput>): Promise<Customer>;
+export declare function searchCustomers(transport: InternerTransport, search: CustomerSearch): Promise<CustomerPage>;
+export declare function issueInvoice(transport: InternerTransport, request: IssueInvoiceRequest): Promise<IssueResult>;
 /**
  * Probelauf von `issueInvoice`: dieselbe Anfrage wird geprueft und gerechnet
  * wie beim Ausstellen, aber nichts festgeschrieben. Die Antwort nennt Summen,
@@ -40,28 +40,28 @@ export declare function issueInvoice(rufen: InternerTransport, anfrage: IssueInv
  * danach unveraendert ausstellen. Verbindlich ist das Ausstellen — zwischen
  * Probelauf und Ausstellen kann sich der Kunde oder das Konto aendern.
  */
-export declare function previewInvoice(rufen: InternerTransport, anfrage: IssueInvoiceRequest): Promise<PreviewResult>;
-export declare function cancelInvoice(rufen: InternerTransport, anfrage: CancelInvoiceRequest): Promise<CancelResult>;
-export declare function createCreditNote(rufen: InternerTransport, anfrage: CreditNoteRequest): Promise<CreditNoteResult>;
-export declare function getInvoice(rufen: InternerTransport, kennung: {
+export declare function previewInvoice(transport: InternerTransport, request: IssueInvoiceRequest): Promise<PreviewResult>;
+export declare function cancelInvoice(transport: InternerTransport, request: CancelInvoiceRequest): Promise<CancelResult>;
+export declare function createCreditNote(transport: InternerTransport, request: CreditNoteRequest): Promise<CreditNoteResult>;
+export declare function getInvoice(transport: InternerTransport, ref: {
     invoiceId: string;
 } | {
     number: string;
 }): Promise<InvoiceDetail>;
-export declare function listInvoices(rufen: InternerTransport, abfrage?: InvoiceListQuery): Promise<InvoicePage>;
+export declare function listInvoices(transport: InternerTransport, query?: InvoiceListQuery): Promise<InvoicePage>;
 /**
  * Darf dieses Konto ueber die API ausstellen, und was fehlt noch? Laeuft auch
  * ohne Freigabe und vor der Live-Freischaltung — genau dann braucht man die
  * Antwort. Vor dem ersten `issueInvoice` aufrufen und `missing` anzeigen.
  */
-export declare function getInvoiceSetupStatus(rufen: InternerTransport): Promise<InvoiceSetupStatus>;
+export declare function getInvoiceSetupStatus(transport: InternerTransport): Promise<InvoiceSetupStatus>;
 /**
  * Das PDF der Rechnung (bei Gutschriften: der Gutschrift), mit eingebetteter
  * Factur-X-Datei. Mit `language` in der anderen Sprache als der Rechnung kommt
  * eine **Uebersetzungskopie**: dieselbe Nummer, auf jeder Seite als Uebersetzung
  * gekennzeichnet, ohne eingebettete E-Rechnung — keine eigene Rechnung.
  */
-export declare function getInvoicePdf(rufenBinaer: InternerBinaerTransport, invoiceId: string, optionen?: {
+export declare function getInvoicePdf(binaryTransport: InternerBinaerTransport, invoiceId: string, options?: {
     language?: InvoiceLanguage;
 }): Promise<Uint8Array>;
 /**
@@ -73,12 +73,14 @@ export declare function getInvoicePdf(rufenBinaer: InternerBinaerTransport, invo
  * zusaetzlich `notice` — eine Barzahlung ist ein Barumsatz und braucht einen
  * Beleg (§ 132a BAO), den dieser Vermerk nicht ersetzt.
  */
-export declare function recordInvoicePayment(rufen: InternerTransport, anfrage: RecordPaymentRequest): Promise<RecordPaymentResult>;
+export declare function recordInvoicePayment(transport: InternerTransport, request: RecordPaymentRequest): Promise<RecordPaymentResult>;
 /** Die Marken des Kontos — die Kennung geht als `brandId` in `issueInvoice`. */
-export declare function listBrands(rufen: InternerTransport): Promise<Brand[]>;
+export declare function listBrands(transport: InternerTransport): Promise<Brand[]>;
 /**
- * Die E-Rechnung als XML-Text. Sie kommt im gewohnten Umschlag (`data.xml`)
- * und nicht als rohe Datei: so bleibt ein fachlicher Fehler
- * (`einvoice_incomplete` mit `missing[]`) ein gewoehnlicher Fehler.
+ * Die E-Rechnung samt Format und Dateiname, genau wie der Server sie schickt.
+ * Sie kommt im gewohnten Umschlag (`data.xml`) und nicht als rohe Datei: so
+ * bleibt ein fachlicher Fehler (`einvoice_incomplete` mit `missing[]`) ein
+ * gewoehnlicher Fehler. Den Dateinamen nicht selbst bauen, sondern
+ * `filename` nehmen (`invoice-<Nummer>.xml`).
  */
-export declare function getInvoiceXml(rufen: InternerTransport, invoiceId: string, format?: EInvoiceFormat): Promise<string>;
+export declare function getInvoiceXml(transport: InternerTransport, invoiceId: string, format?: EInvoiceFormat): Promise<InvoiceXml>;

package/dist/cjs/{rechnung → invoice}/endpunkte.js

@@ -3,7 +3,7 @@
  * Die Aufrufe der Rechnungs-API — Kunden, Rechnungen, Gutschriften, Dateien.
  *
  * Jede Funktion nimmt den Transport als ersten Parameter und ist einzeln
- * importierbar; die Fassade [createRechnungApi] bindet ihn nur einmal.
+ * importierbar; die Fassade [createInvoiceApi] bindet ihn nur einmal.
  *
  * **Geprueft wird hier nichts Fachliches.** Die Anfrage geht unveraendert an
  * das Backend, das sie gegen denselben Vertrag prueft (`vertrag.ts`) und einen
@@ -34,6 +34,7 @@ exports.recordInvoicePayment = recordInvoicePayment;
 exports.listBrands = listBrands;
 exports.getInvoiceXml = getInvoiceXml;
 const errors_js_1 = require("../client/errors.js");
+const vertrag_js_1 = require("./vertrag.js");
 function objekt(wert) {
     return wert !== null && typeof wert === 'object' && !Array.isArray(wert)
         ? wert
@@ -86,30 +87,30 @@ function kennungVerlangen(aufruf, kennung, felder) {
 /** Anfrageobjekt als Nutzlast — flache Kopie, damit der Aufrufer sein Objekt behaelt. */
 const nutzlast = (anfrage) => ({ ...anfrage });
 // ---- Kunden -----------------------------------------------------------------
-async function createCustomer(rufen, customer, optionen = {}) {
+async function createCustomer(transport, customer, options = {}) {
     const params = { customer };
-    if (optionen.idempotencyKey)
-        params['idempotencyKey'] = optionen.idempotencyKey;
-    const daten = await rufen('createCustomer', params);
+    if (options.idempotencyKey)
+        params['idempotencyKey'] = options.idempotencyKey;
+    const daten = await transport('createCustomer', params);
     return pflichtObjekt('createCustomer', daten, 'customer');
 }
-async function getCustomer(rufen, kennung) {
-    kennungVerlangen('getCustomer', kennung, '{ customerId } oder { externalId }');
-    const daten = await rufen('getCustomer', nutzlast(kennung));
+async function getCustomer(transport, ref) {
+    kennungVerlangen('getCustomer', ref, '{ customerId } oder { externalId }');
+    const daten = await transport('getCustomer', nutzlast(ref));
     return pflichtObjekt('getCustomer', daten, 'customer');
 }
-async function updateCustomer(rufen, customerId, patch) {
-    const daten = await rufen('updateCustomer', { customerId, customer: patch });
+async function updateCustomer(transport, customerId, patch) {
+    const daten = await transport('updateCustomer', { customerId, customer: patch });
     return pflichtObjekt('updateCustomer', daten, 'customer');
 }
-async function searchCustomers(rufen, suche) {
-    const daten = await rufen('searchCustomers', nutzlast(suche));
+async function searchCustomers(transport, search) {
+    const daten = await transport('searchCustomers', nutzlast(search));
     const { eintraege, nextCursor } = seite('searchCustomers', daten, 'customers');
     return { customers: eintraege, nextCursor };
 }
 // ---- Rechnungen -------------------------------------------------------------
-async function issueInvoice(rufen, anfrage) {
-    const daten = await rufen('issueInvoice', nutzlast(anfrage));
+async function issueInvoice(transport, request) {
+    const daten = await transport('issueInvoice', nutzlast(request));
     const ergebnis = {
         invoice: pflichtObjekt('issueInvoice', daten, 'invoice'),
         replayed: objekt(daten)['replayed'] === true,
@@ -129,16 +130,16 @@ async function issueInvoice(rufen, anfrage) {
  * danach unveraendert ausstellen. Verbindlich ist das Ausstellen — zwischen
  * Probelauf und Ausstellen kann sich der Kunde oder das Konto aendern.
  */
-async function previewInvoice(rufen, anfrage) {
-    const daten = await rufen('issueInvoice', { ...nutzlast(anfrage), dryRun: true });
+async function previewInvoice(transport, request) {
+    const daten = await transport('issueInvoice', { ...nutzlast(request), dryRun: true });
     const ergebnis = { preview: pflichtObjekt('issueInvoice', daten, 'preview') };
     const notice = hinweise(daten);
     if (notice)
         ergebnis.notice = notice;
     return ergebnis;
 }
-async function cancelInvoice(rufen, anfrage) {
-    const daten = await rufen('cancelInvoice', nutzlast(anfrage));
+async function cancelInvoice(transport, request) {
+    const daten = await transport('cancelInvoice', nutzlast(request));
     return {
         creditNote: pflichtObjekt('cancelInvoice', daten, 'creditNote'),
         original: pflichtObjekt('cancelInvoice', daten, 'original'),
@@ -146,21 +147,21 @@ async function cancelInvoice(rufen, anfrage) {
         replayed: objekt(daten)['replayed'] === true,
     };
 }
-async function createCreditNote(rufen, anfrage) {
-    const daten = await rufen('createCreditNote', nutzlast(anfrage));
+async function createCreditNote(transport, request) {
+    const daten = await transport('createCreditNote', nutzlast(request));
     return {
         creditNote: pflichtObjekt('createCreditNote', daten, 'creditNote'),
         remainingCents: zahl(objekt(daten)['remainingCents']),
         replayed: objekt(daten)['replayed'] === true,
     };
 }
-async function getInvoice(rufen, kennung) {
-    kennungVerlangen('getInvoice', kennung, '{ invoiceId } oder { number }');
-    const daten = await rufen('getInvoice', nutzlast(kennung));
+async function getInvoice(transport, ref) {
+    kennungVerlangen('getInvoice', ref, '{ invoiceId } oder { number }');
+    const daten = await transport('getInvoice', nutzlast(ref));
     return pflichtObjekt('getInvoice', daten, 'invoice');
 }
-async function listInvoices(rufen, abfrage = {}) {
-    const daten = await rufen('listInvoices', nutzlast(abfrage));
+async function listInvoices(transport, query = {}) {
+    const daten = await transport('listInvoices', nutzlast(query));
     const { eintraege, nextCursor } = seite('listInvoices', daten, 'invoices');
     return { invoices: eintraege, nextCursor };
 }
@@ -170,8 +171,8 @@ async function listInvoices(rufen, abfrage = {}) {
  * ohne Freigabe und vor der Live-Freischaltung — genau dann braucht man die
  * Antwort. Vor dem ersten `issueInvoice` aufrufen und `missing` anzeigen.
  */
-async function getInvoiceSetupStatus(rufen) {
-    const daten = objekt(await rufen('getInvoiceSetupStatus', {}));
+async function getInvoiceSetupStatus(transport) {
+    const daten = objekt(await transport('getInvoiceSetupStatus', {}));
     if (typeof daten['ready'] !== 'boolean' || !Array.isArray(daten['missing'])) {
         throw new errors_js_1.KasseneckValidationError('getInvoiceSetupStatus', 'Antwort ohne ready/missing', 'response');
     }
@@ -188,11 +189,11 @@ async function getInvoiceSetupStatus(rufen) {
  * eine **Uebersetzungskopie**: dieselbe Nummer, auf jeder Seite als Uebersetzung
  * gekennzeichnet, ohne eingebettete E-Rechnung — keine eigene Rechnung.
  */
-function getInvoicePdf(rufenBinaer, invoiceId, optionen = {}) {
+function getInvoicePdf(binaryTransport, invoiceId, options = {}) {
     const params = { invoiceId };
-    if (optionen.language)
-        params['language'] = optionen.language;
-    return rufenBinaer('getInvoicePdf', params);
+    if (options.language)
+        params['language'] = options.language;
+    return binaryTransport('getInvoicePdf', params);
 }
 /**
  * Eine Zahlung nachtragen, die nach dem Ausstellen eingetroffen ist
@@ -203,8 +204,8 @@ function getInvoicePdf(rufenBinaer, invoiceId, optionen = {}) {
  * zusaetzlich `notice` — eine Barzahlung ist ein Barumsatz und braucht einen
  * Beleg (§ 132a BAO), den dieser Vermerk nicht ersetzt.
  */
-async function recordInvoicePayment(rufen, anfrage) {
-    const daten = await rufen('recordInvoicePayment', nutzlast(anfrage));
+async function recordInvoicePayment(transport, request) {
+    const daten = await transport('recordInvoicePayment', nutzlast(request));
     const roh = objekt(daten);
     const ergebnis = {
         invoice: pflichtObjekt('recordInvoicePayment', daten, 'invoice'),
@@ -217,22 +218,31 @@ async function recordInvoicePayment(rufen, anfrage) {
     return ergebnis;
 }
 /** Die Marken des Kontos — die Kennung geht als `brandId` in `issueInvoice`. */
-async function listBrands(rufen) {
-    const brands = objekt(await rufen('listBrands', {}))['brands'];
+async function listBrands(transport) {
+    const brands = objekt(await transport('listBrands', {}))['brands'];
     if (!Array.isArray(brands))
         throw new errors_js_1.KasseneckValidationError('listBrands', 'Antwort ohne brands', 'response');
     return brands;
 }
 /**
- * Die E-Rechnung als XML-Text. Sie kommt im gewohnten Umschlag (`data.xml`)
- * und nicht als rohe Datei: so bleibt ein fachlicher Fehler
- * (`einvoice_incomplete` mit `missing[]`) ein gewoehnlicher Fehler.
+ * Die E-Rechnung samt Format und Dateiname, genau wie der Server sie schickt.
+ * Sie kommt im gewohnten Umschlag (`data.xml`) und nicht als rohe Datei: so
+ * bleibt ein fachlicher Fehler (`einvoice_incomplete` mit `missing[]`) ein
+ * gewoehnlicher Fehler. Den Dateinamen nicht selbst bauen, sondern
+ * `filename` nehmen (`invoice-<Nummer>.xml`).
  */
-async function getInvoiceXml(rufen, invoiceId, format = 'ubl') {
-    const daten = await rufen('getInvoiceXml', { invoiceId, format });
-    const xml = objekt(daten)['xml'];
+async function getInvoiceXml(transport, invoiceId, format = 'ubl') {
+    const daten = objekt(await transport('getInvoiceXml', { invoiceId, format }));
+    const { xml, filename } = daten;
+    const gesendet = daten['format'];
     if (typeof xml !== 'string' || !xml) {
         throw new errors_js_1.KasseneckValidationError('getInvoiceXml', 'Antwort ohne xml', 'response');
     }
-    return xml;
+    if (typeof gesendet !== 'string' || !vertrag_js_1.EINVOICE_FORMATS.includes(gesendet)) {
+        throw new errors_js_1.KasseneckValidationError('getInvoiceXml', 'Antwort ohne gueltiges format', 'response');
+    }
+    if (typeof filename !== 'string' || !filename) {
+        throw new errors_js_1.KasseneckValidationError('getInvoiceXml', 'Antwort ohne filename', 'response');
+    }
+    return { xml, format: gesendet, filename };
 }

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

@@ -0,0 +1,31 @@
+/**
+ * Fehler der Rechnungs-API auswerten: am Code, nie am Text.
+ *
+ * Es zaehlen die Codes des Vertrags ([INVOICE_ERROR_CODES]) und die, die
+ * Anmeldung und Rand auf jedem Rechnungsaufruf erzeugen koennen
+ * ([INVOICE_REQUEST_ERROR_CODES], z. B. `dialect_mismatch`, `not_found`,
+ * `route_missing`). Ein fremder Code ist fuer diese Helfer kein
+ * Rechnungs-Fehler: wer darauf verzweigt, soll es bewusst ueber
+ * `KasseneckApiError.code` tun.
+ */
+import type { KasseneckApiError } from '../client/errors.js';
+import { type InvoiceErrorCode, type InvoiceRequestErrorCode } from './vertrag.js';
+/** Ein Code, den ein Rechnungsaufruf liefern kann. */
+export type InvoiceApiErrorCode = InvoiceErrorCode | InvoiceRequestErrorCode;
+/** `true` fuer einen Code aus [INVOICE_ERROR_CODES] oder [INVOICE_REQUEST_ERROR_CODES]. */
+export declare function isInvoiceErrorCode(value: unknown): value is InvoiceApiErrorCode;
+/** Der Fehlercode eines geworfenen Fehlers; `undefined`, wenn es keiner der Rechnungs-API ist. */
+export declare function invoiceErrorCode(error: unknown): InvoiceApiErrorCode | undefined;
+/**
+ * Kurzform fuer `catch (e) { if (isInvoiceError(e, 'customer_exists')) … }`.
+ * Ohne `code`: ist es ueberhaupt ein Fehler der Rechnungs-API?
+ */
+export declare function isInvoiceError(error: unknown, code?: InvoiceApiErrorCode): error is KasseneckApiError;
+/** Ein Feldfehler aus `data.errors[]` einer `validation`-Antwort. */
+export interface InvoiceFieldError {
+    /** Feldpfad in der gesendeten Anfrage, z. B. `items[2].vatRate` oder `customer.vatId`. */
+    field: string;
+    message: string;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export declare function invoiceFieldErrors(error: unknown): InvoiceFieldError[];

package/dist/cjs/invoice/fehler.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Fehler der Rechnungs-API auswerten: am Code, nie am Text.
+ *
+ * Es zaehlen die Codes des Vertrags ([INVOICE_ERROR_CODES]) und die, die
+ * Anmeldung und Rand auf jedem Rechnungsaufruf erzeugen koennen
+ * ([INVOICE_REQUEST_ERROR_CODES], z. B. `dialect_mismatch`, `not_found`,
+ * `route_missing`). Ein fremder Code ist fuer diese Helfer kein
+ * Rechnungs-Fehler: wer darauf verzweigt, soll es bewusst ueber
+ * `KasseneckApiError.code` tun.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInvoiceErrorCode = isInvoiceErrorCode;
+exports.invoiceErrorCode = invoiceErrorCode;
+exports.isInvoiceError = isInvoiceError;
+exports.invoiceFieldErrors = invoiceFieldErrors;
+const fehlercodes_js_1 = require("../client/fehlercodes.js");
+const vertrag_js_1 = require("./vertrag.js");
+const BEKANNT = new Set([...vertrag_js_1.INVOICE_ERROR_CODES, ...vertrag_js_1.INVOICE_REQUEST_ERROR_CODES]);
+/** `true` fuer einen Code aus [INVOICE_ERROR_CODES] oder [INVOICE_REQUEST_ERROR_CODES]. */
+function isInvoiceErrorCode(value) {
+    return typeof value === 'string' && BEKANNT.has(value);
+}
+/** Der Fehlercode eines geworfenen Fehlers; `undefined`, wenn es keiner der Rechnungs-API ist. */
+function invoiceErrorCode(error) {
+    return (0, fehlercodes_js_1.bekannterCode)(error, BEKANNT);
+}
+/**
+ * Kurzform fuer `catch (e) { if (isInvoiceError(e, 'customer_exists')) … }`.
+ * Ohne `code`: ist es ueberhaupt ein Fehler der Rechnungs-API?
+ */
+function isInvoiceError(error, code) {
+    const gefunden = invoiceErrorCode(error);
+    return gefunden !== undefined && (code === undefined || gefunden === code);
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+function invoiceFieldErrors(error) {
+    return (0, fehlercodes_js_1.feldfehlerVon)(error);
+}

package/dist/cjs/invoice/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@kreiseck/kasseneck-api/invoice` – Rechnungen (§ 11 UStG, keine Belege)
+ * und Kunden ueber die Rechnungs-API.
+ *
+ * Ein eigener Unterpfad wie `partner`: der `api_key` eines Kontos, mit dem
+ * Rechnungen ausgestellt werden, gehoert auf einen **Server** und soll nicht
+ * versehentlich in ein Browser-Buendel der Kasse wandern.
+ *
+ * Die Beschreibung der Endpunkte steht in der Referenz des Backends
+ * (`docs/api/rechnungen.md`). Was hier steht, ist der Vertrag als Daten und die
+ * Benutzung des Clients.
+ */
+export { createInvoiceApi, type InvoiceApi, type InvoiceApiOptions } from './api.js';
+export { invoiceKeyAuth, type InvoiceKeyAuthOptions } from './auth.js';
+export { isInvoiceError, isInvoiceErrorCode, invoiceErrorCode, invoiceFieldErrors, type InvoiceApiErrorCode, type InvoiceFieldError, } from './fehler.js';
+export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, previewInvoice, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
+export type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, EInvoiceStatus, Invoice, InvoiceDetail, InvoiceDetailPayment, InvoiceItem, InvoiceItemInput, InvoiceListQuery, InvoicePage, InvoiceRecipient, InvoiceSetupGap, InvoiceSetupStatus, InvoiceTotals, InvoiceXml, InvoiceNotice, InvoicePayment, InvoicePreview, InvoiceRateTotals, IssueInvoiceRequest, IssueResult, PaymentInput, PreviewResult, RecordPaymentRequest, RecordPaymentResult, } from './typen.js';
+export { INVOICE_TEXTS, invoiceText, type InvoiceTextKey } from './texte.js';
+export { computeInvoiceTotals, ZERO_RATED_TAX_SCHEMES, type TotalsItem } from './summen.js';
+export { proratedPriceMicros, MAX_AMOUNT_CENTS, itemFromEuro, formatUnitPrice, CalcError, calculateInvoice, roundDiv, vatRateMapKey, formatVatRate, type CalcResult, type CalcErrorCode, type CalcOptions, type CalcItem, type RateTotal, type ItemConversion, type ConversionReason, type LineAmount, } from './calc.js';
+export { INVOICE_CONTRACT_VERSION, INVOICE_ENDPOINTS, INVOICE_ERROR_CODES, INVOICE_REQUEST_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, EINVOICE_MISSING_CODES, WRITE_OFF_REASON_CODES, INVOICE_LANGUAGES, INVOICE_PAYMENT_METHODS, ITEM_KINDS, REVERSE_CHARGE_REASONS, INVOICE_NOTICE_CODES, INVOICE_UNITS, INVOICE_UNIT_CODES, INVOICE_SETUP_REQUIREMENTS, CUSTOMER_FIELDS, ITEM_FIELDS, ITEM_PRICE_EXACTLY_ONE, INVOICE_REQUESTS, INVOICE_EXACTLY_ONE, INVOICE_AT_LEAST_ONE, type InvoiceEndpoint, type InvoiceErrorCode, type InvoiceRequestErrorCode, type CreditNoteReason, type TaxScheme, type PriceMode, type VatRatePercent, type CustomerType, type InvoiceListStatus, type DocType, type EInvoiceFormat, type EInvoiceMissingCode, type WriteOffReasonCode, type InvoiceLanguage, type InvoicePaymentMethod, type ItemKind, type ReverseChargeReason, type InvoiceNoticeCode, type InvoiceUnit, type InvoiceSetupRequirement, type FieldFormat, type Field, } from './vertrag.js';