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 (Legacy - Deprecated)**:
⚠️ **This method uses the legacy FCM API and is deprecated. Please use the new FCM v1 API below for new projects.**

 - 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);
 ```

### **Firebase Cloud Messaging (FCM) v1 API**:
The new FCM v1 API provides enhanced security with OAuth2 authentication and more flexible message targeting.

#### Setup FCM Configuration
``` typescript
import { fcmConfig } from 'notification-services';

// Configure with service account key file
fcmConfig({
  projectId: 'your-firebase-project-id',
  serviceAccountKey: './path/to/service-account-key.json'
});

// Or configure with environment variables
fcmConfig({
  projectId: process.env.FCM_PROJECT_ID,
  serviceAccountKey: {
    type: "service_account",
    project_id: process.env.FCM_PROJECT_ID,
    private_key_id: process.env.FCM_PRIVATE_KEY_ID,
    private_key: process.env.FCM_PRIVATE_KEY?.replace(/\\n/g, '\n'),
    client_email: process.env.FCM_CLIENT_EMAIL,
    client_id: process.env.FCM_CLIENT_ID,
    auth_uri: "https://accounts.google.com/o/oauth2/auth",
    token_uri: "https://oauth2.googleapis.com/token",
    auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs",
    client_x509_cert_url: process.env.FCM_CLIENT_CERT_URL
  }
});
```

#### Send to Single Device
``` typescript
import { fcmSendToToken } from 'notification-services';

const result = await fcmSendToToken('device-token', {
  notification: {
    title: 'Hello World',
    body: 'This is a test notification'
  },
  data: {
    userId: '123',
    action: 'open_chat'
  },
  webpush: {
    fcm_options: {
      link: '/chat'
    },
    notification: {
      icon: '/icon-192x192.png'
    }
  }
});
```

#### Send to Multiple Devices
``` typescript
import { fcmSendMulticast } from 'notification-services';

const tokens = ['token1', 'token2', 'token3'];
const result = await fcmSendMulticast(tokens, {
  notification: {
    title: 'Broadcast Message',
    body: 'This goes to multiple devices'
  }
});

console.log(`Success: ${result.successCount}, Failed: ${result.failureCount}`);
```

#### Send to Topic
``` typescript
import { fcmSendToTopic } from 'notification-services';

await fcmSendToTopic('news', {
  notification: {
    title: 'Breaking News',
    body: 'Important news update'
  }
});
```

#### Platform-Specific Configurations
``` typescript
const message = {
  notification: {
    title: 'Cross-platform title',
    body: 'Cross-platform message'
  },
  android: {
    priority: 'high',
    notification: {
      color: '#ff0000',
      sound: 'default',
      channel_id: 'important'
    }
  },
  apns: {
    payload: {
      aps: {
        badge: 1,
        sound: 'default'
      }
    }
  },
  webpush: {
    notification: {
      icon: '/icon.png',
      requireInteraction: true
    },
    fcm_options: {
      link: '/notification-page'
    }
  }
};

await fcmSendToToken('device-token', message);
```

For detailed migration guide and advanced usage, see [FCM v1 Migration Guide](./docs/FCM-v1-Migration.md).

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