@kreiseck/kasseneck-api 0.21.0 → 0.23.0

package/dist/esm/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/esm/rechnung/api.js

@@ -6,7 +6,7 @@
  */
 import { createBinaryTransport, createTransport } from '../client/transport.js';
 import { rechnungKeyAuth } from './auth.js';
-import { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
+import { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, previewInvoice, listInvoices, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
 export function createRechnungApi(optionen) {
     const transportOptionen = {
         auth: rechnungKeyAuth({ apiKey: optionen.apiKey }),
@@ -22,6 +22,7 @@ export function createRechnungApi(optionen) {
         updateCustomer: (id, patch) => updateCustomer(rufen, id, patch),
         searchCustomers: (suche) => searchCustomers(rufen, suche),
         issueInvoice: (anfrage) => issueInvoice(rufen, anfrage),
+        previewInvoice: (anfrage) => previewInvoice(rufen, anfrage),
         cancelInvoice: (anfrage) => cancelInvoice(rufen, anfrage),
         createCreditNote: (anfrage) => createCreditNote(rufen, anfrage),
         getInvoice: (kennung) => getInvoice(rufen, kennung),

package/dist/esm/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/esm/rechnung/endpunkte.js

@@ -39,6 +39,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 KasseneckValidationError(aufruf, `Kennung als Objekt erwartet: ${felder}`, 'request');
+    }
+}
 /** Anfrageobjekt als Nutzlast — flache Kopie, damit der Aufrufer sein Objekt behaelt. */
 const nutzlast = (anfrage) => ({ ...anfrage });
 // ---- Kunden -----------------------------------------------------------------
@@ -50,6 +77,7 @@ export async function createCustomer(rufen, customer, optionen = {}) {
     return pflichtObjekt('createCustomer', daten, 'customer');
 }
 export async function getCustomer(rufen, kennung) {
+    kennungVerlangen('getCustomer', kennung, '{ customerId } oder { externalId }');
     const daten = await rufen('getCustomer', nutzlast(kennung));
     return pflichtObjekt('getCustomer', daten, 'customer');
 }
@@ -65,10 +93,32 @@ export async function searchCustomers(rufen, suche) {
 // ---- Rechnungen -------------------------------------------------------------
 export 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.
+ */
+export 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;
 }
 export async function cancelInvoice(rufen, anfrage) {
     const daten = await rufen('cancelInvoice', nutzlast(anfrage));
@@ -88,6 +138,7 @@ export async function createCreditNote(rufen, anfrage) {
     };
 }
 export async function getInvoice(rufen, kennung) {
+    kennungVerlangen('getInvoice', kennung, '{ invoiceId } oder { number }');
     const daten = await rufen('getInvoice', nutzlast(kennung));
     return pflichtObjekt('getInvoice', daten, 'invoice');
 }
@@ -143,8 +194,9 @@ export 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/esm/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/esm/rechnung/index.js

@@ -13,6 +13,8 @@
 export { createRechnungApi } from './api.js';
 export { rechnungKeyAuth } from './auth.js';
 export { istRechnungFehler, rechnungFehlerCode, rechnungFeldFehler, } from './fehler.js';
-export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
+export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, previewInvoice, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
 export { RECHNUNG_TEXTE, rechnungText } from './texte.js';
+export { rechnungSummen, STEUERFREIE_FAELLE } from './summen.js';
+export { anteiligerPreis, BETRAG_GRENZE_CENTS, positionAusEuro, preisText, RechenFehler, rechnungRechnen, rund, satzSchluessel, satzText, } 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, } from './vertrag.js';

package/dist/esm/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/esm/rechnung/rechnen.js

@@ -0,0 +1,316 @@
+/**
+ * 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.
+ */
+/** Skala des Zeilenbruchs: 10⁻¹⁷ Cent. */
+const E = 10n ** 17n;
+/** Hoechster Betrag je Zeile und je Rechnung: 999.999.999,99 €. */
+export const BETRAG_GRENZE_CENTS = 99_999_999_999;
+/** Steuerfaelle, in denen die Rechnung keine Steuer ausweist: jede Zeile zaehlt zu 0 %. */
+export const 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. */
+export 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;
+    }
+}
+/**
+ * `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 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);
+}
+export function rechnungRechnen(positionen, optionen) {
+    const steuerfrei = STEUERFREIE_FAELLE.includes(optionen.taxScheme ?? 'normal');
+    const bruttoPreise = optionen.priceMode === 'gross' && !steuerfrei;
+    const grenze = BigInt(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 ${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]) > BETRAG_GRENZE_CENTS) {
+            throw new RechenFehler('amount_too_large', `Die Rechnung uebersteigt ${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.
+ */
+export 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.
+ */
+export 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`.
+ */
+export function satzSchluessel(rateBp) {
+    return String(rateBp / 100);
+}
+/** Ein USt-Satz fuer die Anzeige: oesterreichisch mit Komma, ohne nachlaufende Nullen. */
+export 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.
+ */
+export 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/esm/rechnung/summen.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Summen einer Rechnung vorab rechnen — genau so, wie der Server sie beim
+ * Ausstellen rechnet. Fuer Shops, die kassieren, bevor die Rechnung entsteht,
+ * und denselben Betrag brauchen, den die Rechnung spaeter ausweist.
+ *
+ * Die Regel (je USt-Satz, Betraege in Cent, kaufmaennisch gerundet):
+ *
+ * | Modus   | Netto                          | USt                        | Brutto             |
+ * |---------|--------------------------------|----------------------------|--------------------|
+ * | `net`   | round(Σ Zeilen)                | round(Σ Zeilen × Satz/100) | Netto + USt        |
+ * | `gross` | round(B × 100 / (100 + Satz))  | B − Netto                  | B = round(Σ Zeilen)|
+ *
+ * Zeile = Einzelpreis × Menge × (1 − Rabatt/100), ungerundet. Im Brutto-Modus
+ * ist das Brutto der vereinbarte Preis und bleibt, wie die Zeilen es ergeben.
+ * Bei einem steuerfreien Steuerfall zaehlt jede Zeile zu 0 %.
+ *
+ * `fixtures/rechnung-summen.json` haelt die Prueffaelle; Backend und
+ * Dart-Zwilling pruefen gegen dieselbe Datei. Verbindlich bleibt, was der
+ * Server rechnet — mit `previewInvoice` laesst sich das vorab abfragen.
+ */
+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;
+    unitPriceCents: number;
+    vatRate: number;
+    discountPct?: number;
+}
+/**
+ * Netto, USt und Brutto einer Rechnung in Cent, je Satz absteigend — dieselbe
+ * Form wie `invoice.totals` in den Antworten.
+ *
+ * `taxScheme` ist der Steuerfall der Rechnung; ohne Angabe `normal`. Leitet der
+ * Server einen steuerfreien Fall ab (etwa eine ig. Lieferung), gehoert dieser
+ * Fall hierher — sonst rechnet die Funktion Steuer, die die Rechnung nicht
+ * ausweist.
+ */
+export declare function rechnungSummen(items: readonly SummenPosition[], priceMode: PriceMode, taxScheme?: TaxScheme): InvoiceTotals;