Add accounts resource (#5)

* Add accounts resource

* Add options to #transactions

* Implement PR Feedback

Author: Will Myers

CHANGELOG.md

@@ -1,3 +1,9 @@
+2.0.0 August 24, 2016
+  - Added `accounts` resource
+      + `accounts#all`
+      + `accounts#transactions`
+  - Changed response structure.  All responses are now an object with two attributes: `data` containing what was previously the entire response and `meta` containing additional properties about a request.
+
 1.0.0 August 5, 2016
   - Initial Release
 

README.md

@@ -95,11 +95,32 @@ promiseCreator(resolver) {
 }
 ```
 
-The returned promise will either reject with an `Error` or resolve with the API response.
+The returned promise will either reject with an `Error` or resolve with the API response object.
+
+## Responses
+
+All responses will assume the following shape: 
+
+```javascript
+{ 
+  data,
+  meta: {
+    next,
+    previous
+  }
+}
+```
+
+The `data` key will contain any resource data received from the API and the `meta` key will contain high-order information pertaining to the request.
+
+##### meta
+
+* `next`: For any paged resource, `next` will be a cursor to supply for the next page of results. 
+* `previous`: For any paged resource, `previous` will be a cursor to supply for the previous page of results. 
 
 ## Resources
 
-We currently expose only one resource to manage, `Orders`. 
+We currently expose two resource to manage, `Orders` and `Accounts`. 
 
 ### Orders
 
@@ -128,6 +149,7 @@ client.orders.get('btnorder-XXX', function(err, res) {
   // ...
 });
 ```
+
 ##### Update
 
 ```javascript
@@ -148,6 +170,50 @@ client.orders.del('btnorder-XXX', function(err, res) {
 });
 ```
 
+### Accounts
+
+##### All
+
+```javascript
+var client = require('./index')('sk-XXX');
+
+client.accounts.all(function(err, res) {
+    // ...
+});
+```
+
+##### Transactions
+
+Transactions are a paged resource.  The response object will contain properties `meta.next` and `meta.previous` which can be supplied to subsequent invocations of `#transactions` to fetch additional results. 
+
+`#transactions` accepts an optional second parameter, `options` which may define the follow keys to narrow results: 
+
+###### options
+
+* `cursor`: An API cursor to fetch a specific set of results
+* `start`: An ISO-8601 datetime string to filter only transactions after `start`
+* `end`: An ISO-8601 datetime string to filter only transactions before `end`
+
+```javascript
+var client = require('./index')('sk-XXX');
+
+// without options argument
+//
+client.accounts.transactions('acc-1', function(err, res) {
+    // ...
+});
+ 
+// with options argument
+//
+client.accounts.transactions('acc-1', {
+  cursor: 'cXw',
+  start: '2015-01-01T00:00:00Z',
+  end: '2016-01-01T00:00:00Z'
+}, function(err, res) {
+    // ...
+});
+```
+
 ## Contributing
 
 * Installing development dependencies: `npm install`

index.js

@@ -1,5 +1,6 @@
 var resources = require('./lib').resources;
 var maybePromise = require('./lib').maybePromise;
+var request = require('./lib').request;
 var version = require('./package.json').version;
 
 module.exports = function client(apiKey, config) {
@@ -31,7 +32,13 @@ module.exports = function client(apiKey, config) {
     }
   };
 
+  var maybePromiseRequest = maybePromise(
+    request(config.timeout),
+    config.promise
+  );
+
   return {
-    orders: resources.orders(requestOptions, config)
+    orders: resources.orders(requestOptions, maybePromiseRequest),
+    accounts: resources.accounts(requestOptions, maybePromiseRequest)
   };
 }

lib/compact.js

@@ -0,0 +1,26 @@
+'use strict';
+
+function compact(obj) {
+  //
+  // compact removes false-y values from an object
+  //
+  // ## Usage
+  //
+  // compact({ a: 1, b: 0, c: null, d: undefined, e: '', f: NaN })
+  // // => { a: 1 }
+  //
+  // @param {Object} obj the object to compacy
+  // @returns {Object} a new object with only truth-y values remaning
+  //
+  var res = {};
+
+  for (var key in obj) {
+    if (obj[key]) {
+      res[key] = obj[key];
+    }
+  }
+
+  return res;
+}
+
+module.exports = compact;

lib/index.js

@@ -2,6 +2,7 @@
 
 module.exports = {
   resources: require('./resources'),
+  compact: require('./compact'),
   maybePromise: require('./maybePromise'),
   merge: require('./merge'),
   once: require('./once'),

lib/request.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var https = require('https');
+var parse = require('url').parse;
 var once = require('./once');
 
 function request(timeout) {
@@ -86,7 +87,7 @@ function responseHandler(callback) {
       var status = response.meta.status;
 
       if (status === 'ok') {
-        return callback(null, response.object);
+        return callback(null, formatResponse(response));
       } else if (status === 'error') {
         if (typeof response.error !== 'object' || !response.error.message) {
           return callback(new Error('Invalid response: ' + rawResponse), null);
@@ -113,4 +114,23 @@ function timeoutHandler(callback, req) {
   };
 }
 
+function formatResponse(response) {
+  return {
+    data: response.object !== undefined ? response.object : response.objects,
+    meta: {
+      next: formatCursor(response.meta.next),
+      previous: formatCursor(response.meta.previous)
+    }
+  };
+}
+
+function formatCursor(url) {
+  if (typeof url === 'string') {
+    var parsed = parse(url, true);
+    return parsed.query.cursor || null;
+  } else {
+    return null;
+  }
+}
+
 module.exports = request;

lib/resources/accounts.js

@@ -0,0 +1,66 @@
+'use strict';
+
+var querystring = require('querystring');
+var merge = require('../merge');
+var compact = require('../compact');
+
+function accounts(requestOptions, maybePromiseRequest) {
+  return {
+    all: function all(callback) {
+      //
+      // Gets an index of all available accounts.
+      //
+      // @callback invoked iff config.promise isn't valid
+      // @returns {Object=} a promise or undefined, depending on
+      //   `config.promise`
+      //
+      var options = merge(requestOptions, {
+        method: 'GET',
+        path: '/v1/affiliation/accounts'
+      });
+
+      return maybePromiseRequest(options, callback);
+    },
+    transactions: function transactions(accountId, params, callback) {
+      //
+      // Gets an index of all transactions for a given account.
+      //
+      // @param {string} accountId the account id
+      // @param {Object=} params an object of optional options for the
+      //                  request
+      // @param {string=} params.cursor an opague string returned by a response
+      //                  which returns consistent results
+      // @param {string=} params.start an ISO-8601 datetime to filter results
+      // @param {string=} params.end an ISO-8601 datetime to filter results
+      // @callback invoked iff config.promise isn't valid
+      // @returns {Object=} a promise or undefined, depending on
+      //   `config.promise`
+      //
+      if (typeof params === 'function') {
+        callback = params;
+        params = {};
+      }
+
+      if (Object.prototype.toString.call(params) !== '[object Object]') {
+        params = {};
+      }
+
+      var queryString = querystring.stringify(compact({
+        cursor: params.cursor,
+        start: params.start,
+        end: params.end
+      }));
+
+      var query = queryString ? '?' + queryString : '';
+
+      var options = merge(requestOptions, {
+        method: 'GET',
+        path: '/v1/affiliation/accounts/' + accountId + '/transactions' + query
+      });
+
+      return maybePromiseRequest(options, callback);
+    }
+  };
+}
+
+module.exports = accounts;

lib/resources/index.js

@@ -1,5 +1,6 @@
 'use strict';
 
 module.exports = {
+  accounts: require('./accounts'),
   orders: require('./orders')
 };

lib/resources/orders.js

@@ -1,19 +1,12 @@
 'use strict';
 
-var request = require('../request');
-var maybePromise = require('../maybePromise');
 var merge = require('../merge');
 
-function orders(requestOptions, config) {
-  var maybePromiseRequest = maybePromise(
-    request(config.timeout),
-    config.promise
-  );
-
+function orders(requestOptions, maybePromiseRequest) {
   return {
     get: function get(orderId, callback) {
       //
-      //  Gets an order.
+      // Gets an order.
       //
       // @param {string} orderId the order id
       // @callback invoked iff config.promise isn't valid
@@ -29,7 +22,7 @@ function orders(requestOptions, config) {
     },
     create: function create(order, callback) {
       //
-      //  Creates an order.
+      // Creates an order.
       //
       // @param {Object} order the order
       // @callback invoked iff config.promise isn't valid
@@ -45,7 +38,7 @@ function orders(requestOptions, config) {
     },
     update: function update(orderId, order, callback) {
       //
-      //  Updates an order.
+      // Updates an order.
       //
       // @param {string} orderId the order id
       // @param {Object} order the order
@@ -62,7 +55,7 @@ function orders(requestOptions, config) {
     },
     del: function del(orderId, callback) {
       //
-      //  Deletes an order.
+      // Deletes an order.
       //
       // @param {string} orderId the order id
       // @callback invoked iff config.promise isn't valid

package.json

@@ -1,6 +1,6 @@
 {
   "name": "button-client-node",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "node.js client for the Button Order API",
   "main": "index.js",
   "scripts": {