npm package: @muana/pay-sdk
Description: SDK sécurisé pour intégrer les paiements Mobile Money avec intelligence artificielle, génération automatique de secrets HMAC, et mode ECDSA recommandé
Author: OKTRA.DEV
Latest version: 0.6.0

# Muana Pay SDK

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

[![Version](https://img.shields.io/npm/v/@muana/pay-sdk)](https://www.npmjs.com/package/@muana/pay-sdk)
[![License](https://img.shields.io/npm/l/@muana/pay-sdk)](https://github.com/muana/pay-sdk/blob/main/LICENSE)
[![Node.js](https://img.shields.io/npm/node/v/@muana/pay-sdk)](https://nodejs.org/)

## 🚀 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
```bash
npm i @muana/pay-sdk
```

### 🚀 Modes d'intégration

**Supabase (Edge Functions)**
```ts
import { MuanaPayClient } from '@muana/pay-sdk/supabase';
```

**BYOB - Bring Your Own Backend/Base (Webhooks)**
```ts
// 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):

```bash
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

```ts
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)

```ts
// 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) :**
```bash
# 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):
```bash
supabase functions deploy muana-filter
supabase functions deploy muana-validation
```

Set env vars in Supabase dashboard or via CLI:
```bash
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.

```tsx
// 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.

```tsx
// 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:
   ```bash
   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**:
   ```bash
   # 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](./README.fr.md) - Guide complet d'installation et configuration
- **🔐 Sécurité** : [docs/WEBHOOK_SECURITY.md](./docs/WEBHOOK_SECURITY.md) - Guide détaillé HMAC vs ECDSA
- **🧠 IA Groq** : [docs/GROQ_FILTERING.md](./docs/GROQ_FILTERING.md) - Filtrage intelligent des SMS
- **📱 Exemples** : [examples/](./examples/) - Implémentations React et Node.js
- **🔧 BYOB** : [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.