Skip to content

Commit 8d8045f

Browse files
jayairjayair
committed
docs: add sdk doc
1 parent b3c8bec commit 8d8045f

File tree

5 files changed

+309
-15
lines changed

5 files changed

+309
-15
lines changed

‎.opencode/agent/docs.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,6 @@ example, if the page title is "Models", avoid using a section title like "Add
2424
new models". This might be unavoidable in some cases, but try to avoid it.
2525

2626
Check out the /packages/web/src/content/docs/docs/index.mdx as an example.
27+
28+
For JS or TS code snippets remove trailing semicolons and any trailing commas
29+
that might not be needed.

‎packages/web/astro.config.mjs‎

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -67,13 +67,7 @@ export default defineConfig({
6767

6868
{
6969
label: "Usage",
70-
items: [
71-
"docs/tui",
72-
"docs/cli",
73-
"docs/ide",
74-
"docs/share",
75-
"docs/github"
76-
],
70+
items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/github"],
7771
},
7872

7973
{
@@ -93,10 +87,7 @@ export default defineConfig({
9387

9488
{
9589
label: "Develop",
96-
items: [
97-
"docs/server",
98-
"docs/plugins",
99-
],
90+
items: ["docs/sdk", "docs/server", "docs/plugins"],
10091
},
10192
],
10293
components: {

‎packages/web/src/content/docs/docs/cli.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ opencode run Explain the use of context in Go
176176

177177
### serve
178178

179-
Start a headless opencode server for API access. See [Server API](/docs/server) for the full HTTP interface.
179+
Start a headless opencode server for API access. Check out the [server docs](/docs/server) for the full HTTP interface.
180180

181181
```bash
182182
opencode serve

‎packages/web/src/content/docs/docs/sdk.mdx‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
---
2+
title: SDK
3+
description: JS SDK for the opencode server.
4+
---
5+
6+
import config from "../../../../config.mjs"
7+
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
8+
9+
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.
10+
11+
---
12+
13+
## Install
14+
15+
Install the SDK from npm:
16+
17+
```bash
18+
npm install @opencode-ai/sdk
19+
```
20+
21+
---
22+
23+
## Create client
24+
25+
Create a client instance to connect to your opencode server:
26+
27+
```javascript
28+
import { createOpencodeClient } from "@opencode-ai/sdk"
29+
30+
const client = createOpencodeClient({
31+
baseUrl: "http://localhost:4096",
32+
})
33+
```
34+
35+
#### Options
36+
37+
| Option | Type | Description | Default |
38+
| --------- | ---------- | --------------------------- | ----------------------- |
39+
| `baseUrl` | `string` | URL of the opencode server | `http://localhost:4096` |
40+
| `fetch` | `function` | Custom fetch implementation | `globalThis.fetch` |
41+
42+
---
43+
44+
## Start server
45+
46+
You can also programmatically start an opencode server:
47+
48+
```javascript
49+
import { createOpencodeServer } from "@opencode-ai/sdk"
50+
51+
const server = await createOpencodeServer({
52+
host: "127.0.0.1",
53+
port: 4096,
54+
})
55+
56+
console.log(`Server running at ${server.url}`)
57+
58+
server.close()
59+
```
60+
61+
---
62+
63+
## Types
64+
65+
The SDK includes TypeScript definitions for all API types. Import them directly:
66+
67+
```typescript
68+
import type { Session, Message, Part } from "@opencode-ai/sdk"
69+
```
70+
71+
All types are generated from the server's OpenAPI specification and available in the <a href={typesUrl}>types file</a>.
72+
73+
---
74+
75+
## APIs
76+
77+
The SDK exposes all server APIs through a type-safe client interface.
78+
79+
---
80+
81+
### App
82+
83+
| Method | Description | Response |
84+
| ------------ | ------------------ | --------------------------------------- |
85+
| `app.get()` | Get app info | <a href={typesUrl}><code>App</code></a> |
86+
| `app.init()` | Initialize the app | `boolean` |
87+
88+
---
89+
90+
#### Examples
91+
92+
```javascript
93+
const app = await client.app.get()
94+
await client.app.init()
95+
```
96+
97+
---
98+
99+
### Config
100+
101+
| Method | Description | Response |
102+
| -------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
103+
| `config.get()` | Get config info | <a href={typesUrl}><code>Config</code></a> |
104+
| `config.providers()` | List providers and default models | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
105+
106+
---
107+
108+
#### Examples
109+
110+
```javascript
111+
const config = await client.config.get()
112+
const { providers, default: defaults } = await client.config.providers()
113+
```
114+
115+
---
116+
117+
### Sessions
118+
119+
| Method | Description | Notes |
120+
| ------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
121+
| `session.list()` | List sessions | Returns <a href={typesUrl}><code>Session[]</code></a> |
122+
| `session.get({ id })` | Get session | Returns <a href={typesUrl}><code>Session</code></a> |
123+
| `session.children({ id })` | List child sessions | Returns <a href={typesUrl}><code>Session[]</code></a> |
124+
| `session.create({ parentID?, title? })` | Create session | Returns <a href={typesUrl}><code>Session</code></a> |
125+
| `session.delete({ id })` | Delete session | Returns `boolean` |
126+
| `session.update({ id, title? })` | Update session properties | Returns <a href={typesUrl}><code>Session</code></a> |
127+
| `session.init({ id, messageID, providerID, modelID })` | Analyze app and create `AGENTS.md` | Returns `boolean` |
128+
| `session.abort({ id })` | Abort a running session | Returns `boolean` |
129+
| `session.share({ id })` | Share session | Returns <a href={typesUrl}><code>Session</code></a> |
130+
| `session.unshare({ id })` | Unshare session | Returns <a href={typesUrl}><code>Session</code></a> |
131+
| `session.summarize({ id, providerID, modelID })` | Summarize session | Returns `boolean` |
132+
| `session.messages({ id })` | List messages in a session | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]` |
133+
| `session.message({ id, messageID })` | Get message details | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
134+
| `session.chat({ id, ...chatInput })` | Send chat message | Returns <a href={typesUrl}><code>Message</code></a> |
135+
| `session.shell({ id, agent, command })` | Run a shell command | Returns <a href={typesUrl}><code>Message</code></a> |
136+
| `session.revert({ id, messageID, partID? })` | Revert a message | Returns <a href={typesUrl}><code>Session</code></a> |
137+
| `session.unrevert({ id })` | Restore reverted messages | Returns <a href={typesUrl}><code>Session</code></a> |
138+
| `session.permissions.respond({ id, permissionID, response })` | Respond to a permission request | Returns `boolean` |
139+
140+
---
141+
142+
#### Examples
143+
144+
```javascript
145+
// Create and manage sessions
146+
const session = await client.session.create({ title: "My session" })
147+
const sessions = await client.session.list()
148+
149+
// Send messages
150+
const message = await client.session.chat({
151+
id: session.id,
152+
providerID: "anthropic",
153+
modelID: "claude-3-5-sonnet-20241022",
154+
parts: [{ type: "text", text: "Hello!" }],
155+
})
156+
```
157+
158+
---
159+
160+
### Files
161+
162+
| Method | Description | Response |
163+
| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
164+
| `find.text({ pattern })` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
165+
| `find.files({ query })` | Find files by name | `string[]` (file paths) |
166+
| `find.symbols({ query })` | Find workspace symbols | <a href={typesUrl}><code>Symbol[]</code></a> |
167+
| `file.read({ path })` | Read a file | `{ type: "raw" \| "patch", content: string }` |
168+
| `file.status()` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> |
169+
170+
---
171+
172+
#### Examples
173+
174+
```javascript
175+
// Search and read files
176+
const textResults = await client.find.text({ pattern: "function.*opencode" })
177+
const files = await client.find.files({ query: "*.ts" })
178+
const content = await client.file.read({ path: "src/index.ts" })
179+
```
180+
181+
---
182+
183+
### Logging
184+
185+
| Method | Description | Response |
186+
| ------------------------------------------------ | --------------- | --------- |
187+
| `log.write({ service, level, message, extra? })` | Write log entry | `boolean` |
188+
189+
---
190+
191+
#### Examples
192+
193+
```javascript
194+
await client.log.write({
195+
service: "my-app",
196+
level: "info",
197+
message: "Operation completed",
198+
})
199+
```
200+
201+
---
202+
203+
### Agents
204+
205+
| Method | Description | Response |
206+
| -------------- | ------------------------- | ------------------------------------------- |
207+
| `agent.list()` | List all available agents | <a href={typesUrl}><code>Agent[]</code></a> |
208+
209+
---
210+
211+
#### Examples
212+
213+
```javascript
214+
const agents = await client.agent.list()
215+
```
216+
217+
---
218+
219+
### TUI
220+
221+
| Method | Description | Response |
222+
| --------------------------------------------- | --------------------------------- | ---------------------- |
223+
| `tui.appendPrompt({ text })` | Append text to the prompt | `boolean` |
224+
| `tui.openHelp()` | Open the help dialog | `boolean` |
225+
| `tui.openSessions()` | Open the session selector | `boolean` |
226+
| `tui.openThemes()` | Open the theme selector | `boolean` |
227+
| `tui.openModels()` | Open the model selector | `boolean` |
228+
| `tui.submitPrompt()` | Submit the current prompt | `boolean` |
229+
| `tui.clearPrompt()` | Clear the prompt | `boolean` |
230+
| `tui.executeCommand({ command })` | Execute a command | `boolean` |
231+
| `tui.showToast({ title?, message, variant })` | Show toast notification | `boolean` |
232+
| `tui.control.next()` | Wait for the next control request | Control request object |
233+
| `tui.control.response({ body })` | Respond to a control request | `boolean` |
234+
235+
---
236+
237+
#### Examples
238+
239+
```javascript
240+
// Control TUI interface
241+
await client.tui.appendPrompt({ text: "Add this to prompt" })
242+
await client.tui.showToast({
243+
message: "Task completed",
244+
variant: "success",
245+
})
246+
```
247+
248+
---
249+
250+
### Auth
251+
252+
| Method | Description | Response |
253+
| ------------------------------- | ------------------------------ | --------- |
254+
| `auth.set({ id, ...authData })` | Set authentication credentials | `boolean` |
255+
256+
---
257+
258+
#### Examples
259+
260+
```javascript
261+
await client.auth.set({
262+
id: "anthropic",
263+
type: "api",
264+
key: "your-api-key",
265+
})
266+
```
267+
268+
---
269+
270+
### Events
271+
272+
| Method | Description | Response |
273+
| ------------------- | ------------------------- | ------------------------- |
274+
| `event.subscribe()` | Server-sent events stream | Server-sent events stream |
275+
276+
---
277+
278+
#### Examples
279+
280+
```javascript
281+
// Listen to real-time events
282+
const eventStream = await client.event.subscribe()
283+
for await (const event of eventStream) {
284+
console.log("Event:", event.type, event.properties)
285+
}
286+
```
287+
288+
---
289+
290+
## Error handling
291+
292+
The SDK throws typed errors that you can catch and handle:
293+
294+
```typescript
295+
try {
296+
const session = await client.session.get({ id: "invalid-id" })
297+
} catch (error) {
298+
console.error("Failed to get session:", error.message)
299+
}
300+
```

‎packages/web/src/content/docs/docs/server.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ The opencode server exposes the following APIs.
5757
| Method | Path | Description | Response |
5858
| ------ | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
5959
| `GET` | `/config` | Get config info | <a href={typesUrl}><code>Config</code></a> |
60-
| `GET` | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
60+
| `GET` | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
6161

6262
---
6363

@@ -76,8 +76,8 @@ The opencode server exposes the following APIs.
7676
| `POST` | `/session/:id/share` | Share session | Returns <a href={typesUrl}><code>Session</code></a> |
7777
| `DELETE` | `/session/:id/share` | Unshare session | Returns <a href={typesUrl}><code>Session</code></a> |
7878
| `POST` | `/session/:id/summarize` | Summarize session | |
79-
| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]` |
80-
| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
79+
| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
80+
| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
8181
| `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 <a href={typesUrl}><code>Message</code></a> |
8282
| `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 <a href={typesUrl}><code>Message</code></a> |
8383
| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` |

0 commit comments

Comments
 (0)