omsorg/omsorgapp/api-client-ts/ANLEITUNG.md

Anleitung — omsorgcore-client-ts

Generierter TypeScript-Client für die omsorgCore-API, erzeugt mit openapi-generator-cli aus der Swagger/OpenAPI-JSON des Backends. Kein eigenständiges Extra mehr: Alle handgeschriebenen Wrapper unter src/api/*Api.js (employeesApi.js, facilitiesApi.js, usersApi.js, ...) importieren ihre *Api-Klasse aus diesem Paket (import ... from "omsorgcore-client-ts") und reichen dessen typisierte Requests/Responses direkt durch — dieser Client ist damit Teil des echten Datenpfads von omsorgapp gegen omsorgCore, nicht nur eine zusätzliche Bibliothek für Skripte/Typprüfung.

README.md in diesem Ordner wird bei jeder Generierung automatisch neu geschrieben (Standard-Output von openapi-generator, dokumentiert die generierten API-Methoden) — diese Datei hier nicht, sie bleibt stabil.

Voraussetzungen

• Node.js + npx (bereits für den Rest von omsorgapp vorhanden)
• Java (wird von openapi-generator-cli intern benötigt, kein separates Setup nötig, sofern java im PATH ist)
• omsorgCore muss lokal im Development-Modus laufen, da Swagger nur dort aktiv ist (siehe omsorgCore/CLAUDE.md, Abschnitt "Session-Killswitch" o.ä. — Swagger ist an app.Environment.IsDevelopment() gebunden)

API lokal starten (für die Generierung)

cd omsorgCore
ASPNETCORE_ENVIRONMENT=Development dotnet run --project src/OmsorgCore.Api
# → Swagger-JSON unter http://localhost:5245/swagger/v1/swagger.json

Client neu generieren

cd omsorgapp/api-client-ts
npm run generate
# entspricht: ./generate.sh

Nimmt die Backend-URL aus OMSORG_CORE_URL (Default http://localhost:5245, dieselbe Konvention wie src/api/config.js). Überschreibt src/, README.md, package.json, .gitignore, tsconfig*.json mit dem aktuellen generierten Stand — danach git diff prüfen, bevor committet wird (eigene Anpassungen an package.json, z. B. das generate-Script, ggf. erneut eintragen, siehe unten).

Bauen

npm install
npm run build

Erzeugt dist/ (CommonJS + ESM, siehe tsconfig.json/tsconfig.esm.json). dist/ und node_modules/ sind .gitignore't — nur der generierte Quellcode unter src/ wird eingecheckt.

Verwendung (Beispiel)

import { Configuration, AuthApi } from "./dist"; // oder "omsorgcore-client-ts" nach npm-Link/Publish

const config = new Configuration({ basePath: process.env.OMSORG_CORE_URL || "http://localhost:5245" });
const authApi = new AuthApi(config);

const loginResponse = await authApi.apiAuthLoginPost({
  loginRequest: { username: "admin", password: "abersicher" },
});
console.log(loginResponse.accessToken);

Jeder Controller aus omsorgCore hat eine eigene *Api-Klasse (AuthApi, EmployeesApi, FacilitiesApi, ContractsApi, OrdersApi, RolesApi, UsersApi, ValueListsApi, AuditLogApi, AdminSessionsApi, AdminEmailApi, HealthApi), Methodennamen sind aus den Routen abgeleitet (z. B. apiEmployeesGet, apiEmployeesIdPut) — siehe src/apis/index.ts bzw. das generierte README.md für die vollständige Liste.

Verbindlich: nach jeder Backend-Änderung neu generieren

Sobald sich Controller/DTOs in omsorgCore.Api/Contracts ändern (neue Endpunkte, neue/umbenannte/entfernte Felder in Requests/Responses), muss dieser Client noch im selben Change neu generiert (npm run generate), neu gebaut (npm run build) und der Diff mitcommittet werden.

Das ist kein Nice-to-have, sondern verhindert einen stillen, fehlerfreien Datenverlust: Ein veralteter generierter Client wirft keinen Fehler, wenn er ein Feld nicht kennt — er lässt es beim (De-)Serialisieren einfach weg. Ein Request/eine Response, die dieses Feld enthält, sieht aus der UI heraus wie ein Erfolg aus, das Feld kommt aber nie beim Backend an bzw. nie in der Antwort zurück. Konkret passiert (2026-08-08, Facility-Website): Website wurde im Backend ergänzt, Speichern in omsorgapp meldete Erfolg, aber der Wert wurde nie persistiert, weil omsorgcore-client-ts zum Zeitpunkt der Änderung noch aus der alten Swagger-JSON generiert war.

Nach npm run generate immer git diff package.json prüfen — der Generator überschreibt die Datei komplett, das eigene generate-Script ("generate": "./generate.sh") muss danach erneut eingetragen werden, sonst fehlt es beim nächsten Lauf.