diff --git a/.opencode/agent/docs.md b/.opencode/agent/docs.md index 54e5cdf9..7f974375 100644 --- a/.opencode/agent/docs.md +++ b/.opencode/agent/docs.md @@ -24,3 +24,6 @@ example, if the page title is "Models", avoid using a section title like "Add new models". This might be unavoidable in some cases, but try to avoid it. Check out the /packages/web/src/content/docs/docs/index.mdx as an example. + +For JS or TS code snippets remove trailing semicolons and any trailing commas +that might not be needed. diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index fb905c72..0d406a53 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -67,13 +67,7 @@ export default defineConfig({ { label: "Usage", - items: [ - "docs/tui", - "docs/cli", - "docs/ide", - "docs/share", - "docs/github" - ], + items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/github"], }, { @@ -93,10 +87,7 @@ export default defineConfig({ { label: "Develop", - items: [ - "docs/server", - "docs/plugins", - ], + items: ["docs/sdk", "docs/server", "docs/plugins"], }, ], components: { diff --git a/packages/web/src/content/docs/docs/cli.mdx b/packages/web/src/content/docs/docs/cli.mdx index 6237e4eb..903c3638 100644 --- a/packages/web/src/content/docs/docs/cli.mdx +++ b/packages/web/src/content/docs/docs/cli.mdx @@ -176,7 +176,7 @@ opencode run Explain the use of context in Go ### serve -Start a headless opencode server for API access. See [Server API](/docs/server) for the full HTTP interface. +Start a headless opencode server for API access. Check out the [server docs](/docs/server) for the full HTTP interface. ```bash opencode serve diff --git a/packages/web/src/content/docs/docs/sdk.mdx b/packages/web/src/content/docs/docs/sdk.mdx new file mode 100644 index 00000000..37d53b30 --- /dev/null +++ b/packages/web/src/content/docs/docs/sdk.mdx @@ -0,0 +1,300 @@ +--- +title: SDK +description: JS SDK for the opencode server. +--- + +import config from "../../../../config.mjs" +export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts` + +The opencode [JS/TS SDK](https://www.npmjs.com/package/@opencode-ai/sdk) provides a type-safe client for interacting with the opencode server. You can use it to build custom integrations and control opencode programmatically. + +--- + +## Install + +Install the SDK from npm: + +```bash +npm install @opencode-ai/sdk +``` + +--- + +## Create client + +Create a client instance to connect to your opencode server: + +```javascript +import { createOpencodeClient } from "@opencode-ai/sdk" + +const client = createOpencodeClient({ + baseUrl: "http://localhost:4096", +}) +``` + +#### Options + +| Option | Type | Description | Default | +| --------- | ---------- | --------------------------- | ----------------------- | +| `baseUrl` | `string` | URL of the opencode server | `http://localhost:4096` | +| `fetch` | `function` | Custom fetch implementation | `globalThis.fetch` | + +--- + +## Start server + +You can also programmatically start an opencode server: + +```javascript +import { createOpencodeServer } from "@opencode-ai/sdk" + +const server = await createOpencodeServer({ + host: "127.0.0.1", + port: 4096, +}) + +console.log(`Server running at ${server.url}`) + +server.close() +``` + +--- + +## Types + +The SDK includes TypeScript definitions for all API types. Import them directly: + +```typescript +import type { Session, Message, Part } from "@opencode-ai/sdk" +``` + +All types are generated from the server's OpenAPI specification and available in the types file. + +--- + +## APIs + +The SDK exposes all server APIs through a type-safe client interface. + +--- + +### App + +| Method | Description | Response | +| ------------ | ------------------ | --------------------------------------- | +| `app.get()` | Get app info | App | +| `app.init()` | Initialize the app | `boolean` | + +--- + +#### Examples + +```javascript +const app = await client.app.get() +await client.app.init() +``` + +--- + +### Config + +| Method | Description | Response | +| -------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `config.get()` | Get config info | Config | +| `config.providers()` | List providers and default models | `{ providers: `Provider[]`, default: { [key: string]: string } }` | + +--- + +#### Examples + +```javascript +const config = await client.config.get() +const { providers, default: defaults } = await client.config.providers() +``` + +--- + +### Sessions + +| Method | Description | Notes | +| ------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `session.list()` | List sessions | Returns Session[] | +| `session.get({ id })` | Get session | Returns Session | +| `session.children({ id })` | List child sessions | Returns Session[] | +| `session.create({ parentID?, title? })` | Create session | Returns Session | +| `session.delete({ id })` | Delete session | Returns `boolean` | +| `session.update({ id, title? })` | Update session properties | Returns Session | +| `session.init({ id, messageID, providerID, modelID })` | Analyze app and create `AGENTS.md` | Returns `boolean` | +| `session.abort({ id })` | Abort a running session | Returns `boolean` | +| `session.share({ id })` | Share session | Returns Session | +| `session.unshare({ id })` | Unshare session | Returns Session | +| `session.summarize({ id, providerID, modelID })` | Summarize session | Returns `boolean` | +| `session.messages({ id })` | List messages in a session | Returns `{ info: `Message`, parts: `Part[]`}[]` | +| `session.message({ id, messageID })` | Get message details | Returns `{ info: `Message`, parts: `Part[]`}` | +| `session.chat({ id, ...chatInput })` | Send chat message | Returns Message | +| `session.shell({ id, agent, command })` | Run a shell command | Returns Message | +| `session.revert({ id, messageID, partID? })` | Revert a message | Returns Session | +| `session.unrevert({ id })` | Restore reverted messages | Returns Session | +| `session.permissions.respond({ id, permissionID, response })` | Respond to a permission request | Returns `boolean` | + +--- + +#### Examples + +```javascript +// Create and manage sessions +const session = await client.session.create({ title: "My session" }) +const sessions = await client.session.list() + +// Send messages +const message = await client.session.chat({ + id: session.id, + providerID: "anthropic", + modelID: "claude-3-5-sonnet-20241022", + parts: [{ type: "text", text: "Hello!" }], +}) +``` + +--- + +### Files + +| Method | Description | Response | +| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- | +| `find.text({ pattern })` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` | +| `find.files({ query })` | Find files by name | `string[]` (file paths) | +| `find.symbols({ query })` | Find workspace symbols | Symbol[] | +| `file.read({ path })` | Read a file | `{ type: "raw" \| "patch", content: string }` | +| `file.status()` | Get status for tracked files | File[] | + +--- + +#### Examples + +```javascript +// Search and read files +const textResults = await client.find.text({ pattern: "function.*opencode" }) +const files = await client.find.files({ query: "*.ts" }) +const content = await client.file.read({ path: "src/index.ts" }) +``` + +--- + +### Logging + +| Method | Description | Response | +| ------------------------------------------------ | --------------- | --------- | +| `log.write({ service, level, message, extra? })` | Write log entry | `boolean` | + +--- + +#### Examples + +```javascript +await client.log.write({ + service: "my-app", + level: "info", + message: "Operation completed", +}) +``` + +--- + +### Agents + +| Method | Description | Response | +| -------------- | ------------------------- | ------------------------------------------- | +| `agent.list()` | List all available agents | Agent[] | + +--- + +#### Examples + +```javascript +const agents = await client.agent.list() +``` + +--- + +### TUI + +| Method | Description | Response | +| --------------------------------------------- | --------------------------------- | ---------------------- | +| `tui.appendPrompt({ text })` | Append text to the prompt | `boolean` | +| `tui.openHelp()` | Open the help dialog | `boolean` | +| `tui.openSessions()` | Open the session selector | `boolean` | +| `tui.openThemes()` | Open the theme selector | `boolean` | +| `tui.openModels()` | Open the model selector | `boolean` | +| `tui.submitPrompt()` | Submit the current prompt | `boolean` | +| `tui.clearPrompt()` | Clear the prompt | `boolean` | +| `tui.executeCommand({ command })` | Execute a command | `boolean` | +| `tui.showToast({ title?, message, variant })` | Show toast notification | `boolean` | +| `tui.control.next()` | Wait for the next control request | Control request object | +| `tui.control.response({ body })` | Respond to a control request | `boolean` | + +--- + +#### Examples + +```javascript +// Control TUI interface +await client.tui.appendPrompt({ text: "Add this to prompt" }) +await client.tui.showToast({ + message: "Task completed", + variant: "success", +}) +``` + +--- + +### Auth + +| Method | Description | Response | +| ------------------------------- | ------------------------------ | --------- | +| `auth.set({ id, ...authData })` | Set authentication credentials | `boolean` | + +--- + +#### Examples + +```javascript +await client.auth.set({ + id: "anthropic", + type: "api", + key: "your-api-key", +}) +``` + +--- + +### Events + +| Method | Description | Response | +| ------------------- | ------------------------- | ------------------------- | +| `event.subscribe()` | Server-sent events stream | Server-sent events stream | + +--- + +#### Examples + +```javascript +// Listen to real-time events +const eventStream = await client.event.subscribe() +for await (const event of eventStream) { + console.log("Event:", event.type, event.properties) +} +``` + +--- + +## Error handling + +The SDK throws typed errors that you can catch and handle: + +```typescript +try { + const session = await client.session.get({ id: "invalid-id" }) +} catch (error) { + console.error("Failed to get session:", error.message) +} +``` diff --git a/packages/web/src/content/docs/docs/server.mdx b/packages/web/src/content/docs/docs/server.mdx index 894c30fd..c1616252 100644 --- a/packages/web/src/content/docs/docs/server.mdx +++ b/packages/web/src/content/docs/docs/server.mdx @@ -57,7 +57,7 @@ The opencode server exposes the following APIs. | Method | Path | Description | Response | | ------ | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- | | `GET` | `/config` | Get config info | Config | -| `GET` | `/config/providers` | List providers and default models | `{ providers: `Provider[]`, default: { [key: string]: string } }` | +| `GET` | `/config/providers` | List providers and default models | `{ providers: `Provider[]`, default: { [key: string]: string } }` | --- @@ -76,8 +76,8 @@ The opencode server exposes the following APIs. | `POST` | `/session/:id/share` | Share session | Returns Session | | `DELETE` | `/session/:id/share` | Unshare session | Returns Session | | `POST` | `/session/:id/summarize` | Summarize session | | -| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `Message`, parts: `Part[]`}[]` | -| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `Message`, parts: `Part[]`}` | +| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `Message`, parts: `Part[]`}[]` | +| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `Message`, parts: `Part[]`}` | | `POST` | `/session/:id/message` | Send chat message | body matches [`ChatInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L358), returns Message | | `POST` | `/session/:id/shell` | Run a shell command | body matches [`CommandInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L1007), returns Message | | `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` |