gennotif

Generic Notification Interface

A generic interface that uses transports to deliver notifications to clients.

Examples

Sending a simple email:

var config = {
  transports: ['email'],
  data: {
    from: '[e-mail]',
    to: '[e-mail]',
    subject: 'A new email message',
    text: 'Lorem ipsum.',
    html: '<b>Lorem</b> ipsum.'
  }
}
var notification = new Notification(config);
notification.send();

Using fallback transports:

This will use multiple transports to send the notification. It will each of them (first to last) until one of them will successfully deliver the notification.

var config = {
  transports: ['email', 'console'],
  data: {
    from: '[e-mail]',
    to: '[e-mail]',
    subject: 'A new email message',
    text: 'Lorem ipsum.',
    html: '<b>Lorem</b> ipsum.'
  }
}
var notification = new Notification(config);
notification.send();

The console transport uses the only the "text" field from the data object.

Using multiple transports:

This notification will be send using all of the available transports. It does this synchronously.

var config = {
  transports: ['email', 'console'],
  data: {
    from: '[e-mail]',
    to: '[e-mail]',
    subject: 'A new email message',
    text: 'Lorem ipsum.',
    html: '<b>Lorem</b> ipsum.'
  }
}

var notification = new Notification(config);
notification.setStrategy(Notification.STRATEGY_ALL);

notification.send();

Reusing the "notification" object:

The config of the notification object can be change for individual notifications in order to not instantiate a new Notification instance.

var config = {
  transports: ['email', 'console'],
  data: {
    from: '[e-mail]',
    to: '[e-mail]',
    subject: 'A new email message',
    text: 'Lorem ipsum.',
    html: '<b>Lorem</b> ipsum.'
  }
}

var notification = new Notification(config);
notification.setStrategy(Notification.STRATEGY_ALL);

notification.send();

notification.send({
  data: {
    text: 'Different text for this notification',
    html: '<b>Different</b> <i>text</i> for this notification'
  }
});

Creating a custom transport:

Custom transports can be created by inheriting the NotificationTransportBase and implementing a "handle" method.

var Notification = require('gennotif').Notification;
var NotificationTransportBase = require('gennotif').NotificationTransportBase;
var util = require('util');

var CustomTransport = function() {
  // execute the super_ constructor
  NotificationTransportBase.apply(this, arguments);

  // do your constructor magic
}

util.inherits(CustomTransport, NotificationTransportBase);
module.exports = CustomTransport;

CustomTransport.prototype.handle = function(data, cb) {
  // you get the data part of the config
  
  // send the notification using this transport and than call cb(err, results) when ready
  
  cb();
}

Using the new transport:

var CustomTransport = require('./path/to/CustomTransport');

// Register this new transport
Notification.registerTransport('MyCustomTransport', CustomTransport);

// Use it
var config = {
  transports: ['MyCustomTransport', 'console'],
  data: {
    text: 'Using my custom transport'
  }
}

var new_notification = new Notification(config);

new_notification.send();

API

Class: Notification

Notification.registerTransport(name, TransportObject)

Registers a new transport with the Notification interface.

• name String the name of the transport that will be used in the config
• TransportObject NotificationTransportBase the object that extends the NotificationTransportBase used to send the notification

Notification.STRATEGY_LR

Default delivery strategy. Tries to deliver the notification using each transport starting with the first and stops after the first successful delivery.

Notification.STRATEGY_ALL

Tries to deliver the notification using all configured transports. This is done synchronously.

Notification.STRATEGY_RL

Same as Notification.STRATEGY_LR but starts with the last added transport.

new Notification(config)

Create a new notification instance.

• config Object
  • notifications Array of notification names that could be used
  • data Object basic configuration for the transports

notification.setStrategy(strategy)

Set the delivery strategy for this notification. Possible values:

• Notification.STRATEGY_LR
• Notification.STRATEGY_ALL
• Notification.STRATEGY_RL

notification.addTransport(name);

Adds a transport to the list of used transports. Has to be an already registered transport.

• name String Name of the transport.

notification.removeTransport(name);

Removes a transport from the list of used transports.

• name String Name of the transport.

notification.send(data)

Send the notification. The data part of the config used at construction time can be changed by using the data arg.

• data Object Optional. Overwrites the data config.