@kreiseck/kasseneck-api 0.6.46 → 0.7.0

package/dist/esm/partner/betrieb.js

@@ -0,0 +1,132 @@
+/**
+ * Was ein Betrieb ueber die Schnittstelle mitbringen darf — Feld fuer Feld.
+ *
+ * **Unbekannte Felder werden abgewiesen, nicht stillschweigend verworfen.**
+ * Vorher verschwand ein `iban` oder ein vertippter Feldname spurlos: der
+ * Partner glaubte, er habe die Steuernummer geschickt, und Kasseneck hatte
+ * nichts. Ein Feld, das man schickt und das nichts bewirkt, ist der teuerste
+ * Fehler in einer Schnittstelle, weil ihn niemand bemerkt.
+ *
+ * Seitdem antwortet `createPartnerCustomer` mit `validation` und dem genauen
+ * Feldpfad — verschachtelt und je Kontakt: `address.land`,
+ * `tax_details.ustid`, `contacts.1.abteilung`.
+ *
+ * Zwei Dinge halten diese Seite dagegen:
+ *
+ * - der Typ [Betrieb] (typen.ts) hat genau diese Felder, und TypeScript meldet
+ *   ein ueberzaehliges schon beim Tippen;
+ * - [unbekannteBetriebsfelder] beantwortet dieselbe Frage zur Laufzeit — fuer
+ *   Daten, die aus einer Datenbank oder einem Formular kommen und deshalb nie
+ *   durch die Typpruefung gelaufen sind.
+ *
+ * **Die Wahrheit bleibt der Server.** Dieser Client weist nichts von sich aus
+ * ab: eine spaetere Backend-Fassung darf ein Feld ergaenzen, ohne dass ein
+ * aelterer Client es blockiert. [unbekannteBetriebsfelder] ist die Vorschau,
+ * nicht das Tor.
+ *
+ * Quelle der Liste: `partner-core.BETRIEB_FELDER` im Backend.
+ */
+/**
+ * Jedes erlaubte Feld als Pfad. `[]` markiert eine Liste — im Fehlerpfad des
+ * Servers steht dort der Index (`contacts.0.name`).
+ *
+ * Bewusst flach und nicht verschachtelt: so ist es EINE Liste, die der
+ * Zwilling Zeile fuer Zeile nachhalten kann. Das Schema fuer die Pruefung
+ * entsteht daraus (siehe unten) und nicht daneben.
+ */
+export const BETRIEB_FELDER = [
+    'companyName',
+    'legalForm',
+    'state',
+    'industry',
+    'companyRegister',
+    'court',
+    'web',
+    'phone',
+    'email',
+    'billingEmail',
+    'address.street',
+    'address.number',
+    'address.zip',
+    'address.city',
+    'taxDetails.taxNumber',
+    'taxDetails.vatId',
+    'taxDetails.gln',
+    'taxDetails.smallBusiness',
+    'contacts[].name',
+    'contacts[].email',
+    'contacts[].phone',
+    'contacts[].roles',
+    'taxAdvisor.name',
+    'taxAdvisor.email',
+    'taxAdvisor.phone',
+    'taxAdvisor.mayContact',
+];
+/** Das Schema entsteht aus [BETRIEB_FELDER] — eine Quelle, keine zweite Liste. */
+const SCHEMA = (() => {
+    const wurzel = {};
+    for (const pfad of BETRIEB_FELDER) {
+        const teile = pfad.split('.');
+        let stand = wurzel;
+        teile.forEach((rohes, i) => {
+            const liste = rohes.endsWith('[]');
+            const name = liste ? rohes.slice(0, -2) : rohes;
+            if (i === teile.length - 1) {
+                stand[name] = true;
+                return;
+            }
+            if (liste) {
+                const vorhanden = stand[name];
+                const eintrag = Array.isArray(vorhanden) ? vorhanden[0] : {};
+                stand[name] = [eintrag];
+                stand = eintrag;
+                return;
+            }
+            const vorhanden = stand[name];
+            const unter = vorhanden !== undefined && vorhanden !== true && !Array.isArray(vorhanden) ? vorhanden : {};
+            stand[name] = unter;
+            stand = unter;
+        });
+    }
+    return wurzel;
+})();
+function istObjekt(wert) {
+    return wert !== null && typeof wert === 'object' && !Array.isArray(wert);
+}
+function sammle(eingabe, schema, pfad) {
+    if (!istObjekt(eingabe))
+        return [];
+    const raus = [];
+    for (const [name, wert] of Object.entries(eingabe)) {
+        const voll = pfad ? `${pfad}.${name}` : name;
+        const erlaubt = schema[name];
+        if (erlaubt === undefined) {
+            raus.push(voll);
+            continue;
+        }
+        if (erlaubt === true)
+            continue;
+        if (Array.isArray(erlaubt)) {
+            // Ein falscher Typ ist kein unbekanntes Feld — den meldet der Server als
+            // eigenen Formfehler auf demselben Pfad.
+            if (!Array.isArray(wert))
+                continue;
+            wert.forEach((eintrag, idx) => raus.push(...sammle(eintrag, erlaubt[0], `${voll}.${idx}`)));
+            continue;
+        }
+        raus.push(...sammle(wert, erlaubt, voll));
+    }
+    return raus;
+}
+/**
+ * Die Feldpfade eines Betriebs, die [BETRIEB_FELDER] nicht kennt — dieselbe
+ * Ableitung wie im Backend, also dieselben Pfade wie in `data.errors[].field`.
+ * Leer heisst: aus dieser Sicht ist nichts ueberzaehlig.
+ *
+ * Sagt **nichts** ueber die Werte: Steuernummer, UID, PLZ und Gericht prueft
+ * das Backend mit `@kreiseck/validator`. Diese Funktion beantwortet nur die
+ * Frage „schicke ich etwas, das dort niemand erwartet?".
+ */
+export function unbekannteBetriebsfelder(business) {
+    return sammle(business, SCHEMA, '');
+}

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

@@ -0,0 +1,142 @@
+/**
+ * Die Aufrufe der Partner-API — Betriebe, Signatur, Kassen.
+ *
+ * Jede Funktion nimmt den Transport als ersten Parameter und ist einzeln
+ * importierbar; die Fassade [createPartnerApi] bindet ihn nur einmal.
+ *
+ * **Was hier geprueft wird und was nicht.** Vor dem Senden prueft dieser Client
+ * nur, was er ohne den Server wissen kann: dass eine Kennung ueberhaupt da ist,
+ * dass eine Liste nicht leer ist, dass eine Zahl im erlaubten Bereich liegt.
+ * Die fachliche Pruefung der Betriebsdaten (Steuernummer samt Pruefziffer, UID,
+ * PLZ, Gericht) macht das Backend mit `@kreiseck/validator` — sie hier zu
+ * wiederholen hiesse, zwei Wahrheiten zu haben, von denen eine veraltet.
+ * Ein Formfehler kommt als `KasseneckApiError` mit `code:"validation"` zurueck;
+ * `partnerFeldFehler(fehler)` macht `data.errors[]` daraus. **Es entsteht dabei
+ * nichts** — der Aufruf ist folgenlos wiederholbar.
+ *
+ * Nach dem Senden wird nichts hart gecastet: fehlt ein zugesagtes Feld, wirft
+ * der Aufruf `KasseneckValidationError` mit `scope:'response'` statt spaeter
+ * einen `TypeError` an unpassender Stelle.
+ */
+import type { InternerTransport } from '../client/aufrufe.js';
+import type { ActivateCashregisterResult, CreateCashregisterOptions, CreateCashregisterResult, CreateCustomerOptions, CreateCustomerResult, CustomerCredentials, FonLinkResult, KassenListe, Kunde, KundenListe, ListCustomersOptions, PartnerInfo, RequestSignatureResult, SignaturStand } from './typen.js';
+/**
+ * Wer bin ich, in welcher Umgebung, mit welchen Rechten — und welche Apps
+ * gehoeren mir. `apps[].id` ist die `appId` fuer [createPartnerCustomer].
+ *
+ * Der guenstigste Selbsttest beim Hochfahren: er beweist Schluessel, Umgebung
+ * und Rechte in einem Aufruf.
+ */
+export declare function getPartnerInfo(rufen: InternerTransport): Promise<PartnerInfo>;
+/**
+ * Legt einen Betrieb an.
+ *
+ * **Ohne Panel-Zugang**, solange nicht `access:{invite:true}` dabeisteht:
+ * viele Betriebe arbeiten ausschliesslich in der App des Partners. Fuer die
+ * Einladung braucht das Partner-Konto ausserdem
+ * `partner.canCreateAccess`.
+ *
+ * **`env` waehlt die Umgebung.** Ohne Angabe entscheidet der Schluessel; ein
+ * Live-Schluessel darf mit `env:"test"` einen Testbetrieb anlegen, ein
+ * Test-Schluessel niemals einen Live-Betrieb (`live_not_allowed`).
+ *
+ * **`idempotencyKey` benutzen.** Ein verlorener Antwortweg ist kein
+ * Sonderfall, und ohne Schluessel legt der zweite Versuch einen zweiten Betrieb
+ * an. Mit Schluessel kommt die gespeicherte Antwort zurueck (`replayed:true`)
+ * — auch dann, wenn der Rumpf inzwischen abweicht. Die eigene Kundennummer ist
+ * der natuerliche Wert dafuer.
+ */
+export declare function createPartnerCustomer(rufen: InternerTransport, optionen: CreateCustomerOptions): Promise<CreateCustomerResult>;
+/** Betriebe dieses Partners, seitenweise. `cursor` aus der Antwort setzt fort. */
+export declare function listPartnerCustomers(rufen: InternerTransport, optionen?: ListCustomersOptions): Promise<KundenListe>;
+/** Ein Betrieb mit allem, was der Partner ueber ihn sehen darf — nie Geheimnisse. */
+export declare function getPartnerCustomer(rufen: InternerTransport, customerId: string): Promise<Kunde>;
+/**
+ * Schickt dem Betrieb den Einrichtungs-Link fuer seinen FinanzOnline-Zugang.
+ * Ohne diesen Zugang gibt es live keine Signatureinheit (`fon_missing`).
+ *
+ * Die Antwort nennt den Empfaenger **maskiert** — die Adresse gibt das Backend
+ * nie im Klartext aus.
+ */
+/**
+ * Ist diese E-Mail-Adresse noch als Kasseneck-Zugang frei?
+ *
+ * Nur noetig, wenn der Betrieb einen eigenen Zugang zum Kundenpanel bekommen
+ * soll (`access.invite: true`) — dann wird die Adresse sein Login und darf
+ * noch keines sein. Ohne Einladung ist eine belegte Adresse kein Hindernis.
+ *
+ * Der Sinn ist der Zeitpunkt: ohne diese Frage faellt `email_taken` erst nach
+ * einem ganzen ausgefuellten Formular auf. Die Antwort sagt NUR ja oder nein —
+ * nie, wem die Adresse gehoert.
+ */
+export declare function checkPartnerCustomerEmail(rufen: InternerTransport, email: string): Promise<boolean>;
+export declare function sendPartnerCustomerFonLink(rufen: InternerTransport, customerId: string): Promise<FonLinkResult>;
+/**
+ * Beantragt die Signatureinheit. Kasseneck laesst die Karte beim
+ * Vertrauensdiensteanbieter **auf diesen Betrieb** ausstellen und meldet sie
+ * bei FinanzOnline an; einen Vorrat fertiger Karten gibt es nicht.
+ *
+ * Der Antrag erzeugt sofort ein Signatur-OBJEKT: `antrag.requestId` ist
+ * zugleich die `signaturId`, auf die sich eine Kasse beruft — auch solange
+ * noch keine Karte zugewiesen ist.
+ *
+ * **Je Betrieb laeuft nur ein Antrag.** Ein zweiter Aufruf liefert den
+ * laufenden zurueck (`replayed:true`) und ist damit folgenlos wiederholbar.
+ * Eine WEITERE Signatur (Ersatzkarte, zweiter Standort) entsteht nur mit
+ * `additional:true` — hoechstens zehn je Betrieb (`signature_limit`). Der
+ * Abschluss kommt als Ereignis `signature.ready`, nicht als Antwort auf diesen
+ * Aufruf.
+ */
+export declare function requestCustomerSignature(rufen: InternerTransport, customerId: string, optionen?: {
+    art?: string;
+    additional?: boolean;
+}): Promise<RequestSignatureResult>;
+/** Stand der Signatur eines Betriebs samt aller Antraege und des FON-Zugangs. */
+export declare function getCustomerSignatureStatus(rufen: InternerTransport, customerId: string): Promise<SignaturStand>;
+/**
+ * Legt eine Kasse an.
+ *
+ * **Jede Kasse bezieht sich auf eine Signatur.** Ohne eine einzige — auch eine
+ * noch laufende zaehlt — entsteht keine (`signature_missing`); bei mehreren
+ * muss `signaturId` dastehen (`signature_ambiguous`).
+ *
+ * **Darf vor der fertigen Signatur aufgerufen werden:** die Kasse bleibt dann
+ * auf `entwurf` und geht von selbst live, sobald IHRE Signatur bereit ist
+ * (`automatic:true`, Vorgabe). `inbetriebnahme.reason` sagt, warum gerade
+ * nichts lief: `signature_not_ready` oder `automatik_aus`.
+ *
+ * Hoechstens 20 Kassen je Betrieb (`cashregister_limit`); ohne gebuchtes Modul
+ * `module_inactive`.
+ */
+export declare function createCustomerCashregister(rufen: InternerTransport, optionen: CreateCashregisterOptions): Promise<CreateCashregisterResult>;
+/**
+ * Nimmt eine Kasse in Betrieb — von Hand, wenn `automatic:false` gilt oder
+ * ein Lauf abgebrochen ist.
+ *
+ * **Jeder Schritt der Kette ist idempotent**, der Startbeleg entsteht nach
+ * RKSV genau einmal und ein vorhandener wird erkannt. Ein Wiederholungsaufruf
+ * setzt deshalb an der Bruchstelle an und macht nichts doppelt; eine bereits
+ * laufende Kasse antwortet mit `unchanged:true`. Das ist der eine
+ * veraendernde Aufruf dieses Clients, der ohne Idempotenzschluessel gefahrlos
+ * wiederholbar ist — weil der Server ihn so gebaut hat.
+ */
+export declare function activateCashregister(rufen: InternerTransport, customerId: string, cashregisterId: string): Promise<ActivateCashregisterResult>;
+/** Die Kassen eines Betriebs samt Stand der Inbetriebnahme — **nie** Token. */
+export declare function listCustomerCashregisters(rufen: InternerTransport, customerId: string): Promise<KassenListe>;
+/**
+ * Holt die **Geheimnisse des Betriebs**: seinen `api_key` und die Token seiner
+ * Kassen. Damit signiert eine App in seinem Namen Belege — und ein Beleg ist
+ * nach RKSV nicht zuruecknehmbar.
+ *
+ * Braucht den Scope `credentials:read`, der **nicht** zum Standardsatz gehoert
+ * und keinem bestehenden Schluessel nachtraeglich hinzugefuegt wird; dafuer
+ * wird ein eigener Schluessel angelegt. Jeder Abruf wird mitgeschrieben
+ * (Partner, Schluessel, Zeitpunkt) und ist fuer den Betrieb sichtbar.
+ *
+ * **Nur verschluesselt speichern. Nie protokollieren, nie in eine Mail, nie in
+ * einen Fehlerbericht.** Die Werte kommen darum als [KasseneckSecret] und
+ * nicht als `string` zurueck: `console.log`, `JSON.stringify` und jede
+ * Zeichenketten-Umwandlung zeigen eine Maske, heraus kommt man nur ueber
+ * `.reveal()`.
+ */
+export declare function getCustomerCredentials(rufen: InternerTransport, customerId: string): Promise<CustomerCredentials>;