@kreiseck/kasseneck-api 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -4,6 +4,100 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 0.23.0
+
+### Rechnung: der Rechenkern in ganzen Zahlen
+
+**Anlass:** Vier Umsetzungen (Server, dieses Paket, Dart, Panel) mussten dieselbe
+Reihenfolge von Gleitkomma-Schritten nachbauen, damit Grenzfälle gleich runden.
+Ein Cent Unterschied im Brutto-Modus hat das am 16.09.2026 sichtbar gemacht.
+
+- **Neu: Unterpfad `@kreiseck/kasseneck-api/rechnung/rechnen`** — rein, ohne
+  Transport, auch für den Browser. Darin:
+  - `rechnungRechnen(positionen, { priceMode, taxScheme })` rechnet exakt in
+    ganzen Zahlen (BigInt) und rundet einmal je USt-Satz. Preise in Millionstel
+    Euro, Mengen in Tausendstel, Rabatt und Satz in Hundertstel-Prozent.
+  - `positionAusEuro(item)` wandelt eine Euro-Position verlustfrei um oder
+    nennt Feld und Grund.
+  - `anteiligerPreis`, `satzSchluessel`, `satzText`, `preisText`.
+  - `RechenFehler` mit `code` (`amount_too_large`, `kein_ganzzahlwert`,
+    `ausserhalb`), Feld und Index.
+- **Prüffälle im Paket:** `fixtures/rechnung-rechnen.json` (20 Fälle von
+  Hand), `fixtures/rechnung-rechnen-zufall.json` (400 aus einer unabhängigen
+  Referenz in Python) und `fixtures/position-aus-euro.json`. Server,
+  Dart-Zwilling und Panel werden gegen dieselben Dateien prüfen.
+- **Fehlerkatalog um zwei Codes erweitert:** `einvoice_unavailable` (zu dieser
+  Rechnung entsteht keine E-Rechnung, Grund im `reason`) und
+  `amount_too_large` (Betrag über der Grenze des Ganzzahlkerns) — beide hinten
+  angehängt, damit gespeicherte Reihenfolgen gültig bleiben. Der Katalog geht
+  dem Server bewusst voraus, damit Fremdsysteme beide Codes behandeln können,
+  bevor der Server sie sendet; heute sendet der Server keinen von beiden,
+  `amount_too_large` erst ab dessen Umstieg auf den Ganzzahlkern.
+- **Unverändert:** `rechnungSummen`, `fixtures/rechnung-summen.json` und Form
+  von Anfrage und Antwort der Rechnungs-API — der Fehlerkatalog wächst nur
+  additiv (s. o.). Der Kern rundet an Halbcent-Grenzen richtig, `rechnungSummen`
+  rechnet weiterhin wie der Server heute; beides wird in 0.24.0
+  zusammengeführt. Wer schon vorab genau rechnen will, nimmt `previewInvoice`.
+
+## 0.22.0
+
+### Rechnung: Brutto bleibt Brutto, Hinweise kommen an, Probelauf
+
+**Anlass:** Rückmeldung eines Shops zur Rechnungs-API (16.09.2026).
+
+- **`issueInvoice` gab `notice` nicht weiter.** Der Typ sah die Liste vor, der
+  Aufruf übernahm sie nie — eine ig. Lieferung meldete deshalb nie, dass eine
+  Zusammenfassende Meldung fällig ist. Behoben.
+- **`recordInvoicePayment` liefert `notice` jetzt als Liste** wie
+  `issueInvoice` (bisher ein einzelnes Objekt). **Bricht die Form:** wer
+  `result.notice.code` las, liest jetzt `result.notice?.[0]?.code`. Ein Server,
+  der noch ein Objekt schickt, wird zur Liste gemacht.
+- **Neu: `rechnungSummen(items, priceMode, taxScheme?)`** rechnet die Summen so,
+  wie der Server sie ausstellt. Im Brutto-Modus ist das Brutto je Satz der
+  vereinbarte Preis: Netto = round(B × 100 / (100 + Satz)), USt = B − Netto.
+  Der Server rechnete bis dahin Netto und USt getrennt und setzte das Brutto neu
+  zusammen — 14,79 € + 15,00 € zu 20 % wurden 29,80 €. Die Prüffälle stehen in
+  `fixtures/rechnung-summen.json`; Server und Dart-Zwilling prüfen dagegen.
+- **Neu: `previewInvoice(anfrage)`** — Probelauf von `issueInvoice`
+  (`dryRun: true` im Vertrag): prüft und rechnet wie das Ausstellen, schreibt
+  nichts fest und verbraucht den `idempotencyKey` nicht. Antwort `preview` mit
+  Summen, Steuerfall samt Grund, Sprache, Marke, E-Rechnung — dazu die Hinweise.
+- **`totals.byRate[]` trägt `grossCents`.** Die Summen sind auch bei
+  Gutschriften positiv; das steht jetzt am Typ.
+- **Texte:** `pdf.tabelle.einzelBrutto`, `pdf.tabelle.betragBrutto`,
+  `pdf.summe.darinUst` — das PDF einer Brutto-Rechnung zeigt Brutto-Spalten,
+  deren Zeilen die Summe ergeben. Dazu `pdf.position.rabatt`: ein Zeilenrabatt
+  stand bisher nirgends auf dem Blatt, „2 × 24,90 = 44,82" ging für den Leser
+  nicht auf.
+- **Kennung als Text:** `getInvoice('…')` und `getCustomer('…')` werfen vor dem
+  Senden `KasseneckValidationError` (`scope: 'request'`). Bisher wurde der Text
+  Zeichen für Zeichen zu Feldern `0`, `1`, … und der Server konnte nur
+  „Bitte Eingaben prüfen." antworten.
+- **Feldfehler in der Meldung:** `KasseneckApiError.message` hängt bis zu fünf
+  Einträge aus `errors[]` an (`[items[0].vatRate: …]`); `serverMessage` und
+  `details` bleiben unverändert.
+
+## 0.21.0
+
+### Rechnung: Kataloge für den abgeleiteten Steuerfall
+
+**Anlass:** Der Server leitet den Steuerfall jetzt selbst ab, statt ihn zu
+glauben (Kundenland, Kundenart, UID, Ware oder Leistung).
+
+- `taxScheme` ist in `issueInvoice` **optional**; eine Angabe prüft der Server
+  gegen die Ableitung (`tax_scheme_mismatch`).
+- Neue Fälle `domesticReverseCharge`, `oss` und `outsideScope`; Katalog der elf
+  Gründe für den Übergang der Steuerschuld im Inland
+  (`REVERSE_CHARGE_REASONS`, mit Fundstelle und Schwelle).
+  `oss` steht im Katalog, **kann aber noch nicht ausgestellt werden** —
+  die Ländersätze folgen.
+- Positionen tragen `kind` (`goods`/`service`), weil ig. Lieferung und Reverse
+  Charge sich genau daran unterscheiden.
+- `notice` ist an `issueInvoice` eine **Liste**: eine bar bezahlte ig. Lieferung
+  trägt zwei Hinweise zugleich.
+- Die Rechnungssicht trägt `reverseChargeReason` und `taxCountry`; neuer
+  Befreiungstext für den nicht steuerbaren Umsatz (E-Rechnung, BR-O-10).
+
 ## 0.20.0
 
 ### Rechnung: richtige Steuerhinweise, Barumsatz auch mit Karte

package/README.md

@@ -547,6 +547,72 @@ await rechnungen.recordInvoicePayment({
 `reference` wird gespeichert, aber **nicht gedruckt**; Kartendaten gehören
 ohnehin nicht auf eine Rechnung.
 
+**Vorab rechnen.** Wer kassiert, bevor die Rechnung entsteht, braucht den
+Betrag, den die Rechnung später ausweist. `rechnungSummen` rechnet ihn genau
+wie der Server; `previewInvoice` fragt den Server selbst — ein Probelauf, der
+prüft wie das Ausstellen, aber nichts festschreibt und den `idempotencyKey`
+nicht verbraucht:
+
+```ts
+import { rechnungSummen } from '@kreiseck/kasseneck-api/rechnung';
+
+const posten = [
+  { description: 'Maniküre', quantity: 1, unitPriceCents: 1479, vatRate: 20 as const },
+  { description: 'Lack', quantity: 1, unitPriceCents: 1500, vatRate: 20 as const },
+];
+rechnungSummen(posten, 'gross');
+// { netCents: 2483, vatCents: 496, grossCents: 2979, byRate: [{ rate: 20, … }] }
+
+const anfrage = { idempotencyKey: `bestellung-${bestellnummer}`, customerId: kunde.id,
+  priceMode: 'gross' as const, serviceStart: '2026-09-16', items: posten };
+const { preview, notice } = await rechnungen.previewInvoice(anfrage);
+// preview.totals, preview.taxScheme, preview.taxSchemeReason — dann:
+await rechnungen.issueInvoice(anfrage);
+```
+
+Im **Brutto-Modus** ist das Brutto je Satz der vereinbarte Preis: Netto =
+round(B × 100 / (100 + Satz)), USt = B − Netto. Im **Netto-Modus** wird die USt
+je Satz aus der Nettosumme gerundet. Gerundet wird kaufmännisch (halber Cent
+aufwärts), je Satz, dann summiert. Die Prüffälle liegen in
+`fixtures/rechnung-summen.json`. Die Summen sind auch bei Gutschriften positiv —
+das Vorzeichen steht im Belegtyp (`docType: 'GU'`).
+
+**Vorab rechnen, ohne Server.** `@kreiseck/kasseneck-api/rechnung/rechnen` ist
+der reine Rechenkern dahinter: kein Transport, kein Zugangsschlüssel, läuft
+auch im Browser (Panel). Er rechnet intern mit ganzen Zahlen (BigInt) statt
+Gleitkomma und rundet genau einmal je USt-Satz — Preise in Millionstel Euro
+(`unitPriceMicros`), Mengen in Tausendstel (`quantityMilli`), Rabatt und Satz
+in Hundertstel-Prozent (`discountBp`, `vatRateBp`):
+
+```ts
+import { rechnungRechnen } from '@kreiseck/kasseneck-api/rechnung/rechnen';
+
+rechnungRechnen(
+  [{ unitPriceMicros: 14_790_000, quantityMilli: 1000, vatRateBp: 2000 }],
+  { priceMode: 'gross' },
+);
+// { netCents: 1233, vatCents: 246, grossCents: 1479, byRate: [{ rateBp: 2000, … }], lines: […] }
+```
+
+`positionAusEuro(item)` wandelt eine Euro-Position (`unitPrice`, `quantity`,
+`vatRate`, `discountPct`) verlustfrei in diese Form um oder nennt Feld und
+Grund, wenn das nicht geht. Die Prüffälle liegen in
+`fixtures/rechnung-rechnen.json`, `fixtures/rechnung-rechnen-zufall.json` und
+`fixtures/position-aus-euro.json`. **Noch nicht zusammengeführt** mit
+`rechnungSummen`: bis 0.24.0 rechnen beide parallel und weichen an
+Halbcent-Grenzen bewusst voneinander ab — **je USt-Satz** bis zu 1 Cent bei
+einmal gerundeten Werten (Netto und USt im Netto-Modus, Brutto im
+Brutto-Modus) und bis zu 2 Cent bei abgeleiteten (Summe zweier Rundungen). Bei
+mehreren Sätzen summiert sich das: eine Rechnung über drei Sätze kann deshalb
+3 Cent auseinanderliegen. Der Kern rundet dort richtig, `rechnungSummen`
+rechnet weiterhin wie der Server heute. Verbindlich
+für den ausgewiesenen Betrag bleibt bis dahin `previewInvoice`.
+
+**Hinweise** (`notice`) sind immer eine Liste — bei `issueInvoice`,
+`previewInvoice` und `recordInvoicePayment`. Eine ig. Lieferung trägt
+`recapitulative_statement_due` (Zusammenfassende Meldung), eine bar bezahlte
+Rechnung zusätzlich `cash_receipt_required`.
+
 **Barumsatz ist nicht nur Bargeld.** Als Barzahlung gilt auch die Karte **vor
 Ort** an der Kasse (§ 131b Abs. 1 Z 3 UStG) — dieselbe Karte im Internet
 dagegen nicht. Weil `card` und `online` beides sein können, sagt es das
@@ -557,8 +623,8 @@ payment: { method: 'card', onSite: true }   // Terminal an der Kasse
 payment: { method: 'card' }                 // Kartenzahlung im Shop
 ```
 
-Bei `cash` (immer) und bei `onSite: true` trägt die Antwort
-`notice.code = 'cash_receipt_required'`: ein Barumsatz braucht einen Beleg
+Bei `cash` (immer) und bei `onSite: true` trägt die Antwort in der Liste
+`notice` den Eintrag `cash_receipt_required`: ein Barumsatz braucht einen Beleg
 (§ 132a BAO), bei Registrierkassenpflicht über die Registrierkasse — der
 Vermerk an der Rechnung ersetzt ihn nicht. `transfer` mit `onSite` ist ein
 Feldfehler, eine Überweisung erfolgt nicht vor Ort.
@@ -586,6 +652,7 @@ gegen genau diese Datei.
 | `…/kasse` | Kachel-Kasse: Kassen-Einstellungen (betriebsweit / je Gerät), Artikelgruppen und Artikel für Kacheln, Rabattverteilung je Steuersatz, Reichweiten der Kassen-Rechte |
 | `…/partner` | Partner-API: Betriebe anlegen, FinanzOnline-Link, Signatur, Kassen, Zugangsdaten, Webhooks samt Signaturprüfung. **Gehört auf einen Server.** |
 | `…/rechnung` | Rechnungs-API: Kunden anlegen und suchen, Rechnungen festgeschrieben ausstellen, Gutschrift und Storno, PDF und E-Rechnung-XML; der Vertrag als Daten. **Gehört auf einen Server.** |
+| `…/rechnung/rechnen` | Reiner Rechenkern für Rechnungssummen (Ganzzahlen, kein Transport, keine Abhängigkeit außer Typen) — darf auch im Browser laufen. |
 | `…/react` | Dünner React-Adapter, der ein Beleg-Layout zeichnet. Braucht React. |
 | `…/fixtures/*` | Golden-Belege (JSON): Eingaben `belege/<name>.json`, zugesagte Zeilenausgabe `erwartet/<name>.lines.json`, `manifest.json` mit Prüfsummen — dieselben Dateien prüfen Backend, Browser-Kasse und Flutter-Paket. |
 

package/dist/cjs/client/errors.d.ts

@@ -87,7 +87,6 @@ export declare function causeDigest(ursache: unknown, geheimnisse: readonly stri
  * demselben Grund **keinen** Vorgabewert.
  */
 export declare function fehlerDetails(daten: unknown, geheimnisse: readonly string[]): Record<string, unknown>;
-/** Fachlicher Fehler: HTTP 200, aber `status: 'error'` im Rumpf. */
 export declare class KasseneckApiError extends Error {
     readonly name = "KasseneckApiError";
     /** Aufgerufene Backend-Funktion, z. B. `createReceipt`. */

package/dist/cjs/client/errors.js

@@ -174,6 +174,29 @@ function sieben(wert, geheimnisse, tiefe) {
     return raus;
 }
 /** Fachlicher Fehler: HTTP 200, aber `status: 'error'` im Rumpf. */
+/**
+ * Die Feldfehler einer Pruefantwort (`errors: [{ field, message }]`) als
+ * Anhang der Fehlermeldung — sonst stuende im Log nur „Bitte Eingaben
+ * pruefen." und niemand wuesste, welches Feld gemeint ist. Hoechstens fuenf;
+ * vollstaendig bleiben sie in `details.errors`.
+ */
+function feldHinweis(details) {
+    const roh = details['errors'];
+    if (!Array.isArray(roh))
+        return '';
+    const teile = [];
+    for (const e of roh) {
+        if (e === null || typeof e !== 'object')
+            continue;
+        const { field, message } = e;
+        if (typeof field === 'string' && typeof message === 'string')
+            teile.push(`${field}: ${message}`);
+    }
+    if (!teile.length)
+        return '';
+    const mehr = teile.length > 5 ? ` (+${teile.length - 5} weitere)` : '';
+    return ` [${teile.slice(0, 5).join('; ')}${mehr}]`;
+}
 class KasseneckApiError extends Error {
     name = 'KasseneckApiError';
     /** Aufgerufene Backend-Funktion, z. B. `createReceipt`. */
@@ -197,7 +220,7 @@ class KasseneckApiError extends Error {
      */
     details;
     constructor(functionName, serverMessage, details = {}, code) {
-        super(`${functionName} fehlgeschlagen: ${serverMessage}`);
+        super(`${functionName} fehlgeschlagen: ${serverMessage}${feldHinweis(details)}`);
         this.functionName = functionName;
         this.serverMessage = serverMessage;
         this.details = details;

package/dist/cjs/rechnung/api.d.ts

@@ -6,7 +6,7 @@
  */
 import { type FetchLike } from '../client/transport.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, RecordPaymentRequest, RecordPaymentResult } from './typen.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 interface RechnungApiOptions {
     /** `api_key` des Kontos (`kr_live_…` / `kr_test_…`). Gehoert auf einen Server. */
     apiKey: string;
@@ -29,6 +29,8 @@ export interface RechnungApi {
     updateCustomer(customerId: string, patch: Partial<CustomerInput>): Promise<Customer>;
     searchCustomers(suche: CustomerSearch): Promise<CustomerPage>;
     issueInvoice(anfrage: IssueInvoiceRequest): Promise<IssueResult>;
+    /** Probelauf: pruefen und rechnen wie `issueInvoice`, ohne auszustellen. */
+    previewInvoice(anfrage: IssueInvoiceRequest): Promise<PreviewResult>;
     cancelInvoice(anfrage: CancelInvoiceRequest): Promise<CancelResult>;
     createCreditNote(anfrage: CreditNoteRequest): Promise<CreditNoteResult>;
     getInvoice(kennung: {

package/dist/cjs/rechnung/api.js

@@ -25,6 +25,7 @@ function createRechnungApi(optionen) {
         updateCustomer: (id, patch) => (0, endpunkte_js_1.updateCustomer)(rufen, id, patch),
         searchCustomers: (suche) => (0, endpunkte_js_1.searchCustomers)(rufen, suche),
         issueInvoice: (anfrage) => (0, endpunkte_js_1.issueInvoice)(rufen, anfrage),
+        previewInvoice: (anfrage) => (0, endpunkte_js_1.previewInvoice)(rufen, anfrage),
         cancelInvoice: (anfrage) => (0, endpunkte_js_1.cancelInvoice)(rufen, anfrage),
         createCreditNote: (anfrage) => (0, endpunkte_js_1.createCreditNote)(rufen, anfrage),
         getInvoice: (kennung) => (0, endpunkte_js_1.getInvoice)(rufen, kennung),

package/dist/cjs/rechnung/endpunkte.d.ts

@@ -18,7 +18,7 @@
  */
 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, RecordPaymentRequest, RecordPaymentResult } from './typen.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?: {
     idempotencyKey?: string;
 }): Promise<Customer>;
@@ -30,6 +30,17 @@ export declare function getCustomer(rufen: InternerTransport, kennung: {
 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>;
+/**
+ * Probelauf von `issueInvoice`: dieselbe Anfrage wird geprueft und gerechnet
+ * wie beim Ausstellen, aber nichts festgeschrieben. Die Antwort nennt Summen,
+ * Steuerfall, Sprache, Marke und die Hinweise — oder scheitert mit demselben
+ * Fehlercode, mit dem das Ausstellen scheitern wuerde.
+ *
+ * Der `idempotencyKey` wird nicht verbraucht: dieselbe Anfrage laesst sich
+ * 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: {

package/dist/cjs/rechnung/endpunkte.js

@@ -23,6 +23,7 @@ exports.getCustomer = getCustomer;
 exports.updateCustomer = updateCustomer;
 exports.searchCustomers = searchCustomers;
 exports.issueInvoice = issueInvoice;
+exports.previewInvoice = previewInvoice;
 exports.cancelInvoice = cancelInvoice;
 exports.createCreditNote = createCreditNote;
 exports.getInvoice = getInvoice;
@@ -55,6 +56,33 @@ function seite(aufruf, daten, feld) {
     return { eintraege: o[feld], nextCursor: typeof o['nextCursor'] === 'string' ? o['nextCursor'] : null };
 }
 const zahl = (wert) => (typeof wert === 'number' && Number.isFinite(wert) ? wert : 0);
+/**
+ * Die Hinweise einer Antwort (`data.notice`) — immer eine Liste, `undefined`
+ * ohne Hinweis. Ein einzelnes Objekt (Server vor der Vereinheitlichung) wird
+ * zur Liste.
+ *
+ * Ein unbrauchbarer Eintrag wird uebergangen, nicht geworfen: der Aufruf hat
+ * schon gewirkt (die Rechnung ist ausgestellt, die Zahlung gebucht). Ein
+ * Fehler an dieser Stelle liesse den Aufrufer glauben, es sei nichts
+ * entstanden — und eine Wiederholung liefert die Hinweise nicht noch einmal.
+ */
+function hinweise(daten) {
+    const roh = objekt(daten)['notice'];
+    if (roh === undefined || roh === null)
+        return undefined;
+    const liste = (Array.isArray(roh) ? roh : [roh]).filter((h) => typeof objekt(h)['code'] === 'string' && typeof objekt(h)['message'] === 'string');
+    return liste.length ? liste : undefined;
+}
+/**
+ * Eine Kennung muss ein Objekt sein (`{ invoiceId }`, `{ customerId }` …). Ein
+ * blosser Text wuerde sonst Zeichen fuer Zeichen zu Feldern `0`, `1`, …
+ * zerlegt, und der Server koennte nur „Bitte Eingaben pruefen" antworten.
+ */
+function kennungVerlangen(aufruf, kennung, felder) {
+    if (kennung === null || typeof kennung !== 'object' || Array.isArray(kennung)) {
+        throw new errors_js_1.KasseneckValidationError(aufruf, `Kennung als Objekt erwartet: ${felder}`, 'request');
+    }
+}
 /** Anfrageobjekt als Nutzlast — flache Kopie, damit der Aufrufer sein Objekt behaelt. */
 const nutzlast = (anfrage) => ({ ...anfrage });
 // ---- Kunden -----------------------------------------------------------------
@@ -66,6 +94,7 @@ async function createCustomer(rufen, customer, optionen = {}) {
     return pflichtObjekt('createCustomer', daten, 'customer');
 }
 async function getCustomer(rufen, kennung) {
+    kennungVerlangen('getCustomer', kennung, '{ customerId } oder { externalId }');
     const daten = await rufen('getCustomer', nutzlast(kennung));
     return pflichtObjekt('getCustomer', daten, 'customer');
 }
@@ -81,10 +110,32 @@ async function searchCustomers(rufen, suche) {
 // ---- Rechnungen -------------------------------------------------------------
 async function issueInvoice(rufen, anfrage) {
     const daten = await rufen('issueInvoice', nutzlast(anfrage));
-    return {
+    const ergebnis = {
         invoice: pflichtObjekt('issueInvoice', daten, 'invoice'),
         replayed: objekt(daten)['replayed'] === true,
     };
+    const notice = hinweise(daten);
+    if (notice)
+        ergebnis.notice = notice;
+    return ergebnis;
+}
+/**
+ * Probelauf von `issueInvoice`: dieselbe Anfrage wird geprueft und gerechnet
+ * wie beim Ausstellen, aber nichts festgeschrieben. Die Antwort nennt Summen,
+ * Steuerfall, Sprache, Marke und die Hinweise — oder scheitert mit demselben
+ * Fehlercode, mit dem das Ausstellen scheitern wuerde.
+ *
+ * Der `idempotencyKey` wird nicht verbraucht: dieselbe Anfrage laesst sich
+ * 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 });
+    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));
@@ -104,6 +155,7 @@ async function createCreditNote(rufen, anfrage) {
     };
 }
 async function getInvoice(rufen, kennung) {
+    kennungVerlangen('getInvoice', kennung, '{ invoiceId } oder { number }');
     const daten = await rufen('getInvoice', nutzlast(kennung));
     return pflichtObjekt('getInvoice', daten, 'invoice');
 }
@@ -159,8 +211,9 @@ async function recordInvoicePayment(rufen, anfrage) {
         payment: pflichtObjekt('recordInvoicePayment', daten, 'payment'),
         replayed: roh['replayed'] === true,
     };
-    if (roh['notice'])
-        ergebnis.notice = roh['notice'];
+    const notice = hinweise(daten);
+    if (notice)
+        ergebnis.notice = notice;
     return ergebnis;
 }
 /** Die Marken des Kontos — die Kennung geht als `brandId` in `issueInvoice`. */

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

@@ -13,7 +13,9 @@
 export { createRechnungApi, type RechnungApi, type RechnungApiOptions } from './api.js';
 export { rechnungKeyAuth, type RechnungKeyAuthOptions } from './auth.js';
 export { istRechnungFehler, rechnungFehlerCode, rechnungFeldFehler, type RechnungFeldFehler, } from './fehler.js';
-export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
-export type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, EInvoiceStatus, Invoice, InvoiceDetail, InvoiceItem, InvoiceItemInput, InvoiceListQuery, InvoicePage, InvoiceRecipient, InvoiceSetupGap, InvoiceSetupStatus, InvoiceTotals, InvoiceNotice, InvoicePayment, IssueInvoiceRequest, IssueResult, PaymentInput, RecordPaymentRequest, RecordPaymentResult, } from './typen.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, InvoiceItem, InvoiceItemInput, InvoiceListQuery, InvoicePage, InvoiceRecipient, InvoiceSetupGap, InvoiceSetupStatus, InvoiceTotals, InvoiceNotice, InvoicePayment, InvoicePreview, InvoiceRateTotals, IssueInvoiceRequest, IssueResult, PaymentInput, PreviewResult, RecordPaymentRequest, RecordPaymentResult, } from './typen.js';
 export { RECHNUNG_TEXTE, rechnungText, type RechnungTextSchluessel } from './texte.js';
+export { rechnungSummen, STEUERFREIE_FAELLE, type SummenPosition } from './summen.js';
+export { anteiligerPreis, BETRAG_GRENZE_CENTS, positionAusEuro, preisText, RechenFehler, rechnungRechnen, rund, satzSchluessel, satzText, type RechenErgebnis, type RechenFehlerCode, type RechenOptionen, type RechenPosition, type SatzSumme, type Umwandlung, type UmwandlungsGrund, type ZeilenBetrag, } from './rechnen.js';
 export { RECHNUNG_VERTRAG_VERSION, RECHNUNG_AUFRUFE, INVOICE_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, INVOICE_LANGUAGES, INVOICE_PAYMENT_METHODS, ITEM_KINDS, REVERSE_CHARGE_REASONS, INVOICE_NOTICE_CODES, INVOICE_UNITS, RECHNUNG_EINHEITEN_CODES, INVOICE_SETUP_REQUIREMENTS, KUNDE_FELDER, POSITION_FELDER, RECHNUNG_ANFRAGEN, RECHNUNG_GENAU_EINS, RECHNUNG_MINDESTENS_EINS, type RechnungAufruf, type InvoiceErrorCode, type CreditNoteReason, type TaxScheme, type PriceMode, type VatRatePercent, type CustomerType, type InvoiceListStatus, type DocType, type EInvoiceFormat, type InvoiceLanguage, type InvoicePaymentMethod, type ItemKind, type ReverseChargeReason, type InvoiceNoticeCode, type InvoiceUnit, type InvoiceSetupRequirement, type Format, type Feld, } from './vertrag.js';

package/dist/cjs/rechnung/index.js

@@ -12,7 +12,8 @@
  * Benutzung des Clients.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RECHNUNG_MINDESTENS_EINS = exports.RECHNUNG_GENAU_EINS = exports.RECHNUNG_ANFRAGEN = exports.POSITION_FELDER = exports.KUNDE_FELDER = exports.INVOICE_SETUP_REQUIREMENTS = exports.RECHNUNG_EINHEITEN_CODES = exports.INVOICE_UNITS = exports.INVOICE_NOTICE_CODES = exports.REVERSE_CHARGE_REASONS = exports.ITEM_KINDS = exports.INVOICE_PAYMENT_METHODS = exports.INVOICE_LANGUAGES = exports.EINVOICE_FORMATS = exports.DOC_TYPES = exports.INVOICE_LIST_STATUS = exports.CUSTOMER_TYPES = exports.VAT_RATES = exports.PRICE_MODES = exports.TAX_SCHEMES = exports.CREDIT_NOTE_REASONS = exports.INVOICE_ERROR_CODES = exports.RECHNUNG_AUFRUFE = exports.RECHNUNG_VERTRAG_VERSION = exports.rechnungText = exports.RECHNUNG_TEXTE = exports.updateCustomer = exports.searchCustomers = exports.recordInvoicePayment = exports.listInvoices = exports.listBrands = exports.issueInvoice = exports.getInvoiceXml = exports.getInvoiceSetupStatus = exports.getInvoicePdf = exports.getInvoice = exports.getCustomer = exports.createCustomer = exports.createCreditNote = exports.cancelInvoice = exports.rechnungFeldFehler = exports.rechnungFehlerCode = exports.istRechnungFehler = exports.rechnungKeyAuth = exports.createRechnungApi = void 0;
+exports.INVOICE_UNITS = exports.INVOICE_NOTICE_CODES = exports.REVERSE_CHARGE_REASONS = exports.ITEM_KINDS = exports.INVOICE_PAYMENT_METHODS = exports.INVOICE_LANGUAGES = exports.EINVOICE_FORMATS = exports.DOC_TYPES = exports.INVOICE_LIST_STATUS = exports.CUSTOMER_TYPES = exports.VAT_RATES = exports.PRICE_MODES = exports.TAX_SCHEMES = exports.CREDIT_NOTE_REASONS = exports.INVOICE_ERROR_CODES = exports.RECHNUNG_AUFRUFE = exports.RECHNUNG_VERTRAG_VERSION = exports.satzText = exports.satzSchluessel = exports.rund = exports.rechnungRechnen = exports.RechenFehler = exports.preisText = exports.positionAusEuro = exports.BETRAG_GRENZE_CENTS = exports.anteiligerPreis = exports.STEUERFREIE_FAELLE = exports.rechnungSummen = exports.rechnungText = exports.RECHNUNG_TEXTE = exports.updateCustomer = exports.searchCustomers = exports.recordInvoicePayment = exports.previewInvoice = exports.listInvoices = exports.listBrands = exports.issueInvoice = exports.getInvoiceXml = exports.getInvoiceSetupStatus = exports.getInvoicePdf = exports.getInvoice = exports.getCustomer = exports.createCustomer = exports.createCreditNote = exports.cancelInvoice = exports.rechnungFeldFehler = exports.rechnungFehlerCode = exports.istRechnungFehler = exports.rechnungKeyAuth = exports.createRechnungApi = void 0;
+exports.RECHNUNG_MINDESTENS_EINS = exports.RECHNUNG_GENAU_EINS = exports.RECHNUNG_ANFRAGEN = exports.POSITION_FELDER = exports.KUNDE_FELDER = exports.INVOICE_SETUP_REQUIREMENTS = exports.RECHNUNG_EINHEITEN_CODES = void 0;
 var api_js_1 = require("./api.js");
 Object.defineProperty(exports, "createRechnungApi", { enumerable: true, get: function () { return api_js_1.createRechnungApi; } });
 var auth_js_1 = require("./auth.js");
@@ -33,12 +34,26 @@ Object.defineProperty(exports, "getInvoiceXml", { enumerable: true, get: functio
 Object.defineProperty(exports, "issueInvoice", { enumerable: true, get: function () { return endpunkte_js_1.issueInvoice; } });
 Object.defineProperty(exports, "listBrands", { enumerable: true, get: function () { return endpunkte_js_1.listBrands; } });
 Object.defineProperty(exports, "listInvoices", { enumerable: true, get: function () { return endpunkte_js_1.listInvoices; } });
+Object.defineProperty(exports, "previewInvoice", { enumerable: true, get: function () { return endpunkte_js_1.previewInvoice; } });
 Object.defineProperty(exports, "recordInvoicePayment", { enumerable: true, get: function () { return endpunkte_js_1.recordInvoicePayment; } });
 Object.defineProperty(exports, "searchCustomers", { enumerable: true, get: function () { return endpunkte_js_1.searchCustomers; } });
 Object.defineProperty(exports, "updateCustomer", { enumerable: true, get: function () { return endpunkte_js_1.updateCustomer; } });
 var texte_js_1 = require("./texte.js");
 Object.defineProperty(exports, "RECHNUNG_TEXTE", { enumerable: true, get: function () { return texte_js_1.RECHNUNG_TEXTE; } });
 Object.defineProperty(exports, "rechnungText", { enumerable: true, get: function () { return texte_js_1.rechnungText; } });
+var summen_js_1 = require("./summen.js");
+Object.defineProperty(exports, "rechnungSummen", { enumerable: true, get: function () { return summen_js_1.rechnungSummen; } });
+Object.defineProperty(exports, "STEUERFREIE_FAELLE", { enumerable: true, get: function () { return summen_js_1.STEUERFREIE_FAELLE; } });
+var rechnen_js_1 = require("./rechnen.js");
+Object.defineProperty(exports, "anteiligerPreis", { enumerable: true, get: function () { return rechnen_js_1.anteiligerPreis; } });
+Object.defineProperty(exports, "BETRAG_GRENZE_CENTS", { enumerable: true, get: function () { return rechnen_js_1.BETRAG_GRENZE_CENTS; } });
+Object.defineProperty(exports, "positionAusEuro", { enumerable: true, get: function () { return rechnen_js_1.positionAusEuro; } });
+Object.defineProperty(exports, "preisText", { enumerable: true, get: function () { return rechnen_js_1.preisText; } });
+Object.defineProperty(exports, "RechenFehler", { enumerable: true, get: function () { return rechnen_js_1.RechenFehler; } });
+Object.defineProperty(exports, "rechnungRechnen", { enumerable: true, get: function () { return rechnen_js_1.rechnungRechnen; } });
+Object.defineProperty(exports, "rund", { enumerable: true, get: function () { return rechnen_js_1.rund; } });
+Object.defineProperty(exports, "satzSchluessel", { enumerable: true, get: function () { return rechnen_js_1.satzSchluessel; } });
+Object.defineProperty(exports, "satzText", { enumerable: true, get: function () { return rechnen_js_1.satzText; } });
 var vertrag_js_1 = require("./vertrag.js");
 Object.defineProperty(exports, "RECHNUNG_VERTRAG_VERSION", { enumerable: true, get: function () { return vertrag_js_1.RECHNUNG_VERTRAG_VERSION; } });
 Object.defineProperty(exports, "RECHNUNG_AUFRUFE", { enumerable: true, get: function () { return vertrag_js_1.RECHNUNG_AUFRUFE; } });

package/dist/cjs/rechnung/rechnen.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Der Rechenkern der Rechnung — exakt, in ganzen Zahlen.
+ *
+ * Eine Zeile ist ein Bruch: Preis (µ€) × Menge (Tausendstel) × Rabattanteil
+ * (Hundertstel-Prozent). Multipliziert man die Skalen, ist die kleinste Einheit
+ * 10⁻¹⁷ Cent — das passt in keine Gleitkommazahl und in keine 53-Bit-Ganzzahl,
+ * also rechnet der Kern mit BigInt. Gerundet wird genau EINMAL je USt-Satz, auf
+ * dem Bruch, kaufmaennisch (halbe Einheit vom Nullpunkt weg).
+ *
+ * Warum das so streng ist: Vier Umsetzungen (Server, dieses Paket, Dart, Panel)
+ * mussten bisher dieselbe Reihenfolge von Gleitkomma-Schritten nachbauen, damit
+ * Grenzfaelle gleich runden. Mit Ganzzahlen gibt es keine Reihenfolge mehr, an
+ * der etwas auseinanderlaufen koennte.
+ *
+ * Dieser Unterpfad ist rein: kein Transport, kein Zugangsschluessel, keine
+ * Abhaengigkeit ausser Typen. Er wird im Browser gebuendelt (Panel) und im
+ * Server geladen.
+ *
+ * Spec: docs/specs/2026-09-17-rechnung-ganzzahlen-design.md § 5.
+ */
+import type { PriceMode, TaxScheme } from './vertrag.js';
+/** Hoechster Betrag je Zeile und je Rechnung: 999.999.999,99 €. */
+export declare const BETRAG_GRENZE_CENTS = 99999999999;
+/** Steuerfaelle, in denen die Rechnung keine Steuer ausweist: jede Zeile zaehlt zu 0 %. */
+export declare const STEUERFREIE_FAELLE: readonly TaxScheme[];
+/** Eine Position in gespeicherter Form — alle Werte ganzzahlig. */
+export interface RechenPosition {
+    /** Einzelpreis in Millionstel Euro, 0 … 10¹². */
+    unitPriceMicros: number;
+    /** Menge in Tausendstel; negativ = Abzugszeile, 0 = Textzeile. */
+    quantityMilli: number;
+    /** Rabatt in Hundertstel-Prozent, 0 … 10000 (ohne Angabe 0). */
+    discountBp?: number;
+    /** USt-Satz in Hundertstel-Prozent, 0 … 10000 (ohne Angabe 0). */
+    vatRateBp?: number;
+}
+export interface RechenOptionen {
+    priceMode: PriceMode;
+    /** Ohne Angabe `normal`. */
+    taxScheme?: TaxScheme;
+}
+export interface SatzSumme {
+    rateBp: number;
+    netCents: number;
+    vatCents: number;
+    grossCents: number;
+}
+export interface ZeilenBetrag {
+    netCents: number;
+    grossCents: number;
+    /** Der Satz, mit dem die Zeile gerechnet wurde (bei steuerfreiem Fall 0). */
+    rateBp: number;
+}
+export interface RechenErgebnis {
+    netCents: number;
+    vatCents: number;
+    grossCents: number;
+    /** Absteigend nach `rateBp`. */
+    byRate: SatzSumme[];
+    /** Je Position, in der Reihenfolge der Eingabe. */
+    lines: ZeilenBetrag[];
+}
+export type RechenFehlerCode = 'amount_too_large' | 'kein_ganzzahlwert' | 'ausserhalb';
+/** Fehler des Kerns — mit Code, Feld und Index, damit die API daraus einen Feldfehler machen kann. */
+export declare class RechenFehler extends Error {
+    readonly code: RechenFehlerCode;
+    readonly feld?: string;
+    readonly index?: number;
+    constructor(code: RechenFehlerCode, nachricht: string, feld?: string, index?: number);
+}
+/**
+ * `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.
+ */
+export declare function rund(a: bigint, b: bigint): bigint;
+export declare function rechnungRechnen(positionen: readonly RechenPosition[], optionen: RechenOptionen): RechenErgebnis;
+export type UmwandlungsGrund = 'kein_zahlwert' | 'nachkommastellen' | 'ausserhalb';
+export type Umwandlung = {
+    ok: true;
+    position: RechenPosition & Record<string, unknown>;
+} | {
+    ok: false;
+    feld: 'unitPrice' | 'quantity' | 'vatRate' | 'discountPct';
+    grund: UmwandlungsGrund;
+};
+/**
+ * Euro-Position → Ganzzahl-Form, verlustfrei oder mit Grund abgelehnt. Die
+ * EINE Stelle, die das tut: Panel (beim Lesen), SEPA-Lauf, Umrechnungsskript
+ * und das Festschreiben benutzen alle diese Funktion, damit niemand eine
+ * zweite Auslegung baut.
+ *
+ * Eine Position, die schon `unitPriceMicros` traegt, kommt unveraendert
+ * zurueck — die Funktion ist die Formweiche, nicht eine blinde Umrechnung.
+ *
+ * Fehlende Menge und fehlender Satz gelten als 0, weil der Server bisher so
+ * abgerechnet hat. Ein fehlender Preis dagegen ist NIE 0: sonst wuerde eine
+ * Position, der nur der Preis fehlt, still zur 0-€-Zeile.
+ */
+export declare function positionAusEuro(item: Record<string, unknown>): Umwandlung;
+/**
+ * Anteiliger Preis fuer einen Teilzeitraum (erste Rechnung eines Abos).
+ * War der Ursprungspreis centgenau, bleibt auch der Anteil centgenau — sonst
+ * stuende auf der ersten Rechnung ein Preis mit sechs Stellen, wo bisher zwei
+ * standen.
+ */
+export declare function anteiligerPreis(unitPriceMicros: number, monate: number, intervall: number): number;
+/**
+ * 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`.
+ */
+export declare function satzSchluessel(rateBp: number): string;
+/** Ein USt-Satz fuer die Anzeige: oesterreichisch mit Komma, ohne nachlaufende Nullen. */
+export declare function satzText(rateBp: number): string;
+/**
+ * Ein Einzelpreis fuer die Anzeige: mindestens zwei, hoechstens sechs
+ * Nachkommastellen, Tausenderpunkt, Komma als Trennzeichen — in jeder Sprache
+ * oesterreichisch, wie die Betraege auf dem Blatt.
+ */
+export declare function preisText(unitPriceMicros: number): string;