Skip to content

Latest commit

 

History

History
224 lines (163 loc) · 10.5 KB

README.md

File metadata and controls

224 lines (163 loc) · 10.5 KB
Raw

Notif.me History

A pretty history of the conversations with your users.

dependencies dev dependencies js-standard-style license license

Features

  • Pretty history — Display all the conversations with your users, along with events associated with the notifications (no more "Did user X received the Y SMS?" from the client service team).

  • Configure data retention — Decide until when each notification must be kept and set a capping on your MongoDB database.

  • Real-time data — The displayed notifications are automatically refreshed when they change or when new ones are created (with the help of Meteor).

  • Search by user info — All user fields are indexed and you can make complex searches with negations and phrases.

  • User management — An administrator can easily give or revoke access to any user.

  • Simple API — The model of the extra data (users, notification details) you send to the API is up to you.

  • MIT license — Use it like you want.


Preview

Getting Started

You can find a demo here or run it locally with docker:

$ docker run -d -p 80:3000 --name notifme-history notifme/history:dev-latest

✨ Then open http://localhost in your favorite browser.

You will need an OAuth client ID and secret from Google (the steps to create one will be detailed in the application).

notifme/history:dev-* images are not suited for production use. They include MongoDB and if you delete the container all the data is lost. See 4. In production

How to use

1. Model

Data is distributed into 3 main tables: Notifications, NotificationDetails, and NotificationUsers.

Table Use
Notifications This is the only table with an imposed model. Data corresponds with the notification list view and is intended to be a summary of the content (datetime, channel, title, text, tags...) to be kept longer than all the details.

You choose how long to keep each notification by setting an expiration date.
NotificationDetails This is where you can store all the (possibly lengthy) details of your notifications. You can use the model you want.

The table can be capped to a given size in MB so you don't exceed your quota.
NotificationUsers This table is used for the search feature. All field are indexes, so you should keep this data simple. The only required field is id.

You choose how long to keep each user by setting an expiration date, or it will expire when the last notification associated expires.

2. API

POST /api/notifications

Usage: when you send a notification to a user, call this API to add it to the history.

Field Required Type Description
id false String The external identifier of the notification. Required if you want to add events later on.
channel true String Type of the notification, you can put any string you want (email, sms, push, webpush, slack...).
datetime true Date Datetime ISO format.
title true String Notification's title.
text false String Notification's text content or summary.
tags false String[] Visual tags associated with the notification.
user false Object User information (for search feature). Only one field is required: id. The rest is up to you (but beware of the search index size, keep your data simple).
details false Object Any detail you want to keep.
events false Object[] Initial events. Fields: type (String, required), datetime (Date, required), info (String, optional).
isFromUser false boolean If the message comes from a user.
expireAt false Date Time until when to keep the notification (ISO format).
Minimal example:
curl -X POST http://localhost:3000/api/notifications \
  -H 'authorization: ...' \
  -H 'content-type: application/json' \
  -d '{ "title": "Minimal notification", "channel": "sms", "datetime": "2019-12-24 12:00:00" }'
Complete example:
curl -X POST http://localhost:3000/api/notifications \
  -H 'authorization: ...' \
  -H 'content-type: application/json' \
  -d '{ "id": "notification-1", "title": "Complete notification", "channel": "email", "datetime": "2019-12-24 12:00:00", "text": "Hello!", "tags": [ "John Doe" ], "user": { "id": "user-1", "name": "John Doe", "email": "[email protected]", "phone": "+15000000000" }, "details": { "subject": "Test email!", "html": "<h1>Hello!</h1>" }, "events": [ { "type": "sent", "datetime": "2019-12-24 12:00:00" } ], "expireAt": "2024-12-24 12:00:00" }'
User answer example:
curl -X POST http://localhost:3000/api/notifications \
-H 'authorization: ...' \
-H 'content-type: application/json' \
-d '{ "title": "Re: Minimal notification", "channel": "sms", "datetime": "2019-12-25 12:00:00", "isFromUser": true, "text": "this is my answer" }'

POST /api/notifications/:notificationId/events

Usage: set up webhooks in all your favorite notification providers, then call this API to save the event.

Field Required Type Description
notificationId true String The external identifier of the notification.
(This parameter is part of the URL).
type true String Type of your event, you can put any string you want (sent, delivered, errored...).
datetime true Date Datetime ISO format.
info false String Any information you want to keep about this event.
Example:
curl -X POST http://localhost:3000/api/notifications/notification-1/events \
  -H 'authorization: ...' \
  -H 'content-type: application/json' \
  -d '{ "type": "delivered", "datetime": "2019-12-24 12:00:00" }'

3. Options

Name Description
NOTIFICATION_DETAILS_LIMIT_MB Optional. Capping in MB for the NotificationDetails table. Changing this value on a non-empty table is possible, but the operation will require a global write lock and block all other operations until it has completed.
GOOGLE_CONSUMER_KEY Required (but not necessarily at startup). OAuth client ID from Google.
GOOGLE_CONSUMER_SECRET Required (but not necessarily at startup). OAuth secret from Google.

You can pass them when you run docker:

$ docker run -d -e NOTIFICATION_DETAILS_LIMIT_MB=256 ...

4. In production

To run in production, simply use the notifme/history:latest image.

$ docker run -d \
  -e MONGO_URL=mongodb://<dbuser>:<dbpassword>@<url>:<port>/<dbname> \
  -e ROOT_URL=https://example.com \
  -e NOTIFICATION_DETAILS_LIMIT_MB=512 \
  -p 80:3000 --name notifme-history notifme/history:latest

On a budget?

    1. Open an mLab account (free tier with 500MB), create a database and a user for this database. You'll get an URL of the form mongodb://<dbuser>:<dbpassword>@<url>:<port>/<dbname>.
    1. Deploy it with Now: npm i -g now && now login && now --public notifme/notifme-history. Use https://notifme-history-[your-company].now.sh as ROOT_URL and 128 for NOTIFICATION_DETAILS_LIMIT_MB.
    1. Alias you deployment: now alias https://notifme-history-[your-company]-[xxxxxxxxxx].now.sh notifme-history-[your-company] and scale it: now scale notifme-history-[your-company].now.sh 1

And... there you go! 😺

Contributing

Contributions are very welcome!

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

$ # Install meteor 1.6 (if not already installed)
$ curl https://install.meteor.com/ | sh
$ git clone [email protected]:[YOUR_USERNAME]/notifme-history.git && cd notifme-history
$ meteor npm install
$ npm run start

Before making a pull request, check that the code respects the Standard JS rules.

$ npm run lint

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.

Related Projects

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