github.com/notifme/notifme-sdk @v1.16.25 sqlite

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

• Features
• Getting started
• How to use
• 1. General options
• 2. Providers
• 3. Custom channels
• 4. Send a notification
• 5. In production
• Contributing
• Need help? Found a bug?
• Related Projects

Features

• Easy channel integration — Want to start sending emails | SMS | pushes | webpushes | slack? 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.

• 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 = all providers are set to console.log
notifmeSdk
  .send({sms: {from: '+15000000000', to: '+15000000001', text: 'Hello, how are you?'}})
  .then(console.log)

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

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

Custom connection settings

If you have the Notification Catcher running on a custom port, domain, or you need to change any other connection setting, set the environment variable NOTIFME_CATCHER_OPTIONS with your custom connection smtp url.

$ # Example
$ NOTIFME_CATCHER_OPTIONS=smtp://127.0.0.1:3025?ignoreTLS=true node your-script-using-notifme.js

How to use

• 1. General options
• 2. Providers
• 3. Custom channels
• 4. Send a notification
• 5. In production

1. General options

new NotifmeSdk({
  channels: ..., // Object
  useNotificationCatcher: ... // boolean
})

Option name	Required	Type	Description
channels	false	Object	Define providers (Array) and multiProviderStrategy (string) for each channel (email, sms, push, webpush, slack).

See all details below: 2. Providers. | | 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({
  useNotificationCatcher: true
})

// Env: production
new NotifmeSdk({
  channels: {
    email: {
      // If "Provider1" fails, use "Provider2"
      multiProviderStrategy: 'fallback',
      providers: [{
        type: 'Provider1',
        // ...credentials
      }, {
        type: 'Provider2',
        // ...credentials
      }]
    },
    sms: {
      // Use "Provider1" and "Provider2" in turns (and fallback if error)
      multiProviderStrategy: 'roundrobin',
      providers: [{
        type: 'Provider1',
        // ...credentials
      }, {
        type: 'Provider2',
        // ...credentials
      }]
    }
  }
})

HTTP proxy option

If you want to use a HTTP proxy, set an environment variable NOTIFME_HTTP_PROXY.

$ # Example
$ NOTIFME_HTTP_PROXY=http://127.0.0.1:8580 node your-script-using-notifme.js

2. Providers

Email providers

Logger (for development)

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

SMTP (can be used for almost all providers)

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'
      }]
    }
  }
})

Mailgun

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'mailgun',
        apiKey: 'xxxxx',
        domainName: 'example.com'
      }]
    }
  }
})

Mandrill

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'mandrill',
        apiKey: 'xxxxx'
      }]
    }
  }
})

Sendgrid

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'sendgrid',
        apiKey: 'xxxxx'
      }]
    }
  }
})

SES

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'ses',
        region: 'xxxxx',
        accessKeyId: 'xxxxx',
        secretAccessKey: 'xxxxx',
        sessionToken: 'xxxxx' // optional
      }]
    }
  }
})

SparkPost

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'sparkpost',
        apiKey: 'xxxxx'
      }]
    }
  }
})

Custom (define your own)

new NotifmeSdk({
  channels: {
    email: {
      providers: [{
        type: 'custom',
        id: 'my-custom-email-provider...',
        send: async (request) => {
          // Send email
          return 'id...'
        }
      }]
    }
  }
})

request being of the following type.

See all options: Email provider options

SMS providers

Logger (for development)

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

46elks

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

Callr

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: 'callr',
        login: 'xxxxx',
        password: 'xxxxx'
      }]
    }
  }
})

Clickatell

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: 'clickatell',
        apiKey: 'xxxxx' // One-way integration API key
      }]
    }
  }
})

Infobip

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: 'infobip',
        username: 'xxxxx',
        password: 'xxxxx'
      }]
    }
  }
})

Nexmo

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

OVH

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: 'ovh',
        appKey: 'xxxxx',
        appSecret: 'xxxxx',
        consumerKey: 'xxxxx',
        account: 'xxxxx',
        host: 'xxxxx' // https://github.com/ovh/node-ovh/blob/master/lib/endpoints.js
      }]
    }
  }
})

Plivo

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

Twilio

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

Seven

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

Custom (define your own)

new NotifmeSdk({
  channels: {
    sms: {
      providers: [{
        type: 'custom',
        id: 'my-custom-sms-provider...',
        send: async (request) => {
          // Send SMS
          return 'id...'
        }
      }]
    }
  }
})

request being of the following type.

See all options: SMS provider options

Voice providers

Logger (for development)

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

Twilio

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

Custom (define your own)

new NotifmeSdk({
  channels: {
    voice: {
      providers: [{
        type: 'custom',
        id: 'my-custom-voice-provider...',
        send: async (request) => {
          // Send Voice
          return 'id...'
        }
      }]
    }
  }
})

request being of the following type.

See all options: Voice provider options

Push providers

Logger (for development)

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

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'
      }]
    }
  }
})

Custom (define your own)

new NotifmeSdk({
  channels: {
    push: {
      providers: [{
        type: 'custom',
        id: 'my-custom-push-provider...',
        send: async (request) => {
          // Send push
          return 'id...'
        }
      }]
    }
  }
})

request being of [the following typ