141 lines · 6 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 | Compile app-specific Tailwind utilities to CSS before importing them. |
| 107 |
| 108 | The starter includes a React home and editor, tree mobile fallback, and a tool. |
| 109 | Use `coline.tools.invoke` or `actions.invokeTool` to run the same declared tool |
| 110 | from UI that Kairo runs. Save with `expectedVersion` to detect concurrent edits. |
| 111 | Homes/editors can write within grants; previews and server render handlers cannot. |
| 112 | `createTestWorkspace(app).client()` tests the interactive contract and |
| 113 | `grantedPermissions` simulates revoked consent. |
| 114 |
| 115 | New `tasks`, `calendar`, `messages`, and `references` capabilities require their |
| 116 | explicit manifest permissions and retain the invoking user's workspace access. |
| 117 | Use `files.list({ scope: "workspace" })` for shared files; document writes stay |
| 118 | with the owning app. Collections are install-private. Code integration and a |
| 119 | native mobile React runtime are separate work. |
| 120 |
| 121 | ### Live collections and access |
| 122 |
| 123 | `createLiveCollection(coline, name, query)` exposes a bounded live query with |
| 124 | synchronous optimistic updates, queued version-checked writes, errors, and |
| 125 | reconnect recovery. Subscribe via `subscribe`, call `start`, read `getSnapshot`, |
| 126 | and finish with `dispose`. React authors use `useLiveCollection` from |
| 127 | `@colineapp/ui` instead. A view holds at most 200 records. |
| 128 |
| 129 | Collection envelopes include `version` and `access`. `insert` accepts |
| 130 | `{ access: { workspace: "none" | "read" | "write", readers: [], writers: [] } }`; |
| 131 | the default is workspace read/write. Only the creator can `setAccess`. Use |
| 132 | `update(id, patch, { expectedVersion })` to reject stale writes. The same options |
| 133 | apply to delete/setAccess. Missing or inaccessible get returns null. Permissions |
| 134 | are filtered before pagination and also apply to reference resolution. |
| 135 |
| 136 | `sync(query, revision?)` returns a durable revision with an authorized snapshot; |
| 137 | `records: null` means unchanged. Live views use WebSocket invalidations and a |
| 138 | two-second fallback poll. They are structured-data views, not offline replicas |
| 139 | or character-level collaborative editors. Mutation errors must be caught; a |
| 140 | network error alone does not establish whether the server committed the write. |
| 141 |