plaid 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1b5ab6d107eb42bdc74441ce2e47c068b43b66c0
-  data.tar.gz: fd69213bbb1001c8b283edb6742da94647ae9a53
+  metadata.gz: 1f1feea43dc48ce5bad450da5642293cf9a26637
+  data.tar.gz: 8e355726ca0db3969979088c505889b4f29d147f
 SHA512:
-  metadata.gz: 8fe17b5426f28e1657f38541b2434c7462f60205d9073b778761a516587e8e809ef582720e5ccad3c08e5cb3f7f2f67a5aad08a0f402c99da0536d8d3129c2b8
-  data.tar.gz: 46bc2fe7a2f1da6895e15b4a9c265613f8da13c8966b75c9e069bbe55185a95dbfed3a15f8445a7929aab6d9e5867afe0aeef11ee42a3d1fd9ddd692499c3e09
+  metadata.gz: 6bcaccd07ed115c5629bd65ba34529aa3cb6264afc575bc9a8adf1859f9e217ac2544c74770283ccd8714edc26e3a167c957422b9d264486a99e3f80b986e2b5
+  data.tar.gz: 7a895e92f13d9ea624f0990834ecedab18613ffb946799d03c7c1972d3fb44ad948ec286d90d0fecb6cdf14627d3414fec1147039838d5c921f6c2168dc644b5

data/.env.sample

@@ -0,0 +1,3 @@
+PLAID_RUBY_CLIENT_ID=the_real_client_id
+PLAID_RUBY_SECRET=the_real_secret
+PLAID_RUBY_PUBLIC_KEY=the_real_public_key

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 4.1.0 04-Jan-2018
+
+* Make `/item/remove` the primary Item removal endpoint
+* Add #options parameter to `/institutions/get`
+* Handle network errors with `PlaidServerError`
+
+# 4.0.0 09-Mar-2017
+
+* Refactored the entire library to support [Plaid's new API](https://blog.plaid.com/improving-our-api/). Use the [transition guide](https://plaid.com/docs/link/transition-guide) to update your integration. Version 3.x.x of this gem is mirrored at [plaid-legacy](https://github.com/plaid/plaid-ruby-legacy).
+
+# 3.0.0. 17-Jan-2017
+
+* Add `/institutions/all` and `/institutions/all/search` endpoints, see [UPGRADING.md](UPGRADING.md#upgrading-from-2xx-to-300)
+
+# 2.2.0. 03-Nov-2016
+
+* Add `Transaction#reference_number` (@ericbirdsall).
+* Fix webhook codes and add risk and income webhooks.
+
+# 2.1.0. 19-Oct-2016
+
+* Documentation fixes (@ishmael).
+* Fix `Transaction#to_s` behavior (@michel-tricot).
+* PATCH `/:product/step` flow.
+* Use the same client in `User#upgrade` (@betesh).
+* Webhook object (@zshannon).
+* `processor_token` access in `User.exchange_token` (@gylaz).
+* Raise `ServerError` in case server returned an empty response body.
+
+# 2.0.0. 24-May-2016
+
+* Use `~> 1.0` spec for multi_json dependency.
+* Support `stripe_bank_account_token` in `User.exchange_token`.
+
+# 2.0.0.alpha.2. 14-May-2016
+
+* Use `:production` instead of `:api` to signify production environment
+  in `Plaid::Client#env=`.
+* `User#mfa_step` allows to specify options now (thanks @gcweeks).
+* Implemented `User#update_webhook`.
+
+# 2.0.0.alpha. 06-May-2016
+
+* Rewrite everything.

data/CONTRIBUTING.md

@@ -4,6 +4,46 @@ After checking out the repo, run `bin/setup` to install dependencies. You can al
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Running tests
+
+The gem test suite can be run in two modes. By default, it runs against the
+live sandbox environment, creating items on the fly and calling various API
+endpoints for them. For this to work you'll need real `client_id`, `secret`,
+and `public_key` from your Plaid dashboard. Create a file named `.env`
+based on `.env.sample` which is provided:
+
+```text
+PLAID_RUBY_CLIENT_ID=the_real_client_id
+PLAID_RUBY_SECRET=the_real_secret
+PLAID_RUBY_PUBLIC_KEY=the_real_public_key
+```
+This file will be loaded during the tests.
+
+Another mode employs pre-recorded API responses using the
+[vcr](https://github.com/vcr/vcr) gem. It runs much faster. Just use
+`rake test_stubbed` and you're good to go even without `.env`!
+
+## Updating VCR "cassettes"
+
+In case you're adding new API endpoints or when there were any substantial
+changes in API you'll need to update the pre-recorded responses. Here's how:
+
+1. Make sure that `STUB_API=1 rake test` fails. It will fail saying something
+   like "... An HTTP request has been made that VCR does not know how to
+   handle".
+2. Run `RECORD_MODE=all STUB_API=1 rake test`. This will run the whole suite
+   and re-record everything. If you only need to update data for one test class,
+   use this:
+
+   ```
+   RECORD_MODE=all STUB_API=1 ruby -w -I"lib:test" -rminitest/pride test/test_which_fails.rb
+   ```
+3. Run `rake vcr_hide_credentials`. This step is essential, because
+   newly recorded files will contain your real `client_id` and friends. This
+   Rake task will go over all recorded files and replace real values with
+   stubbed ones used by `STUB_API=1 rake test`.
+4. Run `STUB_API=1 rake test` and verify that everything works.
+
 ## Contributing
 
 1.  Make one or more atomic commits, and ensure that each commit has a
@@ -14,8 +54,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 3.  Make sure that you've documented all public methods using [TomDoc](http://tomdoc.org/).
 
-4.  Run `rake test`, and address any errors. Preferably, fix commits
-    in place using `git rebase` or `git commit --amend` to make the
+4.  Run tests (in both modes, see above) and address any errors. Preferably,
+    fix commits in place using `git rebase` or `git commit --amend` to make the
     changes easier to review.
 
 5.  Open a pull request.

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 TODO: Write your name
+Copyright (c) 2017 Plaid Technologies, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/PUBLISHING.md

@@ -0,0 +1,14 @@
+# Publishing
+
+The module is published to [RubyGems][1] under the gem name [plaid][2].
+
+To publish:
+
+1. `rake test` (runs the test suite locally).
+2. Update, commit, and merge (with review) the `lib/plaid/version.rb` and `CHANGELOG.md` files. 
+5. `git pull` (makes sure your `HEAD` is up-to-date).
+6. `rake release` (builds the gem, creates a tag, pushes the gem to RubyGems and tag to GitHub).
+7. `rake update_github_docs` (generates RDoc files, updates `gh-pages` branch and pushes it to GitHub).
+
+[1]: https://rubygems.org/
+[2]: https://rubygems.org/gems/plaid

data/README.md

@@ -1,8 +1,8 @@
-# plaid-ruby [![Build Status](https://travis-ci.org/plaid/plaid-ruby.svg)](https://travis-ci.org/plaid/plaid-ruby) [![Gem Version](https://badge.fury.io/rb/plaid.svg)](http://badge.fury.io/rb/plaid)
+# plaid-ruby [![Circle CI](https://circleci.com/gh/plaid/plaid-ruby.svg?style=svg&circle-token=30ee002ac2021da5b5b5a701d45fe2888af124a5)](https://circleci.com/gh/plaid/plaid-ruby) [![Gem Version](https://badge.fury.io/rb/plaid.svg)](http://badge.fury.io/rb/plaid)
 
 The official Ruby bindings for the [Plaid API](https://plaid.com/docs).
 
-This module was recently released as version `4.0.x` for Plaid's updated API. Use the gem `plaid-legacy` for version `3.0.x`.
+**Note:** This module was recently refactored and released as version `4.0.x` to support [Plaid's updated API][1]. The previous module version, `3.0.x`, and API legacy documentation, is still available via RubyGems and mirrored as [`plaid-legacy`][2].
 
 ## Installation
 
@@ -26,7 +26,7 @@ The gem supports Ruby 2.1+ only.
 
 This gem wraps the Plaid API, which is fully described in the [documentation](https://plaid.com/docs/api).
 
-The RubyDoc for the gem is available [here](LINKPLACEHOLDER).
+The RubyDoc for the gem is available [here](http://plaid.github.io/plaid-ruby/).
 
 ### Creating a Plaid client
 
@@ -43,87 +43,13 @@ $client = Plaid::Client.new(env: :sandbox,
 ```
 
 The `env` field is the environment which the client will be running in. Your choices for the `env` field include:
-- `:sandbox` allows you to do your initial integrations tests against preloaded data without being billed or making expensive API calls. More information about using the API sandbox can be found on the [API Sandbox documentation](https://plaid.com/docs/api/blob/master/SANDBOX.md).
+- `:sandbox` allows you to do your initial integrations tests against preloaded data without being billed or making expensive API calls. More information about using the API sandbox can be found on the [API Sandbox documentation](https://plaid.com/docs/api#sandbox).
 - `:development` allows you to test against both real and test accounts without being billed. More information about Plaid test accounts can be found in our [API documentation](https://plaid.com/docs/api/#sandbox).
 - `:production` is the production environment where you can launch your production ready application and be charged for your Plaid usage.
 
-### Creating a new item
-
-A new item can be created by providing a set of credentials, an institution code, and a list of products to create the item with.
-
-```ruby
-item = client.item.create(credentials: { username: 'user_good',
-                                         password: 'pass_good',
-                                         pin: '1234' },
-                          institution_id: 'ins_109509',
-                          initial_products: %i(auth identity transactions))
-```
-The first argument for `client.item.create` is always the credentials in the form of a hash. 
-```ruby
-credentials = { username: 'user_good',
-                password: 'pass_good',
-                pin: '1234' }
-```
-The `pin` field in the credentials hash is not required and does not need to be entered if your institution does not require it.
-
-A successful, non-MFA (multi-factor authentication) response (HTTP 200) to an item creation will come in the form of a hash where each of these attributes can be accessed by the corresponding string key:
-```ruby
-{ "access_token" => String,
-  "item" => { "available_products" => [String],
-              "billed_products"    => [String],
-              "error"              => Object,
-              "institution_id"     => String,
-              "item_id"            => String,
-              "webhook"            => nullable String },
-  "request_id" => String }
-```
-The response provides three primary pieces of information:
-- `access_token` is your token to access this item and the item's products in the future such as `auth` or `transactions`
-- `item` provides information about the item such as the `item_id` and `available_products`
-- `request_id` is the identifier for your actual request, this is often used to file tickets if necessary
-
-There are other responses you can receive from an item creation such as an MFA response and an error response (they're all in hash form).
-
-An MFA response (HTTP 210) looks like this:
-```ruby
-{ "access_token" => String,
-  "device"       => nullable String,
-  "device_list"  => nullable [Object],
-  "mfa_type"     => String Enum (device, device_list, questions, selections),
-  "questions"    => nullable [String],
-  "request_id"   => String,
-  "selections"   => nullable [Object] }
-```
-
-An example of how an MFA onboarding flow looks like can be seen below in the Examples section.
-
-If an error occurs during the creation, an error will be thrown. The class for the error has values that you can access by using the following keys.
-```ruby
-{ "error_type"      => String,
-  "error_code"      => String,
-  "error_message"   => String,
-  "display_message" => (nullable) String,
-  "request_id"      => String }
-```
-Additional information on the meaning or usage of each field can be found in our [API Error documentation](https://plaid.com/docs/api#errors).
-
-You can also add options such as `transactions.await_results` or `webhook` to your item creation, use keyed arguments:
-
-```ruby
-item = client.item.create(credentials: { username: 'user_good',
-                                         password: 'pass_good' },
-                          institution_id: 'ins_109509',
-                          initial_products: %i(auth identity transactions),
-                          transactions_await_results: true,
-                          webhook: 'https://plaid.com/webhook-test')
-```
-
-More information about item creation options can be found in our [API documentation](https://plaid.com/docs/api#post-itemcreate).
-
-
 ## Examples
 
-### Exchanging a Link public token for a Plaid access_token
+### Exchanging a Link public_token for a Plaid access_token
 
 If you have a [Link](https://github.com/plaid/link) `public token`, use this function to get an `access_token`: `client.item.public_token.exchange(public_token)`
 
@@ -134,75 +60,6 @@ response = client.item.public_token.exchange(public_token)
 access_token = response['access_token']
 ```
 
-### Handle MFA during item creation
-
-If MFA is requested by the financial institution, there will be additional steps required to finish the item creation flow:
-```ruby
-require 'plaid'
-
-def answer_mfa(client, access_token, data)
-  case data['mfa_type']
-  when 'questions'
-    answer_questions(client, access_token, data['questions'])
-  when 'device_list'
-    answer_device_list(client, access_token, data['device_list'])
-  when 'selections'
-    answer_selections(client, access_token, data['selections'])
-  when 'device'
-    answer_device(client, access_token, data['device'])
-  else
-    raise 'Unknown MFA type from Plaid'
-  end
-end
-
-def answer_questions(client, access_token, _questions)
-  # We have magically inferred the answer here, so we respond immediately.
-  # In the real world, we would present the questions to our user and
-  # submit their responses.
-  answers = ['answer_0_0']
-  client.item.mfa(access_token, 'questions', answers)
-end
-
-def answer_device_list(client, access_token, device_list)
-  # We have picked the first device here.
-  # In the real world, we would ask our user which device the passcode
-  # should be sent to.
-  device = device_list[0]['device_id']
-  client.item.mfa(access_token, 'device_list', [device])
-end
-
-def answer_device(client, access_token, _device)
-  # Another magically inferred answer.
-  # In the real world, we would ask our user for the passcode they received.
-  client.item.mfa(access_token, 'device', ['1234'])
-end
-
-def answer_selections(client, access_token, _selections)
-  # We have magically inferred the answer here, so we respond immediately.
-  # In the real world, we would present the selection question and choices
-  # to our user and submit their responses.
-  answers = %w(tomato ketchup)
-  client.item.mfa(access_token, 'selections', answers)
-end
-
-begin
-  client = Plaid::Client.new(env: :sandbox,
-                             client_id: '***',
-                             secret: '***',
-                             public_key: '***')
-
-  response = client.item.create(credentials: { username: 'user_good',
-                                               password: 'mfa_device' },
-                                institution_id: 'ins_109508',
-                                initial_products: %i(transactions auth))
-
-  access_token = response['access_token']
-  response = answer_mfa(client, access_token, response) while response.key?('mfa_type')
-rescue Plaid::PlaidError
-  raise 'Error in main flow.'
-end
-```
-
 ### Deleting an item
 
 ```ruby
@@ -220,8 +77,8 @@ response = client.item.create(credentials: { username: 'user_good',
 
 access_token = response['access_token']
 
-# Provide the access_token for the Item you want to delete
-client.item.delete(access_token)
+# Provide the access_token for the Item you want to remove
+client.item.remove(access_token)
 ```
 
 ### Get paginated transactions
@@ -245,7 +102,7 @@ transactions = transaction_response['transactions']
 
 # the transactions in the response are paginated, so make multiple calls while
 # increasing the offset to retrieve all transactions
-while transactions.length < response['total_transactions']
+while transactions.length < transaction_response['total_transactions']
   transaction_response = client.transactions.get(access_token,
                                                  '2016-07-12',
                                                  '2017-01-09',
@@ -255,7 +112,7 @@ end
 
 ```
 
-### Obtaining user-related data
+### Obtaining Item-related data
 
 If you have an `access_token`, you can use following code to retreive data:
 ```ruby
@@ -353,3 +210,6 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/plaid/
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[1]: https://blog.plaid.com/improving-our-api/
+[2]: https://github.com/plaid/plaid-ruby-legacy

data/Rakefile

@@ -2,6 +2,7 @@ require 'bundler/gem_tasks'
 require 'sdoc'
 require 'rdoc/task'
 require 'rake/testtask'
+require 'dotenv/load'
 require 'fileutils'
 
 RDoc::Task.new do |rdoc|
@@ -9,7 +10,7 @@ RDoc::Task.new do |rdoc|
   rdoc.generator = 'sdoc'
   rdoc.main = 'README.md'
 
-  rdoc.rdoc_files.include('README.md', 'LICENSE', 'UPGRADING.md', 'lib/**/*.rb')
+  rdoc.rdoc_files.include('README.md', 'LICENSE.txt', 'lib/**/*.rb')
   rdoc.markup = 'tomdoc'
 end
 
@@ -50,4 +51,35 @@ task update_github_docs: %i(rdoc update_gh_pages) do
   sh 'git push origin gh-pages'
 end
 
-task default: :test
+desc 'Hide real credentials in VCR cassettes'
+task :vcr_hide_credentials do
+
+  all_creds = %w(PLAID_RUBY_CLIENT_ID PLAID_RUBY_SECRET PLAID_RUBY_PUBLIC_KEY)
+
+  all_creds.each do |cred|
+    fail "#{cred} is not set" unless ENV[cred]
+  end
+
+  Dir['test/vcr_cassettes/*'].each do |fn|
+    data = File.read(fn)
+    data_0 = data.clone
+
+    all_creds.each do |cred|
+      data.gsub! ENV[cred], cred
+    end
+
+    if data != data_0
+      File.open(fn, 'w') { |f| f.write data }
+
+      puts ">> Updated #{fn}"
+    end
+  end
+
+end
+
+task :test_stubbed do
+  ENV['STUB_API'] ||= '1'
+  Rake::Task['test'].invoke
+end
+
+task default: :test_stubbed

data/UPGRADING.md

@@ -0,0 +1,64 @@
+## Upgrading from 3.x.x to 4.0.0
+
+Version 4.0.0 supports [Plaid's new API](https://blog.plaid.com/improving-our-api/).  Use the [transition guide](https://plaid.com/docs/link/transition-guide) to update your integration.
+
+## Upgrading from 2.x.x to 3.0.0
+
+Version 3.0.0 makes `Plaid::Institution` use new `institutions/all` endpoint
+of Plaid API which unites "native" and "long tail" institutions.
+`Plaid::LongTailInstitution` class is removed, its functionality is
+concentrated in `Plaid::Institution`.
+
+Use `Plaid::Institution.all` instead of `Plaid::LongTailInstitution.all` (the
+semantics is the same, with added products param).
+
+Use `Plaid::Institution.search` instead of `Plaid::LongTailInstitution.search`.
+
+Use `Plaid::Institution.search_by_id` instead of `Plaid::LongTailInstitution.get`.
+
+
+## Upgrading from 1.x to 2.0.0
+
+Make sure you use Ruby 2.0 or higher.
+
+Update the `Plaid.config` block:
+
+```ruby
+Plaid.config do |p|
+  p.client_id = '<<< Plaid provided client ID >>>'  # WAS: customer_id
+  p.secret = '<<< Plaid provided secret key >>>'    # No change
+  p.env = :tartan  # or :api for production         # WAS: environment_location
+end
+```
+
+Use `Plaid::User.create` instead of `Plaid.add_user` (**NOTE**: parameter order has changed!)
+
+Use `Plaid::User.load` instead of `Plaid.set_user` (**NOTE**: parameter order has changed!)
+
+Use `Plaid::User.exchange_token` instead of `Plaid.exchange_token` (**NOTE**: parameter list has changed!)
+
+Use `Plaid::User.create` or (`.load`) and `Plaid::User#transactions` instead of `Plaid.transactions`.
+
+Use `Plaid::Institution.all` and `Plaid::Institution.get` instead of `Plaid.institution`.
+
+Use `Plaid::Category.all` and `Plaid::Category.get` instead of `Plaid.category`.
+
+`Plaid::Account#institution_type` was renamed to `Plaid::Account#institution`.
+
+`Plaid::Transaction#account` was renamed to `Plaid::Transaction#account_id`.
+
+`Plaid::Transaction#date` is a Date, not a String object now.
+
+`Plaid::Transaction#cat` was removed. Use `Plaid::Transaction#category_hierarchy` and `Plaid::Transaction#category_id` directly.
+
+`Plaid::Transaction#category` was renamed to `Plaid::Transaction#category_hierarchy`.
+
+`Plaid::Transaction#pending_transaction` was renamed to `Plaid::Transaction#pending_transaction_id`.
+
+Use `Plaid::User#mfa_step` instead of `Plaid::User#select_mfa_method` and `Plaid::User#mfa_authentication`.
+
+`Plaid::User#permit?` was removed. You don't need this.
+
+`Plaid::User.delete_user` was renamed to `Plaid::User.delete`.
+
+**NOTE** that Symbols are now consistently used instead of Strings as product names, keys in hashes, etc. Look at the docs, they have all the examples.

data/circle.yml

@@ -1,3 +1,9 @@
 machine:
   ruby:
-    version: 2.2.2
+    version: 2.3.4
+
+test:
+  pre:
+    - bundle exec rake test:
+        environment:
+          STUB_API: yes

data/lib/plaid.rb

@@ -1,5 +1,8 @@
+require 'faraday'
+require 'faraday_middleware'
+
+require_relative 'plaid/middleware'
 require_relative 'plaid/client'
-require_relative 'plaid/connect'
 require_relative 'plaid/errors'
 require_relative 'plaid/version'
 require_relative 'plaid/products/accounts'
@@ -13,7 +16,3 @@ require_relative 'plaid/products/item'
 require_relative 'plaid/products/processor'
 require_relative 'plaid/products/sandbox'
 require_relative 'plaid/products/transactions'
-
-# Public: The Plaid namespace.
-module Plaid
-end

data/lib/plaid/client.rb

@@ -1,36 +1,29 @@
 # Public: The Plaid namespace.
 module Plaid
-  # Internal: Map environment to Plaid environment URL
-  #
-  # env - The type of the environment in symbol form
-  #
-  # Returns a string representing an environment URL
-  def self.url_from_env(env)
-    case env
-    when :sandbox
-      'https://sandbox.plaid.com/'
-    when :development
-      'https://development.plaid.com/'
-    when :production
-      'https://production.plaid.com/'
-    end
-  end
-
-  # Public: A class encapsulating client_id, secret, public key, and Plaid environment.
+  # Public: The main interface to Plaid API.
   class Client
-    # Internal: Set Plaid environment to use
-    #
-    # Handles converting an env symbol into an environment URL
+    # Public: All possible environments for the client to use.
+    ENVIRONMENTS = %i(sandbox development production)
+
+    # Public: The current environment in use (one of ENVIRONMENTS).
+    attr_reader :env
+
+    # Public: Construct a Client instance
     #
-    # env - The Symbol (:sandbox, :development, :production)
+    # Optionally takes a block to allow overriding the default Faraday connection options.
     #
-    # Returns a string representing the environment URL or raises an error
-    def env_map(env)
-      (@env = Plaid.url_from_env(env)) || raise(ArgumentError, 'Invalid value for ' \
-                                                                'Plaid::Client.env ' \
-                                                                "(#{env.inspect}): " \
-                                                                'must be :sandbox, '\
-                                                                ':development, or :production ')
+    # env        - The Symbol (:sandbox, :development, :production)
+    # client_id  - The String Plaid account client ID to authenticate requests
+    # secret     - The String Plaid account secret to authenticate requests
+    # public_key - The String Plaid account public key to authenticate requests
+    def initialize(env:, client_id:, secret:, public_key:, &block)
+      @env        = env.to_sym
+      @api_host   = api_host
+      @client_id  = client_id
+      @secret     = secret
+      @public_key = public_key
+
+      create_connection(&block)
     end
 
     # Public: Memoized class instance to make requests from Plaid::Account
@@ -88,19 +81,6 @@ module Plaid
       @transactions ||= Plaid::Transactions.new(self)
     end
 
-    # Public: Construct a Client instance
-    #
-    # env        - The Symbol (:sandbox, :development, :production)
-    # client_id  - The String Plaid account client ID to authenticate requests
-    # secret     - The String Plaid account secret to authenticate requests
-    # public_key - The String Plaid account public key to authenticate requests
-    def initialize(env:, client_id:, secret:, public_key:)
-      @env        = env_map(env)
-      @client_id  = client_id
-      @secret     = secret
-      @public_key = public_key
-    end
-
     # Public: Make a post request
     #
     # path    - Path or URL to make the request to
@@ -108,7 +88,7 @@ module Plaid
     #
     # Returns the resulting parsed JSON of the request
     def post(path, payload)
-      Plaid::Connect.post(File.join(@env, path), payload)
+      @connection.post(path, payload).body
     end
 
     # Public: Make a post request with appended authentication fields
@@ -118,9 +98,9 @@ module Plaid
     #
     # Returns the resulting parsed JSON of the request
     def post_with_auth(path, payload)
-      auth = { client_id: @client_id,
-               secret: @secret }
-      Plaid::Connect.post(File.join(@env, path), payload.merge(auth))
+      @connection.post(
+        path,
+        payload.merge(client_id: @client_id, secret: @secret)).body
     end
 
     # Public: Make a post request with appended public key field.
@@ -130,8 +110,46 @@ module Plaid
     #
     # Returns the resulting parsed JSON of the request.
     def post_with_public_key(path, payload)
-      public_key = { public_key: @public_key }
-      Plaid::Connect.post(File.join(@env, path), payload.merge(public_key))
+      @connection.post(path, payload.merge(public_key: @public_key)).body
+    end
+
+    protected
+
+    # Internal: Gets the API hostname for given environment.
+    #
+    # env - The Symbol (:sandbox, :development, :production)
+    #
+    # Returns a String representing the environment URL.
+    # Raises ArgumentError if environment is unknown.
+    def api_host
+      unless ENVIRONMENTS.include?(@env)
+        raise ArgumentError,
+          "Invalid value for env (#{@env.inspect}): must be one of " +
+          ENVIRONMENTS.map(&:inspect) * ', '
+      end
+
+      "https://#{@env}.plaid.com"
+    end
+
+    # Internal: Initializes a new Plaid connection object via Faraday.
+    #
+    # Optionally takes a block to allow overriding the defaults.
+    def create_connection(&block)
+      @connection = Faraday.new(url: @api_host) do |builder|
+        block_given? ? yield(builder) : build_default_connection(builder)
+      end
+    end
+
+    # Internal: Set Plaid defaults on the Faraday connection.
+    #
+    # builder - The Faraday builder object.
+    def build_default_connection(builder)
+      builder.options[:timeout] = Plaid::Middleware::NETWORK_TIMEOUT
+      builder.headers = Plaid::Middleware::NETWORK_HEADERS
+      builder.request :json
+      builder.use Plaid::Middleware
+      builder.response :json, content_type: /\bjson$/
+      builder.adapter Faraday.default_adapter
     end
   end
 end

data/lib/plaid/errors.rb

@@ -1,6 +1,12 @@
 module Plaid
-  # Internal: Base class for Plaid errors
-  class PlaidError < StandardError
+  # Public: Base class for Plaid SDK errors
+  class PlaidError < StandardError; end
+
+  # Public: returned on Plaid server or network issues
+  class PlaidServerError < PlaidError; end
+
+  # Public: Base class for any error returned by the API
+  class PlaidAPIError < PlaidError
     attr_reader :error_type, :error_code, :error_message, :display_message, :request_id
 
     # Internal: Initialize an error with proper attributes
@@ -27,28 +33,28 @@ module Plaid
   end
 
   # Public: returned when the request is malformed and cannot be processed.
-  class InvalidRequestError    < PlaidError; end
+  class InvalidRequestError    < PlaidAPIError; end
 
   # Public: returned when all fields are provided and are in the correct format,
   #         but the values provided are incorrect in some way.
-  class InvalidInputError      < PlaidError; end
+  class InvalidInputError      < PlaidAPIError; end
 
   # Public: returned when the request is valid but has exceeded established rate limits.
-  class RateLimitExceededError < PlaidError; end
+  class RateLimitExceededError < PlaidAPIError; end
 
   # Public: returned during planned maintenance windows and
   #         in response to API internal server errors.
-  class APIError               < PlaidError; end
+  class APIError               < PlaidAPIError; end
 
   # Public: indicates that information provided for the item (such as credentials or MFA)
   #         may be invalid or that the item is not supported on Plaid's platform.
-  class ItemError              < PlaidError; end
+  class ItemError              < PlaidAPIError; end
 
   # Internal: A module that provides utilities for errors.
   module Error
-    # Internal: Map error_type to PlaidError
+    # Internal: Map error_type to PlaidAPIError
     #
-    # Maps an error_type from an error HTTP response to an actual PlaidError class instance
+    # Maps an error_type from an error HTTP response to an actual PlaidAPIError class instance
     #
     # error_type - The type of the error as indicated by the error response body
     #
@@ -66,7 +72,7 @@ module Plaid
       when 'ITEM_ERROR'
         Plaid::ItemError
       else
-        Plaid::PlaidError
+        Plaid::PlaidAPIError
       end
     end
   end

data/lib/plaid/middleware.rb

@@ -0,0 +1,25 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'version'
+
+module Plaid
+  class Middleware < ::Faraday::Response::Middleware
+    # Internal: Headers used for correct request and SDK tracking.
+    NETWORK_HEADERS = { 'User-Agent'   => "Plaid Ruby v#{Plaid::VERSION}",
+                        'Content-Type' => 'application/json' }.freeze
+
+    # Internal: Default read timeout for HTTP calls in seconds.
+    NETWORK_TIMEOUT = 600
+
+    def on_complete(env)
+      return unless Faraday::Response::RaiseError::ClientErrorStatuses.include?(env[:status])
+      raise Plaid::Error.error_from_type(env.body['error_type']).new(env.body['error_type'],
+                                                                     env.body['error_code'],
+                                                                     env.body['error_message'],
+                                                                     env.body['display_message'],
+                                                                     env.body['request_id'])
+    end
+  end
+end

data/lib/plaid/products/credit_details.rb

@@ -11,10 +11,17 @@ module Plaid
     # and access_token's item
     #
     # access_token - access_token who's item to fetch credit_details for
+    # account_ids  - Specific account ids to fetch credit_details for (optional)
     #
     # Returns a parsed JSON of credit_details information
-    def get(access_token)
-      payload = { access_token: access_token }
+    def get(access_token, account_ids: nil)
+      options_payload = {}
+      options_payload[:account_ids] = account_ids unless account_ids.nil?
+      payload = {
+        access_token: access_token,
+        options: options_payload
+      }
+
       @client.post_with_auth('credit_details/get', payload)
     end
   end

data/lib/plaid/products/institutions.rb

@@ -10,13 +10,16 @@ module Plaid
     # Does a POST /institutions/get call pulls a list of supported Plaid institutions
     # with the information for each institution
     #
-    # count  - Amount of institutions to pull
-    # offset - Offset to start pulling institutions
+    # count   - Amount of institutions to pull
+    # offset  - Offset to start pulling institutions
+    # options - Options for filtering institutions
     #
     # Returns a parsed JSON of listed institution information
-    def get(count:, offset:)
+    def get(count:, offset:, options: nil)
       payload = { count: count,
                   offset: offset }
+      payload[:options] = options unless options.nil?
+
       @client.post_with_auth('institutions/get', payload)
     end
 

data/lib/plaid/products/item.rb

@@ -226,5 +226,17 @@ module Plaid
       payload = { access_token: access_token }
       @client.post_with_auth('item/delete', payload)
     end
+
+    # Public: Removes an item
+    #
+    # Does a POST /item/remove call which is used to remove an item
+    #
+    # access_token - access_token who's item to remove
+    #
+    # Returns a parsed JSON of remove result
+    def remove(access_token)
+      payload = { access_token: access_token }
+      @client.post_with_auth('item/remove', payload)
+    end
   end
 end

data/lib/plaid/products/transactions.rb

@@ -57,18 +57,5 @@ module Plaid
                   options: options_payload }
       @client.post_with_auth('transactions/get', payload)
     end
-
-    # Public: Deactivate transactions for given access_token.
-    #
-    # Does a POST /transactions/deactivate call which deactivates the transaction product
-    # for a given access_token
-    #
-    # access_token - access_token to deactivate transactions for
-    #
-    # Returns a parsed JSON containing a message describing deactivation success.
-    def deactivate(access_token)
-      payload = { access_token: access_token }
-      @client.post_with_auth('transactions/deactivate', payload)
-    end
   end
 end

data/lib/plaid/version.rb

@@ -1,3 +1,3 @@
 module Plaid
-  VERSION = '4.0.0'.freeze
+  VERSION = '4.1.0'.freeze
 end

data/plaid.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
   if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   else
     raise 'RubyGems 2.0 or newer is required to protect against ' \
       'public gem pushes.'
@@ -32,10 +32,16 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.0.0'
+  spec.required_ruby_version = '>= 2.1.0'
+
+  spec.add_dependency 'faraday'
+  spec.add_dependency 'faraday_middleware'
 
   spec.add_development_dependency 'bundler', '~> 1.7'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'dotenv'
+  spec.add_development_dependency 'rake', '>= 10.0'
   spec.add_development_dependency 'sdoc', '~> 0.4.1'
-  spec.add_development_dependency 'minitest', '~> 5.8'
+  spec.add_development_dependency 'minitest', '~> 5.10'
+  spec.add_development_dependency 'minitest-around', '~> 0.4.0'
+  spec.add_development_dependency 'vcr', '~> 3.0.3'
 end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: plaid
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Edmund Loo
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-09 00:00:00.000000000 Z
+date: 2018-01-04 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -24,18 +52,32 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
@@ -58,14 +100,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.8'
+        version: '5.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.10'
+- !ruby/object:Gem::Dependency
+  name: minitest-around
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.8'
+        version: 3.0.3
 description: Ruby gem wrapper for the Plaid API. Read more at the homepage, the wiki,
   or in the Plaid documentation.
 email:
@@ -74,18 +144,22 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".env.sample"
+- CHANGELOG.md
 - CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
+- PUBLISHING.md
 - README.md
 - Rakefile
+- UPGRADING.md
 - bin/console
 - bin/setup
 - circle.yml
 - lib/plaid.rb
 - lib/plaid/client.rb
-- lib/plaid/connect.rb
 - lib/plaid/errors.rb
+- lib/plaid/middleware.rb
 - lib/plaid/products/accounts.rb
 - lib/plaid/products/auth.rb
 - lib/plaid/products/categories.rb
@@ -112,7 +186,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/plaid/connect.rb

@@ -1,75 +0,0 @@
-require 'json'
-require 'net/http'
-require 'uri'
-
-require_relative 'version'
-
-module Plaid
-  # Internal: A module encapsulating HTTP post requests
-  module Connect
-    # Internal: Headers used for correct request and SDK tracking.
-    NETWORK_HEADERS = { 'User-Agent'   => "Plaid Ruby v#{Plaid::VERSION}",
-                        'Content-Type' => 'application/json' }.freeze
-
-    # Internal: Default read timeout for HTTP calls in seconds.
-    NETWORK_TIMEOUT = 600
-
-    # Internal: Run POST request on path with payload.
-    #
-    # path    - The path to send the request to.
-    # payload - The hash with data.
-    #
-    # Returns the parsed JSON response body.
-    def self.post(path, payload)
-      uri = URI.parse(path)
-
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = true
-
-      http.read_timeout = Plaid::Connect::NETWORK_TIMEOUT
-
-      request = Net::HTTP::Post.new(uri.path, Plaid::Connect::NETWORK_HEADERS)
-      request.body = JSON.generate(payload)
-
-      Plaid::Connect.run http, request
-    end
-
-    # Internal: Run the request and process the response.
-    #
-    # http    - Object created by Net::HTTP.new
-    # request - Object created by Net::HTTP::Post.new (for POST)
-    #
-    # Returns the parsed JSON body or raises an appropriate PlaidError
-    def self.run(http, request)
-      response = http.request(request)
-
-      if response.body.nil? || response.body.empty?
-        raise Plaid::PlaidError.new(0, 'Server error', 'Try to connect later')
-      end
-
-      # All responses are expected to have a JSON body, so we always parse,
-      # not looking at the status code.
-      body = JSON.parse(response.body)
-
-      case response
-      when Net::HTTPSuccess
-        body
-      else
-        raise_error(body)
-      end
-    end
-
-    # Internal: Raise an error with the class depending on reponse body.
-    #
-    # body - A parsed response body with error.
-    #
-    # Raises a PlaidError
-    def self.raise_error(body)
-      raise Plaid::Error.error_from_type(body['error_type']).new(body['error_type'],
-                                                                 body['error_code'],
-                                                                 body['error_message'],
-                                                                 body['display_message'],
-                                                                 body['request_id'])
-    end
-  end
-end