Splitwise Ruby Gem

A Ruby gem for the Splitwise API.

Installation

Add this line to your application's Gemfile:

gem 'splitwise'

And then execute:

$ bundle

Or install it yourself as:

$ gem install splitwise

Configuration

follow this to get required key and secret

require 'splitwise'

SPLITWISE_KEY = <YOUR_CONSUMER_KEY> 
SPLITWISE_SECRET = <YOUR_CONSUMER_SECRET>
Splitwise.access_token = access_token

here access_token is access token obtained after authenticating app by user, more about it below.

Usage

All data returned will be in string format. Do JSON.parse(response) to convert it to json.

API Methods

get_currencies

Splitwise::Request.new.fetch("get_currencies")

get_categories

Splitwise::Request.new.fetch("get_categories")

Users

get_current_user
```
Splitwise::Users.get_current_user
```

get_user

Splitwise::Users.user_info(id) 
# 'id' of user who shares a group or a friendship with current user

update_user_info
```
Splitwise::Users.update_user(id, data)
# id - current_user_id or user_id of invited user who has not logged in yet
# data - Hash of Parameters
```
- Parameters:
  - first_name, last_name, email, password, locale, date_format, default_currency, default_group_id, notification_settings
  - Eg:
```
id = 123
data = { 'first_name' => 'first', 'last_name' => 'last', ... }
Splitwise::Users.update_user(id, data)
```
- Note:
  1. A user can update anything about himself.
  2. For other users (for users who is acquainted with but haven’t logged in yet) only [first_name, last_name, email] can be updated.

Groups
- list_groups : list all groups of current user
```
Splitwise::Groups.list_groups
```
- group_info : get group info of group_id
```
Splitwise::Groups.group_info(group_id)
```
- create : create group
```
Splitwise::Groups.create(data)
# data - Hash of Parameters
```
  - Parameters:
    - name (mandatory), group_type (optional), country_code (optional),
    - a list of group members (optional)
      1. users__ARRAYINDEX__PARAMNAME,
      2. params are either: (first_name, last_name, email) or (user_id)
- delete: delete group
```
Splitwise::Groups.delete(group_id)
# Returns: {:success ⇒ true/false}
```
- add_user_to_group: add a user to existing group
```
Splitwise::Groups.add_user(data)
# data - Hash of Parameters
# Return: {:success ⇒ true/false, :errors ⇒ [any errors]}
```
  - Parameters:
    - group_id and user_id, or
    - group_id, first_name, last_name, email (should send an invite if successful and account does not already exist)
- remove_user_from_group: remove user from an existing group
```
Splitwise::Groups.remove_user(data)
# data - Hash of Parameters (group_id, user_id)
# Return: {:success ⇒ true/false, :errors ⇒ [any errors]}
```

Expenses

list_all_expenses : get all your expenses

Splitwise::Expenses.list_all_expenses

expense_info: get expense info of expense_id

Splitwise::Expenses.expense_info(expense_id)

create_expense: create a new expense
```
Splitwise::Expenses.create(data)
# data - Hash of Parameters
```
- Parameters:
  - payment, cost, description
  - refer this for more info

update_expense: update an expense

Splitwise::Expenses.update_expense(expense_id, data)
# data - Hash of Parameters

delete_expense: delete given expense
```
Splitwise::Expenses.delete(expense_id)
```

Friends

list_friends: list all friends of user
```
Splitwise::Friends.list_friends
```

friend_info: get friend infformation

Splitwise::Friends.friend_info(friend_id)

create_friend: create a new friend

Splitwise::Friends.create(data)
# data - Hash of Parameters

delete_friend: delete a friend
```
Splitwise::Friends.unfriend(friend_id)
```

Usage guideline to integrate with Ruby on Rails / Sinatra app

Splitwise uses OAuth 1.0 for authenticating user which means it needs one time authorization from user. Read more about it here.

I have made a sample Sinatra app as a demo of API usage. Refer example.
I am using omniauth-splitwise for authentication Splitwise API.

How to run it:

cd example
bundle
Enter SPLITWISE_KEY and SPLITWISE_SECRET in the example_splitwise_api.rb
ruby example_splitwise_api.rb
Goto localhost:4567, you will be directed to authorization page.
Once authorized, you can use the api.

Contributing

Fork it ( https://github.com/divyum/splitwise-ruby/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

To-do's

detailed readme (esp expenses, groups, friends ) - [ ] examples for each type - [ ] return values for each
more error handling: - [ ] timeout - [ ] mandatory parameter checks
test cases
make create friends endpoint
make more endpoints for fetching data

divyum / splitwise-ruby