Plan - Intégration Newsletter Loops, Cloudflare Services et Sanity

Plan d’Exécution — Logique Newsletter Loops & Architecture L1/L2/L3

• Date : 2026-10-26
• Statut : Complété et validé de bout en bout
• Références :
  • ADR-Newsletter-Loops.md
  • DAT-Newsletter-Loops.md
• Dépôts cibles :
  • amn-blog (Couche L2 - Présentation Astro & Endpoint /api/submit)
  • amn-services (Couche L3 - Workers form-handler et submission-processor)
  • amn-studio (Couche L1 - Schémas prefooterSettings et submission)
  • ~/.gemini/config/mcp_config.json (Configuration MCP Loops)

---

1. Objectif Global

Mettre en place la logique complète du formulaire d’abonnement à la newsletter situé dans le prefooter de amn-blog, en respectant scrupuleusement l’architecture découplée AMN :

• Sanity (L1 - Contenus) : Administration éditoriale des textes, boutons et messages d’états, ainsi qu’archivage d’audit des soumissions.
• Astro (L2 - Présentation) : Interface utilisateur fluide, accessible, optimisée pour le mobile et le desktop, sans rechargement de page.
• Cloudflare (L3 - Services) : Pipeline asynchrone non-bloquant garantissant une réponse en < 50ms et une résilience maximale grâce à Cloudflare Queues.
• Loops.so (Plateforme Emailing) : Enregistrement de l’abonné dans l’audience de l’équipe “AmCloud” avec pilotage outillé via le serveur MCP.

---

2. Découpage par Phases

Phase 1 : Configuration du Serveur MCP Loops & Clés d’Environnement

• 1.1. Mise à jour de mcp_config.json : Remplacer l’URL distante OAuth (https://mcp.loops.so) par le serveur stdio loops-mcp-server afin d’injecter la clé API validée 796e3ae3c6da58a59e14787256ce0507.
• 1.2. Test de diagnostic MCP : Vérifier la détection des outils (loops_create_contact, loops_find_contact, etc.) et la connectivité avec l’équipe “AmCloud”.
• 1.3. Configuration des secrets Cloudflare : Ajouter LOOPS_API_KEY dans la configuration locale (.dev.vars) et les secrets Cloudflare (wrangler secret put LOOPS_API_KEY --env dev) de amn-services/submission-processor.

---

Phase 2 : Évolution des Schémas Sanity (amn-studio)

• 2.1. Mise à jour de prefooterSettings.ts :
  • Ajouter newsletterSuccessMessage (texte affiché en cas de succès).
  • Ajouter newsletterErrorMessage (texte affiché en cas d’erreur).
• 2.2. Mise à jour de submission.ts :
  • Ajouter le champ formType ('contact' | 'newsletter').
  • Assouplir la validation pour que name et message ne soient pas obligatoires si formType === 'newsletter'.
• 2.3. Validation Studio : Vérifier l’affichage et l’édition dans Sanity Studio en local (tsc --noEmit validé).

---

Phase 3 : Logique Backend & Workers Cloudflare (amn-services)

• 3.1. Évolution du Worker form-handler (Producer) :
  • Remplacer SubmissionSchema par une union discriminée Zod acceptant les soumissions de type contact et de type newsletter ({ type: "newsletter", email: string, source?: string }).
  • Conserver le dispatch asynchrone dans SUBMISSIONS_QUEUE.
  • Déployé sur Cloudflare : amn-form-handler-dev.
• 3.2. Évolution du Worker submission-processor (Consumer) :
  • Détecter le type newsletter dans le lot de messages.
  • Implémenter l’appel REST vers Loops : POST https://app.loops.so/api/v1/contacts/create avec l’en-tête Authorization: Bearer ${env.LOOPS_API_KEY}.
  • Créer le document d’audit correspondant dans Sanity (_type: 'submission', formType: 'newsletter').
  • Gérer l’idempotence (si le contact existe déjà dans Loops, HTTP 409 traité comme succès).
  • Déployé sur Cloudflare : amn-submission-processor-dev.
• 3.3. Mise à jour de l’endpoint local /test-direct :
  • Permettre à l’endpoint de test local de simuler l’envoi vers Loops et Sanity pour faciliter le développement.

---

Phase 4 : Interface Utilisateur & Intégration Astro (amn-blog)

• 4.1. Amélioration de PreFooter.astro :
  • Récupérer les messages de succès et d’erreur depuis Sanity (Astro.props).
  • Intégrer un feedback accessible : spinner/indicateur de chargement sur le bouton lors de la soumission (disabled, aria-busy).
  • Afficher le message de confirmation avec animation fluide et réinitialisation du champ email.
  • Assurer un nettoyage Stega rigoureux sur tous les attributs de formulaire.
• 4.2. Validation du relais /api/submit.ts :
  • Vérifier la compatibilité du relaiement en local et en production via le fallback résilient vers le worker distant.

---

Phase 5 : Recette, Tests Bout en Bout & Démonstration

• 5.1. Test unitaire/local : Soumission d’une adresse de test via le formulaire du prefooter en environnement local.
• 5.2. Vérification dans Loops : Vérification de la présence du contact créé avec le statut subscribed: true et le groupe Newsletter.
• 5.3. Vérification dans Sanity Studio : Vérification du document d’audit créé dans la collection submission.
• 5.4. Test des cas limites :
  • Email invalide (format rejeté par HTML5 et Zod).
  • Double soumission rapide (anti-rebond côté client).
  • Contact déjà existant dans Loops (idempotence HTTP 409).

---

3. Critères d’Acceptation (Definition of Done)

1. La documentation technique (ADR, DAT et Plan) est consultable et intégrée dans amn-docs.
2. Le serveur MCP Loops est configuré et opérationnel avec la clé API fournie.
3. Le formulaire de la newsletter soumet les données sans rechargement de page et affiche un retour visuel clair et accessible.
4. Tout contact soumis est instantanément transmis via la Queue Cloudflare sans bloquer l’interface (< 50ms perçus).
5. L’abonné est créé dans Loops et une trace d’audit est enregistrée dans Sanity.
6. Aucune régression sur le formulaire de contact existant (contact.astro).