@boostecom/provider 0.0.1

package/docs/content/api.mdx

@@ -0,0 +1,757 @@
+---
+title: API Reference
+description: Documentation complète de l'API du provider Claude Code
+---
+
+# API Reference
+
+Cette page documente toutes les options de configuration disponibles pour le provider Claude Code.
+
+## `claudeCode(model, settings?)`
+
+Fonction principale pour créer une instance du modèle Claude Code.
+
+### Paramètres
+
+#### `model` (required)
+
+Type: `string`
+
+Le modèle Claude à utiliser. Peut être un alias court ou un identifiant complet.
+
+**Aliases courts:**
+- `'opus'` - Claude Opus (le plus capable)
+- `'sonnet'` - Claude Sonnet (équilibré)
+- `'haiku'` - Claude Haiku (rapide et économique)
+
+**Identifiants complets:**
+- `'claude-opus-4-5'`
+- `'claude-sonnet-4-5-20250514'`
+- `'claude-haiku-4-5-20250514'`
+
+```typescript
+const model = claudeCode('sonnet');
+// ou
+const model = claudeCode('claude-sonnet-4-5-20250514');
+```
+
+#### `settings` (optional)
+
+Type: `ClaudeCodeSettings`
+
+Configuration avancée du comportement du provider.
+
+## ClaudeCodeSettings
+
+Interface complète de configuration.
+
+### Options de base
+
+#### `systemPrompt`
+
+Type: `string | { type: 'preset', preset: 'claude_code', append?: string }`
+
+Prompt système personnalisé ou preset Claude Code.
+
+```typescript
+// Prompt personnalisé
+const model = claudeCode('sonnet', {
+  systemPrompt: 'Tu es un expert en TypeScript.',
+});
+
+// Preset avec ajout
+const model = claudeCode('sonnet', {
+  systemPrompt: {
+    type: 'preset',
+    preset: 'claude_code',
+    append: 'Réponds toujours en français.',
+  },
+});
+```
+
+#### `maxTurns`
+
+Type: `number`  
+Default: Non défini
+
+Nombre maximum de tours de conversation.
+
+```typescript
+const model = claudeCode('sonnet', {
+  maxTurns: 10, // Maximum 10 échanges
+});
+```
+
+#### `maxThinkingTokens`
+
+Type: `number`  
+Default: Non défini
+
+Tokens maximum pour la phase de réflexion du modèle.
+
+```typescript
+const model = claudeCode('opus', {
+  maxThinkingTokens: 2000,
+});
+```
+
+#### `cwd`
+
+Type: `string`  
+Default: `process.cwd()`
+
+Répertoire de travail pour les opérations du CLI.
+
+```typescript
+const model = claudeCode('sonnet', {
+  cwd: '/chemin/vers/projet',
+});
+```
+
+### Gestion des outils
+
+#### `allowedTools`
+
+Type: `string[]`  
+Default: Tous les outils autorisés
+
+Liste des outils que Claude peut utiliser.
+
+**Outils intégrés:**
+- `'Read'` - Lire des fichiers
+- `'Write'` - Créer/écrire des fichiers
+- `'Edit'` - Modifier des fichiers
+- `'LS'` - Lister les fichiers
+- `'Bash'` - Exécuter des commandes shell
+- `'Task'` - Créer des sous-tâches
+- `'Skill'` - Utiliser des compétences personnalisées
+
+**Patterns avec wildcards:**
+- `'Bash(git:*)'` - Seulement commandes git
+- `'Bash(git log:*)'` - Seulement git log
+
+```typescript
+const model = claudeCode('sonnet', {
+  allowedTools: ['Read', 'LS', 'Bash(git:*)'],
+});
+```
+
+#### `disallowedTools`
+
+Type: `string[]`  
+Default: Aucun
+
+Outils explicitement interdits.
+
+```typescript
+const model = claudeCode('sonnet', {
+  disallowedTools: [
+    'Write',
+    'Bash(rm:*)',  // Interdire rm
+    'Bash(sudo:*)', // Interdire sudo
+  ],
+});
+```
+
+#### `canUseTool`
+
+Type: `(tool: ToolInfo) => Promise<boolean | { allowed: boolean, input?: any }>`  
+Default: Non défini
+
+Callback invoqué avant chaque utilisation d'outil. Permet un contrôle dynamique.
+
+```typescript
+const model = claudeCode('sonnet', {
+  streamingInput: 'always', // Requis pour canUseTool
+  canUseTool: async (tool) => {
+    console.log(`🔧 Demande d'utilisation: ${tool.name}`);
+    
+    // Bloquer certains outils
+    if (tool.name === 'Bash' && tool.input.command.includes('rm')) {
+      console.log('❌ Commande rm refusée');
+      return false;
+    }
+    
+    // Autoriser
+    return true;
+    
+    // Ou modifier l'input
+    // return {
+    //   allowed: true,
+    //   input: { ...tool.input, modified: true }
+    // };
+  },
+});
+```
+
+### Hooks et callbacks
+
+#### `hooks`
+
+Type: `Record<string, Array<{ matcher?: string, hooks: Array<(...args: unknown[]) => Promise<unknown>> }>>`  
+Default: Non défini
+
+Hooks de lifecycle pour intercepter les événements.
+
+```typescript
+const model = claudeCode('sonnet', {
+  hooks: {
+    PreToolUse: [{
+      matcher: 'Bash',
+      hooks: [
+        async (toolName, input) => {
+          console.log(`⚡ Avant exécution de ${toolName}`);
+          console.log('Input:', input);
+        },
+      ],
+    }],
+    PostToolUse: [{
+      hooks: [
+        async (toolName, input, result) => {
+          console.log(`✅ Après exécution de ${toolName}`);
+          console.log('Résultat:', result);
+        },
+      ],
+    }],
+  },
+});
+```
+
+#### `onStreamStart`
+
+Type: `(injector: MessageInjector) => void`  
+Default: Non défini
+
+Callback invoqué au démarrage du streaming. Reçoit un `MessageInjector` pour l'injection de messages mid-session.
+
+```typescript
+let injector: MessageInjector | null = null;
+
+const model = claudeCode('sonnet', {
+  streamingInput: 'always',
+  onStreamStart: (inj) => {
+    injector = inj;
+    console.log('📡 Streaming démarré');
+  },
+});
+
+// Plus tard, injecter un message
+injector?.inject('STOP! Change de direction.');
+```
+
+#### `onQueryCreated`
+
+Type: `(query: Query) => void`  
+Default: Non défini
+
+Callback invoqué à la création de la Query. Utile pour stocker la référence.
+
+```typescript
+const queries = new Map();
+
+const model = claudeCode('sonnet', {
+  onQueryCreated: (query) => {
+    queries.set('session-123', query);
+  },
+});
+```
+
+### Permissions et sécurité
+
+#### `permissionMode`
+
+Type: `'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'delegate' | 'dontAsk'`  
+Default: `'default'`
+
+Mode de permission pour l'exécution des outils.
+
+- `'default'` - Demande permission pour actions sensibles
+- `'acceptEdits'` - Accepte automatiquement les modifications
+- `'bypassPermissions'` - Contourne toutes les permissions (dangereux)
+- `'plan'` - Mode planification sans exécution
+- `'delegate'` - Délègue les décisions
+- `'dontAsk'` - N'affiche pas de prompts
+
+```typescript
+const model = claudeCode('sonnet', {
+  permissionMode: 'acceptEdits',
+});
+```
+
+#### `allowDangerouslySkipPermissions`
+
+Type: `boolean`  
+Default: `false`
+
+Autoriser le contournement des permissions (utilisé avec `permissionMode: 'bypassPermissions'`).
+
+<Note type="danger">
+  **Danger** : N'utilisez ceci que dans des environnements contrôlés et isolés.
+</Note>
+
+```typescript
+const model = claudeCode('sonnet', {
+  permissionMode: 'bypassPermissions',
+  allowDangerouslySkipPermissions: true, // Requis
+});
+```
+
+### Sessions et état
+
+#### `sessionId`
+
+Type: `string`  
+Default: Généré automatiquement
+
+Identifiant de session personnalisé pour tracking et corrélation.
+
+```typescript
+const model = claudeCode('sonnet', {
+  sessionId: 'user-123-conversation-456',
+});
+```
+
+#### `resume`
+
+Type: `string`  
+Default: Non défini
+
+Reprendre une session existante par son ID.
+
+```typescript
+const model = claudeCode('sonnet', {
+  resume: 'session-abc-123',
+});
+```
+
+#### `resumeSessionAt`
+
+Type: `string` (UUID)  
+Default: Non défini
+
+Reprendre à un message spécifique dans une session.
+
+```typescript
+const model = claudeCode('sonnet', {
+  resume: 'session-abc-123',
+  resumeSessionAt: 'msg-uuid-456',
+});
+```
+
+#### `persistSession`
+
+Type: `boolean`  
+Default: `true`
+
+Persister la session sur disque dans `~/.claude/projects/`.
+
+```typescript
+const model = claudeCode('sonnet', {
+  persistSession: false, // Session éphémère
+});
+```
+
+#### `forkSession`
+
+Type: `boolean`  
+Default: `false`
+
+Lors d'une reprise, créer une nouvelle session au lieu de continuer l'originale.
+
+```typescript
+const model = claudeCode('sonnet', {
+  resume: 'session-abc',
+  forkSession: true, // Créer une branche
+});
+```
+
+### Skills et settings
+
+#### `settingSources`
+
+Type: `Array<'user' | 'project' | 'local'>`  
+Default: Non défini
+
+Sources de settings à charger (CLAUDE.md, settings.json, etc.).
+
+**Requis pour Skills.**
+
+```typescript
+const model = claudeCode('sonnet', {
+  settingSources: ['user', 'project'],
+  allowedTools: ['Skill', 'Read', 'Write'], // 'Skill' requis
+});
+```
+
+**Sources:**
+- `'user'` - `~/.claude/` (settings globaux)
+- `'project'` - `./.claude/` (settings du projet)
+- `'local'` - Settings locaux
+
+### Streaming et input
+
+#### `streamingInput`
+
+Type: `'auto' | 'always' | 'off'`  
+Default: `'auto'`
+
+Contrôle du mode streaming input.
+
+- `'auto'` - Active si `canUseTool` est défini
+- `'always'` - Toujours activer (requis pour images et injection)
+- `'off'` - Désactiver
+
+```typescript
+const model = claudeCode('sonnet', {
+  streamingInput: 'always',
+});
+```
+
+### Logging et debugging
+
+#### `verbose`
+
+Type: `boolean`  
+Default: `false`
+
+Activer les logs détaillés (debug et info).
+
+```typescript
+const model = claudeCode('sonnet', {
+  verbose: true,
+});
+```
+
+#### `logger`
+
+Type: `Logger | false`  
+Default: `console`
+
+Logger personnalisé ou désactivation complète des logs.
+
+```typescript
+import type { Logger } from '@boostecom/provider';
+
+// Logger personnalisé
+const customLogger: Logger = {
+  debug: (msg) => myLogger.debug(msg),
+  info: (msg) => myLogger.info(msg),
+  warn: (msg) => myLogger.warn(msg),
+  error: (msg) => myLogger.error(msg),
+};
+
+const model = claudeCode('sonnet', {
+  verbose: true,
+  logger: customLogger,
+});
+
+// Désactiver les logs
+const silentModel = claudeCode('sonnet', {
+  logger: false,
+});
+```
+
+#### `debug`
+
+Type: `boolean`  
+Default: `false`
+
+Activer les logs de debug programmatiques du SDK.
+
+```typescript
+const model = claudeCode('sonnet', {
+  debug: true,
+});
+```
+
+#### `debugFile`
+
+Type: `string`  
+Default: Non défini
+
+Fichier pour les logs de debug du SDK.
+
+```typescript
+const model = claudeCode('sonnet', {
+  debug: true,
+  debugFile: '/tmp/claude-debug.log',
+});
+```
+
+### Fonctionnalités avancées
+
+#### `betas`
+
+Type: `SdkBeta[]`  
+Default: Non défini
+
+Activer des fonctionnalités beta du SDK.
+
+```typescript
+const model = claudeCode('opus', {
+  betas: ['context-1m-2025-08-07'],
+});
+```
+
+#### `sandbox`
+
+Type: `SandboxSettings`  
+Default: Non défini
+
+Configuration du sandbox.
+
+```typescript
+const model = claudeCode('sonnet', {
+  sandbox: { enabled: true },
+});
+```
+
+#### `plugins`
+
+Type: `SdkPluginConfig[]`  
+Default: Non défini
+
+Charger des plugins personnalisés depuis des chemins locaux.
+
+```typescript
+const model = claudeCode('sonnet', {
+  plugins: [
+    { path: '/chemin/vers/plugin' },
+  ],
+});
+```
+
+#### `maxBudgetUsd`
+
+Type: `number`  
+Default: Non défini
+
+Budget maximum en USD pour la requête.
+
+```typescript
+const model = claudeCode('opus', {
+  maxBudgetUsd: 1.0, // Max 1 USD
+});
+```
+
+#### `mcpServers`
+
+Type: `Record<string, McpServerConfig>`  
+Default: Non défini
+
+Configuration des serveurs MCP (Model Context Protocol).
+
+```typescript
+const model = claudeCode('sonnet', {
+  mcpServers: {
+    'mon-serveur': {
+      command: 'node',
+      args: ['/chemin/vers/serveur.js'],
+    },
+  },
+});
+```
+
+#### `agents`
+
+Type: `Record<string, AgentDefinition>`  
+Default: Non défini
+
+Définition de sous-agents programmatiques.
+
+```typescript
+const model = claudeCode('sonnet', {
+  agents: {
+    'code-reviewer': {
+      description: 'Revoit le code et suggère des améliorations',
+      prompt: 'Tu es un expert en revue de code. Sois constructif.',
+      model: 'opus',
+      tools: ['Read', 'LS'],
+    },
+  },
+});
+```
+
+#### `spawnClaudeCodeProcess`
+
+Type: `(options: SpawnOptions) => SpawnedProcess`  
+Default: Utilise `child_process.spawn`
+
+Fonction personnalisée pour spawner le processus Claude Code. Utile pour VMs, conteneurs, etc.
+
+```typescript
+const model = claudeCode('sonnet', {
+  spawnClaudeCodeProcess: (options) => {
+    // Implémentation personnalisée
+    return customSpawn(options);
+  },
+});
+```
+
+#### `maxToolResultSize`
+
+Type: `number`  
+Default: `10000`
+
+Taille maximale (en caractères) des résultats d'outils dans le stream client. Les résultats trop longs sont tronqués.
+
+```typescript
+const model = claudeCode('sonnet', {
+  maxToolResultSize: 50000, // 50k caractères max
+});
+```
+
+#### `sdkOptions`
+
+Type: `Partial<Options>`  
+Default: Non défini
+
+Escape hatch pour les options non exposées de l'Agent SDK. Surcharge les settings explicites.
+
+<Note type="warning">
+  Les champs gérés par le provider (`model`, `abortController`, `prompt`, `outputFormat`) sont ignorés.
+</Note>
+
+```typescript
+const model = claudeCode('sonnet', {
+  sdkOptions: {
+    maxBudgetUsd: 2,
+    // Autres options SDK non exposées
+  },
+});
+```
+
+### Options système
+
+#### `pathToClaudeCodeExecutable`
+
+Type: `string`  
+Default: `'claude'` (cherche dans PATH)
+
+Chemin personnalisé vers l'exécutable Claude Code.
+
+```typescript
+const model = claudeCode('sonnet', {
+  pathToClaudeCodeExecutable: '/custom/path/to/claude',
+});
+```
+
+#### `executable`
+
+Type: `'node' | 'bun' | 'deno'`  
+Default: `'node'` (ou `'bun'` si Bun détecté)
+
+Runtime JavaScript à utiliser.
+
+```typescript
+const model = claudeCode('sonnet', {
+  executable: 'bun',
+});
+```
+
+#### `executableArgs`
+
+Type: `string[]`  
+Default: Non défini
+
+Arguments supplémentaires pour le runtime.
+
+```typescript
+const model = claudeCode('sonnet', {
+  executable: 'node',
+  executableArgs: ['--max-old-space-size=4096'],
+});
+```
+
+#### `env`
+
+Type: `Record<string, string | undefined>`  
+Default: Non défini
+
+Variables d'environnement personnalisées.
+
+```typescript
+const model = claudeCode('sonnet', {
+  env: {
+    NODE_ENV: 'production',
+    CUSTOM_VAR: 'valeur',
+  },
+});
+```
+
+## Types exportés
+
+### `Logger`
+
+Interface pour les loggers personnalisés.
+
+```typescript
+interface Logger {
+  debug: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}
+```
+
+### `MessageInjector`
+
+Interface pour l'injection de messages mid-session.
+
+```typescript
+interface MessageInjector {
+  inject(content: string, onResult?: (delivered: boolean) => void): void;
+  close(): void;
+}
+```
+
+### `StreamingInputMode`
+
+Type pour le mode streaming input.
+
+```typescript
+type StreamingInputMode = 'auto' | 'always' | 'off';
+```
+
+## Valeurs de retour
+
+### Métadonnées provider
+
+Toutes les fonctions AI SDK retournent des métadonnées dans `providerMetadata['claude-code']` :
+
+```typescript
+const result = await generateText({
+  model: claudeCode('sonnet'),
+  prompt: 'Test',
+});
+
+console.log(result.providerMetadata['claude-code']);
+// {
+//   cost: 0.0015,          // Coût estimé en USD
+//   duration: 2300,        // Durée en ms
+//   sessionId: 'abc-123',  // ID de session
+//   rawUsage: {...},       // Usage brut du SDK
+// }
+```
+
+### Usage tokens
+
+```typescript
+const result = await generateText({
+  model: claudeCode('sonnet'),
+  prompt: 'Test',
+});
+
+console.log(result.usage);
+// {
+//   promptTokens: 10,
+//   completionTokens: 20,
+//   totalTokens: 30
+// }
+```
+
+## Prochaines étapes
+
+- [Guide d'utilisation](/docs/guide) - Patterns et exemples pratiques
+- [Exemples](/docs/examples) - Cas d'usage réels
+- [Skills](/docs/skills) - Créer des compétences personnalisées