SDK

Type-safe JS klijent za opencode server.

opencode JS/TS SDK pruza type-safe klijent za interakciju sa serverom. Koristite ga za izradu integracija i programsko upravljanje opencode-om.

Saznajte vise kako server radi. Za primjere pogledajte projects koje je napravila zajednica.

Instalacija

Instalirajte SDK sa npm-a:

npm install @opencode-ai/sdk

Kreiranje klijenta

Kreirajte instancu opencode:

import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()

Ovo pokrece i server i klijent

Opcije

Opcija	Tip	Opis	Default
`hostname`	`string`	Hostname servera	`127.0.0.1`
`port`	`number`	Port servera	`4096`
`signal`	`AbortSignal`	Abort signal za otkazivanje	`undefined`
`timeout`	`number`	Timeout u ms za start servera	`5000`
`config`	`Config`	Konfiguracijski objekat	`{}`

Konfiguracija

Mozete proslijediti konfiguracijski objekat za prilagodavanje ponasanja. Instanca i dalje ucitava opencode.json, ali konfiguraciju mozete nadjacati ili dodati inline:

import { createOpencode } from "@opencode-ai/sdk"

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "anthropic/claude-3-5-sonnet-20241022",
  },
})

console.log(`Server running at ${opencode.server.url}`)

opencode.server.close()

Samo klijent

Ako vec imate pokrenutu opencode instancu, mozete napraviti klijentsku instancu i povezati se na nju:

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
})

Opcije

Opcija	Tip	Opis	Default
`baseUrl`	`string`	URL servera	`http://localhost:4096`
`fetch`	`function`	Prilagodena fetch implementacija	`globalThis.fetch`
`parseAs`	`string`	Metoda parsiranja odgovora	`auto`
`responseStyle`	`string`	Stil povrata: `data` ili `fields`	`fields`
`throwOnError`	`boolean`	Baci greske umjesto povrata	`false`

Tipovi

SDK ukljucuje TypeScript definicije za sve API tipove. Uvezite ih direktno:

import type { Session, Message, Part } from "@opencode-ai/sdk"

Svi tipovi su generisani iz OpenAPI specifikacije servera i dostupni u types datoteci.

Greške

SDK moze baciti greske koje mozete uhvatiti i obraditi:

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Failed to get session:", (error as Error).message)
}

Strukturirani izlaz

Možete zatražiti strukturirani JSON izlaz od modela specificiranjem format sa JSON šemom. Model će koristiti StructuredOutput alat da vrati validirani JSON koji odgovara vašoj šemi.

Osnovna upotreba

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "Company name" },
          founded: { type: "number", description: "Year founded" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "Main products",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

Tipovi formata izlaza

Tip	Opis
`text`	Default. Standardni tekstualni odgovor (nema strukturiranog izlaza)
`json_schema`	Vraća validirani JSON koji odgovara pruženoj šemi

Format JSON šeme

Kada koristite type: 'json_schema', navedite:

Polje	Tip	Opis
`type`	`'json_schema'`	Obavezno. Određuje JSON schema način rada
`schema`	`object`	Obavezno. JSON Schema objekt koji definira strukturu izlaza
`retryCount`	`number`	Opcionalno. Broj ponovnih pokušaja validacije (default: 2)

Rukovanje greškama

Ako model ne uspije proizvesti validan strukturirani izlaz nakon svih ponovnih pokušaja, odgovor će uključivati StructuredOutputError:

if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("Failed to produce structured output:", result.data.info.error.message)
  console.error("Attempts:", result.data.info.error.retries)
}

Najbolje prakse

Navedite jasne opise u svojstvima vaše šeme kako biste pomogli modelu da razumije koje podatke treba izdvojiti
Koristite required da odredite koja polja moraju biti prisutna
Držite šeme fokusiranim - složene ugniježđene šeme modelu mogu biti teže za ispravno popunjavanje
Postavite odgovarajući retryCount - povećajte za složene šeme, smanjite za jednostavne

API-ji

SDK izlaže sve server API-je kroz type-safe klijent.

Global

Metoda	Opis	Odgovor
`global.health()`	Provjera zdravlja i verzije	`{ healthy: true, version: string }`

Primjeri

const health = await client.global.health()
console.log(health.data.version)

App

Metoda	Opis	Odgovor
`app.log()`	Upis log zapisa	`boolean`
`app.agents()`	Lista dostupnih agenata	`Agent[]`

Primjeri

// Write a log entry
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// List available agents
const agents = await client.app.agents()

Project

Metoda	Opis	Odgovor
`project.list()`	Lista svih projekata	`Project[]`
`project.current()`	Trenutni projekat	`Project`

Primjeri

// List all projects
const projects = await client.project.list()

// Get current project
const currentProject = await client.project.current()

Path

Metoda	Opis	Odgovor
`path.get()`	Trenutna putanja	`Path`

Primjeri

// Get current path information
const pathInfo = await client.path.get()

Konfiguracija

Metoda	Opis	Odgovor
`config.get()`	Info o konfiguraciji	`Config`
`config.providers()`	Lista provajdera i default modela	`{ providers:` `Provider[], default: { [key: string]: string } }`

Primjeri

const config = await client.config.get()

const { providers, default: defaults } = await client.config.providers()

Sesije

Metoda	Opis	Napomene
`session.list()`	List sessions	Returns `Session[]`
`session.get({ path })`	Get session	Returns `Session`
`session.children({ path })`	List child sessions	Returns `Session[]`
`session.create({ body })`	Create session	Returns `Session`
`session.delete({ path })`	Delete session	Returns `boolean`
`session.update({ path, body })`	Update session properties	Returns `Session`
`session.init({ path, body })`	Analyze app and create `AGENTS.md`	Returns `boolean`
`session.abort({ path })`	Abort a running session	Returns `boolean`
`session.share({ path })`	Share session	Returns `Session`
`session.unshare({ path })`	Unshare session	Returns `Session`
`session.summarize({ path, body })`	Summarize session	Returns `boolean`
`session.messages({ path })`	List messages in a session	Returns `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Get message details	Returns `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Send prompt message	`body.noReply: true` returns UserMessage (context only). Default returns `AssistantMessage` with AI response. Supports `body.outputFormat` for structured output
`session.command({ path, body })`	Send command to session	Returns `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Run a shell command	Returns `AssistantMessage`
`session.revert({ path, body })`	Revert a message	Returns `Session`
`session.unrevert({ path })`	Restore reverted messages	Returns `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Respond to a permission request	Returns `boolean`

Primjeri

// Create and manage sessions
const session = await client.session.create({
  body: { title: "My session" },
})

const sessions = await client.session.list()

// Send a prompt message
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
    parts: [{ type: "text", text: "Hello!" }],
  },
})

// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "You are a helpful assistant." }],
  },
})

Datoteke

Metoda	Opis	Odgovor
`find.text({ query })`	Search for text in files	Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Find files and directories by name	`string[]` (paths)
`find.symbols({ query })`	Find workspace symbols	`Symbol[]`
`file.read({ query })`	Read a file	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Get status for tracked files	`File[]`

find.files supports a few optional query fields:

type: "file" or "directory"
directory: override the project root for the search
limit: max results (1–200)

Primjeri

// Search and read files
const textResults = await client.find.text({
  query: { pattern: "function.*opencode" },
})

const files = await client.find.files({
  query: { query: "*.ts", type: "file" },
})

const directories = await client.find.files({
  query: { query: "packages", type: "directory", limit: 20 },
})

const content = await client.file.read({
  query: { path: "src/index.ts" },
})

TUI

Metoda	Opis	Odgovor
`tui.appendPrompt({ body })`	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({ body })`	Execute a command	`boolean`
`tui.showToast({ body })`	Show toast notification	`boolean`

Primjeri

// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})

Auth

Metoda	Opis	Odgovor
`auth.set({ ... })`	Set authentication credentials	`boolean`

Primjeri

await client.auth.set({
  path: { id: "anthropic" },
  body: { type: "api", key: "your-api-key" },
})

Događaji

Metoda	Opis	Odgovor
`event.subscribe()`	Server-sent events stream	Server-sent events stream

Primjeri

// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type, event.properties)
}