216 lines
7.2 KiB
Markdown
216 lines
7.2 KiB
Markdown
# 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
|