fortysix-elks - npm Package Compare versions

Comparing version 0.0.2 to 0.0.3

lib/client.js

@@ -36,12 +36,35 @@ var request = require('request');
 // 
-// from     - A string of max 11 alphanumeric charachters (a-zA-Z0-9). This will
-//            show up as the sender of the text message in the recipients phone.
-// to       - A string containing an E.164-formatted phone number. This is the
-//            recipients of the text message.
-// message  - A string containing the message to be sent.
-// callback - A function accepting an 'err' argument. This is called when the
-//            request has been sent to 46elks.
+// from          - A string of max 11 alphanumeric characters (a-zA-Z0-9). This
+//                 will show up as the sender of the text message in the
+//                 recipients phone.
+// to            - A string containing an E.164-formatted phone number. This is
+//                 the recipient of the text message. This string can also
+//                 contain a maximum of 200 E.164-formatted phone numbers in
+//                 which case the text message will be sent to every phone
+//                 number in the list.
+// message       - A string containing the message to be sent.
+// whendelivered - An URL to which delivery reports will be posted (optional).
+// callback      - A function accepting an 'err' and 'sms' param. This is called
+//                 when the request has been sent to 46elks. The 'sms' argument
+//                 contains the response object from 46elks. This object has the
+//                 following keys:
+//            
+//                 from      - This is the should be the same as the 'from'
+//                             param that was passed in.
+//                 to        - This is the should be the same as the 'to' param
+//                             that was passed in.
+//                 message   - This is the should be the same as the 'message'
+//                             param that was passed in.
+//                 id        - The 46elks ID of the SMS.
+//                 cost      - An integer representing the number of cents (or 
+//                             equivalent) times one hundred that was deducted
+//                             from the 46elks account balance. That would be
+//                             3500 for 35 cents. This is given in the currency
+//                             of the account.
+//                 direction - This is always set to 'outgoing'
+//                 created   - A Date object representing the time the SMS was
+//                             created in the 46elks system.
 //
 // Returns undefined.
-Client.prototype.sendSMS = function(from, to, message, callback) {
+Client.prototype.sendSMS = function(from, to, message, whendelivered, callback) {
   if (!from) throw new Error('The param \'from\' was not supplied.');
@@ -55,12 +78,30 @@ if (!to) throw new Error('The param \'to\' was not supplied.');
                                                      '0-9');
-  this.post('/SMS', {
+  if (to.split(',').length > 200) throw new Error('\'to\' can\'t contain more '+
+                                                  'than 200 numbers');
+
+  // Handle the case where whendelivered is not passed.
+  if (typeof whendelivered === 'function') {
+    callback = whendelivered;
+    whendelivered = null;
+  }
+
+  var data = {
     from: from,
     to: to,
     message: message,
-  }, function(err, res) {
+  };
+
+  // If whendelivered is given, add it to the data we're sending.
+  if (whendelivered) {
+    data.whendelivered = whendelivered;
+  }
+
+  this.post('/SMS', data , function(err, res, body) {
     if (err) return callback(err);
     if (res.statusCode !== 200) {
-      return callback(new Error("46elks responded with code "+res.statusCode));
+      return callback(new Error("46elks error ("+res.statusCode+"): "+body));
     }
-    callback(null);
+    var data = JSON.parse(body);
+    data.created = new Date(data.created);
+    callback(null, data);
   });
@@ -67,0 +108,0 @@ };

package.json

 {
   "name": "fortysix-elks",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A wrapper for the 46elks (http://46elks.com) API. At the moment only sms functions are supported",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -11,2 +11,51 @@ fortysix-elks
 npm install fortysix-elks
-```
+```
+
+Usage
+-----
+
+### Set up the Client
+
+Require the fortysix-elks module and initalize a new client using your 46elks
+credentials. If the environment variables `FORTYSIXELKS_USERNAME` and
+`FORTYSIXELKS_PASSWORD` are set these two parameters can be omitted.
+
+```
+var fortysixElks = require('fortysix-elks');
+var fc = new fortysixElks.Client('46elks username', '46elks password');
+```
+
+### Send an SMS
+
+Please check the code comments for details of this functions parameters and the
+values passed to the callback.
+
+```
+fc.sendSMS('Sender', '+4670****085', 'Hello!', function(err, res) {
+  console.log(err);
+  console.log(res);
+});
+```
+
+Changelog
+---------
+### 0.0.3 (2013-09-19)
+* The sendSMS() callback now receives a parsed version of the data that is
+  returned by the 46elks API. Please see the comments in the code or the tests
+  for an explanation of this data.
+* Error messages from the 46elks API is now passed as a part of the Error
+  object's message.
+* Support for text message delivery reports.
+
+### 0.0.2 (2013-09-18)
+* It is now possible to send text messages to multiple recipients.
+
+### 0.0.1 (2013-09-18)
+* Initial release.
+
+TODO
+----
+
+* Support for phone number allocation.
+
+* Support for phone number modification and deallocation.

test/lib/client_test.js

@@ -5,3 +5,3 @@ var nock   = require('nock');
 describe('Client', function() {
-  it('throws if username param isn\'t specified', function(done) {
+  it('throws if \'username\' isn\'t specified', function(done) {
     (function(){
@@ -13,3 +13,3 @@ new Client(undefined, 'pass');
 
-  it('throws if password param isn\'t specified', function(done) {
+  it('throws if \'password\' isn\'t specified', function(done) {
     (function(){
@@ -21,3 +21,3 @@ new Client('user', undefined);
 
-  it('doesn\'t throw when username param isn\'t specified if the '+
+  it('doesn\'t throw if \'username\' isn\'t specified if the '+
      'FORTYSIXELKS_USERNAME environment variable is defined', function(done) {
@@ -31,3 +31,3 @@ process.env.FORTYSIXELKS_USERNAME = 'user';
 
-  it('doesn\'t throw when password param isn\'t specified if the '+
+  it('doesn\'t throw if \'password\' isn\'t specified if the '+
      'FORTYSIXELKS_PASSWORD environment variable is defined', function(done) {
@@ -45,3 +45,3 @@ process.env.FORTYSIXELKS_PASSWORD = 'pass';
       (function(){
-        c.sendSMS(undefined, '[phone]', 'Hej!', function() {});
+        c.sendSMS(undefined, '+4670****085', 'Hej!', function() {});
       }).should.throwError(/'from' was not supplied/);
@@ -51,34 +51,47 @@ done();
 
-    it('throws if \'to\' is not supplied', function(done) {
+    it('throws if \'from\' is longer than 11 characters', function(done) {
       var c = new Client('user', 'pass');
       (function(){
-        c.sendSMS('Calle', undefined, 'Hej!', function() {});
-      }).should.throwError(/'to' was not supplied/);
+        c.sendSMS('abcdefghijkl', '+4670****085', 'Hej!', function() {});
+      }).should.throwError(/'from' can't be longer than 11 charcters/);
       done();
     });
 
-    it('throws if \'message\' is not supplied', function(done) {
+    it('throws if \'from\' contains illegal characters', function(done) {
       var c = new Client('user', 'pass');
       (function(){
-        c.sendSMS('Calle', '[phone]', undefined, function() {});
-      }).should.throwError(/'message' was not supplied/);
+        c.sendSMS('a.asd', '+4670****085', 'Hej!', function() {});
+      }).should.throwError(/'from' can only contain a-z, A-Z and 0-9/);
       done();
     });
 
-    it('throws if \'from\' is longer than 11 characters', function(done) {
+    it('throws if \'to\' is not supplied', function(done) {
       var c = new Client('user', 'pass');
       (function(){
-        c.sendSMS('abcdefghijkl', '[phone]', 'Hej!', function() {});
-      }).should.throwError(/'from' can't be longer than 11 charcters/);
+        c.sendSMS('Calle', undefined, 'Hej!', function() {});
+      }).should.throwError(/'to' was not supplied/);
       done();
     });
 
-    it('throws if \'from\' contains illegal characters', function(done) {
+    it('throws if \'to\' contains more than 200 commas separated phone '+
+       'numbers', function(done) {
+      var to = '+4670****085';
+      for (var i = 0; i < 200; i++) {
+        to += ',+4670****085';
+      }
       var c = new Client('user', 'pass');
       (function(){
-        c.sendSMS('a.asd', '[phone]', 'Hej!', function() {});
-      }).should.throwError(/'from' can only contain a-z, A-Z and 0-9/);
+        c.sendSMS('Calle', to, 'Hej!', function() {});
+      }).should.throwError(/'to' can't contain more than 200 numbers/);
       done();
     });
 
+    it('throws if \'message\' is not supplied', function(done) {
+      var c = new Client('user', 'pass');
+      (function(){
+        c.sendSMS('Calle', '+4670****085', undefined, function() {});
+      }).should.throwError(/'message' was not supplied/);
+      done();
+    });
+
     it('sends a request to the 46elks API', function(done) {
@@ -89,7 +102,15 @@ var c = new Client('user', 'pass');
                     from: 'Calle',
-                    to: '[phone]',
+                    to: '+4670****085',
                     message: 'Hej!'
                   })
-                  .reply(200);
-      c.sendSMS('Calle', '[phone]', 'Hej!', function(err) {
+                  .reply(200, {
+                    direction: 'outgoing',
+                    from: 'Calle',
+                    created: '2013-09-18T06:55:54.431635',
+                    to: '+4670****085',
+                    cost: 3500,
+                    message: 'helloooo', 
+                    id: 'sc591f694d80da1****c126ef3605466a'
+                  });
+      c.sendSMS('Calle', '+4670****085', 'Hej!', function(err) {
         if (err) throw err;
@@ -101,2 +122,27 @@ req.isDone().should.be.true;
 
+    it('passes the whendelivered param to 46elks if given', function(done) {
+      var c = new Client('user', 'pass');
+      var req = nock('https://api.46elks.com')
+                  .post('/a1/SMS', {
+                    from: 'Calle',
+                    to: '+4670****085',
+                    message: 'Hej!',
+                    whendelivered: 'http://google.com',
+                  })
+                  .reply(200, {
+                    direction: 'outgoing',
+                    from: 'Calle',
+                    created: '2013-09-18T06:55:54.431635',
+                    to: '+4670****085',
+                    cost: 3500,
+                    message: 'helloooo', 
+                    id: 'sc591f694d80da1****c126ef3605466a'
+                  });
+      c.sendSMS('Calle', '+4670****085', 'Hej!', 'http://google.com', function(err) {
+        if (err) throw err;
+        req.isDone().should.be.true;
+        done();
+      });
+    });
+
     it('errors if the response code from 46elks wasn\'t 200', function(done) {
@@ -107,12 +153,45 @@ var c = new Client('user', 'pass');
                     from: 'Calle',
-                    to: '[phone]',
+                    to: '+4670****085',
                     message: 'Hej!'
                   })
-                  .reply(503);
-      c.sendSMS('Calle', '[phone]', 'Hej!', function(err) {
-        err.message.should.match(/responded with code 503/);
+                  .reply(403, 'Error message');
+      c.sendSMS('Calle', '+4670****085', 'Hej!', function(err) {
+        err.message.should.match(/46elks error \(403\): Error message/);
         done();
       });
     });
+
+    it('passes an object containing the data 46elks returned to the callback', function(done) {
+      var c = new Client('user', 'pass');
+      var req = nock('https://api.46elks.com')
+                  .post('/a1/SMS', {
+                    from: 'Calle',
+                    to: '+4670****085',
+                    message: 'Hej!'
+                  })
+                  .reply(200, {
+                    direction: 'outgoing',
+                    from: 'Calle',
+                    created: '2013-09-18T06:55:54.431635',
+                    to: '+4670****085',
+                    cost: 3500,
+                    message: 'helloooo', 
+                    id: 'sc591f694d80da1****c126ef3605466a'
+                  });
+      c.sendSMS('Calle', '+4670****085', 'Hej!', function(err, sms) {
+        if (err) throw err;
+        (sms.created instanceof Date).should.be.true;
+        sms.should.eql({
+          direction: 'outgoing',
+          from: 'Calle',
+          created: new Date('2013-09-18T06:55:54.431635'),
+          to: '+4670****085',
+          cost: 3500,
+          message: 'helloooo', 
+          id: 'sc591f694d80da1****c126ef3605466a'
+        });
+        done();
+      });
+    });
   });
 });

No alert changes

Improved metrics

Total package byte prevSize

13175

increased by90.86%

Lines of code

272

increased by71.07%

Number of lines in readme file

60

increased by445.45%

No dependency changes