SDK

Client JS typ pour le serveur opencode.

Le SDK JS/TS d’opencode fournit un client typ pour interagir avec le serveur. Utilisez-le pour crer des intgrations et contrler opencode par programmation.

En savoir plus sur le fonctionnement du serveur. Pour des exemples, consultez les projets crs par la communaut.

Installation

Installez le SDK depuis npm :

npm install @opencode-ai/sdk

Crer un client

Crez une instance d’opencode :

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

const { client } = await createOpencode()

Cela lance la fois un serveur et un client

Options

Option	Type	Description	Default
`hostname`	`string`	Nom d’hte du serveur	`127.0.0.1`
`port`	`number`	Port du serveur	`4096`
`signal`	`AbortSignal`	Signal d’abandon pour l’annulation	`undefined`
`timeout`	`number`	Dlai en ms pour le dmarrage du serveur	`5000`
`config`	`Config`	Objet de configuration	`{}`

Config

Vous pouvez passer un objet de configuration pour personnaliser le comportement. L’instance rcupre toujours votre opencode.json, mais vous pouvez remplacer ou ajouter une configuration en ligne :

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(`Serveur en cours d'excution sur ${opencode.server.url}`)

opencode.server.close()

Client uniquement

Si vous avez dj une instance d’opencode en cours d’excution, vous pouvez crer une instance client pour vous y connecter :

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

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

Options

Option	Type	Description	Default
`baseUrl`	`string`	URL du serveur	`http://localhost:4096`
`fetch`	`function`	Implmentation fetch personnalise	`globalThis.fetch`
`parseAs`	`string`	Mthode d’analyse de la rponse	`auto`
`responseStyle`	`string`	Style de retour : `data` ou `fields`	`fields`
`throwOnError`	`boolean`	Lancer des erreurs au lieu de retourner	`false`

Types

Le SDK inclut les dfinitions TypeScript pour tous les types API. Importez-les directement :

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

Tous les types sont gnrs partir de la spcification OpenAPI du serveur et sont disponibles dans le fichier de types.

Erreurs

Le SDK peut lancer des erreurs que vous pouvez attraper et grer :

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("chec de l'obtention de la session :", (error as Error).message)
}

API

Le SDK expose toutes les API du serveur via un client typ.

Global

Method	Description	Response
`global.health()`	Vrifier la sant du serveur et la version	`{ healthy: true, version: string }`

Exemples

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

App

Method	Description	Response
`app.log()`	crire une entre de journal	`boolean`
`app.agents()`	Lister tous les agents disponibles	`Agent[]`

Exemples

// crire une entre de journal
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Opration termine",
  },
})

// Lister les agents disponibles
const agents = await client.app.agents()

Project

Method	Description	Response
`project.list()`	Lister tous les projets	`Project[]`
`project.current()`	Obtenir le projet actuel	`Project`

Exemples

// Lister tous les projets
const projects = await client.project.list()

// Obtenir le projet actuel
const currentProject = await client.project.current()

Path

Method	Description	Response
`path.get()`	Obtenir le chemin actuel	`Path`

Exemples

// Obtenir les informations sur le chemin actuel
const pathInfo = await client.path.get()

Config

Method	Description	Response
`config.get()`	Obtenir les infos de configuration	`Config`
`config.providers()`	Lister les fournisseurs et les modles par dfaut	`{ providers:` `Provider[], default: { [key: string]: string } }`

Exemples

const config = await client.config.get()

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

Sessions

Method	Description	Notes
`session.list()`	Lister les sessions	Retourne `Session[]`
`session.get({ path })`	Obtenir la session	Retourne `Session`
`session.children({ path })`	Lister les sessions enfants	Retourne `Session[]`
`session.create({ body })`	Crer une session	Retourne `Session`
`session.delete({ path })`	Supprimer une session et toutes ses donnes	Retourne `boolean`
`session.update({ path, body })`	Mettre jour les proprits de la session	Retourne `Session`
`session.init({ path, body })`	Analyser l’application et crer `AGENTS.md`	Retourne `boolean`
`session.abort({ path })`	Avorter une session en cours	Retourne `boolean`
`session.share({ path })`	Partager la session	Retourne `Session`
`session.unshare({ path })`	Annuler le partage de la session	Retourne `Session`
`session.summarize({ path, body })`	Rsumer la session	Retourne `boolean`
`session.messages({ path })`	Lister les messages dans une session	Retourne `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Obtenir les dtails du message	Retourne `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Envoyer un message de prompt	`body.noReply: true` retourne UserMessage (contexte uniquement). Par dfaut, retourne `AssistantMessage` avec rponse IA
`session.command({ path, body })`	Envoyer une commande la session	Retourne `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Excuter une commande shell	Retourne `AssistantMessage`
`session.revert({ path, body })`	Rtablir un message	Retourne `Session`
`session.unrevert({ path })`	Restaurer les messages rtablis	Retourne `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Rpondre une demande d’autorisation	Retourne `boolean`

Exemples

// Crer et grer des sessions
const session = await client.session.create({
  body: { title: "Ma session" },
})

const sessions = await client.session.list()

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

// Injecter du contexte sans dclencher de rponse IA (utile pour les plugins)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "Vous tes un assistant utile." }],
  },
})

Files

Method	Description	Response
`find.text({ query })`	Rechercher du texte dans les fichiers	Tableau d’objets de correspondance avec `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Trouver des fichiers et rpertoires par nom	`string[]` (chemins)
`find.symbols({ query })`	Trouver les symboles de l’espace de travail	`Symbol[]`
`file.read({ query })`	Lire un fichier	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Obtenir le statut des fichiers suivis	`File[]`

find.files prend en charge quelques champs de requete facultatifs :

type : "file" ou "directory"
directory : remplacer la racine du projet pour la recherche
limit : rsultats max (1-200)

Exemples

// Rechercher et lire des fichiers
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

Method	Description	Response
`tui.appendPrompt({ body })`	Ajouter du texte au prompt	`boolean`
`tui.openHelp()`	Ouvrir la bote de dialogue d’aide	`boolean`
`tui.openSessions()`	Ouvrir le slecteur de session	`boolean`
`tui.openThemes()`	Ouvrir le slecteur de thme	`boolean`
`tui.openModels()`	Ouvrir le slecteur de modle	`boolean`
`tui.submitPrompt()`	Soumettre le prompt actuel	`boolean`
`tui.clearPrompt()`	Effacer le prompt	`boolean`
`tui.executeCommand({ body })`	Excuter une commande	`boolean`
`tui.showToast({ body })`	Afficher une notification de toast	`boolean`

Exemples

// Contrler l'interface TUI
await client.tui.appendPrompt({
  body: { text: "Ajouter ceci au prompt" },
})

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

Auth

Method	Description	Response
`auth.set({ ... })`	Dfinir les informations d’authentification	`boolean`

Exemples

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

Events

Method	Description	Response
`event.subscribe()`	Flux d’vnements envoys par le serveur	Flux d’vnements envoys par le serveur

Exemples

// couter les vnements en temps rel
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("vnement :", event.type, event.properties)
}