TypeScript SDK

Überblick

Ottili ONE bietet ein offizielles TypeScript SDK*: das Ottili Module SDK*. Es ist ein Scaffolding- und Authoring-Toolkit, mit dem Sie plattformkonforme Module aus Code heraus erstellen, validieren und mit TypeScript-Typen ausstatten — statt das Dashboard manuell zu konfigurieren. Dieser Artikel beschreibt, was das SDK kann, wie Sie es aus dem Quellcode installieren, die CLI nutzen und es als Bibliothek in TypeScript einbinden.

Status:* Das Ottili Module SDK (TypeScript)* ist Gepflegt · quelloffen verfügbar* (Version 1.0.0). Es ist derzeit nicht* auf npm veröffentlicht — Sie bauen es aus dem Monorepo-Quellcode. Ein TypeScript Developer SDK* für die öffentliche API ist Geplant*, aber noch nicht verfügbar (siehe unten).

Welches SDK ist das richtige?

• Sie bauen ein neues Plattformmodul oder Add-on*? → Ottili Module SDK (TypeScript)* (dieser Artikel).
• Sie rufen die öffentliche Plattform-API* aus Ihrem Backend auf? → Nutzen Sie vorerst das [Python Developer SDK ottili-sdk](/docs/sdk-and-client-libraries) (Beta, aus Quelle) oder rufen Sie die API direkt über HTTPS auf. Ein spiegeltes TypeScript Developer SDK* ist geplant.
• Sie brauchen eine Sprache, die wir noch nicht ausliefern? → Rufen Sie die [öffentliche API](/docs/public-api-overview) direkt über HTTPS auf.

Das Ottili Module SDK (TypeScript)

• Sprache*: TypeScript / Node.js 18+
• Paket*: ottili-module-sdk
• Version*: 1.0.0
• Status*: Gepflegt · quelloffen verfügbar
• Quelle*: ottili-module-sdk/
• Binaries*: create-ottili-module und ottili-module (aus dist/cli.js)

Installation aus dem Quellcode

Das Paket ist noch nicht auf npm veröffentlicht. Klonen Sie das Monorepo und bauen Sie es lokal:

git clone https://github.com/ottili/ottili-one.git
cd ottili-one/ottili-module-sdk
npm install
npm run build

Danach rufen Sie die gebaute CLI direkt auf:

# Neues Modul aus der gebauten CLI scaffolen
node dist/cli.js create-ottili-module my-module --category integration

Ohne das Monorepo zu klonen, können Sie einen lokalen Checkout auch per npx ansprechen:

npx --package /path/to/ottili-module-sdk create-ottili-module my-module

Hinweis:* Der globale npm install -g ottili-module-sdk und der veröffentlichte npx create-ottili-module-Shortcut sind noch nicht verfügbar, weil das Paket nicht auf npm veröffentlicht ist. Bauen Sie es wie oben aus dem Quellcode.

Die CLI nutzen

Die CLI heißt create-ottili-module (Alias ottili-module) und kennt drei Befehle: create, validate und print-manifest.

Neues Modul erstellen

# Einfaches Modul
create-ottili-module my-module

# Mit Name, Beschreibung und Kategorie
create-ottili-module my-module \
  --name "My Module" \
  --description "A custom module for my use case" \
  --category "integration"

# Mit Express-Template (Node.js/TypeScript) statt FastAPI (Python)
create-ottili-module my-module --template express

# In ein anderes Ausgabeverzeichnis
create-ottili-module my-module --output /path/to/output

Optionen von `create`:*

• --name, -n — Modulname (Standard: aus dem Slug abgeleiteter Titel).
• --description, -d — Modulbeschreibung.
• --category, -c — Modulkategorie (Standard: tools).
• --template, -t — Service-Template: fastapi (Python) oder express (Node.js/TypeScript) (Standard: fastapi).
• --output, -o — Ausgabeverzeichnis (Standard: aktuelles Verzeichnis).

Manifest validieren und ausgeben

# Manifest im aktuellen Verzeichnis prüfen
ottili-module validate

# Manifest eines bestimmten Verzeichnisses prüfen
ottili-module validate --path /path/to/module

# Manifest als JSON ausgeben
ottili-module print-manifest --path /path/to/module

Als TypeScript-Bibliothek nutzen

Sie können das SDK auch programmatisch als TypeScript-Bibliothek importieren — etwa um Manifeste zu parsen und zu validieren oder Service-Templates zu erzeugen:

import {
  parseManifest,
  validateManifest,
  generateFastAPIServiceTemplate,
  generateExpressServiceTemplate,
} from "ottili-module-sdk";

// Manifest parsen und validieren
const manifest = parseManifest(manifestData);
const result = validateManifest(manifest);

// Service-Templates erzeugen
const fastapiCode = generateFastAPIServiceTemplate("my-module", "My Module");
const expressCode = generateExpressServiceTemplate("my-module", "My Module");

Verfügbare TypeScript-Typen und Funktionen umfassen unter anderem ModuleSdkManifest, ValidationResult, DEFAULT_SURFACE_NAMES, DEFAULT_ROUTE_ORDER, SurfaceName, Visibility, ActivationType, RolloutState sowie die Generator-Funktionen für Oberflächen- und Health-Check-Payloads.

Modul-Service-Vertrag

Jeder SDK-Modulservice muss diese Endpunkte bereitstellen:

• GET /ottili/health — Health-Check.
• GET /ottili/surfaces/overview — Overview-Surface.
• GET /ottili/surfaces/workspace — Workspace-Surface.
• GET /ottili/surfaces/activity — Activity-Surface.
• GET /ottili/surfaces/settings — Settings-Surface.
• GET|POST|PUT|PATCH|DELETE /ottili/actions/* — Action-Endpunkte.

Die generierten Templates enthalten alle Pflichtendpunkte mit Standardimplementierungen.

Manifest-Struktur (ottili.module.json)

Das create-Kommando erzeugt ein ottili.module.json mit Metadaten, Routen, Capabilities und Runtime-Konfiguration:

{
  "manifestVersion": "1.0",
  "sdkVersion": "1.0.0",
  "module": {
    "slug": "my-module",
    "name": "My Module",
    "description": "A new Ottili ONE module",
    "category": "tools",
    "visibility": "public",
    "activationType": "self_service",
    "supportsMultiTenant": true
  },
  "routes": [
    {
      "routeKey": "overview",
      "label": "Overview",
      "appPath": "/dashboard/modules/my-module",
      "routeType": "overview",
      "isDefault": true,
      "sortOrder": 10
    }
  ],
  "capabilities": [
    {
      "capabilityKey": "my-module.basic",
      "title": "My Module Basic Access",
      "description": "Basic access to the module",
      "sourceService": "my-module_service",
      "rolloutState": "internal"
    }
  ],
  "runtime": {
    "mode": "service",
    "healthPath": "/ottili/health",
    "surfacesPath": "/ottili/surfaces",
    "actionBasePath": "/ottili/actions",
    "surfaceNames": ["overview", "workspace", "activity", "settings"]
  }
}

Nach dem Erstellen implementieren Sie Ihre Logik im Service, testen die Contract-Endpunkte lokal, validieren das Manifest mit ottili-module validate und übergeben das Git-Repository dem Ottili-Plattformteam zur Übernahme und zum Hosting.

Geplanter TypeScript Developer SDK (öffentliche API)

Ein TypeScript-Client für die öffentliche Developer-API*, der das Python-SDK ottili-sdk spiegelt, ist Geplant*. Er ist noch nicht verfügbar; folgen Sie ihm auf der öffentlichen Roadmap. Bis dahin erreichen Sie die öffentliche API unter der Basis-URL https://api.ottili.one (siehe [Öffentliche API im Überblick](/docs/public-api-overview)) direkt über HTTPS. Die Authentifizierung für kommende Developer-API-Calls ist unter [Öffentliche API-Authentifizierung](/docs/public-api-authentication) beschrieben.

Status der Funktionen

Verwandte Artikel

• [SDKs und Client-Bibliotheken](/docs/sdk-and-client-libraries)
• [Öffentliche API im Überblick](/docs/public-api-overview)
• [Öffentlicher API-Vertrag](/docs/public-api-contract)
• [Öffentliche API-Authentifizierung](/docs/public-api-authentication)
• [Was ist Ottili ONE](/docs/what-is-ottili-one)