From d86573e4fd6a235de34659a535761005a242d1ef Mon Sep 17 00:00:00 2001 From: Ewan Dennis Date: Mon, 15 Feb 2016 15:54:59 +0000 Subject: [PATCH 1/5] Added message events wrapper (issue 94) --- lib/messageEvents.js | 19 ++++++++++++++ lib/sparkpost.js | 1 + test/spec/messageEvents.spec.js | 45 +++++++++++++++++++++++++++++++++ 3 files changed, 65 insertions(+) create mode 100644 lib/messageEvents.js create mode 100644 test/spec/messageEvents.spec.js diff --git a/lib/messageEvents.js b/lib/messageEvents.js new file mode 100644 index 0000000..b4ceeaa --- /dev/null +++ b/lib/messageEvents.js @@ -0,0 +1,19 @@ +'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 options = { + uri: api + , qs: parameters + }; + client.get(options, callback); + } + }; +}; diff --git a/lib/sparkpost.js b/lib/sparkpost.js index bbd49fd..38145f9 100644 --- a/lib/sparkpost.js +++ b/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 ) { diff --git a/test/spec/messageEvents.spec.js b/test/spec/messageEvents.spec.js new file mode 100644 index 0000000..e4add47 --- /dev/null +++ b/test/spec/messageEvents.spec.js @@ -0,0 +1,45 @@ +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: ['bob@example.com'], + from: '2015-11-14T16:15', + message_ids: ['0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e'], + page: 1, + per_page: 5, + reason: '%5.2.0%', + recipients: ['jim@example.com'], + 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(); + }); + }); + }); +}); From 337d96492e86ba2b0c45094f12bd0fde53160ece Mon Sep 17 00:00:00 2001 From: Ewan Dennis Date: Mon, 15 Feb 2016 16:08:08 +0000 Subject: [PATCH 2/5] Removed misleading query parameter formats --- test/spec/messageEvents.spec.js | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/test/spec/messageEvents.spec.js b/test/spec/messageEvents.spec.js index e4add47..ad6036f 100644 --- a/test/spec/messageEvents.spec.js +++ b/test/spec/messageEvents.spec.js @@ -19,20 +19,20 @@ describe('Message Events Library', function() { describe('search Method', function() { it('should call client get method with the appropriate parameters', function(done) { var options = { - bounce_classes: [10, 50], + bounce_classes: '10,50', campaign_ids: 'test_campaign', - events: ['bounce'], - friendly_froms: ['bob@example.com'], + events: 'bounce', + friendly_froms: 'bob@example.com', from: '2015-11-14T16:15', - message_ids: ['0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e'], + message_ids: '0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e', page: 1, per_page: 5, reason: '%5.2.0%', - recipients: ['jim@example.com'], - template_ids: ['newsletter_template'], + recipients: 'jim@example.com', + template_ids: 'newsletter_template', timezone: 'America/New_York', to: '2016-11-14T16:15', - transmission_ids: ['65832150921904138'] + transmission_ids: '65832150921904138' }; messageEvents.search(options, function(err, data) { Object.keys(options).forEach(function(key) { From 4183cd706364f1ec6f6e1d62d8294c30cbf93b5f Mon Sep 17 00:00:00 2001 From: Ewan Dennis Date: Tue, 16 Feb 2016 17:07:23 +0000 Subject: [PATCH 3/5] Message events params can now be arrays. Added example code. --- .../messageEvents/search_messageEvents.js | 19 ++++++++++++++ lib/messageEvents.js | 21 ++++++++++++++- test/spec/messageEvents.spec.js | 26 +++++++++++++++++++ 3 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 examples/messageEvents/search_messageEvents.js diff --git a/examples/messageEvents/search_messageEvents.js b/examples/messageEvents/search_messageEvents.js new file mode 100644 index 0000000..36b1b63 --- /dev/null +++ b/examples/messageEvents/search_messageEvents.js @@ -0,0 +1,19 @@ +'use strict'; + +var key = 'YOURAPIKEY' + , SparkPost = require('sparkpost') + , client = new SparkPost(key) + , searchParams = { + events: ['bounce', 'out_of_band'], + bounce_classes: [10,50] + }; + +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!'); + } +}); + diff --git a/lib/messageEvents.js b/lib/messageEvents.js index b4ceeaa..e46f763 100644 --- a/lib/messageEvents.js +++ b/lib/messageEvents.js @@ -9,7 +9,25 @@ var api = 'message-events'; module.exports = function (client) { return { search: function(parameters, callback) { - var options = { + 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 }; @@ -17,3 +35,4 @@ module.exports = function (client) { } }; }; + diff --git a/test/spec/messageEvents.spec.js b/test/spec/messageEvents.spec.js index ad6036f..09a4bca 100644 --- a/test/spec/messageEvents.spec.js +++ b/test/spec/messageEvents.spec.js @@ -41,5 +41,31 @@ describe('Message Events Library', function() { 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: ['bob@example.com', 'jim@example.com'], + //message_ids: ['0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e', '338ac622-4321-5678-0123456789'], + recipients: ['jim@example.com', 'bob@example.com'], + 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(); + }); + }); }); }); From 57a2711f91ac8e9de78bc62fc17192c202263b7d Mon Sep 17 00:00:00 2001 From: Ewan Dennis Date: Tue, 16 Feb 2016 17:10:04 +0000 Subject: [PATCH 4/5] Re-enabled message_ids param in the message events tests --- test/spec/messageEvents.spec.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/spec/messageEvents.spec.js b/test/spec/messageEvents.spec.js index 09a4bca..e26aee9 100644 --- a/test/spec/messageEvents.spec.js +++ b/test/spec/messageEvents.spec.js @@ -48,7 +48,7 @@ describe('Message Events Library', function() { campaign_ids: ['campaign1', 'campaignTwo'], events: ['bounce', 'out_of_band'], friendly_froms: ['bob@example.com', 'jim@example.com'], - //message_ids: ['0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e', '338ac622-4321-5678-0123456789'], + message_ids: ['0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e', '338ac622-4321-5678-0123456789'], recipients: ['jim@example.com', 'bob@example.com'], template_ids: ['newsletter_template', 'newsflash_template'], transmission_ids: ['65832150921904138', '54673829032039839'], From b2daba71ec9887c1f06e215729f1238036e2f558 Mon Sep 17 00:00:00 2001 From: Ewan Dennis Date: Wed, 17 Feb 2016 11:12:26 +0000 Subject: [PATCH 5/5] Added message events docs and example code --- docs/resources/messageEvents.md | 60 +++++++++++++++++++ examples/messageEvents/all_messageEvents.js | 15 +++++ .../messageEvents/search_campaignClicks.js | 19 ++++++ .../messageEvents/search_messageEvents.js | 10 +++- 4 files changed, 101 insertions(+), 3 deletions(-) create mode 100644 docs/resources/messageEvents.md create mode 100644 examples/messageEvents/all_messageEvents.js create mode 100644 examples/messageEvents/search_campaignClicks.js diff --git a/docs/resources/messageEvents.md b/docs/resources/messageEvents.md new file mode 100644 index 0000000..c229b74 --- /dev/null +++ b/docs/resources/messageEvents.md @@ -0,0 +1,60 @@ +# Sending Domains + +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). diff --git a/examples/messageEvents/all_messageEvents.js b/examples/messageEvents/all_messageEvents.js new file mode 100644 index 0000000..5ad4ff3 --- /dev/null +++ b/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!'); + } +}); + diff --git a/examples/messageEvents/search_campaignClicks.js b/examples/messageEvents/search_campaignClicks.js new file mode 100644 index 0000000..82b9e79 --- /dev/null +++ b/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!'); + } +}); + diff --git a/examples/messageEvents/search_messageEvents.js b/examples/messageEvents/search_messageEvents.js index 36b1b63..c446367 100644 --- a/examples/messageEvents/search_messageEvents.js +++ b/examples/messageEvents/search_messageEvents.js @@ -4,9 +4,13 @@ var key = 'YOURAPIKEY' , SparkPost = require('sparkpost') , client = new SparkPost(key) , searchParams = { - events: ['bounce', 'out_of_band'], - bounce_classes: [10,50] - }; + 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) {