Muana Pay SDK

SDK JavaScript/TypeScript pour intégrer les paiements Mobile Money avec sécurité renforcée et intelligence artificielle. Deux modes disponibles:

🚀 Nouveautés v0.4.0

• 🧠 Intelligence artificielle Groq intégrée dans tous les modes (Supabase + BYOB)
• 🔄 Parsing intelligent des SMS : Regex + IA Groq pour extraction optimale
• 🆕 Endpoints unifiés : /muana-validation partout (Supabase + BYOB)
• 🆕 Fingerprinting avancé : Détection des doublons par empreinte cryptographique
• 🆕 Champs structurés : payment_reference, amount_cents, counterparty_number, parsed_confidence
• 🛡️ Mode ECDSA recommandé pour la sécurité maximale

📦 Installation

npm i @muana/pay-sdk

🚀 Modes d'intégration

Supabase (Edge Functions)

import { MuanaPayClient } from '@muana/pay-sdk/supabase';

BYOB - Bring Your Own Backend/Base (Webhooks)

// Pas d'import côté serveur - utilisez les templates fournis
// L'app Android envoie directement à votre endpoint

Mode Supabase

Quickstart

1. Deploy Edge Functions in your Supabase project

Copy files from the SDK into your Supabase functions folder:

node_modules/@muana/pay-sdk/supabase/edge/muana-filter/index.ts           → supabase/functions/muana-filter/index.ts
node_modules/@muana/pay-sdk/supabase/edge/muana-validation/index.ts      → supabase/functions/muana-validation/index.ts

Then deploy and set env vars (from your project root):

supabase functions deploy muana-filter
supabase functions deploy muana-validation

supabase functions set muana-filter \
  SUPABASE_URL=your_url \
  SUPABASE_ANON_KEY=your_anon_key \
  GROQ_API_KEY=your_groq_key  # Optionnel mais recommandé

supabase functions set muana-validation \
  SUPABASE_URL=your_url \
  SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

2. Run the SQL once in your database

Open and execute this script in your Supabase SQL editor:

node_modules/@muana/pay-sdk/supabase/sql/setup_transactions.sql

It creates public.muana_sms (consolidated table for SMS storage + payment processing) with helpful indexes + permissive RLS for inserts/selects used by the functions.

3. Add environment variables in your Web app

Vite example (.env):

VITE_SUPABASE_URL=<YOUR_SUPABASE_URL>
VITE_SUPABASE_ANON_KEY=<YOUR_ANON_KEY>  # never commit .env

4. Initialize the client

import { MuanaPay } from '@muana/pay-sdk/supabase';

const muana = new MuanaPay({
  supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
  anonKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
});

5. Verify a transaction (Pricing flow)

// Méthode 1: Vérification par référence de transaction (méthode classique)
const result = await muana.verifyTransaction({
  userId: 'USER_UUID',                // Supabase Auth user id
  paymentReference: 'ABC123',         // copied from the user's SMS
  planName: 'Pro',                    // nom du plan
});

// Méthode 2: Vérification par numéro de téléphone (nouveau!)
const result = await muana.verifyTransaction({
  userId: 'USER_UUID',
  counterpartyNumber: '7701xxxx',     
  planName: 'Pro',
});

// Méthode 3: Vérification avec montant spécifique
const result = await muana.verifyTransaction({
  userId: 'USER_UUID',
  counterpartyNumber: '7701xxxx',
  amountCents: 10000,                 
});

🤖 Intelligence Artificielle Groq Intégrée

Nouveau ! Tous les modes (Supabase + BYOB) utilisent maintenant Groq AI pour :

• 🧠 Parsing intelligent : Extraction automatique des champs structurés
• 🎯 Filtrage marketing : Distinction SMS transaction vs publicité
• 🌍 Multilingue : Français, anglais, et autres langues
• 📊 Confiance élevée : Score de confiance pour chaque extraction

Configuration (ne jamais exposer ces clés côté client) :

# Supabase
supabase functions set muana-filter GROQ_API_KEY=your_groq_key

# BYOB
export GROQ_API_KEY=your_groq_key

Avantages (sans divulguer de prompts ou d'heuristiques internes) :

• ✅ Extraction précise : payment_reference, amount_cents, counterparty_number
• ✅ Filtrage automatique : Ignore les SMS marketing
• ✅ Fallback robuste : Regex si Groq indisponible
• ✅ Confiance mesurée : parsed_confidence pour chaque SMS

Prerequisites

• Edge Function muana-filter deployed with env: SUPABASE_URL, SUPABASE_ANON_KEY, GROQ_API_KEY (optionnel)
• Edge Function muana-validation deployed with env: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY
• Run the SQL in sql/setup_transactions.sql on your Supabase project

Deploy Edge Functions (copy these files into your Supabase functions)

Copy the files:

• edge/muana-filter/index.ts → supabase/functions/muana-filter/index.ts
• edge/muana-validation/index.ts → supabase/functions/muana-validation/index.ts

Then deploy (from your project root):

supabase functions deploy muana-filter
supabase functions deploy muana-validation

Set env vars in Supabase dashboard or via CLI:

supabase functions set muana-filter SUPABASE_URL=... SUPABASE_ANON_KEY=... GROQ_API_KEY=...
supabase functions set muana-validation SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=...

Notes:

• Muana Android App will POST incoming SMS to muana-filter using your Supabase URL + anon key (no Android native code needed).
• Your web/app server should call muana-validation when a user pastes their payment reference on the Pricing page.

🔐 Sécurité Renforcée

Génération Automatique des Secrets HMAC

Problème résolu : Plus de secrets faibles comme "123456" ou "password" !

Solution : L'app Android génère automatiquement des secrets cryptographiquement sécurisés de 64 caractères.

// Dans l'app MuAna → Configuration → Mode Webhook → HMAC
<Button onClick={() => {
  // Génération sécurisée 32 bytes = 64 hex chars
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  const newSecret = Array.from(array, 
    byte => byte.toString(16).padStart(2, '0')
  ).join('');
  
  setWebhookSecret(newSecret);
}}>
  Générer Secret Sécurisé
</Button>

Mode ECDSA Recommandé

Plus sécurisé que HMAC : Clés privées dans Android Keystore, révocation par appareil.

// Génération automatique des paires de clés
<Button onClick={async () => {
  const { generateEcdsaP256KeyPair } = await import("@/lib/ecdsa");
  const { publicKeyPem, privateJwk } = await generateEcdsaP256KeyPair();
  // Clé privée reste dans l'appareil, clé publique envoyée au serveur
}}>
  Générer Paire de Clés
</Button>

Mode BYOB (Bring Your Own Backend/Base)

Pour les développeurs qui veulent utiliser leur propre base de données (Postgres, MySQL, MongoDB, etc.) sans Supabase.

Principe

• L'app Android MuAna envoie directement les SMS vers votre endpoint webhook.
• Votre serveur reçoit, vérifie la signature, parse le SMS avec IA Groq, et insère en base.
• MuAna ne stocke aucune donnée: BYOB = autonomie totale.

🆕 Nouveautés BYOB v0.4.0

• 🧠 IA Groq intégrée : Parsing intelligent des SMS même en mode BYOB
• 🔄 Endpoints unifiés : /muana-validation partout (comme Supabase)
• 🆕 Fingerprinting avancé : Détection des doublons par empreinte cryptographique
• 🆕 Champs structurés : payment_reference, amount_cents, counterparty_number, parsed_confidence
• 🆕 Parsing hybride : Regex + IA Groq pour extraction optimale

Quickstart BYOB

1. Choisissez un template serveur dans byob/:

   • Node + Postgres: byob/node-express-postgres/server-unified.js (recommandé)
   • Node + Postgres: byob/node-express-postgres/server.js
   • Node + Postgres: byob/node-express-postgres/server-ecdsa.js

2. Créez les tables avec les schemas fournis:

   • Postgres: byob/sql/muana_sms.postgres.sql
   • MySQL: byob/sql/muana_sms.mysql.sql

3. Déployez le serveur avec les variables d'environnement:

   DATABASE_URL=postgresql://...
   GROQ_API_KEY=your_groq_key  # Optionnel mais recommandé pour l'IA

4. Configurez l'app MuAna:

   • Mode: Webhook (BYOB)
   • Signature: ECDSA (recommandé) ou HMAC
   • Webhook URL: https://votre-backend.com/webhook/sms
   • Générez une paire de clés via le bouton

5. Testez la vérification automatique:

   # Créer une demande de paiement
   curl -X POST https://votre-backend.com/muana-validation \
     -H "Content-Type: application/json" \
     -d '{
       "user_id": "user123", 
       "plan_name": "Pro", 
       "amount_cents": 10000,
       "counterparty_number": "123456789"
     }'
   # Retourne: {"status": "verified", "sms_id": "uuid"}
      
   # Quand l'app Android reçoit un SMS de 77010000 avec 10000 FCFA,
   # l'auto-match active automatiquement l'abonnement!

🆕 Architecture BYOB v0.4.0

Parsing hybride intelligent :

SMS reçu → Regex basique → IA Groq (si disponible) → Base de données structurée

Champs extraits automatiquement :

• payment_reference : ID/référence de transaction
• amount_cents : Montant en centimes
• counterparty_number : Numéro expéditeur/destinataire
• parsed_confidence : Score de confiance de l'extraction
• fingerprint : Empreinte cryptographique pour éviter les doublons

Endpoints unifiés :

• POST /webhook/sms : Réception des SMS avec parsing IA
• POST /muana-validation : Vérification des transactions

Sécurité BYOB

• ECDSA par appareil (défaut): clé privée Android Keystore + clé publique en base.
• HMAC par appareil (compat): secret par device_id en base.
• Anti-replay: fenêtre 5 min + table muana_webhook_events.
• Déduplication: fingerprint unique par SMS.
• Parsing sécurisé: Regex + IA Groq avec fallback robuste.

Voir byob/README.md pour les détails complets.

API

Supabase Mode:

• new MuanaPayClient({ supabaseUrl: string, anonKey: string })
• sendSms({ sender: string, message: string, timestamp?: string|number|Date }) → POST to /functions/v1/muana-filter
• verifyTransaction({ userId: string, paymentReference?: string, counterpartyNumber?: string, planName?: string, amountCents?: number }) → POST to /functions/v1/muana-validation

BYOB Mode:

• POST /webhook/sms → Reçoit les SMS, parse avec IA et auto-match
• POST /muana-validation → Vérification des transactions (même interface que Supabase)

Nouveautés v0.4.0:

• 🧠 IA Groq intégrée dans tous les modes (Supabase + BYOB)
• 🔄 Parsing intelligent : Regex + IA pour extraction optimale
• 🆕 Endpoints unifiés : /muana-validation partout
• 🆕 Fingerprinting avancé : Détection des doublons par empreinte
• 🆕 Champs structurés : payment_reference, amount_cents, counterparty_number, parsed_confidence
• 🔄 Vérification automatique par numéro: Plus besoin de saisir l'ID de transaction
• ⚡ Auto-match en temps réel: Activation immédiate du plan dès réception du SMS
• 🔄 Realtime support: Écoute des mises à jour via Supabase Realtime
• 📊 Colonnes enrichies: payment_status, counterparty_number, amount_cents, etc.
• 🛡️ Mode ECDSA recommandé pour la sécurité maximale

Recommended:

• Use planId from your own plans table for exact match.
• If you can't pass a plan, provide amountCents so the function can create a pending transaction and validate amount vs plan later.
• Set GROQ_API_KEY for intelligent SMS parsing and marketing filtering.

SQL Setup

Run sql/setup_transactions.sql on your Supabase database. It creates public.muana_sms with the columns used by the Edge Functions and permissive RLS policies for insert/select.

Security

• muana-filter is called with the anon key from Muana Android. The RLS policy on muana_sms is permissive to allow inserts.
• muana-validation must use the service role key in Edge env (not exposed to clients).
• In your Vite app, define VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env files.

Security checklist (Operational)

• Do not commit .env files; use secrets managers or CI/CD environment variables.
• Never expose or bundle SUPABASE_SERVICE_ROLE_KEY or GROQ_API_KEY in client code.
• Mask phone numbers and references in logs and examples (e.g., 7701xxxx, REFxxxx).
• Avoid logging raw SMS content; log minimal metadata only.
• Rotate keys immediately if exposure is suspected, and audit access logs.
• Keep prompts/model details private; document behavior, not internal instructions.

📚 Documentation

• 🇫🇷 Français : README.fr.md - Guide complet d'installation et configuration
• 🔐 Sécurité : docs/WEBHOOK_SECURITY.md - Guide détaillé HMAC vs ECDSA
• 🧠 IA Groq : docs/GROQ_FILTERING.md - Filtrage intelligent des SMS
• 📱 Exemples : examples/ - Implémentations React et Node.js
• 🔧 BYOB : byob/ - Templates serveur et schémas SQL

Example .env:

VITE_SUPABASE_URL=https://xxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOi...

Troubleshooting

• Node < 18: install a fetch polyfill (e.g. node-fetch) or upgrade Node.
• muana-validation returns 500: check SUPABASE_SERVICE_ROLE_KEY is set on the function and correct.
• Status rejected: make sure the SMS with that payment_reference exists in muana_sms, and the amount matches the selected plan.
• CORS: the Edge Functions set permissive CORS headers by default; if you customize, keep authorization, x-client-info, apikey, content-type allowed.
• GROQ parsing fails: check GROQ_API_KEY is set and valid. The system falls back to regex parsing automatically.