Routes Your App Exposes

createHandler() handles these automatically:

All POST routes are verified using your delivery secret.

API Client

For server-to-server calls (creating files, sending notifications, etc.):

import { ColineApiClient } from "@colineapp/sdk";

const client = new ColineApiClient({
  baseUrl: "https://coline.app",
  apiKey: process.env.COLINE_API_KEY!,
});

// Fluent scoped handles
const ws = client.workspace("acme");
const app = ws.app("com.acme.todos");

// Create a file
const { file } = await app.createFile({
  name: "Buy milk",
  typeKey: "todo",
  document: { status: "open" },
});

// Update it
await app.file(file.id).updateDocument({ status: "done" });

// Send a notification
await app.createNotification({
  channelKey: "updates",
  typeKey: "todo.completed",
  title: "Todo completed",
  body: "Buy milk is done!",
  recipients: [{ userId: "user_123" }],
});

Webhooks

Verify and handle webhook events with typed payloads:

import { webhooks } from "@colineapp/sdk";

// In your webhook handler:
const event = await webhooks.constructEvent(rawBody, request.headers, secret);

switch (event.type) {
  case "message.created":
    console.log(event.data.plaintext);
    break;
  case "task.created":
    console.log(event.data.title, event.data.priority);
    break;
}

Or use createHandler({ onWebhook }) for automatic verification.

UI Components

Build native Coline UI with the ui helper. Components render directly inside Coline's workspace — no iframe, no custom CSS.

Text & Typography

import { ui, actions } from "@colineapp/sdk";

ui.heading("Title", { level: 1 });       // h1–h4
ui.text("Body text");
ui.text("Error occurred", { tone: "danger" });
ui.badge("Active", { tone: "positive" }); // default, muted, positive, warning, danger
ui.link("Read more", "https://docs.example.com", { external: true });

Layout

ui.stack([child1, child2], { gap: "md" });         // vertical
ui.row([badge1, badge2], { gap: "sm" });            // horizontal
ui.divider();

Interactive

ui.button("Save", { action: actions.custom("my-app.save") });
ui.button("Open", { action: actions.openFile("file_123") });
ui.button("Create", {
  action: actions.createFile({ name: "New Todo", typeKey: "todo" }),
});

Form Inputs

ui.input({ name: "title", label: "Title", placeholder: "Enter a title…" });
ui.input({ name: "notes", label: "Notes", type: "textarea" });
ui.input({ name: "amount", label: "Amount", type: "number", required: true });
ui.select({
  name: "priority",
  label: "Priority",
  options: [
    { value: "low", label: "Low" },
    { value: "medium", label: "Medium" },
    { value: "high", label: "High" },
  ],
  defaultValue: "medium",
});

Data Display

ui.table({
  columns: [
    { key: "name", label: "Name" },
    { key: "status", label: "Status" },
    { key: "date", label: "Date", align: "right" },
  ],
  rows: [
    { name: "Sprint planning", status: "Done", date: "Jan 15" },
    { name: "Design review", status: "Open", date: "Jan 20" },
  ],
});

ui.codeBlock("const x = 42;", { language: "typescript" });

Media & References

ui.image({ src: "https://...", alt: "Screenshot", width: 800, height: 400 });
ui.fileCard({ title: "Q4 Report", subtitle: "Updated yesterday", fileId: "file_123" });
ui.userChip({ label: "Alice", userId: "user_123" });
ui.emptyState({
  title: "No items yet",
  description: "Create your first item.",
  action: actions.custom("my-app.create"),
});

Tab Autocomplete API

The Tab API provides OpenAI-compatible completions for inline autocomplete. Authenticate with a workspace API key that has the ai.invoke scope.

import { ColineApiClient } from "@colineapp/sdk";

const client = new ColineApiClient({
  baseUrl: "https://coline.app",
  apiKey: process.env.COLINE_API_KEY!,
});

// Stream text completions
for await (const text of client.streamTabText({
  tab_context: {
    surface: "docs",
    workspace_slug: "acme",
    entity_id: "doc_123",
    active_text_before_cursor: "The quick brown ",
  },
})) {
  process.stdout.write(text);
}

Supported surfaces: notes, docs, messages, tasks, calendar.

Login with Coline (OAuth)

Add "Login with Coline" to your app using standard OAuth 2.0 Authorization Code + PKCE.

import { ColineApiClient, createPkcePair } from "@colineapp/sdk";

const client = new ColineApiClient({ baseUrl: "https://coline.app" });

// 1. Build the authorize URL
const pkce = await createPkcePair();
const authorizeUrl = client.buildLoginWithColineAuthorizeUrl({
  clientId: "col_client_...",
  redirectUri: "https://your-app.com/callback",
  scope: "openid profile email",
  codeChallenge: pkce.challenge,
  codeChallengeMethod: pkce.method,
});
// Redirect the user to authorizeUrl

// 2. Exchange the code (in your callback handler)
const token = await client.exchangeOAuthCode({
  clientId: "col_client_...",
  clientSecret: "col_secret_...",
  code: callbackCode,
  redirectUri: "https://your-app.com/callback",
  codeVerifier: pkce.verifier,
});

// 3. Get user info
const user = await client.getOAuthUserInfo(token.access_token);
console.log(user.email, user.name);

Create OAuth clients from the Developer Console under Login with Coline.

Raw OpenAPI Client

For direct spec-driven access:

import { createAppPlatformClient } from "@colineapp/sdk";

const client = createAppPlatformClient({
  baseUrl: "https://coline.app",
  apiKey: process.env.COLINE_API_KEY!,
});

const { data } = await client.GET("/api/v1/apps");

Regenerate OpenAPI Types

pnpm sdk:generate:openapi