529 lines · 15 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 |
| 5 | function createJsonResponse(payload: unknown, status = 200): Response { |
| 6 | return new Response(JSON.stringify(payload), { |
| 7 | status, |
| 8 | headers: { "Content-Type": "application/json" }, |
| 9 | }); |
| 10 | } |
| 11 |
| 12 | describe("ColineApiClient", () => { |
| 13 | it("registers apps and creates new versions through the v1 app publisher routes", async () => { |
| 14 | const fetchMock = vi |
| 15 | .fn() |
| 16 | .mockResolvedValueOnce( |
| 17 | createJsonResponse({ |
| 18 | data: { |
| 19 | appId: "app_123", |
| 20 | appKey: "com.coline.notes", |
| 21 | versionId: "ver_123", |
| 22 | version: "0.1.0", |
| 23 | }, |
| 24 | }), |
| 25 | ) |
| 26 | .mockResolvedValueOnce( |
| 27 | createJsonResponse({ |
| 28 | data: { |
| 29 | appId: "app_123", |
| 30 | appKey: "com.coline.notes", |
| 31 | versionId: "ver_124", |
| 32 | version: "0.1.1", |
| 33 | }, |
| 34 | }), |
| 35 | ); |
| 36 |
| 37 | const client = new ColineApiClient({ |
| 38 | baseUrl: "https://api.coline.app", |
| 39 | apiKey: "test-key", |
| 40 | fetch: fetchMock, |
| 41 | }); |
| 42 |
| 43 | await client.registerApp({ |
| 44 | version: "0.1.0", |
| 45 | manifest: { |
| 46 | key: "com.coline.notes", |
| 47 | name: "Notes", |
| 48 | permissions: ["app.home.read"], |
| 49 | notificationChannels: [], |
| 50 | hosting: { |
| 51 | mode: "external", |
| 52 | baseUrl: "https://notes.example.com", |
| 53 | }, |
| 54 | }, |
| 55 | fileTypes: [], |
| 56 | }); |
| 57 |
| 58 | await client.createAppVersion("com.coline.notes", { |
| 59 | version: "0.1.1", |
| 60 | manifest: { |
| 61 | key: "com.coline.notes", |
| 62 | name: "Notes", |
| 63 | permissions: ["app.home.read"], |
| 64 | notificationChannels: [], |
| 65 | hosting: { |
| 66 | mode: "external", |
| 67 | baseUrl: "https://notes.example.com", |
| 68 | }, |
| 69 | }, |
| 70 | fileTypes: [], |
| 71 | }); |
| 72 |
| 73 | expect(fetchMock).toHaveBeenNthCalledWith( |
| 74 | 1, |
| 75 | "https://api.coline.app/api/v1/apps", |
| 76 | expect.objectContaining({ |
| 77 | method: "POST", |
| 78 | headers: expect.any(Headers), |
| 79 | }), |
| 80 | ); |
| 81 |
| 82 | expect(fetchMock).toHaveBeenNthCalledWith( |
| 83 | 2, |
| 84 | "https://api.coline.app/api/v1/apps/com.coline.notes/versions", |
| 85 | expect.objectContaining({ |
| 86 | method: "POST", |
| 87 | headers: expect.any(Headers), |
| 88 | }), |
| 89 | ); |
| 90 | }); |
| 91 |
| 92 | it("installs a workspace app with explicit granted permissions", async () => { |
| 93 | const fetchMock = vi.fn().mockResolvedValue( |
| 94 | createJsonResponse({ |
| 95 | data: { |
| 96 | installId: "install_123", |
| 97 | appId: "app_123", |
| 98 | appKey: "com.coline.notes", |
| 99 | version: "0.1.0", |
| 100 | grantedPermissions: ["app.home.read"], |
| 101 | }, |
| 102 | }), |
| 103 | ); |
| 104 |
| 105 | const client = new ColineApiClient({ |
| 106 | baseUrl: "https://api.coline.app", |
| 107 | apiKey: "test-key", |
| 108 | fetch: fetchMock, |
| 109 | }); |
| 110 |
| 111 | const result = await client.installWorkspaceApp("acme", { |
| 112 | appId: "app_123", |
| 113 | grantedPermissions: ["app.home.read"], |
| 114 | }); |
| 115 |
| 116 | expect(result.installId).toBe("install_123"); |
| 117 | expect(fetchMock).toHaveBeenCalledWith( |
| 118 | "https://api.coline.app/api/v1/workspaces/acme/apps", |
| 119 | expect.objectContaining({ |
| 120 | method: "POST", |
| 121 | headers: expect.any(Headers), |
| 122 | }), |
| 123 | ); |
| 124 |
| 125 | const headers = fetchMock.mock.calls[0]?.[1]?.headers as Headers; |
| 126 | expect(headers.get("Authorization")).toBe("Bearer test-key"); |
| 127 | }); |
| 128 |
| 129 | it("loads and updates workspace app permissions", async () => { |
| 130 | const fetchMock = vi |
| 131 | .fn() |
| 132 | .mockResolvedValueOnce( |
| 133 | createJsonResponse({ |
| 134 | data: { |
| 135 | install: { |
| 136 | installId: "install_123", |
| 137 | appId: "app_123", |
| 138 | appKey: "com.coline.notes", |
| 139 | name: "Notes", |
| 140 | description: null, |
| 141 | iconUrl: null, |
| 142 | status: "active", |
| 143 | installScope: "workspace", |
| 144 | scopeSubjectId: "workspace_123", |
| 145 | version: "0.1.0", |
| 146 | }, |
| 147 | availablePermissions: ["app.home.read", "files.write"], |
| 148 | grantedPermissions: ["app.home.read"], |
| 149 | permissions: { |
| 150 | canManageApps: true, |
| 151 | }, |
| 152 | }, |
| 153 | }), |
| 154 | ) |
| 155 | .mockResolvedValueOnce( |
| 156 | createJsonResponse({ |
| 157 | data: { |
| 158 | install: { |
| 159 | installId: "install_123", |
| 160 | appId: "app_123", |
| 161 | appKey: "com.coline.notes", |
| 162 | name: "Notes", |
| 163 | description: null, |
| 164 | iconUrl: null, |
| 165 | status: "active", |
| 166 | installScope: "workspace", |
| 167 | scopeSubjectId: "workspace_123", |
| 168 | version: "0.1.0", |
| 169 | }, |
| 170 | availablePermissions: ["app.home.read", "files.write"], |
| 171 | grantedPermissions: ["app.home.read", "files.write"], |
| 172 | permissions: { |
| 173 | canManageApps: true, |
| 174 | }, |
| 175 | }, |
| 176 | }), |
| 177 | ); |
| 178 |
| 179 | const client = new ColineApiClient({ |
| 180 | baseUrl: "https://api.coline.app", |
| 181 | fetch: fetchMock, |
| 182 | }); |
| 183 |
| 184 | const currentPermissions = await client.getWorkspaceAppPermissions( |
| 185 | "acme", |
| 186 | "com.coline.notes", |
| 187 | ); |
| 188 | expect(currentPermissions.grantedPermissions).toEqual(["app.home.read"]); |
| 189 |
| 190 | const updatedPermissions = await client.updateWorkspaceAppPermissions( |
| 191 | "acme", |
| 192 | "com.coline.notes", |
| 193 | { |
| 194 | grantedPermissions: ["app.home.read", "files.write"], |
| 195 | }, |
| 196 | ); |
| 197 |
| 198 | expect(updatedPermissions.grantedPermissions).toEqual([ |
| 199 | "app.home.read", |
| 200 | "files.write", |
| 201 | ]); |
| 202 | }); |
| 203 |
| 204 | it("loads app detail, app versions, installed app, and uninstalls it", async () => { |
| 205 | const fetchMock = vi |
| 206 | .fn() |
| 207 | .mockResolvedValueOnce( |
| 208 | createJsonResponse({ |
| 209 | data: { |
| 210 | app: { |
| 211 | appId: "app_123", |
| 212 | appKey: "com.coline.notes", |
| 213 | name: "Notes", |
| 214 | description: null, |
| 215 | iconUrl: null, |
| 216 | status: "active", |
| 217 | ownerUserId: "user_123", |
| 218 | latestPublishedVersion: "0.1.0", |
| 219 | latestPublishedVersionId: "ver_123", |
| 220 | }, |
| 221 | }, |
| 222 | }), |
| 223 | ) |
| 224 | .mockResolvedValueOnce( |
| 225 | createJsonResponse({ |
| 226 | data: { |
| 227 | versions: [ |
| 228 | { |
| 229 | versionId: "ver_123", |
| 230 | version: "0.1.0", |
| 231 | status: "published", |
| 232 | apiBaseUrl: "https://notes.example.com", |
| 233 | permissions: ["app.home.read"], |
| 234 | kairo: { |
| 235 | enabled: true, |
| 236 | description: "Notes documents can be searched by Kairo.", |
| 237 | instructions: "Search notes before answering document questions.", |
| 238 | documentTypes: [ |
| 239 | { |
| 240 | documentType: "note", |
| 241 | name: "Note", |
| 242 | metadata: [], |
| 243 | }, |
| 244 | ], |
| 245 | }, |
| 246 | fileTypes: [], |
| 247 | createdAt: "2026-04-01T00:00:00.000Z", |
| 248 | updatedAt: "2026-04-01T00:00:00.000Z", |
| 249 | }, |
| 250 | ], |
| 251 | }, |
| 252 | }), |
| 253 | ) |
| 254 | .mockResolvedValueOnce( |
| 255 | createJsonResponse({ |
| 256 | data: { |
| 257 | install: { |
| 258 | installId: "install_123", |
| 259 | appId: "app_123", |
| 260 | appKey: "com.coline.notes", |
| 261 | name: "Notes", |
| 262 | description: null, |
| 263 | iconUrl: null, |
| 264 | status: "active", |
| 265 | installScope: "workspace", |
| 266 | scopeSubjectId: "workspace_123", |
| 267 | version: "0.1.0", |
| 268 | }, |
| 269 | permissions: { |
| 270 | canManageApps: true, |
| 271 | }, |
| 272 | }, |
| 273 | }), |
| 274 | ) |
| 275 | .mockResolvedValueOnce(createJsonResponse({ data: { ok: true } })); |
| 276 |
| 277 | const client = new ColineApiClient({ |
| 278 | baseUrl: "https://api.coline.app", |
| 279 | fetch: fetchMock, |
| 280 | }); |
| 281 |
| 282 | const app = await client.getApp("com.coline.notes"); |
| 283 | expect(app.app.appKey).toBe("com.coline.notes"); |
| 284 |
| 285 | const versions = await client.listAppVersions("com.coline.notes"); |
| 286 | expect(versions.versions[0]?.version).toBe("0.1.0"); |
| 287 | expect(versions.versions[0]?.kairo?.documentTypes[0]?.documentType).toBe("note"); |
| 288 |
| 289 | const installed = await client.getWorkspaceInstalledApp("acme", "com.coline.notes"); |
| 290 | expect(installed.install.installId).toBe("install_123"); |
| 291 |
| 292 | const uninstallResult = await client.uninstallWorkspaceApp( |
| 293 | "acme", |
| 294 | "com.coline.notes", |
| 295 | ); |
| 296 | expect(uninstallResult.ok).toBe(true); |
| 297 | }); |
| 298 |
| 299 | it("loads and updates app file documents through the public runtime API", async () => { |
| 300 | const fetchMock = vi |
| 301 | .fn() |
| 302 | .mockResolvedValueOnce( |
| 303 | createJsonResponse({ |
| 304 | data: { |
| 305 | file: { |
| 306 | id: "file_123", |
| 307 | name: "Customer", |
| 308 | fileType: "com.acme.customer", |
| 309 | appKey: "acme-crm", |
| 310 | appName: "Acme CRM", |
| 311 | typeLabel: "Customer", |
| 312 | openHref: "/acme/acme-crm/files/file_123", |
| 313 | updatedAt: "2026-03-18T08:00:00.000Z", |
| 314 | }, |
| 315 | document: { status: "active" }, |
| 316 | version: 2, |
| 317 | capabilities: { |
| 318 | canRead: true, |
| 319 | canWrite: true, |
| 320 | canManage: false, |
| 321 | }, |
| 322 | }, |
| 323 | }), |
| 324 | ) |
| 325 | .mockResolvedValueOnce( |
| 326 | createJsonResponse({ |
| 327 | data: { |
| 328 | document: { status: "archived" }, |
| 329 | version: 3, |
| 330 | updatedAt: "2026-03-18T09:00:00.000Z", |
| 331 | }, |
| 332 | }), |
| 333 | ); |
| 334 |
| 335 | const client = new ColineApiClient({ |
| 336 | baseUrl: "https://api.coline.app", |
| 337 | fetch: fetchMock, |
| 338 | }); |
| 339 |
| 340 | const file = await client.getAppFileDocument("acme", "acme-crm", "file_123"); |
| 341 | expect(file.file.id).toBe("file_123"); |
| 342 | expect(file.version).toBe(2); |
| 343 |
| 344 | const updated = await client.updateAppFileDocument( |
| 345 | "acme", |
| 346 | "acme-crm", |
| 347 | "file_123", |
| 348 | { status: "archived" }, |
| 349 | ); |
| 350 | expect(updated.version).toBe(3); |
| 351 | }); |
| 352 |
| 353 | it("lists Tab models and creates OpenAI-compatible Tab completions", async () => { |
| 354 | const fetchMock = vi |
| 355 | .fn() |
| 356 | .mockResolvedValueOnce( |
| 357 | createJsonResponse({ |
| 358 | data: { |
| 359 | object: "list", |
| 360 | data: [ |
| 361 | { |
| 362 | id: "tab-v1", |
| 363 | object: "model", |
| 364 | created: 1775200000, |
| 365 | owned_by: "coline", |
| 366 | providerModelId: "gemini-2.5-flash-lite", |
| 367 | pricing: { |
| 368 | inputPerMillionUsd: 0.2, |
| 369 | outputPerMillionUsd: 0.5, |
| 370 | }, |
| 371 | capabilities: { |
| 372 | streaming: true, |
| 373 | surfaces: ["notes", "docs"], |
| 374 | }, |
| 375 | }, |
| 376 | ], |
| 377 | }, |
| 378 | }), |
| 379 | ) |
| 380 | .mockResolvedValueOnce( |
| 381 | createJsonResponse({ |
| 382 | data: { |
| 383 | id: "chatcmpl_123", |
| 384 | object: "chat.completion", |
| 385 | created: 1775200001, |
| 386 | model: "tab-v1", |
| 387 | choices: [ |
| 388 | { |
| 389 | index: 0, |
| 390 | message: { |
| 391 | role: "assistant", |
| 392 | content: " world", |
| 393 | }, |
| 394 | finish_reason: "stop", |
| 395 | }, |
| 396 | ], |
| 397 | usage: { |
| 398 | prompt_tokens: 10, |
| 399 | completion_tokens: 2, |
| 400 | total_tokens: 12, |
| 401 | }, |
| 402 | }, |
| 403 | }), |
| 404 | ); |
| 405 |
| 406 | const client = new ColineApiClient({ |
| 407 | baseUrl: "https://api.coline.app", |
| 408 | fetch: fetchMock, |
| 409 | }); |
| 410 |
| 411 | const models = await client.listTabModels(); |
| 412 | expect(models.data[0]?.id).toBe("tab-v1"); |
| 413 |
| 414 | const completion = await client.createTabChatCompletion({ |
| 415 | model: "tab-v1", |
| 416 | tab_context: { |
| 417 | surface: "notes", |
| 418 | workspace_slug: "acme", |
| 419 | entity_id: "note_123", |
| 420 | document_type: "markdown", |
| 421 | active_text_before_cursor: "Hello", |
| 422 | active_text_after_cursor: "", |
| 423 | surrounding_context: "Title: Roadmap", |
| 424 | }, |
| 425 | }); |
| 426 |
| 427 | expect(completion.choices[0]?.message.content).toBe(" world"); |
| 428 | }); |
| 429 |
| 430 | it("builds Login with Coline authorize URLs and exchanges OAuth tokens", async () => { |
| 431 | const fetchMock = vi |
| 432 | .fn() |
| 433 | .mockResolvedValueOnce( |
| 434 | createJsonResponse({ |
| 435 | access_token: "col_at_123", |
| 436 | token_type: "Bearer", |
| 437 | expires_in: 3600, |
| 438 | refresh_token: "col_rt_123", |
| 439 | scope: "openid profile email", |
| 440 | }), |
| 441 | ) |
| 442 | .mockResolvedValueOnce( |
| 443 | createJsonResponse({ |
| 444 | sub: "user_123", |
| 445 | email: "radin@example.com", |
| 446 | email_verified: true, |
| 447 | name: "Radin", |
| 448 | given_name: "Radin", |
| 449 | family_name: null, |
| 450 | picture: null, |
| 451 | preferred_username: "radin", |
| 452 | scope: "openid profile email", |
| 453 | }), |
| 454 | ); |
| 455 |
| 456 | const client = new ColineApiClient({ |
| 457 | baseUrl: "https://api.coline.app", |
| 458 | fetch: fetchMock, |
| 459 | }); |
| 460 |
| 461 | const authorizeUrl = client.buildLoginWithColineAuthorizeUrl({ |
| 462 | clientId: "col_client_123", |
| 463 | redirectUri: "https://example.com/callback", |
| 464 | scope: "openid profile email", |
| 465 | state: "state_123", |
| 466 | }); |
| 467 | expect(authorizeUrl).toContain("/api/v1/oauth/authorize"); |
| 468 | expect(authorizeUrl).toContain("client_id=col_client_123"); |
| 469 |
| 470 | const token = await client.exchangeOAuthCode({ |
| 471 | clientId: "col_client_123", |
| 472 | clientSecret: "col_secret_123", |
| 473 | code: "col_code_123", |
| 474 | redirectUri: "https://example.com/callback", |
| 475 | }); |
| 476 | expect(token.access_token).toBe("col_at_123"); |
| 477 |
| 478 | const userInfo = await client.getOAuthUserInfo("col_at_123"); |
| 479 | expect(userInfo.sub).toBe("user_123"); |
| 480 | }); |
| 481 |
| 482 | it("supports client cloning with headers and api keys", async () => { |
| 483 | const fetchMock = vi.fn().mockResolvedValue( |
| 484 | createJsonResponse({ |
| 485 | data: { |
| 486 | apps: [], |
| 487 | }, |
| 488 | }), |
| 489 | ); |
| 490 |
| 491 | const baseClient = new ColineApiClient({ |
| 492 | baseUrl: "https://api.coline.app", |
| 493 | fetch: fetchMock, |
| 494 | headers: { |
| 495 | "X-Test": "base", |
| 496 | }, |
| 497 | }); |
| 498 |
| 499 | const client = baseClient.withApiKey("test-key").withHeaders({ |
| 500 | "X-Request-Source": "sdk-test", |
| 501 | }); |
| 502 |
| 503 | await client.listApps(); |
| 504 |
| 505 | const headers = fetchMock.mock.calls[0]?.[1]?.headers as Headers; |
| 506 | expect(headers.get("Authorization")).toBe("Bearer test-key"); |
| 507 | expect(headers.get("X-Test")).toBe("base"); |
| 508 | expect(headers.get("X-Request-Source")).toBe("sdk-test"); |
| 509 | }); |
| 510 |
| 511 | it("throws structured api errors", async () => { |
| 512 | const fetchMock = vi.fn().mockResolvedValue( |
| 513 | createJsonResponse({ |
| 514 | error: { |
| 515 | code: "FORBIDDEN", |
| 516 | message: "No access.", |
| 517 | }, |
| 518 | }, 403), |
| 519 | ); |
| 520 |
| 521 | const client = new ColineApiClient({ |
| 522 | baseUrl: "https://api.coline.app", |
| 523 | fetch: fetchMock, |
| 524 | }); |
| 525 |
| 526 | await expect(client.listApps()).rejects.toBeInstanceOf(ColineApiError); |
| 527 | }); |
| 528 | }); |
| 529 |