Skip to content

Latest commit

 

History

History
235 lines (181 loc) · 6.82 KB

README.md

File metadata and controls

235 lines (181 loc) · 6.82 KB
Raw

stripe-chainable Build Status npm package Coverage Status

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

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()
    • 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
  • File uploads

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 i
npm test

Who?

FluidApps and the community.

Can I use?

Yes, stripe-chainable is MIT licensed.