SDK

Client JS de type sécurisé pour le serveur opencode.

Le SDK opencode JS/TS fournit un client de type sécurisé pour interagir avec le serveur. Utilisez-le pour créer des intégrations et contrôler opencode par programme.

En savoir plus sur le fonctionnement du serveur. Pour des exemples, consultez les projects construits par la communauté.

Installer

Installez le SDK à partir de npm :

npm install @opencode-ai/sdk

Créer un client

Créez une instance de opencode :

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

const { client } = await createOpencode()

Cela démarre à la fois un serveur et un client

Options

Options	Tapez	Descriptif	Par défaut
`hostname`	`string`	Nom d’hôte du serveur	`127.0.0.1`
`port`	`number`	Port du serveur	`4096`
`signal`	`AbortSignal`	Signal d’abandon pour annulation	`undefined`
`timeout`	`number`	Délai d’attente en ms pour le démarrage du serveur	`5000`
`config`	`Config`	Objet de configuration	`{}`

Vous pouvez transmettre un objet de configuration pour personnaliser le comportement. L’instance récupère 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(`Server running at ${opencode.server.url}`)

opencode.server.close()

Client uniquement

Si vous disposez déjà d’une instance en cours d’exécution de opencode, vous pouvez créer une instance client pour vous y connecter :

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

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

Options

Options	Tapez	Descriptif	Par défaut
`baseUrl`	`string`	URL du serveur	`http://localhost:4096`
`fetch`	`function`	Implémentation de récupération personnalisée	`globalThis.fetch`
`parseAs`	`string`	Méthode d’analyse des réponses	`auto`
`responseStyle`	`string`	Style de retour : `data` ou `fields`	`fields`
`throwOnError`	`boolean`	Lancez des erreurs au lieu de return	`false`

Types

Le SDK inclut des définitions TypeScript pour tous les types API. Importez-les directement :

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

Tous les types sont générés à partir de la spécification OpenAPI du serveur et disponibles dans le fichier de types.

Erreurs

Le SDK peut générer des erreurs que vous pouvez détecter et gérer :

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

APIs

Le SDK expose toutes les API du serveur via un client de type sécurisé.

Mondial

Méthode	Descriptif	Réponse
`global.health()`	Vérifier l’état et la version du serveur	`{ healthy: true, version: string }`

Exemples

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

Application

Méthode	Descriptif	Réponse
`app.log()`	Écrire une entrée de journal	`boolean`
`app.agents()`	Liste tous les agents disponibles	`Agent[]`

Exemples

// 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()

Projet

Méthode	Descriptif	Réponse
`project.list()`	Lister tous les projets	`Project[]`
`project.current()`	Obtenir le projet en cours	`Project`

Exemples

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

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

Chemin

Méthode	Descriptif	Réponse
`path.get()`	Obtenir le chemin actuel	`Path`

Exemples

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

Configuration

Méthode	Descriptif	Réponse
`config.get()`	Obtenir des informations de configuration	`Config`
`config.providers()`	Liste des fournisseurs et modèles par défaut	`{ providers:` `Provider[], default: { [key: string]: string } }`

Exemples

const config = await client.config.get()

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

Séances

Méthode	Descriptif	Remarques
`session.list()`	Liste des séances	Renvoie `Session[]`
`session.get({ path })`	Obtenir une session	Renvoie `Session`
`session.children({ path })`	Liste des sessions enfants	Renvoie `Session[]`
`session.create({ body })`	Créer une séance	Renvoie `Session`
`session.delete({ path })`	Supprimer la séance	Renvoie `boolean`
`session.update({ path, body })`	Mettre à jour les propriétés de la session	Renvoie `Session`
`session.init({ path, body })`	Analysez l’application et créez `AGENTS.md`	Renvoie `boolean`
`session.abort({ path })`	Abandonner une session en cours	Renvoie `boolean`
`session.share({ path })`	Séance de partage	Renvoie `Session`
`session.unshare({ path })`	Annuler le partage de la session	Renvoie `Session`
`session.summarize({ path, body })`	Résumer la séance	Renvoie `boolean`
`session.messages({ path })`	Liste des messages dans une session	Renvoie `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Obtenir les détails du message	Renvoie `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Envoyer un message d’invite	`body.noReply: true` renvoie UserMessage (contexte uniquement). La valeur par défaut renvoie `AssistantMessage` avec réponse IA
`session.command({ path, body })`	Envoyer la commande à la session	Renvoie `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Exécuter une commande shell	Renvoie `AssistantMessage`
`session.revert({ path, body })`	Rétablir un message	Renvoie `Session`
`session.unrevert({ path })`	Restaurer les messages annulés	Renvoie `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Répondre à une demande d’autorisation	Renvoie `boolean`

Exemples

// 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." }],
  },
})

Fichiers

Méthode	Descriptif	Réponse
`find.text({ query })`	Rechercher du texte dans des fichiers	Tableau d’objets correspondant avec `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Rechercher des fichiers et des répertoires par nom	`string[]` (chemins)
`find.symbols({ query })`	Rechercher des symboles d’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 requête facultatifs :

type : "file" ou "directory"
directory : remplace la racine du projet pour la recherche
limit : résultats maximum (1 à 200)

Exemples

// 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

Méthode	Descriptif	Réponse
`tui.appendPrompt({ body })`	Ajouter du texte à l’invite	`boolean`
`tui.openHelp()`	Ouvrir la boîte de dialogue d’aide	`boolean`
`tui.openSessions()`	Ouvrez le sélecteur de session	`boolean`
`tui.openThemes()`	Ouvrez le sélecteur de thème	`boolean`
`tui.openModels()`	Ouvrez le sélecteur de modèle	`boolean`
`tui.submitPrompt()`	Soumettre l’invite actuelle	`boolean`
`tui.clearPrompt()`	Effacez l’invite	`boolean`
`tui.executeCommand({ body })`	Exécuter une commande	`boolean`
`tui.showToast({ body })`	Afficher la notification toast	`boolean`

Exemples

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

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

Authentification

Méthode	Descriptif	Réponse
`auth.set({ ... })`	Définir les informations d’authentification	`boolean`

Exemples

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

Événements

Méthode	Descriptif	Réponse
`event.subscribe()`	Flux d’événements envoyés par le serveur	Flux d’événements envoyés par le serveur

Exemples

// 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)
}