chore: newsletter e2e implementation

[Bappa-Kamba]

✉️ Newsletter Subscription System (Double Opt-In)

Overview

This PR introduces a production-ready newsletter subscription system with double opt-in, secure unsubscribe flow, and admin visibility. The implementation aligns backend APIs with the existing frontend newsletter component and follows best practices for security, validation, and extensibility.

---

Related Issue

Closes #442

---

✨ Features

Public Newsletter Flow

• POST /newsletter/subscribe

  • Accepts and validates email address
  • Normalizes and sanitizes input
  • Prevents duplicate active subscriptions
  • Stores subscriber with PENDING state
  • Generates:
    • verificationToken (confirm subscription)
    • unsubscribeToken (future opt-out)
  • Sends confirmation email (double opt-in)

• POST /newsletter/confirm

  • Validates confirmation token
  • Activates and verifies subscriber
  • Idempotent (safe to retry)
  • Sends confirmation success email

• POST /newsletter/unsubscribe

  • Validates unsubscribe token
  • Soft-deletes subscriber while preserving history
  • Idempotent behavior for repeated requests
  • Sends unsubscribe confirmation email

---

Admin Functionality

• GET /newsletter/subscribers
  • Admin-only endpoint
  • Paginated response using existing pagination utilities
  • Protected by JWT auth + role-based access control

---

🧱 Technical Details

Backend (NestJS)

• Created NewsletterSubscriber entity with:
  • Unique email constraint
  • Timestamps (subscribedAt, verifiedAt)
  • GDPR-friendly fields (consentedAt, ipAddress)
  • Soft delete support
• Implemented providers for:
  • Subscription
  • Confirmation
  • Unsubscription
• Integrated with existing email service (SendGrid)
• Applied rate-limiting to prevent abuse
• Respected global auth setup with @Public() for open routes

Frontend (Next.js)

• Wired newsletter form to backend API
• Added confirmation flow:
  • /newsletter/confirm page
  • Reusable confirmation component
• Clear user feedback for:
  • Pending confirmation
  • Successful confirmation
  • Error states

---

🔐 Security & Validation

• Email format validation
• Disposable email blocking (basic blocklist)
• Input sanitization via custom decorator
• Double opt-in prevents unauthorized subscriptions
• Tokens never exposed via API responses
• Rate limiting on public endpoints

---

🧪 Testing

• Manual API testing via curl/Postman:
  • Subscribe
  • Confirm
  • Unsubscribe
  • Duplicate & invalid scenarios
• Verified DB state transitions
• Frontend tested against live backend endpoints

---

📌 Notes / Future Improvements

• Add token expiration enforcement for confirmation links
• Expand disposable email detection
• Optional welcome email after confirmation
• Admin filters (active / pending / unsubscribed)

---

✅ Checklist

• Backend endpoints implemented
• Double opt-in flow working
• Admin endpoint protected
• Frontend wired and tested
• No breaking changes to existing APIs

[vercel]

@Bappa-Kamba is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.

[Bappa-Kamba]

Hello @yusuftomilola, please review and let me know if there are any changes.