@kreiseck/kasseneck-api 0.14.0 → 0.15.0

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

@@ -0,0 +1,21 @@
+/**
+ * Anmeldung fuer die Rechnungs-API: der `api_key` des Kontos als Bearer.
+ *
+ * Anders als `apiKeyAuth` **ohne** `cashregister-token` — eine Rechnung
+ * entsteht nicht an einer Kasse, sondern am Konto.
+ *
+ * **Der Schluessel gehoert auf einen Server.** Mit ihm entstehen festgeschriebene
+ * Rechnungen mit fortlaufender Nummer, die sich nur noch per Gutschrift
+ * korrigieren lassen.
+ *
+ * Geprueft wird nur, was ohne Netz sicher falsch ist: ein leerer Wert, ein
+ * Partner-Schluessel (`pk_…`) oder ein Kassen-Token (`cb_…`). Die Form des
+ * Kontoschluessels selbst bleibt offen, weil das Backend neben `kr_<env>_…`
+ * weiterhin aeltere Formen annimmt. Die Meldung nennt nie den Wert, nur seine Art.
+ */
+import type { KasseneckAuth } from '../client/auth.js';
+export interface RechnungKeyAuthOptions {
+    /** `api_key` des Kontos, z. B. `kr_live_…` oder `kr_test_…`. */
+    apiKey: string;
+}
+export declare function rechnungKeyAuth(options: RechnungKeyAuthOptions): KasseneckAuth;

package/dist/esm/rechnung/auth.js

@@ -0,0 +1,33 @@
+/**
+ * Anmeldung fuer die Rechnungs-API: der `api_key` des Kontos als Bearer.
+ *
+ * Anders als `apiKeyAuth` **ohne** `cashregister-token` — eine Rechnung
+ * entsteht nicht an einer Kasse, sondern am Konto.
+ *
+ * **Der Schluessel gehoert auf einen Server.** Mit ihm entstehen festgeschriebene
+ * Rechnungen mit fortlaufender Nummer, die sich nur noch per Gutschrift
+ * korrigieren lassen.
+ *
+ * Geprueft wird nur, was ohne Netz sicher falsch ist: ein leerer Wert, ein
+ * Partner-Schluessel (`pk_…`) oder ein Kassen-Token (`cb_…`). Die Form des
+ * Kontoschluessels selbst bleibt offen, weil das Backend neben `kr_<env>_…`
+ * weiterhin aeltere Formen annimmt. Die Meldung nennt nie den Wert, nur seine Art.
+ */
+import { KasseneckAuthError } from '../client/errors.js';
+export function rechnungKeyAuth(options) {
+    const schluessel = typeof options?.apiKey === 'string' ? options.apiKey.trim() : '';
+    if (!schluessel) {
+        throw new KasseneckAuthError('rechnungKeyAuth: apiKey fehlt');
+    }
+    if (/^pk_(live|test)_/i.test(schluessel)) {
+        throw new KasseneckAuthError('rechnungKeyAuth: das ist ein Partner-Schluessel (pk_…) — die Rechnungs-API nimmt den api_key des Kontos (kr_…)');
+    }
+    if (/^cb_(live|test)_/i.test(schluessel)) {
+        throw new KasseneckAuthError('rechnungKeyAuth: das ist ein Kassen-Token (cb_…) — die Rechnungs-API nimmt den api_key des Kontos (kr_…)');
+    }
+    // Pro Aufruf ein frisches Objekt, wie bei den anderen Anmeldungen.
+    return () => ({
+        headers: { Authorization: `Bearer ${schluessel}` },
+        params: {},
+    });
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 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'`.
+ */
+import type { InternerBinaerTransport, InternerTransport } from '../client/aufrufe.js';
+import type { EInvoiceFormat } from './vertrag.js';
+import type { CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, IssueInvoiceRequest, IssueResult } from './typen.js';
+export declare function createCustomer(rufen: InternerTransport, customer: CustomerInput, optionen?: {
+    idempotencyKey?: string;
+}): Promise<Customer>;
+export declare function getCustomer(rufen: InternerTransport, kennung: {
+    customerId: string;
+} | {
+    externalId: string;
+}): Promise<Customer>;
+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>;
+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: {
+    invoiceId: string;
+} | {
+    number: string;
+}): Promise<InvoiceDetail>;
+export declare function listInvoices(rufen: InternerTransport, abfrage?: InvoiceListQuery): Promise<InvoicePage>;
+/** Das PDF der Rechnung (bei Gutschriften: der Gutschrift), mit eingebetteter Factur-X-Datei. */
+export declare function getInvoicePdf(rufenBinaer: InternerBinaerTransport, invoiceId: string): Promise<Uint8Array>;
+/**
+ * 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.
+ */
+export declare function getInvoiceXml(rufen: InternerTransport, invoiceId: string, format?: EInvoiceFormat): Promise<string>;

package/dist/esm/rechnung/endpunkte.js

@@ -0,0 +1,116 @@
+/**
+ * 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'`.
+ */
+import { KasseneckValidationError } from '../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 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 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 -----------------------------------------------------------------
+export 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');
+}
+export async function getCustomer(rufen, kennung) {
+    const daten = await rufen('getCustomer', nutzlast(kennung));
+    return pflichtObjekt('getCustomer', daten, 'customer');
+}
+export async function updateCustomer(rufen, customerId, patch) {
+    const daten = await rufen('updateCustomer', { customerId, customer: patch });
+    return pflichtObjekt('updateCustomer', daten, 'customer');
+}
+export async function searchCustomers(rufen, suche) {
+    const daten = await rufen('searchCustomers', nutzlast(suche));
+    const { eintraege, nextCursor } = seite('searchCustomers', daten, 'customers');
+    return { customers: eintraege, nextCursor };
+}
+// ---- Rechnungen -------------------------------------------------------------
+export async function issueInvoice(rufen, anfrage) {
+    const daten = await rufen('issueInvoice', nutzlast(anfrage));
+    return {
+        invoice: pflichtObjekt('issueInvoice', daten, 'invoice'),
+        replayed: objekt(daten)['replayed'] === true,
+    };
+}
+export 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,
+    };
+}
+export 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,
+    };
+}
+export async function getInvoice(rufen, kennung) {
+    const daten = await rufen('getInvoice', nutzlast(kennung));
+    return pflichtObjekt('getInvoice', daten, 'invoice');
+}
+export 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. */
+export 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.
+ */
+export 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 KasseneckValidationError('getInvoiceXml', 'Antwort ohne xml', 'response');
+    }
+    return xml;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * 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 { KasseneckApiError } from '../client/errors.js';
+import { INVOICE_ERROR_CODES } from './vertrag.js';
+const BEKANNT = new Set(INVOICE_ERROR_CODES);
+/** Der Fehlercode eines geworfenen Fehlers — `undefined`, wenn es keiner der Rechnungs-API ist. */
+export function rechnungFehlerCode(error) {
+    if (!(error instanceof KasseneckApiError))
+        return undefined;
+    const code = error.code;
+    return code !== undefined && BEKANNT.has(code) ? code : undefined;
+}
+/** Kurzform fuer `catch (e) { if (istRechnungFehler(e, 'customer_exists')) … }`. */
+export function istRechnungFehler(error, code) {
+    return rechnungFehlerCode(error) === code;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export function rechnungFeldFehler(error) {
+    if (!(error instanceof 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/esm/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/esm/rechnung/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@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 } from './api.js';
+export { rechnungKeyAuth } from './auth.js';
+export { istRechnungFehler, rechnungFehlerCode, rechnungFeldFehler, } from './fehler.js';
+export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceXml, issueInvoice, listInvoices, searchCustomers, updateCustomer, } from './endpunkte.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, } from './vertrag.js';

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

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export {};

package/dist/esm/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[])[]>>>;