@boostecom/provider 0.0.1

package/docs/examples/README.md

@@ -0,0 +1,499 @@
+# Exemples — Claude Code AI SDK Provider
+
+Ce repertoire contient des exemples selectionnes demontrant les fonctionnalites les plus importantes du Claude Code AI SDK Provider. Chaque exemple a un objectif specifique et illustre un pattern ou une capacite cle.
+
+> **Note** : Ces exemples sont ecrits pour Vercel AI SDK v5. Si vous utilisez AI SDK v4, consultez la branche v4.
+
+## Prerequis
+
+1. Installer et authentifier le CLI Claude :
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+```
+
+2. Compiler le provider :
+
+```bash
+npm run build
+```
+
+3. Verifier votre installation :
+
+```bash
+npx tsx examples/check-cli.ts
+```
+
+## Exemples de demarrage rapide
+
+### 1. Utilisation basique (`basic-usage.ts`)
+
+**Objectif** : L'exemple le plus simple possible — generer du texte avec Claude et afficher les metadonnees.
+
+```bash
+npx tsx examples/basic-usage.ts
+```
+
+**Concepts cles** : Generation de texte, utilisation des tokens, metadonnees provider (cout, duree)
+
+### 2. Streaming (`streaming.ts`)
+
+**Objectif** : Demontrer le streaming en temps reel pour des experiences utilisateur reactives.
+
+```bash
+npx tsx examples/streaming.ts
+```
+
+**Concepts cles** : Traitement du stream, gestion des chunks, sortie en temps reel
+
+### 3. Streaming d'outils (`tool-streaming.ts`)
+
+**Objectif** : Observer les evenements tool-call emis par le provider pendant que Claude Code execute les outils integres.
+
+```bash
+npx tsx examples/tool-streaming.ts
+```
+
+**Concepts cles** : Streaming d'outils, outils executes par le provider, inspection detaillee du stream
+
+### 4. Images (`images.ts`)
+
+**Objectif** : Streamer un prompt incluant une image locale (PNG/JPG/GIF/WebP).
+
+```bash
+npx tsx examples/images.ts /chemin/absolu/vers/image.png
+```
+
+**Concepts cles** : Data URLs d'images, prerequis streaming, prompts multimodaux
+
+### 5. Historique de conversation (`conversation-history.ts`)
+
+**Objectif** : Montrer la bonne facon de maintenir le contexte a travers plusieurs messages.
+
+```bash
+npx tsx examples/conversation-history.ts
+```
+
+**Concepts cles** : Pattern d'historique de messages, preservation du contexte, conversations multi-tours
+
+## Exemples de logging
+
+Le provider inclut un systeme de logging flexible configurable pour differents cas d'usage. Ces exemples demontrent tous les modes de logging :
+
+### 6. Logging par defaut (`logging-default.ts`)
+
+**Objectif** : Comprendre le comportement de logging par defaut (mode non-verbose).
+
+```bash
+npx tsx examples/logging-default.ts
+```
+
+**Concepts cles** : Comportement par defaut, warn/error uniquement, sortie propre
+
+**Ce que vous verrez** : Seuls les messages warning et error apparaissent. Les logs debug et info sont supprimes pour une sortie propre.
+
+### 7. Logging verbose (`logging-verbose.ts`)
+
+**Objectif** : Activer le logging detaille pour le developpement et le depannage.
+
+```bash
+npx tsx examples/logging-verbose.ts
+```
+
+**Concepts cles** : Mode verbose, logs debug/info, tracage d'execution
+
+**Ce que vous verrez** : Tous les niveaux de log (debug, info, warn, error) montrant l'activite detaillee du provider.
+
+### 8. Logger personnalise (`logging-custom-logger.ts`)
+
+**Objectif** : S'integrer avec des systemes de logging externes (Winston, Pino, Datadog, etc.).
+
+```bash
+npx tsx examples/logging-custom-logger.ts
+```
+
+**Concepts cles** : Implementation de logger personnalise, integration externe, formatage des logs
+
+**Ce que vous verrez** : Logs personnalises avec horodatages et prefixes, demontrant les patterns d'integration.
+
+### 9. Logging desactive (`logging-disabled.ts`)
+
+**Objectif** : Operation completement silencieuse sans logs.
+
+```bash
+npx tsx examples/logging-disabled.ts
+```
+
+**Concepts cles** : Mode silencieux, deploiements production, zero sortie
+
+**Ce que vous verrez** : Aucun log provider — operation completement silencieuse.
+
+## Configuration avancee
+
+### 10. Configuration personnalisee (`custom-config.ts`)
+
+**Objectif** : Demontrer les options de configuration du provider et du modele.
+
+```bash
+npx tsx examples/custom-config.ts
+```
+
+**Concepts cles** : Parametres provider, overrides de modele, restrictions d'outils, modes de permission
+
+### 11. Gestion des outils (`tool-management.ts`)
+
+**Objectif** : Montrer le controle fin de l'acces aux outils de Claude pour la securite.
+
+```bash
+npx tsx examples/tool-management.ts
+```
+
+**Concepts cles** : Listes allow/deny, securite des outils, outils serveur MCP, outils integres
+
+### 12. Taches longues (`long-running-tasks.ts`)
+
+**Objectif** : Gerer les timeouts correctement avec le pattern AbortSignal de l'AI SDK.
+
+```bash
+npx tsx examples/long-running-tasks.ts
+```
+
+**Concepts cles** : Timeouts personnalises, annulation gracieuse, logique de retry
+
+### 13. Signal d'annulation (`abort-signal.ts`)
+
+**Objectif** : Implementer des annulations initiees par l'utilisateur et le nettoyage.
+
+```bash
+npx tsx examples/abort-signal.ts
+```
+
+**Concepts cles** : Annulation de requete, nettoyage de ressources, controles utilisateur
+
+### 14. Hooks et Callbacks (`hooks-callbacks.ts`)
+
+**Objectif** : Utiliser les hooks de cycle de vie et les callbacks de permission dynamiques.
+
+```bash
+npx tsx examples/hooks-callbacks.ts
+```
+
+**Concepts cles** : Hooks PreToolUse/PostToolUse, callback canUseTool, controle de permissions, cycle de vie des evenements
+
+### 15. Outils SDK (`sdk-tools-callbacks.ts`)
+
+**Objectif** : Definir et utiliser des outils MCP in-process avec l'Agent SDK.
+
+```bash
+npx tsx examples/sdk-tools-callbacks.ts
+```
+
+**Concepts cles** : Outils in-process, createSdkMcpServer, definitions d'outils, integration MCP
+
+### 16. Gestion des Skills (`skills-management.ts`)
+
+**Objectif** : Configurer le support Skills — outils personnalises definis dans les parametres utilisateur ou projet.
+
+```bash
+npx tsx examples/skills-management.ts
+```
+
+**Concepts cles** : Configuration settingSources, permission d'outil Skill, skills utilisateur/projet, avertissements de validation
+
+**Ce que vous verrez** : Exemples de configuration montrant comment activer les Skills, avec une demonstration de l'avertissement de validation quand 'Skill' est dans allowedTools mais settingSources n'est pas defini.
+
+### 17. Decouverte de Skills (`skills-discovery.ts`)
+
+**Objectif** : Decouvrir et tester programmatiquement les Skills disponibles dans votre environnement Claude Code.
+
+```bash
+npx tsx examples/skills-discovery.ts
+npx tsx examples/skills-discovery.ts --validate
+```
+
+**Concepts cles** : Detection de skills, validation de configuration settingSources, tests de chargement
+
+### 18. Injection mid-stream (`mid-stream-injection.ts`)
+
+**Objectif** : Reorienter une query en cours en injectant un nouveau message utilisateur mid-stream.
+
+```bash
+npx tsx examples/mid-stream-injection.ts
+```
+
+**Concepts cles** : Streaming input, `onQueryCreated`, `query.streamInput()`, mises a jour de prompt en direct
+
+### 18. Injection de messages (`message-injection.ts`)
+
+**Objectif** : Injecter des messages mid-session pour interrompre, rediriger ou fournir un feedback a l'agent.
+
+```bash
+npx tsx examples/message-injection.ts
+```
+
+**Concepts cles** : Callback `onStreamStart`, `MessageInjector`, suivi de livraison, patterns superviseur, recuperation d'injection echouee
+
+**Ce que vous verrez** : Deux exemples demontrant une injection reussie (l'agent arrete d'ecrire des fichiers) et une injection echouee avec recuperation (detection quand l'injection arrive trop tard et retry).
+
+### 20. Agent Teams (`agent-teams.ts`)
+
+**Objectif** : Creer une equipe d'agents specialises (recherche, developpement, tests) travaillant ensemble pour accomplir des taches complexes.
+
+```bash
+npx tsx examples/agent-teams.ts
+```
+
+**Concepts cles** : Agents multiples, restriction d'outils par agent, coordination inter-agents, context etendu (1M tokens beta)
+
+## Generation d'objets (Structured Output)
+
+> **Support natif** : La generation d'objets utilise l'option native `outputFormat` du SDK avec constrained decoding, fournissant du JSON conforme au schema pour les fonctionnalites JSON Schema **supportees**.
+>
+> **Important** : Evitez `.email()`, `.url()`, `.uuid()`, `.datetime()` et les regex complexes avec lookaheads — ceux-ci produisent des annotations JSON Schema `format` et `pattern` qui causent un fallback silencieux du CLI Claude Code vers du texte libre. Utilisez `.describe()` avec des hints de format a la place (ex: `z.string().describe('Adresse email (ex: user@example.com)')`) et validez cote client si une conformite stricte est necessaire.
+
+### 19. Generation d'objets (`generate-object.ts`)
+
+**Objectif** : Patterns de generation d'objets de base — du simple au complexe : primitives, tableaux, champs optionnels, enums, objets imbriques et imbrication profonde.
+
+```bash
+npx tsx examples/generate-object.ts
+```
+
+**Concepts cles** : Bases des schemas, complexite progressive, structures imbriquees, bonnes pratiques
+
+### 20. Contraintes de validation (`generate-object-constraints.ts`)
+
+**Objectif** : Garantir la qualite des donnees avec des plages numeriques, patterns regex simples, limites de longueur de tableaux, enums et multipleOf.
+
+```bash
+npx tsx examples/generate-object-constraints.ts
+```
+
+**Concepts cles** : Min/max/int numeriques, patterns regex (sans lookaheads), contraintes de tableaux, validations combinees complexes
+
+### 21. Stream d'objets (`stream-object.ts`)
+
+**Objectif** : Recevoir des objets partiels incrementaux pendant que l'IA genere des donnees structurees, permettant des mises a jour UI en temps reel.
+
+```bash
+npx tsx examples/stream-object.ts
+```
+
+**Concepts cles** : Streaming d'objets partiels, mises a jour en temps reel, progression champ par champ, API `streamObject()`
+
+### 22. Repro Structured Output (`structured-output-repro.ts`)
+
+**Objectif** : Reproduire les fallbacks CLI de structured output pour certaines fonctionnalites JSON Schema.
+
+```bash
+npx tsx examples/structured-output-repro.ts
+```
+
+**Concepts cles** : Contraintes `format`, limitations regex, comportement de fallback
+
+### 24. Compatibilite Zod 4 (`zod4-compatibility-test.ts`)
+
+**Objectif** : Tester la compatibilite complete du provider avec Zod 4 — schemas basiques, fonctions, objets imbriques, unions discriminees, validations.
+
+```bash
+npx tsx examples/zod4-compatibility-test.ts
+```
+
+**Concepts cles** : Schemas Zod 4, nouvelle API function, discriminated unions, validations string/number, compatibilite provider
+
+## Tests et depannage
+
+### 23. Test d'integration (`integration-test.ts`)
+
+**Objectif** : Suite de tests complete pour verifier votre installation et toutes les fonctionnalites.
+
+```bash
+npx tsx examples/integration-test.ts
+```
+
+**Concepts cles** : Verification des fonctionnalites, gestion d'erreur, patterns de test
+
+### 24. Verification CLI (`check-cli.ts`)
+
+**Objectif** : Outil de depannage pour verifier l'installation et l'authentification du CLI.
+
+```bash
+npx tsx examples/check-cli.ts
+```
+
+**Concepts cles** : Verification d'installation, diagnostic d'erreurs, etapes de depannage
+
+### 25. Limitations (`limitations.ts`)
+
+**Objectif** : Comprendre quelles fonctionnalites AI SDK ne sont pas supportees par le CLI.
+
+```bash
+npx tsx examples/limitations.ts
+```
+
+**Concepts cles** : Parametres non supportes, solutions de contournement, contraintes du provider
+
+## Patterns courants
+
+### Generation d'objets
+
+```typescript
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const { object } = await generateObject({
+  model: claudeCode('haiku'),
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+    // Utiliser .describe() au lieu de .email() — les contraintes format causent un fallback CLI
+    email: z.string().describe('Adresse email (ex: user@example.com)'),
+  }),
+  prompt: 'Generer un profil utilisateur aleatoire',
+});
+```
+
+### Gestion d'erreur
+
+```typescript
+import { isAuthenticationError } from '../dist/index.js';
+
+try {
+  // Votre code ici
+} catch (error) {
+  if (isAuthenticationError(error)) {
+    console.error('Veuillez executer : claude login');
+  }
+}
+```
+
+### Historique de messages pour les conversations
+
+```typescript
+import type { ModelMessage } from 'ai';
+
+const messages: ModelMessage[] = [
+  { role: 'user', content: 'Bonjour, je m\'appelle Alice' },
+  { role: 'assistant', content: 'Enchantee, Alice !' },
+  { role: 'user', content: 'Qu\'est-ce que je viens de te dire ?' },
+];
+
+const { text } = await generateText({
+  model: claudeCode('haiku'),
+  messages,
+});
+```
+
+### Reponses en streaming
+
+```typescript
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: claudeCode('haiku'),
+  prompt: 'Ecris une histoire...',
+});
+
+// Streamer la reponse en temps reel
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Timeouts personnalises
+
+```typescript
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), 300000); // 5 minutes
+
+try {
+  const { text } = await generateText({
+    model: claudeCode('haiku'),
+    prompt: 'Analyse complexe...',
+    abortSignal: controller.signal,
+  });
+  clearTimeout(timeoutId);
+} catch (error) {
+  // Gerer le timeout
+}
+```
+
+### Configuration du logging
+
+```typescript
+import type { Logger } from '../dist/index.js';
+
+// Defaut : warn et error uniquement
+const result1 = streamText({
+  model: claudeCode('haiku'),
+  prompt: 'Bonjour',
+});
+
+// Verbose : tous les niveaux de log
+const result2 = streamText({
+  model: claudeCode('haiku', { verbose: true }),
+  prompt: 'Bonjour',
+});
+
+// Logger personnalise
+const customLogger: Logger = {
+  debug: (msg) => myLogger.debug(msg),
+  info: (msg) => myLogger.info(msg),
+  warn: (msg) => myLogger.warn(msg),
+  error: (msg) => myLogger.error(msg),
+};
+
+const result3 = streamText({
+  model: claudeCode('haiku', {
+    verbose: true,
+    logger: customLogger,
+  }),
+  prompt: 'Bonjour',
+});
+
+// Desactiver tous les logs
+const result4 = streamText({
+  model: claudeCode('haiku', { logger: false }),
+  prompt: 'Bonjour',
+});
+```
+
+## Reference rapide
+
+| Exemple | Cas d'usage principal | Fonctionnalite cle |
+| --- | --- | --- |
+| basic-usage | Demarrage rapide | Generation de texte simple |
+| streaming | UIs reactives | Sortie en temps reel |
+| tool-streaming | Observabilite outils | Inspection evenements outils |
+| images | Prompts multimodaux | Support d'images |
+| conversation-history | Chatbots | Preservation du contexte |
+| logging-default | Comportement par defaut | Warn/error uniquement |
+| logging-verbose | Dev/debogage | Tous les niveaux de log |
+| logging-custom-logger | Integration externe | Logger personnalise |
+| logging-disabled | Operation silencieuse | Aucun log |
+| custom-config | Configuration entreprise | Options de configuration |
+| tool-management | Securite | Controle d'acces |
+| hooks-callbacks | Gestion d'evenements | Hooks de cycle de vie |
+| sdk-tools-callbacks | Outils personnalises | Outils MCP in-process |
+| skills-management | Configuration Skills | Configuration settingSources |
+| skills-discovery | Decouverte de Skills | Detection, validation |
+| agent-teams | Equipes d'agents | Agents multiples, coordination |
+| long-running-tasks | Raisonnement complexe | Gestion des timeouts |
+| generate-object | Generation d'objets | Patterns de base et imbrication |
+| generate-object-constraints | Validation | Regex, plages, enums |
+| stream-object | UI temps reel | Mises a jour d'objets partiels |
+| structured-output-repro | Depannage | Repro fallback schema |
+| zod4-compatibility-test | Compatibilite Zod 4 | Schemas, validations, unions |
+| limitations | Vue d'ensemble contraintes | Fonctionnalites non supportees |
+
+## Parcours d'apprentissage
+
+1. **Debutants** : Commencer avec `basic-usage.ts` → `streaming.ts` → `conversation-history.ts`
+2. **Images et outils** : `images.ts` → `tool-streaming.ts` pour comprendre les entrees multimodales et les evenements d'outils
+3. **Logging** : `logging-default.ts` → `logging-verbose.ts` → `logging-custom-logger.ts` → `logging-disabled.ts`
+4. **Generation d'objets** : `generate-object.ts` → `generate-object-constraints.ts` → `stream-object.ts`
+5. **Avance** : `custom-config.ts` → `tool-management.ts` → `skills-management.ts` → `hooks-callbacks.ts` → `sdk-tools-callbacks.ts` → `long-running-tasks.ts`
+6. **Tests/Depannage** : Executer `integration-test.ts`, puis `structured-output-repro.ts` et `limitations.ts` si le comportement semble incorrect
+
+Pour plus de details, voir le [README principal](../../README.md).

package/docs/examples/abort-signal.ts

@@ -0,0 +1,125 @@
+import { generateText, streamText } from 'ai';
+import { claudeCode } from '../dist/index.js';
+// NOTE: Migrating to Claude Agent SDK:
+// - System prompt is not applied by default
+// - Filesystem settings (CLAUDE.md, settings.json) are not loaded by default
+// To restore old behavior, set:
+//   systemPrompt: { type: 'preset', preset: 'claude_code' }
+//   settingSources: ['user', 'project', 'local']
+
+/**
+ * Example: Request Cancellation with AbortController
+ *
+ * This example demonstrates how to cancel in-progress requests using AbortSignal.
+ * Useful for implementing timeouts, user cancellations, or cleaning up on unmount.
+ */
+
+// Suppress uncaught abort errors from child processes
+process.on('uncaughtException', (err: any) => {
+  if (err.code === 'ABORT_ERR') {
+    // Silently ignore abort errors - they're expected
+    return;
+  }
+  // Re-throw other errors
+  throw err;
+});
+
+async function main() {
+  console.log('🚀 Testing request cancellation with AbortController\n');
+
+  // Example 1: Cancel a non-streaming request after 2 seconds
+  console.log('1. Testing cancellation of generateText after 2 seconds...');
+  try {
+    const controller = new AbortController();
+
+    // Cancel after 2 seconds
+    const timeout = setTimeout(() => {
+      console.log('   ⏱️  Cancelling request...');
+      controller.abort();
+    }, 2000);
+
+    const { text } = await generateText({
+      model: claudeCode('opus'),
+      prompt:
+        'Write a very long detailed essay about the history of computing. Include at least 10 paragraphs.',
+      abortSignal: controller.signal,
+    });
+
+    clearTimeout(timeout);
+    console.log('   ✅ Completed:', text.slice(0, 100) + '...');
+  } catch (error: any) {
+    if (error.name === 'AbortError' || error.message?.includes('aborted')) {
+      console.log('   ✅ Request successfully cancelled');
+    } else {
+      console.error('   ❌ Error:', error.message);
+    }
+  }
+
+  console.log('\n2. Testing immediate cancellation (before request starts)...');
+  try {
+    const controller = new AbortController();
+
+    // Cancel immediately
+    controller.abort();
+
+    await generateText({
+      model: claudeCode('opus'),
+      prompt: 'This should not execute',
+      abortSignal: controller.signal,
+    });
+
+    console.log('   ❌ This should not be reached');
+  } catch (error: any) {
+    if (error.name === 'AbortError' || error.message?.includes('aborted')) {
+      console.log('   ✅ Request cancelled before execution');
+    } else {
+      console.error('   ❌ Error:', error.message);
+    }
+  }
+
+  console.log('\n3. Testing streaming cancellation after partial response...');
+  try {
+    const controller = new AbortController();
+    let charCount = 0;
+
+    const { textStream } = streamText({
+      model: claudeCode('opus'),
+      prompt: 'Count slowly from 1 to 20, explaining each number.',
+      abortSignal: controller.signal,
+    });
+
+    console.log('   Streaming response: ');
+    for await (const chunk of textStream) {
+      process.stdout.write(chunk);
+      charCount += chunk.length;
+
+      // Cancel after receiving 100 characters
+      if (charCount > 100) {
+        console.log('\n   ⏱️  Cancelling stream after', charCount, 'characters...');
+        controller.abort();
+        break;
+      }
+    }
+  } catch (error: any) {
+    if (error.name === 'AbortError' || error.message?.includes('aborted')) {
+      console.log('   ✅ Stream successfully cancelled');
+    } else {
+      console.error('   ❌ Error:', error.message);
+    }
+  }
+
+  console.log('\n✅ AbortSignal examples completed');
+  console.log('\nUse cases for AbortSignal:');
+  console.log('- User-initiated cancellations (e.g., "Stop generating" button)');
+  console.log('- Component unmount cleanup in React/Vue');
+  console.log('- Request timeouts');
+  console.log('- Rate limiting and request management');
+
+  console.log('\nNote: This example suppresses ABORT_ERR uncaught exceptions');
+  console.log('      which are expected when cancelling child processes.');
+
+  // Exit cleanly
+  process.exit(0);
+}
+
+main().catch(console.error);