# Anleitung — omsorgcore-client-ts

Generierter TypeScript-Client für die `omsorgCore`-API, erzeugt mit [openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator) aus der Swagger/OpenAPI-JSON des Backends. **Kein eigenständiges Extra mehr:** Alle handgeschriebenen Wrapper unter `electron/backend/*Client.cjs` (`employeesClient.cjs`, `facilitiesClient.cjs`, `usersClient.cjs`, ...) importieren ihre `*Api`-Klasse aus diesem Paket (`require('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)

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

## Client neu generieren

```bash
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 `electron/backend/config.cjs`). Ü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

```bash
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)

```ts
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.