TypeScript SDK

Overview

Ottili ONE ships an official TypeScript SDK*: the Ottili Module SDK*. It is a scaffolding and authoring toolkit for creating, validating, and typing platform-compliant modules from code instead of configuring the dashboard by hand. This article explains what the SDK does, how to install it from source, use the CLI, and import it as a TypeScript library.

Status:* The Ottili Module SDK (TypeScript)* is Maintained · source-available* (version 1.0.0). It is not* published to npm yet — you build it from the monorepo source. A TypeScript Developer SDK* for the public API is Planned* but not available yet (see below).

Which SDK do you need?

• Building a new platform module or add-on*? → Ottili Module SDK (TypeScript)* (this article).
• Calling the public platform API* from your backend? → For now use the [Python Developer SDK ottili-sdk](/docs/sdk-and-client-libraries) (Beta, from source) or call the API directly over HTTPS. A mirrored TypeScript Developer SDK* is planned.
• Need a language we do not ship yet? → Call the [public API](/docs/public-api-overview) directly over HTTPS.

The Ottili Module SDK (TypeScript)

• Language*: TypeScript / Node.js 18+
• Package*: ottili-module-sdk
• Version*: 1.0.0
• Status*: Maintained · source-available
• Source*: ottili-module-sdk/
• Binaries*: create-ottili-module and ottili-module (from dist/cli.js)

Install from source

The package is not published to npm yet. Clone the monorepo and build it locally:

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

Then run the built CLI directly:

# Scaffold a new module from the built CLI
node dist/cli.js create-ottili-module my-module --category integration

Without cloning the monorepo, you can also point npx at a local checkout:

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

Note:* the global npm install -g ottili-module-sdk and the published npx create-ottili-module shortcut are not available yet because the package is not on npm. Build it from source as shown above.

Using the CLI

The CLI is named create-ottili-module (alias ottili-module) and has three commands: create, validate, and print-manifest.

Create a new module

# Basic module
create-ottili-module my-module

# With name, description and category
create-ottili-module my-module \
  --name "My Module" \
  --description "A custom module for my use case" \
  --category "integration"

# With the Express template (Node.js/TypeScript) instead of FastAPI (Python)
create-ottili-module my-module --template express

# Into a custom output directory
create-ottili-module my-module --output /path/to/output

`create` options:*

• --name, -n — Module name (defaults to the slug converted to title case).
• --description, -d — Module description.
• --category, -c — Module category (default: tools).
• --template, -t — Service template: fastapi (Python) or express (Node.js/TypeScript) (default: fastapi).
• --output, -o — Output directory (default: current directory).

Validate and print the manifest

# Validate the manifest in the current directory
ottili-module validate

# Validate a specific directory
ottili-module validate --path /path/to/module

# Print the manifest as JSON
ottili-module print-manifest --path /path/to/module

Use it as a TypeScript library

You can also import the SDK programmatically as a TypeScript library — for example to parse and validate manifests or to generate service templates:

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

// Parse and validate a manifest
const manifest = parseManifest(manifestData);
const result = validateManifest(manifest);

// Generate service templates
const fastapiCode = generateFastAPIServiceTemplate("my-module", "My Module");
const expressCode = generateExpressServiceTemplate("my-module", "My Module");

Available TypeScript types and functions include ModuleSdkManifest, ValidationResult, DEFAULT_SURFACE_NAMES, DEFAULT_ROUTE_ORDER, SurfaceName, Visibility, ActivationType, RolloutState, and the surface/health-check payload generators.

Module service contract

Every SDK module service must expose these endpoints:

• 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 endpoints.

The generated templates include all required endpoints with default implementations.

Manifest structure (ottili.module.json)

The create command writes an ottili.module.json with metadata, routes, capabilities, and runtime configuration:

{
  "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"]
  }
}

After creating your module, implement your logic in the service, test the contract endpoints locally, validate the manifest with ottili-module validate, and hand the Git repository to the Ottili platform team for import and hosting.

Planned TypeScript Developer SDK (public API)

A TypeScript client for the public Developer API*, mirroring the Python ottili-sdk, is Planned*. It is not available yet; track it on the public roadmap. Until then, reach the public API at the base URL https://api.ottili.one (see [Public API Overview](/docs/public-api-overview)) directly over HTTPS. Authentication for upcoming developer API calls is described in [Public API authentication](/docs/public-api-authentication).

Feature status

Related articles

• [SDKs and Client Libraries](/docs/sdk-and-client-libraries)
• [Public API Overview](/docs/public-api-overview)
• [Public API Contract](/docs/public-api-contract)
• [Public API authentication](/docs/public-api-authentication)
• [What is Ottili ONE](/docs/what-is-ottili-one)