plaid 4.1.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1f1feea43dc48ce5bad450da5642293cf9a26637
-  data.tar.gz: 8e355726ca0db3969979088c505889b4f29d147f
+  metadata.gz: faaa2fa4eb692b453290b83c1e25dd9881b74698
+  data.tar.gz: b35adebbfc727257f36168479cecc659a900e149
 SHA512:
-  metadata.gz: 6bcaccd07ed115c5629bd65ba34529aa3cb6264afc575bc9a8adf1859f9e217ac2544c74770283ccd8714edc26e3a167c957422b9d264486a99e3f80b986e2b5
-  data.tar.gz: 7a895e92f13d9ea624f0990834ecedab18613ffb946799d03c7c1972d3fb44ad948ec286d90d0fecb6cdf14627d3414fec1147039838d5c921f6c2168dc644b5
+  metadata.gz: 0ca822ff868b0525f132ba6c934ff223b7f3e33d49ec9e983defca591f1893ed652ee26023f3ff3acac627f2b9eabeae8a980ff3de2456f8251ad2841c8e05c6
+  data.tar.gz: 0e8023c4270011a064a383cd1c071b17940220bb59724782eb0acd268d213035ed8a8287c278590695191317581e56f446271aab31805632df16be76f91ca04b

data/.circleci/config.yml

@@ -0,0 +1,23 @@
+version: 2
+
+jobs:
+  build:
+    docker:
+      - image: circleci/ruby:2.3
+    steps:
+      - checkout
+      - run:
+          name: Bundle Install
+          command: bundle check || bundle install
+      - run:
+          name: Stubbed API test
+          command: bundle exec rake test
+          environment:
+            STUB_API: yes
+      - run:
+          name: Live API test
+          command: bundle exec rake test
+      - run:
+          name: Rubocop test
+          command: bundle exec rubocop
+

data/.rubocop.yml

@@ -0,0 +1,18 @@
+AllCops:
+  TargetRubyVersion: 2.1
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Layout/IndentHeredoc:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ParameterLists:
+  Max: 5
+  CountKeywordArgs: false

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 5.0.0 23-Mar-2018
+
+* Introduce true response objects instead of deep nested hashes. Any of the
+  three syntaxes can be used interchangeably for any API response:
+  `response['foo']['bar']`, `response[:foo][:bar]`, or `response.foo.bar`.
+* Add Dwolla and Apex products.
+
 # 4.1.0 04-Jan-2018
 
 * Make `/item/remove` the primary Item removal endpoint

data/CONTRIBUTING.md

@@ -36,7 +36,7 @@ changes in API you'll need to update the pre-recorded responses. Here's how:
    use this:
 
    ```
-   RECORD_MODE=all STUB_API=1 ruby -w -I"lib:test" -rminitest/pride test/test_which_fails.rb
+   RECORD_MODE=all STUB_API=1 ruby -w -I"lib:test" -rminitest/pride -rdotenv/load 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

data/Gemfile.lock

@@ -0,0 +1,58 @@
+PATH
+  remote: .
+  specs:
+    plaid (5.0.0)
+      faraday
+      faraday_middleware
+      hashie (>= 3.4.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.0)
+    dotenv (2.2.1)
+    faraday (0.14.0)
+      multipart-post (>= 1.2, < 3)
+    faraday_middleware (0.12.2)
+      faraday (>= 0.7.4, < 1.0)
+    hashie (3.5.7)
+    minitest (5.11.3)
+    minitest-around (0.4.1)
+      minitest (~> 5.0)
+    multipart-post (2.0.0)
+    parallel (1.12.1)
+    parser (2.5.0.4)
+      ast (~> 2.4.0)
+    powerpack (0.1.1)
+    rainbow (3.0.0)
+    rake (12.3.0)
+    rdoc (6.0.1)
+    rubocop (0.53.0)
+      parallel (~> 1.10)
+      parser (>= 2.5)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.9.0)
+    sdoc (1.0.0)
+      rdoc (>= 5.0)
+    unicode-display_width (1.3.0)
+    vcr (4.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  dotenv
+  minitest (~> 5.10)
+  minitest-around (~> 0.4.0)
+  plaid!
+  rake (>= 10.0)
+  rubocop (~> 0.53.0)
+  sdoc (~> 1.0.0)
+  vcr (~> 4.0.0)
+
+BUNDLED WITH
+   1.12.5

data/README.md

@@ -35,18 +35,31 @@ Create an instance of the client using the `client_id`, `secret`, and `public_ke
 ```ruby
 require 'plaid'
 
-$client = Plaid::Client.new(env: :sandbox,
-                            client_id: '***',
-                            secret: '***',
-                            public_key: '***')
-
+client = Plaid::Client.new(env: :sandbox,
+                           client_id: '***',
+                           secret: '***',
+                           public_key: '***')
 ```
 
 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#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.
 
+### Tuning Faraday
+
+The gem uses Faraday to wrap HTTPS connections, which allows you to tune certain params:
+
+```ruby
+client = Plaid::Client.new(env: :sandbox, client_id: '***', secret: '***', public_key: '***') do |builder|
+  Plaid::Client.build_default_connection(builder)
+
+  # Increase network timeout
+  builder.options[:timeout] = 60*20    # 20 minutes
+end
+```
+
 ## Examples
 
 ### Exchanging a Link public_token for a Plaid access_token
@@ -57,7 +70,7 @@ An example of the function's usage if you have a `public_token` in hand:
 
 ```ruby
 response = client.item.public_token.exchange(public_token)
-access_token = response['access_token']
+access_token = response.access_token
 ```
 
 ### Deleting an item
@@ -70,12 +83,8 @@ client = Plaid::Client.new(env: :sandbox,
                            secret: '***',
                            public_key: '***')
 
-response = client.item.create(credentials: { username: 'user_good',
-                                             password: 'pass_good' },
-                              institution_id: 'ins_109509',
-                              initial_products: %i(auth identity transactions))
-
-access_token = response['access_token']
+exchange_token_response = client.item.public_token.exchange('[Plaid Link public_token]')
+access_token = exchange_token_response.access_token
 
 # Provide the access_token for the Item you want to remove
 client.item.remove(access_token)
@@ -90,15 +99,11 @@ client = Plaid::Client.new(env: :sandbox,
                            secret: '***',
                            public_key: '***')
 
-item_response = client.item.create(credentials: { username: 'user_good',
-                                                  password: 'pass_good' },
-                                   institution_id: 'ins_109509',
-                                   initial_products: %i(auth identity transactions))
-
-access_token = item_response['access_token']
+exchange_token_response = client.item.public_token.exchange('[Plaid Link public_token]')
+access_token = exchange_token_response.access_token
 
 transaction_response = client.transactions.get(access_token, '2016-07-12', '2017-01-09')
-transactions = transaction_response['transactions']
+transactions = transaction_response.transactions
 
 # the transactions in the response are paginated, so make multiple calls while
 # increasing the offset to retrieve all transactions
@@ -107,7 +112,7 @@ while transactions.length < transaction_response['total_transactions']
                                                  '2016-07-12',
                                                  '2017-01-09',
                                                  offset: transactions.length)
-  transactions += transaction_response['transactions']
+  transactions += transaction_response.transactions
 end
 
 ```
@@ -123,16 +128,11 @@ client = Plaid::Client.new(env: :sandbox,
                            secret: '***',
                            public_key: '***')
 
-item_response = client.item.create(credentials: { username: 'user_good',
-                                                  password: 'pass_good' },
-                                   institution_id: 'ins_109509',
-                                   initial_products: %i(auth identity transactions))
-
-access_token = item_response['access_token']
+exchange_token_response = client.item.public_token.exchange('[Plaid Link public_token]')
+access_token = exchange_token_response.access_token
 
 auth_response = client.auth.get(access_token)
-auth = auth_response['auth']
-
+auth = auth_response.auth
 ```
 
 ### Create a Stripe bank_account_token
@@ -147,23 +147,22 @@ client = Plaid::Client.new(env: :sandbox,
                            public_key: '***')
 
 exchange_token_response = client.item.public_token.exchange('[Plaid Link public_token]')
-access_token = exchange_token_response['access_token']
+access_token = exchange_token_response.access_token
 
 stripe_response = client.processor.stripe.bank_account_token.create(access_token, '[Account ID]')
-bank_account_token = stripe_response['stripe_bank_account_token']
-
+bank_account_token = stripe_response.stripe_bank_account_token
 ```
 
 There are also a number of other methods you can use to retrieve data:
 
-* `client.accounts.get(access_code, ...)`: accounts
-* `client.accounts.balance.get(access_code, ...)`: real-time balances
-* `client.auth.get(access_code, ...)`: auth
-* `client.identity.get(access_code, ...)`: identity
-* `client.transactions.get(access_code, ...)`: transactions
-* `client.credit_details.get(access_code, ...)`: credit details
+* `client.accounts.get(access_token, ...)`: accounts
+* `client.accounts.balance.get(access_token, ...)`: real-time balances
+* `client.auth.get(access_token, ...)`: auth
+* `client.identity.get(access_token, ...)`: identity
+* `client.transactions.get(access_token, ...)`: transactions
+* `client.credit_details.get(access_token, ...)`: credit details
 
-All of these methods return appropriate data. More information and especially information about fields available in all the returned hashes can be found on the [API documentation](https://plaid.com/docs/api).
+All of these methods return appropriate data. More information can be found on the [API documentation](https://plaid.com/docs/api).
 
 ### Categories
 
@@ -199,9 +198,21 @@ Any methods making API calls will result in an exception raised unless the respo
 Read more about response codes and their meaning in the
 [Plaid documentation](https://plaid.com/docs/api).
 
+## Response Objects
+
+Any API call returns a response object which is accessible by dot notation
+(`response.foo.bar`) or Symbols and Strings as keys: `response[:foo][:bar]`
+and `response['foo']['bar']`. Expected keys for all types of responses are defined,
+and any attempt to access an unknown key will cause `NoMethodError` exception.
+
+These strict model checks can be disabled by setting `Plaid.relaxed_models = true`.
+
 ## Network Timeout
 
-A network timeout value is set in the `lib/plaid/connect.rb` file. It is currently defaulted at 600 (in seconds) which equates to about 10 minutes. Some requests from the Plaid API may take longer than others and we want to make sure that all valid requests have a chance to complete. Adjust this value if necessary.
+A network timeout value is currently defaulted at 600 seconds = 10 minutes.
+Some requests from the Plaid API may take longer than others and we want to
+make sure that all valid requests have a chance to complete. Adjust this value
+if necessary (see "Tuning Faraday").
 
 ## Contributing
 

data/Rakefile

@@ -47,34 +47,31 @@ task :update_gh_pages do
 end
 
 desc 'Generate rdoc and update gh-pages on GitHub'
-task update_github_docs: %i(rdoc update_gh_pages) do
+task update_github_docs: %i[rdoc update_gh_pages] do
   sh 'git push origin gh-pages'
 end
 
 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 = %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]
+    raise "#{cred} is not set" unless ENV[cred]
   end
 
   Dir['test/vcr_cassettes/*'].each do |fn|
     data = File.read(fn)
-    data_0 = data.clone
+    data0 = 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 }
+    next unless data != data0
+    File.open(fn, 'w') { |f| f.write data }
 
-      puts ">> Updated #{fn}"
-    end
+    puts ">> Updated #{fn}"
   end
-
 end
 
 task :test_stubbed do

data/lib/plaid.rb

@@ -2,9 +2,10 @@ require 'faraday'
 require 'faraday_middleware'
 
 require_relative 'plaid/middleware'
-require_relative 'plaid/client'
+require_relative 'plaid/products/base_product'
 require_relative 'plaid/errors'
 require_relative 'plaid/version'
+require_relative 'plaid/models'
 require_relative 'plaid/products/accounts'
 require_relative 'plaid/products/auth'
 require_relative 'plaid/products/categories'
@@ -16,3 +17,41 @@ require_relative 'plaid/products/item'
 require_relative 'plaid/products/processor'
 require_relative 'plaid/products/sandbox'
 require_relative 'plaid/products/transactions'
+require_relative 'plaid/client'
+
+# Public: The namespace for all the things Plaid.
+module Plaid
+  # Public: Get relaxed models state.
+  #
+  # We support two modes for parsing response bodies.
+  #
+  # Strict mode (default). Unknown attributes will cause NoMethodError.
+  #
+  # Relaxed mode. If a response contains an unknown
+  # attribute, it won't cause any error and will be accessible
+  # using brackets notation: `response['unknown_attribute']`.
+  #
+  # Returns truey value for relaxed mode and falsey for strict.
+  def relaxed_models?
+    defined?(@relaxed_models) && @relaxed_models
+  end
+
+  # Public: Sets value for relaxed_models.
+  def relaxed_models=(value)
+    @relaxed_models = value
+  end
+
+  module_function :relaxed_models?, :relaxed_models=
+
+  # Internal: Converts date objects to strings if needed.
+  #
+  # Takes in a string or a Date object and performs necessary operations to
+  # return a string representation of the Date.
+  #
+  # date - Date in Date object form or string form (YYYY-MM-DD).
+  #
+  # Returns a String with an ISO-8601 date.
+  def self.convert_to_date_string(date)
+    date.is_a?(String) ? date : date.to_date.strftime('%Y-%m-%d')
+  end
+end

data/lib/plaid/client.rb

@@ -3,14 +3,15 @@ module Plaid
   # Public: The main interface to Plaid API.
   class Client
     # Public: All possible environments for the client to use.
-    ENVIRONMENTS = %i(sandbox development production)
+    ENVIRONMENTS = %i[sandbox development production].freeze
 
     # Public: The current environment in use (one of ENVIRONMENTS).
     attr_reader :env
 
     # Public: Construct a Client instance
     #
-    # Optionally takes a block to allow overriding the default Faraday connection options.
+    # Optionally takes a block to allow overriding the default Faraday
+    # connection options.
     #
     # env        - The Symbol (:sandbox, :development, :production)
     # client_id  - The String Plaid account client ID to authenticate requests
@@ -26,60 +27,62 @@ module Plaid
       create_connection(&block)
     end
 
-    # Public: Memoized class instance to make requests from Plaid::Account
-    def accounts
-      @accounts ||= Plaid::Accounts.new(self)
-    end
+    extend SubproductMixin
 
-    # Public: Memoized class instance to make requests from Plaid::Auth
-    def auth
-      @auth ||= Plaid::Auth.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Accounts product accessor.
+    subproduct :accounts
 
-    # Public: Memoized class instance to make requests from Plaid::Categories
-    def categories
-      @categories ||= Plaid::Categories.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Auth product accessor.
+    subproduct :auth
 
-    # Public: Memoized class instance to make requests from Plaid::CreditDetails
-    def credit_details
-      @credit_details ||= Plaid::CreditDetails.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Categories product accessor.
+    subproduct :categories
 
-    # Public: Memoized class instance to make requests from Plaid::Identity
-    def identity
-      @identity ||= Plaid::Identity.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::CreditDetails product accessor.
+    subproduct :credit_details
 
-    # Public: Memoized class instance to make requests from Plaid::Income
-    def income
-      @income ||= Plaid::Income.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Identity product accessor.
+    subproduct :identity
 
-    # Public: Memoized class instance to make requests from Plaid::Institutions
-    def institutions
-      @institutions ||= Plaid::Institutions.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Income product accessor.
+    subproduct :income
 
-    # Public: Memoized class instance to make requests from Plaid::Item
-    def item
-      @item ||= Plaid::Item.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Institutions product accessor.
+    subproduct :institutions
 
-    # Public: Memoized class instance to make requests from Plaid::Processor
-    def processor
-      @processor ||= Plaid::Processor.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Item product accessor.
+    subproduct :item
 
-    # Public: Memoized class instance to make requests from Plaid::Sandbox
-    def sandbox
-      @sandbox ||= Plaid::Sandbox.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Processor product accessor.
+    subproduct :processor
 
-    # Public: Memoized class instance to make requests from Plaid::Transactions
-    def transactions
-      @transactions ||= Plaid::Transactions.new(self)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Sandbox product accessor.
+    subproduct :sandbox
+
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Transactions product accessor.
+    subproduct :transactions
 
     # Public: Make a post request
     #
@@ -100,7 +103,8 @@ module Plaid
     def post_with_auth(path, payload)
       @connection.post(
         path,
-        payload.merge(client_id: @client_id, secret: @secret)).body
+        payload.merge(client_id: @client_id, secret: @secret)
+      ).body
     end
 
     # Public: Make a post request with appended public key field.
@@ -113,8 +117,25 @@ module Plaid
       @connection.post(path, payload.merge(public_key: @public_key)).body
     end
 
+    # Public: Set Plaid defaults on the Faraday connection.
+    #
+    # builder - The Faraday builder object.
+    def self.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
+
     protected
 
+    # Internal: subproduct-generated methods depend on client method.
+    def client
+      self
+    end
+
     # Internal: Gets the API hostname for given environment.
     #
     # env - The Symbol (:sandbox, :development, :production)
@@ -124,8 +145,8 @@ module Plaid
     def api_host
       unless ENVIRONMENTS.include?(@env)
         raise ArgumentError,
-          "Invalid value for env (#{@env.inspect}): must be one of " +
-          ENVIRONMENTS.map(&:inspect) * ', '
+              "Invalid value for env (#{@env.inspect}): must be one of " +
+              ENVIRONMENTS.map(&:inspect) * ', '
       end
 
       "https://#{@env}.plaid.com"
@@ -134,22 +155,10 @@ module Plaid
     # Internal: Initializes a new Plaid connection object via Faraday.
     #
     # Optionally takes a block to allow overriding the defaults.
-    def create_connection(&block)
+    def create_connection
       @connection = Faraday.new(url: @api_host) do |builder|
-        block_given? ? yield(builder) : build_default_connection(builder)
+        block_given? ? yield(builder) : Client.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