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