@sourceloop/notification-service

Overview

Microservice for handling notifications to users through real time notifications, email, or SMS. This microservice uses the loopback4-notifications module to publish/send the notifications.

Installation

npm i @sourceloop/notification-service

Usage

Create a new Loopback4 Application (If you don't have one already) lb4 testapp
Install the notification service npm i @sourceloop/notification-service
Install the loopback4-notifications module - npm i loopback4-notifications
Set the environment variables.
Run the migrations.

Add the NotificationServiceComponent to your Loopback4 Application (in application.ts).

// add Component for AuthenticationService
this.component(NotificationServiceComponent);

Set up a Loopback4 Datasource with dataSourceName property set to NotifDbSourceName. You can see an example datasource here.
Email Notifications with Amazon SES -
- Bind the SES Config to the SESBindings.Config key -
```
this.bind(SESBindings.Config).to({
  accessKeyId: process.env.SES_ACCESS_KEY_ID,
  secretAccessKey: process.env.SES_SECRET_ACCESS_KEY,
  region: process.env.SES_REGION,
});
```
- Implement an SES Provider(refer this) or you can import the default SES provider from the loopback4-notifications module and bind it to the NotificationBindings.EmailProvider key as described here.

Email Notifications with Nodemailer -

Bind the Nodemailer Config to the NodemailerBindings.Config key -

this.bind(NodemailerBindings.Config).to({
  pool: true,
  maxConnections: 100,
  url: '',
  host: 'smtp.example.com',
  port: 80,
  secure: false,
  auth: {
    user: 'username',
    pass: 'password',
  },
  tls: {
    rejectUnauthorized: true,
  },
});

Implement a Nodemailer Provider(refer this) or import the default Nodemailer provider from the loopback4-notifications module and bind it to the NotificationBindings.EmailProvider key as described here,

SMS Notification with Amazon SNS -

Bind the SNS Config to the SNSBindings.Config key -

this.bind(SNSBindings.Config).to({
  accessKeyId: process.env.SNS_ACCESS_KEY_ID,
  secretAccessKey: process.env.SNS_SECRET_ACCESS_KEY,
  region: process.env.SNS_REGION,
});

Implement an SnsProvider(refer this) or import the default SNS provider from the loopback4-notifications module and bind it to the NotificationBindings.SMSProvider key -

import {
  NotificationBindings,
  SnsProvider // or your own provider
} from 'loopback4-notifications';
...
this.bind(NotificationBindings.SMSProvider).toProvider(SnsProvider);
...

Push Notifications with Pubnub -

Bind the Pubnub Config to the PubNubProvider.Config key -

this.bind(PubnubBindings.Config).to({
  subscribeKey: process.env.PUBNUB_SUBSCRIBE_KEY,
  publishKey: process.env.PUBNUB_PUBLISH_KEY,
  secretKey: process.env.PUBNUB_SECRET_KEY,
  ssl: true,
  logVerbosity: true,
  uuid: 'my-app',
  cipherKey: process.env.PUBNUB_CIPHER_KEY,
  apns2Env: 'production',
  apns2BundleId: 'com.app.myapp',
});

Implement a Pubnub Provider(refer this) or import the default Pubnub provider from the loopback4-notifications module and bind it to the NotificationBindings.PushProvider key -

import {
  NotificationBindings,
  PubNubProvider //or your own provider
} from 'loopback4-notifications';
...
this.bind(NotificationBindings.PushProvider).toProvider(PubNubProvider);
...

Push Notifications with Socket.io -

Bind the Socket.io Config to the SocketBindings.Config key -

this.bind(SocketBindings.Config).to({
  url: process.env.SOCKETIO_SERVER_URL,
});

Implement a SocketIO Provider(refer this) or import the default Socket.io provider from the loopback4-notifications module and bind it to the NotificationBindings.PushProvider key -

import {
  NotificationBindings,
  SocketIOProvider // or your own provider
} from 'loopback4-notifications';
...
this.bind(NotificationBindings.PushProvider).toProvider(SocketIOProvider);
...

Start the application npm start

Create Notification Payload Structures

Email Notification with SES

interface SESMessage {
  receiver: {
    to: {
      id: string; //Email address
      name?: string;
    }[];
  };
  subject: string;
  body: string;
  sentDate: Date;
  type: 1; //Email
  options?: {
    fromEmail: string; // We do not support attachments with SES Provider yet.
  };
}

Email Notification with Nodemailer

interface NodemailerMessage {
  receiver: {
    to: {
      id: string; //Email address
      name?: string;
    }[];
  };
  subject: string;
  body: string;
  sentDate: Date;
  type: 1; //Email
  options?: {
    from: string;
    subject?: string;
    text?: string;
    html?: string;
    attachments?: {
      filename?: string | false;
      cid?: string;
      encoding?: string;
      contentType?: string;
      contentTransferEncoding?: '7bit' | 'base64' | 'quoted-printable' | false;
      contentDisposition?: 'attachment' | 'inline';
      headers?: Headers;
      raw?:
        | string
        | Buffer
        | Readable
        | {
            content?: string | Buffer | Readable;
            path?: string | Url;
          };
    }[];
  };
}

SMS Notification with SNS

interface SMSMessage {
  receiver: {
    to: {
      id: string; // TopicArn or PhoneNumber
      name?: string;
    }[];
  };
  subject: undefined;
  body: string;
  sentDate: Date;
  type: 2; //SMS
  options?: {
    messageType: any;
  };
}

Push Notification with Pubunb

interface PubNubMessage {
  receiver: {
    to: {
      type: 0; //Channel Type
      id: string; //Channel identifier
      name?: string;
    }[];
  };
  subject: string;
  body: string;
  sentDate: Date;
  type: 0; //Push Notification
  options?: {
    sound: string;
  };
}

Push Notification with Socket.io

interface SocketMessage {
  receiver: {
    to: {
      type: 0; //Channel Type
      id: string; //Channel identifier
      name?: string;
    }[];
  };
  subject: string;
  body: string;
  sentDate: Date;
  type: 0; //Push Notification
  options?: {
    path?: string;
  };
}

Environment Variables

Name	Required	Description
`NODE_ENV`	Y	Node environment value, i.e. `dev`, `test`, `prod`
`LOG_LEVEL`	Y	Log level value, i.e. `error`, `warn`, `info`, `verbose`, `debug`
`DB_HOST`	Y	Hostname for the database server.
`DB_PORT`	Y	Port for the database server.
`DB_USER`	Y	User for the database.
`DB_PASSWORD`	Y	Password for the database user.
`DB_DATABASE`	Y	Database to connect to on the database server.
`DB_SCHEMA`	Y	Database schema used for the data source. In PostgreSQL, this will be `public` unless a schema is made explicitly for the service.
`JWT_SECRET`	Y	Symmetric signing key of the JWT token.
`JWT_ISSUER`	Y	Issuer of the JWT token.

Setting up a `DataSource`

Here is a sample Implementation DataSource implementation using environment variables and PostgreSQL as the data source.

import {inject, lifeCycleObserver, LifeCycleObserver} from '@loopback/core';
import {juggler} from '@loopback/repository';
import {NotifDbSourceName} from '@sourceloop/notification-service';

const config = {
  name: NotifDbSourceName,
  connector: 'postgresql',
  url: '',
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_DATABASE,
  schema: process.env.DB_SCHEMA,
};

@lifeCycleObserver('datasource')
export class NotificationDbDataSource
  extends juggler.DataSource
  implements LifeCycleObserver
{
  static dataSourceName = NotifDbSourceName;
  static readonly defaultConfig = config;

  constructor(
    // You need to set datasource configuration name as 'datasources.config.Notification' otherwise you might get Errors
    @inject('datasources.config.Notification', {optional: true})
    dsConfig: object = config,
  ) {
    super(dsConfig);
  }
}

Blacklisting Users

Here is a sample implementation of how we can blacklist a user(s).

Create a new provider:

import {BindingScope, injectable, Provider} from '@loopback/core';
import {
  INotificationFilterFunc,
  Notification,
} from '@sourceloop/notification-service';

@injectable({scope: BindingScope.TRANSIENT})
export class NotificationfilterProvider
  implements Provider<INotificationFilterFunc>
{
  constructor() {}

  value() {
    return async (notif: Notification) => this.notificationFilterFunc(notif);
  }

  blacklistedUsers = ['id1', 'id2']; //ID's of blacklisted users

  notificationFilterFunc(notif: Notification) {
    const receivers = notif!.receiver.to;
    const result = receivers.filter(receiver => {
      return this.blacklistedUsers.indexOf(receiver.id) === -1;
    });
    notif.receiver.to = result;
    return notif;
  }
}

Add the following line to src/application.ts file

this.bind(NotifServiceBindings.NotificationFilter).toProvider(
  NotificationfilterProvider,
);

Note: One can modify the provider according to the requirements

Migrations

The migrations required for this service are processed during the installation automatically if you set the NOTIF_MIGRATION or SOURCELOOP_MIGRATION env variable. The migrations use db-migrate with db-migrate-pg driver for migrations, so you will have to install these packages to use auto-migration. Please note that if you are using some pre-existing migrations or database, they may be effected. In such scenario, it is advised that you copy the migration files in your project root, using the NOTIF_MIGRATION_COPY or SOURCELOOP_MIGRATION_COPY env variables. You can customize or cherry-pick the migrations in the copied files according to your specific requirements and then apply them to the DB.

API Documentation

Common Headers

Authorization: Bearer where is a JWT token signed using JWT issuer and secret. Content-Type: application/json in the response and in request if the API method is NOT GET

Common Request path Parameters

{version}: Defines the API Version

Common Responses

200: Successful Response. Response body varies w.r.t API 401: Unauthorized: The JWT token is missing or invalid 403: Forbidden : Not allowed to execute the concerned API 404: Entity Not Found 400: Bad Request (Error message varies w.r.t API) 201: No content: Empty Response

API's Details

Visit the OpenAPI spec docs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

@sourceloop/notification-service

Overview

Installation

Usage

Create Notification Payload Structures

Email Notification with SES

Email Notification with Nodemailer

SMS Notification with SNS

Push Notification with Pubunb

Push Notification with Socket.io

Environment Variables

Setting up a `DataSource`

Blacklisting Users

Migrations

API Documentation

Common Headers

Common Request path Parameters

Common Responses

API's Details

Files

README.md

Latest commit

History

README.md

File metadata and controls

@sourceloop/notification-service

Overview

Installation

Usage

Create Notification Payload Structures

Email Notification with SES

Email Notification with Nodemailer

SMS Notification with SNS

Push Notification with Pubunb

Push Notification with Socket.io

Environment Variables

Setting up a DataSource

Blacklisting Users

Migrations

API Documentation

Common Headers

Common Request path Parameters

Common Responses

API's Details

Setting up a `DataSource`