@boostecom/provider 0.0.1

package/docs/content/best-practices.mdx

@@ -0,0 +1,624 @@
+---
+title: Best Practices
+description: Conseils et bonnes pratiques pour utiliser le provider Claude Code efficacement
+---
+
+# Best Practices
+
+Ce guide présente les meilleures pratiques pour utiliser le provider Claude Code de manière efficace, sécurisée et performante.
+
+## Choix du modèle
+
+### Adapter le modèle à la tâche
+
+```typescript
+// ✅ Haiku pour tâches simples et rapides
+const quickTask = claudeCode('haiku');
+await generateText({
+  model: quickTask,
+  prompt: 'Résume ce texte en une phrase',
+});
+
+// ✅ Sonnet pour usage général (recommandé)
+const balanced = claudeCode('sonnet');
+await generateText({
+  model: balanced,
+  prompt: 'Analyse ce code et suggère des améliorations',
+});
+
+// ✅ Opus pour tâches complexes uniquement
+const complex = claudeCode('opus');
+await generateText({
+  model: complex,
+  prompt: 'Conçois l\'architecture complète d\'un système distribué...',
+});
+```
+
+**Règle d'or** : Commencez par Haiku, passez à Sonnet si nécessaire, réservez Opus aux tâches vraiment complexes.
+
+## Gestion du contexte
+
+### Maintenir l'historique efficacement
+
+```typescript
+import type { CoreMessage } from 'ai';
+
+// ✅ Bon : Historique complet mais raisonnable
+const messages: CoreMessage[] = [];
+
+function addMessage(role: 'user' | 'assistant', content: string) {
+  messages.push({ role, content });
+  
+  // Limiter à 20 derniers messages pour éviter token overflow
+  if (messages.length > 20) {
+    messages.splice(0, messages.length - 20);
+  }
+}
+
+// ❌ Mauvais : Historique illimité
+const unlimitedHistory: CoreMessage[] = [];
+// Peut causer des erreurs de limite de tokens
+```
+
+### Résumé périodique pour conversations longues
+
+```typescript
+async function summarizeHistory(messages: CoreMessage[]) {
+  if (messages.length > 15) {
+    const { text } = await generateText({
+      model: claudeCode('haiku'), // Haiku suffisant pour résumé
+      prompt: `Résume cette conversation en quelques phrases clés:\n${
+        messages.map(m => `${m.role}: ${m.content}`).join('\n')
+      }`,
+    });
+    
+    // Remplacer l'historique par le résumé
+    return [
+      { role: 'assistant', content: `Résumé: ${text}` },
+      ...messages.slice(-5), // Garder les 5 derniers messages
+    ];
+  }
+  return messages;
+}
+```
+
+## Structured Outputs
+
+### Schémas simples et robustes
+
+```typescript
+import { z } from 'zod';
+
+// ✅ Bon : Schéma simple avec descriptions
+const goodSchema = z.object({
+  nom: z.string().min(1).max(100),
+  age: z.number().int().min(0).max(150),
+  email: z.string().describe('Email (ex: user@example.com)'),
+  role: z.enum(['admin', 'user', 'guest']),
+});
+
+// ❌ Mauvais : Contraintes complexes qui causent fallback
+const badSchema = z.object({
+  email: z.string().email(), // format constraint
+  url: z.string().url(),     // format constraint
+  password: z.string().regex(/^(?=.*[A-Z])(?=.*[0-9]).{8,}$/), // lookahead
+});
+
+// ✅ Solution : Valider côté client
+const simpleSchema = z.object({
+  email: z.string().describe('Email valide'),
+  url: z.string().describe('URL complète avec protocole'),
+  password: z.string().min(8).describe('8+ caractères, maj et chiffres'),
+});
+
+const result = await generateObject({ model, schema: simpleSchema, prompt });
+
+// Validation stricte côté client
+const emailValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(result.object.email);
+```
+
+### Décomposition pour schémas complexes
+
+```typescript
+// ❌ Mauvais : Un seul appel avec schéma énorme
+const hugeSchema = z.object({
+  user: z.object({ /* 20 champs */ }),
+  company: z.object({ /* 20 champs */ }),
+  settings: z.object({ /* 20 champs */ }),
+});
+
+// ✅ Bon : Plusieurs appels avec schémas ciblés
+const userSchema = z.object({ /* 10 champs essentiels */ });
+const companySchema = z.object({ /* 10 champs essentiels */ });
+
+const user = await generateObject({ model, schema: userSchema, prompt: '...' });
+const company = await generateObject({ model, schema: companySchema, prompt: '...' });
+
+const complete = { user: user.object, company: company.object };
+```
+
+## Sécurité
+
+### Contrôle des outils
+
+```typescript
+// ✅ Bon : Liste blanche explicite
+const safeModel = claudeCode('sonnet', {
+  allowedTools: ['Read', 'LS'], // Seulement lecture
+  disallowedTools: [
+    'Write',
+    'Edit',
+    'Bash(rm:*)',   // Bloquer rm
+    'Bash(sudo:*)', // Bloquer sudo
+  ],
+});
+
+// ❌ Risqué : Tous les outils sans restriction
+const riskyModel = claudeCode('sonnet', {
+  permissionMode: 'bypassPermissions',
+  allowDangerouslySkipPermissions: true,
+});
+```
+
+### Validation des entrées utilisateur
+
+```typescript
+import { z } from 'zod';
+
+// ✅ Bon : Validation avant envoi
+const inputSchema = z.object({
+  prompt: z.string().min(1).max(5000),
+  model: z.enum(['haiku', 'sonnet', 'opus']),
+});
+
+async function safeGenerate(userInput: unknown) {
+  // Valider l'entrée
+  const validated = inputSchema.safeParse(userInput);
+  
+  if (!validated.success) {
+    throw new Error('Entrée invalide');
+  }
+  
+  return await generateText({
+    model: claudeCode(validated.data.model),
+    prompt: validated.data.prompt,
+  });
+}
+
+// ❌ Mauvais : Accepter les entrées sans validation
+async function unsafeGenerate(userInput: any) {
+  return await generateText({
+    model: claudeCode(userInput.model), // Peut crasher
+    prompt: userInput.prompt,           // Peut être malicieux
+  });
+}
+```
+
+### Sandboxing en production
+
+```typescript
+// ✅ Bon : Environnement isolé
+const productionModel = claudeCode('sonnet', {
+  sandbox: { enabled: true },
+  cwd: '/safe/isolated/directory',
+  allowedTools: ['Read'], // Minimal
+  persistSession: false,  // Pas de persistence
+});
+
+// ❌ Risqué : Accès complet au système
+const riskyModel = claudeCode('sonnet', {
+  cwd: '/',
+  allowedTools: ['Bash'], // Accès shell illimité
+});
+```
+
+## Performance
+
+### Streaming pour grandes réponses
+
+```typescript
+// ✅ Bon : Streaming pour réponses longues
+const result = streamText({
+  model: claudeCode('sonnet'),
+  prompt: 'Écris un article de 2000 mots...',
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk); // Affichage progressif
+  // Chunk garbage collected après usage
+}
+
+// ❌ Mauvais : Attendre la réponse complète
+const result = await generateText({
+  model: claudeCode('sonnet'),
+  prompt: 'Écris un article de 2000 mots...',
+});
+console.log(result.text); // Tout en mémoire
+```
+
+### Parallélisation des tâches indépendantes
+
+```typescript
+// ✅ Bon : Exécution parallèle
+const [summary, keywords, sentiment] = await Promise.all([
+  generateText({ model: claudeCode('haiku'), prompt: 'Résume: ...' }),
+  generateText({ model: claudeCode('haiku'), prompt: 'Mots-clés: ...' }),
+  generateText({ model: claudeCode('haiku'), prompt: 'Sentiment: ...' }),
+]);
+
+// ❌ Mauvais : Exécution séquentielle
+const summary = await generateText({ model, prompt: 'Résume: ...' });
+const keywords = await generateText({ model, prompt: 'Mots-clés: ...' });
+const sentiment = await generateText({ model, prompt: 'Sentiment: ...' });
+```
+
+### Cache des résultats fréquents
+
+```typescript
+import NodeCache from 'node-cache';
+
+const cache = new NodeCache({ stdTTL: 3600 }); // 1 heure
+
+async function cachedGenerate(prompt: string) {
+  // Vérifier le cache
+  const cached = cache.get(prompt);
+  if (cached) {
+    return cached;
+  }
+  
+  // Générer si pas en cache
+  const { text } = await generateText({
+    model: claudeCode('haiku'),
+    prompt,
+  });
+  
+  // Mettre en cache
+  cache.set(prompt, text);
+  return text;
+}
+```
+
+## Gestion d'erreurs
+
+### Pattern robuste avec retry
+
+```typescript
+async function generateWithRetry(
+  prompt: string,
+  maxRetries = 3
+): Promise<string> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const { text } = await generateText({
+        model: claudeCode('sonnet'),
+        prompt,
+      });
+      return text;
+    } catch (error: any) {
+      // Dernière tentative
+      if (i === maxRetries - 1) throw error;
+      
+      // Erreur réseau/temporaire
+      if (error.code === 'ECONNRESET' || error.code === 'ETIMEDOUT') {
+        console.log(`Tentative ${i + 1} échouée, retry...`);
+        await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+        continue;
+      }
+      
+      // Erreur non recoverable
+      throw error;
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+```
+
+### Fallback sur modèle plus simple
+
+```typescript
+async function generateWithFallback(prompt: string) {
+  try {
+    // Essayer Opus
+    return await generateText({
+      model: claudeCode('opus'),
+      prompt,
+    });
+  } catch (error: any) {
+    if (error.message?.includes('rate limit')) {
+      // Fallback sur Sonnet si rate limited
+      console.warn('Rate limited, fallback sur Sonnet');
+      return await generateText({
+        model: claudeCode('sonnet'),
+        prompt,
+      });
+    }
+    throw error;
+  }
+}
+```
+
+### Timeout approprié
+
+```typescript
+async function generateWithTimeout(prompt: string, timeoutMs = 60000) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  
+  try {
+    const result = await generateText({
+      model: claudeCode('sonnet'),
+      prompt,
+      abortSignal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+    return result;
+  } catch (error: any) {
+    if (error.name === 'AbortError') {
+      throw new Error(`Timeout après ${timeoutMs}ms`);
+    }
+    throw error;
+  }
+}
+```
+
+## Logging et monitoring
+
+### Logging structuré
+
+```typescript
+import type { Logger } from '@boostecom/provider';
+
+const structuredLogger: Logger = {
+  debug: (msg) => logger.debug({ component: 'claude-code', message: msg }),
+  info: (msg) => logger.info({ component: 'claude-code', message: msg }),
+  warn: (msg) => logger.warn({ component: 'claude-code', message: msg }),
+  error: (msg) => {
+    logger.error({ component: 'claude-code', message: msg });
+    // Alerter si critique
+    if (msg.includes('authentication')) {
+      sendAlert('Claude Code auth failed');
+    }
+  },
+};
+
+const model = claudeCode('sonnet', {
+  verbose: true,
+  logger: structuredLogger,
+});
+```
+
+### Monitoring des coûts
+
+```typescript
+let totalCost = 0;
+let totalTokens = 0;
+
+async function monitoredGenerate(prompt: string) {
+  const result = await generateText({
+    model: claudeCode('sonnet'),
+    prompt,
+  });
+  
+  // Tracker usage
+  totalTokens += result.usage.totalTokens;
+  
+  // Estimer coût (exemple: $0.003/1K tokens)
+  const cost = (result.usage.totalTokens / 1000) * 0.003;
+  totalCost += cost;
+  
+  // Logger
+  console.log({
+    tokens: result.usage.totalTokens,
+    cost: cost.toFixed(4),
+    totalCost: totalCost.toFixed(4),
+    totalTokens,
+  });
+  
+  // Alerte si dépassement budget
+  if (totalCost > 10) {
+    throw new Error('Budget journalier dépassé');
+  }
+  
+  return result;
+}
+```
+
+### Tracking des performances
+
+```typescript
+async function trackedGenerate(prompt: string) {
+  const startTime = Date.now();
+  
+  try {
+    const result = await generateText({
+      model: claudeCode('sonnet'),
+      prompt,
+    });
+    
+    const duration = Date.now() - startTime;
+    
+    // Envoyer métriques
+    metrics.record({
+      metric: 'claude_generate_duration',
+      value: duration,
+      tags: { model: 'sonnet', status: 'success' },
+    });
+    
+    return result;
+  } catch (error: any) {
+    const duration = Date.now() - startTime;
+    
+    metrics.record({
+      metric: 'claude_generate_duration',
+      value: duration,
+      tags: { model: 'sonnet', status: 'error' },
+    });
+    
+    throw error;
+  }
+}
+```
+
+## Testing
+
+### Tests unitaires avec mocking
+
+```typescript
+import { vi, describe, it, expect } from 'vitest';
+
+// Mock du provider
+vi.mock('@boostecom/provider', () => ({
+  claudeCode: vi.fn(() => ({
+    provider: 'claude-code',
+    modelId: 'sonnet',
+  })),
+}));
+
+describe('Service avec Claude', () => {
+  it('génère une réponse', async () => {
+    const mockGenerateText = vi.fn().mockResolvedValue({
+      text: 'Réponse mockée',
+      usage: { totalTokens: 100 },
+    });
+    
+    // Votre logique de test
+    const result = await mockGenerateText({
+      model: claudeCode('sonnet'),
+      prompt: 'Test',
+    });
+    
+    expect(result.text).toBe('Réponse mockée');
+  });
+});
+```
+
+### Tests d'intégration
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { generateText } from 'ai';
+import { claudeCode } from '@boostecom/provider';
+
+describe('Intégration Claude Code', () => {
+  it('génère du texte réel', async () => {
+    const { text } = await generateText({
+      model: claudeCode('haiku'), // Haiku pour coût/vitesse
+      prompt: 'Dis simplement "OK"',
+    });
+    
+    expect(text).toBeTruthy();
+    expect(text.toLowerCase()).toContain('ok');
+  }, 30000); // Timeout 30s
+  
+  it('génère un objet structuré', async () => {
+    const { object } = await generateObject({
+      model: claudeCode('haiku'),
+      schema: z.object({
+        nombre: z.number(),
+      }),
+      prompt: 'Génère un objet avec nombre = 42',
+    });
+    
+    expect(object.nombre).toBe(42);
+  }, 30000);
+});
+```
+
+## Production
+
+### Configuration d'environnement
+
+```typescript
+// config.ts
+const isProd = process.env.NODE_ENV === 'production';
+
+export const claudeConfig = {
+  model: isProd ? 'sonnet' : 'haiku', // Haiku en dev
+  verbose: !isProd, // Logs seulement en dev
+  persistSession: !isProd, // Pas de persistence en prod
+  sandbox: isProd ? { enabled: true } : undefined,
+  maxTurns: isProd ? 5 : 10, // Limiter en prod
+  allowedTools: isProd 
+    ? ['Read', 'LS'] // Minimal en prod
+    : ['Read', 'Write', 'Bash'], // Plus permissif en dev
+};
+
+// Utilisation
+const model = claudeCode('sonnet', claudeConfig);
+```
+
+### Rate limiting
+
+```typescript
+import Bottleneck from 'bottleneck';
+
+// Limiter à 10 requêtes par minute
+const limiter = new Bottleneck({
+  maxConcurrent: 1,
+  minTime: 6000, // 6s entre requêtes
+});
+
+async function rateLimitedGenerate(prompt: string) {
+  return limiter.schedule(async () => {
+    return await generateText({
+      model: claudeCode('sonnet'),
+      prompt,
+    });
+  });
+}
+```
+
+### Health checks
+
+```typescript
+import express from 'express';
+
+const app = express();
+
+app.get('/health', async (req, res) => {
+  try {
+    // Test simple avec timeout court
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+    
+    await generateText({
+      model: claudeCode('haiku'),
+      prompt: 'Dis OK',
+      abortSignal: controller.signal,
+    });
+    
+    clearTimeout(timeoutId);
+    res.json({ status: 'healthy', claude: 'ok' });
+  } catch (error: any) {
+    res.status(503).json({ 
+      status: 'unhealthy', 
+      claude: 'error',
+      message: error.message,
+    });
+  }
+});
+```
+
+## Ressources
+
+- [Guide d'utilisation](/docs/guide) - Patterns de base
+- [API Reference](/docs/api) - Documentation complète
+- [Exemples](/docs/examples) - Cas d'usage pratiques
+- [Dépannage](/docs/troubleshooting) - Solutions aux problèmes
+
+## Checklist finale
+
+Avant de déployer en production :
+
+- [ ] Modèle adapté à la tâche (Haiku pour simple, Sonnet pour général)
+- [ ] Outils restreints au minimum nécessaire
+- [ ] Validation des entrées utilisateur
+- [ ] Gestion d'erreurs avec retry
+- [ ] Timeouts appropriés configurés
+- [ ] Logging structuré en place
+- [ ] Monitoring des coûts activé
+- [ ] Tests d'intégration passants
+- [ ] Rate limiting configuré
+- [ ] Health checks implémentés
+- [ ] Secrets sécurisés (pas de hardcoding)
+- [ ] Documentation à jour