236 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 { createColineAppHandler } from "./app-server"; |
| 6 | import { |
| 7 | buildSignedProtocolRequest, |
| 8 | type ColineProtocolEnvelope, |
| 9 | } from "./protocol"; |
| 10 | import { RENDER_SURFACE_KIND, type RenderSurfacePayload } from "./render-surface"; |
| 11 | import { TOOL_INVOKE_KIND, type ToolInvokePayload } from "./tool-invoke"; |
| 12 |
| 13 | const SECRET = "delivery-secret-of-sufficient-length"; |
| 14 |
| 15 | const createContact = defineTool({ |
| 16 | name: "crm.create_contact", |
| 17 | description: "Create a contact.", |
| 18 | input: z.object({ name: z.string() }), |
| 19 | effect: "write", |
| 20 | execute: async (input, context) => { |
| 21 | const file = await context.coline.files.create({ |
| 22 | typeKey: "crm.contact", |
| 23 | name: input.name, |
| 24 | }); |
| 25 | return { |
| 26 | output: { fileId: file.fileId }, |
| 27 | card: ui.stack([ui.text(`Created ${input.name}`)]), |
| 28 | }; |
| 29 | }, |
| 30 | }); |
| 31 |
| 32 | const badCardTool = defineTool({ |
| 33 | name: "crm.bad_card", |
| 34 | description: "Returns a disallowed card.", |
| 35 | input: z.object({}), |
| 36 | effect: "read", |
| 37 | execute: () => ({ |
| 38 | card: ui.input({ name: "nope" }), |
| 39 | }), |
| 40 | }); |
| 41 |
| 42 | const app = defineApp({ |
| 43 | key: "crm", |
| 44 | name: "CRM", |
| 45 | permissions: ["files.read", "files.write", "ai.tools"], |
| 46 | tools: [createContact, badCardTool], |
| 47 | files: [ |
| 48 | defineFileType({ |
| 49 | metadata: { |
| 50 | typeKey: "crm.contact", |
| 51 | name: "Contact", |
| 52 | indexable: false, |
| 53 | surfaces: { preview: { tier: "tree" }, inline: { tier: "tree" } }, |
| 54 | }, |
| 55 | runtime: { |
| 56 | renderPreview: (context) => |
| 57 | ui.stack([ui.heading(String(context.document.name ?? "Contact"), { level: 3 })]), |
| 58 | renderInline: (context) => ui.text(String(context.document.name ?? "Contact")), |
| 59 | }, |
| 60 | }), |
| 61 | ], |
| 62 | }); |
| 63 |
| 64 | function buildEnvelope(payload: ToolInvokePayload): ColineProtocolEnvelope { |
| 65 | return { |
| 66 | protocol: 2, |
| 67 | deliveryId: "dlv_0123456789", |
| 68 | sentAt: new Date().toISOString(), |
| 69 | workspace: { workspaceId: "ws_1", workspaceSlug: "acme" }, |
| 70 | app: { appKey: "crm", installId: "inst_1" }, |
| 71 | actor: { kind: "user", userId: "user_1" }, |
| 72 | kind: TOOL_INVOKE_KIND, |
| 73 | payload, |
| 74 | }; |
| 75 | } |
| 76 |
| 77 | async function send(envelope: ColineProtocolEnvelope, options?: { secret?: string }) { |
| 78 | const signed = await buildSignedProtocolRequest({ |
| 79 | secret: options?.secret ?? SECRET, |
| 80 | envelope, |
| 81 | }); |
| 82 | const handler = createColineAppHandler({ app, secret: SECRET }); |
| 83 | const response = await handler( |
| 84 | new Request("https://crm.example.com/coline/app", { |
| 85 | method: "POST", |
| 86 | headers: signed.headers, |
| 87 | body: signed.body, |
| 88 | }), |
| 89 | ); |
| 90 | return { status: response.status, body: (await response.json()) as Record<string, unknown> }; |
| 91 | } |
| 92 |
| 93 | async function invoke(payload: ToolInvokePayload, options?: { secret?: string }) { |
| 94 | return send(buildEnvelope(payload), options); |
| 95 | } |
| 96 |
| 97 | const capabilities = { url: "https://coline.test/api/v1/apps/capability", token: "tok_0123456789abcdef" }; |
| 98 |
| 99 | describe("createColineAppHandler", () => { |
| 100 | it("executes a tool with capability-backed context and returns output + card", async () => { |
| 101 | const originalFetch = globalThis.fetch; |
| 102 | globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => { |
| 103 | const body = JSON.parse(String(init?.body)) as { operation: string; args: unknown[] }; |
| 104 | expect(String(input)).toBe(capabilities.url); |
| 105 | expect(body.operation).toBe("files.create"); |
| 106 | expect((init?.headers as Record<string, string>).authorization).toBe( |
| 107 | `Bearer ${capabilities.token}`, |
| 108 | ); |
| 109 | return new Response( |
| 110 | JSON.stringify({ data: { fileId: "file_9", name: "Sarah", typeKey: "crm.contact" } }), |
| 111 | { headers: { "content-type": "application/json" } }, |
| 112 | ); |
| 113 | }) as typeof fetch; |
| 114 |
| 115 | try { |
| 116 | const { status, body } = await invoke({ |
| 117 | tool: "crm.create_contact", |
| 118 | input: { name: "Sarah" }, |
| 119 | capabilities, |
| 120 | }); |
| 121 | expect(status).toBe(200); |
| 122 | const result = body.result as { output: { fileId: string }; card: unknown }; |
| 123 | expect(result.output.fileId).toBe("file_9"); |
| 124 | expect(result.card).toBeDefined(); |
| 125 | } finally { |
| 126 | globalThis.fetch = originalFetch; |
| 127 | } |
| 128 | }); |
| 129 |
| 130 | it("rejects bad signatures", async () => { |
| 131 | const { status, body } = await invoke( |
| 132 | { tool: "crm.create_contact", input: { name: "Sarah" }, capabilities }, |
| 133 | { secret: "the-wrong-secret-of-sufficient-length" }, |
| 134 | ); |
| 135 | expect(status).toBe(401); |
| 136 | expect((body.error as { code: string }).code).toBe("invalid_signature"); |
| 137 | }); |
| 138 |
| 139 | it("rejects unknown tools", async () => { |
| 140 | const { status, body } = await invoke({ |
| 141 | tool: "crm.nonexistent", |
| 142 | input: {}, |
| 143 | capabilities, |
| 144 | }); |
| 145 | expect(status).toBe(404); |
| 146 | expect((body.error as { code: string }).code).toBe("unknown_tool"); |
| 147 | }); |
| 148 |
| 149 | it("rejects invalid input with issue detail", async () => { |
| 150 | const { status, body } = await invoke({ |
| 151 | tool: "crm.create_contact", |
| 152 | input: { name: 42 }, |
| 153 | capabilities, |
| 154 | }); |
| 155 | expect(status).toBe(400); |
| 156 | expect((body.error as { code: string }).code).toBe("invalid_input"); |
| 157 | }); |
| 158 |
| 159 | it("rejects cards outside the chat subset", async () => { |
| 160 | const { status, body } = await invoke({ |
| 161 | tool: "crm.bad_card", |
| 162 | input: {}, |
| 163 | capabilities, |
| 164 | }); |
| 165 | expect(status).toBe(400); |
| 166 | expect((body.error as { code: string }).code).toBe("invalid_card"); |
| 167 | }); |
| 168 | }); |
| 169 |
| 170 | describe("render.surface", () => { |
| 171 | function renderEnvelope(payload: RenderSurfacePayload): ColineProtocolEnvelope { |
| 172 | return { |
| 173 | protocol: 2, |
| 174 | deliveryId: "dlv_render_00001", |
| 175 | sentAt: new Date().toISOString(), |
| 176 | workspace: { workspaceId: "ws_1", workspaceSlug: "acme" }, |
| 177 | app: { appKey: "crm", installId: "inst_1" }, |
| 178 | actor: { kind: "user", userId: "user_1" }, |
| 179 | kind: RENDER_SURFACE_KIND, |
| 180 | payload, |
| 181 | }; |
| 182 | } |
| 183 |
| 184 | const file = { fileId: "file_1", name: "Sarah", typeKey: "crm.contact", version: 3 }; |
| 185 |
| 186 | it("renders a file preview surface", async () => { |
| 187 | const { status, body } = await send( |
| 188 | renderEnvelope({ |
| 189 | surface: "preview", |
| 190 | file, |
| 191 | document: { name: "Sarah Chen" }, |
| 192 | capabilities, |
| 193 | }), |
| 194 | ); |
| 195 | expect(status).toBe(200); |
| 196 | const tree = (body.result as { tree: { type: string } }).tree; |
| 197 | expect(tree.type).toBe("Stack"); |
| 198 | }); |
| 199 |
| 200 | it("renders an inline surface within the chat-card subset", async () => { |
| 201 | const { status, body } = await send( |
| 202 | renderEnvelope({ |
| 203 | surface: "inline", |
| 204 | file, |
| 205 | document: { name: "Sarah Chen" }, |
| 206 | capabilities, |
| 207 | }), |
| 208 | ); |
| 209 | expect(status).toBe(200); |
| 210 | expect((body.result as { tree: { type: string } }).tree.type).toBe("Text"); |
| 211 | }); |
| 212 |
| 213 | it("404s surfaces without handlers", async () => { |
| 214 | const { status, body } = await send( |
| 215 | renderEnvelope({ surface: "editor", file, capabilities }), |
| 216 | ); |
| 217 | expect(status).toBe(404); |
| 218 | expect((body.error as { code: string }).code).toBe("unknown_surface"); |
| 219 | }); |
| 220 |
| 221 | it("404s home when the app has no tree home", async () => { |
| 222 | const { status } = await send(renderEnvelope({ surface: "home", capabilities })); |
| 223 | expect(status).toBe(404); |
| 224 | }); |
| 225 |
| 226 | it("rejects unknown envelope kinds", async () => { |
| 227 | const envelope = { |
| 228 | ...renderEnvelope({ surface: "home", capabilities }), |
| 229 | kind: "something.else", |
| 230 | }; |
| 231 | const { status, body } = await send(envelope); |
| 232 | expect(status).toBe(400); |
| 233 | expect((body.error as { code: string }).code).toBe("unsupported_kind"); |
| 234 | }); |
| 235 | }); |
| 236 |