@feathers-baas/plugin-notifications 0.1.0

package/src/index.ts

@@ -0,0 +1,28 @@
+// Generated by feathers-baas. Safe to edit.
+export { DriverRegistry } from './registry.js'
+export { createBullMQNotifier, createDirectNotifier } from './notifier.js'
+export type { NotifierFn, BullMQNotifierOptions, DirectNotifierOptions } from './notifier.js'
+
+// Queue
+export { createNotificationQueue, enqueueNotification, NOTIFICATION_QUEUE_NAME } from './queue/producer.js'
+export { createNotificationWorker } from './queue/worker.js'
+export type { WorkerOptions } from './queue/worker.js'
+
+// Drivers
+export { SMTPDriver } from './drivers/smtp.driver.js'
+export type { SMTPDriverOptions } from './drivers/smtp.driver.js'
+export { ResendDriver } from './drivers/resend.driver.js'
+export type { ResendDriverOptions } from './drivers/resend.driver.js'
+export { SendGridDriver } from './drivers/sendgrid.driver.js'
+export type { SendGridDriverOptions } from './drivers/sendgrid.driver.js'
+export { BrevoDriver } from './drivers/brevo.driver.js'
+export type { BrevoDriverOptions } from './drivers/brevo.driver.js'
+
+// Types
+export type {
+  Notification,
+  NotifierDriver,
+  NotificationJob,
+  NotificationEvent,
+  AuthNotificationEvent,
+} from './types.js'

package/src/notifier.ts

@@ -0,0 +1,204 @@
+// Generated by feathers-baas. Safe to edit.
+import type { Queue } from 'bullmq'
+import type { NotificationJob, Notification, AuthNotificationEvent } from './types.js'
+import { enqueueNotification } from './queue/producer.js'
+import type { DriverRegistry } from './registry.js'
+
+/**
+ * Auth-management notification types mapped to feathers-baas event keys.
+ * feathers-authentication-management passes these type strings to the notifier.
+ */
+const AUTH_MANAGEMENT_EVENT_MAP: Record<string, AuthNotificationEvent> = {
+  resendVerifySignup: 'auth.resend-verify-signup',
+  verifySignup: 'auth.verify-signup',
+  verifySignupSetPassword: 'auth.verify-signup-set-password',
+  sendResetPwd: 'auth.send-reset-pwd',
+  resetPwd: 'auth.reset-pwd',
+  passwordChange: 'auth.password-change',
+  identityChange: 'auth.identity-change',
+}
+
+/**
+ * Build a default Notification payload for each auth event type.
+ * Templates use EJS — `<%= variable %>` for output, `<% code %>` for logic.
+ */
+function buildAuthNotification(
+  type: AuthNotificationEvent,
+  user: Record<string, unknown>,
+  appUrl: string,
+): Notification | null {
+  const email = user['email'] as string
+  if (!email) return null
+
+  switch (type) {
+    case 'auth.verify-signup':
+    case 'auth.resend-verify-signup': {
+      const token = user['verifyToken'] as string | undefined
+      const verifyUrl = `${appUrl}/verify?token=${token ?? ''}`
+      return {
+        to: email,
+        channel: 'email',
+        subject: 'Verify your email address',
+        bodyTemplate: `
+          <h2>Welcome!</h2>
+          <p>Click the link below to verify your email address:</p>
+          <p><a href="<%= verifyUrl %>">Verify email</a></p>
+          <p>This link expires in 24 hours.</p>
+        `,
+        textTemplate: `Verify your email: <%= verifyUrl %>`,
+        data: { verifyUrl, user },
+      }
+    }
+
+    case 'auth.send-reset-pwd': {
+      const token = user['resetToken'] as string | undefined
+      const resetUrl = `${appUrl}/reset-password?token=${token ?? ''}`
+      return {
+        to: email,
+        channel: 'email',
+        subject: 'Reset your password',
+        bodyTemplate: `
+          <h2>Password reset requested</h2>
+          <p>Click the link below to reset your password:</p>
+          <p><a href="<%= resetUrl %>">Reset password</a></p>
+          <p>This link expires in 2 hours. If you did not request this, ignore this email.</p>
+        `,
+        textTemplate: `Reset your password: <%= resetUrl %>`,
+        data: { resetUrl, user },
+      }
+    }
+
+    case 'auth.reset-pwd': {
+      return {
+        to: email,
+        channel: 'email',
+        subject: 'Your password has been reset',
+        bodyTemplate: `<p>Your password has been successfully reset. If you did not do this, please contact support immediately.</p>`,
+        textTemplate: `Your password has been reset. If you did not do this, please contact support.`,
+        data: { user },
+      }
+    }
+
+    case 'auth.password-change': {
+      return {
+        to: email,
+        channel: 'email',
+        subject: 'Your password has been changed',
+        bodyTemplate: `<p>Your account password was just changed. If this was not you, please contact support immediately.</p>`,
+        textTemplate: `Your password was changed. Contact support if this wasn't you.`,
+        data: { user },
+      }
+    }
+
+    case 'auth.identity-change': {
+      return {
+        to: email,
+        channel: 'email',
+        subject: 'Your email address is being changed',
+        bodyTemplate: `<p>A request was made to change your email address. Click the link to confirm.</p>`,
+        textTemplate: `Confirm your email change by clicking the link in the HTML email.`,
+        data: { user },
+      }
+    }
+
+    case 'auth.verify-signup-set-password': {
+      const token = user['verifyToken'] as string | undefined
+      const verifyUrl = `${appUrl}/verify-set-password?token=${token ?? ''}`
+      return {
+        to: email,
+        channel: 'email',
+        subject: 'Set your password',
+        bodyTemplate: `
+          <h2>Set your password</h2>
+          <p><a href="<%= verifyUrl %>">Set password</a></p>
+        `,
+        textTemplate: `Set your password: <%= verifyUrl %>`,
+        data: { verifyUrl, user },
+      }
+    }
+  }
+}
+
+export type NotifierFn = (
+  type: string,
+  user: Record<string, unknown>,
+  notifierOptions: Record<string, unknown>,
+) => Promise<void>
+
+export interface BullMQNotifierOptions {
+  /** BullMQ Queue instance — from createNotificationQueue(). */
+  queue: Queue<NotificationJob>
+  /** Driver registry — used to determine which drivers handle each event. */
+  registry: DriverRegistry
+  /**
+   * Public base URL of the app, e.g. https://api.example.com
+   * Used to construct verification / reset URLs in email templates.
+   */
+  appUrl: string
+}
+
+/**
+ * Create a notifier function compatible with feathers-authentication-management.
+ *
+ * When an auth event fires (verifySignup, sendResetPwd, etc.), this notifier:
+ * 1. Maps the event type to a feathers-baas notification event key
+ * 2. Looks up all registered drivers for that event
+ * 3. Enqueues one BullMQ job per driver
+ * 4. Returns immediately — delivery is asynchronous
+ *
+ * Wire into the app:
+ * ```ts
+ * app.set('notifier', createBullMQNotifier({ queue, registry, appUrl }))
+ * ```
+ */
+export interface DirectNotifierOptions {
+  /** Driver registry — used to determine which drivers handle each event. */
+  registry: DriverRegistry
+  /** Public base URL of the app. */
+  appUrl: string
+}
+
+/**
+ * Create a notifier that sends notifications directly via the driver (no queue).
+ * Use this when Redis/BullMQ is not available — suitable for API-based drivers
+ * (Brevo, Resend, SendGrid) in development or low-traffic environments.
+ */
+export function createDirectNotifier(opts: DirectNotifierOptions): NotifierFn {
+  return async (type, user, _notifierOptions) => {
+    const eventKey = AUTH_MANAGEMENT_EVENT_MAP[type]
+    if (!eventKey) return
+
+    const notification = buildAuthNotification(eventKey, user, opts.appUrl)
+    if (!notification) return
+
+    const driverNames = opts.registry.getDriversForEvent(eventKey)
+    if (driverNames.length === 0) return
+
+    await Promise.all(
+      driverNames.map(async (driverName) => {
+        const driver = opts.registry.getDriver(driverName)
+        if (!driver) return
+        await driver.send(notification)
+      }),
+    )
+  }
+}
+
+export function createBullMQNotifier(opts: BullMQNotifierOptions): NotifierFn {
+  return async (type, user, _notifierOptions) => {
+    const eventKey = AUTH_MANAGEMENT_EVENT_MAP[type]
+    if (!eventKey) return // Unknown event type — no-op
+
+    const notification = buildAuthNotification(eventKey, user, opts.appUrl)
+    if (!notification) return // Missing required user fields — no-op
+
+    const driverNames = opts.registry.getDriversForEvent(eventKey)
+    if (driverNames.length === 0) return // No drivers configured for this event
+
+    await Promise.all(
+      driverNames.map((driverName) =>
+        enqueueNotification(opts.queue, { driverName, notification }),
+      ),
+    )
+  }
+}

package/src/queue/producer.ts

@@ -0,0 +1,44 @@
+// Generated by feathers-baas. Safe to edit.
+import { Queue } from 'bullmq'
+import type { Redis } from 'ioredis'
+import type { NotificationJob } from '../types.js'
+
+export const NOTIFICATION_QUEUE_NAME = 'feathers-baas:notifications'
+
+/**
+ * Create a BullMQ Queue instance for notification jobs.
+ *
+ * @example
+ * ```ts
+ * const redis = new Redis(process.env.REDIS_URL)
+ * const queue = createNotificationQueue(redis)
+ * await enqueueNotification(queue, { driverName: 'smtp', notification: { ... } })
+ * ```
+ */
+export function createNotificationQueue(redis: Redis): Queue<NotificationJob> {
+  return new Queue<NotificationJob>(NOTIFICATION_QUEUE_NAME, {
+    connection: redis,
+    defaultJobOptions: {
+      attempts: 5,
+      backoff: {
+        type: 'exponential',
+        delay: 1_000, // initial delay: 1s → 2s → 4s → 8s → 16s
+      },
+      removeOnComplete: { count: 100 },
+      removeOnFail: { count: 500 },
+    },
+  })
+}
+
+/**
+ * Enqueue a notification job.
+ *
+ * @param queue  BullMQ Queue instance from createNotificationQueue()
+ * @param job    Job payload { driverName, notification }
+ */
+export async function enqueueNotification(
+  queue: Queue<NotificationJob>,
+  job: NotificationJob,
+): Promise<void> {
+  await queue.add('send', job)
+}

package/src/queue/worker.ts

@@ -0,0 +1,66 @@
+// Generated by feathers-baas. Safe to edit.
+import { Worker } from 'bullmq'
+import type { Redis } from 'ioredis'
+import type { DriverRegistry } from '../registry.js'
+import type { NotificationJob } from '../types.js'
+import { NOTIFICATION_QUEUE_NAME } from './producer.js'
+
+export interface WorkerOptions {
+  /** BullMQ concurrency — number of jobs processed in parallel. */
+  concurrency?: number
+}
+
+/**
+ * Create and start the BullMQ worker that processes notification jobs.
+ *
+ * The worker looks up the driver from the registry by name, renders the
+ * EJS template, and calls driver.send(). BullMQ handles retries with
+ * exponential back-off automatically.
+ *
+ * Call worker.close() during graceful shutdown to drain in-flight jobs.
+ *
+ * @example
+ * ```ts
+ * const worker = createNotificationWorker(registry, redis, { concurrency: 5 })
+ *
+ * process.on('SIGTERM', async () => {
+ *   await worker.close()
+ * })
+ * ```
+ */
+export function createNotificationWorker(
+  registry: DriverRegistry,
+  redis: Redis,
+  opts: WorkerOptions = {},
+): Worker<NotificationJob> {
+  const concurrency = opts.concurrency ?? 5
+
+  const worker = new Worker<NotificationJob>(
+    NOTIFICATION_QUEUE_NAME,
+    async (job) => {
+      const { driverName, notification } = job.data
+
+      const driver = registry.getDriver(driverName)
+      if (!driver) {
+        throw new Error(`Notification driver "${driverName}" is not registered`)
+      }
+
+      await driver.send(notification)
+    },
+    {
+      connection: redis,
+      concurrency,
+      // Don't create a new redis connection per job — reuse the pool
+      autorun: true,
+    },
+  )
+
+  worker.on('failed', (job, err) => {
+    // BullMQ handles retries; this is just for observability
+    const jobId = job?.id ?? 'unknown'
+    const message = err instanceof Error ? err.message : String(err)
+    console.error(`[notifications] Job ${jobId} failed: ${message}`)
+  })
+
+  return worker
+}

package/src/registry.ts

@@ -0,0 +1,51 @@
+// Generated by feathers-baas. Safe to edit.
+import type { NotifierDriver, NotificationEvent } from './types.js'
+
+/**
+ * DriverRegistry maps event keys to the list of drivers that should handle
+ * that event.
+ *
+ * A single driver instance can handle multiple events (e.g. the SMTP driver
+ * handles all auth.* email events).
+ *
+ * @example
+ * ```ts
+ * const registry = new DriverRegistry()
+ * registry.registerDriver(smtpDriver)
+ * registry.mapEvent('auth.verify-signup', 'smtp')
+ * registry.mapEvent('auth.send-reset-pwd', 'smtp')
+ * ```
+ */
+export class DriverRegistry {
+  private readonly drivers = new Map<string, NotifierDriver>()
+  private readonly eventMap = new Map<NotificationEvent, string[]>()
+
+  /** Register a driver under its name. Overwrites any existing driver with the same name. */
+  registerDriver(driver: NotifierDriver): void {
+    this.drivers.set(driver.name, driver)
+  }
+
+  /** Map a notification event to a driver name. Multiple calls for the same event add drivers. */
+  mapEvent(event: NotificationEvent, driverName: string): void {
+    const existing = this.eventMap.get(event) ?? []
+    if (!existing.includes(driverName)) {
+      existing.push(driverName)
+    }
+    this.eventMap.set(event, existing)
+  }
+
+  /** Look up a driver by name. Returns undefined if not registered. */
+  getDriver(name: string): NotifierDriver | undefined {
+    return this.drivers.get(name)
+  }
+
+  /** Get all driver names mapped to the given event. */
+  getDriversForEvent(event: NotificationEvent): string[] {
+    return this.eventMap.get(event) ?? []
+  }
+
+  /** All registered driver names. */
+  listDriverNames(): string[] {
+    return [...this.drivers.keys()]
+  }
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+// Generated by feathers-baas. Safe to edit.
+
+/**
+ * A single notification to be delivered to one recipient.
+ * Templates are EJS strings — the worker renders them just before sending.
+ */
+export interface Notification {
+  /** Recipient address — email address, phone number, device token, etc. */
+  to: string
+  /** Notification channel — determines which driver handles delivery. */
+  channel: 'email' | 'sms' | 'push' | 'webhook'
+  /** Email subject line (email channel only). */
+  subject?: string
+  /** EJS template string for the message body. */
+  bodyTemplate: string
+  /** Variables injected into the EJS template at render time. */
+  data: Record<string, unknown>
+  /** Optional plain-text fallback for HTML email. */
+  textTemplate?: string
+}
+
+/**
+ * A named notification driver — responsible for delivering one channel.
+ * Drivers are registered in the DriverRegistry and looked up by name at
+ * job processing time.
+ */
+export interface NotifierDriver {
+  /** Unique name used as the registry key (e.g. 'smtp', 'resend'). */
+  readonly name: string
+  /** Deliver the notification to the recipient. */
+  send(notification: Notification): Promise<void>
+}
+
+/**
+ * Payload stored inside each BullMQ job.
+ * Worker resolves driverName → NotifierDriver from the registry.
+ */
+export interface NotificationJob {
+  driverName: string
+  notification: Notification
+}
+
+/**
+ * Maps auth-management event types to a human-readable event key used in
+ * the notification event→driver registry.
+ */
+export type AuthNotificationEvent =
+  | 'auth.resend-verify-signup'
+  | 'auth.verify-signup'
+  | 'auth.verify-signup-set-password'
+  | 'auth.send-reset-pwd'
+  | 'auth.reset-pwd'
+  | 'auth.password-change'
+  | 'auth.identity-change'
+
+/** Union of all supported notification event keys. */
+export type NotificationEvent = AuthNotificationEvent | string

package/test/drivers/brevo.driver.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// ─── Mock @getbrevo/brevo ─────────────────────────────────────────────────────
+
+const mockSendTransacEmail = vi.fn()
+
+vi.mock('@getbrevo/brevo', () => {
+  return {
+    TransactionalEmailsApiApiKeys: { apiKey: 0, partnerKey: 1 },
+    TransactionalEmailsApi: vi.fn().mockImplementation(() => ({
+      setApiKey: vi.fn(),
+      sendTransacEmail: mockSendTransacEmail,
+    })),
+    SendSmtpEmail: vi.fn().mockImplementation(() => ({})),
+  }
+})
+
+// ─── Imports after mocking ────────────────────────────────────────────────────
+
+import { BrevoDriver } from '../../src/drivers/brevo.driver.js'
+import type { Notification } from '../../src/types.js'
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('BrevoDriver', () => {
+  let driver: BrevoDriver
+
+  beforeEach(() => {
+    mockSendTransacEmail.mockReset()
+    mockSendTransacEmail.mockResolvedValue({ messageId: '<msg-abc@smtp-relay.sendinblue.com>' })
+    driver = new BrevoDriver({
+      apiKey: 'xkeysib-test',
+      fromName: 'Feathers BaaS',
+      fromAddress: 'no-reply@example.com',
+    })
+  })
+
+  it('has the correct driver name', () => {
+    expect(driver.name).toBe('brevo')
+  })
+
+  describe('send', () => {
+    it('calls sendTransacEmail once per notification', async () => {
+      const notification: Notification = {
+        to: 'recipient@example.com',
+        channel: 'email',
+        subject: 'Welcome!',
+        bodyTemplate: '<h1>Hello, <%= name %></h1>',
+        data: { name: 'Alice' },
+      }
+
+      await driver.send(notification)
+
+      expect(mockSendTransacEmail).toHaveBeenCalledOnce()
+    })
+
+    it('sets htmlContent with rendered EJS', async () => {
+      const notification: Notification = {
+        to: 'user@example.com',
+        channel: 'email',
+        bodyTemplate: '<p>Hello, <%= user %>!</p>',
+        data: { user: 'Bob' },
+      }
+
+      await driver.send(notification)
+
+      // The email object is mutated in-place by the driver before calling send
+      const emailArg = mockSendTransacEmail.mock.calls[0]?.[0] as Record<string, unknown>
+      expect(emailArg['htmlContent']).toBe('<p>Hello, Bob!</p>')
+    })
+
+    it('sets textContent when textTemplate is provided', async () => {
+      const notification: Notification = {
+        to: 'user@example.com',
+        channel: 'email',
+        bodyTemplate: '<p><%= msg %></p>',
+        textTemplate: 'Plain: <%= msg %>',
+        data: { msg: 'hi' },
+      }
+
+      await driver.send(notification)
+
+      const emailArg = mockSendTransacEmail.mock.calls[0]?.[0] as Record<string, unknown>
+      expect(emailArg['textContent']).toBe('Plain: hi')
+    })
+
+    it('does not set textContent when no textTemplate is given', async () => {
+      const notification: Notification = {
+        to: 'user@example.com',
+        channel: 'email',
+        bodyTemplate: '<p>HTML only</p>',
+        data: {},
+      }
+
+      await driver.send(notification)
+
+      const emailArg = mockSendTransacEmail.mock.calls[0]?.[0] as Record<string, unknown>
+      expect(emailArg['textContent']).toBeUndefined()
+    })
+
+    it('falls back to "(no subject)" when subject is not provided', async () => {
+      const notification: Notification = {
+        to: 'user@example.com',
+        channel: 'email',
+        bodyTemplate: 'body',
+        data: {},
+      }
+
+      await driver.send(notification)
+
+      const emailArg = mockSendTransacEmail.mock.calls[0]?.[0] as Record<string, unknown>
+      expect(emailArg['subject']).toBe('(no subject)')
+    })
+  })
+})

package/test/drivers/resend.driver.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// ─── Mock resend SDK ──────────────────────────────────────────────────────────
+
+const mockEmailsSend = vi.fn()
+
+vi.mock('resend', () => ({
+  Resend: vi.fn().mockImplementation(() => ({
+    emails: { send: mockEmailsSend },
+  })),
+}))
+
+// ─── Imports after mocking ────────────────────────────────────────────────────
+
+import { ResendDriver } from '../../src/drivers/resend.driver.js'
+import type { Notification } from '../../src/types.js'
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('ResendDriver', () => {
+  let driver: ResendDriver
+
+  beforeEach(() => {
+    mockEmailsSend.mockReset()
+    mockEmailsSend.mockResolvedValue({ data: { id: 'msg-abc' }, error: null })
+    driver = new ResendDriver({
+      apiKey: 're_test_key',
+      fromName: 'Feathers BaaS',
+      fromAddress: 'no-reply@example.com',
+    })
+  })
+
+  it('has the correct driver name', () => {
+    expect(driver.name).toBe('resend')
+  })
+
+  describe('send', () => {
+    it('calls emails.send with rendered HTML and correct fields', async () => {
+      const notification: Notification = {
+        to: 'recipient@example.com',
+        channel: 'email',
+        subject: 'Welcome!',
+        bodyTemplate: '<h1>Hello, <%= name %></h1>',
+        data: { name: 'Alice' },
+      }
+
+      await driver.send(notification)
+
+      expect(mockEmailsSend).toHaveBeenCalledOnce()
+      const arg = mockEmailsSend.mock.calls[0]?.[0] as Record<string, unknown>
+      expect(arg['to']).toEqual(['recipient@example.com'])
+      expect(arg['from']).toBe('Feathers BaaS <no-reply@example.com>')
+      expect(arg['subject']).toBe('Welcome!')
+      expect(arg['html']).toBe('<h1>Hello, Alice</h1>')
+    })
+
+    it('renders the text template when provided', async () => {
+      const notification: Notification = {
+        to: 'user@example.com',
+        channel: 'email',
+        bodyTemplate: '<p><%= msg %></p>',
+        textTemplate: 'Plain: <%= msg %>',
+        data: { msg: 'test' },
+      }
+
+      await driver.send(notification)
+
+      const arg = mockEmailsSend.mock.calls[0]?.[0] as Record<string, unknown>
+      expect(arg['text']).toBe('Plain: test')
+    })
+
+    it('omits text when no textTemplate is given', async () => {
+      const notification: Notification = {
+        to: 'user@example.com',
+        channel: 'email',
+        bodyTemplate: '<p>HTML only</p>',
+        data: {},
+      }
+
+      await driver.send(notification)
+
+      const arg = mockEmailsSend.mock.calls[0]?.[0] as Record<string, unknown>
+      expect(arg['text']).toBeUndefined()
+    })
+
+    it('falls back to "(no subject)" when subject is not provided', async () => {
+      const notification: Notification = {
+        to: 'user@example.com',
+        channel: 'email',
+        bodyTemplate: 'body',
+        data: {},
+      }
+
+      await driver.send(notification)
+
+      const arg = mockEmailsSend.mock.calls[0]?.[0] as Record<string, unknown>
+      expect(arg['subject']).toBe('(no subject)')
+    })
+
+    it('throws when the Resend API returns an error', async () => {
+      mockEmailsSend.mockResolvedValueOnce({
+        data: null,
+        error: { message: 'Invalid API key', name: 'validation_error' },
+      })
+
+      const notification: Notification = {
+        to: 'user@example.com',
+        channel: 'email',
+        bodyTemplate: 'body',
+        data: {},
+      }
+
+      await expect(driver.send(notification)).rejects.toThrow(/Invalid API key/)
+    })
+  })
+})