feat(billing): close 3 remaining wallet gaps from implementation plan

⑫ sendTextMessage() wallet debit coverage:
- Add organizationId?: string to sendTextMessage() config — calls trackWhatsAppSent() automatically after each successful send
- NudgeHandler, ContentHandler, EnrollHandler, MediaHandler, AdminHandler: pass organizationId in tenantConfig so every outbound message triggers the debit without touching each callsite individually

⑯ GET /billing/summary now includes wallet block:
- wallet: { balance, isHardStopped, creditToFcfa, balanceFcfa } appended to every summary response

⑱ BillingPage: wallet transaction table:
- Table showing last 20 transactions (date, type, description, amount, balance after)
- Type labels with emoji (recharge vs debit), BYOK badge, red/green amount colouring
- Inserted between feature breakdown and chat widget

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

apps/admin/src/pages/BillingPage.tsx

@@ -443,6 +443,61 @@ export default function BillingPage() {
                 </div>
             )}
 
+            {/* Wallet transactions */}
+            {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">Dernières transactions wallet</h2>
+                    </div>
+                    <div className="overflow-x-auto">
+                        <table className="w-full text-sm">
+                            <thead>
+                                <tr className="border-b border-slate-100 text-xs text-slate-400 uppercase">
+                                    <th className="px-6 py-3 text-left font-semibold">Date</th>
+                                    <th className="px-6 py-3 text-left font-semibold">Type</th>
+                                    <th className="px-6 py-3 text-left font-semibold">Description</th>
+                                    <th className="px-6 py-3 text-right font-semibold">Montant</th>
+                                    <th className="px-6 py-3 text-right font-semibold">Solde après</th>
+                                </tr>
+                            </thead>
+                            <tbody>
+                                {wallet.transactions.map(tx => {
+                                    const isCredit = tx.amount > 0;
+                                    const typeLabels: Record<string, string> = {
+                                        TOP_UP_MANUAL: '➕ Recharge manuelle',
+                                        TOP_UP_PAYMENT: '➕ Paiement',
+                                        ADJUSTMENT: '🔧 Ajustement',
+                                        DEBIT_AI: '🤖 IA',
+                                        DEBIT_WHATSAPP: '💬 WhatsApp',
+                                        DEBIT_BROADCAST: '📣 Broadcast',
+                                    };
+                                    return (
+                                        <tr key={tx.id} className="border-b border-slate-50 hover:bg-slate-50 transition-colors">
+                                            <td className="px-6 py-3 text-slate-500 whitespace-nowrap">
+                                                {new Date(tx.createdAt).toLocaleDateString('fr-FR', { day: '2-digit', month: '2-digit', hour: '2-digit', minute: '2-digit' })}
+                                            </td>
+                                            <td className="px-6 py-3 text-slate-600 whitespace-nowrap">
+                                                {typeLabels[tx.type] ?? tx.type}
+                                                {tx.byok && <span className="ml-1 text-xs text-slate-400">(BYOK)</span>}
+                                            </td>
+                                            <td className="px-6 py-3 text-slate-500 max-w-[200px] truncate">
+                                                {tx.description ?? '—'}
+                                            </td>
+                                            <td className={`px-6 py-3 text-right font-mono font-semibold whitespace-nowrap ${isCredit ? 'text-emerald-600' : 'text-slate-700'}`}>
+                                                {isCredit ? '+' : ''}{tx.amount.toLocaleString('fr-FR')} cr
+                                            </td>
+                                            <td className="px-6 py-3 text-right font-mono text-slate-500 whitespace-nowrap">
+                                                {tx.balanceAfter >= 0 ? tx.balanceAfter.toLocaleString('fr-FR') : '—'}
+                                            </td>
+                                        </tr>
+                                    );
+                                })}
+                            </tbody>
+                        </table>
+                    </div>
+                </div>
+            )}
+
             {/* AI Chat Widget */}
             <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 bg-slate-50">

apps/api/src/routes/billing.ts

@@ -27,6 +27,8 @@ export async function billingRoutes(fastify: FastifyInstance) {
                 aiCreditsLimit: true,
                 whatsappMessagesSent: true,
                 billingPeriodStart: true,
+                walletBalance: true,
+                isHardStopped: true,
             }
         });
         if (!org) return reply.code(404).send({ error: 'Organization not found' });
@@ -67,6 +69,12 @@ export async function billingRoutes(fastify: FastifyInstance) {
                 messagesSent: org.whatsappMessagesSent,
                 note: 'Facturé directement par Meta sur votre compte WABA',
             },
+            wallet: {
+                balance: org.walletBalance,
+                isHardStopped: org.isHardStopped,
+                creditToFcfa: 10,
+                balanceFcfa: org.walletBalance * 10,
+            },
         };
     });
 

apps/whatsapp-worker/src/handlers/AdminHandler.ts

@@ -34,7 +34,7 @@ export class AdminHandler implements JobHandler {
         const { sendAudioMessage } = await import('../whatsapp-cloud');
         await sendAudioMessage(user.phone, overrideAudioUrl, tenantConfig);
         const adminMsg = { FR: "Bravo ! Envoyez *SUITE* pour passer à la leçon suivante.", WOLOF: "Baax na ! Yónnee *SUITE* ngir dem ci kanam.", EN: "Well done! Send *CONTINUE* to move to the next lesson.", ES: "¡Bravo! Envía *CONTINUAR* para pasar a la siguiente lección.", PT: "Muito bem! Envie *CONTINUAR* para passar para a próxima lição." }[user.language] ?? "Bravo ! Envoyez *SUITE* pour passer à la leçon suivante.";
-        await sendTextMessage(user.phone, adminMsg, tenantConfig);
+        await sendTextMessage(user.phone, adminMsg, { ...tenantConfig, organizationId });
 
         await prisma.response.create({
             data: {

apps/whatsapp-worker/src/handlers/ContentHandler.ts

@@ -81,7 +81,8 @@ export class ContentHandler implements JobHandler {
 
                         if (user?.phone) {
                             const tenantConfig = await this.getTenantConfig(user.organizationId);
-                            await sendTextMessage(user.phone, congratsMsg[lang] ?? congratsMsg['FR'], tenantConfig);
+                            const orgConfig = { ...tenantConfig, organizationId: user.organizationId };
+                            await sendTextMessage(user.phone, congratsMsg[lang] ?? congratsMsg['FR'], orgConfig);
 
                             if (!nextTrack.isPremium) {
                                 await prisma.$transaction([
@@ -102,7 +103,7 @@ export class ContentHandler implements JobHandler {
                                     ES: `💳 El Nivel ${nextLevel} es Premium. ¡Envía "PAGAR" para desbloquearlo!`,
                                     PT: `💳 O Nível ${nextLevel} é Premium. Envie "PAGAR" para desbloqueá-lo!`,
                                 };
-                                await sendTextMessage(user.phone, payMsg[lang] ?? payMsg['FR'], tenantConfig);
+                                await sendTextMessage(user.phone, payMsg[lang] ?? payMsg['FR'], orgConfig);
                             }
                         }
                     }

apps/whatsapp-worker/src/handlers/EnrollHandler.ts

@@ -32,7 +32,7 @@ export class EnrollHandler implements JobHandler {
                 const tenantConfig = await this.getTenantConfig(organizationId as string);
                 const msgMap: Record<string, string> = { FR: "La formation est en cours de préparation. Nous te préviendrons dès qu'elle est disponible ! 📚", WOLOF: "Dafa daan jàppale — dinañu la xam bu amee ci kanam ! 📚", EN: "Training content is being prepared. We'll notify you when it's ready! 📚", ES: "El contenido de formación está en preparación. ¡Te avisaremos cuando esté listo! 📚", PT: "O conteúdo da formação está a ser preparado. Iremos notificá-lo quando estiver pronto! 📚" };
                 const msg = msgMap[user.language] ?? msgMap['FR'];
-                await sendTextMessage(user.phone, msg, tenantConfig);
+                await sendTextMessage(user.phone, msg, { ...tenantConfig, organizationId: organizationId as string });
             }
             return;
         }
@@ -56,7 +56,7 @@ export class EnrollHandler implements JobHandler {
                     const user = await prisma.user.findUnique({ where: { id: userId } });
                     if (user?.phone) {
                         const tenantConfig = await this.getTenantConfig(organizationId as string);
-                        await sendTextMessage(user.phone, `💳 Cette formation est Premium. Complétez votre paiement ici :\n${checkoutData.url}`, tenantConfig);
+                        await sendTextMessage(user.phone, `💳 Cette formation est Premium. Complétez votre paiement ici :\n${checkoutData.url}`, { ...tenantConfig, organizationId: organizationId as string });
                     }
                 }
             } catch (err) {
@@ -95,7 +95,7 @@ export class EnrollHandler implements JobHandler {
                         ES:    `🎉 ¡Bienvenido a *${track.title}*! Tu lección personalizada (Día 1) está siendo generada...`,
                         PT:    `🎉 Bem-vindo a *${track.title}*! Sua lição personalizada (Dia 1) está sendo gerada...`,
                     };
-                    await sendTextMessage(user.phone, welcomeMsg[user.language] ?? welcomeMsg['FR'], tenantConfig);
+                    await sendTextMessage(user.phone, welcomeMsg[user.language] ?? welcomeMsg['FR'], { ...tenantConfig, organizationId: organizationId as string });
 
                     const q = new Queue('whatsapp-queue', { connection });
                     await q.add('send-content', { userId, trackId, dayNumber: 1, organizationId });

apps/whatsapp-worker/src/handlers/MediaHandler.ts

@@ -81,7 +81,7 @@ export class MediaHandler implements JobHandler {
                         FR: "⏳ J'analyse ton audio...", WOLOF: "⏳ Defar ak sa kàddu...",
                         EN: "⏳ Analysing your audio...", ES: "⏳ Analizando tu audio...", PT: "⏳ Analisando seu áudio..."
                     }[user.language] ?? "⏳ Analysing...";
-                    await sendTextMessage(phone, spinnerMsg, tenantConfig);
+                    await sendTextMessage(phone, spinnerMsg, { ...tenantConfig, organizationId: organizationId as string });
                 }
             }
 
@@ -132,7 +132,7 @@ export class MediaHandler implements JobHandler {
                                         
                                     }
                                 });
-                                await sendTextMessage(phone, "🎙️ Nyangi jaxas sa kàddu. Xamle dina la tontu ci kanam !", tenantConfig);
+                                await sendTextMessage(phone, "🎙️ Nyangi jaxas sa kàddu. Xamle dina la tontu ci kanam !", { ...tenantConfig, organizationId: organizationId as string });
                                 return;
                             }
                         }

apps/whatsapp-worker/src/handlers/NudgeHandler.ts

@@ -35,7 +35,7 @@ export class NudgeHandler implements JobHandler {
 
         const nudgeType = (type || 'ENCOURAGEMENT') as keyof typeof messages;
         const text = messages[nudgeType] || messages.ENCOURAGEMENT;
-        await sendTextMessage(user.phone, text, tenantConfig);
+        await sendTextMessage(user.phone, text, { ...tenantConfig, organizationId: organizationId || undefined });
         logger.info(`[NUDGE_HANDLER] Nudge ${nudgeType} sent to ${user.phone}`);
     }
 }

apps/whatsapp-worker/src/whatsapp-cloud.ts

@@ -1,4 +1,5 @@
 import { logger } from './logger';
+import { trackWhatsAppSent } from './services/usage-tracker';
 /**
  * WhatsApp Cloud API Service
  *
@@ -40,7 +41,7 @@ function getHeaders(explicitToken?: string): Record<string, string> {
  * @param to - Recipient phone number in international format (e.g. "221771234567")
  * @param text - Message body (supports basic WhatsApp markdown: *bold*, _italic_)
  */
-export async function sendTextMessage(to: string, text: string, config?: { accessToken?: string, phoneNumberId?: string }): Promise<void> {
+export async function sendTextMessage(to: string, text: string, config?: { accessToken?: string, phoneNumberId?: string, organizationId?: string }): Promise<void> {
     // Safety guard: HF is inbound-only. Only Railway worker should call this.
     if (process.env.DISABLE_WHATSAPP_SEND === 'true') {
         logger.warn(`[WhatsApp] DISABLE_WHATSAPP_SEND=true — Skipping send to ${to}. Message: "${text.substring(0, 60)}..."`);
@@ -62,6 +63,9 @@ export async function sendTextMessage(to: string, text: string, config?: { acces
     }
 
     logger.info(`[WhatsApp] ✅ Text message sent to ${to}`);
+    if (config?.organizationId) {
+        trackWhatsAppSent(config.organizationId).catch(() => {});
+    }
 }
 
 /**