@kreiseck/kasseneck-api 0.21.0 → 0.22.0

package/dist/esm/client/errors.js

@@ -164,6 +164,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}]`;
+}
 export class KasseneckApiError extends Error {
     name = 'KasseneckApiError';
     /** Aufgerufene Backend-Funktion, z. B. `createReceipt`. */
@@ -187,7 +210,7 @@ export 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/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,8 @@
 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 { 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,7 @@
 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 { 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/summen.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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';
+/** Was fuer die Summe zaehlt — `InvoiceItemInput` passt unveraendert. */
+export interface SummenPosition {
+    quantity: number;
+    unitPriceCents: number;
+    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.
+ *
+ * `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;

package/dist/esm/rechnung/summen.js

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+/** 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',
+]);
+/** 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;
+}
+const euroZuCent = (euro) => Math.round(euroRund(euro) * 100) || 0;
+/** Ganze Cent kaufmaennisch; ein Gleitkomma-Rest wie x,4999999… zaehlt als halber Cent. */
+function centRund(x) {
+    const betrag = Math.round(Math.abs(x) * 1e6) / 1e6;
+    return (x < 0 ? -1 : 1) * Math.round(betrag) || 0;
+}
+/**
+ * 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 function rechnungSummen(items, priceMode, taxScheme = 'normal') {
+    const steuerfrei = STEUERFREIE_FAELLE.includes(taxScheme);
+    const bruttoPreise = priceMode === 'gross' && !steuerfrei;
+    // Ungerundete Zeilen je Satz, in Euro wie am Server.
+    const jeSatz = new Map();
+    for (const p of items) {
+        const satz = steuerfrei ? 0 : p.vatRate;
+        const zeile = (p.unitPriceCents / 100) * p.quantity * (1 - (p.discountPct ?? 0) / 100);
+        jeSatz.set(satz, (jeSatz.get(satz) ?? 0) + zeile);
+    }
+    const byRate = [];
+    for (const [rate, roh] of jeSatz) {
+        let netCents;
+        let vatCents;
+        if (bruttoPreise) {
+            const grossCents = euroZuCent(roh);
+            netCents = centRund((grossCents * 100) / (100 + rate));
+            vatCents = grossCents - netCents;
+        }
+        else {
+            netCents = euroZuCent(roh);
+            vatCents = euroZuCent((roh * rate) / 100);
+        }
+        byRate.push({ rate, netCents, vatCents, grossCents: netCents + vatCents });
+    }
+    byRate.sort((a, b) => b.rate - a.rate);
+    const summe = (feld) => byRate.reduce((s, r) => s + r[feld], 0);
+    return { netCents: summe('netCents'), vatCents: summe('vatCents'), grossCents: summe('grossCents'), byRate };
+}

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

@@ -35,8 +35,12 @@ declare const DE: {
     readonly 'pdf.tabelle.ust': "UST";
     readonly 'pdf.tabelle.einzelNetto': "EINZEL NETTO";
     readonly 'pdf.tabelle.betragNetto': "BETRAG NETTO";
+    readonly 'pdf.tabelle.einzelBrutto': "EINZEL BRUTTO";
+    readonly 'pdf.tabelle.betragBrutto': "BETRAG BRUTTO";
+    readonly 'pdf.position.rabatt': "abzüglich {prozent} % Rabatt";
     readonly 'pdf.summe.zwischensumme': "Zwischensumme netto";
     readonly 'pdf.summe.umsatzsteuer': "Umsatzsteuer {satz}%";
+    readonly 'pdf.summe.darinUst': "darin {satz}% USt von {netto} netto";
     readonly 'pdf.summe.gesamt.rechnung': "Gesamtbetrag";
     readonly 'pdf.summe.gesamt.gutschrift': "Gutschriftsbetrag";
     readonly 'steuer.kleinunternehmer': "Gemäß § 6 Abs. 1 Z 27 UStG wird keine Umsatzsteuer verrechnet (Kleinunternehmer).";

package/dist/esm/rechnung/texte.js

@@ -20,8 +20,12 @@ const DE = {
     'pdf.tabelle.ust': 'UST',
     'pdf.tabelle.einzelNetto': 'EINZEL NETTO',
     'pdf.tabelle.betragNetto': 'BETRAG NETTO',
+    'pdf.tabelle.einzelBrutto': 'EINZEL BRUTTO',
+    'pdf.tabelle.betragBrutto': 'BETRAG BRUTTO',
+    'pdf.position.rabatt': 'abzüglich {prozent} % Rabatt',
     'pdf.summe.zwischensumme': 'Zwischensumme netto',
     'pdf.summe.umsatzsteuer': 'Umsatzsteuer {satz}%',
+    'pdf.summe.darinUst': 'darin {satz}% USt von {netto} netto',
     'pdf.summe.gesamt.rechnung': 'Gesamtbetrag',
     'pdf.summe.gesamt.gutschrift': 'Gutschriftsbetrag',
     'steuer.kleinunternehmer': 'Gemäß § 6 Abs. 1 Z 27 UStG wird keine Umsatzsteuer verrechnet (Kleinunternehmer).',
@@ -226,8 +230,12 @@ const EN = {
     'pdf.tabelle.ust': 'VAT',
     'pdf.tabelle.einzelNetto': 'UNIT NET',
     'pdf.tabelle.betragNetto': 'AMOUNT NET',
+    'pdf.tabelle.einzelBrutto': 'UNIT GROSS',
+    'pdf.tabelle.betragBrutto': 'AMOUNT GROSS',
+    'pdf.position.rabatt': 'less {prozent}% discount',
     'pdf.summe.zwischensumme': 'Subtotal net',
     'pdf.summe.umsatzsteuer': 'VAT {satz}%',
+    'pdf.summe.darinUst': 'incl. {satz}% VAT on {netto} net',
     'pdf.summe.gesamt.rechnung': 'Total',
     'pdf.summe.gesamt.gutschrift': 'Credit total',
     'steuer.kleinunternehmer': 'No VAT charged pursuant to § 6 (1) no. 27 UStG (small business exemption).',

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

@@ -146,7 +146,7 @@ export interface InvoicePayment {
 }
 /**
  * Ein Hinweis zu einer erfolgreichen Antwort — kein Fehler, sondern etwas,
- * das der Aufrufer wissen sollte (heute nur `cash_receipt_required`).
+ * das der Aufrufer wissen sollte. Die Codes stehen in `INVOICE_NOTICE_CODES`.
  */
 export interface InvoiceNotice {
     code: InvoiceNoticeCode;
@@ -156,7 +156,11 @@ export interface RecordPaymentResult {
     invoice: Invoice;
     payment: InvoicePayment;
     replayed: boolean;
-    notice?: InvoiceNotice;
+    /**
+     * Hinweise zu dieser Zahlung — eine **Liste** wie bei `issueInvoice`
+     * (bis 0.21.0 ein einzelnes Objekt). Fehlt, wenn es keinen gibt.
+     */
+    notice?: InvoiceNotice[];
 }
 export interface CancelInvoiceRequest {
     idempotencyKey: string;
@@ -167,15 +171,23 @@ export interface CancelInvoiceRequest {
 export interface CreditNoteRequest extends CancelInvoiceRequest {
     items: InvoiceItemInput[];
 }
+/**
+ * Summen einer Rechnung in Cent, **immer positiv** — auch bei einer Gutschrift
+ * (`docType: 'GU'`); das Vorzeichen steht im Belegtyp, nicht im Betrag.
+ * Gerechnet wird je Satz wie in [rechnungSummen].
+ */
 export interface InvoiceTotals {
     netCents: number;
     vatCents: number;
     grossCents: number;
-    byRate: {
-        rate: number;
-        netCents: number;
-        vatCents: number;
-    }[];
+    /** Je USt-Satz, absteigend. `grossCents` ist `netCents + vatCents` (seit 0.22.0 mitgeliefert). */
+    byRate: InvoiceRateTotals[];
+}
+export interface InvoiceRateTotals {
+    rate: number;
+    netCents: number;
+    vatCents: number;
+    grossCents: number;
 }
 export interface EInvoiceStatus {
     level: string;
@@ -299,6 +311,38 @@ export interface IssueResult {
      */
     notice?: InvoiceNotice[];
 }
+/**
+ * Was `issueInvoice` mit dieser Anfrage ausstellen wuerde — ohne Nummer, ohne
+ * Dokument, ohne Zahlung. Der Probelauf prueft wie das Ausstellen (Einrichtung,
+ * Kunde, Steuerfall, Pflichtangaben, Marke, Zahlung) und scheitert mit
+ * denselben Fehlercodes.
+ */
+export interface InvoicePreview {
+    docType: 'RE';
+    /** Heutiger Wiener Tag — der Tag, den eine sofort ausgestellte Rechnung truege. */
+    invoiceDate: string;
+    dueDate: string | null;
+    customerId: string | null;
+    /** Der abgeleitete Steuerfall. */
+    taxScheme: TaxScheme;
+    /** Warum dieser Fall gilt (z. B. `customer_country_eu_with_vat_id`). */
+    taxSchemeReason: string;
+    reverseChargeReason: ReverseChargeReason | null;
+    taxCountry: string;
+    priceMode: PriceMode;
+    totals: InvoiceTotals;
+    language: InvoiceLanguage;
+    brand: {
+        id: string | null;
+        name: string | null;
+    } | null;
+    einvoice: EInvoiceStatus;
+}
+export interface PreviewResult {
+    preview: InvoicePreview;
+    /** Dieselben Hinweise, die das Ausstellen liefern wuerde. */
+    notice?: InvoiceNotice[];
+}
 export interface CancelResult {
     creditNote: Invoice;
     original: {

package/dist/esm/rechnung/vertrag.js

@@ -417,6 +417,12 @@ export const RECHNUNG_ANFRAGEN = Object.freeze({
          * und ein sofort geholtes PDF Zahlungsinformationen traegt.
          */
         payment: { typ: 'object', pflicht: false, felder: PAYMENT_FELDER },
+        /**
+         * Probelauf: alles pruefen und rechnen wie beim Ausstellen, aber nichts
+         * festschreiben — keine Nummer, kein Dokument, keine Zahlung, kein
+         * Idempotenz-Eintrag. Die Antwort traegt `preview` statt `invoice`.
+         */
+        dryRun: { typ: 'boolean', pflicht: false },
     },
     cancelInvoice: {
         idempotencyKey: idempotencyKey(true),

package/fixtures/hobex-hps-codes.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.21.0",
+  "version": "0.22.0",
   "gemessenAn": {
     "tid": "3600335",
     "hpsVersion": "1.10.0",

package/fixtures/kasse-texte.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.21.0",
+  "version": "0.22.0",
   "meldungen": {
     "netz.keine_verbindung": {
       "text": "Keine Verbindung zum Server. Bitte die Internetverbindung prüfen und erneut versuchen."

package/fixtures/oberflaeche.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.21.0",
+  "version": "0.22.0",
   "aufrufe": [
     "activateCashregister",
     "cancelInvoice",
@@ -519,6 +519,14 @@
       "listBrands",
       "recordInvoicePayment"
     ],
+    "steuerfreieFaelle": [
+      "smallBusiness",
+      "reverseCharge",
+      "igLieferung",
+      "exportThirdCountry",
+      "domesticReverseCharge",
+      "outsideScope"
+    ],
     "taxSchemes": [
       "normal",
       "smallBusiness",

package/fixtures/rechnung-api.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "Kasseneck Rechnungs-API",
   "version": 1,
-  "paket": "0.21.0",
+  "paket": "0.22.0",
   "aufrufe": {
     "createCustomer": {
       "anfrage": {
@@ -523,6 +523,9 @@
               "method"
             ],
             "additionalProperties": false
+          },
+          "dryRun": {
+            "type": "boolean"
           }
         },
         "required": [