237 lines · 10 KBtext/plain; charset=utf-8
The Coline App SDK: apps, tools, file types and surfaces that run inside Coline workspaces, and public websites with Coline Sites. TypeScript, with an in-memory test workspace. MIT.
| storage, scheduled triggers, and external API access — and public websites |
| 6 | with Coline Sites. Coline hosts your logic; there are no servers to deploy |
| 7 | unless you want them. |
| 8 |
| 9 | ```sh |
| 10 | npx create-coline-app my-app # an app for a workspace |
| 11 | npx create-coline-app my-site --template site # a public website, no account needed |
| 12 | ``` |
| 13 |
| 14 | Docs: [docs.coline.app](https://docs.coline.app) · |
| 15 | for coding agents: [docs.coline.app/agents.md](https://docs.coline.app/agents.md) |
| 16 |
| 17 | ## Define an app |
| 18 |
| 19 | ```ts |
| 20 | import { z } from "zod/v4"; |
| 21 | import { defineApp, defineTool, ui } from "@colineapp/sdk/v2"; |
| 22 |
| 23 | const createTodo = defineTool({ |
| 24 | name: "todos.create_todo", |
| 25 | description: "Create a todo with a title.", |
| 26 | input: z.object({ title: z.string().min(1) }), |
| 27 | effect: "write", // enforced by the runtime as a hard capability ceiling |
| 28 | execute: async (input, ctx) => { |
| 29 | const file = await ctx.coline.files.create({ |
| 30 | typeKey: "todos.todo", |
| 31 | name: input.title, |
| 32 | document: { title: input.title, status: "open" }, |
| 33 | }); |
| 34 | return { |
| 35 | output: { fileId: file.fileId }, |
| 36 | card: ui.reference({ kind: "file", id: file.fileId }), |
| 37 | }; |
| 38 | }, |
| 39 | }); |
| 40 |
| 41 | export default defineApp({ |
| 42 | key: "todos", |
| 43 | name: "Todos", |
| 44 | permissions: ["files.read", "files.write", "ai.tools"], |
| 45 | hosting: { default: "coline" }, |
| 46 | surfaces: { home: { tier: "tree" } }, |
| 47 | tools: [createTodo], |
| 48 | handlers: { |
| 49 | renderHome: async (ctx) => { |
| 50 | const { files } = await ctx.coline.files.list({ typeKey: "todos.todo" }); |
| 51 | return ui.stack([ |
| 52 | ui.heading("Todos"), |
| 53 | ...files.map((f) => ui.fileCard({ title: f.name, fileId: f.fileId })), |
| 54 | ]); |
| 55 | }, |
| 56 | }, |
| 57 | }); |
| 58 | ``` |
| 59 |
| 60 | One definition produces two artifacts: a serializable manifest (what the app |
| 61 | *may* do — reviewed and consented to) and a runtime bundle (what it *does*). |
| 62 | Every capability call is checked against the workspace's grants, the acting |
| 63 | user's access, and the declared tool effect. |
| 64 |
| 65 | ## The capability API |
| 66 |
| 67 | The same `coline.*` object everywhere your code runs — tools, render |
| 68 | handlers, schedules, hosted or external: |
| 69 |
| 70 | - `coline.files` — create/read/update/trash workspace files |
| 71 | - `coline.storage.kv` / `coline.storage.collection(name)` — app-private |
| 72 | key-value state and queryable records |
| 73 | - `coline.members`, `coline.notifications`, `coline.search` |
| 74 | - `coline.net.fetch` — external HTTP through Coline's allowlist, with |
| 75 | `{{secret:KEY}}` server-side credential injection |
| 76 |
| 77 | ## Test without a server |
| 78 |
| 79 | ```ts |
| 80 | import { createTestWorkspace } from "@colineapp/sdk/testing"; |
| 81 | import app from "./app.config"; |
| 82 |
| 83 | const ws = createTestWorkspace(app); |
| 84 | await ws.invokeTool("todos.create_todo", { title: "Ship it" }); |
| 85 | expect(ws.files.byType("todos.todo")).toHaveLength(1); |
| 86 | ``` |
| 87 |
| 88 | `@colineapp/sdk/testing` runs your app against an in-memory workspace with |
| 89 | the same capability contract as production. |
| 90 |
| 91 | ## Exports |
| 92 |
| 93 | | Entry | Contents | |
| 94 | |---|---| |
| 95 | | `@colineapp/sdk/v2` | `defineApp`, `defineTool`, `defineFileType`, `ui`, `actions`, manifest schemas, capability types, `createColineAppHandler` for external hosting | |
| 96 | | `@colineapp/sdk/testing` | `createTestWorkspace` — the in-memory test harness | |
| 97 | | `@colineapp/sdk` | The legacy v1 surface (frozen; do not use for new apps) | |
| 98 |
| 99 | ## Docs |
| 100 |
| 101 | Full guides at [docs.coline.app](https://docs.coline.app): [apps](https://docs.coline.app/sdk), |
| 102 | [sites](https://docs.coline.app/sites), and every page as Markdown in |
| 103 | [llms.txt](https://docs.coline.app/llms.txt). |
| 104 |
| 105 | MIT © Coline |
| 106 |
| 107 | ## Workflow |
| 108 |
| 109 | Run `coline-app check` before pushing: it checks types, the manifest, hosted logic, |
| 110 | and the React bundle without uploading. `dev --internal` updates one development |
| 111 | version; install it in the workspace and reload after changes. The CLI bundles |
| 112 | from the app's installed dependencies and preserves imported CSS and inline assets. |
| 113 | CLI 2.5 compiles app-specific Tailwind v4 and ordinary CSS automatically. |
| 114 | Import UI styles followed by app.css. The scaffold includes experimental UI |
| 115 | skills, screen examples, and a credential-free `coline-app preview` command. |
| 116 |
| 117 | The starter includes a React home and editor, tree mobile fallback, and a tool. |
| 118 | Use `coline.tools.invoke` or `actions.invokeTool` to run the same declared tool |
| 119 | from UI that Kairo runs. Save with `expectedVersion` to detect concurrent edits. |
| 120 | Homes/editors can write within grants; previews and server render handlers cannot. |
| 121 | `createTestWorkspace(app).client()` tests the interactive contract and |
| 122 | `grantedPermissions` simulates revoked consent. |
| 123 |
| 124 | New `tasks`, `calendar`, `messages`, and `references` capabilities require their |
| 125 | explicit manifest permissions and retain the invoking user's workspace access. |
| 126 | Use `files.list({ scope: "workspace" })` for shared files; document writes stay |
| 127 | with the owning app. Collections are install-private. A native mobile React runtime is separate |
| 128 | work; Coline Code builds and publishes apps (see `docs/sdk/full-stack.md`). |
| 129 |
| 130 | ### Live collections and access |
| 131 |
| 132 | `createLiveCollection(coline, name, query)` exposes a bounded live query with |
| 133 | synchronous optimistic updates, queued version-checked writes, errors, and |
| 134 | reconnect recovery. Subscribe via `subscribe`, call `start`, read `getSnapshot`, |
| 135 | and finish with `dispose`. React authors use `useLiveCollection` from |
| 136 | `@colineapp/ui` instead. A view holds at most 200 records. |
| 137 |
| 138 | Collection envelopes include `version` and `access`. `insert` accepts |
| 139 | `{ access: { workspace: "none" | "read" | "write", readers: [], writers: [] } }`; |
| 140 | the default is workspace read/write. Only the creator can `setAccess`. Use |
| 141 | `update(id, patch, { expectedVersion })` to reject stale writes. The same options |
| 142 | apply to delete/setAccess. Missing or inaccessible get returns null. Permissions |
| 143 | are filtered before pagination and also apply to reference resolution. |
| 144 |
| 145 | `sync(query, revision?)` returns a durable revision with an authorized snapshot; |
| 146 | `records: null` means unchanged. Live views use WebSocket invalidations and a |
| 147 | two-second fallback poll. They are structured-data views, not offline replicas |
| 148 | or character-level collaborative editors. Mutation errors must be caught; a |
| 149 | network error alone does not establish whether the server committed the write. |
| 150 |
| 151 | ### Coline AI jobs |
| 152 |
| 153 | Coline provides the AI models and credentials. Discover configured models with |
| 154 | `await coline.ai.models()`. Start text/structured output, embedding, speech, |
| 155 | transcription, reranking or video work with `coline.ai.run({ kind, input })`. |
| 156 | Images use `coline.ai.images.generate(input)`, including references, masks and |
| 157 | partial previews on supported models. Every job needs `model`, `idempotencyKey` |
| 158 | and `maxCostMicrousd`. Media outputs are normal Coline files. |
| 159 |
| 160 | ```ts |
| 161 | import { watchAiJob } from "@colineapp/sdk/v2"; |
| 162 |
| 163 | const model = (await coline.ai.models()).find((entry) => entry.kind === "language"); |
| 164 | if (!model) throw new Error("No language model is configured"); |
| 165 | const job = await coline.ai.run({ |
| 166 | kind: "language", |
| 167 | input: { |
| 168 | model: model.id, |
| 169 | prompt: "Write a short welcome message", |
| 170 | idempotencyKey: crypto.randomUUID(), |
| 171 | maxCostMicrousd: model.priceMicrousd, |
| 172 | }, |
| 173 | }); |
| 174 | for await (const update of watchAiJob(coline.ai, job.id)) { |
| 175 | if (update.type === "event") console.log(update.event); |
| 176 | else console.log(update.job.status, update.job.output); |
| 177 | } |
| 178 | ``` |
| 179 |
| 180 | Persist the job ID and last event sequence to reconnect. Aborting observation |
| 181 | leaves the job running; `ai.jobs.cancel(id)` cancels it. Request `ai.generate`, |
| 182 | plus `files.read`/`files.write` for media access and `ai.tools` for app tool loops. |
| 183 | Use `files.readUrl(fileId)` to obtain a fresh signed URL for an output file. |
| 184 | The existing `ai.generate(prompt, options)` remains available. |
| 185 |
| 186 | See `docs/sdk/ai.md` in the Coline repository for all request families, provider |
| 187 | configuration, limits, billing and test fixtures. Models and their capabilities |
| 188 | are server-configured; not every provider supports every operation. |
| 189 |
| 190 | Collection `orderBy` should name a scalar field. Numbers sort numerically, so |
| 191 | priority 2 precedes 10 in ascending order. In a mixed field, numbers precede |
| 192 | other scalar values; remaining values use case-sensitive text order, with null |
| 193 | and missing values treated as empty text. Descending reverses that order; record |
| 194 | IDs break ties. The server, test workspace, and optimistic live view agree. |
| 195 |
| 196 | Live views clear cached rows and reject pending edits for both raw SDK denials |
| 197 | and HTTP-prefixed authorization denials. A transport with no subscription |
| 198 | support still starts the bounded polling fallback. |
| 199 |
| 200 | ## Full-stack apps |
| 201 |
| 202 | Events (`triggers.webhooks` + `handlers.onEvent`, `coline.events.emit`), |
| 203 | inbound endpoints (`defineEndpoint`, verified for Stripe, GitHub, Slack, |
| 204 | Shopify, Linear, HMAC, or a shared token), durable background jobs |
| 205 | (`defineJob`, `coline.jobs.*`, `continueWith`, checkpoints, progress), OAuth |
| 206 | connections held by Coline (`connections`, `{{connection:KEY}}` in |
| 207 | `net.fetch`), developer secrets, collection `count`/`aggregate`/`batch`, |
| 208 | uploads up to 5 GB, `files.preview`/`saveAs`/`move`, and new tree nodes (`list`, `toolbar`, `searchInput`, |
| 209 | `filter`, `chart`, `confirm`, `stat`, `keyValue`). `createColineAppHandler` |
| 210 | rejects replayed deliveries; pass `seenDelivery` to share that across |
| 211 | instances. See `docs/sdk/full-stack.md` in the Coline repository. |
| 212 |
| 213 | ## Coline Sites |
| 214 |
| 215 | `surfaces.site` serves an app as a website on its own address, |
| 216 | `{name}.coline.space` or a custom domain, deployable without an account. |
| 217 |
| 218 | - `collections` declares what visitors may do with each collection |
| 219 | (`public`, `visitor`, `signedIn`, `owner`, `team`) and an optional zod |
| 220 | `schema` enforced on every visitor write. An undeclared collection is |
| 221 | invisible to visitors. |
| 222 | - `surfaces.site.visitors` turns on sign-in with Google or Coline and sets |
| 223 | who may use the site: `open`, `signedIn` or `approved`. |
| 224 | - Site tools run as the app, at most at `write`; records they create belong |
| 225 | to the visitor. `uploads` accepts files, `endpoints` serves app endpoints |
| 226 | on the site's paths, `agentTools` offers tools to browser agents. |
| 227 | - The page uses `@colineapp/sdk/site/react`: `createSiteHooks<typeof app>()` |
| 228 | returns `useCollection`, `usePaginatedCollection` and `useTool` typed from |
| 229 | the app, plus `useSession`, `SignInButton`, `useUpload` and a router. |
| 230 | Without React, `@colineapp/sdk/site` has `createSiteClient`, `site`, |
| 231 | `liveCollection`, `getSession`, `signIn` and `signOut`. |
| 232 | - Test the rules in memory with `createTestWorkspace(app).asVisitor()` and |
| 233 | `invokeSiteTool`. |
| 234 |
| 235 | Start with `npx create-coline-app my-site --template site`. Guide: |
| 236 | [docs.coline.app/sites](https://docs.coline.app/sites). |
| 237 |