# Intégration Rizful.com API pour paiements Lightning et identités

**Auteur** : Équipe 4NK

## Objectif

Intégrer l'API de Rizful.com pour :
- Générer des identités Nostr
- Créer et gérer des factures Lightning pour les paiements d'articles
- Vérifier le statut des paiements Lightning
- Fournir une expérience de paiement fluide via Rizful

## Impacts

### Utilisateurs
- Paiements Lightning facilités via l'infrastructure Rizful
- Interface de paiement améliorée avec modal dédiée
- Vérification automatique des paiements
- Possibilité de générer des identités Nostr via Rizful

### Développeurs
- Service Rizful centralisé pour toutes les opérations de paiement
- Intégration transparente avec le système de paiement existant
- Gestion des factures Lightning standardisée
- API unifiée pour les identités et paiements

### Technique
- Nouveau service `RizfulService` pour les appels API
- Service `PaymentService` intégrant Rizful avec Nostr
- Composant `PaymentModal` pour l'affichage des factures
- Variables d'environnement pour la configuration API

## Modifications

### Nouveaux fichiers

#### `lib/rizful.ts` - Service Rizful API
Service principal pour interagir avec l'API Rizful.com :
- `createInvoice()` : Créer une facture Lightning
- `checkPaymentStatus()` : Vérifier le statut d'un paiement
- `waitForPayment()` : Polling jusqu'à confirmation du paiement
- `generateIdentity()` : Générer une nouvelle identité Nostr
- `getLightningAddress()` : Obtenir l'adresse Lightning d'une identité
- `createPaymentLink()` : Créer un lien de paiement avec URL Lightning

#### `lib/payment.ts` - Service de paiement intégré
Service intégrant Rizful avec le système Nostr :
- `createArticlePayment()` : Créer une facture pour un article
- `checkArticlePayment()` : Vérifier le paiement d'un article
- `waitForArticlePayment()` : Attendre la confirmation du paiement
- `getPaymentUrl()` : Obtenir l'URL de paiement pour un article

#### `types/rizful.ts` - Types TypeScript
Types pour l'API Rizful :
- `RizfulConfig` : Configuration du service
- `RizfulInvoice` : Structure d'une facture Lightning
- `RizfulPaymentStatus` : Statut d'un paiement
- `RizfulIdentity` : Identité Nostr générée
- `RizfulInvoiceRequest` : Requête de création de facture

#### `components/PaymentModal.tsx` - Modal de paiement
Composant React pour afficher la facture Lightning :
- Affichage de la facture en texte
- Bouton pour copier la facture
- Bouton pour ouvrir le wallet Lightning
- Interface utilisateur claire et intuitive

### Modifications des fichiers existants

#### `components/ArticleCard.tsx`
- Intégration du `PaymentService` au lieu du système de zap direct
- Affichage de `PaymentModal` lors de la création d'une facture
- Polling automatique pour vérifier le paiement en arrière-plan
- Gestion améliorée des états de paiement

#### `next.config.js`
- Ajout des variables d'environnement Rizful :
  - `RIZFUL_API_KEY` : Clé API Rizful
  - `RIZFUL_API_URL` : URL de l'API Rizful (défaut: https://api.rizful.com)

### Flux de paiement avec Rizful

1. **Utilisateur clique sur "Unlock for X sats"**
   - Vérification de la connexion Nostr
   - Création d'une facture Lightning via Rizful API

2. **Affichage de la modal de paiement**
   - Facture Lightning affichée
   - Options pour copier ou ouvrir dans wallet

3. **Paiement utilisateur**
   - Utilisateur paie via son wallet Lightning
   - Paiement traité par Rizful

4. **Vérification du paiement**
   - Polling automatique du statut via Rizful API
   - Vérification supplémentaire via zap receipt sur Nostr (double confirmation)

5. **Déblocage du contenu**
   - Une fois le paiement confirmé, chargement du contenu privé
   - Affichage du contenu complet

## Modalités de déploiement

### Prérequis
- Compte Rizful.com avec clé API
- Variables d'environnement configurées

### Configuration

Créer ou mettre à jour le fichier `.env.local` :

```env
# Rizful API Configuration
NEXT_PUBLIC_RIZFUL_API_KEY=your_rizful_api_key_here
NEXT_PUBLIC_RIZFUL_API_URL=https://api.rizful.com

# Existing Nostr configuration
NEXT_PUBLIC_NOSTR_RELAY_URL=wss://relay.damus.io
NEXT_PUBLIC_NOSTRCONNECT_BRIDGE=https://use.nsec.app
```

### Obtenir une clé API Rizful

1. Créer un compte sur [Rizful.com](https://rizful.com/)
2. Accéder aux paramètres du compte
3. Générer une clé API
4. Configurer l'adresse Lightning personnalisée (optionnel)
5. Copier la clé API dans les variables d'environnement

### Déploiement

Aucun changement dans le processus de déploiement standard :
- Les variables d'environnement doivent être configurées dans l'environnement de production
- Le code client peut accéder aux variables `NEXT_PUBLIC_*`
- Les appels API se font depuis le navigateur (CORS doit être configuré côté Rizful)

### Sécurité

- **Clé API** : Stockée côté client (NEXT_PUBLIC_*), donc accessible dans le navigateur
  - Rizful devrait implémenter des restrictions par domaine/origine
  - Considérer un proxy backend pour protéger la clé API en production
- **Factures Lightning** : Valides uniquement pendant la période d'expiration
- **Vérification double** : Combinaison Rizful API + zap receipts Nostr pour validation

## Modalités d'analyse

### Logs et debugging

Les erreurs sont loggées dans la console du navigateur :
- Erreurs de création de facture
- Erreurs de vérification de paiement
- Timeouts de polling

### Métriques à surveiller

1. **API Rizful**
   - Taux de succès des créations de factures
   - Temps de réponse de l'API
   - Taux de confirmation des paiements
   - Erreurs API (rate limiting, authentification, etc.)

2. **Paiements**
   - Temps moyen entre création de facture et paiement
   - Taux d'abandon de paiement
   - Taux de confirmation de paiement
   - Échecs de vérification de paiement

3. **Expérience utilisateur**
   - Utilisation de la modal vs ouverture directe du wallet
   - Taux de copie de facture
   - Temps d'attente pour confirmation

### Points d'amélioration

1. **Backend proxy (recommandé pour production)**
   - Créer un endpoint Next.js API route pour protéger la clé API
   - Appels API depuis le serveur au lieu du client
   - Validation supplémentaire côté serveur

2. **Gestion des erreurs**
   - Retry logic pour les appels API échoués
   - Gestion des timeouts réseau
   - Messages d'erreur utilisateur plus explicites

3. **QR Code**
   - Génération de QR code pour les factures Lightning
   - Affichage dans la modal de paiement
   - Compatible avec wallets mobiles

4. **Webhooks**
   - Intégration webhooks Rizful pour notifications en temps réel
   - Éviter le polling continu
   - Réactivité améliorée

5. **Identités**
   - Utilisation de `generateIdentity()` pour créer des identités
   - Stockage sécurisé des clés privées générées
   - Intégration avec le système d'authentification

### Tests recommandés

1. **Tests unitaires**
   - `RizfulService.createInvoice()`
   - `RizfulService.checkPaymentStatus()`
   - `PaymentService.createArticlePayment()`

2. **Tests d'intégration**
   - Flux complet de paiement (création → paiement → vérification)
   - Gestion des timeouts
   - Gestion des erreurs API

3. **Tests end-to-end**
   - Scénario utilisateur complet avec paiement réel
   - Vérification du déblocage de contenu après paiement