A JavaScript SDK for the Splitwise API.
Clone or download
keriwarr chore(package): update yarn lock (#17)
* chore(pacakge): update yarn lock

* chore(travis): only run branch CI on master
Latest commit 88a45d0 Nov 25, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates (#11) Oct 6, 2018
.vscode Dev (#16) Nov 25, 2018
__mocks__ Dev (#16) Nov 25, 2018
__tests__ Dev (#16) Nov 25, 2018
src Dev (#16) Nov 25, 2018
.editorconfig Add .editorconfig Oct 6, 2018
.eslintrc.js Dev (#16) Nov 25, 2018
.gitignore Switch to Standard JS Nov 13, 2017
.travis.yml chore(package): update yarn lock (#17) Nov 25, 2018
LICENSE Initial commit Nov 11, 2017
README.md Add Codecov badge (#10) Oct 6, 2018
jest.config.js Dev (#16) Nov 25, 2018
package.json Dev (#16) Nov 25, 2018
yarn.lock chore(package): update yarn lock (#17) Nov 25, 2018

README.md

splitwise

Greenkeeper badge codecov

A JavaScript SDK for the Splitwise API.

Quickstart

Step 1: Register your Application

You will need a consumer key and a consumer secret from Splitwise to use this SDK. Get them here: https://secure.splitwise.com/oauth_clients.

Step 2: Install

This module works with Node.js, version 6 or newer. To install, run:

 $ yarn add splitwise

Step 3: Get the current user

const Splitwise = require('splitwise')
const sw = Splitwise({
  consumerKey: 'your key here',
  consumerSecret: 'your secret here'
})

sw.getCurrentUser().then(console.log) // => { id: ... }

Non-trivial Example

In this example, we create a new expense from the current user to the first listed user in the given group, with the same description as the first given expense.

const Splitwise = require('splitwise')
const sw = Splitwise({
  consumerKey: 'your key here',
  consumerSecret: 'your secret here'
})
const group_id = '12345678'

Promise.all([
  sw.getGroup({ id: group_id }),
  sw.getExpenses({ id: group_id }),
  sw.getCurrentUser()
]).then(([group, expenses, me]) => sw.createDebt({
  from: group.members[0].id,
  to: me.id,
  group_id: group_id,
  description: expenses[0].description,
  amount: 100
})).then(
  console.log
).catch(
  console.error
)

API Reference

const sw = Splitwise({...})

This is the entry point to the package. All of the other methods are in the form of properties of sw.

Click here to view the list of available methods.

Parameters

name required? notes
consumerKey yes Obtained by registering your application
consumerSecret yes Obtained by registering your application
accessToken no Re-use an existing access token
logger no Will be called with info and error messages
logLevel no Set to 'error' to only see error messages
group_id no See below
user_id no "
expense_id no "
friend_id no "

The following parameters: group_id, user_id, expense_id, and friend_id can be passed in, to be used by default with all get/update/delete type operations. For example:

const sw = Splitwise({
  // ...
  group_id: '12345678',
});

sw.getGroup({ id: '12345678' }).then(console.log);
// is equivalent to
sw.getGroup().then(console.log);

Logging

You can pass in a logging function to see useful debugging output. If the logger that is passed in has info or error properties, then logger.info and logger.error will be called with info and error messages respectively. Otherwise, logger will itself be called with a string as the first argument. Therefore, for debugging purposes, console.log is recommended.

If you only want to see logs in the case of an error, you can pass in logLevel: 'error'. e.g.:

const sw = Splitwise({
  consumerKey: 'your key here',
  consumerSecret: 'your secret here',
  logger: console.log
})
// => Info: making request for access token
// ...
// => Info: successfully aquired access token
const sw = Splitwise({
  consumerKey: 'your key here',
  consumerSecret: 'INCORRECT secret here',
  logger: console.log,
  logLevel: 'error'
})
// ...
// => Error: your credentials are incorrect

sw.getAccessToken()

When you call Splitwise(), an access token will automatically be fetched using your consumer credentials. If you wish to avoid this behaviour in order to save yourself a network round-trip, you may pass in your own accessToken. You can obtain a re-usable access token as follows:

Splitwise({
  consumerKey: 'your key here',
  consumerSecret: 'your secret here'
}).getAccessToken().then(console.log) // => abcd1234...

// Now save the token somewhere (but don't check it into your VCS!)

const sw = Splitwise({
  consumerKey: 'your key here',
  consumerSecret: 'your secret here',
  accessToken: 'abcd1234...'
})
// do stuff with `sw`

sw.createDebt({...})

The endpoint for creating debts is a little awkward to use. If you are in the common scenario of needing to create a simple debt between two individuals, this method will do just that.

sw.createDebt({
  from: '23456789',
  to: '34567890',
  amount: 100,
  description: 'I am broke, please give me $100',
  group_id: '12345678' // optional
})

Methods

All of the below methods should be called with an object of parameters as the first argument, and (if you must), a callback as the second argument. They all will return Promises which will be resolved if and only if the request was successful, and rejected otherwise. e.g.:

sw.verbResource({
  id: '12345678',
  otherParam: 'foo'
} /*, callback */).then(
  data => doSomethingWithTheData(data)
).catch(
  error => handleTheError(error)
)

Without further ado, here is the list of all available methods. In order to see the specifics of which parameters should be passed in, and which data can be expected in response, please refer to the official API documentation, or click on the method in question.

NOTE: Splitwise makes some important notes about their API that booleans and nested parameters don't work. You won't need to worry about this. That is, instead of calling:

sw.createExpense({ // :'(
  users__0__user_id: '23456789',
  users__1__users_id: '34567890',
  payment: 0
})

You can instead do:

sw.createExpense({
  users: [
    { user_id: '23456789' },
    { user_id: '34567890' }
  ],
  payment: false
})

Notes

Here is a potential alternative to this package: https://github.com/Dean177/splitwise-node

License

MIT