Merge pull request #100 from ewandennis/ISSUE-94

Added message events wrapper (issue 94)

docs/resources/messageEvents.md

@@ -0,0 +1,60 @@
+# Message Events
+
+This library provides easy access to the [Message Events](https://www.sparkpost.com/api#/reference/message-events/) resource.
+
+## Methods
+* **search(params, callback)**
+  Search for message events using the given parameters (NOTE: all params are optional):
+  * `params.bounce_classes` - list of [bounce classes](https://support.sparkpost.com/customer/portal/articles/1929896)
+  * `params.campaign_ids` - campaign IDs 
+  * `params.events` - event types 
+  * `params.friendly_froms` - 'friendly' from addressess
+  * `params.from` - time lower bound  (see below for date/time format details)
+  * `params.message_ids` - message IDs
+  * `params.page` - results page number
+  * `params.per_page` - number of results per page
+  * `params.reason` - bounce reason with '%' wildcards (see below for example)
+  * `params.recipients` - recipient email addresses
+  * `params.template_ids` - template IDs
+  * `params.timezone` - timezone for `from` and `to` params ([reference](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones))
+  * `params.to` - time upper bound (see below for date/time format details)
+  * `params.transmission_ids` - transmission IDs
+
+## Date/Time Parameter Format
+
+The `from` and `to` search parameters accept datestamps of the form:
+
+  `YYYY-MM-DDTHH:MM`
+
+For example: `2016-11-14T16:15`.
+
+Note: timestamps are expressed in the timezone specified by the `timezone` parameter or UTC by default.
+
+## Examples
+
+This example code retrieves up to 5 'invalid recipient' bounce events from the first 2 days of 2016.
+
+```js
+var SparkPost = require('sparkpost');
+var client = new SparkPost('YOUR_API_KEY');
+var searchParams = {
+  from: '2016-01-01T00:00',
+  to: '2016-01-02T23:59',
+  page: 1,
+  per_page: 5,
+  events: ['bounce', 'out_of_band'],
+  bounce_classes: [10]
+};
+
+client.messageEvents.search(searchParams, function(err, res) {
+  if(err) {
+    console.log(err);
+    return;
+  }
+
+  console.log(data.body);
+});
+
+```
+
+Check out all the examples provided [here](/examples/messageEvents).

examples/messageEvents/all_messageEvents.js

@@ -0,0 +1,15 @@
+'use strict';
+
+var key = 'YOURAPIKEY'
+  , SparkPost = require('sparkpost')
+  , client = new SparkPost(key);
+
+client.messageEvents.search({}, function(err, res) {
+  if (err) {
+    console.log(err);
+  } else {
+    console.log(res.body);
+    console.log('Congrats you can use our SDK!');
+  }
+});
+

examples/messageEvents/search_campaignClicks.js

@@ -0,0 +1,19 @@
+'use strict';
+
+var key = 'YOURAPIKEY'
+  , SparkPost = require('sparkpost')
+  , client = new SparkPost(key)
+  , searchParams = {
+      events: 'click',
+      campaign_ids: 'monday_mailshot'
+    };
+
+client.messageEvents.search(searchParams, function(err, res) {
+  if (err) {
+    console.log(err);
+  } else {
+    console.log(res.body);
+    console.log('Congrats you can use our SDK!');
+  }
+});
+

examples/messageEvents/search_messageEvents.js

@@ -0,0 +1,23 @@
+'use strict';
+
+var key = 'YOURAPIKEY'
+  , SparkPost = require('sparkpost')
+  , client = new SparkPost(key)
+  , searchParams = {
+      from: '2016-01-01T00:00',
+      to: '2016-01-02T23:59',
+      page: 1,
+      per_page: 5,
+      events: ['bounce', 'out_of_band'],
+      bounce_classes: [10]
+    };
+
+client.messageEvents.search(searchParams, function(err, res) {
+  if (err) {
+    console.log(err);
+  } else {
+    console.log(res.body);
+    console.log('Congrats you can use our SDK!');
+  }
+});
+

lib/messageEvents.js

@@ -0,0 +1,38 @@
+'use strict';
+
+var api = 'message-events';
+
+/*
+ * "Class" declaration, Message Events API exposes one function:
+ * - search: retrieves list of message events according to given params
+ */
+module.exports = function (client) {
+  return {
+    search: function(parameters, callback) {
+      var arrayParams = [
+        'bounce_classes',
+        'campaign_ids',
+        'events',
+        'friendly_froms',
+        'message_ids',
+        'recipients',
+        'template_ids',
+        'transmission_ids'
+      ]
+        , options;
+
+      arrayParams.forEach(function(paramname) {
+        if (Array.isArray(parameters[paramname])) {
+          parameters[paramname] = parameters[paramname].toString();
+        }
+      });
+
+      options = {
+        uri: api
+        , qs: parameters
+      };
+      client.get(options, callback);
+    }
+  };
+};
+

lib/sparkpost.js

@@ -61,6 +61,7 @@ var SparkPost = function(apiKey, options) {
   this.templates = require('./templates')(this);
   this.transmissions = require('./transmissions')(this);
   this.webhooks = require('./webhooks')(this);
+  this.messageEvents = require('./messageEvents')(this);
 };
 
 SparkPost.prototype.request = function( options, callback ) {

test/spec/messageEvents.spec.js

@@ -0,0 +1,71 @@
+var chai = require('chai')
+  , expect = chai.expect
+  , sinon = require('sinon')
+  , sinonChai = require('sinon-chai');
+
+chai.use(sinonChai);
+
+describe('Message Events Library', function() {
+  var client, templates;
+
+  beforeEach(function() {
+    client = {
+      get: sinon.stub().yields()
+    };
+
+    messageEvents = require('../../lib/messageEvents')(client);
+  });
+
+  describe('search Method', function() {
+    it('should call client get method with the appropriate parameters', function(done) {
+      var options = {
+        bounce_classes: '10,50',
+        campaign_ids: 'test_campaign',
+        events: 'bounce',
+        friendly_froms: '[email protected]',
+        from: '2015-11-14T16:15',
+        message_ids: '0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e',
+        page: 1,
+        per_page: 5,
+        reason: '%5.2.0%',
+        recipients: '[email protected]',
+        template_ids: 'newsletter_template',
+        timezone: 'America/New_York',
+        to: '2016-11-14T16:15',
+        transmission_ids: '65832150921904138'
+      };
+      messageEvents.search(options, function(err, data) {
+        Object.keys(options).forEach(function(key) {
+          expect(client.get.firstCall.args[0].qs).to.have.property(key).and.equal(options[key]);
+        });
+        done();
+      });
+    });
+
+    it('should accept arrays as parameters where appropriate', function(done) {
+      var arroptions = {
+        bounce_classes: [10,50],
+        campaign_ids: ['campaign1', 'campaignTwo'],
+        events: ['bounce', 'out_of_band'],
+        friendly_froms: ['[email protected]', '[email protected]'],
+        message_ids: ['0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e', '338ac622-4321-5678-0123456789'],
+        recipients: ['[email protected]', '[email protected]'],
+        template_ids: ['newsletter_template', 'newsflash_template'],
+        transmission_ids: ['65832150921904138', '54673829032039839'],
+        page: 1,
+        per_page: 5,
+        timezone: 'America/New_York'
+      };
+      messageEvents.search(arroptions, function(err, data) {
+        Object.keys(arroptions).forEach(function(key) {
+          var opt = arroptions[key]
+            , firstCallQS = client.get.firstCall.args[0].qs;
+          if (Array.isArray(opt)) {
+            expect(firstCallQS).to.have.property(key).and.equal(opt.toString());
+          }
+        });
+        done();
+      });
+    });
+  });
+});