mirror of
https://github.com/sst/opencode.git
synced 2025-08-22 14:04:07 +00:00
This commit is contained in:
Jay V
parent
b3c8bec019
commit
8d8045ff95
5 changed files with 309 additions and 15 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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: {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
300
packages/web/src/content/docs/docs/sdk.mdx
Normal file
300
packages/web/src/content/docs/docs/sdk.mdx
Normal file
|
|
@ -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 <a href={typesUrl}>types file</a>.
|
||||
|
||||
---
|
||||
|
||||
## APIs
|
||||
|
||||
The SDK exposes all server APIs through a type-safe client interface.
|
||||
|
||||
---
|
||||
|
||||
### App
|
||||
|
||||
| Method | Description | Response |
|
||||
| ------------ | ------------------ | --------------------------------------- |
|
||||
| `app.get()` | Get app info | <a href={typesUrl}><code>App</code></a> |
|
||||
| `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 | <a href={typesUrl}><code>Config</code></a> |
|
||||
| `config.providers()` | List providers and default models | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, 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 <a href={typesUrl}><code>Session[]</code></a> |
|
||||
| `session.get({ id })` | Get session | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||
| `session.children({ id })` | List child sessions | Returns <a href={typesUrl}><code>Session[]</code></a> |
|
||||
| `session.create({ parentID?, title? })` | Create session | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||
| `session.delete({ id })` | Delete session | Returns `boolean` |
|
||||
| `session.update({ id, title? })` | Update session properties | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||
| `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 <a href={typesUrl}><code>Session</code></a> |
|
||||
| `session.unshare({ id })` | Unshare session | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||
| `session.summarize({ id, providerID, modelID })` | Summarize session | Returns `boolean` |
|
||||
| `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>`}[]` |
|
||||
| `session.message({ id, messageID })` | Get message details | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}` |
|
||||
| `session.chat({ id, ...chatInput })` | Send chat message | Returns <a href={typesUrl}><code>Message</code></a> |
|
||||
| `session.shell({ id, agent, command })` | Run a shell command | Returns <a href={typesUrl}><code>Message</code></a> |
|
||||
| `session.revert({ id, messageID, partID? })` | Revert a message | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||
| `session.unrevert({ id })` | Restore reverted messages | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||
| `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 | <a href={typesUrl}><code>Symbol[]</code></a> |
|
||||
| `file.read({ path })` | Read a file | `{ type: "raw" \| "patch", content: string }` |
|
||||
| `file.status()` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> |
|
||||
|
||||
---
|
||||
|
||||
#### 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 | <a href={typesUrl}><code>Agent[]</code></a> |
|
||||
|
||||
---
|
||||
|
||||
#### 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)
|
||||
}
|
||||
```
|
||||
|
|
@ -57,7 +57,7 @@ The opencode server exposes the following APIs.
|
|||
| Method | Path | Description | Response |
|
||||
| ------ | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `GET` | `/config` | Get config info | <a href={typesUrl}><code>Config</code></a> |
|
||||
| `GET` | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
|
||||
| `GET` | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -76,8 +76,8 @@ The opencode server exposes the following APIs.
|
|||
| `POST` | `/session/:id/share` | Share session | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||
| `DELETE` | `/session/:id/share` | Unshare session | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||
| `POST` | `/session/:id/summarize` | Summarize session | |
|
||||
| `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>`}[]` |
|
||||
| `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>`}` |
|
||||
| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
|
||||
| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
|
||||
| `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> |
|
||||
| `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> |
|
||||
| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue