@kreiseck/kasseneck-api 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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.16.0
+
+### Rechnungs-API: Freigabe und Einrichtung vor dem ersten Ausstellen
+
+**Anlass:** Mit 0.15.0 konnte jedes Konto mit aktivem Modul Rechnung sofort
+automatisiert Rechnungen mit fortlaufender Nummer ausstellen — auch mit einem
+Probezeitraum, ohne Bankverbindung und mit dem ungewollten Standard-Nummernformat,
+das sich mit der ersten Rechnung sperrt. Ein Fremdsystem erfuhr erst beim
+Festschreiben, dass etwas fehlt.
+
+- Neuer Aufruf `getInvoiceSetupStatus()` → `{ ready, environment, missing }`.
+  Er läuft auch ohne Freigabe und vor der Live-Freischaltung, also genau dann,
+  wenn man die Antwort braucht.
+- `INVOICE_SETUP_REQUIREMENTS`: `module_active`, `api_enabled`, `live_enabled`,
+  `business_name`, `address`, `vat_id`, `bank_account`, `number_format`.
+- Neue Fehlercodes: `invoice_api_not_enabled` (Kasseneck hat die Rechnungs-API
+  für das Konto nicht freigegeben; nur live) und `invoice_setup_incomplete`
+  (`details.missing` wie im Status).
+
+## 0.15.0
+
+### Rechnungs-API: Rechnungen statt Belege, per `api_key`
+
+**Anlass:** Fremdsysteme (Shops, Buchhaltungssoftware) konnten Rechnungen nur
+über die Endpunkte des Panels anlegen — mit Anmeldung als Mensch, als Entwurf,
+ohne geprüfte Eingabe und ohne Schutz vor einer doppelt ausgestellten Rechnung
+nach einem Zeitlimit. Eine festgeschriebene Rechnung lässt sich aber nur per
+Gutschrift zurücknehmen; ein Doppel ist also teuer.
+
+- Neuer Unterpfad `@kreiseck/kasseneck-api/rechnung` mit `createRechnungApi`:
+  Kunden (`createCustomer`, `getCustomer`, `updateCustomer`, `searchCustomers`),
+  Rechnungen (`issueInvoice`, `cancelInvoice`, `createCreditNote`, `getInvoice`,
+  `listInvoices`) und Dateien (`getInvoicePdf`, `getInvoiceXml`).
+- Anmeldung `rechnungKeyAuth`: Kontoschlüssel als Bearer, **ohne**
+  Kassen-Token — eine Rechnung entsteht am Konto, nicht an einer Kasse. Ein
+  Partner-Schlüssel oder Kassen-Token wird ohne Netzaufruf abgewiesen.
+- Der Vertrag steht als Daten in `src/rechnung/vertrag.ts` und wird als
+  `fixtures/rechnung-api.schema.json` ausgeliefert (`npm run fixtures:rechnung`),
+  dazu Beispielanfragen unter `fixtures/rechnung-api-beispiele/`. Grund: das
+  Backend und der Dart-Zwilling prüfen gegen dieselbe Datei — die Feldliste
+  kann nicht an drei Stellen auseinanderlaufen.
+- `fixtures/oberflaeche.json` führt die elf Aufrufe und einen Abschnitt
+  `rechnung` (Fehlercodes, Gutschrift-Gründe, Steuerschemata).
+- `getInvoiceXml` liefert das XML als Text im gewohnten Umschlag statt als rohe
+  Datei: so bleibt `einvoice_incomplete` ein gewöhnlicher Fehler mit
+  `missing[]`, und der Transport braucht keinen dritten Leseweg.
+
 ## 0.14.0
 
 ### Das Beleg-Blatt: ein Beleg, der überall gleich aussieht

package/README.md

@@ -426,6 +426,80 @@ app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) =>
 });
 ```
 
+## Rechnungs-API (`./rechnung`)
+
+Für Shops, Buchhaltungs- und Branchensoftware: **Rechnungen** (§ 11 UStG) —
+keine Belege — mit dem `api_key` eines Kontos ausstellen. Eine Rechnung ist
+nach dem Aufruf **festgeschrieben**: sie trägt ihre fortlaufende Nummer, ist
+unveränderlich und lässt sich nur noch per Gutschrift korrigieren.
+
+**Was die Endpunkte tun, steht in der Referenz** — `docs/api/rechnungen.md`
+im Backend. Hier steht, wie man den Client benutzt. Der Schlüssel gehört auf
+einen **Server**.
+
+```ts
+import { createRechnungApi, istRechnungFehler } from '@kreiseck/kasseneck-api/rechnung';
+
+const rechnungen = createRechnungApi({ apiKey: process.env.KASSENECK_API_KEY! });
+
+// 1. Kunde einmal anlegen — externalId ist die eigene Kundennummer.
+let kunde;
+try {
+  kunde = await rechnungen.createCustomer({
+    type: 'company', name: 'Café Muster GmbH', country: 'AT',
+    street: 'Hauptplatz', houseNumber: '3', zip: '1010', city: 'Wien',
+    externalId: 'shop-4711',
+  });
+} catch (fehler) {
+  if (!istRechnungFehler(fehler, 'customer_exists')) throw fehler;
+  kunde = await rechnungen.getCustomer({ externalId: 'shop-4711' });
+}
+
+// 2. Ausstellen. Beträge in ganzen Cent; das Rechnungsdatum setzt der Server.
+const { invoice, replayed } = await rechnungen.issueInvoice({
+  idempotencyKey: `bestellung-${bestellnummer}`,   // gleiche Bestellung = gleiche Rechnung
+  customerId: kunde.id,
+  taxScheme: 'normal',
+  priceMode: 'net',
+  serviceStart: '2026-09-14',
+  items: [{ description: 'Beratung', quantity: 2, unit: 'Std', unitPriceCents: 5000, vatRate: 20 }],
+});
+// invoice.number, invoice.totals.grossCents (12000), invoice.statusUrl
+
+// 3. Dateien holen.
+const pdf = await rechnungen.getInvoicePdf(invoice.id);      // Uint8Array, mit Factur-X
+const xml = await rechnungen.getInvoiceXml(invoice.id, 'ubl'); // Peppol-UBL als Text
+
+// 4. Korrigieren — nur per Gutschrift.
+await rechnungen.createCreditNote({
+  idempotencyKey: `nachlass-${bestellnummer}`,
+  invoiceId: invoice.id,
+  reason: 'price_reduction',
+  items: [{ description: 'Nachlass Beratung', quantity: 1, unitPriceCents: 2000, vatRate: 20 }],
+});
+```
+
+**Vor dem ersten Ausstellen die Einrichtung abfragen.** Die Rechnungs-API muss
+für das Konto von Kasseneck freigegeben sein (live), und Firmenname, Anschrift,
+UID, Bankverbindung und Nummernformat müssen stehen — sonst antwortet
+`issueInvoice` mit `invoice_api_not_enabled` bzw. `invoice_setup_incomplete`:
+
+```ts
+const status = await rechnungen.getInvoiceSetupStatus();
+if (!status.ready) console.warn(status.missing.map((m) => m.message).join('\n'));
+```
+
+**Nach einem Zeitlimit mit demselben `idempotencyKey` wiederholen**, nie mit
+einem neuen: dann kommt die schon ausgestellte Rechnung zurück
+(`replayed: true`). Derselbe Schlüssel mit anderen Daten ergibt
+`idempotency_conflict`.
+
+Formfehler kommen als `validation` mit Feldpfaden (`rechnungFeldFehler(fehler)`
+→ `[{ field: 'items[0].vatRate', message }]`). Der Vertrag selbst liegt als
+Daten im Paket (`RECHNUNG_ANFRAGEN`) und als JSON Schema unter
+`@kreiseck/kasseneck-api/fixtures/rechnung-api.schema.json`; das Backend prüft
+gegen genau diese Datei.
+
 ## Unterpfade
 
 | Unterpfad | Inhalt |
@@ -437,6 +511,7 @@ app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) =>
 | `…/register` | Anmeldung der Browser-Kasse: Gerät koppeln und entkoppeln, Benutzer auflisten, per PIN anmelden, Sitzung erneuern und beenden. |
 | `…/kasse` | Kachel-Kasse: Kassen-Einstellungen (betriebsweit / je Gerät), Artikelgruppen und Artikel für Kacheln, Rabattverteilung je Steuersatz, Reichweiten der Kassen-Rechte |
 | `…/partner` | Partner-API: Betriebe anlegen, FinanzOnline-Link, Signatur, Kassen, Zugangsdaten, Webhooks samt Signaturprüfung. **Gehört auf einen Server.** |
+| `…/rechnung` | Rechnungs-API: Kunden anlegen und suchen, Rechnungen festgeschrieben ausstellen, Gutschrift und Storno, PDF und E-Rechnung-XML; der Vertrag als Daten. **Gehört auf einen Server.** |
 | `…/react` | Dünner React-Adapter, der ein Beleg-Layout zeichnet. Braucht React. |
 | `…/fixtures/*` | Golden-Belege (JSON): Eingaben `belege/<name>.json`, zugesagte Zeilenausgabe `erwartet/<name>.lines.json`, `manifest.json` mit Prüfsummen — dieselben Dateien prüfen Backend, Browser-Kasse und Flutter-Paket. |
 

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

@@ -13,7 +13,7 @@
  * umhuellt, muss ihn weiterhin absetzen koennen.
  */
 import type { TransportBodyFields } from './transport.js';
-export declare const AUFRUFE: readonly ["activateCashregister", "cancelReceipt", "createCustomerCashregister", "createPartnerCustomer", "checkPartnerCustomerEmail", "createPartnerWebhook", "createPaymentLinkStripe", "createPrintJob", "createReceipt", "deletePartnerWebhook", "downloadDailyReport", "downloadReport", "endRegisterSession", "financeWebService", "generateFullReceiptId", "getCustomerCredentials", "getCustomerSignatureStatus", "getFirstReceiptDate", "getKasseSettings", "getPartnerCustomer", "getPartnerInfo", "getPrintJob", "getReceipt", "hobexPayApi", "hobexRefundApi", "listCustomerCashregisters", "listMyArticleGroups", "listMyArticles", "listMyCashregisters", "listMyPrinters", "listMyReceipts", "listMyTipRecipients", "listPartnerCustomers", "listPartnerWebhookDeliveries", "listPartnerWebhooks", "listRegisterUsersForDevice", "listRegisterSessionsForDevice", "pairRegisterDevice", "registerPinLogin", "registerUserLogin", "renewRegisterSession", "requestCustomerSignature", "sendPartnerCustomerFonLink", "sendPartnerWebhookTest", "sendReceiptEmail", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "unpairRegisterDevice", "rotatePartnerWebhookSecret", "updatePartnerWebhook"];
+export declare const AUFRUFE: readonly ["activateCashregister", "cancelInvoice", "cancelReceipt", "createCreditNote", "createCustomer", "createCustomerCashregister", "createPartnerCustomer", "checkPartnerCustomerEmail", "createPartnerWebhook", "createPaymentLinkStripe", "createPrintJob", "createReceipt", "deletePartnerWebhook", "downloadDailyReport", "downloadReport", "endRegisterSession", "financeWebService", "generateFullReceiptId", "getCustomer", "getCustomerCredentials", "getCustomerSignatureStatus", "getFirstReceiptDate", "getInvoice", "getInvoicePdf", "getInvoiceSetupStatus", "getInvoiceXml", "getKasseSettings", "getPartnerCustomer", "getPartnerInfo", "getPrintJob", "getReceipt", "hobexPayApi", "hobexRefundApi", "issueInvoice", "listCustomerCashregisters", "listInvoices", "listMyArticleGroups", "listMyArticles", "listMyCashregisters", "listMyPrinters", "listMyReceipts", "listMyTipRecipients", "listPartnerCustomers", "listPartnerWebhookDeliveries", "listPartnerWebhooks", "listRegisterUsersForDevice", "listRegisterSessionsForDevice", "pairRegisterDevice", "registerPinLogin", "registerUserLogin", "renewRegisterSession", "requestCustomerSignature", "searchCustomers", "sendPartnerCustomerFonLink", "sendPartnerWebhookTest", "sendReceiptEmail", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "unpairRegisterDevice", "rotatePartnerWebhookSecret", "updateCustomer", "updatePartnerWebhook"];
 export type Aufruf = typeof AUFRUFE[number];
 /** Wie [KasseneckTransport], nur mit bekanntem Aufrufnamen. Nicht exportiert nach aussen. */
 export type InternerTransport = <T = unknown>(functionName: Aufruf, params?: Record<string, unknown>, extraBodyFields?: TransportBodyFields, secretParams?: readonly string[]) => Promise<T>;

package/dist/cjs/client/aufrufe.js

@@ -3,7 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AUFRUFE = void 0;
 exports.AUFRUFE = [
     'activateCashregister',
+    'cancelInvoice',
     'cancelReceipt',
+    'createCreditNote',
+    'createCustomer',
     'createCustomerCashregister',
     'createPartnerCustomer',
     'checkPartnerCustomerEmail',
@@ -17,9 +20,14 @@ exports.AUFRUFE = [
     'endRegisterSession',
     'financeWebService',
     'generateFullReceiptId',
+    'getCustomer',
     'getCustomerCredentials',
     'getCustomerSignatureStatus',
     'getFirstReceiptDate',
+    'getInvoice',
+    'getInvoicePdf',
+    'getInvoiceSetupStatus',
+    'getInvoiceXml',
     'getKasseSettings',
     'getPartnerCustomer',
     'getPartnerInfo',
@@ -27,7 +35,9 @@ exports.AUFRUFE = [
     'getReceipt',
     'hobexPayApi',
     'hobexRefundApi',
+    'issueInvoice',
     'listCustomerCashregisters',
+    'listInvoices',
     'listMyArticleGroups',
     'listMyArticles',
     'listMyCashregisters',
@@ -44,6 +54,7 @@ exports.AUFRUFE = [
     'registerUserLogin',
     'renewRegisterSession',
     'requestCustomerSignature',
+    'searchCustomers',
     'sendPartnerCustomerFonLink',
     'sendPartnerWebhookTest',
     'sendReceiptEmail',
@@ -52,5 +63,6 @@ exports.AUFRUFE = [
     'stripeCaptureIntent',
     'unpairRegisterDevice',
     'rotatePartnerWebhookSecret',
+    'updateCustomer',
     'updatePartnerWebhook',
 ];

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

@@ -0,0 +1,45 @@
+/**
+ * Fassade ueber den Aufrufen der Rechnungs-API: Schluessel einmal binden, dann rufen.
+ *
+ * Wie [createPartnerApi] bewusst **keine** Klasse — die Aufrufe sind freie
+ * Funktionen (endpunkte.ts) und bleiben einzeln importierbar.
+ */
+import { type FetchLike } from '../client/transport.js';
+import type { EInvoiceFormat } from './vertrag.js';
+import type { CancelInvoiceRequest, CancelResult, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, InvoiceDetail, InvoiceListQuery, InvoicePage, InvoiceSetupStatus, IssueInvoiceRequest, IssueResult } from './typen.js';
+export interface RechnungApiOptions {
+    /** `api_key` des Kontos (`kr_live_…` / `kr_test_…`). Gehoert auf einen Server. */
+    apiKey: string;
+    /** Abweichende Basis-URL; Vorgabe `https://api.kasseneck.at/v1`. */
+    baseUrl?: string;
+    /** Zeitlimit je Aufruf in Millisekunden. */
+    timeoutMs?: number;
+    /** Eigene `fetch`-Umsetzung (Tests, Proxys). */
+    fetch?: FetchLike;
+}
+export interface RechnungApi {
+    createCustomer(customer: CustomerInput, optionen?: {
+        idempotencyKey?: string;
+    }): Promise<Customer>;
+    getCustomer(kennung: {
+        customerId: string;
+    } | {
+        externalId: string;
+    }): Promise<Customer>;
+    updateCustomer(customerId: string, patch: Partial<CustomerInput>): Promise<Customer>;
+    searchCustomers(suche: CustomerSearch): Promise<CustomerPage>;
+    issueInvoice(anfrage: IssueInvoiceRequest): Promise<IssueResult>;
+    cancelInvoice(anfrage: CancelInvoiceRequest): Promise<CancelResult>;
+    createCreditNote(anfrage: CreditNoteRequest): Promise<CreditNoteResult>;
+    getInvoice(kennung: {
+        invoiceId: string;
+    } | {
+        number: string;
+    }): Promise<InvoiceDetail>;
+    listInvoices(abfrage?: InvoiceListQuery): Promise<InvoicePage>;
+    getInvoicePdf(invoiceId: string): Promise<Uint8Array>;
+    getInvoiceXml(invoiceId: string, format?: EInvoiceFormat): Promise<string>;
+    /** Darf dieses Konto ausstellen, und was fehlt noch? Laeuft auch ohne Freigabe. */
+    getInvoiceSetupStatus(): Promise<InvoiceSetupStatus>;
+}
+export declare function createRechnungApi(optionen: RechnungApiOptions): RechnungApi;

package/dist/cjs/rechnung/api.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Fassade ueber den Aufrufen der Rechnungs-API: Schluessel einmal binden, dann rufen.
+ *
+ * Wie [createPartnerApi] bewusst **keine** Klasse — die Aufrufe sind freie
+ * Funktionen (endpunkte.ts) und bleiben einzeln importierbar.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRechnungApi = createRechnungApi;
+const transport_js_1 = require("../client/transport.js");
+const auth_js_1 = require("./auth.js");
+const endpunkte_js_1 = require("./endpunkte.js");
+function createRechnungApi(optionen) {
+    const transportOptionen = {
+        auth: (0, auth_js_1.rechnungKeyAuth)({ apiKey: optionen.apiKey }),
+        baseUrl: optionen.baseUrl,
+        timeoutMs: optionen.timeoutMs,
+        fetch: optionen.fetch,
+    };
+    const rufen = (0, transport_js_1.createTransport)(transportOptionen);
+    const rufenBinaer = (0, transport_js_1.createBinaryTransport)(transportOptionen);
+    return {
+        createCustomer: (customer, o) => (0, endpunkte_js_1.createCustomer)(rufen, customer, o),
+        getCustomer: (kennung) => (0, endpunkte_js_1.getCustomer)(rufen, kennung),
+        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),
+        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),
+        listInvoices: (abfrage) => (0, endpunkte_js_1.listInvoices)(rufen, abfrage),
+        getInvoicePdf: (id) => (0, endpunkte_js_1.getInvoicePdf)(rufenBinaer, id),
+        getInvoiceXml: (id, format) => (0, endpunkte_js_1.getInvoiceXml)(rufen, id, format),
+        getInvoiceSetupStatus: () => (0, endpunkte_js_1.getInvoiceSetupStatus)(rufen),
+    };
+}

package/dist/cjs/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/cjs/rechnung/auth.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rechnungKeyAuth = rechnungKeyAuth;
+const errors_js_1 = require("../client/errors.js");
+function rechnungKeyAuth(options) {
+    const schluessel = typeof options?.apiKey === 'string' ? options.apiKey.trim() : '';
+    if (!schluessel) {
+        throw new errors_js_1.KasseneckAuthError('rechnungKeyAuth: apiKey fehlt');
+    }
+    if (/^pk_(live|test)_/i.test(schluessel)) {
+        throw new errors_js_1.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 errors_js_1.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/cjs/rechnung/endpunkte.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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, InvoiceSetupStatus, 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>;
+/**
+ * Darf dieses Konto ueber die API ausstellen, und was fehlt noch? Laeuft auch
+ * ohne Freigabe und vor der Live-Freischaltung — genau dann braucht man die
+ * Antwort. Vor dem ersten `issueInvoice` aufrufen und `missing` anzeigen.
+ */
+export declare function getInvoiceSetupStatus(rufen: InternerTransport): Promise<InvoiceSetupStatus>;
+/** 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/cjs/rechnung/endpunkte.js

@@ -0,0 +1,147 @@
+"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.getInvoiceSetupStatus = getInvoiceSetupStatus;
+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 };
+}
+// ---- Freigabe und Einrichtung ---------------------------------------------------
+/**
+ * Darf dieses Konto ueber die API ausstellen, und was fehlt noch? Laeuft auch
+ * ohne Freigabe und vor der Live-Freischaltung — genau dann braucht man die
+ * Antwort. Vor dem ersten `issueInvoice` aufrufen und `missing` anzeigen.
+ */
+async function getInvoiceSetupStatus(rufen) {
+    const daten = objekt(await rufen('getInvoiceSetupStatus', {}));
+    if (typeof daten['ready'] !== 'boolean' || !Array.isArray(daten['missing'])) {
+        throw new errors_js_1.KasseneckValidationError('getInvoiceSetupStatus', 'Antwort ohne ready/missing', 'response');
+    }
+    return {
+        ready: daten['ready'],
+        environment: daten['environment'] === 'test' ? 'test' : 'live',
+        missing: daten['missing'],
+    };
+}
+// ---- 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, getInvoiceSetupStatus, 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, InvoiceSetupGap, InvoiceSetupStatus, 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, 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 InvoiceSetupRequirement, type Format, type Feld, } from './vertrag.js';