nestjs-notification-lib

A multi-channel notification module for NestJS with event-driven dispatch, template rendering, in-app notifications, delivery logging, and pluggable channel adapters.

Installation

npm install nestjs-notification-lib

Peer dependencies: @nestjs/common, @nestjs/core, @nestjs/typeorm, typeorm, class-validator, class-transformer, @aws-sdk/client-ses (optional, for SES adapter)

Usage

Register the module

import { NotificationModule, EmailSesAdapter } from 'nestjs-notification-lib';

@Module({
  imports: [
    NotificationModule.register({
      channels: [
        {
          key: 'email',
          adapter: new EmailSesAdapter({ region: 'ap-south-1', fromAddress: '[email protected]' }),
        },
      ],
    }),
  ],
})
export class AppModule {}

Send a notification

import { NotificationService } from 'nestjs-notification-lib';

@Injectable()
export class OrderService {
  constructor(private readonly notifications: NotificationService) {}

  async onOrderPlaced(order: Order) {
    await this.notifications.send({
      eventType: 'order_placed',
      channel: 'email',
      emailId: [order.customerEmail],
      parameters: { orderNumber: order.id, total: order.total },
    });
  }
}

REST endpoints (auto-registered)

• POST /notifications/send — dispatch a notification
• GET /notifications/:userId?page=&limit=&status= — list in-app notifications
• GET /notifications/:userId/check?lastKnownId= — check for new notifications
• PATCH /notifications/:notificationId/read — mark as read
• DELETE /notifications/:notificationId — soft delete

Custom channel adapter

import { ChannelAdapter } from 'nestjs-notification-lib';

export class SlackAdapter implements ChannelAdapter {
  async send(to: string[], subject: string, body: string) {
    // post to Slack webhook
  }
}

Database tables

| Entity | Table | |--------|-------| | NotificationChannelType | notification_channel_type | | NotificationEventType | notification_event_type | | NotificationTemplate | notification_template | | NotificationParameter | notification_parameter | | NotificationChannelEventTemplateMapping | notification_channel_event_template_mapping | | NotificationEventParameterMapping | notification_event_parameter_mapping | | NotificationInApp | notification_in_app | | NotificationLog | notification_log | | NotificationLogReceiverRecord | notification_log_receiver_record |

How it works

Event type → Channel → Template mapping → Render with params → Dispatch via adapter → Log delivery

Templates use {{paramName}} Mustache-style placeholders. The system logs every dispatch with per-receiver records for audit.