@nathapp/nestjs-notification

Multi-channel notification library for NestJS — Email, SMS, WhatsApp, and Push — with a consistent abstract-provider extension model per channel.

Installation

npm install @nathapp/nestjs-notification

This package is part of the @nathapp/nestjs-* peer-layer stack and builds on @nathapp/nestjs-common.

Channels

Every channel follows the same pattern: an abstract XxxProvider base class that external packages/consumers extend, and an injectable XxxService wrapper that consumers inject and that resolves the provider via its DI token.

| Channel | Provider base class | Service | Injection token | |-----------|-----------------------------|--------------------------|------------------------------| | email | EmailProvider | EmailService | EMAIL_PROVIDER | | sms | SmsProvider | SmsService | SMS_PROVIDER | | whatsapp | WhatsAppProvider | WhatsAppService | WHATSAPP_PROVIDER | | push | PushNotificationProvider | PushNotificationService| PUSH_NOTIFICATION_PROVIDERS|

Push is special-cased: it supports multiple simultaneous providers (e.g. Android + iOS + Huawei) via ProviderManager, and providers additionally implement sendMulticast(tokens, message) for efficient batch sends. Push also has IUserTokenStore / UserTokenStore for mapping users to device tokens (InMemoryUserTokenStore ships as the default).

Providers

SmtpEmailProvider (nodemailer-backed) and FCMPushNotificationProvider (Firebase Cloud Messaging) are built in for convenience. Concrete third-party providers for other services live in separate packages — @nathapp/nestjs-notification-twilio, @nathapp/nestjs-notification-sns, @nathapp/nestjs-notification-brevo, @nathapp/nestjs-notification-ses, @nathapp/nestjs-notification-twilio-whatsapp — each exporting a class that extends the corresponding XxxProvider base class from this package.

A templating system (TemplateService, TemplateLoader, TemplateEngine) is also included, with {{variable}}-style interpolation via StringFormatEngine (not Handlebars/EJS) and a FakeTemplateLoader default.

Usage

import { Module } from '@nestjs/common';
import { NotificationModule, SmtpEmailProvider } from '@nathapp/nestjs-notification';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    NotificationModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        providers: [
          {
            channel: 'email',
            provider: SmtpEmailProvider,
            options: { url: config.get('SMTP_URL'), from: '[email protected]' },
          },
        ],
      }),
    }),
  ],
})
export class AppModule {}

Consuming a channel service elsewhere in the app:

import { Injectable } from '@nestjs/common';
import { EmailService } from '@nathapp/nestjs-notification';

@Injectable()
export class WelcomeMailer {
  constructor(private readonly email: EmailService) {}

  async send(to: string) {
    return this.email.send({
      recipient: to,
      subject: 'Welcome',
      message: '<p>Thanks for signing up!</p>',
    });
  }
}

Extending a channel with a custom provider (or wiring one of the @nathapp/nestjs-notification-* packages):

import { EmailProvider, EmailMessage, SendResult } from '@nathapp/nestjs-notification';

export class MailgunEmailProvider extends EmailProvider {
  get supportsAttachments() { return true; }

  async send(message: EmailMessage): Promise<SendResult> {
    // call the Mailgun API
    return { success: true, requestId: '...' };
  }
}