= plaid_kilt Accessing the Plaid API using Ruby. ===Notes Minimal undergarments. Sporran not included. Tests coming. === Version Head is 0.6.0 === Install 'gem install plaid-kilt' == Usage === Grab a client Clients take 4 parameters: username, email, password, and the institution. client = Plaid.client 'user_name','user@name.com','pass_word', 'amex' === Connect Plaid uses the "connect" Plaid API call to initiate the user flow and to access information. info = client.connect <= gets information from Plaid === Responses This gem returns values in response objects or error objects. This is not very ruby-esque, but it helps to make sense of the Plaid environment as well as making HTTPParty consumable for a business. Response objects are initialized when the client gets a valid response from plaid. In the case of non-MFA banks r = client.connect * r.raw_response <= the raw HTTPParty-wrapped response from Plaid * r.accounts <= Array of accounts associated with this institution for this user * r.transactions <= Array of transactions associated with the accounts * r.is_mfa? <= false for this request * r.message <= "Successful retrieved information from bank" * r.http_code <= 200 in this case Accounts and Transactions are objects that follow the JSON from Plaid. Thus you can expect to see r.transactions[66].category_id <= "52544965f71e87d007000119" r.transactions[66].name <= "Online Payment Processed" r.accounts[2].institution_type <= "fake_institution" r.accounts[2].balance["current"] <= 8.98 More explicitly r.accounts[2].inspect "#3721, \"current\"=>8.98}, @meta={\"limit\"=>3500, \"name\"=>\"Plaid Credit Card\", \"number\"=>\"93004\"}, @institution_type=\"fake_institution\">" === Errors Errors use the gem's PlaidError object client = Plaid.client 'user_name','user@name.com','pass_word_WRONG', 'amex' r = client.connect * r.http_code <= 402 * r.plaid_code <= Plaid's internal error code (https://plaid.com/expand#Response_Code_Detail) * r.error_message <= "Error" * r.resolution <= "The username or password provided were not correct." * r.raw_response <= the raw HTTPParty response More explicitly r = client.connect "#1200, \"message\"=>\"invalid credentials\", \"resolve\"=>\"The username or password provided were not correct.\"}, @response=#, @headers={\"content-type\"=>[\"application/json; charset=utf-8\"], \"date\"=>[\"Sat, 15 Mar 2014 17:31:46 GMT\"], \"x-powered-by\"=>[\"Express\"], \"content-length\"=>[\"109\"], \"connection\"=>[\"Close\"]}>>" === MFA MFA requires some management of user flow, which is why this gem tries to make the returns / errors from API calls explicit. If it seems heavyweight to you, it is because the MFA process is a heavyweight process. Plaid does a better job managing it than some others (no names!!), but if you are going to use Plaid extensively, then you are going to have to cope with MFA. See the wiki for more information. https://github.com/jkoisch/plaid/wiki/MFA These two diagrams go through user set up and user flow with MFA, respectively. https://github.com/jkoisch/plaid/blob/master/design/plaid_user_set_up.png https://github.com/jkoisch/plaid/blob/master/design/plaid_flows_connect.png === Raw response You can, if you would rather, ignore the PlaidResponse objects. #config/initializers/plaid.rb config.save_full_response = true #when you get your responses x = client.connect x.raw_response <= the raw http-party wrapped response to the request. Have fun. === Thin Client The Plaid-kilt gem also has a thin_client for some secure followup operations: thin_client = Plaid.thin_client "me@example.com", "chase", "access_token_test" This client can be used only after you have retrieved an access_token, but supports followup methods allowed for by Plaid: thin_client.followup <= GET operation to get account and transaction information thin_client.get_balance <= GET operation to receive account balances thin_client.get_entity("unique_plaid_entity") <= Entity context information == Scaffolding Some Plaid methods are accessible via a GET with no additional credentials: Plaid.scaffold.institutions <= all of the institutions that Plaid supports Plaid.scaffold.category(id) <= detailed information about the plaid category == Configuration You need to configure access through your own initializers using the values you receive from Plaid. #config/initializers/plaid.rb require 'plaid' Plaid.configure do |config| config.client_id = 'JUNK' config.secret = 'JUNK' config.endpoint = 'https://tartan.plaid.com/' config.certpath = 'ca-bundle.crt' config.headers = {'Content-Type'=>'application/x-www-form-urlencoded'} config.webhook_address = 'https://You.will.need.a/plaid_webhook/' config.save_full_response = false end == Additional Client Methods The Plaid Client is not-quite-skinny so that it can handle various parts of the returns from the Plaid API. This is to support alternate user flows (MFA, etc) or user handling in implementation. The Plaid Client supports the following attr_readers client.settings client.username client.password client.institution client.endpoint client.secret client.access_token client.mfa_type client.mfa_message client.mfa_return <= an array of the MFA returns from Plaid == Contributing to the plaid gem * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet. * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it. * Fork the project. * Start a feature/bugfix branch. * Commit and push until you are happy with your contribution. * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally. * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it. == Copyright Copyright (c) 2014 John Koisch. See LICENSE.txt for further details.