notification-services/README.md

use email, sms and custom notification services for node.js application easily

# notification-service

## Overview

Microservice for handling notifications to users through real time notifications, email, or SMS. 

## Installation

```bash
npm i notification-services
```

## Usage

 - Create a new nodejs/reactjs Application (If you don't have one already)
 - Install the notification service
	 `npm i notification-services`.

#### **Email**:

#### Setup connection
 - There are three arguments to pass in `mailConfig` function.
 - **Email Notifications with SMTP** - 
    - Pass type: 'smtp' as the first argument of `mailConfig` function.
    - Pass second argument as an object having the corresponding `host`, `user` and `pass` for you SMTP server.
    - Third argument is the `callback` function to get the response back.
    - `callback` will return a `transport` as a response along with the message that whether the connection is setup or not.
    ``` typescript
    mailConfig('smtp', {
      host: process.env.SMTP_HOST,
      user: process.env.USER,
      pass: process.env.PASS,
    }, callback);
    ```
    
 - **Email Notifications with SES** -
    - Pass type: 'ses' as the first argument of `mailConfig` function.
    - Pass second argument as an object having the corresponding `awsAccessId`, `awsAccessKey`, `region` and `apiVersion` for you SES server.
    - Third argument is the `callback` function to get the response back.
    ``` typescript
    mailConfig('smtp', {
      awsAccessId: process.env.AWS_ACCESS_ID,
      awsAccessKey: process.env.AWS_ACCESS_KEY,
      region: process.env.REGION,
      apiVersion: process.env.API_VERSION
    }, callback);
    ```
    
#### Send Mail
 - There are four arguments to pass in `sendMail` function.
 - The first argument is `transport` which was returned from the `mailConfig` function.
 - Then pass `mailOptions` as the second argument. `mailOptions` include `from`, `to`, `cc`, `bcc`, `subject`, `text`, `html`, and `attachments`.
 - Third argument is `isTemplate` which is a boolean that whether you are using any template as mail body.
 - Fourth and last argument is the `callback` function to get the response back.
 ``` typescript
 sendMail(
    transporter, 
    data: {
    from, // sender address
    to, // list of receivers
    cc?, // list of cc
    bcc?, // list of bcc
    subject?, // Subject line
    text?, // plain text body
    html?, // html body
    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;
                                             };
        }[]
    }, 
    isTemplate, 
    callback
 );
 ```

 If `isTemplate` is false, the `sendMail` funtion will send the mail to the respective recievers with the body of mail provided in the `data`.
 But if `isTemplate` is true, the `sendMail` will return an `email` of type (`Email`) which can be used to send mail as follows:
 
```typescript
 email.send({
    template,
    locals
    })
    .then((response: any) => {
        console.log(response);
    })
    .catch((error: any) => {
        console.log(error);
    });
}
```

In the above code, the `template` is the name of template which you are using and the `locals` are the variables which were there in the template.
For more information on `email.send` function refer [email-templates (npm)](https://www.npmjs.com/package/email-templates#basic)

    
#### **SMS**:
 - There are three arguments to pass in `SMSSend` function.
 - **SMS Notifications with Gupshup** - 
    - Pass type: 'gupshup' as the first argument of `SMSSend` function.
    - Pass second argument as an object having the configurations: `appid`, `apiKey`, `to` and `message`.
    - Third argument is the `callback` function to get the response back.
    ``` typescript
    SMSSend('gupshup', {
      appid: process.env.APP_ID,
      apiKey: process.env.API_KEY,
      to, // recievers
      message, // notification to be sent in SMS
    }, callback);
    ```
    
 - **SMS Notifications with Fast2sms** - 
    - Pass type: 'fast2sms' as the first argument of `SMSSend` function.
    - Pass second argument as an object having the configurations: `senderID`, `apiKey`, `fast2smsRoute`, `to` and `message`.
    - Third argument is the `callback` function to get the response back.
    ``` typescript
    SMSSend('fast2sms', {
      fast2smsRoute: process.env.FAST_2_SMS_ROUTE,
      apiKey: process.env.API_KEY,
      senderID: process.env.SENDER_ID,
      to, // recievers
      message, // notification to be sent in SMS
    }, callback);
    ```
    
 - **SMS Notifications with Messagebird** - 
    - Pass type: 'messagebird' as the first argument of `SMSSend` function.
    - Pass second argument as an object having the corresponding `from`, `apiKey`, `to` and `message` for you SMTP server.
    - Third argument is the `callback` function to get the response back.
    ``` typescript
    SMSSend('messagebird', {
      from, // sender's name
      apiKey: process.env.API_KEY,
      to, // recievers
      message, // notification to be sent in SMS
    }, callback);
    ```
    
 - **SMS Notifications with Twilio** - 
    - Pass type: 'twilio' as the first argument of `SMSSend` function.
    - Pass second argument as an object having the corresponding `twilioAccountSid`, `twilioAuthToken`, `to` and `message` for you SMTP server.
    - Third argument is the `callback` function to get the response back.
    ``` typescript
    SMSSend('twilio', {
      twilioAccountSid: process.env.TWILIO_ACCOUNT_SID,
      twilioAuthToken: process.env.TWILIO_AUTH_TOKEN,
      from, // sender's name
      to, // recievers
      message, // notification to be sent in SMS
    }, callback);
    ```
    
### **Custom Notification**:
 - There are two arguments to pass in `sendCustomNotification` function.
 - Pass `options` as the first argument. `options` include `serverKey`, `title`, `text` and `fcm_tokens`.
 - Second argument is the `callback` function to get the response back.
 ``` typescript
 sendCustomNotification({
   serverKey: process.env.SERVER_KEY,
   title, // title of notification
   text, // content
   fcm_tokens, // recievers' fcm tokens
 }, callback);
 ```

 - Start the application
	`npm start`

### API Documentation

#### Common Headers

`Content-Type: application/json` in the response and in request if the API method is NOT GET

### 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

## License

MIT

## API's Details

Visit the [Abstraction Layer](https://gitlab.com/arachnomesh/arachnomesh-starter-kit/-/tree/nitin/abstraction/README.md)