musicland/plans/suno-callback-implementation.md

Plan d'implémentation - Fonction Callback Suno

Objectif

Créer une cloud function qui servira de callback pour l'API Suno afin de recevoir les notifications lorsque la génération de musique est terminée.

Problèmes identifiés

• Besoin d'une URL de callback pour l'API Suno
• Gestion des notifications de fin de génération
• Mise à jour automatique du statut dans Firestore
• Traitement des erreurs de callback

Solutions appliquées

✅ 1. Création de la fonction callback

• Créé /functions/src/callback.js
• Fonction sunoCallback avec méthode POST uniquement
• Validation des données reçues
• Gestion des erreurs avec logs émojis

✅ 2. Traitement des données callback

• Extraction des paramètres de l'API Suno :
  • id : Identifiant de la génération
  • status : Statut de la génération
  • audio_url : URL du fichier audio
  • video_url : URL du fichier vidéo
  • image_url : URL de l'image de couverture
  • lyric : Paroles générées
  • title : Titre de la chanson
  • tags : Style musical
  • duration : Durée de la chanson
  • error_message : Message d'erreur si échec

✅ 3. Mise à jour Firestore

• Recherche du document correspondant par ID
• Mise à jour des champs :
  • status : Nouveau statut
  • audioUrl : URL audio si disponible
  • videoUrl : URL vidéo si disponible
  • imageUrl : URL image si disponible
  • lyrics : Paroles si disponibles
  • title : Titre si disponible
  • style : Style si disponible
  • duration : Durée si disponible
  • errorMessage : Message d'erreur si échec
  • updatedAt : Timestamp de mise à jour

✅ 4. Configuration de l'URL callback

• Mis à jour SUNO_CALLBACK_URL dans music.js
• URL : https://us-central1-musicland-app.cloudfunctions.net/sunoCallback
• Intégration dans le payload de génération

✅ 5. Export de la fonction

• Ajouté l'export dans functions/index.js
• Fonction accessible via Firebase Functions

Structure de la fonction callback

exports.sunoCallback = onRequest({
  cors: true,
  methods: ["POST"],
}, async (req, res) => {
  // Validation de la méthode
  // Extraction des données
  // Recherche du document Firestore
  // Mise à jour des données
  // Réponse de succès/erreur
});

Gestion des erreurs

• ✅ Validation de la méthode HTTP (POST uniquement)
• ✅ Vérification de la présence de l'ID
• ✅ Vérification de l'existence du document Firestore
• ✅ Gestion des erreurs de mise à jour
• ✅ Logs avec émojis pour faciliter le debugging

Réponses de la fonction

Succès (200)

{
  "success": true,
  "message": "Callback traité avec succès",
  "id": "generation_id",
  "status": "completed"
}

Erreurs

• 405 : Méthode non autorisée
• 400 : ID manquant
• 404 : Document non trouvé
• 500 : Erreur interne du serveur

Tests à effectuer

• Tester la fonction avec un payload de test
• Vérifier la mise à jour Firestore
• Tester les cas d'erreur
• Vérifier les logs
• Tester l'intégration avec l'API Suno

Déploiement

• Déployer les functions : firebase deploy --only functions
• Vérifier l'URL de la fonction déployée
• Tester la fonction en production

Notes importantes

• La fonction utilise onRequest pour accepter les callbacks HTTP
• CORS activé pour permettre les appels externes
• Seules les requêtes POST sont acceptées
• Les logs utilisent des émojis pour faciliter le debugging
• La fonction met à jour automatiquement le timestamp updatedAt

Fichiers modifiés

• ✅ /functions/src/callback.js (créé)
• ✅ /functions/src/music.js (SUNO_CALLBACK_URL mis à jour)
• ✅ /functions/index.js (export ajouté)
• ✅ /plans/suno-callback-implementation.md (ce fichier)