servers/notifications � @leadmetrics/server-notifications

Platform services (API, BullMQ cron jobs, agent workers)
        |
        |  enqueueNotification(...)   <-- @leadmetrics/queue
        v
Redis (BullMQ)
  |-- notifications__email      <- EmailHandler     (concurrency 10)
  |-- notifications__whatsapp   <- WhatsAppHandler  (concurrency 3)
  |-- notifications__telegram   <- TelegramHandler  (concurrency 5)
  |-- notifications__sms        <- SmsHandler       (concurrency 2, stub)
  +-- notifications__web        <- WebHandler       (concurrency 20)
        |
        v
apps/servers/notifications (this service)
  |-- EmailHandler    -> resolveEmailProvider()    -> SendGrid / SMTP / SES
  |-- WhatsAppHandler -> resolveWhatsAppProvider() -> Meta Graph API
  |-- TelegramHandler -> resolveTelegramProvider() -> Telegram Bot API
  |-- SmsHandler      -> stub (awaiting provider-msg91 / provider-twilio)
  +-- WebHandler      -> notification DB table + optional SSE push hub

import { enqueueNotification } from "@leadmetrics/queue";
 
await enqueueNotification({
  tenantId:     "clxxx...",
  channel:      "email",
  type:         "welcome",
  templateSlug: "welcome",
  priority:     "high",
  recipients:   [{ userId, name: "John Smith", email: "john@acme.com" }],
  variables:    { firstName: "John", companyName: "Acme", dashboardUrl: "https://..." },
  dedupeKey:    `welcome__${tenantId}`,  // prevents duplicate on re-enqueue
});

interface NotificationJobData {
  id:           string;                 // BullMQ jobId � used for deduplication
  tenantId:     string;
  channel:      "email" | "sms" | "whatsapp" | "telegram" | "web";
  type:         string;                 // NotificationType � drives template selection
  priority:     "high" | "normal" | "low";
  recipients:   Array<{
    userId?:  string;                   // platform user ID
    name:     string;
    email?:   string;                   // required for email
    phone?:   string;                   // E.164 � required for sms / whatsapp
    chatId?:  string | number;          // required for telegram
    locale?:  string;                   // e.g. "en", "ta"
  }>;
  templateSlug: string;                 // DB email_template.slug or template map key
  variables:    Record<string, string>; // Handlebars {{variable}} context
  dedupeKey?:   string;
  metadata?:    Record<string, string>; // arbitrary logging context (refId, refType, ...)
}