@app-zentrale/sdk

Client-SDK der App-Zentrale – einer privat betriebenen, zentralen Anwendungsverwaltung. Das Paket bindet eine Anwendung an genau diese Zentrale an: Feedback-Widget, Fehlererfassung, Wartungsanzeige und serverseitige Schreibsperre während eines Wartungsfensters.

Kein Allgemeingut. Das Paket liegt auf der öffentlichen Registry, weil der Docker-Build der einbindenden Anwendungen sonst ein Zugangsgeheimnis bräuchte – nicht als Angebot an die Allgemeinheit. Es ist ohne die zugehörige Zentrale nutzlos, die Lizenz ist UNLICENSED, und es gibt weder Support noch eine Zusage über die Stabilität der API. Solange die Version bei 0.x steht, kann jede Minor-Version brechen.

Installation

npm install @app-zentrale/sdk

Node ≥ 20. react und express sind optionale Peer-Dependencies – eine reine Browser-Einbindung braucht keine davon.

Einstiegspunkte

| Import | Inhalt | |---|---| | @app-zentrale/sdk | initAppZentrale, setAuthenticated, captureWarning, getMaintenance, onMaintenanceChange, getInstanceConfig, onInstanceConfigChange, AppZentraleConfigError, OPTION_DEFAULTS | | @app-zentrale/sdk/node | zentraleMaintenanceGuard, zentraleErrorHandler (beide Express), captureWarning, getInstanceConfig, onInstanceConfigChange, MAINTENANCE_ERROR_CODE | | @app-zentrale/sdk/react | useMaintenance, useReadOnly, MaintenanceBanner, ZentraleErrorBoundary |

import { initAppZentrale } from '@app-zentrale/sdk';

initAppZentrale({
  endpoint: 'https://zentrale.example.org',
  key: import.meta.env.VITE_APP_ZENTRALE_KEY,
  version: __APP_VERSION__, // einziges Pflichtfeld
});

initAppZentrale hängt im Browser zugleich die automatische Fehlererfassung ein: error, unhandledrejection und – solange breadcrumbs > 0 – die Routenkrumen. Renderfehler fängt zusätzlich ZentraleErrorBoundary aus @app-zentrale/sdk/react, serverseitige Fehler zentraleErrorHandler aus @app-zentrale/sdk/node.

app.use(zentraleErrorHandler()); // ganz am Ende der Kette

Der Express-Handler meldet 4xx nicht (erwartetes Verhalten) und reicht jeden Fehler unverändert an die eigene Fehlerbehandlung der Anwendung weiter. Breadcrumbs enthalten ausschließlich Routen und Meldungstexte des SDK – keine Klicks, keine Formularinhalte, keine Adressparameter.

Beim bloßen Import passiert nichts – kein globales Objekt, kein Handler, kein Zeitgeber. Erst initAppZentrale fasst etwas an.

Zur Laufzeit gilt „fail open". Das SDK wirft nie in die einbindende Anwendung hinein: Timeouts, Circuit Breaker, Offline-Queue. Fällt die Zentrale aus, merkt die Anwendung nichts – auch ein bereits bekannter Wartungs-Lesemodus läuft nach drei ausbleibenden Statusabfragen von selbst ab.

Module aus der Zentrale (ab 0.5.0)

Die Zentrale kann je Instanz festlegen, welche Module der Anwendung freigeschaltet sind. Das SDK überbringt diesen Stand mit der Statusabfrage:

import { getInstanceConfig, onInstanceConfigChange } from '@app-zentrale/sdk/node';

getInstanceConfig();
// null                          – noch keine Antwort der Zentrale
// { module: null }              – die Zentrale verwaltet die Module nicht: eigene Konfiguration nutzen
// { module: [] }                – nur der Kern
// { module: ['reinigung', …] }  – genau diese Module, sortiert

const abmelden = onInstanceConfigChange((config) => {
  // feuert nur bei einer echten Änderung, auch beim ersten bekannten Stand
});

• null ist nicht { module: [] }. Das eine heißt „noch nichts bekannt“, das andere „nur der Kern“. Wer beides gleich behandelt, nimmt der Anwendung beim Start alle Module.
• Ein kaputtes Format ändert nichts: Liefert die Zentrale etwas anderes als null oder eine Liste von Zeichenketten, gilt der letzte bekannte Stand weiter.
• Den letzten bekannten Stand hält die Anwendung selbst fest (etwa in ihrer Datenbank): Nach einem Neustart ohne erreichbare Zentrale liefert getInstanceConfig() wieder null.
• Takt: Im Browser alle 60 Sekunden. Im Node-Einstieg fragt das SDK nur beim Start ab und danach im Takt von zentraleMaintenanceGuard (aktualisierenSekunden, Standard 60). Ohne den Guard erfährt ein Node-Prozess eine Änderung erst beim nächsten Start.

Die ausführliche Anleitung zum Einbinden liegt im Repository der Zentrale (docs/einbindung-leitfaden.md) und ist nicht Teil dieses Pakets.