kundencenter/docs/connector-vertrag.md

Connector-Vertrag v1

Code: packages/connector-sdk/src/index.ts. Jeder Provider implementiert Connector und liefert nur normalisierte Daten (NormalizedResource). Provider-Rohmodelle bleiben im Connector-Paket.

Element	Beschreibung
capabilities(ctx)	Fähigkeiten (resources.list, lifecycle.suspend, …). Backend/UI bieten nur Gemeldetes an. Das Lizenz-Connector meldet Schreibfähigkeiten nur mit konfiguriertem API-Benutzer.
healthCheck(ctx)	Erreichbarkeit + Latenz. Ergebnis wird an der Instanz gespeichert (health, last_ok_at).
listResources(ctx)	Abgleich. Ergebnis wird in resources gespiegelt; nicht mehr gelieferte Objekte werden mit missing_since markiert, nie gelöscht.
execute(ctx, {action, externalRef, params, idempotencyKey})	Schreibende Aktion. Läuft ausschließlich als persistenter Auftrag (connector.execute), Idempotenzschlüssel = Job-ID. Aktionen setzen absolute Zielzustände (z. B. until), damit Wiederholung wirkungsgleich ist.
Fehler	ConnectorError mit Codes UNREACHABLE, TIMEOUT, AUTH_FAILED, RATE_LIMITED, NOT_FOUND, INVALID_RESPONSE, UNSUPPORTED, CONFLICT, UPSTREAM_ERROR, BAD_CONFIG; retryable und userMessage (ohne technische Details).
HTTP	httpJson: Timeout, exponentielles Backoff mit Jitter, Retry-After; Wiederholung nur für GET, Schreibzugriffe nie automatisch im Connector.

Aufträge

Status: geplant → wird ausgeführt → erfolgreich | wird wiederholt → manuelle Prüfung erforderlich / fehlgeschlagen. Retries begrenzt (max_attempts, Backoff 30 s · 2ⁿ, max. 1 h). Destruktive Aktionen (terminate) werden nie automatisch wiederholt, auch nicht nach Worker-Absturz (needs_review), und lassen sich nicht über „Erneut ausführen“ starten.

Neuer Connector

1. Paket packages/connector-<name> mit Connector-Implementierung, configFields (Secrets als secret: true).
2. Vertragstest: runContract(...) aus @kc/connector-sdk/dist/contract.js plus Fixtures mit anonymisierten Antworten.
3. In packages/connectors/src/index.ts registrieren. Keine weitere Änderung in API/Worker/UI nötig.

Vorhandene Connectoren

• mock – Testdaten ([Mock]), simuliert Ausfälle (simulateOutage).
• licensing – eigenes Lizenzsystem. Erkennt Erweiterungen über GET / → features:
  • Zugang bevorzugt per Service-Token (token), alternativ API-Benutzer/Passwort. Ohne Zugang nur lesend.
  • catalog.list: Produktkatalog des Lizenzsystems (Programm → Gruppe → Produkt mit Preis, Dauer, Features) als Übernahmevorlagen; Produkt- und Programmschlüssel werden nie ausgegeben. Ältere Systeme: Programme mit Vorschlägen aus bestehenden Lizenzen.
  • lifecycle: Sperren/Entsperren/Verlängern über die Endpunkte /licenses/{id}/suspend|unsuspend|extend (Zielzustand, protokolliert); sonst Rückfall auf PUT.
  • Zustand berücksichtigt is_active, blocked, status, suspended_at, revoked_at und Ablauf. Bei utc_timestamps werden Zeiten als UTC gelesen, sonst als Ortszeit.
  • Anlage (lifecycle.create) mit product_id (Plan/Edition des Lizenzsystems); Produkt und Präfix dürfen nie stillschweigend verloren gehen (Antwort wird geprüft).
• KeyHelp, Plesk: offen (keine Testzugänge; siehe Plane).

Zugangsdaten

Secrets werden pro Verbindung mit AES-256-GCM verschlüsselt (connector_instances.secrets_enc), nur Superadmins dürfen Verbindungen anlegen/ändern, die UI zeigt sie nie wieder an, das Audit-Protokoll maskiert sie.