@kreiseck/kasseneck-api 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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

package/README.md

@@ -577,6 +577,37 @@ 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
@@ -621,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/rechnung/index.d.ts

@@ -17,4 +17,5 @@ export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoic
 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.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.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");
@@ -43,6 +44,16 @@ Object.defineProperty(exports, "rechnungText", { enumerable: true, get: function
 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;

package/dist/cjs/rechnung/rechnen.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * 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.
+ */
+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;
+/** 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;
+/** Steuerfaelle, in denen die Rechnung keine Steuer ausweist: jede Zeile zaehlt zu 0 %. */
+exports.STEUERFREIE_FAELLE = Object.freeze([
+    'smallBusiness',
+    'reverseCharge',
+    'igLieferung',
+    'exportThirdCountry',
+    'domesticReverseCharge',
+    'outsideScope',
+]);
+/** Fehler des Kerns — mit Code, Feld und Index, damit die API daraus einen Feldfehler machen kann. */
+class RechenFehler extends Error {
+    code;
+    feld;
+    index;
+    constructor(code, nachricht, feld, index) {
+        super(nachricht);
+        this.name = 'RechenFehler';
+        this.code = code;
+        this.feld = feld;
+        this.index = index;
+    }
+}
+exports.RechenFehler = RechenFehler;
+/**
+ * `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) {
+    const negativ = a < 0n;
+    const betrag = negativ ? -a : a;
+    const ganz = (2n * betrag + b) / (2n * b);
+    return negativ ? -ganz : ganz;
+}
+const GRENZEN = {
+    unitPriceMicros: [0, 1_000_000_000_000],
+    quantityMilli: [-1_000_000_000_000, 1_000_000_000_000],
+    discountBp: [0, 10_000],
+    vatRateBp: [0, 10_000],
+};
+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);
+    }
+    const [min, max] = GRENZEN[feld];
+    if (wert < min || wert > max) {
+        throw new RechenFehler('ausserhalb', `items[${index}].${feld} liegt ausserhalb von ${min} … ${max}`, feld, index);
+    }
+    return wert;
+}
+/**
+ * Verteilt die Zeilenbetraege eines Satzes so, dass sie genau die Satzsumme
+ * ergeben. Startwert ist die kaufmaennisch gerundete Zeile; der Rest geht
+ * einzeln an die Zeilen, bei denen das Runden am meisten weggenommen (bzw.
+ * zugegeben) hat. Verglichen wird auf dem Bruch, nie in Gleitkomma; bei
+ * Gleichstand bekommt die fruehere Zeile den Cent. Eine Zeile ueber 0 bekommt
+ * nie einen Cent — sonst stuende auf dem Blatt ein Betrag, den die Position
+ * nicht hat.
+ */
+function verteile(gruppe, feld, faktor, nenner, ziel) {
+    const werte = gruppe.map((z) => {
+        const zaehler = z.L * faktor;
+        return { z, zaehler, wert: rund(zaehler, nenner) };
+    });
+    let rest = ziel - werte.reduce((s, w) => s + w.wert, 0n);
+    if (rest !== 0n) {
+        const schritt = rest > 0n ? 1n : -1n;
+        const kandidaten = werte
+            .filter((w) => w.zaehler !== 0n)
+            .sort((a, b) => {
+            const da = (a.zaehler - a.wert * nenner) * schritt;
+            const db = (b.zaehler - b.wert * nenner) * schritt;
+            if (da !== db)
+                return db > da ? 1 : -1;
+            return a.z.index - b.z.index;
+        });
+        for (let k = 0; rest !== 0n && kandidaten.length > 0; k = (k + 1) % kandidaten.length) {
+            kandidaten[k].wert += schritt;
+            rest -= schritt;
+        }
+    }
+    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) => {
+        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);
+        }
+        return { index, rateBp: steuerfrei ? 0 : satz, L, netCents: 0, grossCents: 0 };
+    });
+    const jeSatz = new Map();
+    for (const z of zeilen) {
+        const gruppe = jeSatz.get(z.rateBp);
+        if (gruppe)
+            gruppe.push(z);
+        else
+            jeSatz.set(z.rateBp, [z]);
+    }
+    const byRate = [];
+    for (const [rateBp, gruppe] of jeSatz) {
+        const r = BigInt(rateBp);
+        const S = gruppe.reduce((s, z) => s + z.L, 0n);
+        let netCents;
+        let vatCents;
+        let grossCents;
+        if (bruttoPreise) {
+            grossCents = rund(S, E);
+            netCents = rund(grossCents * 10000n, 10000n + r);
+            vatCents = grossCents - netCents;
+        }
+        else {
+            netCents = rund(S, E);
+            vatCents = rund(S * r, E * 10000n);
+            grossCents = netCents + vatCents;
+        }
+        if (bruttoPreise) {
+            verteile(gruppe, 'netCents', 10000n, E * (10000n + r), netCents);
+            verteile(gruppe, 'grossCents', 1n, E, grossCents);
+        }
+        else {
+            verteile(gruppe, 'netCents', 1n, E, netCents);
+            verteile(gruppe, 'grossCents', 10000n + r, E * 10000n, grossCents);
+        }
+        byRate.push({
+            rateBp,
+            netCents: Number(netCents),
+            vatCents: Number(vatCents),
+            grossCents: Number(grossCents),
+        });
+    }
+    byRate.sort((a, b) => b.rateBp - a.rateBp);
+    const summe = (feld) => byRate.reduce((s, r) => s + r[feld], 0);
+    const ergebnis = {
+        netCents: summe('netCents'),
+        vatCents: summe('vatCents'),
+        grossCents: summe('grossCents'),
+        byRate,
+        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})`);
+        }
+    }
+    return ergebnis;
+}
+/**
+ * Wandelt eine Zahl ueber ihren kuerzesten Dezimaltext in eine Ganzzahl mit
+ * `stellen` Nachkommastellen. Kein Gleitkomma-Rechnen: `0.1 * 1000` ist
+ * 100.00000000000001, `String(0.1)` dagegen genau "0.1". Mehr Stellen als
+ * erlaubt ergeben `null` — auch Gleitkomma-Rauschen wie 0.30000000000000004,
+ * das mit 17 Stellen dasteht.
+ */
+function ganzAusDezimaltext(wert, stellen) {
+    if (typeof wert !== 'number' || !Number.isFinite(wert))
+        return null;
+    const treffer = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(String(wert));
+    if (!treffer)
+        return null;
+    const [, vorzeichen = '', ganzTeil = '0', bruchTeil = '', hoch = '0'] = treffer;
+    const verschiebung = Number(hoch);
+    let ziffern = `${ganzTeil}${bruchTeil}`;
+    let nachkomma = bruchTeil.length - verschiebung;
+    if (nachkomma < 0) {
+        ziffern += '0'.repeat(-nachkomma);
+        nachkomma = 0;
+    }
+    if (nachkomma > stellen) {
+        // Nur echte Nullen am Ende duerfen wegfallen (1.20 bei 1 Stelle).
+        const zuviel = nachkomma - stellen;
+        if (!/^0+$/.test(ziffern.slice(-zuviel)))
+            return null;
+        ziffern = ziffern.slice(0, -zuviel);
+        nachkomma = stellen;
+    }
+    const skaliert = `${ziffern}${'0'.repeat(stellen - nachkomma)}`;
+    const zahl = Number(`${vorzeichen}${skaliert}`);
+    return Number.isSafeInteger(zahl) ? zahl : null;
+}
+const EURO_FELDER = ['unitPrice', 'quantity', 'vatRate', 'discountPct'];
+/**
+ * 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.
+ */
+function positionAusEuro(item) {
+    if (typeof item.unitPriceMicros === 'number') {
+        return { ok: true, position: item };
+    }
+    const roh = item.unitPrice;
+    if (typeof roh !== 'number' || !Number.isFinite(roh)) {
+        return { ok: false, feld: 'unitPrice', grund: 'kein_zahlwert' };
+    }
+    const micros = ganzAusDezimaltext(Math.abs(roh), 6);
+    if (micros === null)
+        return { ok: false, feld: 'unitPrice', grund: 'nachkommastellen' };
+    if (micros > GRENZEN.unitPriceMicros[1])
+        return { ok: false, feld: 'unitPrice', grund: 'ausserhalb' };
+    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' };
+        const ganz = ganzAusDezimaltext(w, stellen);
+        if (ganz === null)
+            return { ok: false, grund: 'nachkommastellen' };
+        if (ganz < (feld === 'quantity' ? -max : 0) || ganz > max)
+            return { ok: false, grund: 'ausserhalb' };
+        return { ok: true, wert: ganz };
+    };
+    const menge = zahl('quantity', 3, GRENZEN.quantityMilli[1]);
+    if (!menge.ok)
+        return { ok: false, feld: 'quantity', grund: menge.grund };
+    const satz = zahl('vatRate', 2, 10_000);
+    if (!satz.ok)
+        return { ok: false, feld: 'vatRate', grund: satz.grund };
+    const rabatt = zahl('discountPct', 2, 10_000);
+    if (!rabatt.ok)
+        return { ok: false, feld: 'discountPct', grund: rabatt.grund };
+    const rest = { ...item };
+    for (const feld of EURO_FELDER)
+        delete rest[feld];
+    return {
+        ok: true,
+        position: {
+            ...rest,
+            unitPriceMicros: micros,
+            quantityMilli: roh < 0 ? -menge.wert : menge.wert,
+            discountBp: rabatt.wert,
+            vatRateBp: satz.wert,
+        },
+    };
+}
+/**
+ * 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.
+ */
+function anteiligerPreis(unitPriceMicros, monate, intervall) {
+    const micros = BigInt(unitPriceMicros);
+    const anteil = rund(micros * BigInt(monate), BigInt(intervall));
+    if (unitPriceMicros % 10_000 !== 0)
+        return Number(anteil);
+    return Number(rund(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`.
+ */
+function satzSchluessel(rateBp) {
+    return String(rateBp / 100);
+}
+/** Ein USt-Satz fuer die Anzeige: oesterreichisch mit Komma, ohne nachlaufende Nullen. */
+function satzText(rateBp) {
+    return satzSchluessel(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) {
+    const negativ = unitPriceMicros < 0;
+    const betrag = Math.abs(unitPriceMicros);
+    const ganz = Math.trunc(betrag / 1_000_000);
+    let bruch = String(betrag % 1_000_000).padStart(6, '0');
+    while (bruch.length > 2 && bruch.endsWith('0'))
+        bruch = bruch.slice(0, -1);
+    const mitPunkten = String(ganz).replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+    return `${negativ ? '-' : ''}${mitPunkten},${bruch}`;
+}

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

@@ -20,6 +20,9 @@
  */
 import type { InvoiceTotals } from './typen.js';
 import type { PriceMode, TaxScheme } from './vertrag.js';
+import { STEUERFREIE_FAELLE } from './rechnen.js';
+/** Aus dem Kern uebernommen, damit Kern und Huelle nie auseinanderlaufen. */
+export { STEUERFREIE_FAELLE };
 /** Was fuer die Summe zaehlt — `InvoiceItemInput` passt unveraendert. */
 export interface SummenPosition {
     quantity: number;
@@ -27,8 +30,6 @@ export interface SummenPosition {
     vatRate: number;
     discountPct?: number;
 }
-/** Steuerfaelle, in denen die Rechnung keine Steuer ausweist: jede Zeile zaehlt zu 0 %. */
-export declare const STEUERFREIE_FAELLE: readonly TaxScheme[];
 /**
  * Netto, USt und Brutto einer Rechnung in Cent, je Satz absteigend — dieselbe
  * Form wie `invoice.totals` in den Antworten.

package/dist/cjs/rechnung/summen.js

@@ -22,15 +22,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STEUERFREIE_FAELLE = void 0;
 exports.rechnungSummen = rechnungSummen;
-/** Steuerfaelle, in denen die Rechnung keine Steuer ausweist: jede Zeile zaehlt zu 0 %. */
-exports.STEUERFREIE_FAELLE = Object.freeze([
-    'smallBusiness',
-    'reverseCharge',
-    'igLieferung',
-    'exportThirdCountry',
-    'domesticReverseCharge',
-    'outsideScope',
-]);
+const rechnen_js_1 = require("./rechnen.js");
+Object.defineProperty(exports, "STEUERFREIE_FAELLE", { enumerable: true, get: function () { return rechnen_js_1.STEUERFREIE_FAELLE; } });
 /** Auf Cent gerundete Euro — dieselbe Rundung wie am Server (halber Cent vom Nullpunkt weg). */
 function euroRund(n) {
     return ((n < 0 ? -1 : 1) * Math.round((Math.abs(n) + Number.EPSILON) * 100)) / 100;
@@ -51,7 +44,7 @@ function centRund(x) {
  * ausweist.
  */
 function rechnungSummen(items, priceMode, taxScheme = 'normal') {
-    const steuerfrei = exports.STEUERFREIE_FAELLE.includes(taxScheme);
+    const steuerfrei = rechnen_js_1.STEUERFREIE_FAELLE.includes(taxScheme);
     const bruttoPreise = priceMode === 'gross' && !steuerfrei;
     // Ungerundete Zeilen je Satz, in Euro wie am Server.
     const jeSatz = new Map();

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

@@ -24,7 +24,7 @@ export type RechnungAufruf = (typeof RECHNUNG_AUFRUFE)[number];
  * Stabile Fehlercodes. Das Fremdsystem verzweigt am Code, der Text darf sich
  * aendern. `validation` traegt zusaetzlich `errors: [{ field, message }]`.
  */
-export declare const INVOICE_ERROR_CODES: readonly ["validation", "idempotency_conflict", "module_inactive", "customer_not_found", "customer_exists", "short_code_taken", "short_code_immutable", "recipient_required", "invoice_requirements_missing", "invoice_not_found", "invoice_ambiguous", "not_cancellable", "partial_credit_exists", "credit_exceeds_invoice", "einvoice_incomplete", "invoice_api_not_enabled", "invoice_setup_incomplete", "language_not_allowed", "brand_not_found", "not_payable", "payment_exceeds_invoice", "tax_scheme_mismatch", "vat_rate_not_in_country", "reverse_charge_reason_required", "reverse_charge_threshold", "mixed_supply_not_allowed", "oss_not_enabled"];
+export declare const INVOICE_ERROR_CODES: readonly ["validation", "idempotency_conflict", "module_inactive", "customer_not_found", "customer_exists", "short_code_taken", "short_code_immutable", "recipient_required", "invoice_requirements_missing", "invoice_not_found", "invoice_ambiguous", "not_cancellable", "partial_credit_exists", "credit_exceeds_invoice", "einvoice_incomplete", "invoice_api_not_enabled", "invoice_setup_incomplete", "language_not_allowed", "brand_not_found", "not_payable", "payment_exceeds_invoice", "tax_scheme_mismatch", "vat_rate_not_in_country", "reverse_charge_reason_required", "reverse_charge_threshold", "mixed_supply_not_allowed", "oss_not_enabled", "einvoice_unavailable", "amount_too_large"];
 export type InvoiceErrorCode = (typeof INVOICE_ERROR_CODES)[number];
 /** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
 export declare const CREDIT_NOTE_REASONS: readonly ["cancellation", "price_reduction", "return", "incorrect_invoice", "other"];

package/dist/cjs/rechnung/vertrag.js

@@ -69,6 +69,8 @@ exports.INVOICE_ERROR_CODES = [
     'reverse_charge_threshold',
     'mixed_supply_not_allowed',
     'oss_not_enabled',
+    '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
 ];
 /** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
 exports.CREDIT_NOTE_REASONS = [

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

@@ -17,4 +17,5 @@ export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoic
 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';