@kreiseck/kasseneck-api 0.13.2 → 0.15.0

package/dist/cjs/rechnung/endpunkte.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Die Aufrufe der Rechnungs-API — Kunden, Rechnungen, Gutschriften, Dateien.
+ *
+ * Jede Funktion nimmt den Transport als ersten Parameter und ist einzeln
+ * importierbar; die Fassade [createRechnungApi] bindet ihn nur einmal.
+ *
+ * **Geprueft wird hier nichts Fachliches.** Die Anfrage geht unveraendert an
+ * das Backend, das sie gegen denselben Vertrag prueft (`vertrag.ts`) und einen
+ * Formfehler als `validation` mit `errors[]` zurueckgibt — zwei Pruefungen
+ * hiessen zwei Wahrheiten, von denen eine veraltet.
+ *
+ * **Nicht automatisch wiederholen.** Wer nach einem Zeitlimit erneut
+ * ausstellt, tut das mit **demselben** `idempotencyKey`: dann kommt die schon
+ * ausgestellte Rechnung zurueck (`replayed: true`) statt einer zweiten.
+ *
+ * Nach dem Senden wird nichts hart gecastet: fehlt ein zugesagtes Feld, wirft
+ * der Aufruf `KasseneckValidationError` mit `scope:'response'`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCustomer = createCustomer;
+exports.getCustomer = getCustomer;
+exports.updateCustomer = updateCustomer;
+exports.searchCustomers = searchCustomers;
+exports.issueInvoice = issueInvoice;
+exports.cancelInvoice = cancelInvoice;
+exports.createCreditNote = createCreditNote;
+exports.getInvoice = getInvoice;
+exports.listInvoices = listInvoices;
+exports.getInvoicePdf = getInvoicePdf;
+exports.getInvoiceXml = getInvoiceXml;
+const errors_js_1 = require("../client/errors.js");
+function objekt(wert) {
+    return wert !== null && typeof wert === 'object' && !Array.isArray(wert)
+        ? wert
+        : {};
+}
+/** Ein zugesagtes Objektfeld der Antwort — oder ein Antwortfehler. */
+function pflichtObjekt(aufruf, daten, feld) {
+    const wert = objekt(daten)[feld];
+    if (wert === null || typeof wert !== 'object' || Array.isArray(wert)) {
+        throw new errors_js_1.KasseneckValidationError(aufruf, `Antwort ohne ${feld}`, 'response');
+    }
+    return wert;
+}
+/** Eine zugesagte Liste samt Cursor — oder ein Antwortfehler. */
+function seite(aufruf, daten, feld) {
+    const o = objekt(daten);
+    if (!Array.isArray(o[feld])) {
+        throw new errors_js_1.KasseneckValidationError(aufruf, `Antwort ohne ${feld}`, 'response');
+    }
+    return { eintraege: o[feld], nextCursor: typeof o['nextCursor'] === 'string' ? o['nextCursor'] : null };
+}
+const zahl = (wert) => (typeof wert === 'number' && Number.isFinite(wert) ? wert : 0);
+/** Anfrageobjekt als Nutzlast — flache Kopie, damit der Aufrufer sein Objekt behaelt. */
+const nutzlast = (anfrage) => ({ ...anfrage });
+// ---- Kunden -----------------------------------------------------------------
+async function createCustomer(rufen, customer, optionen = {}) {
+    const params = { customer };
+    if (optionen.idempotencyKey)
+        params['idempotencyKey'] = optionen.idempotencyKey;
+    const daten = await rufen('createCustomer', params);
+    return pflichtObjekt('createCustomer', daten, 'customer');
+}
+async function getCustomer(rufen, kennung) {
+    const daten = await rufen('getCustomer', nutzlast(kennung));
+    return pflichtObjekt('getCustomer', daten, 'customer');
+}
+async function updateCustomer(rufen, customerId, patch) {
+    const daten = await rufen('updateCustomer', { customerId, customer: patch });
+    return pflichtObjekt('updateCustomer', daten, 'customer');
+}
+async function searchCustomers(rufen, suche) {
+    const daten = await rufen('searchCustomers', nutzlast(suche));
+    const { eintraege, nextCursor } = seite('searchCustomers', daten, 'customers');
+    return { customers: eintraege, nextCursor };
+}
+// ---- Rechnungen -------------------------------------------------------------
+async function issueInvoice(rufen, anfrage) {
+    const daten = await rufen('issueInvoice', nutzlast(anfrage));
+    return {
+        invoice: pflichtObjekt('issueInvoice', daten, 'invoice'),
+        replayed: objekt(daten)['replayed'] === true,
+    };
+}
+async function cancelInvoice(rufen, anfrage) {
+    const daten = await rufen('cancelInvoice', nutzlast(anfrage));
+    return {
+        creditNote: pflichtObjekt('cancelInvoice', daten, 'creditNote'),
+        original: pflichtObjekt('cancelInvoice', daten, 'original'),
+        originalPaidCents: zahl(objekt(daten)['originalPaidCents']),
+        replayed: objekt(daten)['replayed'] === true,
+    };
+}
+async function createCreditNote(rufen, anfrage) {
+    const daten = await rufen('createCreditNote', nutzlast(anfrage));
+    return {
+        creditNote: pflichtObjekt('createCreditNote', daten, 'creditNote'),
+        remainingCents: zahl(objekt(daten)['remainingCents']),
+        replayed: objekt(daten)['replayed'] === true,
+    };
+}
+async function getInvoice(rufen, kennung) {
+    const daten = await rufen('getInvoice', nutzlast(kennung));
+    return pflichtObjekt('getInvoice', daten, 'invoice');
+}
+async function listInvoices(rufen, abfrage = {}) {
+    const daten = await rufen('listInvoices', nutzlast(abfrage));
+    const { eintraege, nextCursor } = seite('listInvoices', daten, 'invoices');
+    return { invoices: eintraege, nextCursor };
+}
+// ---- Dateien ----------------------------------------------------------------
+/** Das PDF der Rechnung (bei Gutschriften: der Gutschrift), mit eingebetteter Factur-X-Datei. */
+function getInvoicePdf(rufenBinaer, invoiceId) {
+    return rufenBinaer('getInvoicePdf', { invoiceId });
+}
+/**
+ * Die E-Rechnung als XML-Text. Sie kommt im gewohnten Umschlag (`data.xml`)
+ * und nicht als rohe Datei: so bleibt ein fachlicher Fehler
+ * (`einvoice_incomplete` mit `missing[]`) ein gewoehnlicher Fehler.
+ */
+async function getInvoiceXml(rufen, invoiceId, format = 'ubl') {
+    const daten = await rufen('getInvoiceXml', { invoiceId, format });
+    const xml = objekt(daten)['xml'];
+    if (typeof xml !== 'string' || !xml) {
+        throw new errors_js_1.KasseneckValidationError('getInvoiceXml', 'Antwort ohne xml', 'response');
+    }
+    return xml;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Fehler der Rechnungs-API auswerten — am Code, nie am Text.
+ *
+ * Es zaehlen nur Codes aus dem Vertrag ([INVOICE_ERROR_CODES]). Ein fremder
+ * Code (z. B. aus einer vorgeschalteten Schicht) ist fuer diese Helfer kein
+ * Rechnungs-Fehler: wer darauf verzweigt, soll es bewusst ueber
+ * `KasseneckApiError.code` tun.
+ */
+import { type InvoiceErrorCode } from './vertrag.js';
+/** Der Fehlercode eines geworfenen Fehlers — `undefined`, wenn es keiner der Rechnungs-API ist. */
+export declare function rechnungFehlerCode(error: unknown): InvoiceErrorCode | undefined;
+/** Kurzform fuer `catch (e) { if (istRechnungFehler(e, 'customer_exists')) … }`. */
+export declare function istRechnungFehler(error: unknown, code: InvoiceErrorCode): boolean;
+/** Ein Feldfehler aus `data.errors[]` einer `validation`-Antwort. */
+export interface RechnungFeldFehler {
+    /** Feldpfad in der gesendeten Anfrage, z. B. `items[2].vatRate` oder `customer.vatId`. */
+    field: string;
+    message: string;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export declare function rechnungFeldFehler(error: unknown): RechnungFeldFehler[];

package/dist/cjs/rechnung/fehler.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Fehler der Rechnungs-API auswerten — am Code, nie am Text.
+ *
+ * Es zaehlen nur Codes aus dem Vertrag ([INVOICE_ERROR_CODES]). Ein fremder
+ * Code (z. B. aus einer vorgeschalteten Schicht) ist fuer diese Helfer kein
+ * Rechnungs-Fehler: wer darauf verzweigt, soll es bewusst ueber
+ * `KasseneckApiError.code` tun.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rechnungFehlerCode = rechnungFehlerCode;
+exports.istRechnungFehler = istRechnungFehler;
+exports.rechnungFeldFehler = rechnungFeldFehler;
+const errors_js_1 = require("../client/errors.js");
+const vertrag_js_1 = require("./vertrag.js");
+const BEKANNT = new Set(vertrag_js_1.INVOICE_ERROR_CODES);
+/** Der Fehlercode eines geworfenen Fehlers — `undefined`, wenn es keiner der Rechnungs-API ist. */
+function rechnungFehlerCode(error) {
+    if (!(error instanceof errors_js_1.KasseneckApiError))
+        return undefined;
+    const code = error.code;
+    return code !== undefined && BEKANNT.has(code) ? code : undefined;
+}
+/** Kurzform fuer `catch (e) { if (istRechnungFehler(e, 'customer_exists')) … }`. */
+function istRechnungFehler(error, code) {
+    return rechnungFehlerCode(error) === code;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+function rechnungFeldFehler(error) {
+    if (!(error instanceof errors_js_1.KasseneckApiError))
+        return [];
+    const roh = error.details['errors'];
+    if (!Array.isArray(roh))
+        return [];
+    const raus = [];
+    for (const eintrag of roh) {
+        if (eintrag === null || typeof eintrag !== 'object')
+            continue;
+        const { field, message } = eintrag;
+        if (typeof field === 'string' && typeof message === 'string')
+            raus.push({ field, message });
+    }
+    return raus;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * `@kreiseck/kasseneck-api/rechnung` — Rechnungen (§ 11 UStG, keine Belege)
+ * und Kunden ueber die Rechnungs-API.
+ *
+ * Ein eigener Unterpfad wie `partner`: der `api_key` eines Kontos, mit dem
+ * Rechnungen ausgestellt werden, gehoert auf einen **Server** und soll nicht
+ * versehentlich in ein Browser-Buendel der Kasse wandern.
+ *
+ * Die Beschreibung der Endpunkte steht in der Referenz des Backends
+ * (`docs/api/rechnungen.md`). Was hier steht, ist der Vertrag als Daten und die
+ * Benutzung des Clients.
+ */
+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, getInvoiceXml, issueInvoice, listInvoices, searchCustomers, updateCustomer, } from './endpunkte.js';
+export type { CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, EInvoiceStatus, Invoice, InvoiceDetail, InvoiceItem, InvoiceItemInput, InvoiceListQuery, InvoicePage, InvoiceRecipient, InvoiceTotals, IssueInvoiceRequest, IssueResult, } from './typen.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, 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 Format, type Feld, } from './vertrag.js';

package/dist/cjs/rechnung/index.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * `@kreiseck/kasseneck-api/rechnung` — Rechnungen (§ 11 UStG, keine Belege)
+ * und Kunden ueber die Rechnungs-API.
+ *
+ * Ein eigener Unterpfad wie `partner`: der `api_key` eines Kontos, mit dem
+ * Rechnungen ausgestellt werden, gehoert auf einen **Server** und soll nicht
+ * versehentlich in ein Browser-Buendel der Kasse wandern.
+ *
+ * Die Beschreibung der Endpunkte steht in der Referenz des Backends
+ * (`docs/api/rechnungen.md`). Was hier steht, ist der Vertrag als Daten und die
+ * 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.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.updateCustomer = exports.searchCustomers = exports.listInvoices = exports.issueInvoice = exports.getInvoiceXml = 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");
+Object.defineProperty(exports, "rechnungKeyAuth", { enumerable: true, get: function () { return auth_js_1.rechnungKeyAuth; } });
+var fehler_js_1 = require("./fehler.js");
+Object.defineProperty(exports, "istRechnungFehler", { enumerable: true, get: function () { return fehler_js_1.istRechnungFehler; } });
+Object.defineProperty(exports, "rechnungFehlerCode", { enumerable: true, get: function () { return fehler_js_1.rechnungFehlerCode; } });
+Object.defineProperty(exports, "rechnungFeldFehler", { enumerable: true, get: function () { return fehler_js_1.rechnungFeldFehler; } });
+var endpunkte_js_1 = require("./endpunkte.js");
+Object.defineProperty(exports, "cancelInvoice", { enumerable: true, get: function () { return endpunkte_js_1.cancelInvoice; } });
+Object.defineProperty(exports, "createCreditNote", { enumerable: true, get: function () { return endpunkte_js_1.createCreditNote; } });
+Object.defineProperty(exports, "createCustomer", { enumerable: true, get: function () { return endpunkte_js_1.createCustomer; } });
+Object.defineProperty(exports, "getCustomer", { enumerable: true, get: function () { return endpunkte_js_1.getCustomer; } });
+Object.defineProperty(exports, "getInvoice", { enumerable: true, get: function () { return endpunkte_js_1.getInvoice; } });
+Object.defineProperty(exports, "getInvoicePdf", { enumerable: true, get: function () { return endpunkte_js_1.getInvoicePdf; } });
+Object.defineProperty(exports, "getInvoiceXml", { enumerable: true, get: function () { return endpunkte_js_1.getInvoiceXml; } });
+Object.defineProperty(exports, "issueInvoice", { enumerable: true, get: function () { return endpunkte_js_1.issueInvoice; } });
+Object.defineProperty(exports, "listInvoices", { enumerable: true, get: function () { return endpunkte_js_1.listInvoices; } });
+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 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; } });
+Object.defineProperty(exports, "INVOICE_ERROR_CODES", { enumerable: true, get: function () { return vertrag_js_1.INVOICE_ERROR_CODES; } });
+Object.defineProperty(exports, "CREDIT_NOTE_REASONS", { enumerable: true, get: function () { return vertrag_js_1.CREDIT_NOTE_REASONS; } });
+Object.defineProperty(exports, "TAX_SCHEMES", { enumerable: true, get: function () { return vertrag_js_1.TAX_SCHEMES; } });
+Object.defineProperty(exports, "PRICE_MODES", { enumerable: true, get: function () { return vertrag_js_1.PRICE_MODES; } });
+Object.defineProperty(exports, "VAT_RATES", { enumerable: true, get: function () { return vertrag_js_1.VAT_RATES; } });
+Object.defineProperty(exports, "CUSTOMER_TYPES", { enumerable: true, get: function () { return vertrag_js_1.CUSTOMER_TYPES; } });
+Object.defineProperty(exports, "INVOICE_LIST_STATUS", { enumerable: true, get: function () { return vertrag_js_1.INVOICE_LIST_STATUS; } });
+Object.defineProperty(exports, "DOC_TYPES", { enumerable: true, get: function () { return vertrag_js_1.DOC_TYPES; } });
+Object.defineProperty(exports, "EINVOICE_FORMATS", { enumerable: true, get: function () { return vertrag_js_1.EINVOICE_FORMATS; } });
+Object.defineProperty(exports, "KUNDE_FELDER", { enumerable: true, get: function () { return vertrag_js_1.KUNDE_FELDER; } });
+Object.defineProperty(exports, "POSITION_FELDER", { enumerable: true, get: function () { return vertrag_js_1.POSITION_FELDER; } });
+Object.defineProperty(exports, "RECHNUNG_ANFRAGEN", { enumerable: true, get: function () { return vertrag_js_1.RECHNUNG_ANFRAGEN; } });
+Object.defineProperty(exports, "RECHNUNG_GENAU_EINS", { enumerable: true, get: function () { return vertrag_js_1.RECHNUNG_GENAU_EINS; } });
+Object.defineProperty(exports, "RECHNUNG_MINDESTENS_EINS", { enumerable: true, get: function () { return vertrag_js_1.RECHNUNG_MINDESTENS_EINS; } });

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

@@ -0,0 +1,224 @@
+/**
+ * Typen der Rechnungs-API. Die Anfragen folgen `vertrag.ts` Feld fuer Feld;
+ * `test/rechnung-client.test.ts` schickt die Beispiele des Vertrags durch.
+ *
+ * Betraege sind ueberall ganze Cent. Datumsangaben sind `YYYY-MM-DD` nach
+ * Wiener Kalender.
+ */
+import type { CreditNoteReason, CustomerType, DocType, InvoiceListStatus, PriceMode, TaxScheme, VatRatePercent } from './vertrag.js';
+export interface CustomerInput {
+    type: CustomerType;
+    name: string;
+    legalForm?: string;
+    email?: string;
+    phone?: string;
+    street?: string;
+    houseNumber?: string;
+    zip?: string;
+    city?: string;
+    /** ISO-3166-Alpha-2, z. B. `AT`. */
+    country: string;
+    /** UID-Nummer, z. B. `ATU12345678`. */
+    vatId?: string;
+    /** Kuerzel fuer die Rechnungsnummer; einmal gesetzt unveraenderlich. */
+    shortCode?: string;
+    /** Behoerde (B2G) — die E-Rechnung verlangt dann Adresse und `orderReference`. */
+    isAuthority?: boolean;
+    note?: string;
+    /** Kennung im eigenen System; je Konto eindeutig. */
+    externalId?: string;
+}
+export interface Customer {
+    id: string;
+    type: CustomerType;
+    name: string;
+    legalForm: string | null;
+    email: string | null;
+    phone: string | null;
+    street: string | null;
+    houseNumber: string | null;
+    zip: string | null;
+    city: string | null;
+    country: string;
+    vatId: string | null;
+    shortCode: string | null;
+    isAuthority: boolean;
+    note: string | null;
+    externalId: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface CustomerSearch {
+    externalId?: string;
+    vatId?: string;
+    email?: string;
+    /** Namensanfang, Gross-/Kleinschreibung und Akzente egal. */
+    name?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface CustomerPage {
+    customers: Customer[];
+    nextCursor: string | null;
+}
+export interface InvoiceItemInput {
+    description: string;
+    subtitle?: string;
+    /** Hoechstens drei Nachkommastellen. */
+    quantity: number;
+    unit?: string;
+    /** Einzelpreis in ganzen Cent, im `priceMode` der Rechnung (netto oder brutto). */
+    unitPriceCents: number;
+    vatRate: VatRatePercent;
+    /** Zeilenrabatt in Prozent, hoechstens zwei Nachkommastellen. */
+    discountPct?: number;
+}
+export interface IssueInvoiceRequest {
+    /** Pflicht: dieselbe Anfrage mit demselben Schluessel erzeugt nie eine zweite Rechnung. */
+    idempotencyKey: string;
+    /** Pflicht ueber 400 € brutto sowie bei Reverse Charge und ig. Lieferung. */
+    customerId?: string;
+    taxScheme: TaxScheme;
+    priceMode: PriceMode;
+    /** Leistungsdatum bzw. Beginn des Leistungszeitraums. */
+    serviceStart: string;
+    serviceEnd?: string;
+    paymentTermDays?: number;
+    orderReference?: string;
+    intro?: string;
+    note?: string;
+    /** Verwendungszweck fuer die Ueberweisung; leer = Rechnungsnummer. */
+    paymentReference?: string;
+    girocode?: boolean;
+    tracking?: boolean;
+    items: InvoiceItemInput[];
+    /** Eigene Merkmale (hoechstens 20), nie gedruckt. */
+    metadata?: Record<string, string>;
+}
+export interface CancelInvoiceRequest {
+    idempotencyKey: string;
+    invoiceId: string;
+    reason: CreditNoteReason;
+    note?: string;
+}
+export interface CreditNoteRequest extends CancelInvoiceRequest {
+    items: InvoiceItemInput[];
+}
+export interface InvoiceTotals {
+    netCents: number;
+    vatCents: number;
+    grossCents: number;
+    byRate: {
+        rate: number;
+        netCents: number;
+        vatCents: number;
+    }[];
+}
+export interface EInvoiceStatus {
+    level: string;
+    formats: string[];
+    missing: string[];
+}
+export interface Invoice {
+    id: string;
+    number: string;
+    docType: DocType;
+    status: string;
+    invoiceDate: string;
+    dueDate: string | null;
+    customerId: string | null;
+    totals: InvoiceTotals;
+    einvoice: EInvoiceStatus | null;
+    statusUrl: string | null;
+    statusPassword: string | null;
+    metadata: Record<string, string>;
+}
+export interface InvoiceRecipient {
+    name: string;
+    type: CustomerType;
+    street: string | null;
+    houseNumber: string | null;
+    zip: string | null;
+    city: string | null;
+    country: string;
+    vatId: string | null;
+    shortCode: string | null;
+    email: string | null;
+    isAuthority: boolean;
+}
+/** Eine gespeicherte Position — wie gesendet, fehlende Angaben mit ihrem Standardwert. */
+export interface InvoiceItem {
+    description: string;
+    subtitle: string;
+    quantity: number;
+    unit: string;
+    unitPriceCents: number;
+    vatRate: number;
+    discountPct: number;
+}
+export interface InvoiceDetail extends Invoice {
+    items: InvoiceItem[];
+    customer: InvoiceRecipient | null;
+    taxScheme: TaxScheme;
+    priceMode: PriceMode;
+    serviceStart: string | null;
+    serviceEnd: string | null;
+    paymentTermDays: number | null;
+    orderReference: string | null;
+    payments: {
+        amountCents: number;
+        date: string;
+        method: string;
+    }[];
+    paidCents: number;
+    openCents: number;
+    overdue: boolean;
+    writtenOff: boolean;
+    writeOffReasonCode: string | null;
+    related: {
+        invoiceId: string;
+        number: string | null;
+    } | null;
+    creditNotes: {
+        id: string;
+        number: string;
+        grossCents: number;
+    }[];
+    source: string | null;
+    createdAt: string | null;
+    finalizedAt: string | null;
+}
+export interface InvoiceListQuery {
+    from?: string;
+    to?: string;
+    status?: InvoiceListStatus;
+    docType?: DocType;
+    customerId?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface InvoicePage {
+    invoices: Invoice[];
+    nextCursor: string | null;
+}
+export interface IssueResult {
+    invoice: Invoice;
+    /** `true`, wenn die Anfrage schon einmal ausgefuehrt wurde und die bestehende Rechnung zurueckkommt. */
+    replayed: boolean;
+}
+export interface CancelResult {
+    creditNote: Invoice;
+    original: {
+        id: string;
+        status: string;
+    };
+    /** Bereits auf das Original bezahlt — die Rueckerstattung ist Sache des Betriebs. */
+    originalPaidCents: number;
+    replayed: boolean;
+}
+export interface CreditNoteResult {
+    creditNote: Invoice;
+    /** Brutto, das nach dieser Gutschrift noch gutgeschrieben werden kann. */
+    remainingCents: number;
+    replayed: boolean;
+}

package/dist/cjs/rechnung/typen.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Typen der Rechnungs-API. Die Anfragen folgen `vertrag.ts` Feld fuer Feld;
+ * `test/rechnung-client.test.ts` schickt die Beispiele des Vertrags durch.
+ *
+ * Betraege sind ueberall ganze Cent. Datumsangaben sind `YYYY-MM-DD` nach
+ * Wiener Kalender.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,98 @@
+/**
+ * Der Vertrag der Rechnungs-API — als Daten, nicht als Prosa.
+ *
+ * Aus dieser Datei entstehen drei Dinge, damit sie nicht auseinanderlaufen
+ * koennen:
+ *
+ * 1. `fixtures/rechnung-api.schema.json` (`npm run fixtures:rechnung`) — das
+ *    Backend liest es aus dem vendorierten Paket und vergleicht es in beide
+ *    Richtungen mit seiner eigenen Pruefung; der Dart-Zwilling zieht es byteweise.
+ * 2. Die Listen unter `rechnung` in `fixtures/oberflaeche.json` (Codes, Gruende,
+ *    Enums) — ueber denselben Namensraum-Scan wie der Partner-Teil.
+ * 3. Die TypeScript-Typen in `typen.ts`.
+ *
+ * Nach aussen spricht die Schnittstelle Englisch: Feldnamen, Codes, Gruende.
+ * Deutsch bleibt, was ein Mensch liest (`message`, der Aufdruck eines Grundes).
+ *
+ * Beschrieben wird die Anfrage. Was der Server daraus macht — Rechnungsdatum,
+ * Nummer, Summen — ist bewusst **nicht** setzbar.
+ */
+export declare const RECHNUNG_VERTRAG_VERSION = 1;
+export declare const RECHNUNG_AUFRUFE: readonly ["createCustomer", "getCustomer", "updateCustomer", "searchCustomers", "issueInvoice", "cancelInvoice", "createCreditNote", "getInvoice", "listInvoices", "getInvoicePdf", "getInvoiceXml"];
+export type RechnungAufruf = (typeof RECHNUNG_AUFRUFE)[number];
+/**
+ * Stabile Fehlercodes. Das Fremdsystem verzweigt am Code, der Text darf sich
+ * aendern. `validation` traegt zusaetzlich `errors: [{ field, message }]`.
+ */
+export declare const INVOICE_ERROR_CODES: readonly ["validation", "idempotency_conflict", "module_inactive", "customer_not_found", "customer_exists", "short_code_taken", "short_code_immutable", "recipient_required", "invoice_requirements_missing", "invoice_not_found", "invoice_ambiguous", "not_cancellable", "partial_credit_exists", "credit_exceeds_invoice", "einvoice_incomplete"];
+export type InvoiceErrorCode = (typeof INVOICE_ERROR_CODES)[number];
+/** Gruende einer Gutschrift. Der Server druckt den deutschen Anzeigetext. */
+export declare const CREDIT_NOTE_REASONS: readonly ["cancellation", "price_reduction", "return", "incorrect_invoice", "other"];
+export type CreditNoteReason = (typeof CREDIT_NOTE_REASONS)[number];
+export declare const TAX_SCHEMES: readonly ["normal", "smallBusiness", "reverseCharge", "igLieferung", "exportThirdCountry"];
+export type TaxScheme = (typeof TAX_SCHEMES)[number];
+export declare const PRICE_MODES: readonly ["net", "gross"];
+export type PriceMode = (typeof PRICE_MODES)[number];
+export declare const VAT_RATES: readonly [0, 10, 13, 20];
+export type VatRatePercent = (typeof VAT_RATES)[number];
+export declare const CUSTOMER_TYPES: readonly ["private", "company"];
+export type CustomerType = (typeof CUSTOMER_TYPES)[number];
+export declare const INVOICE_LIST_STATUS: readonly ["final", "paid", "cancelled", "open", "overdue"];
+export type InvoiceListStatus = (typeof INVOICE_LIST_STATUS)[number];
+export declare const DOC_TYPES: readonly ["RE", "GU"];
+export type DocType = (typeof DOC_TYPES)[number];
+export declare const EINVOICE_FORMATS: readonly ["ubl", "cii"];
+export type EInvoiceFormat = (typeof EINVOICE_FORMATS)[number];
+/** Formate, die der Server mit `@kreiseck/validator` bzw. einem Muster prueft. */
+export type Format = 'email' | 'phone' | 'vatId' | 'country' | 'date' | 'shortCode';
+export type Feld = {
+    typ: 'string';
+    pflicht: boolean;
+    min?: number;
+    max: number;
+    format?: Format;
+} | {
+    typ: 'integer';
+    pflicht: boolean;
+    min: number;
+    max: number;
+} | {
+    typ: 'number';
+    pflicht: boolean;
+    min: number;
+    max: number;
+    nachkomma: number;
+    exklusivMin?: boolean;
+} | {
+    typ: 'boolean';
+    pflicht: boolean;
+} | {
+    typ: 'enum';
+    pflicht: boolean;
+    werte: readonly (string | number)[];
+} | {
+    typ: 'object';
+    pflicht: boolean;
+    felder: Readonly<Record<string, Feld>>;
+} | {
+    typ: 'list';
+    pflicht: boolean;
+    min: number;
+    max: number;
+    eintrag: Feld;
+} | {
+    typ: 'map';
+    pflicht: boolean;
+    maxSchluessel: number;
+    schluesselMuster: string;
+    wertMax: number;
+};
+/** Kunde, wie das Fremdsystem ihn schickt. `vatId` ist die UID-Nummer. */
+export declare const KUNDE_FELDER: Readonly<Record<string, Feld>>;
+/** Eine Rechnungs- oder Gutschriftsposition. Preise in ganzen Cent. */
+export declare const POSITION_FELDER: Readonly<Record<string, Feld>>;
+export declare const RECHNUNG_ANFRAGEN: Readonly<Record<RechnungAufruf, Readonly<Record<string, Feld>>>>;
+/** Genau eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */
+export declare const RECHNUNG_GENAU_EINS: Readonly<Partial<Record<RechnungAufruf, readonly (readonly string[])[]>>>;
+/** Mindestens eines dieser Felder muss gesetzt sein (je Aufruf, je Gruppe). */
+export declare const RECHNUNG_MINDESTENS_EINS: Readonly<Partial<Record<RechnungAufruf, readonly (readonly string[])[]>>>;