initial comimt

Author: Ilya Volodarsky

.gitignore

@@ -0,0 +1 @@
+node_modules

History.md

@@ -0,0 +1,4 @@
+
+0.0.1 - February 26, 2014
+-------------------------
+:sparkles:

Makefile

@@ -0,0 +1,8 @@
+
+node_modules: package.json
+	@npm install
+
+test: node_modules
+	@./node_modules/.bin/mocha --reporter spec
+
+.PHONY: test

Readme.md

@@ -0,0 +1,133 @@
+
+# stripe-cohort
+
+  Create Stripe customer cohorts for a useful business overview.
+
+### Overview
+
+If you're interested in getting a cohort based overview of your Stripe customers, then this library might be of help.
+
+It currently supports the following stats (by cohort):
+
+- Total number of customers
+- Monthly recurring revenue 
+- Number of subscriptions
+- Subscriptions by plan
+
+## Installation
+
+    $ npm install stripe-cohort
+
+## Example
+
+Create a new Stripe cohort (by the customer's `created` date):
+
+```js
+cohort(new Date('1/1/2014'), new Date('2/1/2014'), function (err, customers) {
+  console.log(customers.count() + ' created in January!');
+});
+```
+
+And the `customers` object lets you query information about this cohort.
+
+#### Number of Customers
+
+You can query the total amount of customers returned:
+
+```js
+customers.count();
+```
+
+or filter further inside the cohort by the customers' `created` date:
+
+```js
+customers.count(new Date('1/15/2014'), new Date('1/24/2014'));
+```
+
+#### Customer List
+
+```js
+customers.list()
+```
+```
+[
+  {
+    id: 'cus_2983jd92d2d',
+    name: 'Patrick Collison',
+    ..
+  }
+}
+]
+```
+or filter further by the customers' `created` date:
+
+```js
+customers.list(new Date('1/15/2014'), new Date('1/24/2014'));
+```
+
+or get all the `delinquent` customers:
+
+```js
+customers.delinquent().count();
+```
+
+#### Subscriptions
+
+You can learn about your active subscriptions too
+
+```js
+customers.subscriptions().count();
+```
+
+Or the ones created between the date provided:
+
+```js
+customers.subscriptions(new Date('1/15/2014'), new Date('1/24/2014')).count();
+```
+
+Or just get the list of Stripe subscription objects:
+
+```js
+var objects = customers.subscriptions().list();
+```
+
+#### Monthly Recurring Revenue
+
+You can get the monthly recurring revenue from the active subscriptions on the customers:
+
+```js
+customers.subscriptions().active().mrr();
+```
+
+And for the trialing accounts:
+
+```js
+customers.subscriptions().trialing().mrr();
+```
+
+And for any status really:
+
+```js
+customers.subscriptions().status('unpaid').mrr();
+```
+
+And you can query the monthly recurring revenue  by subscription `start` within a cohort: 
+
+```js
+customers.subscriptions().active().mrr(new Date('1/15/2014'), new Date('1/16/2014'));
+```
+
+Remember that the montly recurring revenue does not equal charges. For example, if a customer upgrades from a $29 plan to a $79 plan today, they will pro-rated for the rest of their billing period. That means you did not make the $79 yet, but you'll make the difference next month. For hard cash, use charges.
+
+#### Plans
+
+It's also interesting to know what plans the subscriptions are being set at. You can select the subscriptions that fall under that plan:
+
+```js
+var mrr = customers.subscriptions().active().plan('startup').mrr();
+console.log('We made $' + mrr + ' off the startup plan!');
+```
+
+## License
+
+MIT

lib/customers.js

@@ -0,0 +1,108 @@
+
+var Subscriptions = require('./subscriptions');
+var util = require('util');
+
+/**
+ * Expose `Customers`.
+ */
+
+module.exports = Customers;
+
+/**
+ * A cohort of Stripe `customers`.
+ *
+ * @param {Array|Customer} customers
+ *
+ */
+
+function Customers (customers) {
+  this.customers = customers;
+}
+
+/**
+ * Return a new `Customers` thats filtered by `start` and `end`.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ * @return {Customers}
+ */
+
+Customers.prototype.created = function (start, end) {
+  if (!util.isDate(start)) return this;
+  if (!util.isDate(end)) end = new Date('1/1/99999');
+  var s = start.getTime(), e = end.getTime();
+  return new Customers(this.customers.filter(function (customer) {
+    var created = customer.created * 1000;
+    return created >= s && created <= e;
+  }));
+};
+
+/**
+ * Return a new `Customers` thats filtered by delinquent customers.
+ *
+ * @param {Boolean} delinquent
+ * @return {Customers}
+ */
+
+Customers.prototype.delinquent = function (delinquent) {
+  if (typeof delinquent !== 'boolean') delinquent = true;
+  return new Customers(this.customers.filter(function (customer) {
+    return customer.delinquent === delinquent;
+  }));
+};
+
+/**
+ * Filter customers by `fn`.
+ *
+ * @param {Function} fn
+ * @return {Customers}
+ */
+
+Customers.prototype.filter = function (fn) {
+  return new Customers(this.customers.filter(fn));
+};
+
+/**
+ * Count the customers between `start` and `end`.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ * @return {Number}
+ */
+
+Customers.prototype.list = function (start, end) {
+  return this.created(start, end).customers;
+};
+
+/**
+ * Count the customers between `start` and `end`.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ * @return {Number}
+ */
+
+Customers.prototype.count = function (start, end) {
+  return this.created(start, end).customers.length;
+};
+
+/**
+ * Get a list of active subscriptions between `start` and `end`.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ * @return {Subscriptions}
+ */
+
+Customers.prototype.subscriptions = function (start, end) {
+  var all = [];
+  this.customers.forEach(function (customer) {
+    var subscriptions = customer.subscriptions.data;
+    subscriptions.forEach(function (subscription) {
+      // create a backwards reference so that we can check discount
+      subscription.customer = customer;
+    });
+    all.push.apply(all, subscriptions);
+  });
+  return new Subscriptions(all).started(start, end);
+};

lib/index.js

@@ -0,0 +1,117 @@
+
+var Batch = require('batch');
+var Customers = require('./customers');
+var debug = require('debug')('stripe-cohort');
+var defaults = require('defaults');
+var range = require('range-component');
+var Stripe = require('stripe');
+var unixTime = require('unix-time');
+var util = require('util');
+
+/**
+ * Expose `Cohorter`.
+ */
+
+module.exports = Cohorter;
+
+/**
+ * Initialize a new `Cohorter` the Stripe `key`.
+ *
+ * @param {String} key
+ * @param {Object} options
+ *   @param {Number} count
+ */
+
+function Cohorter (key, options) {
+  if (!(this instanceof Cohorter)) return new Cohorter(key, options);
+  if (!key) throw new Error('Stripe cohort requires a Stripe key.');
+  this.stripe = Stripe(key);
+  this.options = defaults(options, { count: 100, concurrency: 20 });
+  var self = this;
+  return function () { self.cohort.apply(self, arguments); };
+}
+
+/**
+ * Create a cohort.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ * @param {Function} callback
+ */
+
+Cohorter.prototype.cohort = function (start, end, callback) {
+  if (!util.isDate(start)) throw new Error('Start must be a date.');
+  if (!util.isDate(end)) throw new Error('End must be a date.');
+  var self = this;
+  debug('creating cohort [%s - %s] ..', start, end);
+  this.customers(start, end, function (err, customers) {
+    if (err) return callback(err);
+    debug('created cohort');
+    callback(null, new Customers(customers));
+  });
+};
+
+/**
+ * Load customers between a `start` and `end` date.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ * @param {Function} callback
+ */
+
+Cohorter.prototype.customers = function (start, end, callback) {
+  debug('loading customers with created [%s - %s] ..', start, end);
+  var self = this;
+  var customers = [];
+  var page = this.options.count;
+  // run the first query to get the total unpaginated count
+  this.query(start, end, 0, function (err, res) {
+    if (err) return callback(err);
+    var count = res.count;
+    customers.push.apply(customers, res.data);
+    var got = res.data.length;
+    var left = res.count - got;
+    // check if we grabbed everything in the first query
+    if (0 === left) return callback(null, customers);
+    // there's more, we have to paginate query
+    var pages = Math.ceil(left / page);
+    debug('loaded %d customers, %d left in %d pages of %d', got, left, pages, page);
+    var batch = new Batch();
+    batch.concurrency(self.options.concurrency);
+    range(0, pages).forEach(function (i) {
+      batch.push(function (done) { self.query(start, end, got + (i * page), done); });
+    });
+    batch.end(function (err, results) {
+      if (err) return callback(err);
+      results.forEach(function (res) {
+        customers.push.apply(customers, res.data);
+      });
+      debug('finished loading all customers in cohort');
+      callback(null, customers);
+    });
+  });
+};
+
+/**
+ * List customers between a `start` and `end` date, with an `offset`.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ * @param {Number} offset
+ * @param {Function} callback
+ */
+
+Cohorter.prototype.query = function (start, end, offset, callback) {
+  debug('loading customers with created [%s - %s] with offset %d ..', start, end, offset);
+  var options = {
+    created: { gte: unixTime(start), lte: unixTime(end) },
+    count: this.options.count,
+    offset: offset
+  };
+  this.stripe.customers.list(options, function (err, res) {
+    if (err) return callback(err);
+    var customers = res.data;
+    debug('loaded %d customers with offset %d', customers.length, offset);
+    callback(null, res);
+  });
+};