wolfbiter / splitwise

A JavaScript SDK for the Splitwise API.

splitwise

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.

• sw.test()
• sw.getCurrencies()
• sw.getCategories()
• sw.parseSentence()
• sw.getCurrentUser()
• sw.getUser()
• sw.updateUser()
• sw.getGroups()
• sw.getGroup()
• sw.createGroup()
• sw.deleteGroup()
• sw.addUserToGroup()
• sw.removeUserFromGroup()
• sw.getExpenses()
• sw.getExpense()
• sw.createExpense()
• sw.updateExpense()
• sw.deleteExpense()
• sw.getFriends()
• sw.getFriend()
• sw.createFriend()
• sw.createFriends()
• sw.deleteFriend()
• sw.getNotifications()
• sw.getMainData()

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

This SDK only enables accessing the user data of the developer (owner) of the application for the linked key/secret. If you need a solution to enable users to access their own data for use in your app or service you will need to look elsewhere.

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

License

MIT