194 lines · 7 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.
| 4 | import { ui } from "../tree/tree"; |
| 5 | import { createTestWorkspace } from "./test-workspace"; |
| 6 |
| 7 | const createContact = defineTool({ |
| 8 | name: "crm.create_contact", |
| 9 | description: "Create a contact.", |
| 10 | input: z.object({ name: z.string(), email: z.string().optional() }), |
| 11 | effect: "write", |
| 12 | execute: async (input, context) => { |
| 13 | const file = await context.coline.files.create({ |
| 14 | typeKey: "crm.contact", |
| 15 | name: input.name, |
| 16 | document: { name: input.name, email: input.email ?? null }, |
| 17 | }); |
| 18 | await context.coline.search.index.upsert({ |
| 19 | documents: [ |
| 20 | { |
| 21 | documentKey: `contact:${file.fileId}`, |
| 22 | documentType: "contact", |
| 23 | fileId: file.fileId, |
| 24 | title: input.name, |
| 25 | body: input.email ?? "", |
| 26 | }, |
| 27 | ], |
| 28 | }); |
| 29 | return { |
| 30 | output: { fileId: file.fileId }, |
| 31 | card: ui.stack([ui.reference({ kind: "file", id: file.fileId })]), |
| 32 | }; |
| 33 | }, |
| 34 | }); |
| 35 |
| 36 | const app = defineApp({ |
| 37 | key: "crm", |
| 38 | name: "CRM", |
| 39 | permissions: ["files.read", "files.write", "storage.app", "ai.tools", "search.index"], |
| 40 | surfaces: { home: { tier: "tree" } }, |
| 41 | files: [ |
| 42 | defineFileType({ |
| 43 | metadata: { |
| 44 | typeKey: "crm.contact", |
| 45 | name: "Contact", |
| 46 | indexable: false, |
| 47 | surfaces: { preview: { tier: "tree" }, inline: { tier: "tree" } }, |
| 48 | }, |
| 49 | runtime: { |
| 50 | renderPreview: (context) => ui.heading(String(context.document.name ?? "Contact")), |
| 51 | renderInline: (context) => ui.text(String(context.document.name ?? "Contact")), |
| 52 | }, |
| 53 | }), |
| 54 | ], |
| 55 | tools: [createContact], |
| 56 | triggers: { schedules: [{ id: "digest", cron: "0 9 * * 1-5" }] }, |
| 57 | handlers: { |
| 58 | renderHome: async (context) => { |
| 59 | const { files } = await context.coline.files.list({ typeKey: "crm.contact" }); |
| 60 | return ui.stack([ui.heading("CRM"), ui.text(`${files.length} contacts`)]); |
| 61 | }, |
| 62 | onSchedule: async (context) => { |
| 63 | await context.coline.storage.kv.set("last-digest", context.firedAt); |
| 64 | }, |
| 65 | }, |
| 66 | }); |
| 67 |
| 68 | describe("createTestWorkspace", () => { |
| 69 | it("invokes tools through the schema and captures state", async () => { |
| 70 | const workspace = createTestWorkspace(app); |
| 71 | const result = await workspace.invokeTool("crm.create_contact", { name: "Sarah" }); |
| 72 | expect(result.output).toMatchObject({ fileId: expect.stringContaining("file_test") }); |
| 73 | expect(result.card?.type).toBe("Stack"); |
| 74 | expect(workspace.files.byType("crm.contact")).toHaveLength(1); |
| 75 | expect(workspace.state.indexDocuments.size).toBe(1); |
| 76 | }); |
| 77 |
| 78 | it("rejects invalid tool input with schema detail", async () => { |
| 79 | const workspace = createTestWorkspace(app); |
| 80 | await expect(workspace.invokeTool("crm.create_contact", { name: 42 })).rejects.toThrow( |
| 81 | /invalid/i, |
| 82 | ); |
| 83 | }); |
| 84 |
| 85 | it("renders home against live fake state", async () => { |
| 86 | const workspace = createTestWorkspace(app); |
| 87 | await workspace.invokeTool("crm.create_contact", { name: "A" }); |
| 88 | await workspace.invokeTool("crm.create_contact", { name: "B" }); |
| 89 | const tree = await workspace.renderHome(); |
| 90 | expect(JSON.stringify(tree)).toContain("2 contacts"); |
| 91 | }); |
| 92 |
| 93 | it("renders file surfaces and enforces the inline subset", async () => { |
| 94 | const workspace = createTestWorkspace(app); |
| 95 | const preview = await workspace.renderFileSurface( |
| 96 | "preview", |
| 97 | { fileId: "f1", name: "Sarah", typeKey: "crm.contact" }, |
| 98 | { name: "Sarah Chen" }, |
| 99 | ); |
| 100 | expect(JSON.stringify(preview)).toContain("Sarah Chen"); |
| 101 | }); |
| 102 |
| 103 | it("fires declared schedules with the schedule context", async () => { |
| 104 | const workspace = createTestWorkspace(app); |
| 105 | const at = new Date("2026-08-10T09:00:00Z"); |
| 106 | await workspace.fireSchedule("digest", at); |
| 107 | expect(workspace.state.kv.get("last-digest")).toBe(at.toISOString()); |
| 108 | }); |
| 109 |
| 110 | it("rejects undeclared schedules", async () => { |
| 111 | const workspace = createTestWorkspace(app); |
| 112 | await expect(workspace.fireSchedule("nope")).rejects.toThrow(/not declared/); |
| 113 | }); |
| 114 | }); |
| 115 |
| 116 | describe("runtime parity", () => { |
| 117 | it("allows interactive home writes but rejects preview writes", async () => { |
| 118 | const ws = createTestWorkspace(app); |
| 119 | await ws.client().files.create({ typeKey: "crm.contact", name: "Allowed" }); |
| 120 | await expect( |
| 121 | ws.client("preview").files.create({ typeKey: "crm.contact", name: "Denied" }), |
| 122 | ).rejects.toMatchObject({ code: "effect_ceiling_exceeded" }); |
| 123 | }); |
| 124 | it("enforces revoked grants in tools and clients", async () => { |
| 125 | const ws = createTestWorkspace(app, { grantedPermissions: ["files.read"] }); |
| 126 | await expect(ws.invokeTool("crm.create_contact", { name: "Denied" })).rejects.toMatchObject({ |
| 127 | code: "permission_not_granted", |
| 128 | }); |
| 129 | expect(ws.files.all()).toHaveLength(0); |
| 130 | }); |
| 131 | it("filters, sorts and pages records without exposing mutable stored objects", async () => { |
| 132 | const ws = createTestWorkspace(app); |
| 133 | const records = ws.client().storage.collection<{ name: string; score: number }>("contacts"); |
| 134 | await records.insert({ name: "Alice", score: 2 }); |
| 135 | await records.insert({ name: "Alex", score: 3 }); |
| 136 | await records.insert({ name: "Bob", score: 4 }); |
| 137 | const first = await records.query({ |
| 138 | where: { name: { contains: "al" }, score: { gte: 2 } }, |
| 139 | orderBy: "name", |
| 140 | order: "asc", |
| 141 | limit: 1, |
| 142 | }); |
| 143 | expect(first.records[0]?.data.name).toBe("Alex"); |
| 144 | const second = await records.query({ |
| 145 | where: { name: { contains: "al" } }, |
| 146 | orderBy: "name", |
| 147 | order: "asc", |
| 148 | limit: 1, |
| 149 | cursor: first.nextCursor!, |
| 150 | }); |
| 151 | expect(second.records[0]?.data.name).toBe("Alice"); |
| 152 | first.records[0]!.data.name = "Changed outside capability"; |
| 153 | expect((await records.get(first.records[0]!.id))?.data.name).toBe("Alex"); |
| 154 | }); |
| 155 | it("enforces read-only rendering", async () => { |
| 156 | const bad = defineApp({ |
| 157 | key: "bad", |
| 158 | name: "Bad", |
| 159 | permissions: ["storage.app"], |
| 160 | surfaces: { home: { tier: "tree" } }, |
| 161 | handlers: { |
| 162 | renderHome: async ({ coline }) => { |
| 163 | await coline.storage.kv.set("bad", true); |
| 164 | return ui.text("bad"); |
| 165 | }, |
| 166 | }, |
| 167 | }); |
| 168 | await expect(createTestWorkspace(bad).renderHome()).rejects.toMatchObject({ |
| 169 | code: "effect_ceiling_exceeded", |
| 170 | }); |
| 171 | }); |
| 172 | }); |
| 173 |
| 174 | describe("interactive tools", () => { |
| 175 | it("invokes declared tools from a client and preserves preview ceilings", async () => { |
| 176 | const ws = createTestWorkspace(app); |
| 177 | await ws.client().tools.invoke("crm.create_contact", { name: "Client" }); |
| 178 | expect(ws.files.all()).toHaveLength(1); |
| 179 | await expect( |
| 180 | ws.client("preview").tools.invoke("crm.create_contact", { name: "Denied" }), |
| 181 | ).rejects.toMatchObject({ code: "effect_ceiling_exceeded" }); |
| 182 | expect(ws.files.all()).toHaveLength(1); |
| 183 | }); |
| 184 | it("blocks interactive invocation when the tool grant is revoked", async () => { |
| 185 | const ws = createTestWorkspace(app, { |
| 186 | grantedPermissions: ["files.read", "files.write", "storage.app", "search.index"], |
| 187 | }); |
| 188 | await expect( |
| 189 | ws.client().tools.invoke("crm.create_contact", { name: "Denied" }), |
| 190 | ).rejects.toMatchObject({ code: "permission_not_granted" }); |
| 191 | expect(ws.files.all()).toHaveLength(0); |
| 192 | }); |
| 193 | }); |
| 194 |