Diese Sektion dokumentiert das Platform-SDK: die Bausteine, mit denen Tools für die Plattform entwickelt werden. Du findest hier die Referenz für jeden SDK-Namespace und den Leitfaden für den Aufbau eines kompletten Moduls.
Architektur in Kürze
- Tool vs. Modul: Ein Tool ist der Name, den Nutzer:innen im Marketplace sehen (z.B. "Zugangsdaten-Tresor"). Ein Modul ist die Code-Struktur dahinter: ein Ordner mit Manifest, Compute, UI und Tests. Ein Tool wird durch genau ein Modul implementiert.
- Manifest als Single Source of Truth:
manifest.tsdeklariert ID, Version, Kategorie, Credit-Kosten, Permissions, UI-Flächen, Lifecycle-Hooks und das Marketplace-Listing. CI validiert jedes Manifest gegen das Schema (ModuleManifestSchemaaus@reosa/sdk). - Compute über den Runs-Harness: Module exportieren eine
runTool-Funktion. Der Plattform-Harness besitzt den kompletten Lauf-Lebenszyklus: Credits reservieren, Lauf ausführen, bei Erfolg committen, bei Fehler erstatten und benachrichtigen. Ein Modul fasst nie selbst Credits, Notifications oder Run-Tabellen an. - Reserve→Compute→Commit/Refund: Jede credit-verbrauchende Aktion läuft über dieses Two-Phase-Pattern. Niemals direkt abbuchen. Details auf der Credits-Seite.
- Context als erster Parameter: Jeder server-seitige SDK-Aufruf nimmt einen
PlatformContext(Tenant, User, Rolle, Permissions). Tenant-Isolation erzwingt Postgres-RLS, nicht dein Code. - Fehler-Hierarchie: Alle SDK-Fehler erben von
SdkErrormit strukturiertemcodeunddetails. Du branchst mitinstanceof(z.B.InsufficientCreditsError,StorageQuotaExceededError,PermissionDeniedError).
Der Weg zu einem Tool
SDK-Namespaces
Credits
Reserve→Compute→Commit/Refund, Fehlerbilder, Anzeige-Regel für kleine Beträge und Add-on-Tools.
Storage
Quota-geprüfte Writes, Bucket-Wahl per Key-Prefix und der saubere Umgang mit vollem Speicher.
Dateispeicher (Files)
Tool-Ausgaben sichtbar im Explorer ablegen, Dateien wählen lassen und teilen.
REOS AI
Tier-basierte KI ohne Modell-Namen, Abrechnungs-Modi und BYOK.
Notifications
In-App-Benachrichtigungen an einzelne Nutzer:innen oder Rollen, mit Action-Buttons.
Audit
Der unveränderliche Audit-Trail: Namenskonvention, Metadaten-Regeln, Sichtbarkeit.
Compliance
AGG-Diskriminierungs-Check für Inserats-Texte und die AI-Risk-Klassen im Manifest.
Share
Zeitlich begrenzte, optional passwortgeschützte Links nach außen, mit Widerruf und Zähler.
Webhooks und Events
Domain-Events emittieren, im Event-Katalog registrieren, Outbox-Zustellung verstehen.
Grundregeln
- Externe Inputs immer mit Zod validieren, bevor du sie verarbeitest. Das gilt auch für das
payloaddeiner eigenen Tool-UI. - Nie direkt auf Provider oder Storage zugreifen. KI-Aufrufe laufen über REOS AI, Datei-Writes über den Dateispeicher bzw. Storage. Direktzugriffe blockt der Reuse-Ratchet in CI.
- Frontend-Gating ist UX, Backend-Check ist Security. Jede Permission wird an beiden Stellen geprüft (Defense in Depth).
- Keine PII in Logs und Telemetrie. Nutzereingaben, Datei-Inhalte und Geheimnisse gehören nie nach Sentry oder PostHog.
- User-Trust gewinnt. Jeder technische Fehler erstattet Credits automatisch; der Harness erledigt das, wenn dein Compute wirft.
Das Gegenstück für API-Integrationen (Webhooks empfangen, REST-API) findest du in der API-Sektion.