feat: CSV export, monthly report, and quota alert plan filter

- BillingPage: add "CSV" download button that exports all wallet
transactions (date, type, description, amount, balance) as UTF-8 CSV
- scheduler.ts: add startMonthlyReportScheduler() — cron on 1st of month
07:30 UTC; sends per-org recap of AI calls, WhatsApp messages, top-3
features, credits recharged/spent, and current balance
- index.ts: register startMonthlyReportScheduler() alongside existing crons
- usage-tracker.ts: quota alert (85% threshold) now only fires for GROWTH,
SCALE, and ENTERPRISE plans; STARTER alerts were high-noise / low-value

apps/admin/src/pages/BillingPage.tsx

@@ -1,5 +1,5 @@
 import { useState, useEffect, useRef } from 'react';
-import { Brain, MessageCircle, TrendingUp, Send, Loader2, AlertCircle, Zap, X, Flame, HelpCircle } from 'lucide-react';
+import { Brain, MessageCircle, TrendingUp, Send, Loader2, AlertCircle, Zap, X, Flame, HelpCircle, Download } from 'lucide-react';
 import { api } from '@/lib/api';
 import { useAuth } from '@/lib/auth';
 import { useTenant } from '@/lib/tenant';
@@ -262,6 +262,28 @@ export default function BillingPage() {
         DEBIT_BROADCAST: '📣 Campagne',
     };
 
+    function downloadTransactionsCSV() {
+        if (!wallet?.transactions.length) return;
+        const rows = [
+            ['Date', 'Type', 'Description', 'Montant (crédits)', 'Solde après'],
+            ...wallet.transactions.map(tx => [
+                new Date(tx.createdAt).toLocaleString('fr-FR'),
+                TX_LABELS[tx.type] ?? tx.type,
+                tx.description ?? '',
+                tx.amount.toString(),
+                tx.balanceAfter >= 0 ? tx.balanceAfter.toString() : '',
+            ]),
+        ];
+        const csv = rows.map(r => r.map(cell => `"${String(cell).replace(/"/g, '""')}"`).join(',')).join('\n');
+        const blob = new Blob(['' + csv], { type: 'text/csv;charset=utf-8;' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = `transactions-${new Date().toISOString().slice(0, 10)}.csv`;
+        a.click();
+        URL.revokeObjectURL(url);
+    }
+
     return (
         <div className="p-6 max-w-5xl mx-auto space-y-6">
             {showRecharge && <RechargeModal onClose={() => setShowRecharge(false)} />}
@@ -463,9 +485,18 @@ export default function BillingPage() {
             {/* Historique des transactions — simplifié */}
             {wallet && wallet.transactions.length > 0 && (
                 <div className="bg-white rounded-2xl border border-slate-200 shadow-sm overflow-hidden">
-                    <div className="px-6 py-4 border-b border-slate-100">
-                        <h2 className="text-sm font-semibold text-slate-700">Derniers mouvements de crédits</h2>
-                        <p className="text-xs text-slate-400 mt-0.5">Les 20 dernières opérations sur votre solde</p>
+                    <div className="px-6 py-4 border-b border-slate-100 flex items-center justify-between">
+                        <div>
+                            <h2 className="text-sm font-semibold text-slate-700">Derniers mouvements de crédits</h2>
+                            <p className="text-xs text-slate-400 mt-0.5">Les 20 dernières opérations sur votre solde</p>
+                        </div>
+                        <button
+                            onClick={downloadTransactionsCSV}
+                            className="flex items-center gap-1.5 text-xs text-slate-500 hover:text-indigo-600 hover:bg-indigo-50 px-3 py-1.5 rounded-lg transition-colors border border-slate-200 hover:border-indigo-200"
+                        >
+                            <Download className="w-3.5 h-3.5" />
+                            CSV
+                        </button>
                     </div>
                     <div className="divide-y divide-slate-50">
                         {wallet.transactions.filter(tx => !tx.byok).map(tx => {

apps/whatsapp-worker/src/index.ts

@@ -258,11 +258,12 @@ const start = async () => {
         logger.info(`🚀 WhatsApp Worker + Bridge listening on port ${PORT}`);
         
         // Start the daily cron scheduler + token expiry monitor
-        const { startDailyScheduler, startTokenExpiryMonitor, startWalletAlertMonitor, startWeeklyReportScheduler, startPedagogyAdvisor } = await import('./scheduler');
+        const { startDailyScheduler, startTokenExpiryMonitor, startWalletAlertMonitor, startWeeklyReportScheduler, startMonthlyReportScheduler, startPedagogyAdvisor } = await import('./scheduler');
         startDailyScheduler();
         startTokenExpiryMonitor();
         startWalletAlertMonitor();
         startWeeklyReportScheduler();
+        startMonthlyReportScheduler();
         startPedagogyAdvisor();
     } catch (err) {
         logger.error('Failed to start worker server:', err);

apps/whatsapp-worker/src/scheduler.ts

@@ -436,3 +436,115 @@ async function analyzeCohort(organizationId: string, orgName: string) {
         }).catch((e: unknown) => logger.error({ e }, '[PEDAGOGY-ADVISOR] Email failed'));
     }
 }
+
+/**
+ * Monthly report — runs on the 1st of each month at 07:30 UTC.
+ * Summarizes the previous month's AI usage, WhatsApp volume, and wallet spend
+ * for every active org, then emails the admin.
+ */
+export function startMonthlyReportScheduler() {
+    // 1st of every month at 07:30 UTC
+    cron.schedule('30 7 1 * *', async () => {
+        logger.info('[MONTHLY-REPORT] Generating monthly reports...');
+        try {
+            const now = new Date();
+            const startOfLastMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
+            const startOfThisMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+            const monthLabel = startOfLastMonth.toLocaleDateString('fr-FR', { month: 'long', year: 'numeric' });
+
+            const orgs = await prisma.organization.findMany({
+                where: { subscriptionStatus: 'ACTIVE' },
+                select: { id: true, name: true, walletBalance: true, aiCreditsUsed: true, aiCreditsLimit: true, subscriptionPlan: true },
+            });
+
+            for (const org of orgs) {
+                const admin = await findOrgAdminEmail(org.id);
+                if (!admin) continue;
+
+                const [usage, byFeature, topups, debits, whatsappCount] = await Promise.all([
+                    prisma.usageEvent.aggregate({
+                        where: { organizationId: org.id, createdAt: { gte: startOfLastMonth, lt: startOfThisMonth }, type: { not: 'WHATSAPP_SENT' } },
+                        _sum: { costUsd: true, tokensIn: true, tokensOut: true },
+                        _count: { id: true },
+                    }),
+                    prisma.usageEvent.groupBy({
+                        by: ['feature'],
+                        where: { organizationId: org.id, createdAt: { gte: startOfLastMonth, lt: startOfThisMonth }, type: { not: 'WHATSAPP_SENT' } },
+                        _count: { id: true },
+                        orderBy: { _count: { id: 'desc' } },
+                        take: 3,
+                    }),
+                    prisma.walletTransaction.aggregate({
+                        where: { organizationId: org.id, createdAt: { gte: startOfLastMonth, lt: startOfThisMonth }, amount: { gt: 0 } },
+                        _sum: { amount: true },
+                    }),
+                    prisma.walletTransaction.aggregate({
+                        where: { organizationId: org.id, createdAt: { gte: startOfLastMonth, lt: startOfThisMonth }, amount: { lt: 0 } },
+                        _sum: { amount: true },
+                    }),
+                    prisma.usageEvent.count({
+                        where: { organizationId: org.id, createdAt: { gte: startOfLastMonth, lt: startOfThisMonth }, type: 'WHATSAPP_SENT' },
+                    }),
+                ]);
+
+                const aiCalls   = usage._count.id;
+                const costFcfa  = Math.round((usage._sum.costUsd ?? 0) * 600);
+                const credited  = topups._sum.amount ?? 0;
+                const spent     = Math.abs(debits._sum.amount ?? 0);
+                const topFeats  = byFeature.map(f => `${FEATURE_LABELS[f.feature] ?? f.feature} (${f._count.id})`).join(', ') || 'N/A';
+
+                if (aiCalls === 0 && whatsappCount === 0) continue; // Skip orgs with zero activity
+
+                await EmailService.sendEmail({
+                    to: admin.email,
+                    subject: `📅 Rapport mensuel Xamlé — ${org.name} — ${monthLabel}`,
+                    htmlContent: `
+                        <div style="font-family:sans-serif;max-width:600px;margin:auto;padding:24px;border:1px solid #e2e8f0;border-radius:12px;">
+                            <h2 style="color:#1e293b;margin-bottom:4px;">📅 Rapport mensuel — ${monthLabel}</h2>
+                            <p style="color:#64748b;margin-top:0;">${org.name} · Plan ${org.subscriptionPlan ?? 'STARTER'}</p>
+                            <table style="width:100%;border-collapse:collapse;margin:20px 0;font-size:0.95rem;">
+                                <tr style="background:#f8fafc;">
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;">Appels IA</td>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;font-weight:600;">${aiCalls.toLocaleString('fr-FR')}</td>
+                                </tr>
+                                <tr>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;">Messages WhatsApp envoyés</td>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;font-weight:600;">${whatsappCount.toLocaleString('fr-FR')}</td>
+                                </tr>
+                                <tr style="background:#f8fafc;">
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;">Fonctionnalités top 3</td>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;">${topFeats}</td>
+                                </tr>
+                                <tr>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;">Coût IA (estimation)</td>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;font-weight:600;">${costFcfa.toLocaleString('fr-FR')} FCFA</td>
+                                </tr>
+                                <tr style="background:#f8fafc;">
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;">Crédits rechargés</td>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;font-weight:600;color:#059669;">+${credited.toLocaleString('fr-FR')} crédits</td>
+                                </tr>
+                                <tr>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;">Crédits consommés</td>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;font-weight:600;color:#dc2626;">-${spent.toLocaleString('fr-FR')} crédits</td>
+                                </tr>
+                                <tr style="background:#f8fafc;">
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;">Solde actuel</td>
+                                    <td style="padding:10px 14px;border:1px solid #e2e8f0;font-weight:600;color:${org.walletBalance < 200 ? '#dc2626' : '#059669'};">${org.walletBalance.toLocaleString('fr-FR')} crédits</td>
+                                </tr>
+                            </table>
+                            <a href="https://admin.xamle.studio/billing" style="display:inline-block;padding:12px 24px;background:#4f46e5;color:white;text-decoration:none;border-radius:8px;font-weight:bold;">Voir le détail complet</a>
+                            <p style="color:#94a3b8;font-size:0.8rem;margin-top:32px;">Ce rapport est généré automatiquement le 1er de chaque mois. · L'équipe Xamlé Studio</p>
+                        </div>`,
+                }).catch(e => logger.error({ e, orgId: org.id }, '[MONTHLY-REPORT] Email failed'));
+
+                logger.info({ orgId: org.id }, '[MONTHLY-REPORT] Report sent');
+            }
+
+            logger.info('[MONTHLY-REPORT] All monthly reports sent.');
+        } catch (err) {
+            logger.error({ err }, '[MONTHLY-REPORT] Failed');
+        }
+    });
+
+    logger.info('[MONTHLY-REPORT] Monthly report scheduler initialized (cron: 1st of month 07:30 UTC).');
+}

apps/whatsapp-worker/src/services/usage-tracker.ts

@@ -10,9 +10,12 @@ async function maybeQueueQuotaAlert(organizationId: string, creditsBefore: numbe
     try {
         const org = await prisma.organization.findUnique({
             where: { id: organizationId },
-            select: { aiCreditsUsed: true, aiCreditsLimit: true, name: true, users: { where: { role: 'ADMIN' }, select: { email: true, name: true }, take: 1 } }
+            select: { aiCreditsUsed: true, aiCreditsLimit: true, subscriptionPlan: true, name: true, users: { where: { role: 'ADMIN' }, select: { email: true, name: true }, take: 1 } }
         });
         if (!org || org.aiCreditsLimit === 0) return;
+        // Only notify paying plans — STARTER quota alerts add noise, not value
+        const notifiablePlans = ['SCALE', 'ENTERPRISE', 'GROWTH'];
+        if (!notifiablePlans.includes(org.subscriptionPlan ?? '')) return;
 
         const pctBefore = Math.floor((creditsBefore / org.aiCreditsLimit) * 100);
         const pctNow = Math.floor((org.aiCreditsUsed / org.aiCreditsLimit) * 100);