Notification Channels

Job received
  |
  +-> filterRecipientsForDev(recipients, "email")
  |     dev/test: drop addresses whose domain is not in DEV_ALLOWED_EMAIL_DOMAINS
  |     production/staging: pass all through
  |     empty result -> return { status: "skipped_dev_filter" }
  |
  +-> resolveEmailProvider(tenantId)
  |     tenant verified row -> SmtpProvider | SendGridProvider | SesProvider
  |     none/unverified     -> SendGridProvider (platform default)
  |
  +-> loadEmailTemplate(templateSlug ?? type, tenantId)
  |     in-memory cache (1 min TTL)
  |     DB: email_template WHERE slug = ? AND (tenantId = ? OR tenantId IS NULL)
  |         ORDER BY tenantId DESC  (tenant row sorts first)
  |     returns { subject, html, text }
  |
  +-> renderTemplate(subject | html | text, variables)
  |     Handlebars.compile(template, { noEscape: true })(variables)
  |
  +-> provider.send({ to, subject, html, text })
  |     returns { messageId }
  |
  +-> return { status: "sent", messageId }

model EmailTemplate {
  id        String   @id @default(cuid())
  tenantId  String?  // null = platform default
  slug      String   // e.g. "welcome", "approval_required"
  subject   String
  htmlBody  String   @db.Text
  textBody  String   @db.Text
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
 
  @@unique([tenantId, slug])
  @@map("email_template")
}

// whatsapp-templates.ts
export const WHATSAPP_TEMPLATES: Partial<Record<NotificationType, WhatsAppTemplateConfig>> = {
  approval_required: { name: "leadmetrics_approval_required", languageCode: "en", paramKeys: [...] },
  // ...
};

Job received
  |
  +-> filterRecipientsForDev(recipients, "whatsapp")
  |     dev: keep only phone numbers starting with DEV_ALLOWED_PHONE_PREFIX
  |
  +-> getWhatsAppTemplate(type)   (from whatsapp-templates.ts)
  |     no entry -> return { status: "no_template" }
  |
  +-> resolveWhatsAppProvider(tenantId)
  |
  +-> per-recipient: provider.sendTemplate({ to: phone, template: { name, languageCode }, variables })
  |     Promise.allSettled � partial success allowed
  |
  +-> return { status: "sent" | "partial", sent: N }

Job received
  |
  +-> targets = recipients.length > 0          (ops fallback BEFORE dev filter)
  |       ? recipients
  |       : [{ name: "ops", chatId: TELEGRAM_DEFAULT_CHAT_ID }]
  |
  +-> filterRecipientsForDev(targets, "telegram")
  |     empty -> return { status: "skipped_dev_filter", sent: 0 }
  |
  +-> resolveTelegramProvider(tenantId)
  |
  +-> getTelegramTemplate(type)                (from telegram-templates.ts)
  |     fallback: "[<type>]" literal
  +-> renderTemplate(templateStr, variables)   -> HTML string
  |
  +-> per-target: provider.send({ chatId, text, parseMode: "HTML" })
  |     Promise.allSettled — partial success allowed
  |
  +-> return { status: "sent" | "partial", sent: N }

const SMS_TEMPLATES: Partial<Record<string, (vars: Record<string, string>) => string>> = {
  credits_exhausted: (v) =>
    `Leadmetrics: Credit limit reached. ${v.pausedActivities} activities paused. Top up at ${v.topupUrl}`,
  credits_warning_80: (v) =>
    `Leadmetrics: ${v.creditsUsed}/${v.creditsTotal} credits used. ${v.creditsRemaining} remaining until ${v.resetDate}`,
  payment_failed: (v) =>
    `Leadmetrics: Payment of Rs.${v.amountInr} failed. Update billing at ${v.billingUrl}`,
  pipeline_blocked: (v) =>
    `Leadmetrics: Pipeline blocked � "${v.blockedTaskTitle}". View at ${v.pipelineUrl}`,
};

Job received
  |
  +-> renderTemplate("web_<type>", variables)   -> short message string
  |
  +-> per-recipient: db.notification.create({
  |     tenantId, userId, type, message, refId, refType, read: false
  |   })
  |     failure: log.warn + continue (soft fail � don't retry for a DB insert error)
  |
  +-> if NOTIFICATION_HUB_URL && NOTIFICATION_HUB_KEY:
  |     POST <hub>/push { tenantId, type, message, recipients: [userId, ...] }
  |     Headers: { x-hub-key: NOTIFICATION_HUB_KEY }
  |     -> triggers SSE push to open Dashboard tabs
  |     best-effort: hub offline -> notification persisted, no live push
  |
  +-> return { status: "sent" }

model Notification {
  id        String    @id @default(cuid())
  tenantId  String
  userId    String?
  type      String
  channel   String    @default("web")
  title     String
  message   String    @db.Text
  refId     String?
  refType   String?
  read      Boolean   @default(false)
  readAt    DateTime?
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
 
  @@index([tenantId, userId, read])
  @@index([tenantId, createdAt])
  @@map("notification")
}