feat: complete agentic audit roadmap — retry, KB generate, real costs, traceId, rate-limit

- ai-sdk: exponential backoff retry (3 attempts, 1s→2s) in callWithFailover; skips 4xx and QuotaExceededError
- api/whatsapp: traceId (crypto.randomUUID) propagated to worker bridge via x-trace-id header
- api/whatsapp: route-level rate limit 500/min on POST /webhook, returns 200 on rejection
- api/organizations: POST /:id/kb/generate — GPT-4o-mini JSON mode generates FAQ pairs, embeds via IndexingService
- api/indexing-service: new service batching OpenAI text-embedding-3-small + pgvector INSERT
- admin/AnalyticsPage: real cost from UsageEvent aggregate + byFeature breakdown table
- admin/KnowledgeBasePage: KB auto-generation panel (description textarea, generate button, FAQ preview)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

apps/admin/src/pages/AnalyticsPage.tsx

@@ -135,11 +135,11 @@ export default function AnalyticsPage() {
           color="text-amber-600"
           bg="bg-amber-50"
         />
-        <StatCard 
-          title={t('dashboard.stats.ai_cost')} 
-          value={`$${usage?.costs?.estimatedUsd?.toFixed(2) || '0.00'}`} 
-          icon={<BrainCircuit className="w-5 h-5" />} 
-          trend="Optimisé"
+        <StatCard
+          title={t('dashboard.stats.ai_cost')}
+          value={`$${(usage?.costs?.totalUsd ?? 0).toFixed(4)}`}
+          icon={<BrainCircuit className="w-5 h-5" />}
+          trend={`${((usage?.costs?.totalTokens ?? 0) / 1000).toFixed(1)}k tokens`}
           color="text-purple-600"
           bg="bg-purple-50"
         />
@@ -226,6 +226,55 @@ export default function AnalyticsPage() {
         </div>
       </div>
 
+      {/* ── AI Cost Breakdown ─────────────────────────────────────────── */}
+      {usage?.costs?.byFeature?.length > 0 && (
+        <div className="bg-white rounded-3xl border border-slate-100 shadow-sm p-8">
+          <div className="flex items-center gap-3 mb-6">
+            <div className="p-2.5 bg-purple-50 rounded-xl">
+              <BrainCircuit className="w-5 h-5 text-purple-600" />
+            </div>
+            <div>
+              <h2 className="font-bold text-slate-800">Coût IA par fonctionnalité</h2>
+              <p className="text-xs text-slate-400">Données réelles — source : UsageEvent</p>
+            </div>
+          </div>
+          <div className="overflow-x-auto">
+            <table className="w-full text-sm">
+              <thead>
+                <tr className="text-left text-xs text-slate-400 uppercase tracking-wider border-b border-slate-100">
+                  <th className="pb-3 font-semibold">Fonctionnalité</th>
+                  <th className="pb-3 font-semibold text-right">Appels</th>
+                  <th className="pb-3 font-semibold text-right">Tokens in</th>
+                  <th className="pb-3 font-semibold text-right">Tokens out</th>
+                  <th className="pb-3 font-semibold text-right">Coût (USD)</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-slate-50">
+                {(usage.costs.byFeature as Array<{ feature: string; calls: number; tokensIn: number; tokensOut: number; costUsd: number }>)
+                  .sort((a, b) => b.costUsd - a.costUsd)
+                  .map((row) => (
+                    <tr key={row.feature} className="hover:bg-slate-50 transition">
+                      <td className="py-3 font-medium text-slate-700">
+                        <span className="px-2 py-0.5 bg-purple-50 text-purple-700 rounded-full text-[11px] font-mono">{row.feature}</span>
+                      </td>
+                      <td className="py-3 text-right text-slate-600">{row.calls.toLocaleString()}</td>
+                      <td className="py-3 text-right text-slate-500">{row.tokensIn.toLocaleString()}</td>
+                      <td className="py-3 text-right text-slate-500">{row.tokensOut.toLocaleString()}</td>
+                      <td className="py-3 text-right font-bold text-slate-800">${row.costUsd.toFixed(4)}</td>
+                    </tr>
+                  ))}
+              </tbody>
+              <tfoot className="border-t-2 border-slate-200">
+                <tr>
+                  <td className="pt-3 font-bold text-slate-800" colSpan={4}>Total</td>
+                  <td className="pt-3 text-right font-bold text-purple-700">${(usage.costs.totalUsd as number).toFixed(4)}</td>
+                </tr>
+              </tfoot>
+            </table>
+          </div>
+        </div>
+      )}
+
       {/* ── Text-to-SQL Search ─────────────────────────────────────────── */}
       <div className="bg-white rounded-3xl border border-slate-100 shadow-sm p-8">
         <div className="flex items-center gap-3 mb-6">

apps/admin/src/pages/KnowledgeBasePage.tsx

@@ -1,6 +1,6 @@
 import { useState, useEffect } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Database, Trash2, RefreshCw, Search, ChevronLeft, ChevronRight, Loader2, FileText } from 'lucide-react';
+import { Database, Trash2, RefreshCw, Search, ChevronLeft, ChevronRight, Loader2, FileText, Wand2, CheckCircle2 } from 'lucide-react';
 import { api } from '../lib/api';
 import { useAuth } from '../lib/auth';
 import { useTenant } from '../lib/tenant';
@@ -34,6 +34,9 @@ export default function KnowledgeBasePage() {
     const [search, setSearch] = useState('');
     const [deletingId, setDeletingId] = useState<string | null>(null);
     const [reindexing, setReindexing] = useState(false);
+    const [genDescription, setGenDescription] = useState('');
+    const [generating, setGenerating] = useState(false);
+    const [genResult, setGenResult] = useState<{ faqCount: number; chunksIndexed: number; preview: Array<{ question: string; answer: string }> } | null>(null);
 
     const fetchEntries = async (p = page) => {
         if (!token || !selectedOrgId) return;
@@ -89,6 +92,28 @@ export default function KnowledgeBasePage() {
         }
     };
 
+    const handleGenerate = async () => {
+        if (!token || !selectedOrgId || !genDescription.trim()) return;
+        setGenerating(true);
+        setGenResult(null);
+        try {
+            const res = await api.post(
+                `/v1/organizations/${selectedOrgId}/kb/generate`,
+                { description: genDescription },
+                token
+            );
+            setGenResult(res);
+            toast.success(`${res.faqCount} Q&A générées et indexées`);
+            await fetchEntries(1);
+            setPage(1);
+        } catch (err: any) {
+            logError('[KB] Generate failed:', err);
+            toast.error(err?.message ?? 'Échec de la génération');
+        } finally {
+            setGenerating(false);
+        }
+    };
+
     const handlePageChange = (newPage: number) => {
         setPage(newPage);
         fetchEntries(newPage);
@@ -124,6 +149,46 @@ export default function KnowledgeBasePage() {
                 </button>
             </div>
 
+            {/* KB Auto-Generation Panel */}
+            <div className="bg-white rounded-2xl border border-slate-100 p-5 mb-6">
+                <div className="flex items-center gap-2 mb-3">
+                    <Wand2 className="w-4 h-4 text-violet-500" />
+                    <h2 className="text-sm font-semibold text-slate-700">Générer depuis une description</h2>
+                </div>
+                <textarea
+                    value={genDescription}
+                    onChange={e => setGenDescription(e.target.value)}
+                    placeholder="Décrivez votre activité, vos produits ou services… L'IA génèrera automatiquement une FAQ et l'indexera dans la base de connaissances."
+                    rows={3}
+                    className="w-full px-3 py-2 border border-slate-200 rounded-xl text-sm outline-none focus:ring-2 focus:ring-violet-400 resize-none mb-3"
+                />
+                <button
+                    onClick={handleGenerate}
+                    disabled={generating || !genDescription.trim()}
+                    className="flex items-center gap-2 px-4 py-2 bg-violet-600 text-white rounded-xl text-sm font-medium hover:bg-violet-700 transition disabled:opacity-50"
+                >
+                    {generating ? <Loader2 className="w-4 h-4 animate-spin" /> : <Wand2 className="w-4 h-4" />}
+                    {generating ? 'Génération en cours…' : 'Générer'}
+                </button>
+
+                {genResult && (
+                    <div className="mt-4 pt-4 border-t border-slate-100">
+                        <p className="text-sm font-medium text-slate-700 mb-3">
+                            <CheckCircle2 className="inline w-4 h-4 text-green-500 mr-1" />
+                            {genResult.faqCount} Q&R générées · {genResult.chunksIndexed} chunks indexés
+                        </p>
+                        <div className="space-y-2">
+                            {genResult.preview.slice(0, 3).map((qa, i) => (
+                                <div key={i} className="bg-slate-50 rounded-xl p-3 text-sm">
+                                    <p className="font-medium text-slate-700 mb-1">Q: {qa.question}</p>
+                                    <p className="text-slate-500">R: {qa.answer}</p>
+                                </div>
+                            ))}
+                        </div>
+                    </div>
+                )}
+            </div>
+
             <div className="relative mb-4">
                 <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-slate-400" />
                 <input

apps/api/src/routes/organizations.ts

@@ -259,6 +259,65 @@ export async function organizationRoutes(fastify: FastifyInstance) {
         return { ok: true };
     });
 
+    /**
+     * POST /v1/organizations/:id/kb/generate
+     * Admin describes their business → GPT generates FAQ pairs → indexed in KB automatically.
+     */
+    fastify.post<P>('/:id/kb/generate', async (req, reply) => {
+        const id = await resolveOrgId(req.params.id);
+        if (!id) return reply.code(404).send({ error: 'Organization not found' });
+
+        const schema = z.object({ description: z.string().min(20).max(2000) });
+        const body = schema.safeParse(req.body);
+        if (!body.success) return reply.code(400).send({ error: body.error.flatten() });
+
+        const { description } = body.data;
+
+        // Generate FAQ pairs via GPT-4o-mini
+        const OpenAI = (await import('openai')).default;
+        const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, timeout: 25_000 });
+
+        let faqs: Array<{ question: string; answer: string }>;
+        try {
+            const completion = await openai.chat.completions.create({
+                model: 'gpt-4o-mini',
+                temperature: 0.3,
+                response_format: { type: 'json_object' },
+                messages: [
+                    {
+                        role: 'system',
+                        content: 'Tu es un expert en création de bases de connaissance pour chatbots WhatsApp. Génère des paires question/réponse précises et utiles basées sur la description métier fournie. Réponds en JSON avec une clé "faqs" contenant un tableau d\'objets {question, answer}.'
+                    },
+                    {
+                        role: 'user',
+                        content: `Génère 10 à 15 paires Q&A pour ce business :\n\n${description}\n\nCover : horaires, produits/services, prix, localisation, livraison, contact, politique de retour, FAQ courantes. Réponds en JSON.`
+                    }
+                ]
+            });
+
+            const raw = JSON.parse(completion.choices[0]?.message?.content ?? '{}');
+            faqs = Array.isArray(raw.faqs) ? raw.faqs : [];
+            if (faqs.length === 0) throw new Error('No FAQs generated');
+        } catch (err) {
+            logger.error({ err }, '[KB-GENERATE] FAQ generation failed');
+            return reply.code(503).send({ error: 'AI service failed to generate FAQ' });
+        }
+
+        // Index each FAQ as a separate KB chunk
+        const { IndexingService } = await import('../services/indexing-service');
+        const chunks = faqs.map((faq) => `Q: ${faq.question}\nR: ${faq.answer}`);
+        const indexed = await IndexingService.indexTextChunks(id, chunks, { source: 'auto-generated-faq' });
+
+        auditService.log({
+            action: 'KB_AUTO_GENERATED',
+            actorId: req.user?.id,
+            resourceId: id,
+            details: { faqCount: faqs.length, chunksIndexed: indexed },
+        });
+
+        return { ok: true, faqCount: faqs.length, chunksIndexed: indexed, preview: faqs.slice(0, 3) };
+    });
+
     fastify.get<P & Q<{ page?: string; limit?: string }>>('/:id/kb', async (req, reply) => {
         const id = await resolveOrgId(req.params.id);
         if (!id) return reply.code(404).send({ error: 'Organization not found' });

apps/api/src/routes/whatsapp.ts

@@ -64,7 +64,16 @@ export async function whatsappRoutes(fastify: FastifyInstance) {
      * POST /v1/whatsapp/webhook
      * Main entry point for incoming messages and events
      */
-    fastify.post('/webhook', async (request, reply) => {
+    fastify.post('/webhook', {
+        config: {
+            rateLimit: {
+                max: 500,       // Meta sends bursts for large groups
+                timeWindow: '1 minute',
+                // On rejection, still return 200 so Meta doesn't disable the webhook
+                errorResponseBuilder: () => ({ statusCode: 200, error: 'Too Many Requests' })
+            }
+        }
+    }, async (request, reply) => {
         // Verify X-Hub-Signature-256 — fail-open if WHATSAPP_APP_SECRET is not configured
         const APP_SECRET = process.env.WHATSAPP_APP_SECRET;
         if (APP_SECRET) {

apps/api/src/services/indexing-service.ts

@@ -0,0 +1,65 @@
+import { prisma } from './prisma';
+import { Prisma } from '@repo/database';
+import { logger } from '../logger';
+import { randomUUID } from 'crypto';
+
+export class IndexingService {
+    /**
+     * Embeds an array of text chunks and inserts them into KnowledgeBaseEntry.
+     * Returns the number of chunks indexed.
+     */
+    static async indexTextChunks(
+        organizationId: string,
+        chunks: string[],
+        metadata?: Record<string, unknown>
+    ): Promise<number> {
+        if (chunks.length === 0) return 0;
+
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) throw new Error('OPENAI_API_KEY not configured');
+
+        // Generate embeddings in batches of 100 (OpenAI limit)
+        const BATCH = 100;
+        let indexed = 0;
+
+        for (let i = 0; i < chunks.length; i += BATCH) {
+            const batch = chunks.slice(i, i + BATCH);
+
+            const response = await fetch('https://api.openai.com/v1/embeddings', {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({ input: batch, model: 'text-embedding-3-small' }),
+            });
+
+            if (!response.ok) {
+                const err = await response.text();
+                throw new Error(`OpenAI embeddings failed: ${err}`);
+            }
+
+            const data = await response.json() as { data: Array<{ embedding: number[] }> };
+            const embeddings = data.data.map((d) => d.embedding);
+
+            for (let j = 0; j < batch.length; j++) {
+                const content = batch[j];
+                const embedding = embeddings[j];
+                const vecRaw = Prisma.raw(`'[${embedding.join(',')}]'::vector`);
+
+                await prisma.$executeRaw`
+                    INSERT INTO "KnowledgeBaseEntry" ("id", "organizationId", "content", "embedding", "metadata", "createdAt")
+                    VALUES (
+                        ${randomUUID()},
+                        ${organizationId},
+                        ${content},
+                        ${vecRaw},
+                        ${JSON.stringify(metadata ?? {})}::jsonb,
+                        NOW()
+                    )
+                `;
+                indexed++;
+            }
+        }
+
+        logger.info({ organizationId, indexed }, '[INDEXING-SERVICE] Text chunks indexed');
+        return indexed;
+    }
+}

packages/ai-sdk/src/index.ts

@@ -137,6 +137,31 @@ export class AIService {
         return tenantRegistry.getProvidersFor(capability);
     }
 
+    private static async withRetry<T>(
+        fn: () => Promise<T>,
+        maxAttempts = 3,
+        baseDelayMs = 1000
+    ): Promise<T> {
+        let lastErr: unknown;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                return await fn();
+            } catch (err: any) {
+                lastErr = err;
+                // Don't retry quota errors or client errors — fail immediately to the next provider
+                if (err?.name === 'QuotaExceededError' || (err?.status >= 400 && err?.status < 500 && err?.status !== 429)) {
+                    throw err;
+                }
+                if (attempt < maxAttempts - 1) {
+                    const delay = baseDelayMs * Math.pow(2, attempt);
+                    logger.warn(`[AI_RETRY] Transient error on attempt ${attempt + 1}/${maxAttempts} — retrying in ${delay}ms: ${err?.message}`);
+                    await new Promise(r => setTimeout(r, delay));
+                }
+            }
+        }
+        throw lastErr;
+    }
+
     private async callWithFailover<T>(
         prompt: string,
         schema: z.ZodSchema<T>,
@@ -149,7 +174,9 @@ export class AIService {
 
         for (const provider of providers) {
             try {
-                const { data, usage } = await provider.instance.generateStructuredData(prompt, schema, temperature, imageUrl);
+                const { data, usage } = await AIService.withRetry(
+                    () => provider.instance.generateStructuredData(prompt, schema, temperature, imageUrl)
+                );
                 logger.info(`${provider.name} used successfully for Org: ${organizationId || 'global'}.`);
                 return { data, source: provider.name, usage };
             } catch (err) {