stripe-chainable

Syntactic sugar for stripe-node

stripe
  .find()
  .last(150)
  .charges(function(err, charges) {
    // 'nuff said
  });

stripe
  .entire()
  .charges()
  .history()
  .since(new Date(2015, 0, 1))
  .please(function(err, balance) {
    // What he said
  });

Why?

We believe the folks over at Stripe built an awesome API, but found it a bit lacking when it came to generating boring detailed reports. With that in mind, we designed a set of intuitive methods for crafting beautiful queries.

Indeed, stripe-chainable is intentionally limited in scope and very much complementary to Stripe's module. In fact, it focuses on a single operation: retrieving exactly the bunch of objects you're looking for.

Where?

npm install stripe-chainable or yarn add stripe-chainable

How?

Exactly the same as, well, Stripe.

var stripe = require('stripe-chainable')(key[, version]);

Your key goes straight to Stripe's module, not even an internal reference is kept.

What?

Sugar

Akin to assertion frameworks, stripe-chainable provides keywords to build queries in plain English.

• and(): pure sugar

• of(): pure sugar

• that(): pure sugar

• since(date): alias for from(), except date is mandatory

• until([date]): alias for to()

• entire(): alias for all()

• for([string]): alias for setAccount() and used for setting customer id, charge id and purpose

• find([number]): sugar allowing to set a limit

• last(number): limits results to this value

• all(): queries the Stripe API until all the objects are returned

• are(string): sets a status

• type(string): sets an event type

• available(): tells the following time-based methods to set available_on instead of created

• before([mixed]): may be called with a date or used as a synonym for ending_before

• after([mixed]): may be called with a date or used as a synonym for starting_after

• from([date]): may be called with a date (inclusive)

• to([date]): may be called with a date (inclusive)

• now(): chain with to(), until()

• include(key): sets the include[] key, Stripe only makes total_count available at the moment

• setAccount(acct_id): sets the account id to use (for Stripe Connect users)

• history(): use the Balance history API for this query, in conjuction with one of:

  • charges()
  • refunds()
  • adjustments()
  • applicationFees()
  • applicationFeeRefunds()
  • transfers()
  • transferFailures()

• The following may be used to set context or execute the query in that context:

  • charges()
  • customers()
  • plans()
  • subcriptions()
  • coupons()
  • invoices()
  • invoiceItems()
  • transfers()
  • applicationFees()
  • accounts()
  • events()
  • bitcoinReceivers()
  • fileUploads()

For executing, a callback must be supplied and an optional progress callback is available as well

• charges([progress, ]callback)

With the following signatures:

• progress(current, total)
• callback(err, objects)

It's often clearer to set context early in a sentence and execute later. These methods may be used for executing a chain:

• please([progress, ]callback)

Supported objects

• Charges
  • customer set with for('cus_id'))
• Customers
• Plans
• Coupons
• Invoices
• Invoice items
  • customer set with for('cus_id')
• Applications fees
  • charge set with for('ch_id')
• Accounts
  • Note: Stripe does not support filtering on this object
• Events
  • type set with type('type'), list of types
• File uploads
  • purpose argument set with for('purpose'), list of purposes

Partially supported objects

• Refunds
  • Strictly through Balance history (refunds().history())
• Disputes
  • Strictly through adjustments with Balance history (adjustments().history())
• Transfers
  • status set with are('status'), list of statuses
  • date and recipient are not supported at the moment
• Balance history (through the history() method)
  • available_on set by preceding time-based methods (from(), to(), etc) by available()
  • type set through object context methods (charges(), refunds(), etc)
  • source set with for('ch_id')
  • currency and transfer are not supported at the moment
• Bitcoin receivers
  • active, filled and uncaptured_funds are not supported at the moment

Currently unsupported objects

• Cards
• Subscriptions
• Discounts
• Transfer reversals
• Application fee refunds
• Balance
• Tokens

Objects deprecated by Stripe are unsupported

• Recipients

Feature

Yes, that's feature. Without an s.

The Stripe API limits the number of objects returned to 100. Fair enough, but what if you need more?

stripe
  .find()
  .all()
  .charges(function(err, charges) {
    // They're all here, automatically queried and concatenated.
  });

Wait, what?

All methods return this, making it possible to chain anything with (almost) anything. Here are a few examples.

List

stripe
  .find()
  .all()
  .charges()
  .since(new Date(2015, 0, 1))
  .please(
    function(current, total) {
      console.info("%d / %d", current, total);
    },
    function(err, charges) {
      // All charges in 2015 up until now
    }
  );

stripe
  .find()
  .last(50)
  .customers()
  .after(new Date(2014, 11, 31))
  .please(function(err, customers) {
    // Last 50 customers created after December 31st 2014
  });

stripe
  .find()
  .all()
  .transfers()
  .that()
  .are("pending")
  .please(function(err, transfers) {
    // All pending transfers
  });

Balance

stripe
  .entire()
  .history()
  .of()
  .applicationFees()
  .from(new Date(2015, 3, 1))
  .until()
  .now()
  .and()
  .include("total_count")
  .please(function(err, balance) {
    // Self-explanatory
  });

stripe
  .entire()
  .history()
  .available()
  .from(new Date(2015, 4, 1))
  .please(
    function(progress, total) {
      console.info("%d / %d", progress, total);
    },
    function(err, charges) {
      // Self-explanatory
    }
  );

Does it work?

Yes, according to mocha, chai, sinon and istanbul.

npm install
npm test

Can I use?

Yes, stripe-chainable is MIT licensed.