story-research-zapwall/features/rizful-integration.md

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 :

# 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
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