@feathers-baas/plugin-notifications 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,252 @@
+import { Queue, Worker } from 'bullmq';
+import { Redis } from 'ioredis';
+
+/**
+ * A single notification to be delivered to one recipient.
+ * Templates are EJS strings — the worker renders them just before sending.
+ */
+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.
+ */
+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.
+ */
+interface NotificationJob {
+    driverName: string;
+    notification: Notification;
+}
+/**
+ * Maps auth-management event types to a human-readable event key used in
+ * the notification event→driver registry.
+ */
+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. */
+type NotificationEvent = AuthNotificationEvent | string;
+
+/**
+ * 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')
+ * ```
+ */
+declare class DriverRegistry {
+    private readonly drivers;
+    private readonly eventMap;
+    /** Register a driver under its name. Overwrites any existing driver with the same name. */
+    registerDriver(driver: NotifierDriver): void;
+    /** Map a notification event to a driver name. Multiple calls for the same event add drivers. */
+    mapEvent(event: NotificationEvent, driverName: string): void;
+    /** Look up a driver by name. Returns undefined if not registered. */
+    getDriver(name: string): NotifierDriver | undefined;
+    /** Get all driver names mapped to the given event. */
+    getDriversForEvent(event: NotificationEvent): string[];
+    /** All registered driver names. */
+    listDriverNames(): string[];
+}
+
+type NotifierFn = (type: string, user: Record<string, unknown>, notifierOptions: Record<string, unknown>) => Promise<void>;
+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 }))
+ * ```
+ */
+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.
+ */
+declare function createDirectNotifier(opts: DirectNotifierOptions): NotifierFn;
+declare function createBullMQNotifier(opts: BullMQNotifierOptions): NotifierFn;
+
+declare 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: { ... } })
+ * ```
+ */
+declare function createNotificationQueue(redis: Redis): Queue<NotificationJob>;
+/**
+ * Enqueue a notification job.
+ *
+ * @param queue  BullMQ Queue instance from createNotificationQueue()
+ * @param job    Job payload { driverName, notification }
+ */
+declare function enqueueNotification(queue: Queue<NotificationJob>, job: NotificationJob): Promise<void>;
+
+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()
+ * })
+ * ```
+ */
+declare function createNotificationWorker(registry: DriverRegistry, redis: Redis, opts?: WorkerOptions): Worker<NotificationJob>;
+
+interface SMTPDriverOptions {
+    /** SMTP connection URL, e.g. smtp://user:pass@mail.example.com:587 */
+    url: string;
+    /** Display name shown in the From field. */
+    fromName: string;
+    /** Email address shown in the From field. */
+    fromAddress: string;
+}
+/**
+ * Email driver backed by nodemailer over SMTP.
+ * Templates are rendered with EJS at send time.
+ *
+ * Use this driver for self-hosted SMTP servers (Postfix, Mailtrap, etc.).
+ * For transactional email services, prefer ResendDriver.
+ */
+declare class SMTPDriver implements NotifierDriver {
+    private readonly opts;
+    readonly name = "smtp";
+    private readonly transporter;
+    constructor(opts: SMTPDriverOptions);
+    send(notification: Notification): Promise<void>;
+    /** Verify SMTP connectivity. Throws if the server is unreachable. */
+    verify(): Promise<void>;
+    /** Close the underlying connection pool. */
+    close(): void;
+}
+
+interface ResendDriverOptions {
+    /** Resend API key (from https://resend.com/api-keys). */
+    apiKey: string;
+    /** Display name shown in the From field. */
+    fromName: string;
+    /** Verified sender address. Must be a verified domain in your Resend account. */
+    fromAddress: string;
+}
+/**
+ * Email driver backed by the Resend transactional email API.
+ * Templates are rendered with EJS at send time.
+ *
+ * Resend offers generous free tier and excellent deliverability,
+ * making it the recommended choice for new projects.
+ */
+declare class ResendDriver implements NotifierDriver {
+    private readonly opts;
+    readonly name = "resend";
+    private readonly client;
+    constructor(opts: ResendDriverOptions);
+    send(notification: Notification): Promise<void>;
+}
+
+interface SendGridDriverOptions {
+    /** SendGrid API key (from https://app.sendgrid.com/settings/api_keys). */
+    apiKey: string;
+    /** Display name shown in the From field. */
+    fromName: string;
+    /** Verified sender address. Must be verified in your SendGrid account. */
+    fromAddress: string;
+}
+/**
+ * Email driver backed by the SendGrid API.
+ * Templates are rendered with EJS at send time.
+ */
+declare class SendGridDriver implements NotifierDriver {
+    private readonly opts;
+    readonly name = "sendgrid";
+    constructor(opts: SendGridDriverOptions);
+    send(notification: Notification): Promise<void>;
+}
+
+interface BrevoDriverOptions {
+    /** Brevo API key (from https://app.brevo.com/settings/keys/api). */
+    apiKey: string;
+    /** Display name shown in the From field. */
+    fromName: string;
+    /** Verified sender address. Must be verified in your Brevo account. */
+    fromAddress: string;
+}
+/**
+ * Email driver backed by the Brevo (formerly Sendinblue) Transactional Email API.
+ * Templates are rendered with EJS at send time.
+ */
+declare class BrevoDriver implements NotifierDriver {
+    private readonly opts;
+    readonly name = "brevo";
+    private readonly apiInstance;
+    constructor(opts: BrevoDriverOptions);
+    send(notification: Notification): Promise<void>;
+}
+
+export { type AuthNotificationEvent, BrevoDriver, type BrevoDriverOptions, type BullMQNotifierOptions, type DirectNotifierOptions, DriverRegistry, NOTIFICATION_QUEUE_NAME, type Notification, type NotificationEvent, type NotificationJob, type NotifierDriver, type NotifierFn, ResendDriver, type ResendDriverOptions, SMTPDriver, type SMTPDriverOptions, SendGridDriver, type SendGridDriverOptions, type WorkerOptions, createBullMQNotifier, createDirectNotifier, createNotificationQueue, createNotificationWorker, enqueueNotification };

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+import { Queue, Worker } from 'bullmq';
+import { Redis } from 'ioredis';
+
+/**
+ * A single notification to be delivered to one recipient.
+ * Templates are EJS strings — the worker renders them just before sending.
+ */
+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.
+ */
+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.
+ */
+interface NotificationJob {
+    driverName: string;
+    notification: Notification;
+}
+/**
+ * Maps auth-management event types to a human-readable event key used in
+ * the notification event→driver registry.
+ */
+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. */
+type NotificationEvent = AuthNotificationEvent | string;
+
+/**
+ * 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')
+ * ```
+ */
+declare class DriverRegistry {
+    private readonly drivers;
+    private readonly eventMap;
+    /** Register a driver under its name. Overwrites any existing driver with the same name. */
+    registerDriver(driver: NotifierDriver): void;
+    /** Map a notification event to a driver name. Multiple calls for the same event add drivers. */
+    mapEvent(event: NotificationEvent, driverName: string): void;
+    /** Look up a driver by name. Returns undefined if not registered. */
+    getDriver(name: string): NotifierDriver | undefined;
+    /** Get all driver names mapped to the given event. */
+    getDriversForEvent(event: NotificationEvent): string[];
+    /** All registered driver names. */
+    listDriverNames(): string[];
+}
+
+type NotifierFn = (type: string, user: Record<string, unknown>, notifierOptions: Record<string, unknown>) => Promise<void>;
+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 }))
+ * ```
+ */
+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.
+ */
+declare function createDirectNotifier(opts: DirectNotifierOptions): NotifierFn;
+declare function createBullMQNotifier(opts: BullMQNotifierOptions): NotifierFn;
+
+declare 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: { ... } })
+ * ```
+ */
+declare function createNotificationQueue(redis: Redis): Queue<NotificationJob>;
+/**
+ * Enqueue a notification job.
+ *
+ * @param queue  BullMQ Queue instance from createNotificationQueue()
+ * @param job    Job payload { driverName, notification }
+ */
+declare function enqueueNotification(queue: Queue<NotificationJob>, job: NotificationJob): Promise<void>;
+
+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()
+ * })
+ * ```
+ */
+declare function createNotificationWorker(registry: DriverRegistry, redis: Redis, opts?: WorkerOptions): Worker<NotificationJob>;
+
+interface SMTPDriverOptions {
+    /** SMTP connection URL, e.g. smtp://user:pass@mail.example.com:587 */
+    url: string;
+    /** Display name shown in the From field. */
+    fromName: string;
+    /** Email address shown in the From field. */
+    fromAddress: string;
+}
+/**
+ * Email driver backed by nodemailer over SMTP.
+ * Templates are rendered with EJS at send time.
+ *
+ * Use this driver for self-hosted SMTP servers (Postfix, Mailtrap, etc.).
+ * For transactional email services, prefer ResendDriver.
+ */
+declare class SMTPDriver implements NotifierDriver {
+    private readonly opts;
+    readonly name = "smtp";
+    private readonly transporter;
+    constructor(opts: SMTPDriverOptions);
+    send(notification: Notification): Promise<void>;
+    /** Verify SMTP connectivity. Throws if the server is unreachable. */
+    verify(): Promise<void>;
+    /** Close the underlying connection pool. */
+    close(): void;
+}
+
+interface ResendDriverOptions {
+    /** Resend API key (from https://resend.com/api-keys). */
+    apiKey: string;
+    /** Display name shown in the From field. */
+    fromName: string;
+    /** Verified sender address. Must be a verified domain in your Resend account. */
+    fromAddress: string;
+}
+/**
+ * Email driver backed by the Resend transactional email API.
+ * Templates are rendered with EJS at send time.
+ *
+ * Resend offers generous free tier and excellent deliverability,
+ * making it the recommended choice for new projects.
+ */
+declare class ResendDriver implements NotifierDriver {
+    private readonly opts;
+    readonly name = "resend";
+    private readonly client;
+    constructor(opts: ResendDriverOptions);
+    send(notification: Notification): Promise<void>;
+}
+
+interface SendGridDriverOptions {
+    /** SendGrid API key (from https://app.sendgrid.com/settings/api_keys). */
+    apiKey: string;
+    /** Display name shown in the From field. */
+    fromName: string;
+    /** Verified sender address. Must be verified in your SendGrid account. */
+    fromAddress: string;
+}
+/**
+ * Email driver backed by the SendGrid API.
+ * Templates are rendered with EJS at send time.
+ */
+declare class SendGridDriver implements NotifierDriver {
+    private readonly opts;
+    readonly name = "sendgrid";
+    constructor(opts: SendGridDriverOptions);
+    send(notification: Notification): Promise<void>;
+}
+
+interface BrevoDriverOptions {
+    /** Brevo API key (from https://app.brevo.com/settings/keys/api). */
+    apiKey: string;
+    /** Display name shown in the From field. */
+    fromName: string;
+    /** Verified sender address. Must be verified in your Brevo account. */
+    fromAddress: string;
+}
+/**
+ * Email driver backed by the Brevo (formerly Sendinblue) Transactional Email API.
+ * Templates are rendered with EJS at send time.
+ */
+declare class BrevoDriver implements NotifierDriver {
+    private readonly opts;
+    readonly name = "brevo";
+    private readonly apiInstance;
+    constructor(opts: BrevoDriverOptions);
+    send(notification: Notification): Promise<void>;
+}
+
+export { type AuthNotificationEvent, BrevoDriver, type BrevoDriverOptions, type BullMQNotifierOptions, type DirectNotifierOptions, DriverRegistry, NOTIFICATION_QUEUE_NAME, type Notification, type NotificationEvent, type NotificationJob, type NotifierDriver, type NotifierFn, ResendDriver, type ResendDriverOptions, SMTPDriver, type SMTPDriverOptions, SendGridDriver, type SendGridDriverOptions, type WorkerOptions, createBullMQNotifier, createDirectNotifier, createNotificationQueue, createNotificationWorker, enqueueNotification };