@kreiseck/kasseneck-api 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -4,6 +4,65 @@ 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.22.0
+
+### Rechnung: Brutto bleibt Brutto, Hinweise kommen an, Probelauf
+
+**Anlass:** Rückmeldung eines Shops zur Rechnungs-API (16.09.2026).
+
+- **`issueInvoice` gab `notice` nicht weiter.** Der Typ sah die Liste vor, der
+  Aufruf übernahm sie nie — eine ig. Lieferung meldete deshalb nie, dass eine
+  Zusammenfassende Meldung fällig ist. Behoben.
+- **`recordInvoicePayment` liefert `notice` jetzt als Liste** wie
+  `issueInvoice` (bisher ein einzelnes Objekt). **Bricht die Form:** wer
+  `result.notice.code` las, liest jetzt `result.notice?.[0]?.code`. Ein Server,
+  der noch ein Objekt schickt, wird zur Liste gemacht.
+- **Neu: `rechnungSummen(items, priceMode, taxScheme?)`** rechnet die Summen so,
+  wie der Server sie ausstellt. Im Brutto-Modus ist das Brutto je Satz der
+  vereinbarte Preis: Netto = round(B × 100 / (100 + Satz)), USt = B − Netto.
+  Der Server rechnete bis dahin Netto und USt getrennt und setzte das Brutto neu
+  zusammen — 14,79 € + 15,00 € zu 20 % wurden 29,80 €. Die Prüffälle stehen in
+  `fixtures/rechnung-summen.json`; Server und Dart-Zwilling prüfen dagegen.
+- **Neu: `previewInvoice(anfrage)`** — Probelauf von `issueInvoice`
+  (`dryRun: true` im Vertrag): prüft und rechnet wie das Ausstellen, schreibt
+  nichts fest und verbraucht den `idempotencyKey` nicht. Antwort `preview` mit
+  Summen, Steuerfall samt Grund, Sprache, Marke, E-Rechnung — dazu die Hinweise.
+- **`totals.byRate[]` trägt `grossCents`.** Die Summen sind auch bei
+  Gutschriften positiv; das steht jetzt am Typ.
+- **Texte:** `pdf.tabelle.einzelBrutto`, `pdf.tabelle.betragBrutto`,
+  `pdf.summe.darinUst` — das PDF einer Brutto-Rechnung zeigt Brutto-Spalten,
+  deren Zeilen die Summe ergeben. Dazu `pdf.position.rabatt`: ein Zeilenrabatt
+  stand bisher nirgends auf dem Blatt, „2 × 24,90 = 44,82" ging für den Leser
+  nicht auf.
+- **Kennung als Text:** `getInvoice('…')` und `getCustomer('…')` werfen vor dem
+  Senden `KasseneckValidationError` (`scope: 'request'`). Bisher wurde der Text
+  Zeichen für Zeichen zu Feldern `0`, `1`, … und der Server konnte nur
+  „Bitte Eingaben prüfen." antworten.
+- **Feldfehler in der Meldung:** `KasseneckApiError.message` hängt bis zu fünf
+  Einträge aus `errors[]` an (`[items[0].vatRate: …]`); `serverMessage` und
+  `details` bleiben unverändert.
+
+## 0.21.0
+
+### Rechnung: Kataloge für den abgeleiteten Steuerfall
+
+**Anlass:** Der Server leitet den Steuerfall jetzt selbst ab, statt ihn zu
+glauben (Kundenland, Kundenart, UID, Ware oder Leistung).
+
+- `taxScheme` ist in `issueInvoice` **optional**; eine Angabe prüft der Server
+  gegen die Ableitung (`tax_scheme_mismatch`).
+- Neue Fälle `domesticReverseCharge`, `oss` und `outsideScope`; Katalog der elf
+  Gründe für den Übergang der Steuerschuld im Inland
+  (`REVERSE_CHARGE_REASONS`, mit Fundstelle und Schwelle).
+  `oss` steht im Katalog, **kann aber noch nicht ausgestellt werden** —
+  die Ländersätze folgen.
+- Positionen tragen `kind` (`goods`/`service`), weil ig. Lieferung und Reverse
+  Charge sich genau daran unterscheiden.
+- `notice` ist an `issueInvoice` eine **Liste**: eine bar bezahlte ig. Lieferung
+  trägt zwei Hinweise zugleich.
+- Die Rechnungssicht trägt `reverseChargeReason` und `taxCountry`; neuer
+  Befreiungstext für den nicht steuerbaren Umsatz (E-Rechnung, BR-O-10).
+
 ## 0.20.0
 
 ### Rechnung: richtige Steuerhinweise, Barumsatz auch mit Karte

package/README.md

@@ -547,6 +547,41 @@ await rechnungen.recordInvoicePayment({
 `reference` wird gespeichert, aber **nicht gedruckt**; Kartendaten gehören
 ohnehin nicht auf eine Rechnung.
 
+**Vorab rechnen.** Wer kassiert, bevor die Rechnung entsteht, braucht den
+Betrag, den die Rechnung später ausweist. `rechnungSummen` rechnet ihn genau
+wie der Server; `previewInvoice` fragt den Server selbst — ein Probelauf, der
+prüft wie das Ausstellen, aber nichts festschreibt und den `idempotencyKey`
+nicht verbraucht:
+
+```ts
+import { rechnungSummen } from '@kreiseck/kasseneck-api/rechnung';
+
+const posten = [
+  { description: 'Maniküre', quantity: 1, unitPriceCents: 1479, vatRate: 20 as const },
+  { description: 'Lack', quantity: 1, unitPriceCents: 1500, vatRate: 20 as const },
+];
+rechnungSummen(posten, 'gross');
+// { netCents: 2483, vatCents: 496, grossCents: 2979, byRate: [{ rate: 20, … }] }
+
+const anfrage = { idempotencyKey: `bestellung-${bestellnummer}`, customerId: kunde.id,
+  priceMode: 'gross' as const, serviceStart: '2026-09-16', items: posten };
+const { preview, notice } = await rechnungen.previewInvoice(anfrage);
+// preview.totals, preview.taxScheme, preview.taxSchemeReason — dann:
+await rechnungen.issueInvoice(anfrage);
+```
+
+Im **Brutto-Modus** ist das Brutto je Satz der vereinbarte Preis: Netto =
+round(B × 100 / (100 + Satz)), USt = B − Netto. Im **Netto-Modus** wird die USt
+je Satz aus der Nettosumme gerundet. Gerundet wird kaufmännisch (halber Cent
+aufwärts), je Satz, dann summiert. Die Prüffälle liegen in
+`fixtures/rechnung-summen.json`. Die Summen sind auch bei Gutschriften positiv —
+das Vorzeichen steht im Belegtyp (`docType: 'GU'`).
+
+**Hinweise** (`notice`) sind immer eine Liste — bei `issueInvoice`,
+`previewInvoice` und `recordInvoicePayment`. Eine ig. Lieferung trägt
+`recapitulative_statement_due` (Zusammenfassende Meldung), eine bar bezahlte
+Rechnung zusätzlich `cash_receipt_required`.
+
 **Barumsatz ist nicht nur Bargeld.** Als Barzahlung gilt auch die Karte **vor
 Ort** an der Kasse (§ 131b Abs. 1 Z 3 UStG) — dieselbe Karte im Internet
 dagegen nicht. Weil `card` und `online` beides sein können, sagt es das
@@ -557,8 +592,8 @@ payment: { method: 'card', onSite: true }   // Terminal an der Kasse
 payment: { method: 'card' }                 // Kartenzahlung im Shop
 ```
 
-Bei `cash` (immer) und bei `onSite: true` trägt die Antwort
-`notice.code = 'cash_receipt_required'`: ein Barumsatz braucht einen Beleg
+Bei `cash` (immer) und bei `onSite: true` trägt die Antwort in der Liste
+`notice` den Eintrag `cash_receipt_required`: ein Barumsatz braucht einen Beleg
 (§ 132a BAO), bei Registrierkassenpflicht über die Registrierkasse — der
 Vermerk an der Rechnung ersetzt ihn nicht. `transfer` mit `onSite` ist ein
 Feldfehler, eine Überweisung erfolgt nicht vor Ort.

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

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

package/dist/cjs/client/errors.js

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

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

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

package/dist/cjs/rechnung/api.js

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

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

@@ -18,7 +18,7 @@
  */
 import type { InternerBinaerTransport, InternerTransport } from '../client/aufrufe.js';
 import type { EInvoiceFormat, InvoiceLanguage } from './vertrag.js';
-import type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, IssueInvoiceRequest, IssueResult, RecordPaymentRequest, RecordPaymentResult } from './typen.js';
+import type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, IssueInvoiceRequest, IssueResult, PreviewResult, RecordPaymentRequest, RecordPaymentResult } from './typen.js';
 export declare function createCustomer(rufen: InternerTransport, customer: CustomerInput, optionen?: {
     idempotencyKey?: string;
 }): Promise<Customer>;
@@ -30,6 +30,17 @@ export declare function getCustomer(rufen: InternerTransport, kennung: {
 export declare function updateCustomer(rufen: InternerTransport, customerId: string, patch: Partial<CustomerInput>): Promise<Customer>;
 export declare function searchCustomers(rufen: InternerTransport, suche: CustomerSearch): Promise<CustomerPage>;
 export declare function issueInvoice(rufen: InternerTransport, anfrage: IssueInvoiceRequest): Promise<IssueResult>;
+/**
+ * Probelauf von `issueInvoice`: dieselbe Anfrage wird geprueft und gerechnet
+ * wie beim Ausstellen, aber nichts festgeschrieben. Die Antwort nennt Summen,
+ * Steuerfall, Sprache, Marke und die Hinweise — oder scheitert mit demselben
+ * Fehlercode, mit dem das Ausstellen scheitern wuerde.
+ *
+ * Der `idempotencyKey` wird nicht verbraucht: dieselbe Anfrage laesst sich
+ * danach unveraendert ausstellen. Verbindlich ist das Ausstellen — zwischen
+ * Probelauf und Ausstellen kann sich der Kunde oder das Konto aendern.
+ */
+export declare function previewInvoice(rufen: InternerTransport, anfrage: IssueInvoiceRequest): Promise<PreviewResult>;
 export declare function cancelInvoice(rufen: InternerTransport, anfrage: CancelInvoiceRequest): Promise<CancelResult>;
 export declare function createCreditNote(rufen: InternerTransport, anfrage: CreditNoteRequest): Promise<CreditNoteResult>;
 export declare function getInvoice(rufen: InternerTransport, kennung: {

package/dist/cjs/rechnung/endpunkte.js

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

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

@@ -13,7 +13,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/cjs/rechnung/index.js

@@ -12,7 +12,7 @@
  * Benutzung des Clients.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RECHNUNG_MINDESTENS_EINS = exports.RECHNUNG_GENAU_EINS = exports.RECHNUNG_ANFRAGEN = exports.POSITION_FELDER = exports.KUNDE_FELDER = exports.INVOICE_SETUP_REQUIREMENTS = exports.RECHNUNG_EINHEITEN_CODES = exports.INVOICE_UNITS = exports.INVOICE_NOTICE_CODES = exports.REVERSE_CHARGE_REASONS = exports.ITEM_KINDS = exports.INVOICE_PAYMENT_METHODS = exports.INVOICE_LANGUAGES = exports.EINVOICE_FORMATS = exports.DOC_TYPES = exports.INVOICE_LIST_STATUS = exports.CUSTOMER_TYPES = exports.VAT_RATES = exports.PRICE_MODES = exports.TAX_SCHEMES = exports.CREDIT_NOTE_REASONS = exports.INVOICE_ERROR_CODES = exports.RECHNUNG_AUFRUFE = exports.RECHNUNG_VERTRAG_VERSION = exports.rechnungText = exports.RECHNUNG_TEXTE = exports.updateCustomer = exports.searchCustomers = exports.recordInvoicePayment = exports.listInvoices = exports.listBrands = exports.issueInvoice = exports.getInvoiceXml = exports.getInvoiceSetupStatus = exports.getInvoicePdf = exports.getInvoice = exports.getCustomer = exports.createCustomer = exports.createCreditNote = exports.cancelInvoice = exports.rechnungFeldFehler = exports.rechnungFehlerCode = exports.istRechnungFehler = exports.rechnungKeyAuth = exports.createRechnungApi = void 0;
+exports.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;
 var api_js_1 = require("./api.js");
 Object.defineProperty(exports, "createRechnungApi", { enumerable: true, get: function () { return api_js_1.createRechnungApi; } });
 var auth_js_1 = require("./auth.js");
@@ -33,12 +33,16 @@ Object.defineProperty(exports, "getInvoiceXml", { enumerable: true, get: functio
 Object.defineProperty(exports, "issueInvoice", { enumerable: true, get: function () { return endpunkte_js_1.issueInvoice; } });
 Object.defineProperty(exports, "listBrands", { enumerable: true, get: function () { return endpunkte_js_1.listBrands; } });
 Object.defineProperty(exports, "listInvoices", { enumerable: true, get: function () { return endpunkte_js_1.listInvoices; } });
+Object.defineProperty(exports, "previewInvoice", { enumerable: true, get: function () { return endpunkte_js_1.previewInvoice; } });
 Object.defineProperty(exports, "recordInvoicePayment", { enumerable: true, get: function () { return endpunkte_js_1.recordInvoicePayment; } });
 Object.defineProperty(exports, "searchCustomers", { enumerable: true, get: function () { return endpunkte_js_1.searchCustomers; } });
 Object.defineProperty(exports, "updateCustomer", { enumerable: true, get: function () { return endpunkte_js_1.updateCustomer; } });
 var texte_js_1 = require("./texte.js");
 Object.defineProperty(exports, "RECHNUNG_TEXTE", { enumerable: true, get: function () { return texte_js_1.RECHNUNG_TEXTE; } });
 Object.defineProperty(exports, "rechnungText", { enumerable: true, get: function () { return texte_js_1.rechnungText; } });
+var summen_js_1 = require("./summen.js");
+Object.defineProperty(exports, "rechnungSummen", { enumerable: true, get: function () { return summen_js_1.rechnungSummen; } });
+Object.defineProperty(exports, "STEUERFREIE_FAELLE", { enumerable: true, get: function () { return summen_js_1.STEUERFREIE_FAELLE; } });
 var 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/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/cjs/rechnung/summen.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * 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.
+ */
+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',
+]);
+/** 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.
+ */
+function rechnungSummen(items, priceMode, taxScheme = 'normal') {
+    const steuerfrei = exports.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/cjs/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/cjs/rechnung/texte.js

@@ -24,8 +24,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).',
@@ -230,8 +234,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/cjs/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/cjs/rechnung/vertrag.js

@@ -420,6 +420,12 @@ exports.RECHNUNG_ANFRAGEN = Object.freeze({
          * und ein sofort geholtes PDF Zahlungsinformationen traegt.
          */
         payment: { typ: 'object', pflicht: false, felder: exports.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/dist/esm/client/errors.d.ts

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