Home

Awesome

redis-notifications

Build Status Build Status NPM version

A redis based notification engine. It implements the rsmq-worker to safely create notifications and recurring reports.

The goal is to define a simple API to be able to send notifications and mails to multiple users. A user can define a setting to only receive one mail per day as a report. This is all done within a queuing solution. so it's scalable and failsafe.

NPM

Install

  npm install redis-notifications

Initialize

initialize

    var RedisNotifications = require( "redis-notifications" );

    var nf = new RedisNotifications();

    // REQUIRED EVENT LISTENERS
    // listen to errors
    nf.on( "error", function( err ){});

    // Hook to read details of an user
    nf.on( "readUser", function( user_id, cb ){ /* ... */ });

    // Hook to generate the message content for the notification and the mail
    nf.on( "getContent", function( type, user, editor, additional, cb ){  /* ... */ });

    // Hook to write/send the notification to the user. Is is done immediately on every create
    nf.on( "createNotification", function( user, editor, message, cb ){ /* ... */ });

    // Hook to send a report to a user.
    nf.on( "sendMail", function( user, messages, isReport, cb ){ /* ... */ });

    // INIT
    nf.init();

    // METHODS
    // define the data of the editor
    var editor = { id: "ABCDE", firstname: "William", lastname: "Creator", email: "william.create@example.com" };

    // create a notification to a single user
    nf.create( editor, { type: "notification_type", user: 123 }, function( err, msgid ){  /* ... */  });

Config

Event Hooks

readUser

Call to read a user by the given id. So you have to implement the DB/API read yourself

Arguments

getContent

Create the notification content

Arguments

createNotification

This will called immediately after .create{Multile}(). Here you have to write the notification to your db and/or send it immediately to the user.

Arguments

sendMail

Send a mail to the user. This is only done if sendInterval is d{time}, i or p Only on d{time} a report is generated witch could contain more than one message.

Arguments

error

An error occurred

Arguments

Methods

.init()

After you added the required hooks you have the call .init() to start the module.

.create( editor, message [, cb ] )

Create a notification for one user

Arguments

Return

( Null|Error ): Null on success or a validation error.

.createMulti( editor, message [, cb ] )

Create a notification for multiple users

Arguments

Return

( Null|Error ): Null on success or a validation error.

.getRsmqWorker()

Helper method to get internal used instance

Return

( RSMQWorker ): The internal rsmq-worker instance.

.getRsmq()

Helper method to get internal used instance

Return

( RedisSMQ ): The internal rsmq instance.

.getRedis()

Helper method to get internal used instance

Return

( RedisClient ): The internal redis instance.

Example

This is a example implementation. It's up to you to implement the DB read and Write methods and do the notification and mail sending.

    var RedisNotifications = require( "redis-notifications" );

    var nf = new RedisNotifications();

    // REQUIRED EVENT LISTENERS
    // listen to errors
    nf.on( "error", function( err ){
        console.error( err, err.stack );
    });

    // Hock to read details of an user
    nf.on( "readUser", function( user_id, cb ){

        // here you have to query your database and return a valid user with at least these fields
        var user = {
            // required fields
            id: user_id,                                // unique user id
            firstname: "John",          
            email: "john.do@mail.com",
            timezone: "CET",                        // a moment-timezone valid timezone
            sendInterval: "i",                      // when to send a mail 

            // optional fields
            lastname: "Do",             

            // custom fields
            custom_lang: "DE"                       // it is possible to add custom fields
        };
        cb( null, user );
    });

    // Hook to generate the message content for the notification and the mail
    nf.on( "getContent", function( type, user, editor, additional, cb ){

        // here you have to generate your message by type. Usually you would use a template-engine
        
        var content = {
            // required fields
            subject: "This is my message subject",
            body: "Lorem ipsum dolor ...",          

            // custom fields
            custom_field: additional.custom_key,    // it is possible to add custom fields to the content
            custom_lang: user.custom_lang           // reuse the custom field from user
        };
        cb( null, content );
    });

    // Hook to write/send the notification to the user. Is is done immediately on every create
    nf.on( "createNotification", function( user, editor, message, cb ){

        // here you have to write the notification to your db and/or send it immediately to the user

        cb( null );
    });

    // Hook to send a report to a user.
    // This is only done if `sendInterval` is `d{time}`, `i` or `p`
    // Only on `d{time}` a report is generated witch could contain more than one message
    nf.on( "sendMail", function( user, messages, isReport, cb ){

        // here you have to do create of the mail content and mail send it.

        cb( null );
    });

    // INIT
    // you have to initialize the module until the required listeners has been added
    nf.init();

    // METHODS

    // define the data of the editor
    var editor = {
        // required fields
        id: "ABCDE",

        // optional fields
        firstname: "William",
        lastname: "Creator",
        email: "william.create@example.com",

        // custom fields
        custom_lang: "DE"
    };


    // create a notification for multiple users without callback
    var errCrM = nf.createMulti( editor, {
        type: "notification_type",                  // A type to differ the content in the `getContent` hook
        users: [ 123, 456, 789 ],                   // An array of user that will receive this notification
        high: true                                  // A flag to define this notification as high prio.
    });
    if( errCrM ){
        console.error( errCrM );
    }
    // High means:
    // - This message will be send by mail immediately.
    // - Users with `sendInterval = "p"` (only high prio) will also get this notification.

    // create a notification to a single user
    nf.create( editor, {
        type: "notification_type",                  // A type to differ the content in the `getContent` hook
        user: 123,                                  // The user id that will receive this notification
        high: false,                                // A flag to define this notification as high prio.
        additional: {
            custom_icon: "info"                     // additional data that later can be used with in the `getContent` hook
        }
    }, function( err, msgid ){
        if( err ){
            console.error( err );
        }
    });

Todos

Release History

VersionDateDescription
0.2.12016-10-27Small bugfix with default value (Thanks to Anton Rau for #3). Updated dependencies
0.2.02016-07-18Updated dev env and dependencies
0.1.12015-01-30Logo update
0.1.02015-01-30Added docs and optimized code and API
0.0.22015-01-29moved schema to extra module obj-schema
0.0.12015-01-29Initial version. No tests and docs until now!

NPM

Initially Generated with generator-mpnodemodule

Other projects

NameDescription
rsmqA really simple message queue based on Redis
rsmq-workerHelper to simply implement a worker RSMQ ( Redis Simple Message Queue ).
node-cacheSimple and fast NodeJS internal caching. Node internal in memory cache like memcached.
obj-schemaSimple module to validate an object by a predefined schema
redis-sessionsAn advanced session store for NodeJS and Redis
connect-redis-sessionsA connect or express middleware to simply use the redis sessions. With redis sessions you can handle multiple sessions per user_id.
systemhealthNode module to run simple custom checks for your machine or it's connections. It will use redis-heartbeat to send the current state to redis.
task-queue-workerA powerful tool for background processing of tasks that are run by making standard http requests.
soyerSoyer is small lib for serverside use of Google Closure Templates with node.js.
grunt-soy-compileCompile Goggle Closure Templates ( SOY ) templates inclding the handling of XLIFF language files.
backlunrA solution to bring Backbone Collections together with the browser fulltext search engine Lunr.js

The MIT License (MIT)

Copyright © 2015 Mathias Peter, http://www.tcs.de

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.