Release Notes - v1.9.0

Release Notes - v1.9.0

This release introduces significant improvements to logging, configuration, worker management, and adds new features like campaign cancellation, focusing on robustness, developer experience, and alignment with best practices.

✨ New Features & Major Improvements

1. Structured Logging with Pino:
   • Replaced the previous simple logger with pino for fast, structured (JSON) logging. (#XXX)
   • Logs now include rich context (component, queue, job ID, campaign ID, etc.).
   • Log level is configurable via loggerFactory.setLevel() or the LOG_LEVEL environment variable (info default).
   • Added pino-pretty as an optional dev dependency for improved readability during development.
2. Refactored Worker Management:
   • Removed startWorker: true from dispatchNotifications: This breaking change promotes the standard architecture of separating job producers and consumers. Users must now run workers independently using startWorkerServer. (#XXX)
   • Added WorkerManager.pauseProcessing() and WorkerManager.resumeProcessing() methods to allow operators to gracefully pause/resume job consumption from a queue. (#XXX)
   • The existing WorkerManager.close() method provides graceful shutdown.
3. Campaign Cancellation:
   • Added optional campaignId to dispatchNotifications. (#XXX)
   • Workers now check for a Redis key (worker:cancel:campaign:<campaignId>) before processing jobs with a matching campaignId. Setting the key's value to 'true' will cause workers to skip processing for that campaign gracefully.
   • Removed the previous global SimulationManager in favor of this more targeted cancellation mechanism.
4. Simplified Dispatch Configuration:
   • Removed notifierOptions and customNotifier from dispatchNotifications. Notifier configuration is now solely handled by startWorkerServer. (#XXX)
   • Renamed notifierType to channelName in dispatchNotifications for clarity. Kept generic type link for meta safety.
5. Refactored Notifier Implementation:
   • Notifiers (EmailNotifier, FirebaseNotifier, etc.) now delegate batching/concurrency/rate-limiting to a shared batchSender utility internally. (#XXX)
   • Notifier send methods now accept a PinoLogger instance for contextual logging during message sending.
6. Improved Redis Instance Handling (ensureRedisInstance):
   • The helper now robustly validates provided ioredis instances or creates new ones, ensuring required BullMQ options (maxRetriesPerRequest: null) are set correctly. (#XXX)
   • Provides clearer warnings and errors for misconfigured instances.
7. Firebase Notifier Configuration:
   • startWorkerServer configuration for Firebase (notifiers.firebase) now accepts the ServiceAccount object or a file path string directly, removing the need for the { serviceAccount: ... } wrapper. (#XXX)

💥 Breaking Changes

• startWorker: true Removed: The startWorker option in dispatchNotifications has been removed. Users must run worker processes separately using startWorkerServer. Update your deployment strategy accordingly.
• dispatchNotifications Configuration:
  • notifierOptions parameter removed. Configure notifiers via startWorkerServer.
  • customNotifier parameter removed. Register custom notifiers manually via NotifierRegistry in your worker process.
  • notifierType renamed to channelName.
• SimulationManager Removed: The global simulation mode managed via SimulationManager and Redis key worker:simulation_mode has been removed. Use targeted Campaign Cancellation or environment variables for testing/simulation needs.
• Notifier send Signature: The send method on the NotificationChannel interface (and all implementing classes) now requires a PinoLogger instance as the third argument. If you have custom notifiers, update their signatures.
• Firebase Config: The structure for configuring Firebase in startWorkerServer has changed from notifiers: { firebase: { serviceAccount: ... } } to notifiers: { firebase: serviceAccountOrPathString }.

🔧 Minor Changes & Fixes

• Improved type safety in various interfaces (NotificationResult, Meta types).
• Refined error formatting in notifier results.
• Standardized use of RateLimiter across notifiers.
• Added comprehensive unit tests for core utilities and notifiers (focusing on functionality). (#XXX)
• Updated README with new architecture, configuration, and examples. (#XXX)

⬆️ Dependency Updates

• Added pino as a direct dependency.
• Updated BullMQ / ioredis / Notifier SDK types where applicable (List specific versions if changed significantly).

📝 Migration Guide

1. Remove startWorker: true: Delete the startWorker option from all dispatchNotifications calls.
2. Create Worker Script: Set up a separate Node.js script using startWorkerServer to run your worker processes. Configure all necessary notifiers within the notifiers option of startWorkerServer. Deploy and manage this script using a process manager (PM2, nodemon, Docker, etc.).
3. Update dispatchNotifications Calls:
   • Rename notifierType to channelName.
   • Remove notifierOptions.
   • Remove customNotifier.
   • (Optional) Add campaignId if you need cancellation capabilities.
4. Update startWorkerServer Config: If using Firebase, update the notifiers.firebase value to pass the service account object or path directly.
5. Update Custom Notifiers: If you have custom classes implementing NotificationChannel, update their send method to accept logger: PinoLogger as the third argument.
6. Review Logging: Adapt to the new pino based logging output. Configure log levels via LOG_LEVEL env var or loggerFactory.setLevel(). Consider using pino-pretty in development.
7. Update Redis Instance Creation: If providing your own ioredis instance, ensure it's created with maxRetriesPerRequest: null.

---

How to Use:

See the updated README.md for detailed usage instructions and examples.