--- title: SDK description: Client JS de type sécurisé pour le serveur opencode. --- import config from "../../../../config.mjs" export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts` 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](/docs/server) sur le fonctionnement du serveur. Pour des exemples, consultez les [projects](/docs/ecosystem#projects) construits par la communauté. --- ## Installer Installez le SDK à partir de npm : ```bash npm install @opencode-ai/sdk ``` --- ## Créer un client Créez une instance de opencode : ```javascript 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 | `{}` | --- ## 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 : ```javascript 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 : ```javascript 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 : ```typescript 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 : ```typescript try { await client.session.get({ path: { id: "invalid-id" } }) } catch (error) { console.error("Failed to get session:", (error as Error).message) } ``` --- ## Sortie structurée Vous pouvez demander une sortie JSON structurée au modèle en spécifiant un `format` avec un schéma JSON. Le modèle utilisera un outil `StructuredOutput` pour renvoyer un JSON validé correspondant à votre schéma. ### Utilisation de base ```typescript 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"] } ``` ### Types de format de sortie | Type | Description | | ------------- | ----------------------------------------------------------------- | | `text` | Par défaut. Réponse textuelle standard (pas de sortie structurée) | | `json_schema` | Renvoie un JSON validé correspondant au schéma fourni | ### Format de schéma JSON Lors de l'utilisation de `type: 'json_schema'`, fournissez : | Champ | Type | Description | | ------------ | --------------- | --------------------------------------------------------------- | | `type` | `'json_schema'` | Requis. Spécifie le mode de schéma JSON | | `schema` | `object` | Requis. Objet JSON Schema définissant la structure de sortie | | `retryCount` | `number` | Facultatif. Nombre de tentatives de validation (par défaut : 2) | ### Gestion des erreurs Si le modèle ne parvient pas à produire une sortie structurée valide après toutes les tentatives, la réponse inclura une `StructuredOutputError` : ```typescript 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) } ``` ### Bonnes pratiques 1. **Fournissez des descriptions claires** dans les propriétés de votre schéma pour aider le modèle à comprendre quelles données extraire 2. **Utilisez `required`** pour spécifier quels champs doivent être présents 3. **Gardez les schémas ciblés** - les schémas imbriqués complexes peuvent être plus difficiles à remplir correctement pour le modèle 4. **Définissez un `retryCount` approprié** - augmentez-le pour les schémas complexes, diminuez-le pour les simples --- ## 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 ```javascript 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 ```javascript // 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 ```javascript // 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 ```javascript // 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 ```javascript 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. Prend en charge `body.outputFormat` pour [sortie structurée](#structured-output) | | `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 ```javascript // 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 ```javascript // 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 ```javascript // 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 ```javascript 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 ```javascript // 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) } ```