Manifest (olan-app.json)

{
  "$schema": "https://olan.app/schemas/olan-app/v1.json",
  "schemaVersion": 1,
  "id": "com.example.overdue-tasks",
  "name": "Geciken görevler",
  "version": "0.1.0",
  "sdk": "^1.8.0",
  "minServerVersion": "0.1.0",
  "description": "Projelerdeki geciken görevler",
  "entry": "dist/app.js",
  "icon": "assets/icon.png",
  "surfaces": {
    "app": { "title": "Geciken görevler" },
    "project.widget": { "title": "Gecikenler" },
    "settings": { "title": "Ayarlar" }
  },
  "permissions": ["projects:read"],
  "settings": {
    "threshold": { "type": "number", "label": "Gecikme eşiği (gün)", "default": 3 }
  }
}

Unknown top-level fields are errors (manifest.unknown_field); only $schema is extra. The allowed fields depend on schemaVersion (only 1 today).

server declares backend code that Olan runs (server/index.ts with @olan-app/sdk/backend; backend.md). A server whose administrator turned backends off (OLAN_APPS_BACKEND=0) rejects it with manifest.feature_not_available.

Data (olan.db) #

data declares the app's database collections (since SDK 1.1.0, still schemaVersion: 1):

"data": {
  "version": 1,
  "collections": {
    "decisions": {
      "scope": "organization",
      "fields": {
        "title": { "type": "string", "required": true, "maxLength": 200, "indexed": true },
        "status": { "type": "string", "enum": ["open", "done"], "indexed": true },
        "projectId": { "type": "ref:project", "indexed": true }
      },
      "rules": { "read": "any", "update": "any", "delete": "owner" }
    }
  }
}

Field types, options, limits, scopes, rules and schema changes: database.md. Errors: manifest.data_* (errors.md).

Surfaces #

app, project.widget, settings, project.tab and project.settings entries are { "title"?: string } (≤ 80; defaults to the app name); the other surfaces need "title", chat.command also "command" (surfaces.md). Every declared surface must be defined in defineApp({ ... }) with the same name (app.surface_missing), and a surface defined in code but not declared is never opened (app.surface_undeclared).

export default defineApp({ app: Overview, 'project.widget': OverdueCard, settings: SettingsScreen });

projectTemplates #

SDK 1.7: up to 5 project templates the organization's "Yeni proje" lists while the app is installed for the person. A project made from one gets the template's work packages, statuses, labels, starter tasks and task/issue templates, and the app is added to it; the statuses and labels are the app's (members use them, the app manages them with olan.project.statuses / labels). A new app version with the same key replaces the template.

"projectTemplates": [{
  "key": "purchasing",
  "name": "Satın alma",
  "description": "Talep, onay, sipariş ve teslim",
  "content": {
    "version": 1,
    "lists": [{ "key": "requests", "title": "Talepler", "steps": [{ "key": "approval", "title": "Onay" }] }],
    "statuses": [
      { "key": "todo", "name": "Yeni talep", "color": "#8A94A6", "category": "unstarted" },
      { "key": "awaiting-approval", "name": "Onay bekliyor", "color": "#E0A526", "category": "started" },
      { "key": "done", "name": "Teslim alındı", "color": "#2F9E6E", "category": "completed" },
      { "key": "cancelled", "name": "İptal", "color": "#A1A7B3", "category": "cancelled" }
    ],
    "labels": [{ "name": "Donanım", "color": "#5B8DEF", "groupName": "Tür" }]
  }
}]

• key ^[a-z0-9][a-z0-9._-]{0,62}$, unique; name 1–120; description ≤ 2000; content ≤ 64 KiB.
• content: version: 1; lists (1–50 work packages, key, title, code?, color?, steps? ≤ 50); statuses? (≤ 30, { key, name, color: #RRGGBB, category }; when given they replace the defaults, so include one per unstarted, started, completed and cancelled); labels? (≤ 100, { name, color, groupName?, description? }); tasks? (≤ 200) and recordTemplates? (≤ 50) in the shape of Olan's own project templates; settings? (description, coverColor, estimateScale).
• The manifest checks the shape (manifest.project_template_invalid); the server checks references between keys and skips a template it cannot use.

Settings fields #

settings maps a key (^[A-Za-z][A-Za-z0-9_]{0,63}$, ≤ 64 fields) to a field:

"settings": {
  "currency": { "type": "select", "label": "Para birimi", "default": "TRY", "options": [
    { "value": "TRY", "label": "Türk lirası" }, { "value": "EUR", "label": "Euro" } ] },
  "apiKey": { "type": "string", "label": "API anahtarı", "secret": true },
  "showDone": { "type": "boolean", "label": "Bitenleri göster", "default": false }
}

Olan generates the settings form from these fields (unless the app has a settings surface). Read values with useSettings() or olan.settings.get(); defaults apply to unset fields. In tests and validate --strict the defaults apply too, overridden by fixtures/settings.json.

Web links #

{ "kind": "web-link", "url": "https://…" } describes a link instead of a packaged app: no entry, no settings, no permissions, no remote/events/ai, only the app surface (optional), and icon is an http(s) URL or an Olan icon name. Users add web links in Olan → Uygulamalar; they are not built with this SDK.

Package (olan-app pack) #

dist/<id>-<version>.olanapp is a ZIP of olan-app.json, dist/app.js, dist/server.js (when the manifest declares server), assets/**, a digest.json (SHA-256 of every file and of the whole package) and, when signed (--dev-sign, or olan-app.key.json exists), signature.json (Ed25519; optional keyId, cli.md#signing-and-publishing). The package must stay ≤ 5 MiB. The bundles keep the license comments of bundled code at the end of the file; other notices go in assets/NOTICE or assets/THIRD_PARTY_NOTICES (marketplace.md#automatic-checks). Organization admins upload it (olan-app publish --org, or the admin panel's Uygulamalar section).