A Node.js library to send all kinds of transactional notifications.

• Features
• Getting started
• How to use
  • 1. General options
  • 2. Providers
  • 3. Use a request queue
  • 4. Send a notification
  • 5. In production
• Contributing
• Need help? Found a bug?

Features

• Easy channel integration — Want to start sending emails | SMS | pushes | webpushes? Do so in no time!

• Unique documentation — Don't look everywhere for the parameters you need to pass, just do it once. Switching provider becomes a no-brainer.

• Multiple providers strategies — Want to use more than one provider? Use fallback and round-robin strategies out of the box.

• Queue system — Plug your own external queue system to ensure delivery (if you have one).

• Tools for local testing — Run a catcher locally to intercept all your notifications and display them in a web interface.

• MIT license — Use it like you want.

Getting Started

$ yarn add notifme-sdk

import NotifmeSdk from 'notifme-sdk'

const notifmeSdk = new NotifmeSdk({}) // empty config = no queue and provider is console.log
notifmeSdk
  .send({sms: {from: '+15000000000', to: '+15000000001', text: 'Hello, how are you?'}})
  .then(console.log)

✨ Congratulations, you should see the following lines in your console:

[Recommended] Setup Notification Catcher for your local tests

Notification Catcher is a web interface for viewing and testing notifications during development.

$ yarn add --dev notification-catcher
$ yarn run notification-catcher

import NotifmeSdk from 'notifme-sdk'

const notifmeSdk = new NotifmeSdk({
  useNotificationCatcher: true // <= this sends all your notifications to the catcher running on port 1025
})
notifmeSdk
  .send({sms: {from: '+15000000000', to: '+15000000001', text: 'Hello, how are you?'}})
  .then(console.log)

😻 Open http://localhost:1080 on your favorite browser, you should see the notification:

How to use

• 1. General options
• 2. Providers
• 3. Use a request queue
• 4. Send a notification
• 5. In production

1. General options

new NotifmeSdk({
  channels: ..., // Object
  requestQueue: ..., // false | 'in-memory' | Function
  onSuccess: ..., // Function
  onError: ..., // Function
  useNotificationCatcher: ... // boolean
})

Option name	Required	Type	Description
channels	false	Object	Define providers (Array) and multiProviderStrategy (string) for each channel (email, sms, push, webpush). See all details below: 2. Providers.
requestQueue	false	false | string | Function	Default: false. Queue used for your notification requests. You can pass 'in-memory' to mimic an external queue in your local environment. To use a real queue, see 3. Use a request queue below.
onSuccess	false	Function	Callback to call when a notification has been sent with success. The first parameter is described below and the second is your request.
onError	false	Function	Callback to call when a notification has an error in at least one channel. The first parameter is described below and the second is your request.
useNotificationCatcher	false	boolean	If true, all your notifications are sent to the catcher running on localhost:1025 (channels option will be completely ignored!)

Complete examples

// Env: development
new NotifmeSdk({
  requestQueue: false,
  useNotificationCatcher: true,
  onSuccess: (result, originalRequest) => {
    console.log(`My request id ${originalRequest.id} was successful \\o/.`, result)
  },
  onError: (result, originalRequest) => {
    console.log(`Oh no, my request id ${originalRequest.id} has errors.`, result.errors)
  }
})

// Env: production
new NotifmeSdk({
  channels: {
    email: {
      multiProviderStrategy: 'fallback', // If Mailgun fails, use Mailjet
      providers: [{
        type: 'smtp',
        host: 'smtp.mailgun.org',
        port: 465,
        secure: true,
        auth: {
          user: 'postmaster@xxxxx.mailgun.org',
          pass: 'xxxxx'
        }
      }, {
        type: 'smtp',
        host: 'in-v3.mailjet.com',
        port: 587,
        secure: true,
        auth: {
          user: 'xxxxx',
          pass: 'xxxxx'
        }
      }]
    },
    sms: {
      multiProviderStrategy: 'roundrobin', // Use Nexmo and Twilio in turns (and fallback if error)
      providers: [{
        type: 'nexmo',
        apiKey: 'xxxxx',
        apiSecret: 'xxxxx'
      }, {
        type: 'twilio',
        accountSid: 'xxxxx',
        authToken: 'xxxxx'
      }]
    }
  },
  onSuccess: (result, originalRequest) => {
    // Maybe log success in database
  },
  onError: (result, originalRequest) => {
    // Maybe retry failed channel(s) later
  }
})

2. Providers

Email providers

SMTP

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'smtp',
        host: 'smtp.example.com',
        port: 465,
        secure: true,
        auth: {
          user: 'xxxxx',
          pass: 'xxxxx'
        }
      }]
    }
  }
})

Sendmail

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'sendmail',
        sendmail: true,
        newline: 'unix',
        path: '/usr/sbin/sendmail'
      }]
    }
  }
})

Logger (for development)

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'logger'
      }]
    }
  }
})

See all options: Email provider options

SMS providers

Nexmo

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: 'nexmo',
        apiKey: 'xxxxx',
        apiSecret: 'xxxxx'
      }]
    }
  }
})

Twilio

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: 'twilio',
        accountSid: 'xxxxx',
        authToken: 'xxxxx'
      }]
    }
  }
})

46elks

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: '46elks',
        apiUsername: 'xxxxx',
        apiPassword: 'xxxxx'
      }]
    }
  }
})

Logger (for development)

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: 'logger'
      }]
    }
  }
})

See all options: SMS provider options

Push providers

APN (Apple Push Notification)

new NotifmeSdk({
  channels: {
    push: {
      providers: [{
        type: 'apn',
        token: {
          key: './certs/key.p8',
          keyId: 'xxxxx',
          teamId: 'xxxxx'
        }
      }]
    }
  }
})

FCM (Firebase Cloud Messaging, previously called GCM, Google Cloud Messaging)

new NotifmeSdk({
  channels: {
    push: {
      providers: [{
        type: 'fcm',
        id: 'xxxxx'
      }]
    }
  }
})

WNS (Windows Push Notification)

new NotifmeSdk({
  channels: {
    push: {
      providers: [{
        type: 'wns',
        clientId: 'xxxxx',
        clientSecret: 'xxxxx',
        notificationMethod: 'sendTileSquareBlock'
      }]
    }
  }
})

ADM (Amazon Device Messaging)

new NotifmeSdk({
  channels: {
    push: {
      providers: [{
        type: 'adm',
        clientId: 'xxxxx',
        clientSecret: 'xxxxx'
      }]
    }
  }
})

Logger (for development)

new NotifmeSdk({
  channels: {
    push: {
      providers: [{
        type: 'logger'
      }]
    }
  }
})

See all options: Push provider options

Webpush providers

GCM (Google Cloud Messaging) - uses W3C endpoints if possible

new NotifmeSdk({
  channels: {
    webpush: {
      providers: [{
        type: 'gcm',
        gcmAPIKey: 'xxxxx',
        vapidDetails: {
          subject: 'mailto: contact@example.com',
          publicKey: 'xxxxx',
          privateKey: 'xxxxx'
        }
      }]
    }
  }
})

Logger (for development)

new NotifmeSdk({
  channels: {
    webpush: {
      providers: [{
        type: 'logger'
      }]
    }
  }
})

See all options: Webpush provider options

Multi-provider strategies

Strategy name	Description
fallback	If the used provider returns an error, try the next in the list.
roundrobin	Use every provider in turns. If one of them returns an error, fallback to the next.
no-fallback	Deactivates fallback strategy.

Adding a provider or a channel

If you would like to see another provider or channel, please upvote the corresponding issue (or create one if it does not exist yet).

3. Use a request queue

You can use your own queue system to handle notification requests. It must implement the following interface:

interface QueueType<T> {
  enqueue(type: string, jobData: T): Promise<?Object>;
  dequeue(type: string, callback: CallbackType<T>): void;
  // Note: callback is an async method treating a request
}

Example

new NotifmeSdk({
  requestQueue: {
    enqueue: (type, request) => { // 'type' is prefixed by 'notifme:'
      return new Promise((resolve) => {
        // Put request in your queue
        resolve(/* info from your queue system */)
      })
    },
    dequeue: (type, callback) => {
      // Get a request from your queue
      callback(request).then(/* Send ack for this request */)
    }
  }
})

4. Send a notification

Parameters

Send an email

notifmeSdk.send({
  email: {
    from: 'me@example.com',
    to: 'john@example.com',
    subject: 'Hi John',
    html: '<b>Hello John! How are you?</b>'
  }
})

See all parameters.

Send a SMS

notifmeSdk.send({
  sms: {
    from: '+15000000000',
    to: '+15000000001',
    text: 'Hello John! How are you?'
  }
})

See all parameters.

Send a push

notifmeSdk.send({
  push: {
    registrationToken: 'xxxxx',
    title: 'Hi John',
    body: 'Hello John! How are you?',
    icon: 'https://notifme.github.io/notifme-sdk/img/icon.png'
  }
})

See all parameters.

Send a webpush

notifmeSdk.send({
  webpush: {
    subscription: {
      keys: {
        auth: 'xxxxx',
        p256dh: 'xxxxx'
      },
      endpoint: 'xxxxx'
    },
    title: 'Hi John',
    body: 'Hello John! How are you?',
    icon: 'https://notifme.github.io/notifme-sdk/img/icon.png'
  }
})

See all parameters.

Send a multi-channel notification

notifmeSdk.send({
  email: {
    from: 'me@example.com',
    to: 'john@example.com',
    subject: 'Hi John',
    html: '<b>Hello John! How are you?</b>'
  },
  sms: {
    from: '+15000000000',
    to: '+15000000001',
    text: 'Hello John! How are you?'
  },
  push: {
    registrationToken: 'xxxxx',
    title: 'Hi John',
    body: 'Hello John! How are you?',
    icon: 'https://notifme.github.io/notifme-sdk/img/icon.png'
  },
  webpush: {
    subscription: {
      keys: {
        auth: 'xxxxx',
        p256dh: 'xxxxx'
      },
      endpoint: 'xxxxx'
    },
    title: 'Hi John',
    body: 'Hello John! How are you?',
    icon: 'https://notifme.github.io/notifme-sdk/img/icon.png'
  }
})

See all parameters.

Returned type

send returns a Promise resolving with an Object of the following type:

type NotificationStatusType = {
  status: 'queued' | 'success' | 'error',
  channels?: {[channel: ChannelType]: {
    id: string,
    providerId: ?string
  }},
  info?: ?Object,
  errors?: {[channel: ChannelType]: Error}
}

Examples:

Case	Returned JSON
Success (when Promise resolves)	{status: 'success', channels: {sms: {id: 'id-116561976', providerId: 'sms-default-provider'}}}
Success (when you use a queue for requests)	{status: 'queued'}
Error (here Notification Catcher is not running)	{status: 'error', channels: {sms: {id: undefined, providerId: 'sms-notificationcatcher-provider'}}, errors: {sms: 'connect ECONNREFUSED 127.0.0.1:1025'}}

5. In production

Recommended options

Option name	Usage in production
useNotificationCatcher	false
requestQueue	false | Function (see 3. Use a request queue)

Logger

This project uses winston as logging library. You can add or remove loggers as you wish.

import NotifmeSdk from 'notifme-sdk'
import winston from 'winston'

const notifmeSdk = new NotifmeSdk({})

// To deactivate all loggers
notifmeSdk.logger.mute()

// Or set the loggers you want
notifmeSdk.logger.configure([
  new (winston.transports.File)({filename: 'somefile.log'})
])

See winston's documentation for more details.

Send us a message

So that we can make a list of people using this library ;)

Contributing

Contributions are very welcome!

To get started: fork this repository to your own GitHub account and then clone it to your local device.

$ git clone git@github.com:[YOUR_USERNAME]/notifme-sdk.git && cd notifme-sdk
$ yarn install

Before making a pull request, check that the code respects the Standard JS rules and the Flow type checker.

$ yarn run lint

Next for this project

• Implement other providers for each channel (ask or vote for a provider)
• Add other types of notifications based on what people ask (slack, messenger, skype, telegram, kik, spark...)
• A plugin system (for queues, retry system on error, templating, strategies...)

Need Help? Found a bug?

Submit an issue to the project Github if you need any help. And, of course, feel free to submit pull requests with bug fixes or changes.