# @olan-app/sdk — Olan Apps SDK (llms.txt)

> One-file digest of node_modules/@olan-app/sdk/docs/*.md (generated; edit the docs instead).
> Olan Apps are React + TypeScript running in a sandbox; UI = the 23 SDK components, data = permission-checked olan.* calls.
> Done = `npx olan-app validate --strict` and `npx olan-app test` both pass.

<!-- docs/getting-started.md -->
# Getting started

An Olan App is a small React program that runs in a sandbox (a Web Worker on web/desktop, an
isolated JS engine on mobile). It does not draw anything itself: it describes its screen with the
components of `@olan-app/sdk`, and Olan draws them with its own native controls on every platform.
Data comes from `olan.*` calls that Olan answers after checking the app's permissions.

Formerly @olan/app-sdk; the old name still builds.

## Create an app

```sh
npx olan-app init "Geciken görevler" --template list-detail   # or: olan app init …
cd geciken-gorevler
npm install
npx olan-app validate --strict
npx olan-app test
npx olan-app dev        # serve it to Olan Studio (Geliştirme sunucuları)
```

Templates: `blank` (one screen), `list-detail` (projects → tasks → task), `project-widget` (a card on
the project page), `project-tab` (a project tab and project settings with `olan.project.config`), `project-records`
(the app's records on tasks: a task action, a record card, the app's status, calendar items, feed
lines, approvals and a project template; SDK 1.7), `external-api` (`olan.http.fetch` with an `http:<host>` permission), `data-list`
(`olan.db`), `backend` (`--backend`: UI + backend code that Olan runs, backend.md).

## Project layout

```
olan-app.json          manifest: id, name, version, surfaces, permissions, settings (manifest.md)
src/app.tsx            the app; must `export default defineApp({ ... })`
tests/*.test.ts        headless tests (node:test + @olan-app/cli/testing) (testing.md)
fixtures/*.json        mock data for tests, validate --strict and dev (testing.md#fixtures)
assets/icon.png        icon referenced by the manifest
dist/app.js            build output (generated, git-ignored)
AGENTS.md, CLAUDE.md   instructions for coding agents
```

## The smallest app

```tsx
import { useState } from 'react';
import { Button, Screen, Stack, Text, defineApp, olan } from '@olan-app/sdk';

function Home() {
  const [count, setCount] = useState(0);
  return (
    <Screen title="Sayaç">
      <Stack gap="md" padding="md">
        <Text text={`Düğmeye ${count} kez bastınız.`} />
        <Button label="Bas" variant="primary" onPress={() => setCount((value) => value + 1)} />
        <Button label="Bildirim" onPress={() => olan.ui.toast({ text: 'Merhaba!', tone: 'success' })} />
      </Stack>
    </Screen>
  );
}

export default defineApp({ app: Home });
```

```json
{
  "schemaVersion": 1,
  "id": "com.example.counter",
  "name": "Sayaç",
  "version": "0.1.0",
  "sdk": "^1.8.0",
  "entry": "dist/app.js",
  "surfaces": { "app": { "title": "Sayaç" } },
  "permissions": []
}
```

## Rules (the sandbox enforces them; `validate --strict` reports them)

1. **Surfaces are named components.** `defineApp({ app: Home })`, never an inline arrow function
   (the React hook rules only apply to named components). Surface names: `app`,
   `project.widget`, `project.tab`, `project.settings`, `settings` (and the in-context surfaces of
   surfaces.md) — and each one used must be declared in `olan-app.json` `surfaces`.
2. **Only SDK components.** No DOM elements (`<div>`, `<span>`), no `react-dom`, no
   `react-native`, no Node built-ins (`fs`, `path`, …). There is no `style` or `className`: Olan
   owns colours, fonts and spacing. Use `tone`, `variant`, `gap` and `padding` props instead.
3. **Text lives in `<Text>`.** A string directly inside `Screen`, `Stack`, `Card` or `Form` is an
   error (`tree.text_outside_text`). Write `<Text text="…" />` or `<Text>…</Text>`.
4. **No browser globals for I/O.** `fetch`, `XMLHttpRequest`, `WebSocket`, `localStorage`,
   `indexedDB`, `window`, `document` do not exist. Use `olan.http.fetch`, `olan.storage`,
   `olan.settings`.
5. **Every `olan.*` call needs its permission** in `olan-app.json` `permissions` (permissions.md).
   Without it the call rejects with `OlanError` code `permission_denied` (`http_blocked` for HTTP).
6. **Keys are unique.** Every `List` item, `Table` row, `Menu` item and `Action` has a unique `key`
   (string or number); events give it back as `{ key }`.
7. **Every `Button` has a `label`.** Every `Menu` has a `label` (or at least an `icon`).
8. **Use React normally:** `useState`, `useEffect`, `useMemo`, custom hooks, context. Load data with
   `useQuery(() => olan.….(), [deps])` (hooks.md).

## Done means

```sh
npx olan-app validate --strict   # manifest, build, TypeScript, every surface rendered, no missing permission
npx olan-app test                # all tests pass
```

Both exit with code 0. Add `--json` for machine-readable output (cli.md).

## Running it in Olan

During development the app runs unsigned, but only in development mode: Studio, `olan-app dev`
and "Olan'da dene" (`/apps/dev`), for people an administrator gave the `developer` grant, under
a "Geliştirme" label. **Studio** is in the Olan web app: sign in at your Olan web address (e.g. `https://olan.example.com`) with an account that has the `developer` grant (Yönetim → Kullanıcılar) and open `<Olan web address>/tr/studio`; `/tr/studio?section=publish` opens Yayınla (marketplace publishing).

Installing it (for yourself or the organization) needs a signed package. An Olan server installs a
package only when its signature verifies and the signing key is on the server's trusted key list.
Every Olan server ships with the Olan Marketplace key built in (`olan-marketplace-2026-10-17`), and
in production that is the only trusted key, so apps reach real organizations through Olan
Marketplace review. An unsigned package can be uploaded, but it is listed as "İmzasız" and
cannot be installed. For your own local Olan:

```sh
npx olan-app keygen --dev        # once; prints OLAN_APPS_TRUSTED_KEYS=dev-local=<key> for the local API
npx olan-app validate --strict   # first: pack runs only the non-strict checks (and refuses on errors)
npx olan-app pack --dev-sign     # dist/<id>-<version>.olanapp, signed with your development key
```

Then upload it in Olan → Yönetim → Uygulamalar → Katalog (or `olan-app publish --org --dev-sign`)
and install it there (cli.md#signing-and-publishing). Uploading and, by default, installing are for organization admins: an organization without an install policy is "admin only" until an admin lets members install apps.

For real organizations, submit it to Olan Marketplace (automatic checks, review, signing;
marketplace.md):

```sh
npx olan-app login --marketplace --server https://api.example.com   # once: signs you in in the browser
npx olan-app developer create --marketplace --slug acme --name "Acme Ltd" --accept-agreement   # once
npx olan-app publish --marketplace --age-rating 4+   # age rating (4+, 9+, 13+): required before release
npx olan-app release --marketplace <appId> <version>  # after approval (`olan-app status` prints the exact command)
```

With an Olan CLI that has the `app` command and is signed in, `olan app login --marketplace` works too. CI does not sign in: it uses the saved session as `OLAN_MARKETPLACE_SESSION` (marketplace.md#signing-in).

## Where to read next

- components.md — every component and its props
- api.md — `olan.*` (projects, chat, storage, settings, http, ui, navigation)
- hooks.md, navigation.md — `useQuery`, `useNavigation`, multi-screen apps
- permissions.md, manifest.md — what to declare in `olan-app.json`
- server.md, remote-requests.md, files.md, links.md — the app's own server, requests as the person,
  file uploads, external sign-in flows and app addresses
- testing.md — `renderApp`, fixtures, assertions
- cli.md, errors.md — commands and every error code with its fix
- marketplace.md, review-guidelines.md — sign-in, publishing, the automatic checks and the review rules
- examples.md — complete apps to copy from

<!-- docs/components.md -->
# Components

Import every component from `@olan-app/sdk`. These 23 are the only ones that exist (SDK 1.5 added
`Tabs`, `Switch`, `MultiSelect`, `Stat`, `Banner`, `Image`, `Avatar` and `ProgressBar`; apps using
them declare `"sdk": "^1.5.0"`); Olan draws each
with its own native control (web, desktop, iOS, Android). All props are optional unless marked
**required**. Props not listed here are rejected (`tree.unknown_prop`), including `style`,
`className`, `color` and `id`.

Handler props (`onPress`, `onSelect`, `onChange`, `onSubmit`, …) may be async; a rejected promise is
reported as an app error. Event payloads are listed with each handler.

Shared value sets:

| Type | Values |
|---|---|
| `Tone` | `'default' \| 'muted' \| 'accent' \| 'danger' \| 'success' \| 'warning'` |
| `Spacing` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg'` |
| `Key` | `string \| number` (non-empty string) |
| `IconName` | a name from the icon list at the end of this page |
| `Action` | `{ key: Key; label: string; icon?: IconName; onPress: () => void }` |

Children: `Screen`, `Stack`, `Card` and `Form` take any components; `Text` takes only text; every
other component takes no children (`tree.children_not_allowed`).

## Screen

Title bar plus body. **Required root** of the `app` and `settings` surfaces (`validate --strict`
warns `ui.root_not_screen`); also the recommended root of modal and panel surfaces (`chat.*`,
`mail.*`, `calendar.event.action`, `meeting.panel`, SDK 1.7 `task.action`, `issue.action`, `record.card`), where its title and actions are the header.
`project.widget` uses `Card` (or `EmptyState`) instead. `project.tab` and `project.settings` (SDK 1.6)
also start with `Screen`: its title heads the tab or the settings sheet.

| Prop | Type | Notes |
|---|---|---|
| `title` | `string` | Title bar text |
| `subtitle` | `string` | |
| `actions` | `Action[]` | Buttons in the title bar |
| `loading` | `boolean` | Shows a loading indicator |
| `scroll` | `boolean` | Body scrolls (default: host decides) |
| children | any | |

```tsx
<Screen title="Projeler" loading={q.loading} actions={[{ key: 'refresh', label: 'Yenile', icon: 'refresh', onPress: () => q.refetch() }]}>
  …
</Screen>
```

## Stack

Lays children out in a column (default) or a row.

| Prop | Type |
|---|---|
| `direction` | `'vertical' \| 'horizontal'` |
| `gap` | `Spacing` |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch'` |
| `justify` | `'start' \| 'center' \| 'end' \| 'between'` |
| `wrap` | `boolean` |
| `padding` | `Spacing` |
| children | any |

## Card

A grouped block. The usual root of a `project.widget` surface.

| Prop | Type |
|---|---|
| `title` | `string` |
| `subtitle` | `string` |
| `actions` | `Action[]` |
| `padding` | `Spacing` |
| children | any |

## Text

| Prop | Type | Notes |
|---|---|---|
| `text` | `string` | Or pass the text as children: `<Text>Merhaba {name}</Text>` |
| `variant` | `'title' \| 'heading' \| 'body' \| 'caption' \| 'label'` | |
| `tone` | `Tone` | |
| `weight` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` | |
| `truncate` | `boolean` | One line with an ellipsis |

Children may only be strings, numbers, booleans/null (ignored) or arrays of them — no elements.

## Badge

| Prop | Type |
|---|---|
| `text` **required** | `string` |
| `tone` | `Tone` |

## EmptyState

| Prop | Type | Notes |
|---|---|---|
| `title` **required** | `string` | |
| `description` | `string` | |
| `icon` | `IconName` | |
| `action` | `{ label: string; onPress: () => void }` | A button under the text |

## List

Rows with a title. Send all items; the host virtualises long lists.

| Prop | Type | Notes |
|---|---|---|
| `items` **required** | `ListItem[]` | |
| `onSelect` | `({ key }) => void` | Row pressed; `key` is the item's key |
| `emptyText` | `string` | Shown when `items` is empty |
| `loading` | `boolean` | |

`ListItem`: `{ key: Key (required); title: string (required); subtitle?: string; meta?: string (short trailing text, e.g. a date); badge?: { text: string; tone?: Tone }; icon?: IconName; disabled?: boolean }`.

```tsx
<List
  items={tasks.map((t) => ({ key: t.id, title: t.title, meta: t.due ?? undefined, badge: { text: 'Gecikti', tone: 'danger' } }))}
  emptyText="Görev yok"
  onSelect={({ key }) => navigation.push('task', { taskId: String(key) })}
/>
```

Do not pass `undefined`-valued text you need to see: `meta: t.due ?? undefined` omits it cleanly.

## Table

| Prop | Type | Notes |
|---|---|---|
| `columns` **required** | `TableColumn[]` | below |
| `rows` **required** | `{ key: Key; cells: Record<columnKey, string \| number \| null> }[]` | |
| `onSelectRow` | `({ key }) => void` | |
| `emptyText` | `string` | |
| `defaultSort` | `{ key: string; direction: 'asc' \| 'desc' }` | Initial order (SDK 1.5) |

`TableColumn`: `{ key: string; title: string; width?: number; align?: 'start' | 'center' | 'end';
format?: 'text' | 'number' | 'currency' | 'percent'; currency?: string; sortable?: boolean }`.
`width` is a relative (flex) weight > 0. SDK 1.5:

- `format`: the host formats number cells with the person's locale (`Intl.NumberFormat`); a cell
  that is not a number shows as it is. `percent` takes a fraction (`0.034` → "%3,4").
- `currency`: ISO 4217 (`'TRY'`), required with `format: 'currency'` (`tree.invalid_prop`).
- `sortable`: the person sorts by tapping the title. The host sorts the rows itself, on the raw
  cell values (numbers as numbers); there is no handler.

```tsx
<Table
  columns={[
    { key: 'name', title: 'Kampanya', sortable: true },
    { key: 'spend', title: 'Harcama', format: 'currency', currency: 'TRY', align: 'end', sortable: true },
    { key: 'ctr', title: 'TO', format: 'percent', align: 'end', sortable: true },
  ]}
  rows={campaigns.map((c) => ({ key: c.id, cells: { name: c.name, spend: c.spend, ctr: c.ctr } }))}
  defaultSort={{ key: 'spend', direction: 'desc' }}
/>
```

## Chart

| Prop | Type | Notes |
|---|---|---|
| `kind` **required** | `'bar' \| 'line' \| 'area'` | `area` since SDK 1.5 |
| `series` **required** | `{ name: string; points: { x: string; y: number }[] }[]` | `x` is a label (e.g. a date) |
| `height` | `number` | Integer 1–2000 |
| `stacked` | `boolean` | Stacks the series; `bar` and `area` only (SDK 1.5) |
| `valueFormat` | `'number' \| 'currency' \| 'percent'` | Axis and tooltip format (SDK 1.5; `percent` takes fractions) |
| `currency` | `string` | ISO 4217; required with `valueFormat: 'currency'` |

Colours come from Olan's chart palette; you cannot set them.

```tsx
<Chart kind="area" stacked valueFormat="currency" currency="TRY"
  series={[{ name: 'Meta', points: days.map((d) => ({ x: d.day, y: d.meta })) }, { name: 'Google', points: days.map((d) => ({ x: d.day, y: d.google })) }]} />
```

## Form

Groups fields and submits their values together.

| Prop | Type | Notes |
|---|---|---|
| `onSubmit` **required** | `({ values }) => void` | `values: Record<string, string>` maps each field `name` to its value |
| `submitLabel` | `string` | Submit button text |
| `cancelLabel` | `string` | |
| `onCancel` | `() => void` | |
| children | any | Fields and layout |

```tsx
<Form submitLabel="Kaydet" onSubmit={({ values }) => save(values.title, values.due)}>
  <TextField name="title" label="Başlık" required />
  <DatePicker name="due" label="Bitiş" />
</Form>
```

Submitting does **not** clear the fields: an uncontrolled field (no `value`) keeps what the user
typed, in Olan and in `renderApp`. To empty the form after a save, either control the fields
(`value={title}` + `onChange={({ value }) => setTitle(value)}`, then `setTitle('')`) or remount
the form with a new React `key` (`<Form key={saved} …>`, `setSaved((n) => n + 1)`).

## TextField

| Prop | Type | Notes |
|---|---|---|
| `name` **required** | `string` | Key in `Form` values |
| `label` **required** | `string` | |
| `value` | `string` | Controlled value; omit for an uncontrolled field (it is not cleared on submit, see `Form`) |
| `placeholder` | `string` | |
| `multiline` | `boolean` | |
| `secure` | `boolean` | Password entry |
| `required` | `boolean` | |
| `error` | `string` | Validation message under the field |
| `onChange` | `({ value }) => void` | `value: string` |
| `maxLength` | `number` | 1–100000 (SDK 1.5): the host stops input at this many characters and shows an "n/max" counter under the field. Counted in Unicode code points (`[...value].length`), so an emoji is one |

## Select

The platform's own picker.

| Prop | Type | Notes |
|---|---|---|
| `name` **required** | `string` | |
| `label` **required** | `string` | |
| `options` **required** | `{ value: string; label: string }[]` | |
| `value` | `string \| null` | Selected option value; `null` = none |
| `placeholder` | `string` | |
| `onChange` | `({ value }) => void` | `value` is the option `value` |

## DatePicker

The platform's own date (or date and time) picker.

| Prop | Type | Notes |
|---|---|---|
| `name` **required** | `string` | |
| `label` **required** | `string` | |
| `value` | `string \| null` | ISO date `YYYY-MM-DD` or ISO date-time |
| `mode` | `'date' \| 'datetime'` | |
| `onChange` | `({ value }) => void` | ISO string |

## Button

| Prop | Type | Notes |
|---|---|---|
| `label` **required** | `string` | Never empty (`ui.button_label_missing`) |
| `onPress` **required** | `() => void` | |
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | |
| `icon` | `IconName` | Shown next to the label |
| `disabled` | `boolean` | |
| `loading` | `boolean` | Also blocks presses |

## Menu

An anchored menu button: UIMenu on iOS, PopupMenu on Android, the Olan menu on web.

| Prop | Type | Notes |
|---|---|---|
| `label` | `string` | Button text. `label` or `icon` is required; prefer a label |
| `icon` | `IconName` | |
| `items` **required** | `{ key: Key; label: string; icon?: IconName; destructive?: boolean; disabled?: boolean }[]` | |
| `onSelect` **required** | `({ key }) => void` | Chosen item |

```tsx
<Menu
  label="Durumu değiştir"
  items={[{ key: 'in-process', label: 'Sürüyor' }, { key: 'completed', label: 'Tamamlandı' }, { key: 'cancelled', label: 'İptal', destructive: true }]}
  onSelect={({ key }) => setStatus(String(key) as ProjectTaskStatus)}
/>
```

For a menu opened from code (not anchored to a button) use `olan.ui.menu` (api.md).

## SDK 1.5 components

The components below need `"sdk": "^1.5.0"` and an Olan server that knows them (an older one
reports `tree.unknown_type`). They take no children and are **not allowed in chat cards**
(`card.component_not_allowed`). Numbers are formatted by the host with the person's locale
(`Intl.NumberFormat`); `percent` always takes a fraction (`0.034` → "%3,4" in Turkish).

## Tabs

A controlled segmented control: UISegmentedControl on iOS, Material segmented buttons on Android
(a scrolling tab bar above 5 tabs), the Olan segmented control on web. Render the selected content
yourself.

| Prop | Type | Notes |
|---|---|---|
| `items` **required** | `{ key: Key; label: string; badge?: string \| number; disabled?: boolean }[]` | 2–8 tabs; `label` ≤ 40, never empty (`a11y.tab_label_missing`); `badge` ≤ 16 characters or a count |
| `value` **required** | `Key` | The selected `key` |
| `label` | `string` | The tab group's accessible name for screen readers, not shown; ≤ 40, default "Bölümler". Leave it out rather than passing an empty string (`a11y.tab_label_missing`) |
| `onChange` **required** | `({ key }) => void` | |

```tsx
const [tab, setTab] = useState('media');
<Tabs value={tab} label="Medya bölümleri" onChange={({ key }) => setTab(String(key))}
  items={[{ key: 'media', label: 'Medya', badge: processing }, { key: 'upload', label: 'Yükle' }, { key: 'stats', label: 'Analiz' }]} />
{tab === 'media' ? <MediaList /> : tab === 'upload' ? <UploadForm /> : <Stats />}
```

## Switch

The platform's on/off switch (UISwitch, Material switch).

| Prop | Type | Notes |
|---|---|---|
| `label` **required** | `string` | Never empty (`a11y.field_label_missing`) |
| `value` **required** | `boolean` | |
| `description` | `string` | A second line under the label |
| `disabled` | `boolean` | |
| `onChange` | `({ value }) => void` | `value: boolean`, the new state |

Not a `Form` field: its value is not in `onSubmit`'s `values` (still `Record<string, string>`);
keep it in state with `onChange`.

## MultiSelect

Several values from a list: a checkmarked native menu on iOS (it stays open while the person
ticks), a multi-choice dialog on Android, the Olan menu on web. The trigger shows how many are
selected.

| Prop | Type | Notes |
|---|---|---|
| `label` **required** | `string` | Never empty (`a11y.field_label_missing`) |
| `value` **required** | `string[]` | The selected option values |
| `options` **required** | `{ value: string; label: string }[]` | ≤ 200 |
| `placeholder` | `string` | Shown when nothing is selected |
| `max` | `number` | Most values the person may select |
| `disabled` | `boolean` | |
| `onChange` | `({ value }) => void` | `value: string[]`, the new selection |

Not a `Form` field either: keep its value with `onChange`.

```tsx
<MultiSelect label="Kanallar" value={channels} onChange={({ value }) => setChannels(value)} max={3}
  options={[{ value: 'instagram', label: 'Instagram' }, { value: 'tiktok', label: 'TikTok' }, { value: 'linkedin', label: 'LinkedIn' }]} />
```

## Stat

One key figure (a KPI tile).

| Prop | Type | Notes |
|---|---|---|
| `label` **required** | `string` | |
| `value` **required** | `number \| string \| null` | A number is formatted by `format`; a string shows as it is; `null` shows "—" |
| `format` | `'number' \| 'currency' \| 'percent'` | Default `number` |
| `currency` | `string` | ISO 4217 (`'TRY'`); required with `format: 'currency'` (`tree.invalid_prop`) |
| `delta` | `number` | Relative change as a fraction, shown as a signed percent (`0.124` → "+%12,4") |
| `deltaGood` | `'up' \| 'down'` | Which direction is good (green); default `up`, `down` for costs such as CPC |
| `caption` | `string` | A short line, e.g. "Son 30 gün" |

```tsx
<Stack direction="horizontal" gap="md" wrap>
  <Stat label="Harcama" value={1250.5} format="currency" currency="TRY" delta={0.08} caption="Son 7 gün" />
  <Stat label="Tıklama oranı" value={0.034} format="percent" delta={-0.012} />
  <Stat label="Tıklama başı maliyet" value={2.4} format="currency" currency="TRY" delta={-0.05} deltaGood="down" />
</Stack>
```

## Banner

A message across the screen: a connection that expired, an error to act on, a success.

| Prop | Type | Notes |
|---|---|---|
| `tone` **required** | `'info' \| 'success' \| 'warning' \| 'danger'` | |
| `text` **required** | `string` | |
| `title` | `string` | |
| `action` | `{ label: string; onPress: () => void }` | One button; `label` never empty (`a11y.action_label_missing`) |
| `onDismiss` | `() => void` | Shows a close button; remove the banner in the handler |

```tsx
{error ? <Banner tone="danger" title="Sunucuya ulaşılamıyor" text={error.message} action={{ label: 'Tekrar dene', onPress: () => items.refetch() }} /> : null}
```

## Image

An image from the app's own server.

| Prop | Type | Notes |
|---|---|---|
| `src` **required** | `string` | `https:` URL ≤ 2048 (`http:` only to local addresses in development) |
| `alt` **required** | `string` | What it shows, read by screen readers; `""` only for decoration (`validate --strict` warns `a11y.image_alt_missing`) |
| `aspectRatio` | `number` | Width / height, 0.1–10; default 16/9 |
| `fit` | `'cover' \| 'contain'` | Default `cover` |
| `poster` | `string` | A still shown while `src` loads or when it fails; same URL rule |

Origin rule (the host enforces it): `src` and `poster` must be on the origin of the manifest
`remote.url` (or the installation's override) or on a host granted as `http:<host>`. Any other
image is drawn as a neutral placeholder and logged as a warning; it is not an error. Serve images
from your app server (or a CDN host you list as `http:<host>`); signed, expiring URLs work.

```tsx
<Image src={item.thumbnailUrl} alt={item.title} aspectRatio={1} fit="cover" poster={item.posterUrl} />
```

## Avatar

| Prop | Type | Notes |
|---|---|---|
| `name` **required** | `string` | The person's or brand's name: read aloud and used for the initials. Never empty (`a11y.avatar_name_missing`) |
| `src` | `string` | Picture, with the `Image` origin rule; initials when missing or broken |
| `size` | `'sm' \| 'md' \| 'lg'` | |

## ProgressBar

| Prop | Type | Notes |
|---|---|---|
| `value` | `number` | 0–1; leave it out for an indeterminate bar (the platform's activity indicator) |
| `label` | `string` | E.g. "Yükleniyor…" |
| `tone` | `'default' \| 'success' \| 'warning' \| 'danger'` | |

Keep the percentage out of `label`: the bar already shows `value` itself.

```tsx
<ProgressBar value={progress} label="Yükleniyor…" />
<Button label="İptal" variant="ghost" onPress={() => task.cancel()} />
```

## Accessibility checks

`validate --strict` and the marketplace lint the rendered tree (`lintUiTree`, errors.md): a
`Button`, field (`TextField`, `Select`, `DatePicker`, `Switch`, `MultiSelect`), `Menu` item, action
or `Banner` action without a label, a `Tabs` item without a label (`a11y.tab_label_missing`) and
an `Avatar` without a name (`a11y.avatar_name_missing`) are errors; an icon-only `Menu` and an
`Image` with an empty `alt` are warnings.

## Exported prop types

`ScreenProps`, `StackProps`, `CardProps`, `TextProps`, `BadgeProps`, `EmptyStateProps`, `ListProps`,
`ListItem`, `TableProps`, `TableColumn`, `TableRow`, `ChartProps`, `ChartSeries`, `FormProps`,
`TextFieldProps`, `SelectProps`, `SelectOption`, `DatePickerProps`, `ButtonProps`, `MenuProps`,
`MenuItem`, `TabsProps`, `TabItem`, `SwitchProps`, `MultiSelectProps`, `StatProps`, `BannerProps`,
`ImageProps`, `AvatarProps`, `ProgressBarProps`, `ValueFormat`, `Action`, `BadgeData`, `Key`,
`Tone`, `Spacing`, `IconName`, `TextChildren`.

## Icons

`icon` props take an Olan icon name. Unknown names fall back to a generic icon. Names:

`mail chat meetings calendar projects marketing contacts files settings inbox all-inboxes archive
delete report-spam reply reply-all forward compose edit draw mark-unread mark-read flag folder
search attachment send send-arrow add minus close clear check check-double check-circle checkbox
more back chevron-right chevron-down chevron-up chevron-up-down list day-view refresh copy paste
share document document-text photo photo-library camera camera-flip video-play gif emoji poll mic
mic-off video video-off call call-end screen-share speaker waveform play pause stop group account
lock block sidebar person-add link record signal approval compare clock warning status-open
status-active touch face-id fingerprint qr-scan help info pin list-checks seal-check warning-circle
undo favorite bell bell-slash timer sign-out crop rotate sticker download tag snooze print`

<!-- docs/api.md -->
# `olan.*` API

```ts
import { olan, OlanError, RemoteError, isRemoteError } from '@olan-app/sdk';
```

Every call is asynchronous: the sandbox sends it to Olan, Olan checks the permission and answers.
A failed call rejects with an `OlanError` whose `code` is one of `permission_denied`,
`not_installed`, `invalid_params`, `unknown_method`, `host_error`, `http_blocked`, `cancelled`,
`validation_failed`, `conflict`, `not_found`, `forbidden_record`, `quota_exceeded`, `project_not_enabled`
(SDK 1.6: the call names a project the app was not added to); `olan.remote.request`
rejects with a `RemoteError` (`remote_rejected`, `remote_unavailable`, `consent_required`, `rate_limited`, …),
uploads also with `upload_failed` (errors.md). Call `olan.*` from event handlers, effects or `useQuery` — not during render.

| Call | Returns | Permission |
|---|---|---|
| `olan.projects.list({ limit?, cursor? })` | `{ items: Project[]; nextCursor?: string }` (projects the app is enabled in) | `projects:read` |
| `olan.projects.get(projectId)` | `ProjectDetail` | `projects:read` |
| `olan.projects.tasks(projectId, { status? })` | `ProjectTask[]` | `projects:read` |
| `olan.projects.updateTask(projectId, taskId, { status?, due?, assigneeId?, revision })` | `ProjectTask` | `tasks:write` (or the older `projects:write`) |
| `olan.projects.createTask(projectId, { title, listId?, description?, status?, due?, allDay?, assigneeId?, priority? })` | `ProjectTask` | `tasks:write` |
| `olan.projects.deleteTask(projectId, taskId, { revision })` | `void` | `tasks:delete` |
| `olan.projects.deleteList(projectId, listId, { revision })` | `void` | `projects:delete` |
| `olan.users.get(ids)` | `DirectoryUser[]` | `users:read` |
| `olan.chat.conversations()` | `Conversation[]` | `chat:read` |
| `olan.chat.messages(conversationId, { limit? })` | `Message[]` | `chat:read` |
| `olan.storage.get<T>(key)` | `T \| null` | `storage` |
| `olan.storage.set(key, value)` | `void` | `storage` |
| `olan.storage.remove(key)` | `void` | `storage` |
| `olan.storage.keys()` | `string[]` | `storage` |
| `olan.db.collection<T>(name)` → `insert(data)`, `get(id)`, `query({ where?, orderBy?, limit?, cursor? })`, `update(id, patch, { revision })`, `delete(id, { revision? })`, `count(where?)` | `DbRow<T>`, `DbRow<T> \| null`, `{ rows, nextCursor }`, `DbRow<T>`, `void`, `number` | `db` (database.md) |
| `olan.settings.get()` | `Record<string, JsonValue>` | none |
| `olan.project.config.get(projectId)` | `ProjectConfig` (SDK 1.6) | none; the app is enabled in the project |
| `olan.project.config.set(projectId, value, { revision? })` | `ProjectConfig` | none; members who may change the project |
| `olan.project.statuses.list(projectId)` | `ProjectStatus[]` (SDK 1.7) | `projects:read` |
| `olan.project.statuses.define(projectId, statuses)` | the app's `ProjectStatus[]` | `projects:extend` |
| `olan.project.statuses.remove(projectId, key, { replacementKey? })` | `{ movedTasks }` | `projects:extend` |
| `olan.project.labels.list(projectId)` | `ProjectLabel[]` | `projects:read` |
| `olan.project.labels.define(projectId, labels)` | the app's `ProjectLabel[]` | `projects:extend` |
| `olan.project.labels.remove(projectId, key)` | `void` | `projects:extend` |
| `olan.project.fields.list(projectId)` | `ProjectField[]` (SDK 1.8) | `projects:read` |
| `olan.project.fields.define(projectId, fields)` | the app's `ProjectField[]` | `projects:extend` |
| `olan.project.fields.remove(projectId, key)` | `void` | `projects:extend` |
| `olan.project.fields.values(projectId, target)` | `{ target, values }` | `projects:read` |
| `olan.project.fields.setValues(projectId, target, values)` | `{ target, values }` | `tasks:write` |
| `olan.project.links.list(projectId, target?)` | `RecordLink[]` | `projects:read` |
| `olan.project.links.upsert(projectId, { target, externalId, card })` | `RecordLink` | `tasks:write` |
| `olan.project.links.remove(projectId, linkId)` | `void` | `tasks:write` |
| `olan.project.links.setStatus(projectId, linkId, input)` | `{ target, status?, statusId?, statusKey?, state? }` | `tasks:write` (or `projects:write`) |
| `olan.project.calendar.list(projectId, { from?, to? })` | `ProjectCalendarItem[]` | `projects:read` |
| `olan.project.calendar.upsert(projectId, item)` | `ProjectCalendarItem` | `projects:extend` |
| `olan.project.calendar.remove(projectId, externalId)` | `void` | `projects:extend` |
| `olan.project.activity.post(projectId, text, { target? })` | `void` | `projects:extend` |
| `olan.project.approvals.list(projectId, { state? })` | `ProjectApproval[]` | `projects:read` |
| `olan.project.approvals.request(projectId, input)` | `ProjectApproval` | `projects:extend` |
| `olan.project.approvals.cancel(projectId, approvalId)` | `ProjectApproval` | `projects:extend` |
| `olan.http.fetch(url, { method?, headers?, body? })` | `HttpResponse` | `http:<host of url>` |
| `olan.ui.confirm({ title, message?, confirmLabel?, cancelLabel?, destructive? })` | `boolean` | none |
| `olan.ui.prompt({ title, message?, placeholder?, defaultValue? })` | `string \| null` | none |
| `olan.ui.toast({ text, tone? })` | `void` | none |
| `olan.ui.menu({ items })` | chosen `key` or `null` | none |
| `olan.ui.datePicker({ value?, mode? })` | ISO string or `null` | none |
| `olan.ui.share({ text, url? })` | `void` | none |
| `olan.navigation.push(screen, params?)` | `void` | none |
| `olan.navigation.pop()` | `void` | none |
| `olan.navigation.replace(screen, params?)` | `void` | none |
| `olan.projects.create({ title, description? })` | `Project` | `projects:create` |
| `olan.projects.archive(projectId)` | `void` | `projects:archive` |
| `olan.chat.postCard({ conversationId, card, threadRootId? })` | `{ messageId }` | `chat:write` |
| `olan.chat.updateCard(messageId, card)` | `{ messageId }` | `chat:write` |
| `olan.calendar.calendars()` | `Calendar[]` | `calendar:read` |
| `olan.calendar.events({ from, to, calendarId?, limit? })` | `CalendarEvent[]` | `calendar:read` |
| `olan.calendar.createEvent({ title, start, end?, duration?, calendarId?, timeZone?, isAllDay?, location?, description? })` | `CalendarEvent` | `calendar:write` |
| `olan.calendar.updateEvent(eventId, patch)` | `CalendarEvent` | `calendar:write` |
| `olan.calendar.deleteEvent(eventId)` | `void` | `calendar:delete` |
| `olan.contacts.addressBooks()` | `AddressBook[]` | `contacts:read` |
| `olan.contacts.search(query, { limit? })` | `Contact[]` | `contacts:read` |
| `olan.contacts.create({ name, addressBookId?, emails?, phones?, organization?, title?, note? })` | `Contact` | `contacts:write` |
| `olan.contacts.update(contactId, patch)` | `Contact` | `contacts:write` |
| `olan.contacts.delete(contactId)` | `void` | `contacts:delete` |
| `olan.mail.getMessage(messageId)` | `MailMessage` | `mail:read` (only the email the surface was opened on) |
| `olan.meetings.get(meetingId)` | `Meeting` | `meetings:read` |
| `olan.backend.call<T>(name, args?)` | `T` (the function's JSON result) | none; the manifest declares `server` (backend.md) |
| `olan.remote.request({ method, path, query?, headers?, body?, timeoutMs? })` | `{ status, headers, body }` | none (implied `remote`); the manifest declares `remote.requests` (remote-requests.md) |
| `olan.files.pick({ accept?, multiple?, maxFiles?, maxBytes? })` | `FileHandle[]` | `files:pick` (files.md) |
| `olan.files.upload(file, { url, method?, headers?, formField?, fields?, onProgress? })` | `UploadTask`: a promise of `{ status, headers, body }` with `uploadId` and `cancel()` | `files:pick` |
| `olan.files.cancel(uploadId)` | `void` | `files:pick` |
| `olan.ui.openUrl(url)` | `void` | none (links.md) |
| `olan.ui.openExternal(url, { expectReturn? })` | `{ returned: true, params } \| { returned: false }` | none (links.md) |

## olan.projects

**Enabled projects (SDK 1.6, Olan Apps phase 6).** A project stays generic until a member adds an
app to it (project page → Uygulamalar). On the person's behalf an installed app reaches only those
projects: `list` leaves the others out, and every call naming one fails with `project_not_enabled`.
The project surfaces (`project.widget`, `project.tab`, `project.settings`) show only there too.
Projects the app creates (`projects.create`) have it enabled. Studio previews without an
installation keep the person's own reach.

```ts
const { items, nextCursor } = await olan.projects.list({ limit: 50 });     // limit default 50
const detail = await olan.projects.get('p0');                              // { project, members, lists, tasks }
const open = await olan.projects.tasks('p0', { status: 'needs-action' });
const updated = await olan.projects.updateTask('p0', task.id, { status: 'completed', revision: task.revision });
const created = await olan.projects.createTask('p0', { title: 'Follow up', due: '2026-10-20' });
await olan.projects.deleteTask('p0', created.id, { revision: created.revision });
await olan.projects.deleteList('p0', list.id, { revision: list.revision });   // empty, non-default work packages only
```

- Pass `cursor: nextCursor` to get the next page; `nextCursor` is absent on the last page.
- `updateTask` needs the task's current `revision` (optimistic concurrency). If the task changed in
  the meantime the call fails with `conflict` (`invalid_params` on Olan servers before 1b); reload
  the task and retry. The result is the updated task (with a new `revision`). Only `status`, `due`
  (ISO date or `null`) and `assigneeId` (user id or `null`) can be changed. New apps request
  `tasks:write`; `projects:write` keeps working for `updateTask` only.
- `createTask` puts the task in `listId`, or else in the project's default work package
  (`lists[].isDefault`). The task's `createdByApp` is your app id. Needs `tasks:write`.
- `deleteTask` needs the task's current `revision` and `tasks:delete`. Every deletion is written
  to the organization's audit log. Tasks with a delivery/approval workflow, and (when the admin
  turned on "only records the app created") tasks the app did not create, fail with
  `forbidden_record`.
- `deleteList` removes (archives) an **empty** work package: no live tasks or sub-packages. The
  project's default work package is never removed. Both fail with `forbidden_record`. Needs
  `projects:delete`. Apps cannot change or delete projects, nor create work packages; creating
  and archiving projects is `projects.create` / `projects.archive` (below).
- Protected records: projects, the default work package, task statuses and fields (fixed by
  Olan), project chats and calendars, members, accounts. Show a toast such as "Bu kayıt korunuyor"
  on `forbidden_record`.

Types (all exported from `@olan-app/sdk`):

```ts
type ProjectTaskStatus = 'needs-action' | 'in-process' | 'completed' | 'cancelled';

interface Project {
  id: string; name: string; description: string; timeZone: string; archived: boolean;
  revision: number; role: ProjectRole; createdAt: string; updatedAt: string;
  lastActivityAt?: string; taskKeyPrefix?: string;
}
interface ProjectTask {
  id: string; projectId: string; listId: string; key?: string; number?: number;
  title: string; description: string; status: ProjectTaskStatus; assigneeId: string | null;
  createdBy: string; start?: string | null; due: string | null; allDay: boolean;
  revision: number; updatedAt?: string;
  createdByApp?: string | null;      // app id when an app created it
}
interface ProjectDetail { project: Project; members: ProjectMember[]; lists: ProjectTaskList[]; tasks: ProjectTask[] }
interface ProjectMember { userId: string; displayName: string; role: ProjectRole }
interface ProjectTaskList { id: string; name: string; isDefault: boolean; revision: number; parentId: string | null }
type ProjectRole = 'owner' | 'manager' | 'member' | 'guest' | string;
interface UpdateTaskInput { status?: ProjectTaskStatus; due?: string | null; assigneeId?: string | null; revision: number }
interface CreateTaskInput { title: string; listId?: string; description?: string; status?: ProjectTaskStatus; due?: string | null; allDay?: boolean; assigneeId?: string | null; priority?: number }
```

`due` is an ISO date (`2026-10-16`) or date-time, or `null`. Compare dates as strings of the same
length (`task.due.slice(0, 10) < today`) or with `Date`.

## olan.project.config

The app's own configuration of one project (SDK 1.6), kept per installation and project: which
brand, account or pipeline the project uses, the app's choices for it. No permission is needed; the
app must be enabled in the project (else `project_not_enabled`). Any member reads it; members who
may change the project set it (read-only members get `permission_denied`, archived projects
`conflict`). The value is a JSON object of at most 64 KiB (`payload_too_large`).

```ts
const config = await olan.project.config.get(projectId);
// { projectId, value: { brandId: 'b1' }, revision: 3, updatedBy: '<user id>', updatedAt: '2026-10-22T09:00:00Z' }
// Before the first set: { value: {}, revision: 0, updatedBy: null, updatedAt: null }
await olan.project.config.set(projectId, { ...config.value, brandId: 'b2' }, { revision: config.revision });
```

- `set` replaces the whole value. With `{ revision }` it is refused with `conflict` when someone
  changed it meanwhile (`revision: 0`: only if nothing is stored yet); without it the write wins.
- The configuration stays when the app is removed from the project, and answers again once a member
  adds it back. It goes with the installation (uninstall) or the project.
- The app's server reads and writes it too: `GET`/`PUT /api/v2/apps/installations/:id/projects/:projectId/config`
  with the app's own token (server.md), and backend code with the same `olan.project.config`.
- In React, `useProjectConfig(projectId?)` (hooks.md) loads it and saves on the loaded revision.

```ts
interface ProjectConfig {
  projectId: string;
  value: Record<string, JsonValue>;
  revision: number;                 // 0 until the first set
  updatedBy: string | null;         // a user id, or 'app:<installationId>' (the app's server)
  updatedAt: string | null;
}
```

## olan.project: records, statuses, calendar, feed, approvals

SDK 1.7 (Olan Apps phase 6): what the app adds to the projects it is enabled in — the same calls in
the UI and in backend code; the app's server uses the routes under
`/api/v2/apps/installations/:id/projects/:projectId/` (`links`, `statuses`, `labels`, `fields`,
`field-values`, `calendar`, `activity`, `approvals`) with its own token. Projects without the app fail with
`project_not_enabled`; archived projects refuse changes with `conflict`.

**Record links.** One of the app's records (`externalId`, the app's own id) attached to a task or an
issue, with a card the app draws on it. The card is a chat card (cards.md) whose buttons only
`{ kind: 'open', payload? }`: they open the app's `record.card` surface (surfaces.md). Any other
button fails with `validation_failed` (`invalid_card`). The same `externalId` on the same target
replaces the card; an app links at most 10 records to one task or issue (`quota_exceeded`).

```ts
const link = await olan.project.links.upsert(projectId, {
  target: { kind: 'task', id: task.id },
  externalId: 'SAT-12',
  card: { version: 1, root: 1, fallbackText: 'SAT-12 · Toplantı masası', nodes: [
    { id: 1, type: 'Card', props: { title: 'Toplantı masası', subtitle: 'SAT-12' }, children: [2] },
    { id: 2, type: 'Button', props: { label: 'Kaydı aç', action: { kind: 'open', payload: { id: 'SAT-12' } } }, children: [] },
  ] },
});
await olan.project.links.setStatus(projectId, link.id, { statusKey: 'awaiting-approval' }); // a task
await olan.project.links.setStatus(projectId, issueLink.id, { state: 'closed', stateReason: 'completed' }); // an issue
const onTask = await olan.project.links.list(projectId, { kind: 'task', id: task.id });
```

`setStatus` moves a linked task by `statusKey` (a key of the project's statuses: the defaults
`todo`, `in_progress`, `done`, `cancelled` or one the app defined), `statusId`, or the CalDAV
`status` (its first status of that kind); a linked issue opens or closes with `state`. The change is
an ordinary edit of the person the app acts for: the project feed shows it under the app and other
apps hear `project.task.updated` / `project.task.completed`. Members may take a link off
(the card disappears); a link of an app removed from the project stays read-only.

**Statuses and labels.** The app defines its own by stable keys (`^[a-z0-9][a-z0-9._-]{0,62}$`,
≤ 20 per call); `define` adds or updates and returns all of the app's. Members put them on tasks
but cannot rename, recolour or remove them. A key or a name the project already uses is `conflict`;
a status keeps its category. Removing a status moves its tasks to `replacementKey` (a status of the
same kind) or the first status of its kind; the last status of a required kind cannot go (`conflict`).

```ts
await olan.project.statuses.define(projectId, [{ key: 'awaiting-approval', name: 'Onay bekliyor', category: 'started' }]);
await olan.project.labels.define(projectId, [{ key: 'hardware', name: 'Donanım', groupName: 'Tür' }]);
```

**Custom fields** (needs `"sdk": "^1.8.0"`). The project's own fields and the app's, defined by stable keys like
statuses (≤ 20 per call, ≤ 50 fields per project); `define` returns all of the app's. Members fill them in on tasks
and issues (`appliesTo`, default tasks) but cannot change or remove them; a taken key or name is `conflict`, the
`type` is fixed (`invalid_params`). Options keep their `id` (a new one gets a slug of its name); removing an option
or the field clears its values. Values are keyed by field key (the project's own fields: by id): text, url, date
(`YYYY-MM-DD`), select option id and person (a member's user id) are strings, then numbers, `boolean` checkboxes and
lists of option ids. `setValues` changes the fields it names; `null` clears one (not a `required` one:
`invalid_params`); an app's field removed with its app from the project is read-only (`conflict`).

```ts
await olan.project.fields.define(projectId, [{ key: 'channel', name: 'Kanal', type: 'select', options: [{ id: 'ig', name: 'Instagram' }], showOnCard: true }]);
await olan.project.fields.setValues(projectId, { kind: 'task', id: task.id }, { channel: 'ig' });
const { values } = await olan.project.fields.values(projectId, { kind: 'task', id: task.id });   // { channel: 'ig', … }
```

**Calendar layer and feed lines.** Calendar items (one per `externalId`, ≤ 500 per project; all-day
items take dates) show in the project calendar while the app is enabled in the project; `linkId`
makes the item open its record. `list` takes a range of at most 366 days. `activity.post` writes a
line (1–280 characters) in the project feed under the app, optionally about a task or issue.

```ts
await olan.project.calendar.upsert(projectId, { externalId: 'SAT-12', title: 'Teslim: Toplantı masası', start: '2026-11-05', allDay: true, linkId: link.id });
await olan.project.activity.post(projectId, 'SAT-12 bağlandı, onay bekliyor', { target: { kind: 'task', id: task.id } });
```

**Approvals.** `request` asks 1–10 project members who may change the project; they find it in
their approval box (with the record card, if given). `mode: 'all'` (default): every approver
approves, one rejection rejects; `'any'`: the first decision decides. The app hears the outcome as
`project.approval.decided` (server.md#events) and can `cancel` a pending request (`conflict` once
decided).

```ts
const approval = await olan.project.approvals.request(projectId, { title: 'SAT-12 onayı', approverIds: [managerId], mode: 'any', linkId: link.id, card: link.card });
const pending = await olan.project.approvals.list(projectId, { state: 'pending' });   // newest first
```

```ts
type ProjectStatusCategory = 'backlog' | 'unstarted' | 'started' | 'completed' | 'cancelled';
interface ProjectStatus { id: string; projectId: string; name: string; color: string; category: ProjectStatusCategory; position: number; key: string | null; createdByApp: string | null; appInstallationId: string | null; revision: number }
interface ProjectLabel { id: string; projectId: string; name: string; color: string; groupName: string | null; description: string; position: number; key: string | null; createdByApp: string | null; appInstallationId: string | null; revision: number }
type ProjectFieldType = 'text' | 'number' | 'date' | 'select' | 'multi_select' | 'person' | 'url' | 'checkbox';
type ProjectFieldValue = string | number | boolean | string[];
interface ProjectField { id: string; projectId: string; name: string; description: string; type: ProjectFieldType; position: number; options: { id: string; name: string; color: string }[]; required: boolean; appliesTo: ('task' | 'issue')[]; showOnCard: boolean; key: string | null; createdByApp: string | null; appInstallationId: string | null; appName?: string | null; readOnly?: boolean; revision: number }
interface ProjectFieldDefinition { key: string; name: string; type: ProjectFieldType; description?: string; options?: { id?: string; name: string; color?: string }[]; required?: boolean; appliesTo?: ('task' | 'issue')[]; showOnCard?: boolean; position?: number }
interface ProjectFieldValues { target: RecordTarget; values: Record<string, ProjectFieldValue> }
type RecordTarget = { kind: 'task' | 'issue'; id: string };
// RecordLink, ProjectCalendarItem and ProjectApproval also carry the app: installationId, appId, name, active.
interface RecordLink { id: string; projectId: string; target: RecordTarget; externalId: string; title: string; card: AppCard; createdBy: string | null; updatedBy: string | null; revision: number; createdAt: string; updatedAt: string }
interface ProjectCalendarItem { id: string; projectId: string; externalId: string; title: string; start: string; end: string; allDay: boolean; color: string | null; linkId: string | null; target: RecordTarget | null; updatedAt: string }
interface ProjectApproval { id: string; projectId: string; projectName: string; externalId: string | null; linkId: string | null; target: RecordTarget | null; title: string; card: AppCard | null; approvers: string[]; mode: 'all' | 'any'; state: 'pending' | 'approved' | 'rejected' | 'cancelled'; dueAt: string | null; requestedBy: string | null; decisions: { userId: string; decision: 'approve' | 'reject'; note: string; decidedAt: string }[]; createdAt: string; decidedAt: string | null }
```

## olan.users

```ts
const people = await olan.users.get([task.assigneeId, row.createdBy]);   // DirectoryUser[]
```

`DirectoryUser`: `{ id, displayName, email, title?, department?, team?, avatarUrl? }`. Ids are the
central Olan user ids (`useUser().id`, `createdBy`, `assigneeId`, `member.userId`). Unknown ids and
people outside the organization are left out; duplicates are asked once and lists over 100 are
split into several calls. The current user's id needs no permission (`useUser()`); their name
does. `users:read` is all it needs: no other permission is required alongside it. In components
use `useUsers(ids)` (hooks.md).

There is **no lookup by email or name** (no directory search). To relate an email address (e.g. a
`mail.sidebar` sender) to Olan people or tasks, collect the ids you already have (`member.userId`
of `olan.projects.get`, `task.assigneeId`, `createdBy`), call `olan.users.get(ids)` and compare
`user.email.toLowerCase()` with the address; for people outside the organization use
`olan.contacts.search(email)`.

## olan.chat

```ts
const conversations = await olan.chat.conversations();
const messages = await olan.chat.messages(conversations[0].id, { limit: 20 }); // the latest messages (limit default 50)
```

```ts
interface Conversation { id: string; kind: 'direct' | 'group'; title: string | null; projectId?: string | null; createdAt: string; updatedAt: string; unreadCount?: number }
interface Message { id: string; conversationId: string; sender: { id: string; displayName: string }; body: string | null; replyToId: string | null; createdAt: string; editedAt: string | null; deletedAt: string | null }
```

Apps cannot send messages. With `chat:write` they post **cards** as the app:
`olan.chat.postCard({ conversationId, card })` and `olan.chat.updateCard(messageId, card)` (cards.md).

## olan.projects.create / archive

```ts
const project = await olan.projects.create({ title: 'Standup', description: 'Günlük' });   // projects:create
await olan.projects.archive(project.id);                                                  // projects:archive
```

`create` opens the project with its own chat, calendar and default work package, on behalf of the
person; `project.createdByApp` is your app id. `archive` removes (archives) only projects your app
created (others: `forbidden_record`, reason `not_created_by_app`); an archived one answers `conflict`.

## olan.calendar

```ts
const calendars = await olan.calendar.calendars();     // [{ id, name, color, isDefault, mayWrite }]
const events = await olan.calendar.events({ from: '2026-10-19', to: '2026-10-26' });   // ≤ 366 days, limit ≤ 200
const event = await olan.calendar.createEvent({ title: 'Standup notu', start: '2026-10-20T09:00:00+03:00', duration: 'PT15M' });
await olan.calendar.updateEvent(event.id, { location: 'Toplantı odası' });
await olan.calendar.deleteEvent(event.id);
```

```ts
interface CalendarEvent { id: string; calendarId: string; uid: string; title: string; start: string; end: string; timeZone: string | null; isAllDay: boolean; location: string | null; description: string | null; isOrganizer: boolean; createdByApp: string | null; updatedAt: string | null }
```

- Without `calendarId` the default calendar is used (else the first writable one). Pass `end` or an
  ISO 8601 `duration`; neither means one hour (one day for all-day events).
- Apps never send invitations: there is no `participants`.
- `updateEvent` / `deleteEvent` fail with `forbidden_record` for Olan meetings (UID `…@olan.app`) and
  project calendar events (`system_record`), invitations (`not_organizer`), read-only calendars
  (`permission_denied`) and, when the admin requires it, events the app did not create
  (`not_created_by_app`). Calendars themselves cannot be created or deleted. Deletions are audited.

## olan.contacts

```ts
const books = await olan.contacts.addressBooks();        // [{ id, name, isDefault, shared }]
const found = await olan.contacts.search('ayşe');        // name, email or organization; limit ≤ 50
const contact = await olan.contacts.create({ name: 'Ayşe Yılmaz', emails: ['ayse@example.com'] });
await olan.contacts.update(contact.id, { phones: ['+90 555 000 0000'] });
await olan.contacts.delete(contact.id);
```

`Contact`: `{ id, addressBookId, name, emails, phones, organization, title, note, createdByApp, updatedAt }`.
Contacts in shared or directory address books are read-only (`forbidden_record`, `system_record`);
address books cannot be created or deleted.

## olan.mail and olan.meetings

```ts
const { messageId } = useSurfaceParams<'mail.sidebar'>();
const message = await olan.mail.getMessage(messageId);   // { id, subject, from, to, cc, receivedAt, textBody, attachments: [{ name, type, size }] }
const meeting = await olan.meetings.get(meetingId);      // { id, slug, title, startsAt, endsAt, status, organizerId, participants: [{ userId?, displayName, role }] }
```

`mail.getMessage` reads only the email a `mail.sidebar` / `mail.action` surface was opened on (other
ids: `permission_denied`); Olan reads it with the person's own mail session. There is no other
mail access.

## olan.storage

Private key–value storage per app installation **and** user. Values are JSON (≤ 64 KiB each, at
most 1000 keys).

```ts
const favorites = (await olan.storage.get<string[]>('favorites')) ?? [];
await olan.storage.set('favorites', [...favorites, id]);
await olan.storage.remove('favorites');
const keys = await olan.storage.keys();
```

`get` returns `null` for a missing key.

## olan.db

The app's own database: collections declared in the manifest's `data`, rows with revisions,
indexed queries and cursors. Needs `db`. Everything about it is in database.md.

```ts
const decisions = olan.db.collection<{ title: string; status?: 'open' | 'done' }>('decisions');
const row = await decisions.insert({ title: 'Ship 1.1', status: 'open' });
const { rows, nextCursor } = await decisions.query({ where: { status: 'open' }, orderBy: { field: 'title' }, limit: 20 });
await decisions.update(row.id, { status: 'done' }, { revision: row.revision });
```

## olan.settings

```ts
const settings = await olan.settings.get();   // e.g. { threshold: 3, currency: 'TRY' }
```

The values of the manifest `settings` fields (manifest.md), with defaults applied. Admins (or the
user, for a personal installation) edit them in Olan → Ayarlar → Uygulamalar. Apps cannot write
settings. In components prefer `useSettings()` (hooks.md), which re-renders when they change.

## olan.http

The sandbox has no network. `olan.http.fetch` asks Olan to make the request; Olan only reaches
hosts listed as `http:<host>` permissions (permissions.md).

```ts
const response = await olan.http.fetch('https://api.example.com/v1/rates?base=USD', {
  method: 'GET',                         // 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'
  headers: { accept: 'application/json' },
  body: null,                            // string | null; JSON.stringify(...) for JSON bodies
});
if (response.status !== 200) throw new Error(`API answered ${response.status}`);
const data = response.json<{ rates: Record<string, number> }>();
```

`HttpResponse`: `{ status: number; headers: Record<string, string>; body: string; json<T>(): T }`.
`json()` throws `OlanError('invalid_params')` when the body is not JSON. Non-2xx statuses do
**not** reject; check `status`. Redirects are returned, not followed. Request bodies ≤ 512 KiB,
response bodies ≤ 2 MiB (text). Cookies of the user are never sent; put API keys in `headers`
(store them in a `secret` setting). Rejections: `http_blocked` (host not permitted, or a private
address), `host_error`.

## olan.ui

Each call opens the platform's own control and resolves when the user answers.

```ts
if (await olan.ui.confirm({ title: 'Görev silinsin mi?', confirmLabel: 'Sil', destructive: true })) { … }
const name = await olan.ui.prompt({ title: 'Yeni ad', defaultValue: 'Rapor' });   // null = cancelled
await olan.ui.toast({ text: 'Kaydedildi', tone: 'success' });                       // tone: 'default' | 'success' | 'warning' | 'danger'
const key = await olan.ui.menu({ items: [{ key: 'edit', label: 'Düzenle' }, { key: 'delete', label: 'Sil', destructive: true }] }); // null = dismissed
const day = await olan.ui.datePicker({ value: '2026-10-16', mode: 'date' });        // ISO string or null
await olan.ui.share({ text: 'Rapor hazır', url: 'https://example.com/r/1' });
```

`olan.ui.menu` items: `{ key: string; label: string; icon?: IconName; destructive?: boolean; disabled?: boolean }`.
For a menu attached to a button, use the `Menu` component instead.

Links and sign-in flows (SDK 1.5, links.md):

```ts
await olan.ui.openUrl('https://media.example.com/items/7');                      // the platform browser; resolves at once
const flow = await olan.ui.openExternal(authorizeUrl, { expectReturn: true });  // system browser / ASWebAuthenticationSession / Custom Tabs
if (flow.returned) await finishConnection(flow.params);                         // the query of https://<Olan web>/apps/return/<installationId>?…
```

Both take `https:` URLs (`http:` only to local addresses in development). `openExternal` resolves
`{ returned: false }` at once without `expectReturn`, and when the person closes the flow or after
30 minutes; check `params.state` on your server.

## olan.remote

The app's own server, as the person (SDK 1.5; manifest `remote` with `"requests": true`; everything
in remote-requests.md):

```ts
const page = await olan.remote.request({ method: 'GET', path: '/items', query: { status: 'ready' } });
const created = await olan.remote.request({ method: 'POST', path: '/items', body: { title: 'Lansman' }, timeoutMs: 60_000 });
```

The result is `{ status, headers: { 'content-type'?, etag? }, body }` for answers 200–399. Failures
reject with `RemoteError` (`code`, `status`, `details` = the server's body for `remote_rejected` and
`remote_unavailable`, `reason?`, `retryAfterSeconds?`); `isRemoteError(error, 'remote_rejected')`
narrows it. Body ≤ 1 MiB, answer ≤ 4 MiB, timeout 1–60 s (default 30 s), 300 requests a minute.

## olan.files

Pick files with the platform picker and upload them straight to the app's server (SDK 1.5,
`files:pick`; everything in files.md):

```ts
const [file] = await olan.files.pick({ accept: ['image/*', 'video/*'], maxBytes: 300 * 1024 * 1024 });   // [] = cancelled
if (file) {
  const task = olan.files.upload(file, { url: uploadUrl, onProgress: ({ loaded, total }) => setProgress(loaded / total) });
  // task.uploadId; task.cancel() (or olan.files.cancel(task.uploadId)) makes it reject with `cancelled`
  const { status, headers, body } = await task;    // every HTTP status resolves: check `status`
}
```

`url` must be on the origin of `remote.url` or a host granted as `http:<host>` (`http_blocked`
otherwise). PUT (default) sends the raw bytes, POST `multipart/form-data`; both send the name in
`x-olan-file-name`.

## olan.navigation

```ts
await olan.navigation.push('task', { taskId: 't1' });
await olan.navigation.replace('done', null);
await olan.navigation.pop();
```

The stack lives in the app; read it with `useNavigation()` (navigation.md). `pop()` on the first
screen keeps the stack and tells Olan, which closes a modal surface.

## olan.backend

`olan.backend.call(name, args?)` runs `functions[name]` of the app's backend code (`server`,
backend.md) with the person's consented permissions and resolves with its JSON result (≤ 256 KiB).
Failures: `backend_function_not_found`, `backend_error` (the function threw; `message` is its
error), `backend_limit`, `backend_busy`, `payload_too_large`, `backend_unavailable`, `backend_migrating` (errors.md).

```tsx
const summary = useQuery(() => olan.backend.call<Summary>('summary'), []);
```

## OlanError

```ts
try {
  await olan.projects.updateTask(projectId, task.id, { status: 'completed', revision: task.revision });
} catch (error) {
  if (isOlanError(error, 'conflict')) { /* reload and retry */ }
  else if (error instanceof OlanError && error.code === 'permission_denied') { /* … */ }
}
```

`error.code` (`OlanErrorCode`: the codes above, or a newer host's) and `error.message`.
`isOlanError(error, code?)` narrows an unknown error. `useQuery` puts the error in
`query.error`, `useCollection` in `list.error`. `error.hostDetails` holds machine-readable extras the
host sent, if any. `RemoteError` (a subclass, from `olan.remote.request`) adds `status`, `details`,
`reason?` and `retryAfterSeconds?` (remote-requests.md#errors-remoteerror).

## Other exports

`defineApp`, `isAppDefinition`, `isOlanError`, `isRemoteError`, `RemoteError`, `SDK_VERSION` (`'1.8.1'`), `PROTOCOL_VERSION` (`1`), `SURFACE_NAMES`, and types
`SurfaceParams`, `AppCard`, `Calendar`, `CalendarEvent`, `Contact`, `AddressBook`, `MailMessage`, `Meeting`,
`AppDefinition`, `AppSurfaces`, `SurfaceComponent`, `SurfaceProps`, `JsonValue`, `Surface`,
`Theme`, `Platform`, `AppContext`, `AppUser`, `DirectoryUser`, `RpcMethods`, `OlanErrorCode`, `DbRow`, `DbWhere`,
`DbCondition`, `DbOrderBy`, `DbQuery`, `DbCollection`, `DbPatch`, `CreateTaskInput`,
`DeleteRecordInput`, `RemoteRequestInit`, `RemoteResponse`, `RemoteErrorReason`, `FileHandle`,
`FilePickOptions`, `FileUploadResult`, `UploadOptions`, `UploadTask`, `ExternalFlowResult`,
`AppSurfaceParams`, `QueryOptions`, (SDK 1.7) `ProjectStatus`, `ProjectLabel`, `RecordLink`, `RecordTarget`,
`ProjectCalendarItem`, `ProjectApproval`, `TaskActionParams`, `IssueActionParams`, `RecordCardParams`, and (SDK 1.8)
`ProjectField`, `ProjectFieldDefinition`, `ProjectFieldType`, `ProjectFieldValue`, `ProjectFieldValues`. The runtime exports (`startRuntime`,
`workerTransport`, `createMemoryChannel`, `createUiRoot`, tree helpers) are used by the CLI and
the Olan host; apps do not call them. `@olan-app/sdk/server` is for the app's own server
(server.md), `@olan-app/sdk/backend` for backend code Olan runs (`defineBackend`, the server-side
`olan`, `OlanBackendError`; backend.md).

<!-- docs/hooks.md -->
# Hooks

```ts
import { useQuery, useCollection, useRecord, useUser, useUsers, useNavigation, useSurfaceParams, useProjectConfig, useSettings, useTheme, useLocale, usePlatform, useAppContext } from '@olan-app/sdk';
import { useState, useEffect, useMemo, useCallback, useRef } from 'react';   // React hooks work as usual
```

Hooks only work inside components rendered by a surface (they read the running session), and
only in named components (`function Projects() { … }`), following the React hook rules.

## useQuery(fn, deps?, options?)

Runs an async function when the component mounts and again whenever `deps` change (like
`useEffect`). Results of superseded runs are ignored. `options.refetchIntervalMs` refreshes it
regularly (SDK 1.5, below).

```ts
const projects = useQuery(() => olan.projects.list({ limit: 50 }));
const detail = useQuery(() => olan.projects.get(projectId), [projectId]);
```

Returns `QueryState<T>`:

| Field | Type | Notes |
|---|---|---|
| `data` | `T \| undefined` | Last successful result; kept while refetching and after an error |
| `error` | `Error \| undefined` | The rejection (an `OlanError` for `olan.*` failures) |
| `loading` | `boolean` | `true` on the first render and during a refetch |
| `fetching` | `boolean` | `true` while any run is in flight, including the quiet interval refreshes (SDK 1.5) |
| `refetch` | `() => Promise<void>` | Runs it again (e.g. after `updateTask`) |

Typical shape:

```tsx
function Projects() {
  const projects = useQuery(() => olan.projects.list({ limit: 50 }));
  if (projects.error) {
    return (
      <Screen title="Projeler">
        <EmptyState title="Projeler yüklenemedi" description={projects.error.message} action={{ label: 'Tekrar dene', onPress: () => projects.refetch() }} />
      </Screen>
    );
  }
  const items = (projects.data?.items ?? []).map((p) => ({ key: p.id, title: p.name }));
  return (
    <Screen title="Projeler" loading={projects.loading}>
      <List items={items} emptyText="Henüz proje yok" />
    </Screen>
  );
}
```

After a change, update and refetch:

```ts
await olan.projects.updateTask(projectId, task.id, { status: 'completed', revision: task.revision });
await tasks.refetch();
```

### Refreshing on an interval (`refetchIntervalMs`)

```tsx
const posts = useQuery(
  () => olan.remote.request({ method: 'GET', path: '/posts' }),
  [brandId],
  { refetchIntervalMs: hasPending ? 10_000 : undefined },      // poll only while something is publishing
);
```

- At least 5000 ms; smaller values are raised to 5000. `undefined`, `0`, `false` or `null` turns
  it off; changing the value restarts the timer.
- Interval runs are quiet: `loading` stays `false`, `data` stays until the new result, a failure
  goes to `error` (and the old `data` stays). `fetching` is `true` while one runs. A tick while a run
  is still in flight is skipped.
- Olan drives the timer, not the sandbox: there are no ticks while the surface is not visible (a
  hidden browser tab, a closed panel, the app in the background on a phone). When it becomes visible
  and the interval has passed, a tick comes at once, then the timer continues.
- At most 16 timers per sandbox. On an Olan server before 1.5 the SDK falls back to a timer inside
  the sandbox.
- Tests: `app.fireTimers()` sends one tick (testing.md).

## useCollection(name, query?, deps?)

Rows of an `olan.db` collection (database.md), loaded on mount and whenever `name`, `query`
(compared by value) or `deps` change. Needs `db`.

```ts
const list = useCollection<Decision>('decisions', { where: { status }, orderBy: { field: 'title' }, limit: 20 });
```

| Field | Type | Notes |
|---|---|---|
| `rows` | `DbRow<T>[]` | The first page plus every page `loadMore` added |
| `nextCursor` | `string \| null` | `null` on the last page |
| `loading` | `boolean` | `true` on the first render, while refetching and during `loadMore` |
| `error` | `OlanError \| undefined` | e.g. `permission_denied`, `invalid_params` |
| `refetch` | `() => Promise<void>` | Loads the first page again |
| `loadMore` | `() => Promise<void>` | Appends the next page (no-op on the last page) |

`insert`, `update` and `delete` through `olan.db.collection(name)` anywhere in the app reload every
`useCollection`/`useRecord` of that collection; there are no live updates from other people, so
offer a refresh action (`refetch`).

## useRecord(name, id)

One row: `QueryState<DbRow<T> | null>` (`data` is `null` when the row does not exist or is
hidden). `id` `null` skips the call. Reloads when the row changes through `olan.db` in the app.

```ts
const decision = useRecord<Decision>('decisions', params.id);
```

## useUser()

The person using the app: `{ id }`, the central Olan user id (a UUID). It is the same value as
`row.createdBy`, `task.assigneeId`, `task.createdBy` and `member.userId`, so compare with it to show
actions only where they will work. Needs no permission.

```tsx
const me = useUser();
const mine = row.createdBy === me.id;   // e.g. hide "Sil" on other people's rows of a delete: 'owner' collection
const myTasks = tasks.filter((task) => task.assigneeId === me.id);
```

## useUsers(ids)

Directory entries (`olan.users.get`) for a set of ids: `QueryState<DirectoryUser[]>` plus `byId`
(a `Map`). Reloads when the set changes (order and duplicates do not matter); `[]` makes no call.
Unknown or inaccessible ids are missing from the result. Needs `users:read`.

```tsx
const people = useUsers(rows.map((row) => row.createdBy));
const name = (id: string) => people.byId.get(id)?.displayName ?? '—';
```

## useNavigation()

The visible screen of the surface's navigation stack and the navigation actions (navigation.md).

```ts
const { screen, params, depth, push, pop, replace } = useNavigation();
```

| Field | Type | Notes |
|---|---|---|
| `screen` | `string` | `'index'` on the first screen |
| `params` | `JsonValue` | Params of the visible screen (first screen: the surface params, or the query of an app address, links.md) |
| `depth` | `number` | Screens on the stack (1 on the first screen) |
| `push(screen, params?)` | `Promise<void>` | Same as `olan.navigation.push` |
| `pop()` | `Promise<void>` | |
| `replace(screen, params?)` | `Promise<void>` | |

## useSurfaceParams<S>()

What the host opened the surface on, typed per surface (surfaces.md):

```ts
const { conversationId, message } = useSurfaceParams<'chat.action'>();
const mail = useSurfaceParams<'mail.sidebar'>();
// { messageId, threadId: string | null, subject, from: { name: string | null, email }, to: same[], cc: same[], receivedAt: ISO date-time }
const returned = useSurfaceParams<'app'>()?.return;   // SDK 1.5: an external flow came back with no pending openExternal (links.md)
```

Exact shapes and which fields may be `null`: surfaces.md. In tests they come from the fixtures
(testing.md, "Surface params in tests").

Panels (`mail.sidebar`, `meeting.panel`) re-render with new params when the person opens another
object; use the params as `useQuery` deps. The type argument is not checked at run time.

## useProjectConfig(projectId?)

SDK 1.6: the app's configuration of a project (`olan.project.config`, api.md). Without `projectId`
it uses the project the surface was opened for (`project.widget`, `project.tab`, `project.settings`; SDK 1.7 also `task.action`, `issue.action`, `record.card`).
A `useQuery` state plus `value` (`{}` until set) and `save(value, { revision? })`, which writes on the
loaded `revision` so a change someone made meanwhile fails with `conflict` (then `refetch()`).

```tsx
const config = useProjectConfig();
const brandId = typeof config.value.brandId === 'string' ? config.value.brandId : null;
await config.save({ ...config.value, brandId: 'b2' });   // config.data.revision + 1 afterwards
if (isOlanError(config.error, 'project_not_enabled')) { /* the app was not added to this project */ }
```

## useSettings()

`Record<string, JsonValue>`: the app's settings (manifest `settings` with defaults applied).
Re-renders when an admin changes them.

```ts
const settings = useSettings();
const threshold = typeof settings.threshold === 'number' ? settings.threshold : 3;
```

## useTheme(), useLocale(), usePlatform()

- `useTheme()` → `'light' | 'dark'` (colours stay with the host; use it only for content choices).
- `useLocale()` → the host UI's BCP 47 locale, e.g. `'tr'` or `'en-US'`. Use it with
  `Intl.DateTimeFormat`/`Intl.NumberFormat` and to pick your strings.
- `usePlatform()` → `'web' | 'desktop' | 'ios' | 'android'`.

## useAppContext()

The whole host context: `{ theme, locale, platform, permissions: string[], settings, development: boolean, user: { id } }`.
`permissions` are the permissions the installation granted; `development` is `true` in Studio and
in tests; `user` is what `useUser()` returns.

```ts
const { permissions } = useAppContext();
const canDelete = permissions.includes('tasks:delete');
```

<!-- docs/navigation.md -->
# Navigation

Each surface has its own navigation stack, kept inside the app. The first screen is named
`'index'` and its params are the surface params. `push` adds a screen, `pop` removes the top one,
`replace` swaps the top one. Olan is told about every change so it can show its own back control;
when the user presses back (or swipes back on iOS, or uses the Android back button), Olan pops the
stack.

The pattern: one surface component reads `useNavigation()` and renders the visible screen.

```tsx
import { List, Screen, defineApp, olan, useNavigation, useQuery } from '@olan-app/sdk';

function ProjectsScreen() {
  const navigation = useNavigation();
  const projects = useQuery(() => olan.projects.list({ limit: 50 }));
  const items = (projects.data?.items ?? []).map((p) => ({ key: p.id, title: p.name }));
  return (
    <Screen title="Projeler" loading={projects.loading}>
      <List items={items} onSelect={({ key }) => navigation.push('project', { projectId: String(key) })} />
    </Screen>
  );
}

function ProjectScreen({ projectId }: { projectId: string }) {
  const detail = useQuery(() => olan.projects.get(projectId), [projectId]);
  const items = (detail.data?.tasks ?? []).map((t) => ({ key: t.id, title: t.title }));
  return (
    <Screen title={detail.data?.project.name ?? 'Proje'} loading={detail.loading}>
      <List items={items} emptyText="Görev yok" />
    </Screen>
  );
}

function App() {
  const { screen, params } = useNavigation();
  const p = (params ?? {}) as { projectId?: string };
  if (screen === 'project' && p.projectId) return <ProjectScreen projectId={p.projectId} />;
  return <ProjectsScreen />;
}

export default defineApp({ app: App });
```

Rules:

- Screen names and params are yours; params must be JSON (strings, numbers, booleans, null,
  arrays, objects).
- Each screen component gets fresh state when it is pushed; screens below keep nothing (they
  re-render from their queries when they become visible again).
- Do not add your own "Geri" (back) button for the stack; Olan shows one. A button that calls
  `pop()` after finishing a task (e.g. after a form submit) is fine.
- `pop()` on the first screen keeps the stack; Olan closes a modal surface, other surfaces stay open.
- `project.widget` surfaces are small cards; keep them to one screen.
- An app address (`https://<Olan web>/apps/a/<appId>/<screen>?id=…`, SDK 1.5, links.md) opens the
  `app` surface on that screen: the stack starts as `[index, <screen>]` with the query as the
  screen's params (`index` alone gets them as its params), and back returns to `index`. So read
  every screen's params defensively: they may come from a link, as strings.

Testing navigation (testing.md):

```ts
const app = await renderApp();
await app.press('Lansman');                 // List item title
app.navigation();                           // [{ action: 'push', screen: 'project', params: { projectId: 'launch' } }]
await app.back();                           // the host's back control
```

<!-- docs/surfaces.md -->
# Surfaces

A surface is a place in Olan where the app appears. Declare each one in `olan-app.json`
`surfaces` and define a component with the same name in `defineApp({ … })`:

```tsx
export default defineApp({ app: Home, 'chat.action': AddToStandup, 'mail.sidebar': CustomerPanel });
```

| Surface | Where | Shown as | `params` (`useSurfaceParams<S>()`) |
|---|---|---|---|
| `app` | Olan's app list, sidebar, its address `/apps/a/<appId>` | full screen | `null`, or `{ return }` after an external flow (SDK 1.5, links.md) |
| `project.widget` | Project summary page | card | `{ projectId }` |
| `settings` | Ayarlar → Uygulamalar | full screen | `null` |
| `chat.action` | A message's "More" menu → Apps | modal | `{ conversationId, message: { id, body, senderId, senderKind, createdAt, threadRootId } }` |
| `chat.command` | `/<command>` in the chat composer | modal | `{ conversationId, text, threadRootId? }` (`text`: what follows the command) |
| `chat.card` | The `open` button of the app's chat card (cards.md) | modal | `{ conversationId, messageId, payload }` |
| `mail.sidebar` | A tab next to the contact panel of an open email | panel | `{ messageId, threadId, subject, from: { name, email }, to, cc, receivedAt }` |
| `mail.action` | The email toolbar's overflow menu → Apps | modal | same as `mail.sidebar` |
| `calendar.event.action` | The event popover → Apps | modal | `{ calendarId, eventId, uid, title, start, end, timeZone, isAllDay, location?, isOrganizer }` |
| `meeting.panel` | A tab in the meeting room's side panel (not for guests) | panel | `{ meetingId, slug, title, startsAt, endsAt, role: 'organizer' \| 'participant', projectId? }` |
| `project.tab` | A tab of the project page (SDK 1.6) | tab | `{ projectId }` |
| `project.settings` | The project page → Uygulamalar → the app's "Ayarlar" (SDK 1.6) | full screen (a sheet) | `{ projectId }` |
| `task.action` | A task's "…" menu → the app (SDK 1.7) | modal | `{ projectId, task: { id, key, title, status, statusId, statusCategory, assigneeId, due } }` |
| `issue.action` | An issue's "…" menu → the app (SDK 1.7) | modal | `{ projectId, issue: { id, key, number, title, kind, state, stateReason, inTriage } }` |
| `record.card` | The `open` button of the card the app drew on a task or issue (SDK 1.7) | modal | `{ projectId, linkId, target: { kind, id }, externalId, payload }` |

Manifest entries: `app`, `project.widget`, `settings`, `project.tab` and `project.settings` take
`{ "title"?: string }` (the tab label and the settings title fall back to the app name); every other
surface needs `"title"` (1–80, the menu or tab label). `chat.command` also needs `"command"`
(`^[a-z][a-z0-9-]{1,31}$`, typed after `/`) and may have `"description"` (≤ 120):

```json
"surfaces": {
  "chat.action": { "title": "Standup'a ekle" },
  "chat.command": { "title": "Standup", "command": "standup", "description": "Bugünün standup'ını aç" },
  "mail.sidebar": { "title": "Müşteri" }
}
```

## Reading the params

```tsx
import { useSurfaceParams, useQuery, olan, Screen, Text } from '@olan-app/sdk';

function CustomerPanel() {
  const mail = useSurfaceParams<'mail.sidebar'>();          // typed per surface
  const contacts = useQuery(() => olan.contacts.search(mail.from.email), [mail.from.email]);
  return <Screen title={mail.subject}><Text text={`${contacts.data?.length ?? 0} kişi`} /></Screen>;
}
```

Exact shapes (types `SurfaceParams`, `MailSurfaceParams` … from `@olan-app/sdk`): keys without
`?` are always present; `?` keys may be absent or `null`. Tests build them from fixtures (testing.md):

```ts
type MailAddress = { name: string | null; email: string };   // name null when the header has none
interface MailSurfaceParams {        // mail.sidebar, mail.action (no body: olan.mail.getMessage)
  messageId: string; threadId: string | null; subject: string;   // '' when there is no subject
  from: MailAddress;                 // the first From address; email '' if the message has none
  to: MailAddress[]; cc: MailAddress[];   // [] when empty (no bcc)
  receivedAt: string;                // ISO 8601 date-time, e.g. '2026-10-16T09:00:00Z'
}
// chat.action: message.body/senderId/threadRootId are string | null; createdAt ISO date-time
// calendar.event.action: start/end ISO date (all-day) or date-time; timeZone/location string | null
// meeting.panel: endsAt/projectId string | null; chat.card: payload is the card action's JsonValue or null
// task.action: task.key ('WEB-12'), statusId, statusCategory, assigneeId, due string | null; status is the CalDAV value
// issue.action: issue.key ('WEB-#4'), kind, stateReason string | null; state 'open' | 'closed'
// record.card: target.kind 'task' | 'issue'; payload is the open action's JsonValue or null
```

Compare email addresses case-insensitively (`from.email.toLowerCase()`).

- The summary fields in `params` need no permission: the person opened the app on that object.
  More than that needs the read permission: the email body (`olan.mail.getMessage`, `mail:read`),
  other messages (`chat:read`), participants (`meetings:read`).
- Panels (`mail.sidebar`, `meeting.panel`) stay open while the person moves to another email or
  meeting; the component re-renders with the new params (no new start). Key queries on the params.
- Root component: `app`, `settings`, `project.tab` and `project.settings` start with `<Screen>`
  (`validate --strict` warns `ui.root_not_screen` otherwise); `project.widget` renders a `<Card>` (or `EmptyState`). Modals and
  panels should also start with `<Screen>`: its `title`/`actions` become the modal's or panel's
  header (not checked; another root is shown as is, without a header).
- Modals: the surface's first `Screen` is shown in a modal; `olan.navigation.pop()` (or the host's
  close control) on the first screen closes it. One modal per app at a time.
- The `params` prop of the surface component carries the same value (`JsonValue`).

## Project extensions (SDK 1.6)

A project is generic: statuses, labels, work packages. An app turns it into the project of a
process (a marketing calendar, a sales pipeline) only where a member adds it: the project page →
Uygulamalar lists the apps installed in the organization, and "Ekle" / "Kaldır" enables or removes
one there (it also shows in the project's activity). Only then:

- `project.widget` shows in the project's summary, `project.tab` adds a tab with the surface's
  `title` (or the app name), and `project.settings` opens from the app's "Ayarlar" button in
  Uygulamalar. All three get `{ projectId }`.
- `olan.projects.*` on the person's behalf reaches the project (`project_not_enabled` elsewhere).
- `olan.project.config` keeps the app's settings of that project (api.md#olanprojectconfig).

```tsx
function BrandTab() {
  const { projectId } = useSurfaceParams<'project.tab'>();
  const config = useProjectConfig();                       // this project's configuration
  const brandId = typeof config.value.brandId === 'string' ? config.value.brandId : null;
  return <Screen title="Marka">{brandId ? <BrandCalendar brandId={brandId} /> : <EmptyState title="Marka seçilmedi" />}</Screen>;
}
```

`project.tab` fills the tab's content area and keeps its own screen stack
(`olan.navigation.push` works; the back control appears in the tab). `project.settings` opens in a
sheet; `olan.navigation.pop()` on its first screen closes it. Removing the app from the project
hides its surfaces there; its configuration and the records it linked stay.

## Records on tasks and issues (SDK 1.7)

In the projects it is enabled in, an app also adds its own records and process (api.md#olanproject-records-statuses-calendar-feed-approvals):

- `task.action` / `issue.action` put the app in a task's or issue's "…" menu (the entry is the
  surface's `title`); the modal gets the task or issue. A typical action links one of the app's
  records to it: `olan.project.links.upsert` with a card the task or issue then shows.
- `record.card` opens from an `open` button of that card, with the link, its target, the record's
  `externalId` and the button's `payload`. Record cards have no `submit` buttons.
- The app's statuses (`olan.project.statuses.define`), labels and (SDK 1.8) custom fields
  (`olan.project.fields.define`, values with `setValues`) show among the project's; the task
  moves through a link (`olan.project.links.setStatus`). Its calendar items show as a layer of the
  project calendar, its feed lines and the status changes it made under its name in the project
  activity, its approval requests in the approvers' approval box.
- Manifest `projectTemplates` offers whole projects (work packages, statuses, labels, starter tasks)
  in "Yeni proje"; a project made from one has the app added (manifest.md#projecttemplates).

```tsx
function LinkRecord() {
  const { projectId, task } = useSurfaceParams<'task.action'>();
  const link = async () => {
    const created = await olan.project.links.upsert(projectId, { target: { kind: 'task', id: task.id }, externalId: 'SAT-12', card });
    await olan.project.links.setStatus(projectId, created.id, { statusKey: 'awaiting-approval' });
  };
  return <Screen title="Kayda bağla" subtitle={task.title}><Button label="Bağla" onPress={link} /></Screen>;
}
```

`olan-app init --template project-records` builds all of it with tests. Removing the app from the
project hides these surfaces; links and approvals stay read-only, calendar items hide.

## Visibility

An entry is shown when the installation is active, the person consented (the consent screen
opens on first use) and policy does not block it. Each place lists at most 8 apps, the rest go
under "Tüm uygulamalar". Two apps with the same `command` are both listed with their names.
Surfaces need no permission of their own; the consent screen lists them under "Görüneceği yerler".

<!-- docs/cards.md -->
# Chat cards

An app posts a static card into a chat as itself (name and icon of the app). A card is the UI tree
format without handlers, so it renders on web, desktop and mobile without running the app:

```ts
import type { AppCard } from '@olan-app/sdk';

const card: AppCard = {
  version: 1,
  root: 1,
  fallbackText: 'Standup: 3 görev açık',          // 1–500: notifications, search, previews
  nodes: [
    { id: 1, type: 'Card', props: { title: 'Standup', subtitle: '17 Ekim' }, children: [2, 4, 5] },
    { id: 2, type: 'Text', props: {}, children: [3] },
    { id: 3, type: '#text', props: { text: '3 görev açık' }, children: [] },
    { id: 4, type: 'Button', props: { label: 'Aç', action: { kind: 'open', payload: { day: '2026-10-17' } } }, children: [] },
    { id: 5, type: 'Button', props: { label: 'Bitti', variant: 'primary', action: { kind: 'submit', name: 'done' } }, children: [] },
  ],
};
const { messageId } = await olan.chat.postCard({ conversationId, card });   // chat:write
await olan.chat.updateCard(messageId, { ...card, fallbackText: 'Standup bitti' });
```

- Components: `Card`, `Stack`, `Text` (with `#text` children or `text`), `Badge`, `Table`,
  `Button`, `EmptyState`; props as in components.md. No inputs and no handlers (`$handler`,
  `onPress`, `Card.actions`, `EmptyState.action`, `Table.onSelectRow`).
- `Button` has `action` instead of `onPress`:
  - `{ kind: 'open', payload? }` opens the app's `chat.card` surface with
    `{ conversationId, messageId, payload }` (declare `chat.card` in `surfaces`).
  - `{ kind: 'submit', name, payload? }` calls the app's server (`POST {remote.url}/card-actions`,
    server.md); it needs `remote`. The answer may replace the card and show a toast.
- Limits: JSON ≤ 16 KiB, ≤ 100 nodes, depth ≤ 8, each `payload` ≤ 2 KiB. Invalid cards fail with
  `validation_failed`; the message lists `card.*` / `tree.*` codes (errors.md#cards).
- Where: a conversation the person is in (from a chat surface: `useSurfaceParams().conversationId`).
  From the app's server with the app identity: only conversations the app was added to (server.md).
- `updateCard` changes only cards this installation posted. Apps never receive events for their own
  cards. Cards do not trigger push notifications; they count as unread.
- Rate limits: 60 cards per minute per installation, 10 per conversation.

Record cards (SDK 1.7): the same format is the card an app draws on a task or issue
(`olan.project.links.upsert`, api.md) and attaches to an approval request. Its buttons may only
`{ kind: 'open', payload? }`, which opens the app's `record.card` surface with
`{ projectId, linkId, target, externalId, payload }`; `validateRecordCard(card)` checks it.

`validateCard(card, { remote })` from `@olan-app/schema` runs the same checks; `olan-app test`
validates every `postCard` like the server (`app.host.cards` lists what the app posted).

<!-- docs/database.md -->
# App database (`olan.db`)

Each app can have its own database on the Olan server: collections of JSON rows with declared
fields, indexed queries, cursors and per-row revisions. Declare the collections in the manifest's
`data` and request the `db` permission. Needs `@olan-app/sdk` ^1.1.0 (`"sdk": "^1.1.0"`).

`olan.db` is for the app's records (decisions, checklists, pins). For a few per-user preferences
keep using `olan.storage` (api.md); for Olan's own records (tasks) use `olan.projects`.

## Declaring collections

```jsonc
// olan-app.json
"permissions": ["db"],
"data": {
  "version": 1,                                  // integer; increase it whenever the schema changes
  "collections": {
    "decisions": {
      "scope": "organization",                   // shared in the organization (with rules)
      "fields": {
        "title":     { "type": "string", "required": true, "maxLength": 200, "indexed": true },
        "status":    { "type": "string", "enum": ["open", "done"], "indexed": true },
        "projectId": { "type": "ref:project", "indexed": true },
        "taskId":    { "type": "ref:task" },
        "decidedOn": { "type": "date", "indexed": true },
        "score":     { "type": "number", "integer": true, "min": 0, "max": 10 },
        "meta":      { "type": "json" }
      },
      "rules": { "read": "any", "update": "any", "delete": "owner" }
    },
    "pins": { "scope": "user", "fields": { "decisionId": { "type": "string", "maxLength": 64, "indexed": true } } }
  }
}
```

| `type` | Value | Options | Indexable |
|---|---|---|---|
| `string` | string | `maxLength` (default 1000, ≤ 10000), `enum` (≤ 100 values, each ≤ 100 characters) | yes, when `maxLength` ≤ 512 or it has `enum` |
| `number` | finite number | `integer`, `min`, `max` | yes |
| `boolean` | `true` / `false` | – | yes (`eq`/`in` only) |
| `date` | `"YYYY-MM-DD"` (a real calendar day) | – | yes |
| `datetime` | ISO date-time **with offset** (`Z` or `+03:00`); stored as UTC `toISOString()` | – | yes |
| `json` | any JSON, ≤ 16 KiB serialised | – | no |
| `ref:project`, `ref:task`, `ref:user` | UUID string (stored lower-case) | – | yes (`eq`/`in` only) |

Every field also takes `required` (default `false`), `indexed` (default `false`) and `label`
(≤ 80, shown in Studio and exports). A field that is not `required` may be missing or `null`
(both mean "no value"; `null` is not stored). Refs only check the UUID format; Olan does not
check that the project/task/user exists, and does not clean up when it is deleted.

Limits: ≤ 20 collections; ≤ 64 fields and ≤ 5 indexed fields per collection; collection names
`^[a-z][a-z0-9_]{0,39}$`; field names `^[A-Za-z][A-Za-z0-9_]{0,63}$`; `id`, `createdAt`,
`updatedAt`, `createdBy`, `revision` are reserved; a row's data ≤ 64 KiB as JSON. There are no
composite or unique indexes. `createdAt`, `updatedAt` and `createdBy` are always indexed.

### Scope and rules

- `"scope": "user"`: each person sees only the rows they created. No `rules`.
- `"scope": "organization"`: rows are shared by everyone who uses the installation, subject to
  `rules` — `read`, `update`, `delete`, each `"any"` or `"owner"` (the row's creator). Default
  `{ "read": "any", "update": "any", "delete": "owner" }`. In a personal installation (installed
  by one user for themselves) an organization collection belongs to that user.
- A row the rules hide does not appear in `get`/`query`/`count`; changing or deleting it fails
  with `forbidden_record`. Admins see every row only through export and the admin data browser,
  never inside the app.

### Changing the schema

Increase `data.version` with every change. When a new version is installed, Olan compares it
with the stored schema:

- Applied automatically: new collections, new optional fields, adding or removing `indexed`,
  a larger `maxLength`/`max`, a smaller `min`, new `enum` values, `required: true → false`,
  `rules`, `label`.
- Refused until migrations arrive (Phase 3): removing a collection (`data.collection_removed`)
  or field (`data.field_removed`), changing a type (`data.type_changed`) or scope
  (`data.scope_changed`), adding a required field or making one required
  (`data.required_added`), narrowing a constraint (`data.constraint_tightened`).
- A changed schema with the same `version` is `data.version_not_bumped`; a lower one
  `data.version_downgrade`.

When the app is removed, its data is kept for 30 days and comes back if it is installed again
(with a compatible schema); admins can export it (NDJSON) or delete it earlier.

## API

```ts
import { olan, isOlanError, type DbRow } from '@olan-app/sdk';

type Decision = { title: string; status?: 'open' | 'done'; projectId?: string; score?: number };
const decisions = olan.db.collection<Decision>('decisions');

const row = await decisions.insert({ title: 'Ship 1.1', status: 'open' });
// row: { id, data: { title, status }, revision: 1, createdAt, updatedAt, createdBy }
const same = await decisions.get(row.id);                        // DbRow<Decision> | null
const { rows, nextCursor } = await decisions.query({
  where: { status: 'open', decidedOn: { gte: '2026-01-01' } },
  orderBy: { field: 'decidedOn', direction: 'desc' },
  limit: 20,
});
const changed = await decisions.update(row.id, { status: 'done', score: null }, { revision: row.revision });
await decisions.delete(row.id, { revision: changed.revision });  // revision optional
const open = await decisions.count({ status: 'open' });
```

| Call | Returns | Notes |
|---|---|---|
| `collection<T>(name)` | `DbCollection<T>` | `name` from `data.collections`; unknown → `invalid_params` |
| `insert(data)` | `DbRow<T>` | `data` is the whole row (validated) |
| `get(id)` | `DbRow<T> \| null` | `null` when missing or hidden by rules |
| `query({ where?, orderBy?, limit?, cursor? })` | `{ rows: DbRow<T>[]; nextCursor: string \| null }` | see below |
| `update(id, patch, { revision })` | `DbRow<T>` | shallow merge; `null` clears a field; `revision` must be current |
| `delete(id, { revision? })` | `void` | with `revision`, only if unchanged |
| `count(where?)` | `number` | same `where` as `query` |

```ts
interface DbRow<T> { id: string; data: T; revision: number; createdAt: string; updatedAt: string; createdBy: string }
type DbScalar = string | number | boolean | null;
type DbCondition = DbScalar | { eq?: DbScalar; in?: DbScalar[]; gt?: DbScalar; gte?: DbScalar; lt?: DbScalar; lte?: DbScalar };
type DbWhere = Record<string, DbCondition>;               // fields are combined with AND
interface DbOrderBy { field: string; direction?: 'asc' | 'desc' }
interface DbQuery { where?: DbWhere; orderBy?: DbOrderBy; limit?: number; cursor?: string }
```

### Queries

- `where` only on indexed fields and `createdAt`, `updatedAt`, `createdBy`; at most 5 fields.
  A plain value means `eq`; `{ field: null }` finds rows without a value; `in` takes ≤ 50 values
  (`null` allowed); `gt`/`gte`/`lt`/`lte` may be combined on one field for a range. `boolean`,
  `ref:*` and `createdBy` allow only `eq`/`in`. Values must match the field type (dates as
  `YYYY-MM-DD`, date-times with an offset). Anything else is `invalid_params`.
- `orderBy`: one indexed field, `createdAt` or `updatedAt`; `direction` defaults to `'asc'`.
  Without `orderBy` rows come newest first (`{ field: 'createdAt', direction: 'desc' }`). Ties are
  broken by `id`; rows without a value come last in both directions. Strings sort by Unicode
  code point (`'B' < 'a'`), not alphabetically for a language.
- `limit` 1–100, default 50. `nextCursor` is `null` on the last page; pass it as `cursor` with the
  **same** `where` and `orderBy` (a different query → `invalid_params`). Cursors are opaque.
- No full-text search, joins or aggregates; filter on indexed fields and finish in JavaScript.

## Hooks

`useCollection(name, query?, deps?)` → `{ rows, nextCursor, loading, error, refetch, loadMore }` and
`useRecord(name, id | null)` → `{ data, error, loading, refetch }` (hooks.md). Mutations through
`olan.db.collection(name)` in the app reload the hooks reading that collection; there are no live
subscriptions, so other people's changes appear after `refetch`.

## Errors

| Code | When | What to do |
|---|---|---|
| `validation_failed` | The row does not match the schema. `message` names the first problem: `"data.title: row.required"` (`row.unknown_field`, `row.required`, `row.type`, `row.max_length`, `row.range`, `row.enum`, `row.not_integer`, `row.json_too_large`, `row.too_large`) | Fix the form values; show the field |
| `conflict` | `update`/`delete` with an old `revision` (someone changed the row) | `get` the row again, re-apply the change, retry |
| `not_found` | `update`/`delete` of a row that does not exist (or belongs to another user in a `user` collection) | Refetch the list |
| `forbidden_record` | The collection's `rules` do not allow this user to change/delete the row | Catch it and explain ("only the person who added it can delete it"); see below |
| `quota_exceeded` | The installation's row or size limit is reached (default 100 000 rows, 100 MiB) | Tell the user to contact an admin; delete old rows |
| `invalid_params` | Unknown collection, non-indexed `where`/`orderBy` field, bad `limit` or cursor | Fix the call |
| `permission_denied` | `db` is not granted | Add `"db"` to `permissions` |

```ts
async function markDone(row: DbRow<Decision>) {
  try {
    return await decisions.update(row.id, { status: 'done' }, { revision: row.revision });
  } catch (error) {
    if (!isOlanError(error, 'conflict')) throw error;
    const fresh = await decisions.get(row.id);          // someone else changed it: retry once
    return fresh && decisions.update(fresh.id, { status: 'done' }, { revision: fresh.revision });
  }
}
```

`createdBy` is the central Olan user id, the same as `useUser().id` (hooks.md). With `owner`
rules, show the action only on the user's own rows, and still handle the refusal (the row or the
rules may change in between):

```tsx
const me = useUser();
const canDelete = row.createdBy === me.id;   // rules.delete: 'owner'

async function remove(row: DbRow<Decision>) {
  try {
    await decisions.delete(row.id, { revision: row.revision });
  } catch (error) {
    if (!isOlanError(error, 'forbidden_record')) throw error;
    await olan.ui.toast({ text: 'Bu kararı yalnızca ekleyen kişi silebilir', tone: 'warning' });
  }
}
```

If everyone should be able to do it, use `"any"` for that rule instead; for "my rows only", use
a `"scope": "user"` collection.

## Testing

`olan-app test` and `validate --strict` run the app against an in-memory database with the same
rules and error codes (`@olan-app/sdk/memory-db`). Seed it with `fixtures/db.json`:

```json
{ "decisions": [{ "id": "d1", "data": { "title": "İlk karar", "status": "open" } }] }
```

Missing `id`, `createdBy` (the default user `00000000-0000-4000-8000-000000000001`), timestamps
and `revision` (1) are filled in; another `"createdBy"` makes a row someone else wrote. Row ids may
be any unique string. Rows must match the schema, and `ref:*` values must be UUIDs, while the
mock's built-in project and task ids are not (`p0`, `p0-t0`): an app that stores project/task ids
needs `fixtures/projects.json` with UUID ids (testing.md, "Fixtures").

<!-- docs/permissions.md -->
# Permissions

Declare every permission the app uses in `olan-app.json`:

```json
"permissions": ["projects:read", "tasks:write", "db", "http:api.example.com"]
```

Olan shows them when someone installs the app, grouped as Okuma (read), Yazma (write), **Silme**
(delete — its own heading with a warning and each permission's description), Uygulama verisi
(app data), Ağ (network) and Ayarlar (settings). Delete permissions start unticked: the admin
grants them explicitly. Olan checks every `olan.*` call against the permissions the installation
granted. Declare only what the app calls.

| Permission | Group | Shown to the user | Allows |
|---|---|---|---|
| `projects:read` | read | Projelerinizi ve görevlerinizi okuyabilir | `olan.projects.list`, `get`, `tasks`; SDK 1.7 the `list` calls of `olan.project.statuses`, `labels`, `links`, `calendar`, `approvals`; SDK 1.8 `olan.project.fields.list`, `values`; `project.task.*`, `project.issue.*`, `project.approval.decided` events |
| `users:read` | read | Kuruluşunuzdaki kişilerin adını, e-postasını ve dizin bilgilerini görebilir | `olan.users.get`, `useUsers` (name, email, title, department, team); a permission of its own, no other one needed |
| `chat:read` | read | Sohbetleri okuyabilir | `olan.chat.conversations`, `messages` |
| `tasks:write` | write | Erişebildiğiniz projelerde görev oluşturabilir ve görevleri değiştirebilir | `olan.projects.createTask`, `updateTask` (reading still needs `projects:read`); SDK 1.7 `olan.project.links.upsert`, `remove`, `setStatus`; SDK 1.8 `olan.project.fields.setValues` |
| `projects:write` | write | Proje görevlerini değiştirebilir | `olan.projects.updateTask` only. Older permission: new apps use `tasks:write` |
| `tasks:delete` | delete | Erişebildiğiniz projelerdeki görevleri silebilir; her silme denetim kaydına yazılır | `olan.projects.deleteTask` |
| `projects:delete` | delete | Erişebildiğiniz projelerde boş iş paketlerini kaldırabilir (arşivler). Proje ve varsayılan iş paketi kaldırılamaz | `olan.projects.deleteList` |
| `storage` | data | Kendi verisini saklayabilir | `olan.storage.*`: small key–value data per installation and user (≤ 64 KiB per value, ≤ 1000 keys), for preferences and cache, not records |
| `db` | data | Kendi veritabanında kayıt oluşturabilir, okuyabilir, değiştirebilir ve silebilir; veriler bu Olan sunucusunda kalır | `olan.db.*` on the collections in the manifest's `data` (database.md) |
| `http:<host>` | network | `<host>` adresine istek atabilir | `olan.http.fetch` to that host |
| `settings:read` | settings | Organizasyon ayarlarını okuyabilir | nothing yet (reserved) |
| `chat:write` | write | Eklendiği ve sizin bulunduğunuz sohbetlere uygulama adına kart gönderebilir | `olan.chat.postCard`, `updateCard` (cards.md) |
| `calendar:read` | read | Takvimlerinizi ve etkinliklerinizi görebilir | `olan.calendar.calendars`, `events`; `calendar.event.*` events |
| `calendar:write` | write | Takvimlerinizde etkinlik oluşturabilir ve değiştirebilir; davet göndermez | `olan.calendar.createEvent`, `updateEvent` |
| `calendar:delete` | delete | Etkinlikleri silebilir; takvimler, varsayılan takvim ve Olan toplantıları silinemez; her silme denetim kaydına yazılır | `olan.calendar.deleteEvent` |
| `contacts:read` | read | Adres defterlerinizi ve kişilerinizi görebilir | `olan.contacts.addressBooks`, `search` |
| `contacts:write` | write | Kişi kartı oluşturabilir ve değiştirebilir | `olan.contacts.create`, `update` |
| `contacts:delete` | delete | Kendi adres defterlerinizdeki kişileri silebilir; adres defterleri silinemez | `olan.contacts.delete` |
| `mail:read` | read | Uygulamayı açtığınız e-postanın içeriğini görebilir; diğer e-postalarınıza erişemez | `olan.mail.getMessage` for the open email only |
| `meetings:read` | read | Görebildiğiniz toplantıların başlığını, saatini ve katılımcılarını görebilir | `olan.meetings.get`; `meeting.*` events |
| `projects:create` | write | Proje oluşturabilir; her proje kendi sohbetini, takvimini ve iş paketini açar | `olan.projects.create` |
| `projects:archive` | delete | Yalnız bu uygulamanın oluşturduğu projeleri kaldırabilir (arşivler) | `olan.projects.archive` |
| `projects:extend` | write | Eklendiği projelerde durum ve etiket tanımlayabilir, takvime katman, etkinlik akışına satır ve onay isteği ekleyebilir | SDK 1.7: `olan.project.statuses.define`, `remove`, `labels.define`, `remove`, `calendar.upsert`, `remove`, `activity.post`, `approvals.request`, `cancel`; SDK 1.8 `fields.define`, `remove` (api.md#olanproject-records-statuses-calendar-feed-approvals); only in projects the app was added to |
| `profile:read` | read | Profilinizi görme: uygulamanın sunucusu adınızı, e-posta adresinizi ve kurumdaki rolünüzü görür | SDK 1.5: adds `user.email`, `user.displayName` and `user.role` (`admin` \| `member`) to the `olan.remote.request` envelopes (remote-requests.md). Nothing in the sandbox changes (`useUser()` stays `{ id }`). Needs `remote` in the manifest (`manifest.profile_requires_remote`) |
| `files:pick` | data | Dosya seçtirme: seçtiğiniz dosyaları okuyabilir ve sizin onayınızla yükleyebilir; başka dosyalarınıza erişemez | SDK 1.5: `olan.files.pick`, `upload`, `cancel` (files.md); uploads go only to the `remote.url` origin or an `http:<host>` host |

Two more are **implied** by the manifest and never listed in `permissions` (`manifest.permission_unknown`):
`remote` (network: "Veriler `<host>` adresindeki uygulama sunucusuna gönderilebilir") when it
declares `remote` (it also covers `olan.remote.request` when `remote.requests` is `true`; there is
no separate permission for requests), and `ai:tools` (network: "Olan asistanı bu uygulamanın araçlarını sizin adınıza
çağırabilir; araç girdileri `<host>`'a gönderilir") when it declares `ai.tools`. Consent screens show
them with the server's host; admins can block them like any permission. Surfaces need no
permission; the consent screen lists them under "Görüneceği yerler".

`db` covers the app's own rows only; deleting them does not need a delete permission. Deleting
Olan records always does, and protected records (projects, the default work package, task
statuses and fields, chats, calendars, address books, Olan meetings, members, accounts) cannot be deleted by any app; such
calls fail with `forbidden_record` and are written to the audit log. An admin can also restrict
an app to deleting only the records it created.

No permission is needed for `olan.settings.get` (the app's own settings), `olan.ui.*` (including
`openUrl` and `openExternal`), `Image` and `Avatar` pictures (the host checks their origin instead),
`olan.navigation.*`, `useTheme`, `useLocale`, `usePlatform`, `useSettings`, `useNavigation`, and
`useUser()` (the current user's id; their name needs `users:read`).

## Reserved permissions

Ids fixed for a later phase fail with `manifest.permission_reserved` (the hint names the phase).
None are reserved today. Deleting projects (as opposed to archiving the app's own), creating work
packages, calendars or address books and sending chat messages are not app permissions.
`projects:delete` keeps its meaning (empty work packages); removing projects is `projects:archive`.

Permissions come in families: `<resource>:read`, `<resource>:write` (create and change) and
`<resource>:delete`. Deleting is always its own permission and is shown separately at install.

## `http:<host>`

- Grammar: `http:` + a DNS host name or IPv4 address + an optional `:port` (1–65535). No scheme,
  path, wildcard (`*.example.com`), user info or IPv6. Hosts are lower-cased
  (`http:API.Example.com` → `http:api.example.com`).
- A permission without a port matches only the scheme's default port: `http:api.example.com`
  allows `https://api.example.com/...` (443) and `http://api.example.com/...` (80), not
  `https://api.example.com:8443/`. A permission with a port matches only that port.
- One permission per host: `api.example.com` does not cover `www.example.com`.
- Only `http` and `https` URLs; URLs with credentials (`https://user:pw@…`) are refused.
- Olan's server additionally refuses private and loopback addresses (`localhost`, `10.x`, …).

## What happens when one is missing

- At run time the call rejects with `OlanError` code `permission_denied` (or `http_blocked` for a
  host that is not allowed). Show an `EmptyState` with the message rather than crashing.
- `olan-app validate --strict` renders every surface with the manifest's permissions and reports
  `permission.missing` / `permission.http_missing` with the permission to add.
- In tests, `renderApp({ permissions: [] })` checks how the app behaves without them.

Admins can block permissions for the whole organization (e.g. every `http:` host); a blocked
permission behaves like a missing one.

<!-- docs/manifest.md -->
# Manifest (`olan-app.json`)

```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`.

| Field | Required | Rule |
|---|---|---|
| `$schema` | no | `"https://olan.app/schemas/olan-app/v1.json"` (editor completion) |
| `schemaVersion` | yes | `1` |
| `id` | yes | Reverse domain, lowercase: `[a-z0-9-]+(\.[a-z0-9-]+)+`, ≤ 128. Never change it after publishing |
| `name` | yes | 1–80 characters |
| `version` | yes | Semver `MAJOR.MINOR.PATCH` (pre-release allowed). Raise it for every new release; an organization catalog (`publish --org`) never takes the same number twice. On the marketplace a `checks_failed`, rejected or withdrawn version number may be submitted again; approved or released ones may not (marketplace.md#publishing) |
| `sdk` | yes | `@olan-app/sdk` range: `"*"`, `"1.2.3"`, `"^1.0.0"`, `"~1.2.0"` or `">=1.0.0 <2.0.0"` (no `\|\|`, no `1.x`). Use `"^1.8.0"` (the current SDK; `olan-app init` writes it; `data` needs ^1.1.0, `useUser`/`olan.users` ^1.2.0, the Phase 3 surfaces, cards, calendar/contacts/mail/meetings calls and `remote` ^1.3.0, backend code (`server`) ^1.4.0, `remote.requests`, `olan.files`, `openUrl`/`openExternal`, `refetchIntervalMs`, the components `Tabs` … `ProgressBar` and `ai.tools` `timeoutMs` ^1.5.0, `project.tab`, `project.settings`, `olan.project.config` and `useProjectConfig` ^1.6.0, `task.action`, `issue.action`, `record.card`, the `olan.project` links/statuses/labels/calendar/activity/approvals calls, `projects:extend` and `projectTemplates` ^1.7.0, `olan.project.fields` ^1.8.0) |
| `minServerVersion` | no | Oldest Olan server that may install it (semver). Use `"0.1.0"`, the first Olan server with Olan Apps (`olan-app init` writes it); raise it only when the app needs a newer server. Olan's own version is still 0.x, so `"1.0.0"` would block every server today |
| `description` | no | ≤ 400 characters |
| `entry` | yes (apps) | Bundle path in the package: `"dist/app.js"` (relative `.js`/`.mjs`, no `..`) |
| `icon` | no | Package path to a png/svg/jpg/webp, e.g. `"assets/icon.png"` (the file must exist) |
| `kind` | no | `"app"` (default) or `"web-link"` |
| `surfaces` | yes (apps) | At least one surface (below, surfaces.md) |
| `permissions` | no | Default `[]`; ≤ 64; no duplicates (permissions.md) |
| `settings` | no | Settings fields (below) |
| `data` | no | App database collections (below, database.md). Apps only, not web links. Needs `"sdk": "^1.1.0"` and the `db` permission |
| `remote` | no | `{ "url", "jwksUrl", "requests"? }` of the app's own server (server.md); implies the `remote` permission. `"requests": true` (default `false`, SDK 1.5) turns on `olan.remote.request`: Olan posts signed requests to `{url}/requests` on behalf of the person (remote-requests.md). `profile:read` needs `remote` (`manifest.profile_requires_remote`) |
| `events` | no | Event types sent to `{remote.url}/events` (server.md#events); needs `remote` and each event's permission |
| `ai` | no | `{ "tools": [ … ] }`: assistant tools run by the app server (server.md#assistant-tools-aitools); needs `remote`, implies `ai:tools`. A tool's `timeoutMs` (1000–60000, default 15000; read-only tools at most 15000, SDK 1.5) sets how long Olan waits for it |
| `projectTemplates` | no | Project templates offered in "Yeni proje" while the app is installed (SDK 1.7, below) |
| `server` | no | Backend code Olan runs (backend.md): `{ "entry": "server/index.ts", "schedules"?: [{ name, cron, timeZone?, function? }] (≤ 10, ≥ 5 min apart), "events"?: { "<event type>": "<function>" }, "hooks"?: [{ name, function?, verify: { kind: "hmac-sha256"\|"standard-webhooks"\|"none", header?, secretSetting? } }] }`; `olan-app build` bundles `entry` into `dist/server.js`. Handlers go in `defineBackend`'s `schedules`/`events`/`hooks` maps by name; `function` (optional; required as the `events` value) only names a fallback in `functions`, and such a function is not callable from the UI (backend.md#handler-resolution) |

## Data (`olan.db`)

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

```json
"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

| Surface | Where it appears | Params | Root component |
|---|---|---|---|
| `app` | Full screen: Olan's app list (`/apps/<installation>`), sidebar, the permanent address `/apps/a/<appId>` (links.md) | `null`, or `{ return }` (links.md) | `Screen` (required: `ui.root_not_screen`) |
| `project.widget` | A card on the summary page of the projects the app is enabled in | `{ projectId: string }` | `Card` (or `EmptyState`) |
| `project.tab` | A tab of the project page, in projects the app is enabled in (SDK 1.6) | `{ projectId: string }` | `Screen` (required) |
| `project.settings` | The app's settings of one project: project page → Uygulamalar → Ayarlar (SDK 1.6) | `{ projectId: string }` | `Screen` (required) |
| `settings` | Olan → Ayarlar → Uygulamalar, instead of the generated form | `null` | `Screen` (required) |
| `chat.action`, `chat.command`, `chat.card`, `mail.sidebar`, `mail.action`, `calendar.event.action`, `meeting.panel` | Modals and panels in chat, email, calendar and meeting screens (surfaces.md) | the object it was opened on | `Screen` recommended (its title is the header; not checked) |
| `task.action`, `issue.action`, `record.card` | A task's or issue's "…" menu; the `open` button of the app's record card (SDK 1.7, projects the app is enabled in) | `{ projectId, task }`, `{ projectId, issue }`, `{ projectId, linkId, target, externalId, payload }` | `Screen` recommended |

`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`).

```tsx
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.

```json
"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:

| Property | Notes |
|---|---|
| `type` | `"string"`, `"number"`, `"boolean"` or `"select"` |
| `label` | Required, ≤ 80 |
| `description` | ≤ 400 |
| `default` | Same type as the field; for `select` one of the option values |
| `required` | boolean |
| `secret` | boolean: stored encrypted, masked in admin screens. Apps without `server` still receive the value; with `server` the UI gets `null` and only backend code reads it (`olan.secrets.get`, backend.md#secrets) |
| `options` | `select` only: `[{ "value": "TRY", "label": "Türk lirası" }]`, ≥ 1, unique values |

```json
"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).

<!-- docs/server.md -->
# The app's own server (`remote`)

An app may run its own HTTPS server. Olan then sends it signed **events**, runs its **assistant
tools** there, forwards **card actions** and (SDK 1.5, `"requests": true`) the app's own
**requests** made as the person (`olan.remote.request`, remote-requests.md); the server calls Olan
back with short-lived tokens.

```json
"remote": { "url": "https://standup.example.com/olan", "jwksUrl": "https://standup.example.com/.well-known/jwks.json" },
"events": ["project.task.created", "chat.message.created"],
"permissions": ["projects:read", "chat:read"],
"ai": { "tools": [ { "name": "standup_summary", "title": "Standup özeti", "description": "Summarises today's standup of a project.",
  "input": { "type": "object", "properties": { "projectId": { "type": "string" } }, "required": ["projectId"] },
  "permissions": ["projects:read"], "readOnly": true } ] }
```

- `remote.url`: https. Olan posts to `{url}/events`, `{url}/ai-tools/{name}`, `{url}/card-actions`
  and `{url}/requests`. Its origin is also where uploads (files.md) and `Image` pictures may come from.
  `http://127.0.0.1`, `localhost` and private addresses validate, but Olan only delivers to them
  for development installations on servers with `OLAN_APPS_REMOTE_ALLOW_PRIVATE=1`. An admin may
  point an installation to another copy of the server (`remoteUrlOverride`).
- `remote.jwksUrl`: https, your public keys (JWKS) for token requests.
- `remote` implies the permission `remote` ("Veriler `<host>` adresindeki uygulama sunucusuna
  gönderilebilir"), `ai.tools` implies `ai:tools`. Never list them in `permissions`.
- `events` and `ai.tools` need `remote`. Code that Olan runs for you (no server of your own) is
  `server`: backend.md.

## `@olan-app/sdk/server`

Plain Node ≥ 22 (WebCrypto, no dependencies; also Deno, Bun, edge runtimes). Create one per app.

**Where the code lives.** Your own server is a separate Node program that you run and host. In an
app project keep it in `app-server/` (`olan-app init --template remote` creates `app-server/server.ts`,
`routes.ts` and `tsconfig.json`), **not** in `server/`: `server/` is backend code that Olan runs for
you (manifest `server`, backend.md), bundled into the package. `app-server/` is never packed.
`olan-app validate` type-checks it through `app-server/tsconfig.json` (Node types), next to
`tsconfig.json` and `tests/tsconfig.json`; tests import it (`../app-server/server.ts`).

**Running TypeScript.** Node ≥ 22.18 (and 23.6+) runs `.ts` files directly (`node app-server/server.ts`;
type stripping: no enums or namespaces, relative imports with the `.ts` extension). Older Node 22
needs `node --experimental-strip-types app-server/server.ts`, or compile it first (`tsc`, esbuild).

```ts
import { createServer } from 'node:http';
import { createOlanServer, fromNodeRequest, sendNodeResponse, ToolError } from '@olan-app/sdk/server';

const olan = createOlanServer({
  appId: 'com.example.team-standup',
  privateKeyPem: process.env.OLAN_APP_KEY,          // PKCS#8 Ed25519 (or P-256 / RSA) private key
  issuers: process.env.OLAN_ISSUERS!.split(','),    // every Olan server you accept: always explicit
});

createServer(async (req, res) => {
  if (req.url === '/.well-known/jwks.json') return sendNodeResponse(res, Response.json(await olan.jwks()));
  const request = await fromNodeRequest(req);       // raw body: the signature covers the exact bytes
  if (req.url === '/olan/events') {
    return sendNodeResponse(res, await olan.handleEvent(request, {
      'project.task.created': async (event) => { /* event.data.task */ },
    }));
  }
  if (req.url?.startsWith('/olan/ai-tools/')) {
    return sendNodeResponse(res, await olan.handleToolCall(request, {
      standup_summary: async (input, ctx) => {
        const r = await fetch(`${ctx.issuer}/api/v2/projects/${input.projectId}`,
          { headers: { authorization: `Bearer ${ctx.token.accessToken}` } });
        if (!r.ok) throw new ToolError('not_found', 'Proje bulunamadı');
        return { result: await r.json(), summary: 'Standup özeti hazır' };
      },
    }));
  }
  if (req.url === '/olan/card-actions') {
    return sendNodeResponse(res, await olan.handleCardAction(request, async (action) => ({ toast: { text: 'Kaydedildi' } })));
  }
  if (req.url === '/olan/requests') {                // olan.remote.request (remote-requests.md)
    return sendNodeResponse(res, await olan.handleRequest(request, {
      'GET /standups/:day': async (ctx) => ({ body: await loadStandup(ctx.user!.organizationId, ctx.params.day) }),
    }));
  }
  res.writeHead(404).end();
}).listen(4100);
```

**Always pass `issuers` explicitly**, e.g. `[process.env.OLAN_ISSUER]` with the `apps.issuer` of the
Olan server's `/.well-known/olan` (Olan's cloud: `https://api.olan.app`). The default
`DEFAULT_ISSUERS` is `['https://api.olan.app']` only (since SDK 1.5; `https://olan.app` before):
self-hosted and development servers are never in it, and requests from an issuer that is not
listed are rejected.

Other helpers: `handleRequest` (remote-requests.md), `appReturnUrl({ issuer, installationId })` and
`isAppReturnUrl({ issuer, installationId, url })` for external flows (links.md), `RequestError`,
`matchRemoteRoute` and `runRemoteRoute` (the router `handleRequest` uses).

`await generateAppKey()` (async, WebCrypto) makes a new Ed25519 key: `{ privateKeyPem, publicJwk,
keyId }`; `jwks()` serves its public half. The `kid` defaults to the key's RFC 7638 thumbprint
(`keyId` overrides it). To replace the key without a gap, see
[Rotating the app key](#rotating-the-app-key).

### `createOlanServer(options)`

| Option | Type | Default | Needed for |
|---|---|---|---|
| `appId` **required** | `string` | — | Everything (`iss`/`sub` of client assertions) |
| `issuers` | `readonly string[] \| ((issuer: string) => boolean)` | `DEFAULT_ISSUERS` (`['https://api.olan.app']`) | Always set it (above) |
| `privateKeyPem` | `string` (PKCS#8 PEM: Ed25519, P-256 or RSA) | — | Only `jwks()`, `getInstallationToken()` and `createClientAssertion()`: without it they throw `OlanServerError('no_private_key')`. **Not** needed to verify: `verify`, `handleRequest`, `handleEvent`, `handleToolCall`, `handleCardAction`, `appReturnUrl` work without it |
| `keyId` | `string` | RFC 7638 thumbprint | `kid` of the key in your JWKS |
| `nextPrivateKeyPem`, `nextKeyId` | `string` | — | Key rotation: `jwks()` publishes this key too, tokens are still signed with `privateKeyPem` ([Rotating the app key](#rotating-the-app-key)) |
| `additionalPublicKeys` | `readonly Jwk[]` (each with `kid`) | — | More public keys for `jwks()`, e.g. the retired key while a rotation finishes; private members are dropped |
| `idempotency` | `IdempotencyStore \| false` | `memoryIdempotencyStore()` | Seen `webhook-id`s: `handleEvent` (24 h, a retry is processed once), `handleRequest` (`req_` ids) and `handleCardAction` (`act_` ids), 10 min each (a repeat is a replay: 409 `duplicate_request`); `false` turns the checks off |
| `toleranceSeconds` | `number` | `300` | Allowed clock skew of `webhook-timestamp` |
| `jwksCacheSeconds` | `number` | `600` | Cache of the issuer's `/.well-known/olan` and JWKS |
| `fetch` | `typeof fetch` | global `fetch` | Tests (a fake issuer) |
| `now` | `() => number` | `Date.now` | Tests (ms since the epoch) |

```ts
/** Share one across processes (Redis SET NX EX, a table with a unique key and an expiry). */
interface IdempotencyStore {
  has(id: string): boolean | Promise<boolean>;
  add(id: string, ttlSeconds: number): void | Promise<void>;
}
```

Types exported by `@olan-app/sdk/server`: `OlanServer` (what `createOlanServer` returns),
`OlanServerOptions`, `IdempotencyStore`, `OlanServerError` (`code`, `status`, `detail?`),
`VerifiedRequest`, `IncomingRequest` (a WHATWG `Request` or `{ headers, body: string | Uint8Array }`),
`InstallationToken`, `ToolHandler`/`ToolContext`/`ToolOutput`/`ToolError`, `EventHandler(s)`/`EventContext`,
`CardActionHandler`, and for `handleRequest`: **`RemoteRoutes`** (the router object,
`Readonly<Record<"METHOD /path", RemoteRequestHandler>>`), `RemoteRequestHandler`
(`(ctx: RemoteRequestContext) => RemoteRequestResult | void | Promise<…>`), `RemoteRequestContext`,
`RemoteRequestResult` (`{ status?, headers?, body? }`), `RequestError`, plus `RemoteRequestEnvelope`,
`RemoteRequestUser`, `RemoteAnswer`. Helpers: `memoryIdempotencyStore()`, `fromNodeRequest(req, { maxBytes? })`
(1 MiB default; keeps `req.url`), `sendNodeResponse(res, response)`, `cardResponse(card?, toast?)`.
Constants: `DEFAULT_ISSUERS`, `WEBHOOK_HEADERS`, `REQUEST_ID_RETENTION_SECONDS`, `PROFILE_REQUIRED`,
`TOKEN_INVALIDATING_EVENTS`, `STALE_TOKEN_ERRORS` ([Calling Olan back](#calling-olan-back)).

```ts
import type { RemoteRoutes } from '@olan-app/sdk/server';
export const routes: RemoteRoutes = { 'GET /items': async (ctx) => ({ body: await list(ctx.installationId) }) };
```

## Verifying Olan's requests

Every request from Olan (events, tool calls, card actions, requests) is signed (Standard Webhooks, asymmetric):

| Header | Value |
|---|---|
| `webhook-id` | `evt_…` / `call_…` / `act_…` / `req_…`: equals the body's `id`; the same on every retry (requests are never retried) |
| `webhook-timestamp` | Unix seconds of this attempt |
| `webhook-signature` | `v1a,<base64 Ed25519 signature of "<id>.<timestamp>.<raw body>">` (several, space-separated, during key rotation) |
| `olan-issuer` | The Olan server, e.g. `https://olan.example.com` |
| `olan-key-id` | `kid` of the signing key in the issuer's JWKS |
| `olan-installation-id` | The installation |
| `olan-event-type`, `olan-delivery-attempt` | Events only |

`olan.verify(request)` checks, in order: the issuer is in `issuers` → the `kid` is in the issuer's
JWKS (found through `<issuer>/.well-known/olan` → `apps.jwksUri`, cached 10 minutes, refetched
at most once a minute for an unknown `kid`) → the signature → the timestamp is within ±5 minutes.
It throws `OlanServerError` (`issuer_not_allowed`, `unknown_key`, `invalid_signature`,
`timestamp_out_of_range`, `missing_header`, `jwks_unavailable`, `invalid_body`); the `handle*`
helpers answer 401 for these. Keep the issuer list explicit: anyone can run "an Olan server".

The signature covers the id, the timestamp and the body, not the URL. The handlers therefore also
check what the body claims against how it arrived:

| Helper | Check | Answer |
|---|---|---|
| all | `body.id === webhook-id` | 400 `invalid_body` |
| `handleRequest` | the envelope's `issuer` equals the `olan-issuer` header (trailing `/` ignored); you map accounts by it | 401 `issuer_mismatch` (400 `invalid_body` without `issuer`) |
| `handleToolCall` | the tool in the URL (`…/ai-tools/{name}`) equals the body's `tool` | 400 `tool_mismatch` |
| `handleRequest`, `handleCardAction` | the `req_` / `act_` id was not seen in the last 10 minutes (Olan never retries them) | 409 `duplicate_request` |
| `handleEvent` | the `evt_` id was not processed in the last 24 h (Olan retries events) | 200 `{ ok: true, duplicate: true }` |

`handleToolCall` knows the URL from a WHATWG `Request` (`request.url`) or from
`fromNodeRequest(req)`, which keeps `req.url`; for a hand-made `{ headers, body }` add `url`
(the path is enough), otherwise only the body names the tool.

## The `/.well-known/olan` document

`GET <issuer>/.well-known/olan` (public, `Cache-Control: public, max-age=300`) describes an Olan
server. App servers need `apps.issuer`, `apps.jwksUri`, `apps.tokenEndpoint` and `webOrigin`
(`createOlanServer` reads them for you); the CLI and Studio read the rest. An Olan 1.5 server answers:

```json
{
  "apiVersion": 1,
  "serverVersion": "1.5.0",
  "sdkVersions": ["^1.0.0"],
  "apps": {
    "enabled": true,
    "maxPackageBytes": 5242880,
    "surfaces": ["app", "project.widget", "settings", "chat.action", "chat.command", "chat.card", "mail.sidebar", "mail.action", "calendar.event.action", "meeting.panel"],
    "permissions": ["projects:read", "projects:write", "…"],
    "trustedKeyFingerprints": ["3f2957e0dbdd6b87"],
    "builtInKeys": [{ "keyId": "olan-marketplace-2026-10-17", "fingerprint": "3f2957e0dbdd6b87" }],
    "trustedKeys": [{ "name": "olan-marketplace-2026-10-17", "publicKey": "Y/CrYSv6RfoVrZCRFUy6c/JGXsGRtVU9fDOQr8SNHEI=", "fingerprint": "3f2957e0dbdd6b87" }],
    "features": ["db", "record-writes", "remote", "events", "ai-tools", "pim-writes", "project-writes", "app-cards", "remote-requests", "files", "external-return", "app-links"],
    "issuer": "https://api.olan.app",
    "jwksUri": "https://api.olan.app/api/v2/apps/jwks.json",
    "tokenEndpoint": "https://api.olan.app/api/v2/apps/oauth/token",
    "events": ["app.installed", "app.updated", "…"],
    "returnUrlTemplate": "https://olan.app/apps/return/{installationId}",
    "appUrlTemplate": "https://olan.app/apps/a/{appId}"
  },
  "webOrigin": "https://olan.app",
  "catalogUrl": "https://api.olan.app/api/v2/apps/catalog",
  "marketplaceUrl": "https://marketplace.olan.app",
  "revocationsUrl": "https://api.olan.app/api/v2/apps/revocations",
  "marketplaceKeysUrl": "https://api.olan.app/api/v2/apps/marketplace-keys",
  "issuer": "https://api.olan.app"
}
```

| Field | Meaning |
|---|---|
| `apiVersion`, `serverVersion`, `sdkVersions` | Discovery version (1), the server's version (`minServerVersion` is checked against it), SDK ranges its host serves |
| `apps.enabled` | Olan Apps are on for this server |
| `apps.maxPackageBytes`, `apps.surfaces`, `apps.permissions` | Package size limit (5 MiB), the surfaces and permission ids it knows |
| `apps.trustedKeyFingerprints`, `apps.builtInKeys`, `apps.trustedKeys` | Package signing keys it trusts (first 16 hex of sha256 of the raw key); `builtInKeys` cannot be removed (cli.md#signing-and-publishing). Developers' registered keys are not listed: each vouches only for its developer's own development installations |
| `apps.features` | Capabilities; `remote-requests`, `files`, `external-return`, `app-links` since 1.5 |
| `apps.issuer` | **The issuer to list in `issuers`** (`OLAN_PUBLIC_URL`; also `olan-issuer` and the envelope's `issuer`) |
| `apps.jwksUri` | The Ed25519 keys that sign Olan's requests to app servers (`kid` = `olan-key-id`) |
| `apps.tokenEndpoint` | Where `getInstallationToken` posts its client assertion |
| `apps.events` | Event types this server delivers |
| `apps.returnUrlTemplate`, `apps.appUrlTemplate` | Return address of external flows and permanent app address (links.md); since 1.5, only when the web origin is configured |
| `webOrigin` | Origin of Olan's web app (`OLAN_WEB_URL`), e.g. `https://olan.app` for the API `https://api.olan.app`: return addresses and the CORS origin of uploads (files.md). Missing before 1.5 (`appReturnUrl` then throws `web_origin_unknown`) |
| `catalogUrl`, `revocationsUrl`, `marketplaceKeysUrl` | Organization catalog, signed revocation list and marketplace key set (authenticated) |
| `marketplaceUrl` | Olan Marketplace this server uses (null from older servers) |
| `marketplaceOwnership` | Only while an ownership proof runs (then `Cache-Control: no-store`): `{ serverId, challenge, token }` |
| `issuer` | Same as `apps.issuer` |

Older servers may lack the newer fields: read them as optional. The CLI's local issuers
(`events send`, `requests send`, `dev --remote live`, `createTestIssuer` in tests) serve the same shape.

## Events

Delivered to `POST {remote.url}/events` with this body (`data` version 1):

```json
{ "id": "evt_…", "type": "project.task.created", "version": 1, "occurredAt": "…", "issuer": "https://olan.example.com",
  "installationId": "…", "appId": "com.example.team-standup", "actor": { "kind": "user", "id": "…" }, "data": { … } }
```

| Event | Permission | Sent for | `data` |
|---|---|---|---|
| `app.installed`, `app.updated`, `app.uninstalled` | none, always sent | the installation | `{ versionId, version, scope, grantedPermissions, organizationId }` (`organizationId`, the tenant id = `user.organizationId` of requests, since Olan 1.5; `uninstalled`: `{}`) |
| `app.consent.changed` | none, always sent | the installation | `{ userId, permissions, declined }` |
| `chat.message.created` | `chat:read` | conversations the app was added to | `{ conversationId, message: { id, body, senderId, senderKind, createdAt, replyToId, threadRootId, attachments } }` |
| `project.task.created`, `project.task.updated` | `projects:read` | projects the app was added to | `{ projectId, task, changed? }` |
| `project.task.deleted` | `projects:read` | projects the app was added to | `{ projectId, taskId, title }` |
| `project.task.completed` | `projects:read` | projects the app was added to (SDK 1.7) | `{ projectId, task, changed }`: the task moved to a completed status (also sent as `project.task.updated`) |
| `project.issue.opened`, `.closed`, `.triaged` | `projects:read` | projects the app was added to (SDK 1.7) | `{ projectId, issue: { id, key, number, title, kind, state, stateReason, priority, assigneeId, labels, triagedAt, … }, decision? }` (`triaged`: `accepted`, `declined`, `duplicate`, `snoozed`) |
| `project.approval.decided` | `projects:read` | only the installation that asked (`olan.project.approvals.request`, SDK 1.7) | `{ projectId, installationId, approvalId, externalId, linkId, state: approved \| rejected \| cancelled, decisions }` |
| `calendar.event.created`, `.updated`, `.deleted` | `calendar:read` | people whose consent includes it | `{ userId, calendarId, eventId, uid, event? }` |
| `meeting.created`, `.started`, `.ended`, `.cancelled` | `meetings:read` | meetings of consenting organizers or of granted projects | `{ meetingId, slug, title, startsAt, endsAt, organizerId, projectId? }` |

- Answer 2xx within 10 s. Anything else is retried after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h,
  6 h and 12 h (±20 %, `Retry-After` honoured for 429/503); `410` stops at once. Order is not guaranteed.
- `handleEvent` skips `webhook-id`s it already processed (in memory; pass `idempotency` with a shared
  store when running several processes) and answers 500 when the handler throws, so Olan retries.
- Bodies over 256 KiB cut `chat.message.created` `body` (`truncated: true`). An app does not get
  events it caused itself.

## Assistant tools (`ai.tools`)

The Olan assistant (and Olan's MCP server) lists the tools of apps the person consented to
(`ai:tools` plus each tool's `permissions`) as `app_<slug>_<name>`, where `slug` is the last part
of the app id in `[a-z0-9]` (≤ 16): `app_teamstandup_standup_summary`.

- Manifest: ≤ 16 tools; `name` `^[a-z][a-z0-9_]{1,31}$`; `title` ≤ 80; `description` 1–1024 (the
  model reads it); `input` a JSON Schema with `"type": "object"` (≤ 8 KiB, only local `$ref`);
  `permissions` ⊆ the manifest's; `readOnly` (runs without confirmation, retried once) or
  `destructive` (always confirmed), not both. Other tools are confirmed by the person first.
- Request body: `{ id: "call_…", tool, installationId, appId, issuer, channel: "assistant" | "mcp",
  user: { id, locale, timeZone }, input, token: { accessToken, expiresIn: 300 } }`.
- `timeoutMs` (SDK 1.5): 1000–60000, default 15000; a `readOnly` tool keeps at most 15000
  (`manifest.ai_tool_invalid`). Use it for slow tools that change something (an AI draft).
- Answer HTTP 200 within the tool's timeout: `{ "ok": true, "result": …, "summary"?: "≤ 500" }` or
  `{ "ok": false, "error": { "code", "message" } }`, ≤ 64 KiB. Olan reports `app_tool_timeout`,
  `app_tool_failed` (non-2xx), `app_tool_result_too_large`, `app_tool_unavailable`.
- Tool results are untrusted content for the assistant: writes after them ask for confirmation.

## Card actions

A card's `submit` button (cards.md) posts `{ id: "act_…", issuer, installationId, user: { id, locale },
conversationId, messageId, name, payload, token }` to `{url}/card-actions`; answer within 5 s with
`{ card?, toast? }` (`card` replaces the message's card). Olan sends each action once:
`handleCardAction` answers a repeated `act_` id with 409 `duplicate_request` without running the
handler (ids kept 10 minutes in `idempotency`; share the store across processes).

## Calling Olan back

- **Embedded tokens.** Tool calls and card actions carry `token.accessToken` (300 s, on behalf of the
  person; permissions = the tool's ∩ the person's). Use it as `Authorization: Bearer …` on the routes
  app tokens may call (e.g. `GET <issuer>/api/v2/projects/:projectId`, `…/apps/installations/:id/…`).
- **Installation tokens.** `await olan.getInstallationToken({ issuer, installationId, userId? })` signs
  a client assertion (RFC 7523 `private_key_jwt`: `iss = sub = appId`,
  `aud = <issuer>/api/v2/apps/oauth/token`, ≤ 300 s, single-use `jti`, `olan_installation_id`,
  optional `olan_user_id`) and returns `{ accessToken, expiresIn (≤ 900), permissions }` (cached).
  - Without `userId` (**app identity**): only the app's own `db` collections, `users.get` with
    `users:read`, and the projects and conversations people added the app to (project/chat
    settings → Uygulamalar). Never calendars, contacts, mail, meetings or creating projects.
  - With `userId`: on behalf of that person; fails with `consent_required` until they consented.
  - Errors: `invalid_client` (unknown key, bad signature), `invalid_grant`, `consent_required`.
- **After a grant change.** A cached token keeps the permissions it was issued with (≤ 15 min), so
  after a new version or a consent change the first call needing a new permission would be refused.
  `handleEvent` drops the installation's cached tokens (app identity and every person) on
  `app.updated`, `app.consent.changed` and `app.uninstalled` (`TOKEN_INVALIDATING_EVENTS`) before
  your handler runs. Handling events yourself, or in another process or `createOlanServer` instance
  (one per app id)? Call `olan.invalidateToken(installationId, { issuer? })` (returns how many it
  dropped) or `olan.clearTokenCache()`.
- **`olan.fetchOlan({ issuer, installationId, userId? }, path, init?)`** sends `init` to
  `<issuer><path>` with the installation token (another origin is refused). A 403
  `permission_denied` or `insufficient_scope` (`STALE_TOKEN_ERRORS`: the token predates the grant)
  is retried **once** with a fresh token (bodies must be replayable: string, bytes, `FormData`, …);
  a second refusal and other 403s (`app_project_forbidden`, …) come back unchanged.

## Rotating the app key

Olan verifies your client assertions with the keys at `remote.jwksUrl`, cached 10 minutes and
refetched at most once a minute for an unknown `kid`. Publish the new key before you sign with it:

1. **Publish the next key.** `const next = await generateAppKey()`; store `next.privateKeyPem` as a
   second secret and deploy with
   `createOlanServer({ …, privateKeyPem: CURRENT, keyId: 'app-2026-10', nextPrivateKeyPem: NEXT, nextKeyId: 'app-2027-01' })`.
   `jwks()` now serves both keys (current first); tokens are still signed with the current key.
2. **Wait** at least 10 minutes (Olan's JWKS cache), longer if a CDN caches your `jwksUrl`.
3. **Switch.** Deploy with `privateKeyPem: NEXT, keyId: 'app-2027-01'` and
   `additionalPublicKeys: [{ ...currentPublicJwk, kid: 'app-2026-10' }]` (the old public half,
   e.g. `(await previousServer.jwks()).keys[0]`), so assertions signed by processes that still run
   the old key keep verifying.
4. **Retire.** After every process runs the new key (and at least 5 minutes: an assertion lives
   60 s), drop `additionalPublicKeys` and delete the old secret.

A key that leaked is removed at once instead: switch to the new key without `additionalPublicKeys`.
Tokens issued before stay valid until they expire (≤ 15 minutes). Never reuse a `kid`.

## When the app needs the person's profile

`email`, `displayName` and `role` reach `handleRequest` only with `profile:read`
(remote-requests.md#the-person-user). When a route needs them and they are missing, answer the
generic error `profile_required` (exported as `PROFILE_REQUIRED` by `@olan-app/sdk/server` and
`@olan-app/sdk`) instead of creating an account from `user.id` alone:

```ts
import { PROFILE_REQUIRED, RequestError } from '@olan-app/sdk/server';

'POST /connections/start': async (ctx) => {
  if (!ctx.user?.email) throw new RequestError(409, { error: PROFILE_REQUIRED, message: 'Profil izni gerekli' });
  …
},
```

The app gets a `RemoteError` `remote_rejected` with `status` 409 and
`details.error === PROFILE_REQUIRED`, and explains that the app needs "Profilinizi görme".

## Self-hosted Olan servers

Each Olan server signs with its own key and is its own issuer (`OLAN_PUBLIC_URL`): add every
server you serve to `issuers`. Olan servers that the internet cannot reach still deliver to you,
but embedded tokens only work where your server can reach that Olan. Deliveries follow the
organization's egress rules.

## Developing locally

```sh
npx olan-app events send project.task.created        # signed event to remote.url/events (sample data from fixtures)
npx olan-app events send chat.message.created --data @event-data.json --to http://127.0.0.1:4100/olan
npx olan-app tools call standup_summary --input '{"projectId":"p0"}'
npx olan-app requests send GET "/standups/2026-10-18?team=web"   # olan.remote.request to remote.url/requests
npx olan-app dev --remote live                       # the dev server forwards the app's remote.request calls
```

They sign with your development key and serve its JWKS from a local issuer
`http://127.0.0.1:5180` while the request runs (for `dev --remote live`, while dev runs): add it to
`issuers` in development (`issuers: ['https://olan.example.com', 'http://127.0.0.1:5180']`). The
embedded token is a placeholder (`olan-app-dev-token`); calls back to Olan need a local Olan server.
MCP: `olan_app_event_send`, `olan_app_tool_call`, `olan_app_request_send`. Automated server tests:
`createTestIssuer` and `signRemoteRequest` (remote-requests.md#testing-the-app-server).

<!-- docs/remote-requests.md -->
# Remote requests (`olan.remote.request`)

An app with its own server (`remote`, server.md) can ask that server for data **as the person using
the app** (SDK 1.5). The sandbox never sees a token and the app server never sees Olan's cookie:

```
sandbox ── olan.remote.request ──▶ Olan host ──▶ Olan server ── signed POST {remote.url}/requests ──▶ app server
        ◀── { status, headers, body } ◀────────────────────────── HTTP 200 { status, headers?, body } ◀──
```

Olan checks the installation, the person's consent and the limits, signs an envelope with the
person's identity and a 300 s token, posts it, and passes the app server's answer back. Olan never
retries a request.

## Manifest

```json
"sdk": "^1.5.0",
"remote": { "url": "https://media.example.com/olan", "jwksUrl": "https://media.example.com/olan/jwks.json", "requests": true },
"permissions": ["profile:read"]
```

- `remote.requests: true` turns the call on (default `false`; without it every call fails with
  `permission_denied`, "manifest does not declare remote.requests").
- No permission of its own: it uses the implied `remote` permission. An admin who blocks `remote`
  blocks it (`permission_denied`).
- `profile:read` (optional) adds the person's email, name and role to the envelope (below).
- UI only: backend code (`server`, backend.md) has no `olan.remote`; it uses `olan.http.fetch`.

## Calling it

```tsx
import { isRemoteError, olan, useQuery } from '@olan-app/sdk';

const items = useQuery(() => olan.remote.request({ method: 'GET', path: '/items', query: { status: ['ready', 'processing'] } }), []);
// items.data: { status: 200, headers: { 'content-type': 'application/json' }, body: [...] }

const created = await olan.remote.request({
  method: 'POST',
  path: '/brands/b1/posts',
  body: { text: 'Merhaba' },
  headers: { 'idempotency-key': draftId },
  timeoutMs: 60_000,                 // a slow AI draft; default 30 s
});
```

| Field | Rule |
|---|---|
| `method` **required** | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'` |
| `path` **required** | Starts with `/`, ≤ 2048, no `?`, `#`, `\`, `//`, `.`/`..` segments, encoded `/` or control characters. Put parameters in `query`, encode segments with `encodeURIComponent` |
| `query` | `Record<string, string \| number \| boolean \| (string \| number \| boolean)[]>`, ≤ 50 keys (≤ 128 characters each), ≤ 100 values per key. The app server gets strings (`true` → `"true"`) |
| `headers` | Only `accept`, `accept-language`, `if-match`, `if-none-match`, `idempotency-key` (names lower-cased, values one line ≤ 1024). Others: `invalid_params` |
| `body` | Any JSON value, ≤ 1 MiB serialised (`payload_too_large`); not with `GET` and `DELETE` |
| `timeoutMs` | Integer 1000–60000, default 30000 |

The result (`RemoteResponse`) is `{ status, headers: { 'content-type'?, etag? }, body }` for an app
server status **200–399**. `body` is the app server's JSON as it is (`null` when it had none).

## Errors: `RemoteError`

Every failure rejects with a `RemoteError` (a subclass of `OlanError`, so `isOlanError` is true too):

| `code` | When | `status` | `details` |
|---|---|---|---|
| `remote_rejected` | The app server answered 400–499 | its status | its `body` |
| `remote_unavailable` | The app server answered 500–599 (`reason: 'http_status'`), or no usable answer: `reason` `timeout`, `network`, `invalid_response` (not the wrapper below, not JSON, HTTP status other than 200), `response_too_large` (> 4 MiB) | its status, else `0` | its `body`, else `null` |
| `consent_required` | The person has not consented to the app yet | `403` | `null` |
| `permission_denied` | No `remote.requests`, or `remote` is blocked by policy | `403` | `null` |
| `feature_not_enabled` | The organization's plan does not include the app's feature | `403` | `null` |
| `payload_too_large` | `body` over 1 MiB | `413` | `null` |
| `rate_limited` | Over 300 requests a minute, or 8 at once, per person and installation; `retryAfterSeconds` says when to retry | `429` | `null` |
| `invalid_params` | A field breaks the rules above | `400` | `null` |
| `not_installed`, `cancelled`, `host_error`, `unknown_method` | As for every call (errors.md); `unknown_method` on an Olan server before 1.5 | | |

```tsx
try {
  await olan.remote.request({ method: 'POST', path: '/items', body: draft });
} catch (error) {
  if (isRemoteError(error, 'remote_rejected') && error.status === 422) {
    setIssues((error.details as { issues?: Issue[] } | null)?.issues ?? []);   // the server's 422 body
  } else if (isRemoteError(error, 'remote_unavailable')) {
    setBanner(error.reason === 'timeout' ? 'Sunucu yanıt vermedi' : 'Sunucuya ulaşılamıyor');
  } else throw error;
}
```

`RemoteError`: `code`, `message`, `status: number`, `details: JsonValue`, `reason?` and
`retryAfterSeconds?`. `isRemoteError(error, code?)` narrows an unknown error. In `useQuery` the
`RemoteError` is in `query.error`.

## The app server: `handleRequest`

```ts
import { createOlanServer, RequestError } from '@olan-app/sdk/server';

const olan = createOlanServer({
  appId: 'com.example.media-desk',
  privateKeyPem: process.env.OLAN_APP_KEY,
  issuers: (process.env.OLAN_ISSUERS ?? '').split(',').filter(Boolean),   // always explicit
});

// POST {remote.url}/requests
const response = await olan.handleRequest(request, {
  'GET /items': async (ctx) => ({ body: await listItems(ctx.user!.organizationId) }),
  'POST /items': async (ctx) => ({ status: 201, body: await createItem(ctx.user!, ctx.body) }),
  'GET /items/:id': async (ctx) => {
    const item = await findItem(ctx.params.id);
    if (!item) throw new RequestError(404, { error: 'item_not_found' });
    return { body: item, headers: { etag: `"${item.revision}"` } };
  },
  'GET /files/*': async (ctx) => ({ body: await describe(ctx.params['*']) }),   // the rest of the path
});
```

`request` is a WHATWG `Request`, or `{ headers, body: Uint8Array }` from `fromNodeRequest(req)`
(server.md); the answer is a `Response` (`sendNodeResponse(res, response)` in Node).

- `handleRequest(request, router)` verifies the request (below), checks the envelope (`id` equals
  `webhook-id`, `installationId`, `appId`, `request.method`, `request.path`; `issuer` equals the
  `olan-issuer` header, else HTTP 401 `{ error: 'issuer_mismatch' }`), refuses a repeated
  `req_` id with **HTTP 409** `{ error: 'duplicate_request' }` (ids are kept 10 minutes in the
  `idempotency` store; pass a shared one when you run several processes), then routes.
- Routes are `"METHOD /path"`: `:name` matches one segment (decoded into `ctx.params.name`), a
  trailing `/*` the rest (`ctx.params['*']`), `*` as the method any method. The first matching route
  in declaration order wins: list specific routes first. `router` may also be one function.
- Unknown path: `status: 404` `{ error: 'unknown_route' }`; known path, other method: `status: 405`
  `{ error: 'method_not_allowed' }`. Both are wrapped (HTTP 200), so the app sees `remote_rejected`.
- A route returns `{ status?, headers?, body? }` (`status` default 200, 200–599; `body` default
  `null`). `throw new RequestError(status, body?, headers?)` answers that status; any other
  exception answers `status: 500` `{ error: 'internal_error' }` (the app sees `remote_unavailable`).
- Answer within the request's `ctx.timeoutMs` (default 30 s, at most 60 s): Olan gives up then.

The route context (`RemoteRequestContext`):

| Field | |
|---|---|
| `id` | `req_<uuid>`, also the `webhook-id` |
| `issuer` | The Olan server (`https://api.olan.app` for Olan's cloud) |
| `installationId`, `appId` | The installation that called |
| `user` | `{ id, organizationId, locale, timeZone, email?, displayName?, role? }`; `null` for an app-identity call (none in SDK 1.5: every request comes from a person) |
| `method`, `path`, `params` | The request and the route's parameters |
| `query` | `Record<string, string \| string[]>` (normalised) |
| `headers` | Only the allowed request headers, lower-case |
| `body` | JSON, `null` when none |
| `token` | `{ accessToken, expiresIn: 300 }` on behalf of the person: call Olan back (server.md#calling-olan-back) |
| `timeoutMs` | What the app asked for |

### The person (`user`)

- `user.id` is the central Olan user id (the OIDC `sub` of "Olan ile giriş yap") and
  `user.organizationId` the tenant id. Map them to your accounts as `(issuer, user.id)` and
  `(issuer, user.organizationId)`: ids are unique per issuer only.
- `locale` (`tr`, `en-US`) and `timeZone` (IANA) are always present.
- `email`, `displayName` and `role` are present **only** when the person's permissions include
  `profile:read` (permissions.md); otherwise the keys are missing. `email` is the Olan account's
  address (verified by Olan). `displayName` is missing when the person has none. `role` is
  `'admin'` (organization admins) or `'member'`.
- Without `profile:read`, do not create accounts from `user.id` alone if you need an email; answer
  the generic `409 { error: 'profile_required' }` (`throw new RequestError(409, { error: PROFILE_REQUIRED })`,
  server.md#when-the-app-needs-the-persons-profile) and let the app explain it: it gets
  `remote_rejected` with `error.details.error === PROFILE_REQUIRED` (exported by `@olan-app/sdk`).
- No `user` means the app identity (Phase 3 tokens): never act on behalf of a person then.

## The envelope

`POST {remote.url}/requests` (the installation's `remoteUrlOverride` applies), signed like events
(server.md#verifying-olans-requests):

```
POST https://media.example.com/olan/requests
content-type: application/json
webhook-id: req_5f0c2a8e-1b7d-4c31-9b0e-2f7d8c1a9e44
webhook-timestamp: 1792310400
webhook-signature: v1a,<base64 Ed25519 signature of "<webhook-id>.<webhook-timestamp>.<raw body>">
olan-issuer: https://api.olan.app
olan-key-id: olan-apps-2026-10-17
olan-installation-id: 6d3f8e2a-0c4b-4f7e-9a51-3b2c1d0e9f87
```

```json
{
  "id": "req_5f0c2a8e-1b7d-4c31-9b0e-2f7d8c1a9e44",
  "issuer": "https://api.olan.app",
  "installationId": "6d3f8e2a-0c4b-4f7e-9a51-3b2c1d0e9f87",
  "appId": "com.example.media-desk",
  "user": { "id": "0b7a1c2d-…", "organizationId": "9c8b7a6d-…", "locale": "tr", "timeZone": "Europe/Istanbul",
            "email": "utku@example.com", "displayName": "Utku Gökcan", "role": "admin" },
  "request": { "method": "POST", "path": "/brands/b1/posts", "query": { "draft": "true", "channel": ["instagram", "tiktok"] },
               "headers": { "idempotency-key": "c1f2" }, "body": { "text": "Merhaba" }, "timeoutMs": 60000 },
  "token": { "accessToken": "eyJhbGciOi…", "expiresIn": 300 }
}
```

No `olan-event-type` or `olan-delivery-attempt` header. Verify in this order: issuer in your
allowlist → `kid` in the issuer's JWKS → signature over the raw bytes → timestamp within ±5 minutes
→ `body.id === webhook-id` → `body.issuer` is the `olan-issuer` header → the `req_` id not seen in the last 10 minutes (a repeat is a replay,
since Olan never retries). `handleRequest` does all of it.

## The answer: the JSON wrapper

To every **verified** request the app server answers **HTTP 200**, `content-type: application/json`:

```json
{ "status": 201, "headers": { "content-type": "application/json", "etag": "\"v7\"" }, "body": { "id": "post_9", "status": "draft" } }
```

- `status`: the app's own status, an integer 200–599 (404 "no such brand", 422 validation …).
- `headers`: optional; Olan passes only `content-type` and `etag` to the app.
- `body`: any JSON value, `null` when none. The raw answer is ≤ 4 MiB.
- A request that fails verification gets **HTTP 401** `{ error, message }` without the wrapper; a
  malformed envelope HTTP 400; a replayed id HTTP 409.
- Any HTTP status other than 200, a body that is not the wrapper, more than 4 MiB or no answer in
  time is `remote_unavailable` for the app (`reason`: `http_status`, `invalid_response`,
  `response_too_large`, `timeout`, `network`).

The wrapper keeps your own statuses apart from transport failures (a 401 signature error, a 502
proxy, a missing `/requests` route). A server that already has an HTTP API can forward the request
internally and wrap that answer (`{ status: res.statusCode, headers: res.headers, body: res.json() }`).

Without the SDK (another language), follow the same rules: verify as above, answer the wrapper,
keep seen ids 10 minutes.

## Limits

| Limit | Value |
|---|---|
| Request body | 1 MiB (JSON) |
| App server answer | 4 MiB |
| Timeout | 30 s default, 1–60 s |
| Rate | 300 a minute and 8 at once per person and installation (`rate_limited`, `Retry-After`) |
| Path / query | 2048 characters / 50 keys, 100 values per key |
| Replay window | Keep `req_` ids ≥ 10 minutes |

Olan writes an audit row per request (`remote.request { method, status, durationMs, errorCode? }`);
paths, queries, headers and bodies are never stored.

## Issuers: always pass them explicitly

`createOlanServer({ issuers })` decides which Olan servers you accept. Always set it, e.g.
`issuers: [process.env.OLAN_ISSUER]` with the `apps.issuer` of the Olan server's
`/.well-known/olan` (Olan's cloud: `https://api.olan.app`). The default (`DEFAULT_ISSUERS`,
`['https://api.olan.app']`) is Olan's cloud only; self-hosted and development servers (e.g.
`http://localhost:4000`, the CLI's `http://127.0.0.1:5180`) are never in it, and a request from an
issuer that is not listed is rejected (`issuer_not_allowed`, HTTP 401).

## Testing

**The app.** `renderApp({ remote })` runs `olan.remote.request` against routes in the same
`"METHOD /path"` format (or `fixtures/remote.json` answers), with the same wrapper and `RemoteError`
mapping; `app.host.remoteRequests` holds each envelope and answer (testing.md#remote-requests-files-and-links).
Pass your server's own routes object to test the UI against the real route code.

### Testing the app server

`@olan-app/cli/testing` has a local Olan issuer for server tests (`olan-app init --template remote`
writes this test): `createTestIssuer()` serves `/.well-known/olan` (with `webOrigin`) and the JWKS
of a fresh Ed25519 key on `127.0.0.1` and returns `{ issuer, keyId, jwk, wellKnown(), sign(), close() }`;
`signRemoteRequest(issuer, input, options?)` returns `{ headers, body, envelope }`, exactly what Olan
posts to `{remote.url}/requests`. Your server lists `issuer.issuer` in `issuers` and verifies the
requests over the real JWKS: no mocks, no private key on the app server.

```ts
import assert from 'node:assert/strict';
import { after, before, test } from 'node:test';

import { createTestIssuer, signRemoteRequest, type TestIssuer } from '@olan-app/cli/testing';
import { createOlanServer } from '@olan-app/sdk/server';

import { routes } from '../app-server/routes.ts';

let issuer: TestIssuer;
before(async () => { issuer = await createTestIssuer(); });     // { webOrigin?, port?, keyId? }
after(() => issuer.close());

test('routes a signed request', async () => {
  const olan = createOlanServer({ appId: 'com.example.media-desk', issuers: [issuer.issuer] });
  const signed = signRemoteRequest(issuer, {
    appId: 'com.example.media-desk',
    request: { method: 'POST', path: '/items', body: { title: 'Lansman' } },
    // installationId (default 'mock-installation'), user (default the mock person; null = no user), token, id
  });
  const response = await olan.handleRequest({ headers: signed.headers, body: signed.body }, routes);
  assert.equal(response.status, 200);                                    // HTTP 200 + the wrapper
  assert.equal(((await response.json()) as { status: number }).status, 201);
  // Over HTTP instead: await fetch(`${baseUrl}/olan/requests`, { method: 'POST', headers: signed.headers, body: signed.body })
});

test('refuses forged requests', async () => {
  const olan = createOlanServer({ appId: 'com.example.media-desk', issuers: [issuer.issuer] });
  const forged = (options: Parameters<typeof signRemoteRequest>[2]) =>
    olan.handleRequest(signRemoteRequest(issuer, { appId: 'com.example.media-desk', request: { method: 'GET', path: '/items' } }, options), routes);
  assert.equal((await forged({ badSignature: true })).status, 401);                               // invalid_signature
  assert.equal((await forged({ timestamp: Math.floor(Date.now() / 1000) - 600 })).status, 401);  // timestamp_out_of_range
  assert.equal((await forged({ issuer: 'https://evil.example' })).status, 401);                   // issuer_not_allowed
  assert.equal((await forged({ keyId: 'other' })).status, 401);                                   // unknown_key
  assert.equal((await forged({ webhookId: 'req_other' })).status, 400);                           // id ≠ webhook-id
});
```

- `input.user` defaults to `{ id: DEFAULT_USER_ID, organizationId: DEFAULT_ORGANIZATION_ID, locale: 'tr',
  timeZone: 'Europe/Istanbul' }` (no profile fields); pass `email`/`displayName`/`role` to test
  `profile:read`, `null` for an envelope without a person.
- `input.request` is normalised like Olan does (`query` values become strings, header names
  lower-case); params Olan would refuse throw. Each call gets a new `req_` id; sending the same
  `signed` twice is a replay (409).
- The signature covers `body` byte for byte: send it unchanged.
- Types: `TestIssuer`, `TestIssuerOptions`, `RemoteRequestSignInput`, `RemoteRequestSignOptions`
  (`timestamp`, `badSignature`, `keyId`, `issuer`, `webhookId`), `SignedRemoteRequest`.
- By hand: `olan-app requests send POST /items --body '{"title":"Lansman"}'` against the running
  server (cli.md), or `olan-app dev --remote live` for the whole app.

## Integration checklist (an existing service as the app server)

1. Manifest: `"sdk": "^1.5.0"`, `"remote": { "url", "jwksUrl", "requests": true }`, `profile:read`
   if you map people by email, `files:pick` for uploads (files.md).
2. `POST {remote.url}/requests`: `handleRequest` (or the same rules), issuers from configuration
   (`https://api.olan.app`), a shared `idempotency` store if you run more than one process.
3. Map the person: `(issuer, user.id)` → your account, `(issuer, user.organizationId)` → your
   workspace. `email`/`displayName`/`role` only with `profile:read`; without them, do not create
   accounts: answer a 4xx the app can explain.
4. No `user` = the app identity: never act as a person.
5. Route only an allowlist of your API (`"GET /brands"`, `"POST /brands/:brandId/posts"` …); forward
   internally and wrap the answer. Your 4xx bodies (e.g. 422 `{ issues }`) reach the app as
   `RemoteError.details`.
6. Answer within the app's `timeoutMs`; long jobs (AI drafts, campaign creation) send
   `timeoutMs: 60000`, or answer 202 and let the app poll (`useQuery(…, { refetchIntervalMs })`, hooks.md).
7. Uploads: issue a one-time upload URL on the `remote.url` origin (or a host the manifest grants
   as `http:<host>`), read the name from `x-olan-file-name`, allow CORS from Olan's web origin (files.md).
8. Images (`Image`, `Avatar`) come from the `remote.url` origin or an `http:<host>` host (components.md).
9. External sign-in (OAuth of a network): build the return address with
   `olan.appReturnUrl({ issuer, installationId })`, keep and check your own `state`, accept a
   caller-given `returnUrl` only when `olan.isAppReturnUrl(…)` is true (links.md).
10. `app.installed` / `app.updated` events carry `organizationId`: link the installation to the
    workspace there (server.md#events).

<!-- docs/files.md -->
# Files (`olan.files`)

SDK 1.5: the person picks files with the platform's own picker, and the app uploads them **straight
from the device or browser to its own server**, never through Olan. The sandbox only gets handles;
the bytes stay with the host. Needs the `files:pick` permission ("Dosya seçtirme": the app can read
the files the person picks and upload them; it cannot reach their other files).

```tsx
import { Button, ProgressBar, olan, type FileHandle, type UploadTask } from '@olan-app/sdk';

const picked = await olan.files.pick({ accept: ['image/*', 'video/mp4', '.mov'], multiple: true, maxBytes: 300 * 1024 * 1024 });
if (picked.length === 0) return;                                   // the person cancelled

const { body } = await olan.remote.request({ method: 'POST', path: '/media/uploads', body: { name: picked[0]!.name, size: picked[0]!.size } });
const { uploadUrl } = body as { uploadUrl: string };               // one-time URL on the remote.url origin

const task = olan.files.upload(picked[0]!, {
  url: uploadUrl,                                                  // PUT by default
  onProgress: ({ loaded, total }) => setProgress(total > 0 ? loaded / total : 0),
});
setRunning(task);                                                  // <Button label="İptal" onPress={() => task.cancel()} />
const result = await task;                                         // { status, headers, body }
if (result.status >= 300) throw new Error(`Yükleme reddedildi (${result.status})`);
```

## `olan.files.pick(options?)` → `FileHandle[]`

| Option | Rule |
|---|---|
| `accept` | ≤ 32 entries: MIME types (`image/jpeg`), wildcards (`image/*`, `video/*`) or extensions (`.pdf`). Default: any file |
| `multiple` | Default `false` |
| `maxFiles` | 1–20; default 20 with `multiple`, else 1 |
| `maxBytes` | Per file; default 100 MiB, at most 1 GiB. Larger files are left out of the result (the host tells the person) |
| `source` | `'device'` (the only source in SDK 1.5) |

`FileHandle`: `{ id: 'file_…', name, size, type, lastModified? }`. `type` is
`application/octet-stream` when the platform does not know it; `lastModified` is epoch ms when known.
A handle is valid only while this sandbox runs (not after the app is closed or reloaded); do not
store it. An empty array means the person cancelled.

Pickers: web `<input type="file">`; iOS PHPicker for images and videos and the document picker for
other types; Android the Photo Picker and the system document picker.

## `olan.files.upload(handle, options)` → `UploadTask`

| Option | Rule |
|---|---|
| `url` **required** | The target; see "Where uploads may go" |
| `method` | `'PUT'` (default) or `'POST'` |
| `headers` | ≤ 20, values one line ≤ 4096. Not `host`, `content-length`, `cookie`, `connection`, `transfer-encoding`, `origin`, `referer` or any `x-olan-*` |
| `formField` | POST only: the file's multipart field, default `file` (letters, digits, `_.[]-`) |
| `fields` | POST only: ≤ 50 string fields sent **before** the file |
| `onProgress` | `({ loaded, total }) => void`: at most every 250 ms, and once at the end |

`UploadTask` is a `Promise<FileUploadResult>` with `uploadId` (`upl_…`) and `cancel()`. A handle id
string works in place of the handle. `olan.files.cancel(uploadId)` does the same as `task.cancel()`;
unknown or finished ids are ignored.

- The result is `{ status, headers: { 'content-type'?, etag?, location? }, body }` for **every**
  HTTP status, like `olan.http.fetch`: check `status`. `body` is parsed JSON for a JSON
  `content-type`, else text (≤ 1 MiB).
- Rejections: `cancelled` (after `cancel()`), `upload_failed` (network error, or no progress for
  60 s), `http_blocked` (the target breaks the rule below), `invalid_params` (unknown handle, a
  forbidden header, `formField`/`fields` on a PUT), `permission_denied` (no `files:pick`).
- At most 4 uploads run at once per sandbox; more wait in line. Uploads do not continue after the
  app is closed.

## Where uploads may go

`url` must be `https:` and its origin either:

- the origin of the manifest `remote.url` (with the installation's `remoteUrlOverride`), or
- a host the manifest grants as `http:<host>` (permissions.md; e.g. a separate storage host).

`http:` works only in development installations for loopback and private addresses. URLs with
credentials (`https://user:pw@…`) are refused. Anything else rejects with `http_blocked`.

No cookies are sent (`credentials: 'omit'`): put a one-time token in the URL (or a header) that
your server issued for this upload, e.g. from an `olan.remote.request`.

## What the target receives

Every upload carries `x-olan-file-name: <encodeURIComponent(name)>`. Read the file name from this
header (URL-decoded), never from the multipart `filename`, which browsers change.

**PUT** (default): the body is the file's raw bytes.

```
PUT /olan/uploads/item_7?token=4c1f… HTTP/1.1
content-type: video/mp4                     # handle.type; your headers may replace it
content-length: 5242880
x-olan-file-name: tan%C4%B1t%C4%B1m.mp4
<your headers>

<bytes>
```

**POST**: `multipart/form-data`; the `fields` parts in order, then one file part.

```
POST /olan/uploads HTTP/1.1
content-type: multipart/form-data; boundary=…
x-olan-file-name: kampanya.jpg

--…
Content-Disposition: form-data; name="itemId"

item_7
--…
Content-Disposition: form-data; name="file"; filename="kampanya.jpg"
Content-Type: image/jpeg

<bytes>
--…--
```

**Web (CORS).** In the browser the upload is a cross-origin request from Olan's web origin
(`webOrigin` of the Olan server's `/.well-known/olan`, e.g. `https://olan.app`). The target answers
the preflight and the upload with:

```
Access-Control-Allow-Origin: https://olan.app
Access-Control-Allow-Methods: PUT, POST
Access-Control-Allow-Headers: content-type, x-olan-file-name, <every header you send>
Access-Control-Expose-Headers: etag, location
```

Without `Expose-Headers` the app cannot read `etag` and `location`. iOS and Android do not need CORS.

A Node target is plain HTTP (no Olan signature: the one-time token is the proof): check the token,
read the raw body, answer `201` with JSON (`{ id, url }`), which the app gets as `result.body`.
Show the uploaded media with `Image` from the same origin (components.md#image).

```ts
import { createServer, type IncomingMessage } from 'node:http';

const WEB_ORIGINS = new Set(['https://olan.app']);         // webOrigin of each Olan server you serve
const cors = (req: IncomingMessage): Record<string, string> =>
  WEB_ORIGINS.has(req.headers.origin ?? '')
    ? { 'access-control-allow-origin': req.headers.origin!, 'access-control-allow-methods': 'PUT, POST',
        'access-control-allow-headers': 'content-type, x-olan-file-name', 'access-control-expose-headers': 'etag, location', vary: 'origin' }
    : {};

createServer(async (req, res) => {
  const url = new URL(req.url ?? '/', 'http://localhost');   // path + query: /olan/uploads/item_7?token=4c1f…
  const match = /^\/olan\/uploads\/([\w-]+)$/.exec(url.pathname);
  if (!match) return res.writeHead(404).end();
  if (req.method === 'OPTIONS') return res.writeHead(204, cors(req)).end();               // CORS preflight (web)
  if (req.method !== 'PUT') return res.writeHead(405, cors(req)).end();
  if (!takeUploadToken(match[1]!, url.searchParams.get('token'))) return res.writeHead(403, cors(req)).end();
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);                           // the raw file bytes (PUT)
  const bytes = Buffer.concat(chunks);                                                   // stream to storage for big files
  const name = decodeURIComponent(String(req.headers['x-olan-file-name'] ?? 'file'));    // never the multipart filename
  const type = req.headers['content-type'] ?? 'application/octet-stream';
  await saveFile(match[1]!, { name, type, bytes });
  res.writeHead(201, { ...cors(req), 'content-type': 'application/json', etag: `"${bytes.length}"`, location: `/olan/media/${match[1]}` });
  res.end(JSON.stringify({ id: match[1], name, size: bytes.length }));
}).listen(4100);
```

`olan-app init --template remote` has this target (with a size limit) in `app-server/server.ts`
and tests for the preflight and the one-time token. A POST target parses `multipart/form-data`
(e.g. `busboy`); the `fields` come before the file part.

## Limits

| | |
|---|---|
| File size | `maxBytes`, default 100 MiB, at most 1 GiB per file (your server may allow less) |
| Files per pick | 20 |
| Parallel uploads | 4 per sandbox |
| Stall timeout | 60 s without progress → `upload_failed` |
| Response body | 1 MiB |

## Testing

`fixtures/files.json` lists what the picker offers (`[{ "name", "type"?, "size"?, "content"? }]`;
built in: `kampanya.jpg`, `tanitim.mp4`, `brief.pdf`). `renderApp({ ui: { files: ['kampanya.jpg'] } })`
picks those (`null` or `[]` cancels), `renderApp({ upload })` answers uploads, and
`app.host.uploads` records each request with its headers (testing.md#remote-requests-files-and-links).

<!-- docs/links.md -->
# External links, sign-in flows and app addresses

SDK 1.5 (`olan.ui.openUrl`, `olan.ui.openExternal`, permanent app addresses). No permission is
needed.

## `olan.ui.openUrl(url)`

Opens a page in the platform browser and resolves at once: a new tab on the web, the default
browser on desktop, the system browser on iOS and Android.

```ts
await olan.ui.openUrl('https://media.example.com/items/7');
```

## `olan.ui.openExternal(url, { expectReturn? })`

For flows that come back to the app: connecting an account, OAuth of another service, a payment
page. It opens the system browser, never an embedded web view: a new tab on the web, the default
browser on desktop, `ASWebAuthenticationSession` on iOS, Custom Tabs on Android.

```ts
const result = await olan.ui.openExternal(authorizeUrl, { expectReturn: true });
if (result.returned) {
  // result.params: the return address's query, e.g. { state: 'st_91', connection: 'connected' }
  await olan.remote.request({ method: 'POST', path: '/connections/complete', body: result.params });
}
```

- Result: `{ returned: true, params: Record<string, string> }` or `{ returned: false }`.
- `expectReturn` defaults to `false`: the call resolves `{ returned: false }` as soon as the page opens.
- With `expectReturn: true` it resolves when the flow reaches the app's return address, or
  `{ returned: false }` when the person closes it (iOS cancel), another `openExternal` of the same
  installation starts (one pending flow per installation) or 30 minutes pass.
- URL rule (also for `openUrl`): `https:`; `http:` only for loopback and private addresses in
  development installations; no credentials. Other schemes: `invalid_params`.
- When the host cannot tie the call to the person's tap (a pop-up blocker on the web), it asks
  first ("Bağlantı açılsın mı?").

## The return address

```
https://<webOrigin>/apps/return/<installationId>?state=<your state>&<other params>
```

- `webOrigin` is the Olan web app's origin (`https://olan.app` while the API is
  `https://api.olan.app`), published in the issuer's `/.well-known/olan` (below).
- Your **server** builds it and puts it in the flow (e.g. OAuth `redirect_uri` of your own callback,
  which then redirects here):

  ```ts
  // in a handleRequest route (remote-requests.md)
  'POST /connections/start': async (ctx) => {
    const state = await saveState({ installationId: ctx.installationId, userId: ctx.user!.id });
    const returnUrl = await olan.appReturnUrl({ issuer: ctx.issuer, installationId: ctx.installationId });
    return { body: { authorizeUrl: `https://media.example.com/connect?state=${state}&return=${encodeURIComponent(returnUrl)}` } };
  },
  ```

  `olan.appReturnUrl({ issuer, installationId })` (`@olan-app/sdk/server`) reads `webOrigin` from
  the issuer's `/.well-known/olan` (cached; the issuer must be in `issuers`; an Olan server before
  1.5 has none: `web_origin_unknown`). `appReturnUrl(webOrigin, installationId)` of
  `@olan-app/schema` builds it when you already know the origin.
- When something else gives you a return URL (a client, a query parameter), accept it only when
  `await olan.isAppReturnUrl({ issuer, installationId, url })` is true: same origin, exactly
  `/apps/return/<installationId>`, any query, no credentials.
- `state` is yours: create it on your server, check it when the flow comes back. Olan passes it
  through untouched.
- `params`: the query parameters as strings; the last of repeated keys wins; at most 50 keys and
  4 KiB; the fragment (`#…`) is ignored. Never put secrets in them.

### Coming back without a pending call

If no `openExternal` is waiting (the app was closed, the tab reloaded, the phone killed the app),
Olan opens the app's `app` surface with the parameters as `params.return`:

```tsx
function Home() {
  const returned = useSurfaceParams<'app'>()?.return;      // { state, connection, … } or undefined
  useEffect(() => { if (returned?.state) void completeConnection(returned); }, [returned?.state]);
  …
}
```

On the web the return page hands the parameters to the waiting tab (`BroadcastChannel`) and
closes itself; without a waiting tab it opens `/apps/<installationId>` with `return`. On iOS and
Android the return address is a universal link / App Link that brings Olan to the front.

## App addresses: `/apps/a/<appId>`

Every app has a permanent address, the same for every organization and installation:

```
https://<webOrigin>/apps/a/<appId>[/<screen>]?<params>
https://olan.app/apps/a/com.example.media-desk/item?id=item_7
```

- Olan finds the person's installation of `appId` and opens its `app` surface (not installed: a
  link to the store page; plan without the app: "planınızda yok"). On iOS and Android it opens Olan.
- `screen` (`^[A-Za-z0-9_-]{1,64}$`, default `index`) and the query (strings, ≤ 50 keys, ≤ 4 KiB)
  become the start of the navigation stack (`init.navigation`):
  - `index`: the first screen's `useNavigation().params` are the query parameters;
  - another screen: the stack is `[index, <screen>]` with the params on `<screen>`; the back
    control returns to the first screen.

```tsx
function App() {
  const { screen, params } = useNavigation();
  const p = (params ?? {}) as { id?: string };
  if (screen === 'item' && p.id) return <ItemScreen id={p.id} />;    // /apps/a/<appId>/item?id=…
  return <Home />;
}
```

Use it in emails, chat cards (`open` buttons go to the app anyway), notifications and your own
web pages. `appLinkUrl(webOrigin, appId, { screen?, params? })` and `parseAppLink(url)` of
`@olan-app/schema` build and read them. Test with `renderApp({ navigation: { screen: 'item', params: { id: 'item_7' } } })`.

## `/.well-known/olan` (Olan 1.5)

```json
{
  "webOrigin": "https://olan.app",
  "apps": {
    "issuer": "https://api.olan.app",
    "returnUrlTemplate": "https://olan.app/apps/return/{installationId}",
    "appUrlTemplate": "https://olan.app/apps/a/{appId}",
    "features": ["…", "remote-requests", "files", "external-return", "app-links"]
  }
}
```

`features` tells an app server what this Olan server supports; a server without `remote-requests`
answers `olan.remote.request` with `unknown_method`.

## Testing

`renderApp({ ui: { openExternal: { returned: true, params: { state: 'st_1', connection: 'connected' } } } })`
answers `openExternal(…, { expectReturn: true })` (default `{ returned: false }`);
`app.host.opened` lists `{ url, external, expectReturn }` of every opened URL;
`renderApp({ params: { return: { state: 'st_1' } } })` opens the `app` surface as a return without a
pending call (testing.md#remote-requests-files-and-links).

<!-- docs/backend.md -->
# Backend code (`server`)

An app may ship backend code that **Olan runs** on its own server: functions the UI calls,
schedules (cron), event handlers and incoming webhooks (hooks). Use it for work that must happen
while nobody has the app open, or that needs a secret. (Your *own* server is `remote`, server.md.)

```jsonc
// olan-app.json
"server": {
  "entry": "server/index.ts",
  "schedules": [{ "name": "digest", "cron": "*/5 * * * *", "timeZone": "Europe/Istanbul" }],
  "events": { "project.task.created": "onTaskCreated" },
  "hooks": [{ "name": "github",
              "verify": { "kind": "hmac-sha256", "header": "x-signature-256", "secretSetting": "hookSecret" } }]
}
```

```ts
// server/index.ts
import { defineBackend, olan } from '@olan-app/sdk/backend';

export default defineBackend({
  // Only what the UI calls (olan.backend.call): everything here is callable from the UI.
  functions: { async summary(args, ctx) { return { count: await olan.db.collection('records').count() }; } },
  // Trigger handlers, keyed by the manifest name.
  schedules: { digest: async (ctx) => { /* ctx.schedule, ctx.scheduledAt */ } },
  events: { 'project.task.created': async (event, ctx) => { /* event.data.task */ } },
  hooks: { github: async (request, ctx) => ({ status: 204 }) },
});
```

In the UI: `const result = await olan.backend.call<Summary>('summary', args)` (no permission).
Full example: `examples/ops-inbox` in the Olan repository.

## Runtime model

- `olan-app build` bundles `server.entry` into `dist/server.js`: one script (esbuild IIFE,
  `globalName: '__olanBackendModule'`, ES2022) with `@olan-app/sdk/backend` inside. Its default
  export must be `defineBackend({ … })`. `pack` adds it to the package (covered by `digest.json` and
  the signature).
- Olan runs it in an isolated sandbox (`@olan-app/runtime`): **isolated-vm** (a V8 isolate) in a
  separate runtime process, or **QuickJS** (WebAssembly) where isolated-vm has no build (Intel Mac,
  Windows ARM; ~10–30× slower on CPU-heavy code). One sandbox per installation; globals may survive
  between calls but are dropped at any time: keep state in `olan.db`.
- Available: ES built-ins, `console.*`, `setTimeout`/`clearTimeout`, `queueMicrotask`,
  `TextEncoder`/`TextDecoder` (UTF-8), `atob`/`btoa`, and `olan.*`. **Not available**: Node modules
  (`fs`, `crypto`, `http`, …), `process`, `require`, `fetch`, `setInterval`, `URL`, `WebAssembly` and
  `Atomics` (by decision: WebAssembly memory escapes the sandbox's memory limit, `Atomics.wait` blocks
  without using CPU time). `olan-app build` fails on Node imports (`build.backend_node_import`).
- **Known limitation**: on servers with a separate Identity service, backend calls to Olan APIs
  (`olan.db`, `olan.projects`, …) fail with `host_error` for now; `secrets`, `settings` and `http.fetch` work.
- **Timers** only run while their call runs: a timer due after the call's deadline never fires and
  pending timers are cancelled when the call returns. Periodic work is a `schedules` entry.
- **Identity**: `backend.call` runs as the calling person with their consented permissions
  (`ctx.identity = { actor: 'user', userId, permissions }`); schedules, events and hooks run as the
  app (`actor: 'app'`, `userId: null`; the app identity sees only projects and chats the app was
  added to, server.md).
- `ctx = { installationId, appId, identity, signal }`. `signal` never aborts: at the deadline Olan
  tears the sandbox down, so nothing of that call runs afterwards.

## Handler resolution

| Trigger | Handler | Arguments |
|---|---|---|
| `olan.backend.call(name, args)` | `functions[name]` only | `(args, ctx)` |
| schedule | `schedules[schedule.name]`, else `functions[schedule.function]` | `(ctx & { schedule, scheduledAt })`, fallback `({ schedule, scheduledAt }, ctx)` |
| event | `events[type]`, else `functions[server.events[type]]` | `(event, ctx)` |
| hook | `hooks[hook.name]`, else `functions[hook.function]` | `(request, ctx)` |
| update | `migrate(fromVersion, ctx)` once after an update, before other calls | |
| lifecycle (`app.installed`, `app.updated`, `app.consent.changed`, `app.uninstalled`) | `events[type]`, else `functions[server.events[type]]`; none: ignored | `(event, ctx)` |

No handler → `not_found` (`backend_function_not_found` in the UI). `olan-app validate` loads
`dist/server.js` in the runtime and fails with `validate.backend_handler_missing` for every
schedule, event or hook without a handler.

Lifecycle events reach every backend, no subscription needed; `app.uninstalled` runs once, just
before the installation is removed (Olan waits ≤ 10 s). **A failed `migrate` is not done**: until it
succeeds, every call of the new version answers `backend_migrating` (503). Olan retries after 30 s,
2 min, 10 min, 30 min and 1 h (6 attempts in all), then an admin or developer retries it (Studio → Backend).

**Put trigger handlers in `schedules` / `events` / `hooks`**, never in `functions`. `function` of a
schedule or hook is optional (a fallback for older apps); the value of `server.events[type]` is
required by the manifest shape but only used as a fallback. **A function named as such a fallback
is not callable from the UI**: `olan.backend.call` answers `backend_function_not_found`, exactly as
for a missing one (on the Olan server, in `olan-app dev`, `renderApp` and `createBackendHarness`).
So the UI can never run a hook handler without its signature check, or a schedule as the person.

## `olan.*` in the backend

Same names, parameters and permissions as in the UI (api.md); each call is checked against the
invocation identity. Host errors throw `OlanBackendError` with `.code` (`permission_denied`,
`http_blocked`, `conflict`, `forbidden_record`, `validation_failed`, `not_found`, …).

| Call | Permission |
|---|---|
| `olan.secrets.get(name)` → `string \| null` | none (only `secret: true` settings) |
| `olan.settings.get()` (secret fields are `null`) | none |
| `olan.db.collection(name)` → `insert`, `get`, `query`, `update`, `delete`, `count` | `db` |
| `olan.http.fetch(url, { method?, headers?, body? })` → `{ status, headers, body, json() }` | `http:<host>` |
| `olan.projects.list/get/tasks/createTask/updateTask/deleteTask/deleteList/create/archive` | as in the UI |
| `olan.users.get(ids)` | `users:read` |
| `olan.chat.conversations/messages/postCard/updateCard` | `chat:read` / `chat:write` |
| `olan.calendar.calendars/events/createEvent/updateEvent/deleteEvent` | `calendar:*` |
| `olan.contacts.addressBooks/search/create/update/delete` | `contacts:*` |
| `olan.meetings.get(meetingId)` | `meetings:read` |
| `olan.project.config`, and (SDK 1.7) `olan.project.statuses/labels/links/calendar/activity/approvals`, (SDK 1.8) `olan.project.fields` | as in the UI (api.md); only projects the app was added to |

Not in the backend: `olan.ui.*`, `olan.navigation.*` (no screen), `olan.storage.*` (per person; use
`olan.db`), `olan.mail.getMessage` (bound to an opened mail surface), `olan.backend.call`.
Importing `@olan-app/sdk/backend` into the UI works for types; its `olan.*` rejects with
`backend_unavailable` there.

## Secrets

`"secret": true` settings of apps that declare `server` never reach the UI: `olan.settings.get()`
and `useSettings()` give `null` for them. Read them in the backend with `olan.secrets.get(name)`
and never return them from a function (return `configured: true` instead). Apps without `server`
keep the old behaviour (the UI receives the value). Locally the values come from
`fixtures/settings.json`: put only dev-only test secrets there (it is not packed). The test tools
record backend calls with secret values replaced by `"[secret]"` (testing.md#backend-tests).

## Schedules

`schedules`: ≤ 10, five-field cron (`minute hour day-of-month month day-of-week`), at least 5
minutes apart, `timeZone` IANA (default UTC). Runs as the app. On a DST change day a run at a
skipped local time does not happen, and one in the repeated hour runs once. Studio's Backend tab has
"Şimdi çalıştır"; locally:
`POST <dev>/backend/schedules/<name>/run`.

## Events

`server.events` maps catalogue event types (server.md#events) to handlers; each needs its
permission (`project.task.*` → `projects:read`, …) and follows the same scope rules as
`remote` events. Delivery retries like webhooks. The handler gets the envelope
`{ id, type, version, occurredAt, installationId, appId, actor, data }`.

## Hooks (incoming webhooks)

`POST /api/v2/apps/hooks/<installationId>/<name>`, body ≤ 1 MiB, 120 requests/min per
installation. Olan verifies the request **before** the function runs:

| `verify.kind` | Check |
|---|---|
| `hmac-sha256` | `verify.header` = `sha256=<hex>`: HMAC-SHA256 over the **raw body bytes** with the `secretSetting` value (hex in any case; the `sha256=` prefix is optional) |
| `standard-webhooks` | `webhook-id`, `webhook-timestamp` (± 5 min), `webhook-signature` `v1,<base64>` (`whsec_` secrets) |
| `none` | development installations only (Studio / `olan-app dev`, or signed with a development key) |

Use a generic header such as `x-signature-256` for your own senders (`x-hub-signature-256` for
GitHub). Sign the exact bytes you send:

```sh
BODY='{"ref":"main"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
# node -e 'console.log(require("crypto").createHmac("sha256",process.env.SECRET).update(process.argv[1]).digest("hex"))' "$BODY"
curl -X POST "$URL" -H 'content-type: application/json' -H "x-signature-256: sha256=$SIG" --data-binary "$BODY"
```

Failures answer `401 hook_verification_failed` (missing secret: `503 hook_secret_missing`). The
function gets `{ method, headers (lower-case), body (raw text), query }` and may return
`{ status, headers?, body? }` within 10 s: `status` 200–599; a string `body` is sent as is
(default `text/plain`), any other JSON value as `JSON.stringify(body)` (default `application/json`);
only `content-type`, `cache-control`, `etag`, `last-modified` and `x-*` headers are kept. Anything
else (no return value, no valid `status`) or no answer within 10 s → `202`; a thrown error → `500`.
`verifyHookSignature` / `signHookRequest` in `@olan-app/sdk/server` implement the same checks.

## Limits

| Limit | Default | Ceiling |
|---|---|---|
| CPU per call (also after `await` and in timers) | 1000 ms | 5000 ms |
| Wall clock, `backend.call` | 10 s | 30 s |
| Wall clock, schedules, events, hooks | 30 s | 30 s |
| Memory (isolate heap) | 64 MiB | 128 MiB |
| Calls at once per installation | 4 | 8 |
| Arguments and result | 256 KiB, JSON only (`undefined` → `null`) | |
| Console | 1000 lines per call, 4 KiB per line | |

Admins may change the defaults per organization, never past the ceilings (`BACKEND_LIMITS` in
`@olan-app/schema`). A limit only stops that call.

## Error codes (`olan.backend.call` → `OlanError.code`)

| Code | Meaning |
|---|---|
| `backend_function_not_found` | No `functions[name]`, or `name` is a trigger's fallback function |
| `backend_error` | The function threw (`message` is its error) or `dist/server.js` does not load |
| `backend_limit` | CPU, wall-clock or memory limit |
| `backend_busy` | Too many calls at once for this installation |
| `payload_too_large` | Arguments or result over 256 KiB |
| `backend_unavailable` | The app has no `server`, or backends are turned off on this server (`OLAN_APPS_BACKEND=0`; the manifest then fails with `manifest.feature_not_available`) |
| `backend_migrating` | The new version's `migrate` has not succeeded yet (`attempts`, `nextAttemptAt`) |

## Logs

`console.log/info/warn/error` lines of every invocation appear in Studio → the app → Backend
(kept 7 days), with each call's trigger, status, CPU and wall time. `olan-app dev` prints them
(`[backend log] …`), the test harness returns them (`result.logs`).

## Local development

```sh
npx olan-app build                    # dist/app.js + dist/server.js
npx olan-app validate --strict        # loads dist/server.js, checks every handler (--engine quickjs|isolated-vm)
npx olan-app test                     # UI tests + tests/*.backend.test.ts (createBackendHarness; --engine)
npx olan-app dev                      # backend runs locally on the mock host; --engine quickjs|isolated-vm
```

`olan-app dev` (cli.md#dev-server): `olan.backend.call` from the preview reaches the local
backend (the Studio preview of an uninstalled app has no installation, so there
`olan.backend.call` fails with `backend_unavailable`: use `olan-app dev` or install the app);
`POST /backend/call` `{ name, args }`, `POST /backend/schedules/<name>/run`,
`POST /backend/events/<type>` `{ data? }`, `POST /hooks/<name>` (verified with the secret from
`fixtures/settings.json`). Where isolated-vm cannot load, the engine falls back with the warning
`isolated-vm prebuild not available on <platform>; using QuickJS (slower)`.

Tests: `createBackendHarness` (testing.md#backend-tests). `renderApp` also runs the backend for
`olan.backend.call`, on the same mock database.

<!-- docs/testing.md -->
# Testing

`olan-app test` runs `tests/**/*.test.ts` with Node's test runner (`node:test`). Each test renders
the app headlessly with `renderApp` from `@olan-app/cli/testing`: your real `src/app.tsx`, the real
SDK runtime and React reconciler, against a mock Olan host that answers `olan.*` from fixtures and
enforces permissions exactly like Olan. No browser, no screenshots: you assert on text, the UI
tree and the recorded `olan.*` calls.

```ts
import assert from 'node:assert/strict';
import { test } from 'node:test';

import { renderApp } from '@olan-app/cli/testing';

test('lists projects and opens one', async () => {
  const app = await renderApp({ surface: 'app' });
  app.expectText('Web sitesi');
  await app.press('Web sitesi');                       // List item title
  assert.deepEqual(app.navigation(), [{ action: 'push', screen: 'project', params: { projectId: 'p0' } }]);
  app.expectText('Görev 2');
  await app.dispose();
});
```

Run: `npx olan-app test` (all), `npx olan-app test overdue` (files whose path contains
`overdue`), `--json` for a summary `{ files, tests, passed, failed, skipped, durationMs, failures }`.
Set `OLAN_APP_TEST_LOGS=1` to print the app's `console.*` output. Always `await app.dispose()`.

For Olan Marketplace: `npx olan-app test --report test-report.json` packs the app **first** (like
`pack`, into `.olan-app/report/`), runs the whole suite (no pattern) and writes a report bound to
that package's `digest.package` and signed with your development key; failing runs write it too
and exit 1. Make it after your last source change and attach it with `publish --marketplace
--test-report test-report.json` (marketplace.md#signed-test-reports).

## renderApp(options?)

Bundles the app (cached per run), boots the runtime, opens the surface and resolves after the
first render and its `olan.*` calls have settled. It **throws** if the surface reports an error
(unless `allowErrors: true`).

| Option | Default | Notes |
|---|---|---|
| `surface` | `'app'` | Any surface (surfaces.md) |
| `params` | built from the fixtures ("Surface params in tests" below); `null` for `app`/`settings` | Surface params (`useSurfaceParams`); a given value replaces the default entirely (no merge) |
| `fixtures` | — | Overrides per key over `fixtures/*.json` over the built-in data |
| `permissions` | the manifest's `permissions` plus the implied `remote` / `ai:tools` | Granted permissions; `[]` to test denial. An explicit list replaces the manifest's, but `remote` stays granted when the manifest has `remote.requests` (it is implied, never listed): `permissions: ['files:pick']` still reaches the app server. Block it with `remote: false` |
| `settings` | — | Over the manifest defaults and `fixtures/settings.json` |
| `ui` | `confirm → true`, `prompt/menu/datePicker → null`, `files` → the `fixtures/files.json` files `accept` allows, `openExternal` → `{ returned: false }` | Answers for `olan.ui.*` and the file picker: a value or `(params) => value` (below) |
| `remote` | the `fixtures/remote.json` routes | The app server behind `olan.remote.request`: `remote({ 'GET /items': (ctx) => ({ body: […] }) })` or one handler (below). `false`: the implied `remote` permission is not granted (an admin blocked it): every call fails with `permission_denied` |
| `upload` | `200`, no body | `MockUploadHandler` = `(upload: MockUpload) => MockUploadAnswer \| Promise<MockUploadAnswer>`: the upload target's answer to `olan.files.upload`; throw to fail it (`upload_failed`), never settle to keep it running (cancel recipe below) |
| `profileRole` | `'member'` | `user.role` of remote envelopes when `profile:read` is granted |
| `navigation` | — | `{ screen, params? }`: open on a screen as a permanent app address does (`/apps/a/<appId>/<screen>?…`, links.md) |
| `now` | real clock | Freezes `Date.now()`/`new Date()` in the app: ISO string, `Date` or ms. Also starts the host clock: `olan.db`/task timestamps are `now` + 1 s per write |
| `userId` | `'00000000-0000-4000-8000-000000000001'` ("Utku") | The signed-in user: `useUser().id` and the mock host's user (`createdBy` of new rows and tasks, owner of `user` rows, `owner` rules) |
| `quota` | `{ rows: 100000, bytes: 104857600 }` | `olan.db` limits `{ rows?, bytes? }` (bytes = rows as UTF-8 JSON); over it → `quota_exceeded` |
| `deleteOwnRecordsOnly` | `false` | Admin switch "only delete records it created": `deleteTask` works only on tasks this app created, `deleteList` never (`forbidden_record`) |
| `locale` / `theme` / `platform` | `'tr'` / `'light'` / `'web'` | Host context |
| `allowErrors` | `false` | Keep going on app errors; read them with `errors()` |
| `timeoutMs` | `5000` | Max time for an action to settle |
| `backend` | `true` with `server` | `olan.backend.call` runs the real backend (`server.entry`) on the same mock host and database; `false` → `backend_unavailable`; `{ engine }` picks the engine. `secret: true` settings are `null` for the UI (`backendLogs()` has the backend's console lines) |
| `secrets` | the secret settings' values | `olan.secrets.get` values for the backend. Precedence: `secrets[name]` (even `null`), else the `secret: true` setting from `settings` over `fixtures/settings.json` over the manifest default |
| `root` / `entry` | app dir / `src/app.tsx` | Rarely needed (`olan-app test` sets the root) |

## The rendered app

| Method | What it does |
|---|---|
| `await press(label)` | Presses a `Button` (label), `List` item (title), `Table` row (any cell text), `Menu` item (label), `Screen`/`Card` action (label), `EmptyState` action (label), `Form` submit/cancel label. Exact text first, then case-insensitive; a `RegExp` also works. Several targets with the label: the **first in document order** is pressed (a `Screen` action comes before the screen's content); if it is disabled/loading, `press` fails instead of trying the next, so give targets distinct labels. No match: it lists what can be pressed |
| `await fill(label, value)` | Types into a `TextField` (or sets a `DatePicker`/`Select`) found by `label`, else `name`; fires `onChange({ value })` |
| `await select(label, value)` | Picks a `Select` option by `value` or option label; fires `onChange`. On a `MultiSelect` a string toggles that option and an array sets the whole selection (`onChange({ value: string[] })`) |
| `await toggle(label)` | Flips a `Switch` found by label (`onChange({ value: !value })`); fails when it is disabled |
| `await dismiss(text?)` | Presses a `Banner`'s close button (`onDismiss`): the `Banner` whose `title` or `text` matches (exact, then case-insensitive; or a `RegExp`), else the first on screen. Fails when there is none or it has no `onDismiss` |
| `await fireTimers()` | One tick of every running `useQuery(…, { refetchIntervalMs })` timer, as the host sends them (the mock host never ticks on its own) |
| `remote(handler)` | Replaces the app server behind `olan.remote.request` for the next calls (`null`: back to `fixtures/remote.json`) |
| `await submit(submitLabel?)` | Submits a `Form` (first one, or the one with that `submitLabel`) with the current field values |
| `await back()` | The host's back control (pops the navigation stack) |
| `await setParams(params)` | New surface params, as the host sends them to an open panel (`mail.sidebar`, `meeting.panel`) |
| `await setContext({ theme?, locale?, settings? })` | Context change from the host |
| `expectText(text)` / `expectNoText(text)` | Visible text contains / does not contain (`string` = substring, whitespace-normalised; or `RegExp`). Failure messages list the visible text |
| `await waitForText(text, ms = 2000)` / `await waitFor(predicate, ms)` | For timers and slow chains; usually not needed (actions already settle) |
| `text()` | All visible text as **one string**, pieces joined with `\n` (`app.text().split('\n')` for lines) |
| `tree()` | Visible nodes in document order: `UiNode[]` = `{ id, type, props: Record<string, PropValue>, children: NodeId[] }[]`. Prop values are `PropValue` (JSON or handler refs): cast with `as unknown as` (below) |
| `snapshot()` | Nested `{ type, props, children }` (handlers appear as `{ $handler: n }`) |
| `find(type, predicate?)` | Nodes of a component type, e.g. `app.find('Badge')`; same `UiNode` shape as `tree()` |
| `calls(method?, { source? })` | `olan.*` calls: `MockCall[]` = `{ method, params, ok, result?, error?: { code, message, details? }, source: 'ui' \| 'backend' }[]` (`details`, e.g. `{ status, body?, reason? }` of a failed `remote.request`). With a backend, the `olan.*` calls its code made are included (`source: 'backend'`, secret values redacted; `{ source: 'ui' }` keeps only the UI's). `params` is the RPC's named object, not the positional arguments: `olan.projects.updateTask('p1', 't1', { status: 'completed', revision: 2 })` is recorded as `{ projectId: 'p1', taskId: 't1', status: 'completed', revision: 2 }`. `params`/`result` are typed `JsonValue`: cast them (below). Method names: below |
| `toasts()` | `{ text, tone? }[]` from `olan.ui.toast` |
| `navigation()` | `{ action: 'push' \| 'pop' \| 'replace', screen?, params? }[]` |
| `logs()` / `errors()` | Console output `{ level, args }[]` / app errors `{ message, stack?, fatal? }[]` |
| `host` | The mock host: `await host.handle(method, params)` → `{ ok: true, result } \| { ok: false, error: { code, message, details? } }` (an RPC as the UI sends it, permission-checked and recorded; `{ backend: true }` as backend code), `host.data` (live data, shapes below), `host.db` (the in-memory database; `host.db.as('u2').insert({ collection, data })` writes as another user), `host.permissions`, `host.ui`, `host.shares`, `host.audit()` (`{ action, detail }[]`: deletions and refused deletions, as in Olan's audit log), `host.remoteRequests`, `host.uploads`, `host.opened`, `host.timers()` (below) |
| `await settle()` | Wait until rendering and calls are idle |
| `await dispose()` | Unmount and free timers |

"Visible text" includes `Text`, titles and subtitles, `List` titles/subtitles/meta/badges, empty
texts, `Table` headers and cells, `Badge`, `Button` and `Menu` labels, field labels and values,
`EmptyState` texts and `Chart` series names; also `Tabs` labels, `Switch` labels and descriptions,
the `MultiSelect` label and the selected options' labels (else its placeholder), `Stat` label, raw
value (`1250.5`, not the formatted text; `null` is "—") and caption, `Banner` title, text and action
label, and the `ProgressBar` label. `Image` and `Avatar` add no text (check them with `find`).
`Menu` items are not visible until opened, but `press('<item label>')` selects them; `press` also
selects a `Tabs` item (by label) and a `Banner` action; `dismiss(text?)` closes a `Banner`.

### Recorded method names

`calls(method)` filters by RPC name, the `olan.*` path without `olan.`:

| Area | Methods (params) |
|---|---|
| Projects | `projects.list` (`{ limit?, cursor? }`), `projects.get` (`{ projectId }`), `projects.tasks` (`{ projectId, status? }`), `projects.createTask` (`{ projectId, title, listId?, … }`), `projects.updateTask` (`{ projectId, taskId, revision, … }`), `projects.deleteTask` (`{ projectId, taskId, revision }`), `projects.deleteList` (`{ projectId, listId, revision }`) |
| Database | `db.insert` (`{ collection, data }`), `db.get` (`{ collection, id }`), `db.query` (`{ collection, where?, orderBy?, limit?, cursor? }`), `db.update` (`{ collection, id, patch, revision }`), `db.delete` (`{ collection, id, revision? }`), `db.count` (`{ collection, where? }`); `useCollection`/`useRecord` record `db.query`/`db.get` |
| Projects (Phase 3) | `projects.create` (`{ title, description? }`), `projects.archive` (`{ projectId }`) |
| Project extensions (SDK 1.6–1.7) | `project.config.get/set`, `project.statuses.list/define/remove`, `project.labels.list/define/remove`, `project.fields.list/define/remove/values/setValues` (SDK 1.8), `project.links.list/upsert/remove/setStatus`, `project.calendar.list/upsert/remove`, `project.activity.post`, `project.approvals.list/request/cancel` (`{ projectId, … }`: the call's arguments by name, e.g. `{ projectId, linkId, statusKey }`) |
| Users | `users.get` (`{ ids }`, one call per 100 ids) |
| Chat | `chat.conversations` (`{}`), `chat.messages` (`{ conversationId, limit? }`), `chat.postCard` (`{ conversationId, card, threadRootId? }`), `chat.updateCard` (`{ messageId, card }`) |
| Calendar | `calendar.calendars` (`{}`), `calendar.events` (`{ from, to, calendarId?, limit? }`), `calendar.createEvent` (the input object), `calendar.updateEvent` (`{ eventId, patch }`), `calendar.deleteEvent` (`{ eventId }`) |
| Contacts | `contacts.addressBooks` (`{}`), `contacts.search` (`{ query, limit? }`), `contacts.create` (the input object), `contacts.update` (`{ contactId, patch }`), `contacts.delete` (`{ contactId }`) |
| Mail, meetings, backend | `mail.getMessage` (`{ messageId }`), `meetings.get` (`{ meetingId }`), `backend.call` (`{ name, args }`) |
| Remote, files, links (SDK 1.5) | `remote.request` (`{ method, path, query?, headers?, body?, timeoutMs? }`; a failure's `error.details` is `{ status, body?, reason? }`), `files.pick` (the options), `files.upload` (`{ uploadId, fileId, url, method?, headers?, formField?, fields? }`), `files.cancel` (`{ uploadId }`), `ui.openUrl` (`{ url }`), `ui.openExternal` (`{ url, expectReturn? }`), `timers.set`/`timers.clear` (`useQuery` refresh) |
| Other | `storage.get/set/remove/keys`, `settings.get`, `http.fetch`, `ui.confirm/prompt/toast/menu/datePicker/share`, `navigation.push/pop/replace` (also from `useNavigation()`) |

```ts
const params = app.calls('db.insert')[0]!.params as { collection: string; data: { title: string } }; // JsonValue → cast
assert.equal(params.data.title, 'Rapor');
const task = app.calls('projects.createTask')[0]!.result as { id: string; title: string };
const items = app.find('List')[0]!.props.items as unknown as { key: string; title: string }[]; // PropValue → cast
assert.equal(items[0]!.title, 'Görev 1');
```

Tests are type-checked: `olan-app validate` (also with `--strict`) runs `tsc --noEmit` on
`tsconfig.json` and `tests/tsconfig.json`, so a missing cast is a `typescript.*` error there.
`olan-app test` only bundles the tests and does not type-check.

### `host.data`

| Key | Shape |
|---|---|
| `projects` | `ProjectDetail[]`: `{ project: Project, members: ProjectMember[], lists: ProjectTaskList[], tasks: ProjectTask[] }[]`, **not** the flat fixture shape: `host.data.projects[0]!.project.name`, `host.data.projects[0]!.tasks[1]!.status` |
| `db` | `{ "<collection>": DbRow[] }`, every user's rows, oldest first; a fresh copy on each read (write through the app or `host.db`) |
| `storage` / `settings` / `http` | `{ "<key>": value }` / `{ "<setting>": value }` / `{ "<url>": { status?, headers?, body?, json? } }` |
| `conversations` / `messages` | `Conversation[]` / `{ "<conversationId>": Message[] }` |
| `projectConfigs` | `{ "<projectId>": ProjectConfig }` (SDK 1.6) |
| `recordLinks`, `projectStatuses`, `projectLabels`, `projectIssues`, `projectCalendarItems`, `projectApprovals` | by project id (SDK 1.7): the app's links, every status (defaults included), labels, issues, the app's calendar items, its approval requests (oldest first) |
| `projectFields`, `projectFieldValues` | by project id (SDK 1.8): every custom field; values by `<kind>:<id>` of the task or issue, then field id |
| `taskStatusIds` | `{ "<taskId>": "<statusId>" }`: where each task stands (status ids are `<projectId>-status-<key>`) |
| `projectActivity` | `{ "<projectId>": { type, text, target, actorId, at }[] }`: what the app put in the feed (`APP_ACTIVITY`, `APP_RECORD_LINKED`, `APP_RECORD_UNLINKED`, `APP_APPROVAL_REQUESTED`, `APP_APPROVAL_DECIDED`, `TASK_STATUS_CHANGED`, `ISSUE_STATE_CHANGED`, `PROJECT_UPDATED`) |

Mutating `app.host.data` changes what the next `olan.*` call returns:

```ts
app.host.data.http[URL] = { status: 200, json: { services: [] } };
await app.press('Tekrar dene');
```

## Fixtures

The mock host serves, key by key: `renderApp({ fixtures })` over `fixtures/*.json` over the
built-in data. Built-in projects: `p0` "Web sitesi", `p1` "Mobil uygulama", `p2` "Ofis taşınması",
each with tasks `<id>-t0`…`<id>-t3` titled "Görev 1"…"Görev 4", due `2026-10-10`…`2026-10-13`, the
first `completed` and the rest `needs-action`. No chats, storage, settings or HTTP responses by
default. Calendar: `cal-0` (default) with `ev-0` (the user organizes it), `ev-meeting` (an Olan
meeting, UID `mt-0@olan.app`, protected) and `ev-invite` (an invitation), and the project calendar
`cal-p0` (`ev-p0`, protected). Contacts: `ab-0` (own, default) with `ct-0`, `ab-company` (shared,
read-only) with `ct-company`. Mail: `mail-0` "Teklif hakkında". Meetings: `mt-0`. A key you provide replaces the built-in one entirely (e.g. your `projects` replace all
three).

| File | Content |
|---|---|
| `fixtures/projects.json` | `[{ "id", "name", "description"?, "timeZone"? (IANA, default `"Europe/Istanbul"`), "archived"? (default `false`), "tasks"?: [{ "id", "title", "status"?, "due"?, "assigneeId"?, "description"?, "revision"? }] }]` or `{ "projects": [...] }` |
| `fixtures/chat.json` | `{ "conversations": [{ "id", "title"?, "kind"? }], "messages": { "<conversationId>": [{ "id", "body", "sender"?: { "id", "displayName" } }] } }` |
| `fixtures/settings.json` | `{ "<setting>": value }` |
| `fixtures/storage.json` | `{ "<key>": value }` (initial `olan.storage`) |
| `fixtures/http.json` | `{ "<url>": { "status"?: 200, "headers"?: {}, "body"?: "text" , "json"?: {} } }` |
| `fixtures/users.json` | `[{ "id", "displayName", "email", "title"?, "department"?, "team"? }]` or `{ "users": [...] }`: people `olan.users.get` knows besides the default user (`fixtures.users_invalid`) |
| `fixtures/calendar.json` | `{ "calendars": [{ "id", "name", "color"?, "isDefault"?, "mayWrite"?, "projectId"? }], "events": [{ "id", "title", "start", "end"?, "calendarId"?, "uid"?, "isAllDay"?, "isOrganizer"?, "location"?, "createdByApp"? }] }` (`projectId` = a project calendar) |
| `fixtures/contacts.json` | `{ "addressBooks": [{ "id", "name", "isDefault"?, "shared"? }], "contacts": [{ "id", "name", "addressBookId"?, "emails"?, "phones"?, "organization"? }] }` |
| `fixtures/mail.json` | `[{ "id", "subject", "threadId"?, "from"?: { "name", "email" }, "to"?: [{ "name", "email" }], "cc"?: [same], "receivedAt"?, "textBody"?, "attachments"?: [{ "name", "type", "size" }] }]` or `{ "messages": [...] }`. `name` may be `null`; `receivedAt` is an ISO date-time. Defaults: `threadId: null`, `from`: the default user (Utku, `utku@example.com`), `to`/`cc`/`attachments`: `[]`, `receivedAt: "2026-10-16T09:00:00.000Z"`, `textBody: ""` |
| `fixtures/meetings.json` | `[{ "id", "title", "startsAt", "endsAt"?, "slug"?, "organizerId"?, "participants"?, "projectId"? }]` or `{ "meetings": [...] }` |
| `fixtures/db.json` | `{ "<collection>": [{ "id"?, "data", "createdBy"?, "createdAt"?, "updatedAt"?, "revision"? }] }` (initial `olan.db` rows; `createdBy` defaults to the default user (also with another `userId`), times to `now` (else `2026-10-16T09:00:00Z`), `revision` to 1). Rows must match the manifest `data` schema (`fixtures.db_invalid`, `fixtures.db_unknown_collection`) |
| `fixtures/remote.json` | `{ "GET /items": { "status"?: 200, "headers"?: {}, "body"?: … }, "GET /items/:id": { … } }`: canned answers of the app server to `olan.remote.request`, keyed like `handleRequest` routes (the wrapper of remote-requests.md). Used when no `renderApp({ remote })` is given; `validate --strict` and `dev` use it too (`fixtures.remote_missing`) |
| `fixtures/files.json` | `[{ "name", "type"?, "size"?, "content"?, "lastModified"? }]` or `{ "files": [...] }`: what the file picker offers. `type` defaults from the extension (else `application/octet-stream`), `size` from `content` (else 1024). Built in: `kampanya.jpg` (image/jpeg), `tanitim.mp4` (video/mp4, 5 MiB), `brief.pdf` |

Missing task fields get defaults: `status: "needs-action"`, `due: null`, `revision: 1`,
`assigneeId: null`, `description: ""`, `createdBy`: the default user, `listId` = the first list. Projects
without `"members"` get `[{ "userId": <default user>, "displayName": "Utku", "role": "owner" }]`; without
`"lists"`, one list `{ "id": "<projectId>-l0", "name": "Görevler" }`. A `projects.json` entry may
give `"lists"` and `"members"`, or use the `ProjectDetail` shape `{ "project", "members", "lists", "tasks" }`.

SDK 1.6 (project extensions): every fixture project has the app enabled unless it says
`"enabled": false`: such a project is left out of `olan.projects.list`, and calls naming it fail with
`project_not_enabled`, as on a server. `"config": { … }` is the stored `olan.project.config` value
(revision 1); after a `set` the mock host keeps the new one in `app.host.data.projectConfigs[projectId]`.

SDK 1.7: every fixture project has the default statuses `todo` "Yapılacak", `in_progress` "Devam
ediyor", `done` "Tamamlandı" and `cancelled` "İptal" (ids `<projectId>-status-<key>`); its tasks
start on the one of their `status`. A project may add what the app already contributed — each the
app's own unless it says `"app": false`:

```json
{ "id": "office", "name": "Ofis", "taskKeyPrefix": "OFS",
  "issues": [{ "id": "i1", "title": "Klima bozuk", "number"?: 1, "state"?: "open", "inTriage"?: false }],
  "statuses": [{ "key": "awaiting-approval", "name": "Onay bekliyor", "category": "started", "color"?: "#E0A526" }],
  "labels": [{ "key": "hardware", "name": "Donanım", "groupName"?: "Tür" }],
  "fields": [{ "key": "size", "name": "Boyut", "type": "select", "options"?: [{ "id"?: "large", "name": "Büyük" }], "required"?: false, "appliesTo"?: ["task"] }],
  "fieldValues": [{ "target": { "kind": "task", "id": "t1" }, "values": { "size": "large" } }],
  "links": [{ "id": "link-1", "target": { "kind": "task", "id": "t1" }, "externalId": "SAT-7", "card": { …record card… } }],
  "calendarItems": [{ "externalId": "SAT-7", "title": "Teslim", "start": "2026-11-10", "linkId"?: "link-1" }],
  "approvals": [{ "id": "a1", "title": "SAT-7 onayı", "approverIds": ["<member id>"], "mode"?: "any", "state"?: "pending", "linkId"?: "link-1" }] }
```

The mock host answers `olan.project.*` with the server's checks and codes (keys, taken names,
record cards that only `open`, limits, approvers who are project members other than `guest`).
`app.host.decideApproval(projectId, approvalId, 'approve' | 'reject', { userId?, note? })` decides
as an approver would (`any`: the first decision; `all`: a rejection or the last approval).
Links, calendar items and approvals carry the manifest's `id` and `name` (`appId`, `name`) and
`installationId: MOCK_INSTALLATION_ID`.

### Surface params in tests

Without `params`, `renderApp` builds what the host would send from the (merged) fixtures:

| Surface | Default params |
|---|---|
| `project.widget`, `project.tab`, `project.settings` | `{ projectId }` of the first project the app is enabled in (`p0`) |
| `task.action` | that project's first task: `{ projectId, task: { id, key (default null), title, status, statusId, statusCategory, assigneeId, due } }` |
| `issue.action` | that project's first issue (built-in: `p0-i1`): `{ projectId, issue: { id, key, number, title, kind, state, stateReason, inTriage } }` |
| `record.card` | the app's first link in that project: `{ projectId, linkId, target, externalId, payload: null }` (none: a sample `link-0` on the first task) |
| `chat.action` | the first conversation (else `conversation-0`) and its last message `{ id, body, senderId: sender.id, senderKind: "user", createdAt, threadRootId: null }` (no messages: a sample `message-0` "Yarın 10:00 standup") |
| `chat.command` / `chat.card` | `{ conversationId, text: "", threadRootId: null }` / `{ conversationId, messageId: "card-message-0", payload: null }` |
| `mail.sidebar`, `mail.action` | the **first** `mail.json` entry with defaults applied: `id` → `messageId`; `threadId`, `subject`, `from`, `to`, `cc`, `receivedAt` copied (`textBody`/`attachments` only via `olan.mail.getMessage`). Built-in: `{ messageId: "mail-0", threadId: "thread-0", subject: "Teklif hakkında", from: { name: "Ayşe Yılmaz", email: "ayse@example.com" }, to: [{ name: "Utku", email: "utku@example.com" }], cc: [], receivedAt: "2026-10-16T09:00:00.000Z" }`. An empty `mail.json` (`[]`) gives `messageId: "mail-0"`, `subject: ""`, `from: { name: null, email: "someone@example.com" }` |
| `calendar.event.action` | the first event with `isOrganizer` (default `true`), else the first event: built-in `ev-0`; missing event fields default to `calendarId`: the default calendar, `uid: "<id>@example.com"`, `end = start`, `isAllDay`: `start` has no time, `timeZone`/`location`: `null` |
| `meeting.panel` | the first meeting (`mt-0`): `{ meetingId: id, slug (default: id), title, startsAt, endsAt (default null), role: "organizer" when `organizerId` (default `DEFAULT_USER_ID`) is the signed-in user, else "participant", projectId (default null) }` |

`mail.getMessage` answers only for the current `messageId` (others: `permission_denied`) and needs
the entry in `mail.json` (`not_found` otherwise). Test another email with
`renderApp({ surface: 'mail.sidebar', fixtures: { mail: [{ id: 'm1', subject: 'Fatura', from: { name: null, email: 'muhasebe@firma.com' } }] } })`
or, in an open panel, `await app.setParams({ ...params, messageId: 'm1' })`.

Users: the signed-in user is `DEFAULT_USER_ID` = `00000000-0000-4000-8000-000000000001`, "Utku"
(`utku@example.com`; exported with `DEFAULT_USER` from `@olan-app/cli/testing`); `renderApp({ userId })`
changes it (`useUser().id` follows). `olan.users.get` answers from the default user plus
`fixtures/users.json`; other ids are left out. Other people: add them to `users.json`, list them in a
project's `members`, seed rows with their `createdBy`, or act as them with `app.host.db.as(id)`.

Ids: the built-in project, task and list ids (`p0`, `p0-t0`, `p0-l0`) are **not UUIDs**, but
`ref:project`, `ref:task` and `ref:user` fields accept only UUIDs (`validation_failed`). If the app
stores such ids in `olan.db`, give `fixtures/projects.json` UUID ids (and `members` with UUID `userId`s). `fixtures/db.json` row ids may be any unique non-empty
string (`"d1"`); rows the app inserts get UUIDs, as in Olan, so do not depend on the id format.

HTTP fixtures match `"METHOD url"` first, then the exact `url`, then the URL without its query
string. A URL without a fixture answers `http_blocked` (the mock never touches the network);
`validate --strict` warns `fixtures.http_missing` for it. `json` sets the body to
`JSON.stringify(json)` and `content-type: application/json`.

The mock host also applies Olan's rules: missing permission → `permission_denied`, HTTP host not
in permissions → `http_blocked`, a stale `revision` → `conflict`, storage values > 64 KiB →
`invalid_params`. `olan.db` runs on the same in-memory database Studio uses
(`@olan-app/sdk/memory-db`), with the server's validation, rules, cursors, quota and error codes
(`renderApp({ userId, quota })` changes the signed-in user and the limits). The first work package
of each mock project is the default one (`isDefault: true`): `deleteList` on it, or on a non-empty
one, fails with `forbidden_record`, as on the server.

## Remote requests, files and links

`olan.remote.request` goes to a mock app server: `renderApp({ remote })` (or `app.remote(…)`), else
the `fixtures/remote.json` answers. Routes use the `handleRequest` format and rules
(remote-requests.md): `:name` and `/*` parameters, unknown route 404, other method 405, a thrown
`RequestError` its status, any other throw 500. The answer goes through the same mapping as in Olan:
200–399 resolve, 4xx reject `remote_rejected`, 5xx and no handler `remote_unavailable`, and the
call waits at most its `timeoutMs`. Without `"requests": true` in the manifest every call fails with
`permission_denied`.

```ts
import { remote, renderApp, RequestError } from '@olan-app/cli/testing';

const items = [{ id: 'm1', title: 'Lansman', status: 'ready', url: 'http://127.0.0.1:4419/olan/media/m1' }];
const app = await renderApp({
  remote: remote({
    'GET /items': () => ({ body: items }),
    'POST /items': (ctx) => ({ status: 201, body: { item: { id: 'm2', ...(ctx.body as object) }, upload: { url: 'http://127.0.0.1:4419/olan/uploads/m2?token=t' } } }),
    'DELETE /items/:id': (ctx) => { if (ctx.params.id !== 'm1') throw new RequestError(404, { error: 'item_not_found' }); },
  }),
  ui: { files: ['kampanya.jpg'] },                       // fixtures/files.json names or inline { name, type, size, content }
  upload: (upload) => ({ status: 201, headers: { etag: '"1"' }, body: { id: 'm2' } }),
  profileRole: 'admin',
});
await app.press('Yükle');                                // Tabs item
const [sent] = app.host.remoteRequests;                  // { envelope, answer }
assert.equal(sent!.envelope.user?.email, 'utku@example.com');   // only with profile:read
assert.equal(app.host.uploads[0]!.headers['x-olan-file-name'], 'kampanya.jpg');
await app.fireTimers();                                  // a useQuery refetchIntervalMs tick
```

- **Envelopes.** `host.remoteRequests` holds `{ envelope, answer }` per call: `envelope` is the
  signed body Olan would post (issuer `MOCK_ISSUER` `https://olan.test`, installation
  `MOCK_INSTALLATION_ID`, `user.organizationId` `DEFAULT_ORGANIZATION_ID`, `locale` `tr`, `timeZone`
  `Europe/Istanbul`, a placeholder token); with `profile:read` the user gets `email` and
  `displayName` from the users fixtures and `role` from `profileRole`. `answer` is the wrapper the
  route returned (`null` when there was none).
- **Errors in the app.** `app.calls('remote.request')[0]!.error` is `{ code, message, details }`
  (`details`: `{ status, body?, reason? }`); in the app it is a `RemoteError`. Throw `RequestError`
  in test routes, imported from `@olan-app/cli/testing` or `@olan-app/sdk/server` (your server's
  own routes work as they are).
- **Files.** The picker returns the `fixtures/files.json` files (default: all that `accept` and
  `maxBytes` allow, up to `maxFiles`); `ui.files` chooses (`['tanitim.mp4']`, inline entries,
  `null`/`[]` = cancelled, or `(options) => …`). Uploads must target the manifest `remote.url`
  origin or an `http:<host>` permission (`http_blocked`); `http://127.0.0.1` works because tests
  are a development installation. `onProgress` gets `{ loaded: 0 }` at the start and
  `{ loaded: size }` at the end.
- **Upload types** (exported from `@olan-app/cli/testing`). `host.uploads` and the `upload` handler's
  argument are `MockUpload`: `{ uploadId: 'upl_…', file: FileHandle & { content: string }, url,
  method: 'PUT' | 'POST', headers: Record<string, string>, formField: string | null, fields:
  Record<string, string>, status: 'running' | 'done' | 'cancelled' | 'failed' }`. `file.content` is
  the fixture file's `content` text (`''` when it has none); `headers` are what the target got,
  lower-case (`content-type`, `content-length` for PUT, `x-olan-file-name`, yours). The handler
  returns `MockUploadAnswer` = `{ status?: number, headers?: Record<string, string>, body?: JsonValue }`
  (only `content-type`, `etag`, `location` reach the app); its type is `MockUploadHandler`.
- **Cancelling an upload.** `press` resolves only when everything it started has settled, and a
  running upload has not. Start the press **without awaiting it**, wait for the progress UI, press
  cancel, then await the first press:

  ```ts
  const app = await renderApp({ ui: { files: ['tanitim.mp4'] }, upload: () => new Promise(() => {}) });  // never answers
  const uploading = app.press('Yükle');                       // not awaited yet
  await app.waitFor((view) => view.find('ProgressBar').length > 0);
  await app.press('İptal');                                   // task.cancel(): the upload rejects with `cancelled`
  await uploading;                                            // now it settles
  assert.equal(app.host.uploads[0]!.status, 'cancelled');
  ```

  Awaiting `press('Yükle')` directly fails after `timeoutMs` with "files.upload is still pending";
  the same pattern works for a slow `remote` route (return a promise you resolve later).
- **Without `profile:read`.** The envelope's `user` has only `id`, `organizationId`, `locale` and
  `timeZone`. Leave the permission out of the list to test what your server does then (`remote`
  stays granted):

  ```ts
  const app = await renderApp({ permissions: ['files:pick'], remote: remote({ 'GET /me': (ctx) => ({ body: { email: ctx.user?.email ?? null } }) }) });
  assert.equal(app.host.remoteRequests[0]!.envelope.user?.email, undefined);
  ```
- **Testing your server.** `createTestIssuer` and `signRemoteRequest` sign requests exactly as Olan
  does, for tests of the app server itself (remote-requests.md#testing-the-app-server).
- **Links.** `host.opened` lists `{ url, external, expectReturn }`. `ui.openExternal` answers
  `openExternal(…, { expectReturn: true })` (e.g. `{ returned: true, params: { state: 'st_1' } }`).
  A return without a pending call is `renderApp({ params: { return: { state: 'st_1' } } })`.
- **App addresses.** `renderApp({ navigation: { screen: 'item', params: { id: 'm1' } } })` opens on
  `item` over `index` (`app.back()` returns to `index`); `screen: 'index'` gives the first screen
  these params.
- **Refresh.** The mock host never ticks by itself: `host.timers()` lists the running
  `{ timerId, intervalMs }` (at least 5000) and `app.fireTimers()` sends one tick to each.
- **Switches and multi-selects.** `await app.toggle('Hemen yayınla')`,
  `await app.select('Kanallar', ['instagram', 'tiktok'])` (or one value to toggle it).
- **Banners.** `await app.press('Yeniden bağla')` presses a `Banner` action;
  `await app.dismiss('Bağlantının süresi doldu')` presses its close button (`onDismiss`).

## Backend tests

Backend code (`server`, backend.md) is tested headlessly with `createBackendHarness`: it bundles
`server.entry`, runs it in `@olan-app/runtime` (isolated-vm in a forked runtime process, or QuickJS
with `olan-app test --engine quickjs`) and answers `olan.*` from the same mock host as `renderApp`
(in-memory `olan.db`, `fixtures/*.json`, `fixtures/http.json` for `olan.http.fetch`). Name the files
`tests/*.backend.test.ts` (any `*.test.ts` runs).

```ts
import { createBackendHarness, signHookRequest } from '@olan-app/cli/testing';

test('digest', async () => {
  const backend = await createBackendHarness({ secrets: { apiToken: 't' }, now: '2026-10-17T09:00:00Z' });
  try {
    const summary = await backend.call<{ count: number }>('summary', { limit: 5 });   // { ok, value | error, logs, cpuMs, wallMs }
    assert.equal(summary.ok, true, summary.error?.message);
    await backend.runSchedule('digest', { scheduledAt: '2026-10-17T09:05:00Z' });
    await backend.emit({ type: 'project.task.created', data: { projectId: 'p0', task: { id: 't1', title: 'Yeni' } } });
    const hook = await backend.hook('github', { headers: { 'x-github-event': 'push' }, body: { ref: 'refs/heads/main' } });
    assert.equal(hook.status, 200);                                   // signed with the secret setting for you
    const forged = await backend.hook('github', { headers: { 'x-hub-signature-256': 'sha256=00' }, body: '{}' });
    assert.equal(forged.status, 401);                                 // the function did not run
    assert.equal(backend.calls('http.fetch')[0]?.ok, true);           // olan.* calls the backend made
  } finally {
    await backend.dispose();                                          // always: it stops the runtime
  }
});
```

| Option | Default | Notes |
|---|---|---|
| `settings`, `secrets` | manifest defaults + `fixtures/settings.json`; secrets = the `secret: true` values | `secrets: { apiToken: null }` tests "not configured" |
| `db`, `fixtures` | `fixtures/*.json` | `db` = rows by collection (like `fixtures/db.json`) |
| `permissions` | the manifest's | The app identity's (schedules, events, hooks) and the default caller's |
| `engine` | `auto` (`OLAN_APP_BACKEND_ENGINE`, `olan-app test --engine`) | `isolated-vm` or `quickjs` |
| `manifest` | — | Fields over `olan-app.json` |
| `build` | `true` | `false` loads the existing `dist/server.js` |
| `limits` | 1000 ms CPU, 10 s / 30 s, 64 MiB, 4 at once | e.g. `{ cpuMs: 5000 }` on a slow machine |
| `userId`, `now` | as in `renderApp` | |

Methods: `call(name, args?, { userId?, permissions? })` (actor `user`), `runSchedule(name, { scheduledAt? })`,
`emit(type | { type, data?, actor?, id? })` (only events in `server.events`; default data from the
fixtures), `hook(name, { method?, headers?, body?, query?, sign? })` (returns `{ status, headers, body,
verified }` plus the result; `sign: false` sends it unsigned), `migrate(fromVersion)`, `calls(method?)`
(only the backend's calls),
`logs()`, `host`, `db`, `manifest`, `engine`, `dispose()`. Results: `{ ok, value?, error?: { code,
runtimeCode, message }, logs, cpuMs, wallMs }` — `code` is what `olan.backend.call` rejects with
(`backend_error`, `backend_limit`, …), `runtimeCode` the runtime's (`handler_error`, `cpu_limit`, …).

`hook()` bodies: a string is sent as is; any other JSON value as `JSON.stringify(body)` with
`content-type: application/json` (signed over those exact bytes). `await signHookRequest(verify, body,
secret)` is async and returns the headers to send: `{ [verify.header]: 'sha256=<lower-case hex>' }`
for `hmac-sha256`, `webhook-id`/`webhook-timestamp`/`webhook-signature` for `standard-webhooks`;
`verifyHookSignature` checks one by hand.

Recorded calls (`backend.calls()`, `renderApp().calls(m, { source: 'backend' })`): `params` is the
RPC object, e.g. `http.fetch` → `{ url, method?, headers?, body? }`. Secret values never appear:
a `secrets.get` result is `"[secret]"`, and every occurrence of a secret value (4+ characters) in
params, results and errors is replaced by `"[secret]"` (`headers.authorization` →
`'Bearer [secret]'`). `host.handle()` and the backend itself still get the real values.
`fixtures/settings.json` holds dev-only secrets (never real ones): it is used by tests, `validate`
and `dev`, and is not packed.

## Patterns

```ts
// project.widget with params
const app = await renderApp({ surface: 'project.widget', params: { projectId: 'site' }, now: '2026-10-20T09:00:00Z' });

// a write: check the call and the new state
await app.press('Görev 2');
await app.press('Tamamlandı');                                   // Menu item
assert.equal(app.calls('projects.updateTask')[0]?.ok, true);
assert.equal(app.host.data.projects[0]!.tasks[1]!.status, 'completed');

// dialogs
const app2 = await renderApp({ ui: { confirm: false, prompt: (params) => 'Yeni ad' } });

// storage
const app3 = await renderApp({ fixtures: { storage: { currency: 'EUR' } } });
assert.deepEqual(app3.host.data.storage, { currency: 'EUR' });

// forms
await app.fill('Başlık', 'Rapor');
await app.select('Durum', 'completed');
await app.press('Kaydet');                                        // Form submitLabel (or a Button)

// permissions
const denied = await renderApp({ permissions: [] });
assert.equal(denied.calls('projects.list')[0]?.error?.code, 'permission_denied');
```

Test files are bundled with esbuild for Node, so TypeScript works without a separate compiler.
Import only `node:*` modules, `@olan-app/cli/testing`, `@olan-app/sdk/server` (server tests), your
app server's modules (`../app-server/routes.ts`) and your own helpers; do not import `src/app.tsx`
into tests (`renderApp` loads it). After a file's tests end, its process gets 1.5 s to exit by
itself; a crash after every test passed is reported as `test.process_crashed` (a warning), not as
a failed test.

<!-- docs/cli.md -->
# CLI (`olan-app`)

`@olan-app/cli` is a dev dependency of every app, so `npx olan-app <command>` works offline. The
Olan CLI forwards `olan app <command>` to it (and passes your Olan sign-in to `publish --org` and `login --marketplace`).
Node.js 22 or newer.

Every command accepts `--json` (machine-readable output), `--cwd <dir>` and `--help`. Commands
that need an app look for `olan-app.json` in the directory or its parents. The marketplace commands
(`login`, `developer`, `keys`, `publish`/`status --marketplace`, `release`, `rollout`, `halt`, `withdraw`) print the marketplace's answer unchanged
with `--json`; every other command uses the `{ ok, … }` envelope (Output).

| Command | What it does |
|---|---|
| `init <name> [--template blank\|list-detail\|project-widget\|project-tab\|project-records\|external-api\|data-list\|backend\|remote] [--backend] [--id <id>] [--dir <dir>] [--link <packagesDir>]` | New app from a template (with AGENTS.md, CLAUDE.md, agent skills, tests, fixtures). `--backend` = `--template backend` (UI + `server/index.ts`, backend code Olan runs, backend.md). `remote`: UI + your own Node app server in `app-server/` (`handleRequest` routes, an upload target, UI and server tests; server.md, remote-requests.md). `--link` (or `OLAN_APP_PACKAGES_DIR`) writes `file:` dependencies on `<dir>/app-sdk` and `<dir>/app-cli` (monorepo development) |
| `validate [--strict [--verbose]] [--no-build] [--no-typecheck] [--engine auto\|isolated-vm\|quickjs]` | Manifest, build, entry/icon files, size, `tsc --noEmit`; with `server`: loads `dist/server.js` in the backend runtime and checks every schedule, event and hook has a handler (`backend` check); `--strict` also renders every surface with the mock host (running the backend for `olan.backend.call`) and checks component props and missing permissions, then runs Olan Marketplace's static review checks on the files `pack` would package (size, files, forbidden APIs, permissions, accessibility, licenses; the marketplace's codes, errors.md; `--verbose` prints info findings) |
| `test [pattern] [--engine auto\|isolated-vm\|quickjs]` | Runs `tests/**/*.test.ts` (testing.md), backend tests (`createBackendHarness`, `tests/*.backend.test.ts`) and app-server tests included; `--engine` picks their engine. A test file whose process crashes after all its tests passed is a `test.process_crashed` warning, not a failure. `--report <file> [--package <pkg>]` packs first, then writes a signed test report for the marketplace (marketplace.md#signed-test-reports) |
| `build [--no-minify]` | Bundles `src/app.tsx` into `dist/app.js` (one classic script with React and the SDK inside) and, with `server`, `server.entry` into `dist/server.js` (IIFE `__olanBackendModule`, no Node modules: `build.backend_node_import`) |
| `dev [--port 5178] [--host 127.0.0.1] [--server <olan web url>] [--open] [--engine auto\|isolated-vm\|quickjs] [--remote fixtures\|live] [--issuer-port 5180] [--detach]` | Watches and rebuilds; serves the app to Olan Studio (and, with `--host 0.0.0.0`, to a phone on your network); with `server` runs the backend locally (below). `olan.remote.request` is answered from `fixtures/remote.json`, or with `--remote live` by your app server at `remote.url` (below). Stopping: below |
| `pack [--out <file>] [--dev-sign \| --sign-key <file> \| --no-sign] [--no-build] [--no-validate]` | Runs the non-strict `validate` checks first and refuses on errors (`pack.validation_failed` plus the errors; `--no-validate` skips them), then writes `dist/<id>-<version>.olanapp`; `--dev-sign` signs with your development key, otherwise it signs when `olan-app.key.json` exists. Pack does not render surfaces: run `validate --strict` before it |
| `keygen --dev [--force]` | Creates (or shows) your development key in `~/.olan/olan-app-dev.key.json` (`OLAN_APP_DEV_KEY` overrides) and prints the `OLAN_APPS_TRUSTED_KEYS` line for a local Olan |
| `keygen [--out olan-app.key.json] [--force]` | Creates an Ed25519 key in the app and adds it to `.gitignore` (installs only where a server trusts it) |
| `sign --key <private-key.pem> [--key-id <id>] <package.olanapp>` | **Internal** (Olan's own apps): signs an existing package with an Ed25519 PEM key (below) |
| `login --marketplace [url] --server <api> [--no-browser] [--token <t>]` | Signs in to Olan Marketplace with your Olan account (in the browser unless `--token`/`OLAN_TOKEN`); saves a 30-day developer session (marketplace.md) |
| `developer create --marketplace [url] --slug <slug> --name <name> [--kind person\|company] --accept-agreement`, `developer list` | Creates a marketplace developer account (you become its owner) / lists yours |
| `publish --marketplace [url] [--developer <slug>] [--channel stable\|beta] [--percent N] [--visibility public\|org\|organization:<serverId>/<organizationId>] [--file <pkg>] [--test-report <file>] [--age-rating 4+|9+|13+] [--no-wait]` | Packs (unsigned) and submits to Olan Marketplace: automatic checks, review, signing; attaches a signed test report. Production path (marketplace.md) |
| `release`, `rollout`, `halt`, `withdraw` `--marketplace [url] <appId> <version>` | Release an approved version (`release [--channel stable\|beta] [--percent N]`), widen a staged rollout (`rollout --percent N`: 10 → 50 → 100), halt it, withdraw a submission (marketplace.md#releasing-and-rollout) |
| `keys register\|list\|revoke <id> [--server <api>] [--token <t>] [--name <n>]` | Registers your development key's public half on your Olan server (the server and token of `try`): it signs only your own development installations in your organization (below); `revoke` is final and stops them. With `--marketplace [url] [--developer <slug>]` (`register\|list\|remove <fingerprint>`): on a marketplace developer account instead (signed test reports show as verified) |
| `status --marketplace [url] <appId> [version] [--wait-decision]` | Submission state, checks, review level, next action (the exact command), rejection and findings; exit 1 on `checks_failed`, `rejected`, `withdrawn` |
| `app show|set --marketplace [url] <appId> [--age-rating 4+|9+|13+] [--category <id>] [--platforms <list>] [--support-url <u>] [--privacy-url <u>]` | Shows or changes the app's store settings; the age rating is required before `release`; for a live app the change is reviewed first ("in review") |
| `publish --org [--server <api url>] [--token <t>] [--file <pkg>] [--dev-sign]` | Packs and uploads to an organization catalog (admins; development and offline servers). Token from `--token` or `OLAN_TOKEN`, server from `--server`, `OLAN_SERVER` or `OLAN_API_URL`. Warns when the server will not install the version |
| `try [--server <api url>] [--token <t>]` | Packs (validate + build, like `pack`), signs with your development key and installs the app for your organization on a development server (`POST <server>/api/v2/apps/developer/try`, multipart `package`; needs developer access and a server that trusts the key). Same server and token as `publish --org`. Prints the app address `<webOrigin>/apps/<installationId>` (below) |
| `revocations sign --dev --in list.json [--out revocations.json]` | Development only: signs a revocation list with your development key (below) |
| `events send <type> [--to <url>] [--data <json\|@file>] [--installation <id>] [--attempt <n>] [--id <evt_…>] [--issuer-port 5180]` | Sends one signed event to the app's own server (`{remote.url}/events`), signed with your development key; a local issuer `http://127.0.0.1:5180` serves its JWKS meanwhile (server.md#developing-locally). Non-2xx: `events.delivery_failed` |
| `tools call <name> [--input <json\|@file>] [--to <url>] [--user <id>] [--channel assistant\|mcp]` | Calls an `ai.tools` tool on the app server like the Olan assistant and checks input and answer |
| `requests send <METHOD> <path[?query]> [--body <json\|@file>] [--query <json>] [--headers <json>] [--user <id>] [--profile\|--no-profile] [--role admin\|member] [--timeout <ms>] [--to <url>] [--issuer-port 5180]` | Sends one signed `olan.remote.request` envelope to `{remote.url}/requests` (development key, local issuer `http://127.0.0.1:5180`) and reads the answer as Olan does: prints the `{ status, headers, body }` wrapper and what the app gets (the response or a `RemoteError`). `--profile` (default: when the manifest has `profile:read`) adds `email`, `displayName`, `role`. No usable answer (401, not the wrapper, not running): `requests.delivery_failed`. Git Bash rewrites `/items` into a Windows path: use `MSYS_NO_PATHCONV=1` or `//items` there |
| `docs <query> [--limit 8]` | Searches these docs offline |
| `mcp` | MCP server over stdio (below) |

## The agent loop

1. Edit `src/app.tsx` (and `olan-app.json`, `fixtures/`, `tests/`).
2. `npx olan-app validate --strict --json` — fix every error (each has `code`, `file`, `line`, `hint`).
3. `npx olan-app test --json` — fix failing tests or the app.
4. Repeat until both report `"ok": true`. That is "done".

## Output

Without `--json`: results on stdout, progress and problems on stderr as
`file:line:column code: message` plus `hint:` lines.

With `--json`, stdout holds exactly one JSON object (for marketplace commands the marketplace's answer, marketplace.md):

```json
{ "ok": true, "command": "validate", "result": { … }, "warnings": [ … ] }
{ "ok": false, "command": "validate", "errors": [{ "code": "tree.unknown_prop", "message": "…", "file": "src/app.tsx", "line": 12, "column": 5, "hint": "…" }], "result": { … } }
```

`dev --json` prints the envelope on one line, then one JSON line per event
(`{"type":"rebuilt","buildId":"…","durationMs":…}`, `{"type":"error","errors":[…]}`,
`{"type":"manifest"}`, `{"type":"log","level":"info","args":[…],"at":"…"}`).

Exit codes: `0` success, `1` the command failed (errors), `2` usage error (unknown command or
option).

`validate --json` result: `{ app: { id, version }, strict, checks: [{ name, ok, skipped? }],
bundleBytes, surfaces: [{ surface, rendered, nodes, calls: [{ method, ok, code? }], text }], review? }`;
`--strict` adds `review: { findings: [{ check, code, severity, message, path?, hint?, rule? }], usage }`
(every marketplace finding, info included); review issues in `errors`/`warnings` carry `rule`.
Checks: `manifest`, `build`, `files`, `size`, `backend` (with `server`), `typescript`, `strict`. With `server` the result also has
`backend: { bytes, engine, handlers: { functions, schedules, events, hooks, migrate } }`; `build --json` has
`backend: { file, bytes, sha256 }`; `pack` puts `dist/server.js` in the package.

`pack --json` result: `{ file, bytes, sha256, signed, publicKey, keyFingerprint, files: [{ path, bytes, sha256 }] }`
(`files` are the app files; the archive also holds `digest.json` and, when signed, `signature.json`:
"3 app files (+ digest, signature)"),
plus `devKey: { file, created, fingerprint, envLine }` with `--dev-sign`. `sign --json` result:
`{ file, bytes, sha256, publicKey, keyFingerprint, keyId, signedAt, replaced }`. `publish --json` adds
`trust` (the server's verdict, below). `test --report --json` adds `report: { file, appId, appVersion,
packageSha256, package, keyFingerprint, keyFile, keyCreated }`.

## dev server

`olan-app dev` listens on `http://localhost:5178` (127.0.0.1 only). `--host 0.0.0.0` listens on
every interface and prints the LAN addresses (`result.lanUrls`) for the Olan mobile app's direct
mode (development builds); anyone on that network can then reach the server, so use it only on a
trusted network.

| Endpoint | |
|---|---|
| `GET /manifest` | The parsed `olan-app.json` (422 `{ error: 'manifest_invalid', issues }`) |
| `GET /app.js` | Latest successful bundle (503 `{ error: 'build_failed', errors }`) |
| `GET /package` | That bundle (and, with `server`, the backend) packed and signed with your development key: `application/octet-stream`, `content-disposition: attachment; filename="<id>-<version>.olanapp"`, `x-olan-package-sha256`, `x-olan-signing-key` (fingerprint). Studio's "Bu kurumda dene" uploads it. `?version=<semver>` packs and signs it with that `version` in the packaged `olan-app.json` (the server-named `-dev.N`; the file on disk is not changed; otherwise 400 `version_invalid`). 503 `build_failed` while a build fails, 422 `manifest_invalid` |
| `GET /status` | `{ appId, version, buildId, errors, builtAt, user: { id } }`; hosts using `/rpc` send `user` as `context.user` |
| `GET /fixtures` | The mock data |
| `POST /rpc` | `{ method, params, permissions? }` → the mock host's answer |
| `POST /logs` | `{ entries: [{ level, args, at }] }` (≤ 100 entries, ≤ 8 KiB each) → 204; printed as `[app <level>] …` (`--json`: `log` events) |
| `ws://localhost:5178/ws` | `{ type: 'rebuilt', buildId }`, `{ type: 'error', errors }`, `{ type: 'manifest' }`; with a backend also `{ type: 'backend', kind, name, ok }`, `backend-built`, `backend-error` |

With `server` (backend.md) the backend runs locally in `@olan-app/runtime` on the same mock host
(`olan.backend.call` through `/rpc` reaches it), is rebuilt when files under `server/` change, and
every invocation is printed with its console lines (`backend schedule digest: ok (4 ms)`,
`  [backend log] …`; `--json`: `backend-invocation` events). `--engine` forces an engine; `auto` falls
back to QuickJS where isolated-vm has no prebuild and prints
`isolated-vm prebuild not available on <platform>; using QuickJS (slower)`. `dev` bundles the
backend in memory, unminified (it writes no `dist/server.js`): its `sha256` differs from the
minified `dist/server.js` of `olan-app build`.

| Endpoint | |
|---|---|
| `GET /backend` | `{ engine, sha256, errors, schedules, hooks, events }` (also `status.backend`) |
| `POST /backend/call` | `{ name, args?, permissions? }` → `{ ok, value \| error, logs, cpuMs, wallMs }` (`result`: alias of `value`); a trigger's fallback function answers `backend_function_not_found` |
| `POST /backend/schedules/<name>/run` | Run a schedule now → `{ ok, value \| error, logs, cpuMs, wallMs }` |
| `POST /backend/events/<type>` | `{ data? }` (default: sample data from the fixtures) → the handler's outcome |
| `POST /hooks/<name>` | Raw body ≤ 1 MiB: verified like Olan does (secret from `fixtures/settings.json`), then the hook's answer, or `202` after 10 s |

In Olan open Studio (`/studio`, needs developer access from an admin), add the address under
"Geliştirme sunucuları", and the preview reloads on every save. `--open` opens
`<server>/studio?dev=<dev url>`.

**Remote requests in dev.** By default `dev` answers `olan.remote.request` (through `/rpc`) from
`fixtures/remote.json`, like tests do. `--remote live` sends each call to your running app server
instead: a signed envelope to `{remote.url}/requests` from the development issuer
`http://127.0.0.1:<--issuer-port, 5180>` (your development key; it runs as long as `dev` and serves
its `/.well-known/olan` and JWKS), read with Olan's rules (HTTP 200 + wrapper, ≤ 4 MiB, the call's
`timeoutMs`). List that issuer in the server's `issuers`. Each call is printed
(`remote GET /items → 200 (12 ms)`; `--json`: `{"type":"remote","message":…}`); a 401 means the
issuer is not listed. The envelope's `installationId` is `00000000-0000-4000-8000-0000000000a1` and
the token a placeholder.

**Stopping `dev`.** Ctrl+C or SIGTERM. On Windows Ctrl+C works in Windows Terminal, PowerShell and
cmd; closing the terminal window, or ending the shell or agent process that started `dev`, also
stops it within 2 s (it watches its parent process), so no orphaned server keeps the port. With
`--detach` it keeps running: stop it with `Stop-Process -Id <pid>` (PowerShell) or
`taskkill /PID <pid> /T /F` (the PID of the `node` process listening on 5178:
`netstat -ano | findstr :5178`), or `kill <pid>` elsewhere.

## Signing and publishing

An Olan server installs and runs a package only when its Ed25519 signature verifies **and** the
signing key is on the server's trusted key list (`OLAN_APPS_TRUSTED_KEYS`). The public key inside
`signature.json` proves nothing by itself. Every Olan server ships with the **Olan Marketplace key** built in (key id `olan-marketplace-2026-10-17`); `OLAN_APPS_TRUSTED_KEYS` can add keys but cannot remove the built-in one, which is revoked only through the marketplace revocation list (Phase 4a).
In production the list holds the **Olan Marketplace key only**: every app, organization-only apps included, is reviewed and signed by Olan Marketplace
(Phase 4). There is no organization key, and an administrator's approval does not replace the
signature.

| Package | Upload to a catalog | Install / run |
|---|---|---|
| Signed with a trusted key | accepted | yes |
| Unsigned | accepted, marked "İmzasız" | no: `package_unsigned` |
| Signed with another key | accepted, marked "Bilinmeyen anahtar" | no: `package_untrusted_key` |
| Bad signature or digest | rejected: `package_invalid` | — |

Trust is checked again on every install, version change, bundle and app-token request, so a key
removed from the list stops its apps. Unsigned code runs only in development: Studio, `olan-app dev`
and "Olan'da dene" (`/apps/dev`), for people with the `developer` grant, under a "Geliştirme" label.

Who installs: catalog uploads are for admins, and an organization without an install policy is **admin only** by default until an admin lets members install (Olan → Yönetim → Uygulamalar).

Local development with your own Olan:

```sh
npx olan-app keygen --dev             # once: ~/.olan/olan-app-dev.key.json, prints the env line
# add the printed line to the local Platform API environment and restart it:
#   OLAN_APPS_TRUSTED_KEYS=dev-local=<your public key>
npx olan-app keys register            # or instead: register the key on the server (your development installations only)
npx olan-app validate --strict && npx olan-app test
npx olan-app pack --dev-sign          # dist/<id>-<version>.olanapp, signed with the development key
npx olan-app publish --org --dev-sign --server http://localhost:4000 --token "$OLAN_TOKEN"
olan app publish --org --dev-sign     # the same with the Olan CLI signed in (sets OLAN_TOKEN and --server)
npx olan-app try --server http://localhost:4000 --token "$OLAN_TOKEN"   # install it for your organization now
```

**Trying an app in your organization.** `olan-app try` packs and dev-signs like `pack --dev-sign`,
then uploads to `POST <server>/api/v2/apps/developer/try` (multipart field `package`, the same bearer
token as `publish --org`). The server installs it for your organization and answers
`{ installationId, appId, version }`; `try` prints `Open: <webOrigin>/apps/<installationId>`
(`webOrigin` from `/.well-known/olan`; without it, open Olan → Uygulamalar). `--json` result:
`{ server, endpoint, file, installationId, appId, version, appUrl, keyFingerprint }`. Refusals come
back as `try.<error>` (e.g. `try.developer_required`) or the package issue codes. Studio does the same
from a running `olan-app dev` ("Bu kurumda dene" uploads `GET /package`). **Developer keys:** instead of `OLAN_APPS_TRUSTED_KEYS`, register the key on the server once (`olan-app keys register`, or Studio → Geliştir → "Geliştirici anahtarları"). It vouches only for your own development installations (`try`) in your organization, while you are a member and until you revoke it; then they stop (`developer_key_revoked` / `developer_not_member`) but are not deleted. It never vouches for catalog uploads (`publish --org`), marketplace packages or other people.

**Development versions (`-dev.N`).** A version in the organization's catalog never changes. When you
try a changed build under a version the catalog already holds, the server answers
`409 version_exists` with `nextVersion`, the next free development prerelease of that app
(`1.2.0` → `1.2.0-dev.1`, then `1.2.0-dev.2`, …; a `-dev.N` version counts on from the same base).
`olan-app.json` is part of the signed digest, so the server cannot rename the package: `try` packs
and signs the same build again with `version` set to `nextVersion` and uploads it once more (the
`file` and `version` of the result name it; `olan-app.json` on disk is not changed). Studio asks the
dev server for `GET /package?version=<nextVersion>` and does the same. A second conflict, or a server
that names no `nextVersion`, is reported as `try.version_exists`: raise `version` yourself. To ask
first: `GET <server>/api/v2/apps/developer/try/next-version?appId=<id>&version=<version>` →
`{ appId, version }` (the version itself while the catalog does not hold it). The catalog upload
(`publish --org`) keeps a plain `version_exists`.

`/.well-known/olan` lists the fingerprints of the keys a server trusts
(`apps.trustedKeyFingerprints`); `pack` prints your key's fingerprint to compare. Never add a
development key to a production server. `olan-app keygen` without `--dev` writes a key into the
app (`olan-app.key.json`, git-ignored) for servers that are configured to trust it, such as an
offline test server.

**Internal: signing Olan's own apps.** Until Olan Marketplace signs packages itself, Olan signs its own apps with the marketplace key: `npx olan-app pack --no-sign`, then `npx olan-app sign --key <marketplace.pem> --key-id olan-marketplace-2026-10-17 dist/<id>-<version>.olanapp`. `sign` reads an unencrypted PKCS#8 Ed25519 PEM (`-----BEGIN PRIVATE KEY-----`, e.g. `openssl genpkey -algorithm ed25519`) and refuses other key types and encrypted keys, verifies the package digest, then writes `signature.json` (replacing an existing one; other files stay byte-identical). `--key-id` becomes `keyId`, the key's name on the server's trusted list (1-64 letters, digits, `.`, `_`, `-`); it is informational, servers trust the public key. The private key stays in memory only: never printed, logged, copied or stored. App developers use `pack --dev-sign` instead.

**Revocation lists (development).** Olan Marketplace signs the list of revoked apps; servers and
the mobile app refuse to open a revoked version. To try this locally:

```sh
echo '[{ "appId": "com.example.my-app", "versions": ["0.1.0"], "reason": "Test" }]' > list.json
npx olan-app revocations sign --dev --in list.json --out revocations.json
```

The output is `{ "payload": "<JSON text>", "signature": { "keyId": "dev-local", "algorithm": "ed25519", "signature": "…" } }`,
signed over the payload text with your development key. `--in` holds the entries (`appId`, then
`versions` or `packageSha256` or neither for every version, `reason`, `revokedAt`?) or
`{ issuedAt?, expiresAt?, sequence?, entries }`; missing values become now, now + 48 h and the time
in seconds. Only development builds accept such a list.

`publish` prints a warning (`publish.package_unsigned`, `publish.package_untrusted_key`) when the
server stored the version but will not install it. Server rejections come back as
`publish.<error>` (e.g. `publish.version_exists`: bump `version`) or the package issue codes.

## Olan Marketplace

The production path: `login --marketplace` once (browser sign-in or the Olan CLI; CI uses the saved session as `OLAN_MARKETPLACE_SESSION`), `developer create` once, `keys register` once per computer, then `test --report`, `publish --marketplace --test-report`, `status --marketplace`, `app set --age-rating` once and, after approval, `release`. Sign-in, the
marketplace address order, `--visibility`, the `--json` answers, `nextAction`, review levels and
every automatic check with its finding codes: marketplace.md. Error codes: errors.md#olan-marketplace.

## MCP server

`olan-app mcp` gives Claude Code and Codex the same tools over stdio:

```sh
claude mcp add olan-app -- npx olan-app mcp
```

```toml
# ~/.codex/config.toml
[mcp_servers.olan-app]
command = "npx"
args = ["olan-app", "mcp"]
```

| Tool | Input | Returns |
|---|---|---|
| `olan_app_validate` | `{ dir?, strict? = true }` | validate result or errors |
| `olan_app_build` | `{ dir? }` | build result |
| `olan_app_test` | `{ dir?, pattern? }` | test summary |
| `olan_app_render` | `{ dir?, surface?, params?, permissions?, fixtures?, settings?, userId?, locale?, theme?, now? }` | `{ surface, tree, text, calls, toasts, navigation, errors }`; becomes the session |
| `olan_app_dispatch` | `{ action: 'press' \| 'fill' \| 'select' \| 'submit' \| 'back', label?, value? }` | the new view of the session |
| `olan_app_logs` | `{}` | session logs, errors, calls; last build and test |
| `olan_app_db` | `{ collection?, where?, limit? }` | the session's mock `olan.db`: collections with row counts and usage, or the rows of one collection (every user's, with owner), newest first (default 50, max 500) |
| `olan_app_event_send` | `{ type, dir?, to?, data?, installationId?, attempt?, id?, issuerPort? }` | the signed event, HTTP status and the app server's answer |
| `olan_app_tool_call` | `{ name, dir?, input?, to?, userId?, channel?, issuerPort? }` | the tool's answer (`{ ok, result \| error }`) |
| `olan_app_request_send` | `{ method, path, dir?, query?, body?, headers?, timeoutMs?, userId?, profile?, role?, to?, issuerPort? }` | the signed envelope, the app server's wrapper and what the app gets (`requests send`) |
| `olan_app_docs_search` | `{ query, limit? }` | matching doc sections |

Every tool answers `{ ok, result }` or `{ ok: false, errors }` as JSON text.

<!-- docs/marketplace.md -->
# Olan Marketplace

Apps reach production Olan servers through Olan Marketplace: automatic checks run on the package, a person reviews it, and the marketplace signs the approved version with the marketplace key.

```sh
npx olan-app login --marketplace --server https://api.example.com   # once: browser sign-in, 30-day session
npx olan-app developer create --marketplace --slug acme --name "Acme Ltd" --accept-agreement   # once
npx olan-app keys register --marketplace    # once per computer: your development key signs test reports
npx olan-app validate --strict && npx olan-app test --report test-report.json   # packs, then tests
npx olan-app publish --marketplace --test-report test-report.json   # submits, attaches, waits for the checks
npx olan-app status --marketplace com.example.my-app --wait-decision
npx olan-app app set --marketplace com.example.my-app --age-rating 4+   # once: required before release
npx olan-app release --marketplace com.example.my-app 1.0.0 --percent 10   # after approval
```

Reviewers apply review-guidelines.md (rule numbers like `2.1` in findings and rejections). **Studio** does the same in the browser: sign in to your Olan web app (e.g. `https://olan.example.com`) with an account that has developer access (the `developer` grant), open `<Olan web address>/tr/studio?section=publish` (Studio → Yayınla): developer accounts, store settings and page, submissions, test reports, releases.

## Signing in

The marketplace trusts your Olan server: `login` gets a 5-minute identity token from the server (`POST /api/v2/apps/marketplace/identity-token`; your account needs the `developer` grant from an admin) and exchanges it for a developer session. There are three ways to give `login` your Olan sign-in:

1. **Browser (default).** `olan-app login --marketplace --server <Olan API address>` opens the browser at the server's sign-in page (OAuth 2.0 authorization code with PKCE; the endpoints come from `<server>/.well-known/openid-configuration`, client `olan-app-cli`) and receives the answer on `http://127.0.0.1:<random port>/callback`. `--no-browser` only prints the address; open it in a browser **on the same computer** (the redirect goes to 127.0.0.1). The CLI waits 5 minutes.
2. **Olan CLI.** `olan app login --marketplace` with the Olan CLI signed in (`olan auth login`) passes your access token (`OLAN_TOKEN`) and server. Every `olan app …` command needs an Olan CLI that has the `app` command (`olan app --help` works; Olan Apps 4a release or newer); with an older `olan` use `npx olan-app …` and 1.
3. **CI.** Olan has no personal access tokens or API keys to create for CI, and `olan` does not print its token. CI uses a marketplace session instead: run `olan-app login --marketplace --server <api>` once on your computer (browser), then store the contents of `~/.olan/marketplace.json` (or only its `token`) as the CI secret `OLAN_MARKETPLACE_SESSION`; it replaces the file, lasts 30 days (sign in again and update the secret before `expiresAt`) and is all `publish`, `status`, `app`, `release`, `keys` need. `OLAN_TOKEN` / `--token` is only an input to `login` (an Olan access token the Olan CLI passes); CI never needs it.

The server is `--server`, else `OLAN_SERVER`, else `OLAN_API_URL` (the Olan CLI sets them). The session is saved in `~/.olan/marketplace.json` (`{ url, token, expiresAt, userRef, … }`, mode 0600; on Windows restricted to your user with `icacls`, best effort) and lasts 30 days. No token is ever printed or logged, and the session token is not accepted on the command line.

**Marketplace address**, first of: `--marketplace <url>`, `OLAN_MARKETPLACE_URL`, the saved session's marketplace (`publish`, `status`, `developer`), the server's `/.well-known/olan` `marketplaceUrl` (when a server is known: `login --server`, `OLAN_SERVER`, `OLAN_API_URL`), `https://marketplace.olan.app`.

## Developer accounts

Apps belong to a developer account (a person or a company); you can be a member of several.

- `olan-app developer create --marketplace [url] --slug <slug> --name <name> [--kind person|company] --accept-agreement` creates one and makes you its owner. `--slug` is the developer name in app pages (a-z, 0-9 and `-`, 2-63 characters; `olan…` is reserved). Creating an account accepts the current developer agreement; `--accept-agreement` is required and the CLI reads the version from `GET /api/v1/developer/me`.
- `olan-app developer list` shows your accounts, roles, agreement state and pending invites (invites are accepted in Studio → Yayınla).

## Publishing

- **publish.** A new app needs a developer account; `--developer <slug>` picks one when you have several. Existing apps get a new version (versions only go up). `--channel stable|beta [--percent N]` releases on approval. `--visibility public` (default) or `--visibility organization:<serverId>/<organizationId>` limits a new app to one organization on one Olan server; `--visibility org` fills both from the session (the server must be registered with the marketplace). Visibility is set when the app is created; later in Studio. `publish` waits while the checks run (`--no-wait` does not) and exits 1 with the findings on `checks_failed`. `--age-rating 4+|9+|13+` sets the app's age rating after uploading.
- **Version numbers.** A `checks_failed`, `rejected` or withdrawn version may be submitted again under the same number (it was never signed); one that is in review, approved or released may not (`version_exists`), and a new version must be higher than the latest (`version_not_increasing`). Organization catalog uploads (`publish --org`) always need a new number (manifest.md).
- **status.** Without a version: the newest. Prints the state, each check's status, the review level and reasons and `Next:` with the exact command (rejections too, on stderr before the findings). Exit 0 for `approved`, `checking`, `in_review`; 1 for `checks_failed`, `rejected`, `withdrawn`. `--wait-decision` polls every 5 s until a decision.
- **Store settings.** `olan-app app show --marketplace <appId>` and `olan-app app set --marketplace <appId> [--age-rating 4+|9+|13+] [--category <id>] [--platforms web,desktop,ios,android] [--support-url <url>] [--privacy-url <url>]` (developer role; `PATCH /api/v1/developer/apps/:appId`). Before the first release the change applies at once; for an app live in the public store it is reviewed first (`202 { pendingChange }`, printed as "in review"). Studio → Yayınla → the app → Mağaza sayfası is the same.
- **`--json`** prints the marketplace's answer unchanged (no `{ ok, … }` envelope): `publish` → `{ app, version, createdApp, submission }` (the submission as last polled; with `--test-report` also `testReport`; with `--age-rating` also `storeSettings`), `app` → `{ app, pendingChange? }`, `status` → `{ version, submission }`, `keys` → `{ key }` / `{ keys }`, `login` → `{ url, expiresAt, user, developers, sessionFile }`, `developer list` → `{ user, developers, agreement, invites }`, `developer create` → `{ developer }`, errors → `{ error, message, issues?, hint? }`.

## Releasing and rollout

After approval (`status` says `nextAction: release`), with an owner or admin role. **The app needs an age rating first** (4+, 9+ or 13+; guideline 5.4): `olan-app app set --marketplace <appId> --age-rating 4+`, `publish --marketplace --age-rating 4+`, or Studio → Yayınla → the app → Mağaza sayfası; without it `release` fails with `age_rating_required`.

- `olan-app release --marketplace [url] <appId> <version> [--channel stable|beta] [--percent N]`: publish to a channel (default `stable`, 100%). `--percent 10` is a staged rollout: only that share of servers get it (chosen deterministically per server). `beta` reaches only the organizations on the app's beta list (Studio → Yayınla).
- `olan-app rollout … --percent N`: widen it (10 → 50 → 100). It never narrows (`rollout_invalid`); it also resumes a halted rollout.
- `olan-app halt --marketplace <appId> <version>`: no new servers get the version; installed copies stay.
- `olan-app withdraw --marketplace <appId> <version>`: take back a submission still `checking` or `in_review`.

Each prints the marketplace answer with `--json` (`{ version }`, `withdraw`: `{ submission }`; errors `{ error, message }`) and exits 0 on success, 1 on failure (2: unknown option).

## Signed test reports

The marketplace cannot run your own tests (a package has no sources), so you attach their result, bound to the exact package and signed with your development key:

1. `olan-app keys register --marketplace [--developer <slug>] [--name <name>]` registers the public half of `~/.olan/olan-app-dev.key.json` (`OLAN_APP_DEV_KEY` overrides; created on first use) with the developer account. `keys list` and `keys remove <fingerprint>` manage them. (Without `--marketplace`, `keys register` registers the key on your Olan server for your development installations instead: cli.md.)
2. `olan-app test --report test-report.json` packs the app first (unsigned, into `.olan-app/report/`; a signature does not change `digest.package`), runs the whole suite and writes the report. Generate it **after** your last source change: `publish` packs the same sources to the same `digest.package`; a report for another build is refused (`test_report_mismatch`). `--package <file>` binds it to a package you packed yourself (for `publish --file`). Failing runs still write a report (and exit 1); reviewers see the failures.
3. `olan-app publish --marketplace --test-report test-report.json` checks the report locally, submits, then attaches it (`PUT …/versions/:version/test-report`, only while `checking`/`in_review`). `--json` adds `testReport` (`{ status: verified|unregistered_key, keyFingerprint, summary, failed }`).

The file is `{ payload, signature: { algorithm: "ed25519", publicKey, signature, keyId } }`: `payload` is the JSON text of `{ version: 1, appId, appVersion, packageSha256, generatedAt, tool: { cli, runner }, summary: { passed, failed, skipped, durationMs }, tests: [{ file, name, status, durationMs?, error? }] }`, signed over its UTF-8 bytes (`@olan-app/schema` `TestReportDocument`, `verifyTestReport`). A registered key shows as `verified` to reviewers, any other as `unregistered_key`.

## Submissions

A submission has `state`, `reviewLevel`, `reviewReasons`, `checks` (the report below), `rejection` (`{ rule, code, notes, findings }`), `release`, `testReport`, `notes` (reviewer notes) and `nextAction`. `checks` is null while checking, then `{ version: 1, passed, startedAt, finishedAt, usage: { rpcMethods, permissionsUsed, permissionsUnused, httpHosts }, checks: [{ id, status: passed|warning|failed|skipped, durationMs, findings: [{ check, code, severity, message, path?, rule?, hint? }] }] }` (`@olan/contracts` `OlanAppCheckReport`), one entry per check below.

| `nextAction` | Meaning |
|---|---|
| `wait` | `checking` or `in_review`: automatic checks or a reviewer are working |
| `fix_and_resubmit` | `checks_failed` or `rejected`: fix the findings, publish again (same version allowed) |
| `release` | `approved` without a release: `olan-app release` (or Studio → Yayınla) |
| `none` | `approved` and released (on approval or with `olan-app release`) |
| `resubmit` | `withdrawn`: publish again |

`reviewLevel` is `light` or `full`. `reviewReasons` say why a review is full: `first_version`, `new_permissions` (permissions the last approved version did not have), `unverified_developer`, `security_findings` (a warning or error under guideline 1.x).

## Automatic checks

Every submission runs these checks on the package (the same static checks the marketplace shares with `@olan-app/schema`). `checks.passed` is false when any finding is an `error`; warnings go to the reviewer; `info` findings are notes. Each finding has `check`, `code`, `severity`, `message`, and often `path`, `rule` (the guideline, e.g. `2.1`) and `hint`.

| Check | Looks at | Common codes |
|---|---|---|
| `manifest` | `olan-app.json`, digest, signature and package layout (the server's install validation) | `manifest.*`, `package.*` (errors; the other checks are skipped) |
| `size` | Package and entry size (≤ 5 MiB) | `size.package_too_large` (error), `size.entry_large` (warning), `size.summary` (info) |
| `files` | File types in the package | `files.entry_missing`, `files.native_binary`, `files.type_not_allowed`, `files.svg_active_content` (errors), `files.source_map` (warning) |
| `permissions` | Declared permissions against `olan.*` calls in the bundle, in the backend (`dist/server.js`, since 1.5.1), during the render, and the event subscriptions and assistant tools that need them | `permissions.missing`, `permissions.http_missing` (errors), `permissions.unused`, `permissions.http_unused` (warnings), `permissions.http_hosts` (info) |
| `forbidden-apis` | Code the sandbox forbids (guideline 1.x) | `forbidden.eval`, `forbidden.function_constructor`, `forbidden.dynamic_import`, `forbidden.fetch`, `forbidden.xhr`, `forbidden.websocket`, `forbidden.dom`, `forbidden.browser_storage`, `forbidden.workers`, `forbidden.crypto_mining` (errors); `forbidden.navigator`, `forbidden.location`, `forbidden.require`, `obfuscation.*` (warnings) |
| `surfaces` | Renders every declared surface with sample data | `surfaces.not_rendered`, `surfaces.load_error`, `surfaces.timeout`, `surfaces.unknown_method`, `surfaces.limit_exceeded`, `surfaces.app_error` (errors; `surfaces.runner_failed` is the marketplace's own failure: publish again); `surfaces.empty`, `surfaces.root_not_screen`, `surfaces.not_settled` (warnings) |
| `interaction` | Presses the buttons and menus of each rendered surface | `interaction.app_error` (error), `interaction.summary` (info), `interaction.developer_tests_unavailable` (info; `interaction.developer_tests_reported` once a test report is attached) |
| `accessibility` | Labels and keys in the rendered trees (guideline 4.x) | `a11y.button_label_missing`, `a11y.field_label_missing`, `a11y.action_label_missing`, `a11y.menu_item_label_missing` (errors); `a11y.image_alt_missing`, `a11y.menu_label_missing`, `a11y.list_key_missing`, `a11y.duplicate_key` (warnings) |
| `licenses` | License files and notices in the bundle (guideline 6.x) | `licenses.found` (info), `licenses.notices_missing` (info), `licenses.copyleft` (warning) |

`validate --strict` catches most of these before you submit. `interaction.developer_tests_unavailable` is always informational: a package does not contain your source, so your own `olan-app test` suites cannot run on the marketplace; attach a signed test report instead (above). The checks may finish before the report arrives; once it is attached the note reads `interaction.developer_tests_reported` with the report's counts. What each `rule` means and how to fix it: review-guidelines.md. `olan-app build` keeps the license comments of bundled code (React, MIT) at the end of `dist/app.js` and `dist/server.js`, which satisfies `licenses.notices_missing`; extra notices go in a `NOTICE` or `THIRD_PARTY_NOTICES` file under `assets/` (only `assets/**` is packed).

Marketplace error codes (`marketplace.<code>`) are listed in errors.md#olan-marketplace.

<!-- docs/review-guidelines.md -->
# Olan App Review Guidelines (summary)

Every app submitted to Olan Marketplace follows these rules, public and organization-only apps alike. Rule numbers are stable: automatic check findings (`rule`), rejections (`rejection.rule` in `olan-app status --json`) and `validate --strict` findings (`(guideline 2.1)`) cite them.

## How review works

- **Automatic checks first** (minutes; marketplace.md#automatic-checks). Any `error` finding ends the submission as `checks_failed` without a human review: fix it and publish again.
- **A person reviews every version**; nothing is approved automatically, organization-only apps included. **Full review**: the first version, a version that asks for a new permission or host, an unverified developer, security findings (1.x). **Light review**: everything else (`reviewLevel`, `reviewReasons`).
- **Store page changes** (listing text, age rating, category, links) of a live public app go live after a quick review (7.x; `olan-app app set` prints "in review"); for organization-only apps they apply at once.
- **Approval signs** the package with the Olan Marketplace key; Olan can stop a signed app on every server (revocation list).
- **A rejection names the rule.** A rejected or `checks_failed` version was never signed, so its version number may be submitted again; an approved or released number may not.

## Rules

| Rule | What it means | Typical findings | Typical fix |
|---|---|---|---|
| 1.1 No obfuscation | Minified code is fine; deliberately obscured code, encrypted or encoded payloads and code decoded at run time are not | `obfuscation.*` | Ship the plain output of `olan-app build` |
| 1.2 No dynamic code | No `eval`, `new Function`, dynamic `import()` or downloaded code: the behaviour is in the reviewed package | `forbidden.eval`, `forbidden.function_constructor`, `forbidden.dynamic_import` | Static imports; data, not code, from the network |
| 1.3 No native binaries | Only JavaScript, JSON, images and text (`.so`, `.dex`, `.jar`, `.wasm`, `.hbc`, `.node`, `.exe`, `.dylib` are refused) | `files.native_binary`, `files.type_not_allowed` | Remove them from `assets/` |
| 1.4 Only `olan.*` | No direct `fetch`, `XMLHttpRequest`, `WebSocket`, DOM, `localStorage`, `navigator` or sandbox escapes; device APIs (location, camera, contacts) are not available | `forbidden.fetch`, `forbidden.dom`, `forbidden.browser_storage`, `surfaces.unknown_method` | `olan.http.fetch`, `olan.storage`, SDK components (api.md) |
| 1.5 No mining or abuse | The app does not use the device or the Olan server for anything but its purpose | `forbidden.crypto_mining` | Remove it |
| 2.1 Least privilege | Every permission backs a visible feature; no unused permissions; `*:delete` never deletes without asking the person | `permissions.missing`, `permissions.unused` | Declare what you call, drop the rest; `olan.ui.confirm` before deleting (examples.md#confirm-before-a-destructive-action) |
| 2.2 Honest data-use declaration | The store page's data declaration (data, purposes, third parties) matches what the app does | Reviewer | Update the listing in Studio → Yayınla |
| 2.3 Justified network access | `http:<host>` only for hosts the app's job needs, each named in the declaration; no personal data leaves Olan without consent | `permissions.http_missing`, `permissions.http_unused`, `permissions.http_hosts` (info) | Grant only the hosts you fetch; explain each in the listing |
| 2.4 KVKK and GDPR | Apps that process personal data give a privacy policy URL and honour deletion and export requests; sensitive data (health, ID numbers) needs a separate justification | Reviewer | `olan-app app set --marketplace <appId> --privacy-url <https url>` |
| 3.1 Every surface opens | Each declared surface opens with sample data without errors | `surfaces.*` | `olan-app validate --strict`; render an `EmptyState` rather than nothing |
| 3.2 Headless tests | Your `olan-app test` suites pass; a signed test report (key registered with the account) shows reviewers your results, failures included | `interaction.developer_tests_unavailable`, `interaction.developer_tests_reported` (info) | `olan-app test --report r.json`, `publish --marketplace --test-report r.json` (marketplace.md#signed-test-reports) |
| 3.3 No crash on interaction | Pressing buttons and submitting forms raises no error; failures show the person a clear message | `interaction.app_error` | Catch failures; show a toast or an `EmptyState` |
| 4.1 Labelled controls | Every button, menu, menu item, action and form field has a label | `a11y.button_label_missing`, `a11y.field_label_missing`, `a11y.action_label_missing`, `a11y.menu_item_label_missing` | Give each a `label`, even with an icon |
| 4.2 Image descriptions | Meaningful images have alternative text | `a11y.image_alt_missing` | Add `alt` |
| 5.1 Not misleading | Name, description, screenshots and the app tell the same story | Reviewer; `manifest.description_template` (warning) | Write your own `description` |
| 5.2 Not impersonating Olan | No Olan name, logo or design imitation; `com.olan.*`, `app.olan.*`, `olan.*` ids are Olan's | `app_id_reserved` | Choose your own id and branding |
| 5.3 User content | Apps that show user or AI-generated content offer filtering, reporting and blocking | Reviewer | Add those controls |
| 5.4 Correct age rating | 4+, 9+ or 13+ matching the content; Olan is rated 13+, so 16+ and 18+ apps are not accepted. Required before release | `age_rating_required`, `age_rating_not_allowed` | `olan-app app set --marketplace <appId> --age-rating 4+` (or Studio) |
| 6.1 License notices kept | Notices of bundled third-party code stay in the package | `licenses.notices_missing` (info) | `olan-app build` keeps them; more in `assets/NOTICE` |
| 6.2 Copyleft reviewed | GPL, AGPL, LGPL, SSPL code is reviewed separately | `licenses.copyleft` (warning) | Explain it in the review notes, or replace it |
| 7.1 Accurate store page | Screenshots are from the real app; the description is complete in TR or EN | Reviewer | Studio → Yayınla → store page |
| 7.2 Working support and privacy links | Both open and belong to the app | Reviewer | `olan-app app set --marketplace <appId> --support-url … --privacy-url …` |
| 8.1 Organization-only apps | The same rules and a person reviews every version; only visibility differs and store page changes apply without review. The submitter signs in through that organization's verified Olan server as an admin or developer | `organization_not_allowed`, `server_not_verified` | `olan-app login --marketplace --server <that server>` |

Every app page has "Bildir" (report); Olan may revoke a version or the whole app after a report and tells the developer why. Legal terms (developer agreement, data processing) are separate documents.

<!-- docs/errors.md -->
# Error codes

## Run time: `OlanError.code`

| Code | Meaning | Fix |
|---|---|---|
| `permission_denied` | The installation did not grant the permission the call needs | Add it to `permissions` (permissions.md); handle the error with an `EmptyState` |
| `http_blocked` | `olan.http.fetch` to a host without `http:<host>`, a private address, or (tests) a URL without an HTTP fixture | Add `http:<host>`; add the URL to `fixtures/http.json` |
| `invalid_params` | Bad arguments: storage value > 64 KiB, `json()` on a non-JSON body, unknown `olan.db` collection, `where`/`orderBy` on a field that is not indexed, `limit` outside 1–100, a cursor from another query | Check the arguments (database.md#queries) |
| `validation_failed` | An `olan.db` row does not match the manifest `data` schema; `message` is `"data.<field>: row.<code>"` (`row.unknown_field`, `row.required`, `row.type`, `row.max_length`, `row.range`, `row.enum`, `row.not_integer`, `row.json_too_large`, `row.too_large`), `"data.<field>: ref.not_found"` (the referenced project, task or user does not exist or is not visible; on `insert` and on changed `update` fields), `ref.too_many` (> 20 references per call); or a card is invalid (`card.*`, below) | Fix the value of that field |
| `conflict` | Stale `revision` in `olan.db` `update`/`delete`, `updateTask`, `deleteTask` or `deleteList` (older servers: `invalid_params`) | Reload (`get`/`refetch`) and retry with the new `revision` |
| `not_found` | The row, task or work package does not exist (any more) | Refetch the list |
| `forbidden_record` | A protected record (default work package, non-empty work package, task with an approval workflow, a record the app did not create when the admin requires that; Olan meetings, project calendar events and shared contacts `system_record`; invitations `not_organizer`; read-only calendars `permission_denied`; a project the app did not create `not_created_by_app`) or an `olan.db` row the collection's `rules` do not allow this user to change | Show "Bu kayıt korunuyor"; do not retry |
| `quota_exceeded` | The installation's database is full (rows or bytes) | Ask an admin to raise the limit, or delete rows |
| `not_installed` | The app is not installed (or was disabled) for this user | Nothing to do in code |
| `unknown_method` | The host does not know the call (older Olan) | Check `olan.*` names; require a newer server with `minServerVersion` |
| `host_error` | The host failed, or `olan.*` was called before the runtime started (e.g. at module top level) | Call `olan.*` from effects, handlers or `useQuery` |
| `cancelled` | The app was closed while the call was pending | Ignore |
| `backend_function_not_found` | `olan.backend.call(name)`: the backend has no `functions[name]` | Add it to `defineBackend({ functions })` (backend.md) |
| `backend_error` | The backend function threw (`message` is its error) or `dist/server.js` does not load | Fix the function; check the logs (Studio → Backend, `olan-app dev`) |
| `backend_limit` | The backend call ran out of CPU (1 s), time (10 s) or memory (64 MiB) | Do less per call; move periodic work to `schedules` |
| `backend_busy` | More than 4 backend calls at once for this installation | Retry later |
| `payload_too_large` | `backend.call` arguments or result over 256 KiB | Send ids, page results |
| `backend_unavailable` | The app has no `server`, or backends are off on this server | Declare `server`; ask the admin |
| `backend_migrating` | After an update, the new version's `migrate` has not succeeded yet (retried with backoff, then by hand) | Retry later; fix `migrate` (Studio → Backend shows the error) |
| `remote_rejected` | `olan.remote.request`: the app server answered 400–499; `RemoteError.status` is its status, `details` its body (remote-requests.md) | Show the server's reason (e.g. 422 `issues` per field); do not retry unchanged |
| `remote_unavailable` | `olan.remote.request`: the app server answered 500–599 (`reason: 'http_status'`) or gave no usable answer: `timeout`, `network`, `invalid_response` (not HTTP 200 with the `{ status, headers?, body? }` wrapper), `response_too_large` (> 4 MiB) | A `Banner` with "Tekrar dene"; on the server, check the `/requests` route and the wrapper |
| `consent_required` | The person has not consented to the app yet (remote requests) | Nothing in code: Olan shows the consent screen on the next open |
| `rate_limited` | Over 300 remote requests a minute (or 8 at once) per person and installation; `RemoteError.retryAfterSeconds` | Wait and retry; poll less often |
| `feature_not_enabled` | The organization's plan does not include this app (`details.feature` on the server) | Nothing in code; an admin changes the plan |
| `payload_too_large` | Also: a `remote.request` body over 1 MiB | Send less, or upload files with `olan.files.upload` |
| `upload_failed` | `olan.files.upload`: network error, or no progress for 60 s | Offer to retry the upload |
| `project_not_enabled` | SDK 1.6: the call names a project the app was not added to (`olan.projects.*`, `olan.project.*`) | Say "Uygulama bu projeye eklenmemiş"; a member adds it on the project page → Uygulamalar |

`olan.project.*` (SDK 1.7) map the server's reasons to these codes; the reason is in `message`:
`not_found` — `link_not_found`, `status_not_found`, `label_not_found`, `calendar_item_not_found`,
`approval_not_found`, `field_not_found`, `task_not_found`, `issue_not_found` (refetch); `validation_failed` —
`invalid_card` (a record card with a `submit` button or another card problem: use `{ kind: 'open' }`);
`conflict` — `status_key_taken`, `label_key_taken`, `field_key_taken`, `status_name_taken`, `label_name_taken`,
`field_name_taken` (the project already uses the key or name: pick another), `field_read_only` (the field's app was
removed from the project), `approval_not_pending` (already decided or cancelled),
`last_status_in_category` (the project keeps one status of each required kind), `project_archived`;
`quota_exceeded` — `record_links_limit` (10 records per task or issue), `calendar_items_limit` (500 per
project), `fields_limit` (50 fields per project); `invalid_params` — `invalid_key`, `invalid_definitions`, `status_category_immutable`,
`invalid_target`, `invalid_status`, `invalid_state`, `invalid_range`, `invalid_approvers` (not a
member who may change the project), `invalid_text`, and for fields `invalid_field_type`, `field_type_immutable`,
`invalid_field_options`, `invalid_field` (no such field for that task or issue), `invalid_field_value`, `field_required`.
| `cancelled` | Also: an upload stopped with `task.cancel()` / `olan.files.cancel` | Expected after your own cancel; reset the progress UI |
| `http_blocked` | Also: an upload `url` that is not on the `remote.url` origin or a granted `http:<host>` (or `http:` outside development) | Upload to your app server's origin (files.md#where-uploads-may-go) |

## `olan-app validate`

Each error has `code`, `message`, `file`, `line`/`column` when known, and a `hint`.

### Manifest (`olan-app.json`)

| Code | Fix |
|---|---|
| `manifest.missing` | Create `olan-app.json` (`olan-app init`, or copy manifest.md) |
| `manifest.invalid_json` / `manifest.not_object` | Fix the JSON syntax; the file is one object |
| `manifest.unknown_field` | Remove the field (only the fields in manifest.md exist) |
| `manifest.feature_not_available` | This server turned backend code off (`OLAN_APPS_BACKEND=0`; locally the same variable): remove `server`, or use your own server (`remote`, server.md) or `olan.http.fetch` |
| `manifest.schema_version` | `"schemaVersion": 1` |
| `manifest.id` | Lowercase reverse domain: `"com.example.my-app"` |
| `manifest.name` | 1–80 characters |
| `manifest.version` | Semver: `"0.1.0"` |
| `manifest.sdk` | `"^1.5.0"` |
| `manifest.schema_url` | `$schema` is `"https://olan.app/schemas/olan-app/v1.json"`, or remove it |
| `manifest.min_server_version` | Semver, or remove it |
| `manifest.description` | ≤ 400 characters |
| `manifest.entry` / `manifest.entry_required` | `"entry": "dist/app.js"` |
| `manifest.icon` | A png/svg/jpg/webp path in the package, e.g. `"assets/icon.png"` |
| `manifest.kind` | `"app"` or `"web-link"` |
| `manifest.surfaces_required` | `"surfaces": { "app": { "title": "…" } }` |
| `manifest.surface_unknown` | Use a surface from surfaces.md |
| `manifest.surface_invalid` | `app`/`project.widget`/`settings`: `{ "title"?: string }`; other surfaces need `"title"` (1–80); `chat.command` `description` ≤ 120 |
| `manifest.project_template_invalid` | `projectTemplates`: ≤ 5 `{ key, name, description?, content }` with unique keys; `content` is `{ version: 1, lists, statuses?, labels?, tasks?, recordTemplates?, settings? }` (manifest.md#projecttemplates) |
| `manifest.command_invalid` | `chat.command` needs `"command"`: `^[a-z][a-z0-9-]{1,31}$`, e.g. `"standup"` |
| `manifest.permissions` / `manifest.permission_unknown` | Use a permission from permissions.md or `http:<host>` (no scheme or path); `remote` and `ai:tools` are implied, never listed |
| `manifest.permission_reserved` | The permission is reserved for a later phase (none today) |
| `manifest.remote_invalid_url` | `remote` is `{ "url", "jwksUrl", "requests"? }`: https URLs without credentials, query or fragment (http only for localhost/private addresses); `requests` a boolean |
| `manifest.profile_requires_remote` | `profile:read` only adds fields to remote requests: add `"remote": { "url", "jwksUrl", "requests": true }`, or remove `profile:read` |
| `manifest.events_require_remote`, `manifest.ai_tools_require_remote` | Add `remote`: events and tools go to the app's own server |
| `manifest.event_unknown` | Use an event type from server.md#events |
| `manifest.event_permission_missing` | Add the permission the event needs (`detail: { event, permission }`) |
| `manifest.ai_tool_invalid` | Tool `name` `^[a-z][a-z0-9_]{1,31}$` and unique, `description` 1–1024, `input` a JSON Schema with `"type": "object"` (≤ 8 KiB, only `#…` `$ref`), not both `readOnly` and `destructive`, ≤ 16 tools; `timeoutMs` an integer 1000–60000, at most 15000 on a `readOnly` tool |
| `manifest.ai_tool_permission_missing` | A tool's `permissions` must also be in the manifest's `permissions` |
| `manifest.web_link_remote` | Web links have no `remote`, `events`, `ai` or `server` |
| `manifest.server_invalid` | Fix `server` (`entry` a .ts/.js path in the package, `schedules` cron ≥ 5 minutes apart and unique names, `hooks` `verify` with `header` and a `secret: true` `secretSetting`) |
| `manifest.permission_duplicate` | Remove the repeated permission |
| `manifest.settings_field` | Fix the settings field: `type`, `label`, `default` of the right type, `select` with `options` containing the default |
| `manifest.url` / `manifest.url_required` / `manifest.url_not_allowed` | `url` only for `kind: "web-link"` |
| `manifest.web_link_entry` / `_surface` / `_permissions` / `_settings` / `_data` | Web links have none of these |
| `manifest.data_version` | `data.version` is an integer 1–1000000; increase it when the schema changes |
| `manifest.data_collections_required` | `data` is `{ "version", "collections" }` with at least one collection |
| `manifest.data_collection_name` / `manifest.data_collection_limit` | Collection names `^[a-z][a-z0-9_]{0,39}$`; at most 20 |
| `manifest.data_scope` | `"scope": "organization"` or `"user"` |
| `manifest.data_field_name` / `manifest.data_field_reserved` / `manifest.data_field_limit` | Field names `^[A-Za-z][A-Za-z0-9_]{0,63}$`, not `id`, `createdAt`, `updatedAt`, `createdBy`, `revision`; at most 64 |
| `manifest.data_field_type` | `type`: `string`, `number`, `boolean`, `date`, `datetime`, `json`, `ref:project`, `ref:task`, `ref:user` |
| `manifest.data_field_option` | An option the type does not have (e.g. `maxLength` on a number) or a bad value (`maxLength` 1–10000, `enum` 1–100 unique strings, `min` ≤ `max`) |
| `manifest.data_index_limit` / `manifest.data_index_type` | At most 5 `indexed` fields; `json` cannot be indexed, strings only with `maxLength` ≤ 512 or `enum` |
| `manifest.data_rules` | `rules` only on `organization` collections; values `"any"` or `"owner"` |
| `manifest.invalid` | Other schema error; read the message |

### Build and files

| Code | Fix |
|---|---|
| `build.entry_missing` | Create `src/app.tsx` with `export default defineApp({ … })` |
| `build.sdk_missing` | `npm install` |
| `build.error` | Syntax or import error at `file:line`; "Could not resolve" → install the package or fix the path |
| `build.forbidden_import` | Remove imports of `react-dom`, `react-native`, Node built-ins or `@olan-app/cli` from `src/` |
| `build.manifest_invalid` (warning) | `build` ran although `olan-app.json` has errors; run `olan-app validate` |
| `build.warning` (warning) | esbuild warning; usually a real bug |
| `build.too_large` (warning), `validate.bundle_too_large`, `validate.package_too_large` | Bundle/package over 5 MiB: drop big dependencies (`olan-app build --json` → `largestInputs`) or assets |
| `validate.entry_missing` | Run `olan-app build` (or drop `--no-build`) |
| `validate.icon_missing` | Add the icon file or remove `"icon"` |
| `validate.typescript_missing` (warning) | `npm install -D typescript` |
| `build.backend_node_import` | Backend code (`server/`) imported a Node module (`fs`, `crypto`, `node:*`, `axios`, …): use `olan.http.fetch`, `olan.db`, `olan.secrets` (backend.md) |
| `build.backend_forbidden_import` | Backend code may import only `@olan-app/sdk/backend` from the SDK, no React and no `@olan-app/cli` |
| `build.backend_entry_missing`, `build.backend_missing` | Create `server.entry` (`export default defineBackend({ … })`) |
| `build.backend_error` | Syntax or import error in backend code at `file:line` |
| `build.backend_large` (warning) | `dist/server.js` is over 1 MiB; every new sandbox loads it |
| `validate.backend_missing` | `dist/server.js` does not exist: run `olan-app build` (or drop `--no-build`) |
| `validate.backend_load`, `validate.backend_default_export` | `dist/server.js` does not load in the backend runtime (a top-level throw, a Node API at the top level) or has no `export default defineBackend(...)` |
| `validate.backend_handler_missing` | A `server.schedules`/`events`/`hooks` entry has no handler: add `schedules[name]`/`events[type]`/`hooks[name]` or `functions[<its function>]` (backend.md#handler-resolution) |
| `validate.backend_handler_unused` (warning) | `defineBackend` has a schedule, event or hook handler the manifest does not declare, so Olan never runs it |
| `backend.engine` (warning) | The backend engine fell back (`isolated-vm prebuild not available on <platform>; using QuickJS (slower)`) |
| `backend.engine_unavailable`, `backend.runtime_missing` | `--engine isolated-vm` cannot start here: use `--engine quickjs` or `auto`; reinstall `@olan-app/cli` |
| `typescript.TS<n>` | A type error at `file:line` (e.g. `typescript.TS2322`: wrong prop type, `TS2741`: missing required prop) |
| `typescript.failed` | `tsc` could not run; read the message |

### `--strict`: rendering every surface

| Code | Fix |
|---|---|
| `app.default_export` | End `src/app.tsx` with `export default defineApp({ app: MyScreen })` |
| `app.surface_missing` | The manifest declares a surface `defineApp` does not define: add it or remove it from `surfaces` |
| `app.surface_undeclared` (warning) | Declare the surface in `olan-app.json` or remove it from `defineApp` |
| `runtime.load_failed` | `src/app.tsx` throws at import time (top-level code); move it into components |
| `runtime.render_failed` / `runtime.error` | The surface threw while rendering with the default fixtures. "`fetch`/`window`/`document`/`localStorage` is not defined" → use `olan.*`; otherwise guard missing data (`data?.items ?? []`) |
| `runtime.unknown_method` | Use only the `olan.*` calls in api.md |
| `permission.missing` | A write in a handler (found in `src/`, at `file:line`) or a backend call needs a permission the manifest lacks: add it. `olan.files.*` needs `files:pick`; `olan.remote.request` needs `"requests": true` in `remote` |
| `fixtures.db_invalid`, `fixtures.db_unknown_collection` | A row in `fixtures/db.json` does not match its collection in `data.collections`, or names a collection the manifest does not declare; fix the row or the collection name (rendering continues on an empty database) |
| `fixtures.http_missing` (warning) | Add the URL to `fixtures/http.json` so headless runs get a response |
| `fixtures.remote_missing` (warning) | Add the route to `fixtures/remote.json` (or pass `renderApp({ remote })`) so `olan.remote.request` gets an answer |
| `tree.unknown_type` | Only the 23 SDK components exist; no `<div>`, `<span>`, `<img>` (use `Image`). An Olan server before 1.5 reports it for the SDK 1.5 components |
| `tree.unknown_prop` | Remove the prop (no `style`, `className`, `color`, `onClick` — it is `onPress`) |
| `tree.invalid_prop` | Wrong value: check the allowed values in components.md (e.g. `gap="16"` → `gap="md"`, missing required `label`, `Menu` without `label` and `icon`, `format: 'currency'` without `currency`, `Tabs` with fewer than 2 or more than 8 items, `stacked` on a line chart, an `Image` `src` that is not an http(s) URL) |
| `tree.text_outside_text` | Wrap strings and numbers in `<Text>` |
| `tree.children_not_allowed` | Only `Screen`, `Stack`, `Card`, `Form` take children; `Text` takes text; `List`, `Button`, `Badge` … take none (use props) |
| `tree.text_invalid` | Text nodes carry one string |
| `tree.child_missing`, `tree.cycle`, `tree.shared_child`, `tree.root_missing`, `tree.id_mismatch`, `tree.invalid_node` | Internal tree errors; report them with the app source |
| `ui.empty_tree` (warning) | The surface rendered nothing; render an `EmptyState` instead of `null` |
| `ui.root_not_screen` (warning) | Start `app`/`settings` surfaces with `<Screen>` (only these two are checked; `project.widget` uses `Card`, modals and panels should use `Screen`) |

### `--strict`: Olan Marketplace review checks

The marketplace's static checks (`@olan-app/schema` `runStaticReviewChecks`, `reviewPermissions`,
`lintUiTree`) on the files `pack` would package, merged with the calls the surfaces made: the same
codes, severities and guideline (`rule`, explained in review-guidelines.md) the marketplace reports (marketplace.md#automatic-checks).
Errors fail `validate`, warnings print, info findings show with `--verbose` (`--json`: `result.review`).

| Code | Fix |
|---|---|
| `permissions.missing` | Add the named permission (or remove the call); with a `file:line` in `src/` when the source scan found the call |
| `permissions.http_missing` | `olan.http.fetch` without `http:<host>`, or a fetched host not granted: add `http:<host>` |
| `permissions.unused`, `permissions.http_unused` (warnings) | Remove permissions nothing uses. Counted as use: `olan.*` calls in `dist/app.js` and, with `server`, in `dist/server.js` (SDK 1.5.1; before, backend-only use was not seen), event subscriptions (`events`, `server.events`) and `ai.tools[].permissions`. What your own server (`remote`) does with its tokens is not visible: the reviewer reads your listing |
| `permissions.http_hosts` (info) | The hosts the app may call; the listing must explain each |
| `a11y.button_label_missing`, `a11y.field_label_missing`, `a11y.menu_item_label_missing`, `a11y.action_label_missing` | Give every `Button`, field (also `Switch`, `MultiSelect`), menu item and action (also a `Banner` action) a non-empty `label` |
| `a11y.tab_label_missing` | Every `Tabs` item needs a non-empty `label`; the `Tabs` `label` (the group's name) is optional but not empty |
| `a11y.avatar_name_missing` | Give every `Avatar` the person's or brand's `name` (read aloud, and the initials) |
| `a11y.menu_label_missing`, `a11y.image_alt_missing` (warnings) | Add `label` to icon-only menus; `alt` to images (`""` only for decoration) |
| `a11y.list_key_missing`, `a11y.duplicate_key` (warnings) | Every `List` item needs a unique `key`; make `Menu` item, `Table` row and action keys unique |
| `forbidden.*` (e.g. `forbidden.eval`, `forbidden.function_constructor`, `forbidden.dom`, `forbidden.fetch`) | Remove the API from the bundle (`dist/app.js#line:column`); use `olan.*` and SDK components |
| `files.native_binary`, `files.type_not_allowed`, `files.svg_active_content`, `files.entry_missing`, `files.source_map` (warning) | Package only JS, JSON, images, text; plain SVGs; no source maps |
| `size.package_too_large`, `size.entry_large` (warning), `size.summary` (info) | Stay ≤ 5 MiB; keep the entry under 2 MiB |
| `licenses.copyleft` (warning), `licenses.found`, `licenses.notices_missing` (info) | Copyleft code gets manual review; `olan-app` keeps license comments at the end of `dist/app.js` |

### Data schema changes (install and update)

The server compares the new `data` with the stored one: `409 data_schema_incompatible` with
`issues`. Fix: keep the change additive and increase `data.version` (database.md#changing-the-schema).

| Code | Fix |
|---|---|
| `data.version_not_bumped` | The schema changed: increase `data.version` |
| `data.version_downgrade` | `data.version` must not go down |
| `data.collection_removed`, `data.field_removed` | Keep it (stop using it instead) |
| `data.type_changed`, `data.scope_changed` | Add a new field or collection instead |
| `data.required_added` | Add the field as optional |
| `data.constraint_tightened` | Keep `maxLength`/`max` as large, `min` as small, every `enum` value, no new `integer` |

## Other commands

| Code | Fix |
|---|---|
| `cli.unknown_command`, `cli.unknown_option`, `cli.missing_value`, `cli.invalid_option` | See `olan-app <command> --help` (exit code 2) |
| `cli.internal` | An unexpected failure; the message (and the stack without `--json`) says where |
| `project.not_found` | Run inside an app directory or pass `--cwd` |
| `test.none` | Add `tests/*.test.ts` with at least one `test(...)` |
| `test.build_error` | The test file does not compile; see `file:line` |
| `test.failed` | Assertion or app failure; the message includes the visible text |
| `test.process_crashed` (warning) | Every test of the file passed, then its process exited with a non-zero code (on Windows often `0xC0000409`, the Node/libuv abort while sockets close); not counted as a failure. Rerun; if it repeats, look for `process.exit()` or aborts in `after()` hooks |
| `test.report_pattern`, `test.package_without_report` | A report covers the whole suite (drop the pattern); `--package` needs `--report` |
| `test.report_too_many`, `test.report_too_large`, `test.report_invalid` | A report holds ≤ 2000 tests and ≤ 512 KiB; shorten names or split the suite |
| `test.report_package_stale` (warning) | `dist/<id>-<version>.olanapp` is another build than the report's package: pack again before `publish --file` |
| `package.missing`, `package.unreadable` | `--package` must be a `.olanapp` made by `olan-app pack` |
| `fixtures.invalid_json`, `fixtures.invalid`, `fixtures.users_invalid` | Fix the fixture file (testing.md#fixtures; users need `id`, `displayName`, `email`) |
| `init.name_required`, `init.name_too_long`, `init.invalid_id`, `init.not_empty`, `init.unknown_template`, `init.template_conflict` | Fix the `init` arguments (`--backend` is the `backend` template; it cannot be combined with another `--template`) |
| `pack.key_missing`, `pack.key_invalid` | Run `olan-app keygen` or pass a valid `--sign-key` (`--dev-sign` creates the development key itself) |
| `pack.validation_failed` | `pack` ran the `validate` checks and found the errors listed after it: fix them (and run `validate --strict`); `--no-validate` packages anyway |
| `pack.sign_conflict` | `--dev-sign` signs with the development key; drop `--sign-key`/`--no-sign` |
| `pack.entry_missing`, `pack.icon_missing`, `pack.unsafe_path`, `pack.too_large`, `pack.web_link`, `pack.signature_failed` | Fix the files named in the message |
| `pack.version_invalid` | The version to package (`olan-app try`'s server-named `-dev.N`) is not semver: check the server's `nextVersion` |
| `pack.backend_missing` | The manifest has `server` but `dist/server.js` is missing: run `olan-app build` |
| `keygen.exists` | Keep the key, or `--force` to replace it |
| `keygen.dev_out` | `--dev` keeps the key in `~/.olan`; set `OLAN_APP_DEV_KEY` for another file |
| `sign.key_required`, `sign.key_missing`, `sign.key_invalid`, `sign.key_encrypted`, `sign.key_not_ed25519`, `sign.key_id_invalid` | Internal `olan-app sign`: pass `--key` with an unencrypted PKCS#8 Ed25519 PEM; `--key-id` is 1-64 letters, digits, `.`, `_`, `-` |
| `sign.package_required`, `sign.package_missing`, `sign.package_invalid`, `sign.package_too_large`, `sign.digest_missing`, `sign.digest_invalid`, `sign.digest_mismatch`, `sign.signature_failed` | Pass one package made by `olan-app pack`; if it changed after packing, pack it again |
| `validate.unsigned` (warning, `--strict`) | Nothing to do for `publish --marketplace` (the marketplace signs approved versions). For an organization catalog (`publish --org`) a plain `pack` is unsigned and not installable: `olan-app pack --dev-sign` / `publish --org --dev-sign` locally with your development key (`keygen --dev`; cli.md#signing-and-publishing) |
| `manifest.description_template` (warning, `--strict`) | `description` is still the `olan-app init` template's: describe your app (guideline 5.1) |
| `publish.target_required` | Pass `--marketplace` (production, marketplace.md) or `--org` (development servers) |
| `publish.target_conflict`, `publish.marketplace_option` | Use one target; `--developer`, `--channel`, `--percent`, `--visibility` are for `--marketplace` only |
| `publish.server_required`, `publish.token_required` | Use `olan app publish --org` (signed in), or pass `--server` and `--token`/`OLAN_TOKEN` |
| `publish.network` | Check `--server` (the API address) |
| `publish.test_report_missing`, `publish.test_report_invalid` | `--test-report` must be the JSON file `olan-app test --report <file>` wrote |
| `publish.file_missing` | The `--file` package does not exist; run `olan-app pack` or drop `--file` |
| `publish.apps_disabled` | Olan Apps are turned off on that server |
| `publish.dev_sign_file` | `--dev-sign` packs and signs; drop `--file` (or upload a package you packed with `pack --dev-sign`) |
| `publish.package_unsigned` (warning) | Uploaded but unsigned, so it cannot be installed. Locally: `publish --dev-sign` and trust the key (`keygen --dev`); production installs need Olan Marketplace signing |
| `publish.package_untrusted_key` (warning) | Uploaded, but the server does not trust the signing key; on a development server add it to `OLAN_APPS_TRUSTED_KEYS` |
| `publish.<server error>` | e.g. `publish.version_exists` (bump `version`), `publish.forbidden`/`admin_required` (admins only), `publish.invalid_token` (sign in again); package issues come with their own codes (`package.*`, `manifest.*`) |
| `docs.query_required`, `docs.sdk_missing` | Pass a query; `npm install` |
| `dev.port_in_use` | Stop the other server or `--port <n>` |
| `dev.remote_missing` | `dev --remote live` needs `remote` (with `requests: true`) in `olan-app.json` |
| `cli.usage`, `revocations.dev_required`, `revocations.input_required`, `revocations.input_missing`, `revocations.input_invalid`, `revocations.entry_invalid`, `revocations.signature_failed` | `olan-app revocations sign --dev --in list.json`; entries need `appId` (and `versions`/`packageSha256`, `reason`) |
| `mcp.no_session`, `mcp.invalid_input` | Call `olan_app_render` first; pass `label`/`value` |
| `events.unknown_type` | Use an event type from server.md#events |
| `events.delivery_failed` | The app server did not answer 2xx; 401 usually means the dev issuer `http://127.0.0.1:5180` is not in its `issuers` |
| `events.not_subscribed`, `events.permission_missing` (warnings) | Olan would not send this event: add it to `events` / add its permission |
| `tools.unknown_tool`, `tools.input_invalid` | Use a tool from `ai.tools`; make `--input` match its `input` schema |
| `tools.response_invalid` | Answer HTTP 200 with `{ ok: true, result }` or `{ ok: false, error: { code, message } }`, ≤ 64 KiB, `summary` ≤ 500 |
| `remote.missing`, `remote.invalid_url`, `remote.unreachable`, `remote.issuer_port` | Add `remote` or pass `--to`; start the app server; free port 5180 or pass `--issuer-port` |
| `remote.request_invalid` | `requests send`: the method, path, query, headers or body break the `olan.remote.request` rules (remote-requests.md#calling-it); put the query in `?…` or `--query`, not in the path segments |
| `requests.delivery_failed` | `requests send` got no usable answer (the app sees `remote_unavailable` with that `reason`): 401 = the app server does not list the dev issuer `http://127.0.0.1:5180`; `invalid_response` = not HTTP 200 with `{ status, headers?, body? }`; `network` = not running |
| `requests.not_enabled` (warning) | `remote` has no `"requests": true`, so Olan refuses `olan.remote.request` |

## Olan Marketplace

`login`, `developer`, `app`, `publish --marketplace`, `status --marketplace` and `release` report `marketplace.<code>`
in human output; with `--json` they print `{ error: "<code>", message, hint?, issues? }` (marketplace.md).

| Code | Fix |
|---|---|
| `marketplace.target_required`, `marketplace.app_required`, `marketplace.action_required`, `marketplace.invalid_option`, `marketplace.invalid_url` | Fix the arguments: `--marketplace [url]`, the app id, `developer create\|list`, `--channel stable\|beta`, `--percent 1-100` (needs `--channel`), `--visibility public\|org\|organization:<serverId>/<organizationId>`, `--slug`/`--name`/`--kind` |
| `marketplace.server_required` | `login` needs the Olan API address: `--server <url>`, `OLAN_SERVER` or `OLAN_API_URL` |
| `marketplace.token_required` | `--token` was empty: drop it to sign in in the browser, or pass an Olan access token (`olan app login --marketplace` passes one; CI uses `OLAN_MARKETPLACE_SESSION` instead) |
| `marketplace.server_unreachable`, `marketplace.network` | Check `--server` / `--marketplace` (or `OLAN_MARKETPLACE_URL`) and the connection |
| `marketplace.sign_in_unsupported` | The server has no OpenID configuration with PKCE: check `--server`, or use `OLAN_TOKEN` / `olan app login --marketplace` |
| `marketplace.sign_in_timeout`, `marketplace.sign_in_denied` | Run `login` again and finish signing in within 5 minutes, in a browser on the same computer |
| `marketplace.sign_in_failed` | The server refused the code exchange; `invalid_client`: the server predates the `olan-app-cli` client (update it, or use `OLAN_TOKEN`) |
| `marketplace.identity_token_failed` | 401: the access token expired (sign in again); 403: ask an admin for the `developer` grant; 404: the server predates marketplace sign-in |
| `marketplace.identity_invalid`, `marketplace.identity_untrusted_issuer` | The marketplace did not accept your server's identity: sign in again; an unregistered server must be verified with the marketplace by its administrator |
| `marketplace.session_missing`, `marketplace.session_expired`, `marketplace.developer_sign_in_required`, `marketplace.session_invalid`, `marketplace.session_other_marketplace` | Run `olan-app login --marketplace [url]` (CI: a valid `OLAN_MARKETPLACE_SESSION`) |
| `marketplace.session_env_override` (warning) | `OLAN_MARKETPLACE_SESSION` replaces the session `login` just saved; unset it |
| `marketplace.developer_account_missing` | `olan-app developer create --marketplace --slug <slug> --name <name> --accept-agreement` (or accept an invite) |
| `marketplace.developer_required` | You belong to several developer accounts: pass `--developer <slug>` |
| `marketplace.developer_not_found`, `marketplace.developer_role_required` | Check `--developer` (`olan-app developer list`); ask an owner or admin for the role |
| `marketplace.developer_exists` | The developer name is taken (`olan…` is reserved): choose another `--slug` |
| `marketplace.agreement_required`, `marketplace.agreement_unknown` | Pass `--accept-agreement` to `developer create`; existing accounts accept a new version in Studio → Yayınla |
| `marketplace.file_missing`, `marketplace.package_unreadable` | `--file` must be a package made by `olan-app pack` |
| `marketplace.package_invalid` (with issues), `marketplace.package_too_large` | Fix the listed package issues (`validate --strict`); stay ≤ 5 MiB |
| `marketplace.version_exists`, `marketplace.version_not_increasing` | Raise `version` in `olan-app.json` |
| `marketplace.app_not_found`, `marketplace.version_not_found` | No such app in your developer accounts, or no such version: check the id and version (`status` shows the newest) |
| `marketplace.app_owned_by_other_developer`, `marketplace.app_id_reserved` | Change `id` (`com.olan.*`, `app.olan.*`, `olan.*` are Olan's), or pass the owning `--developer` |
| `marketplace.age_rating_required`, `marketplace.age_rating_not_allowed` | Release needs an age rating: `olan-app app set --marketplace <appId> --age-rating 4+` (4+, 9+ or 13+; or Studio → Yayınla → the app → Mağaza sayfası); Olan does not accept 16+ or 18+ (guideline 5.4) |
| `marketplace.age_rating_not_set` | `publish --age-rating` submitted the version but could not save the rating: run the `olan-app app set` command in the hint |
| `marketplace.visibility_org_unknown`, `marketplace.visibility_ignored` (warning) | Pass `--visibility organization:<serverId>/<organizationId>`; visibility applies only when an app is created |
| `marketplace.server_not_found`, `marketplace.server_not_verified`, `marketplace.organization_not_allowed` | Organization-only apps need a server registered and verified with the marketplace, and an admin or developer sign-in through it |
| `marketplace.checks_failed`, `marketplace.rejected`, `marketplace.withdrawn` | Fix the findings listed after it (marketplace.md#automatic-checks) or the review notes, then publish again; the cited guideline is explained in review-guidelines.md |
| `marketplace.review_state_conflict`, `marketplace.rollout_invalid` | Only approved versions are released; a rollout only widens (10 → 50 → 100) and only once released; `halt` stops it |
| `marketplace.app_not_active`, `marketplace.package_revoked` | The app is suspended or the version revoked by Olan: publish a fixed version |
| `marketplace.submission_not_found`, `marketplace.submission_state_conflict` | `withdraw` and test reports need a submission that is still `checking` or `in_review` |
| `marketplace.test_report_invalid`, `marketplace.test_report_signature_invalid`, `marketplace.test_report_mismatch` | Generate the report again after packing, from the sources you publish (`olan-app test --report <file>`), and do not edit it |
| `marketplace.test_report_not_attached` | The package was submitted, the report was not: fix it and attach it in Studio → Yayınla |
| `marketplace.invalid_request` | The marketplace refused a parameter; check the command's options |
| `marketplace.rate_limited`, `marketplace.http_<status>` | Wait and retry; another status means the marketplace answered without an error body |

## Cards

`olan.chat.postCard` / `updateCard` fail with `validation_failed` listing these (cards.md):

| Code | Fix |
|---|---|
| `card.invalid` | `{ version: 1, root, nodes, fallbackText }` and nothing else |
| `card.fallback_text` | `fallbackText` 1–500 characters |
| `card.too_large`, `card.too_many_nodes`, `card.too_deep` | ≤ 16 KiB, ≤ 100 nodes, depth ≤ 8 |
| `card.component_not_allowed` | Only `Card`, `Stack`, `Text`, `Badge`, `Table`, `Button`, `EmptyState` |
| `card.handler_not_allowed` | No handlers in cards; buttons use `action` |
| `card.action_invalid`, `card.payload_too_large` | `{ kind: 'open', payload? }` or `{ kind: 'submit', name, payload? }`, `payload` ≤ 2 KiB; record cards (`olan.project.links.upsert`, `approvals.request`) only `open` |
| `card.submit_requires_remote` | `submit` buttons need `remote`; use `open` |
| `tree.*` | As in validate (props, children, text placement) |

## Install errors from the server

Uploading accepts any well-formed package; installing it is another matter (cli.md#signing-and-publishing).

| Error | Meaning | Fix |
|---|---|---|
| `package_unsigned` (403) | The version has no `signature.json`; the server installs, updates to or serves only signed versions | Locally: `olan-app pack --dev-sign` with your key on the server's `OLAN_APPS_TRUSTED_KEYS`; production: Olan Marketplace signs the app |
| `package_untrusted_key` (403, `keyFingerprint`) | Signed, but by a key not on the server's trusted list (or a key that was removed); from `developer/try` also when the key is not one you registered (`reason: developer_key_revoked \| developer_not_member` for one that stopped) | Sign with a trusted key; for `olan-app try`, register your development key (`olan-app keys register`); development servers may add it to `OLAN_APPS_TRUSTED_KEYS` |
| `developer_key_revoked` / `developer_not_member` (403) | A development installation signed with your registered key: the key was revoked, or you are no longer a member of the organization. The installation is kept | Register a new key (`keygen --dev --force`, `keys register`) and `olan-app try` again |
| `key_exists` (409) | `keys register`: the key is already registered (a revoked key cannot come back) | Use it, or create a new key |
| `package_invalid` with `package.signature_invalid` (400, on upload) | The signature does not verify against the package digest | Pack again; do not edit a package after signing |

<!-- docs/examples.md -->
# Examples

Complete apps live in the Olan repository under `examples/` (each passes `validate --strict` and
`test`, with fixtures and tests to copy):

| Example | Shows |
|---|---|
| `examples/project-pulse` | `app` surface, three screens on the navigation stack, status `Badge`s, `Menu` → `olan.projects.updateTask` with `revision`, `OlanError` handling, toasts (`projects:read`, `projects:write`) |
| `examples/overdue-widget` | `project.widget` surface with `params.projectId`, manifest `settings` + `useSettings`, date logic tested with a frozen clock (`projects:read`) |
| `examples/exchange-rates` | `olan.http.fetch` with `http:<host>`, `Table`, `Chart`, a `settings` surface with a `Select` saving to `olan.storage`, HTTP fixtures, retry (`http:rates.example.com`, `storage`) |
| `examples/decision-log` | `olan.db` with an `organization` and a `user` collection, `useCollection` with a status filter and `loadMore`, `useRecord`, "Göreve dönüştür" → `olan.projects.createTask`, `deleteTask`, `deleteList` with `forbidden_record` → toast, `fixtures/db.json` (`projects:read`, `db`, `tasks:write`, `tasks:delete`, `projects:delete`) |
| `examples/ops-inbox` | Backend code (`server`, backend.md): `olan.backend.call('summary')` from the UI, a 5-minute `schedules` digest into `olan.db`, a `project.task.created` event handler, a GitHub hook verified with `hmac-sha256`, a `secret: true` setting read only by the backend (`olan.secrets.get`) and used for `olan.http.fetch`; `createBackendHarness` tests (`db`, `projects:read`, `http:ops.example.com`) |
| `examples/media-desk` | SDK 1.5 "Medya Masası": `olan.remote.request` to its own Node server (`handleRequest` routes, `RemoteError` → `Banner`, 422 issues on fields), `olan.files.pick` + `upload` with `ProgressBar` and cancel, `Image`/`Avatar` from the server, `openExternal` sign-in that returns (`appReturnUrl`, `state`, `useSurfaceParams<'app'>().return`), an `/apps/a/…/item?id=` address, `Tabs`, `Switch`, `MultiSelect`, `Stat`, stacked area `Chart`, sortable `Table`, `TextField maxLength`, `refetchIntervalMs`; server tests for signature, stale timestamp, unknown issuer and replay (`profile:read`, `files:pick`) |
| `examples/field-kit` | Every component, `Form`/`TextField`/`Select`/`DatePicker`, every `olan.ui.*` call, `app` + `project.widget`, settings, `olan.db`, task create/delete (the mobile acceptance app) |

These directories are in the Olan source repository, **not** in `node_modules`, so an app
project cannot open them; the table only says what each one shows. Everything you need is inline
in these docs: the snippets below are complete surfaces, and the database pattern (collection,
`useCollection`, insert/update/delete with `revision`, `conflict`/`forbidden_record` handling,
`fixtures/db.json`) is in database.md ("API", "Errors", "Testing").

The `olan-app init` templates (`blank`, `list-detail`, `data-list`, `project-widget`, `project-tab`,
`project-records`, `external-api`) are smaller starting points that land in your project: `npx olan-app init "Notlar"
--template data-list` writes a complete `olan.db` app (list, add with a `Form`, detail, update,
delete) with tests.

To install an example in a local Olan, pack it with your development key
(`npx olan-app pack --dev-sign`, inside the example directory) after adding the key to the local
Platform API (`npx olan-app keygen --dev` prints the `OLAN_APPS_TRUSTED_KEYS` line). A plain
`pack` is unsigned: the catalog lists it, but it does not install (cli.md#signing-and-publishing).

## A widget on the project page

```tsx
import { Card, EmptyState, List, defineApp, olan, useQuery, type SurfaceProps } from '@olan-app/sdk';

function OverdueCard({ params }: SurfaceProps) {
  const projectId = (params as { projectId?: string } | null)?.projectId ?? '';
  const tasks = useQuery(() => olan.projects.tasks(projectId), [projectId]);
  // A sketch: "today" here is the UTC date. A real app should compare in the project's
  // `timeZone` (olan.projects.get) and treat a due time (`2026-10-17T15:00`) as overdue once it passes.
  const today = new Date().toISOString().slice(0, 10);
  const overdue = (tasks.data ?? []).filter(
    (t) => (t.status === 'needs-action' || t.status === 'in-process') && t.due !== null && t.due.slice(0, 10) < today,
  );
  if (tasks.error) return <EmptyState title="Görevler yüklenemedi" description={tasks.error.message} />;
  if (!tasks.loading && overdue.length === 0) return <EmptyState title="Geciken görev yok" icon="check-circle" />;
  return (
    <Card title="Geciken görevler" subtitle={`${overdue.length} görev`}>
      <List loading={tasks.loading} items={overdue.map((t) => ({ key: t.id, title: t.title, meta: t.due ?? undefined, badge: { text: 'Gecikti', tone: 'danger' } }))} />
    </Card>
  );
}

export default defineApp({ 'project.widget': OverdueCard });
```

Manifest: `"surfaces": { "project.widget": { "title": "Gecikenler" } }`, `"permissions": ["projects:read"]`.

## Changing a task from a menu

```tsx
const STATUS_LABEL: Record<ProjectTaskStatus, string> = { 'needs-action': 'Yapılacak', 'in-process': 'Sürüyor', completed: 'Tamamlandı', cancelled: 'İptal' };

function TaskScreen({ projectId, taskId }: { projectId: string; taskId: string }) {
  const detail = useQuery(() => olan.projects.get(projectId), [projectId]);
  const task = detail.data?.tasks.find((t) => t.id === taskId);
  if (!task) return <Screen title="Görev" loading={detail.loading} />;
  return (
    <Screen title={task.title}>
      <Stack gap="md" padding="md">
        <Badge text={STATUS_LABEL[task.status]} />
        <Menu
          label="Durumu değiştir"
          items={(Object.keys(STATUS_LABEL) as ProjectTaskStatus[]).map((s) => ({ key: s, label: STATUS_LABEL[s], disabled: s === task.status }))}
          onSelect={async ({ key }) => {
            await olan.projects.updateTask(projectId, task.id, { status: key as ProjectTaskStatus, revision: task.revision });
            await olan.ui.toast({ text: 'Güncellendi', tone: 'success' });
            await detail.refetch();
          }}
        />
      </Stack>
    </Screen>
  );
}
```

Permissions: `projects:read`, `tasks:write` (apps written before SDK 1.1 use `projects:write`, which still allows `updateTask`).

## A form that saves to storage

```tsx
function Notes() {
  const notes = useQuery(async () => (await olan.storage.get<string[]>('notes')) ?? []);
  const add = async (text: string) => {
    if (!text.trim()) return;
    await olan.storage.set('notes', [...(notes.data ?? []), text.trim()]);
    await notes.refetch();
  };
  return (
    <Screen title="Notlar" loading={notes.loading}>
      <Stack gap="md" padding="md">
        <Form submitLabel="Ekle" onSubmit={({ values }) => add(values.text ?? '')}>
          <TextField name="text" label="Not" placeholder="Bir not yazın" />
        </Form>
        <List items={(notes.data ?? []).map((text, index) => ({ key: index, title: text }))} emptyText="Not yok" />
      </Stack>
    </Screen>
  );
}

export default defineApp({ app: Notes });
```

Permission: `storage`. Test: `await app.fill('Not', 'Süt al'); await app.press('Ekle'); app.expectText('Süt al');`.

## An external API

```tsx
const URL = 'https://status.example.com/api/services.json';   // permission "http:status.example.com"

function Services() {
  const services = useQuery(async () => {
    const response = await olan.http.fetch(URL, { headers: { accept: 'application/json' } });
    if (response.status !== 200) throw new Error(`API ${response.status}`);
    return response.json<{ services: { id: string; name: string; up: boolean }[] }>().services;
  });
  return (
    <Screen title="Servisler" loading={services.loading} actions={[{ key: 'refresh', label: 'Yenile', icon: 'refresh', onPress: () => services.refetch() }]}>
      {services.error ? (
        <EmptyState title="Durum alınamadı" description={services.error.message} action={{ label: 'Tekrar dene', onPress: () => services.refetch() }} />
      ) : (
        <List items={(services.data ?? []).map((s) => ({ key: s.id, title: s.name, badge: s.up ? { text: 'Çalışıyor', tone: 'success' } : { text: 'Kapalı', tone: 'danger' } }))} />
      )}
    </Screen>
  );
}
```

`fixtures/http.json`: `{ "https://status.example.com/api/services.json": { "status": 200, "json": { "services": [ … ] } } }`.

## Confirm before a destructive action

```tsx
<Button
  label="Hepsini temizle"
  variant="danger"
  onPress={async () => {
    if (!(await olan.ui.confirm({ title: 'Tüm notlar silinsin mi?', confirmLabel: 'Sil', destructive: true }))) return;
    await olan.storage.remove('notes');
    await notes.refetch();
  }}
/>
```

Test the "cancel" path with `renderApp({ ui: { confirm: false } })`. Review guidelines 2.1 (nothing is deleted without asking) and 4.1 (labelled controls) in review-guidelines.md.