node-notification

In sintesi

Hub centralizzato delle notifiche del tenant: riceve richieste di delivery da altri microservizi (via REST o via subject NATS services.notification.send) e le instrada su tredici canali (email SMTP/Resend, SMS Twilio, push mobile FCM, web-push browser, in-app persistito su PostgreSQL, Telegram, webhook generico, Mattermost, Slack, Teams, WhatsApp). Gestisce template, preferenze utente, account multi-canale, scheduling e retry, e ripubblica le notifiche in-app in real-time via Core NATS verso il frontend Vue connesso.

Funzionalità principali

• Delivery multi-canale con provider adapter dedicati per ogni canale: email (SMTP/Resend), SMS (Twilio), push (Firebase Cloud Messaging), web-push (VAPID), in-app, Telegram, webhook, Mattermost, Slack, Teams, WhatsApp
• Auto-selezione canale quando il chiamante non specifica channels: il gateway interroga gli account configurati dell'utente e sceglie il primo canale attivo seguendo l'ordine email > sms > in_app > telegram > push > webhook, con fallback finale in-app
• Template engine con variabili interpolate, escape HTML opzionale e caching layered (EnhancedTemplateCacheService); i template sono caricati da repository esterno e validati
• Scheduling e retry delle notifiche con NotificationSchedulingService e NotificationRetryService (retry policy configurabili, backoff esponenziale)
• Preferenze e quiet hours per utente: NotificationPreferenceService, UserChannelConfigService, IntelligentTiming per ottimizzare l'orario di consegna
• Coda JetStream isolata per tenant ({namespace}_NOTIFICATIONS con subject {namespace}.notifications.>): processamento asincrono per canale, ack policy esplicita, dead-letter dopo NATS_WORKER_MAX_DELIVER
• Pub/sub real-time via Core NATS: notifiche in-app ripubblicate su {namespace}.notifications.inapp.user.{userId} e broadcast su {namespace}.notifications.inapp.broadcast per consegna best-effort al browser
• Integrazione orchestrator: registra task come modulo @pzeta/orchestrator-node, esponendo le proprie capability di invio come step richiamabili da workflow
• Analytics di delivery e di coda (AnalyticsService, ChannelAnalyticsApplicationService, @pzeta/queue-analytics), provider health monitoring, log di consegna persistito

Architettura

Stack: Fastify v5 · Inversify (DI con constructor injection) · PostgreSQL via driver pg (no ORM) · NATS 2.x con JetStream · @pzeta/notification-contracts per i contratti inbound · @pzeta/orchestrator-node per l'integrazione con node-orchestrator · @pzeta/fastify-utils (auth, security, errorHandler, healthcheck, openapi, metrics) · @pzeta/log per logging strutturato · Zod per validazione · provider SDK: nodemailer, resend, twilio, firebase-admin, web-push.

Layout DDD (src/):

Pattern adottati: Facade (NotificationServiceFacade aggrega i servizi specializzati), Strategy (selezione provider per canale), Dispatcher (NotificationDispatcher separa la scelta del provider dal flusso applicativo), Repository, Circuit Breaker sui provider esterni, Adapter (un provider per ciascun SDK), DataLoader batching per i template, cache layered (templates / preferenze / provider config / metadata / quick-lookup) con eviction policy configurabile.

Bootstrap: AppBootstrapper esegue in ordine connessione DB, migrazioni schema all'avvio, registrazione servizi nel container Inversify, middleware, security + auth nginx, healthcheck + metrics + OpenAPI, inizializzazione dell'adapter orchestrator (se ORCHESTRATOR_ENABLED=true), avvio del NATSInboundGateway (se NATS_URL configurato), registrazione route e graceful shutdown.

Casi d'uso

• Notifica di completamento workflow: un workflow di node-orchestrator invoca via task il modulo registrato di node-notification per inviare un riepilogo email all'utente, con template caricato da TEMPLATE_API_BASE_URL e variabili interpolate
• Alert oncall multi-canale: un servizio applicativo pubblica su services.notification.send.ditta un messaggio con category: "alert" e priority: 9; il gateway risolve i canali email + SMS + Telegram dell'utente target e li attiva in parallelo con escalation
• Broadcast tenant: un'operazione amministrativa pubblica su {namespace}.notifications.inapp.broadcast un messaggio che tutte le sessioni Vue connesse via NATS-WebSocket ricevono e mostrano in tempo reale
• Notifica utente cross-tab via Core NATS: dopo aver persistito una notifica in-app su PostgreSQL, il servizio chiama publishUserNotification(userId, ...) su {namespace}.notifications.inapp.user.{userId}; tutte le tab del browser dell'utente la ricevono e aggiornano il contatore senza polling
• Reminder schedulato: un client REST chiama POST /notifications con scheduledAt futuro; NotificationSchedulingService la accoda e NotificationRetryService gestisce eventuali fallimenti di consegna con backoff esponenziale e dead-letter dopo N tentativi

Identità & esposizione

Endpoint operazionali

Endpoint convenzionali esposti da tutti i microservizi PZeta basati su @pzeta/fastify-utils:

Configurazione

Variabili d'ambiente che un integratore deve conoscere (per la lista completa vedi EnvironmentPlugin e .env.example del repo):

Il servizio esegue le migrazioni dello schema all'avvio (MigrationService.runMigrations): un deploy con codice nuovo aggiorna automaticamente la base dati.

Note eventing NATS

Il servizio agisce sia come consumer che come producer sul cluster NATS, con tre pattern distinti:

1. Inbound gateway (consumer di contratto pubblico) — NATSInboundGateway si sottoscrive al subject services.notification.send.{namespace} derivato da @pzeta/notification-contracts (buildInboundSubject). I producer (altri microservizi) pubblicano un messaggio conforme a inboundNotificationSchema (Zod) con userId, category, channels opzionali, templateCode o content inline, priority, correlationId. Il gateway valida, risolve canali e delega a NotificationServiceFacade.sendNotification. Se i channels non sono specificati, l'auto-selezione sceglie il primo canale con account attivo per l'utente.
2. JetStream interno (consumer + producer privato) — NATSQueueManager crea uno stream {namespace}_NOTIFICATIONS con subject {namespace}.notifications.{channel}[.urgent|.normal]. Il servizio pubblica il job sul subject del canale (jetStreamClient.publish) e contestualmente è il consumer durable che processa il job invocando il provider corrispondente. Delivery at-least-once con ackWait, maxDeliver e DLQ implicita.
3. Core NATS real-time (producer fire-and-forget) — Le notifiche in-app, dopo la persistenza, vengono ripubblicate su {namespace}.notifications.inapp.user.{userId} (per il singolo utente) o {namespace}.notifications.inapp.broadcast (per tutti i connessi) tramite publishRealtime. Il browser Vue connesso via NATS-WebSocket riceve l'aggiornamento senza polling; se nessun subscriber è connesso il messaggio viene scartato silenziosamente perché la notifica è già persistita in PostgreSQL.

Quando NATS_URL non è configurato il servizio funziona comunque via REST e via integrazione orchestrator: i pattern (1) e (3) sono disabilitati con log warning, e i job sono processati sincronicamente dal NotificationDispatcher.

Dipendenze e dipendenti

Dipende da (servizi che questo servizio chiama):

• node-user-auth

Consumato da (chi chiama questo servizio):

• frontend Vue
• node-orchestrator

Infrastruttura (PostgreSQL, NATS, Redis, MinIO) non è elencata qui — vedi sezione Architettura del singolo servizio.