plaid 13.2.0 → 42.0.0

data/README.md

@@ -1,8 +1,21 @@
-# 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)
+# plaid-ruby [![Gem Version](https://badge.fury.io/rb/plaid.svg)](http://badge.fury.io/rb/plaid)
 
-:warning: After 7/12/21, this major version of the library will only receive critical security patches. Please consider trying out our new [beta version](https://github.com/plaid/plaid-ruby/tree/14.0.0-beta-release).
+The official Ruby bindings for the [Plaid API](https://plaid.com/docs). It's generated from our [OpenAPI schema](https://github.com/plaid/plaid-openapi).
 
-The official Ruby bindings for the [Plaid API](https://plaid.com/docs).
+## Table of Contents
+
+- [Installation](#installation)
+- [Versioning](#versioning)
+- [Getting Started](#getting-started)
+  - [Create a client](#create-a-client)
+  - [Tuning Faraday](#tuning-faraday)
+  - [Dates](#dates)
+- [Examples](#examples)
+- [Errors](#errors)
+- [Response objects](#response-objects)
+- [Migration Guide](#migration-guide)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
@@ -20,61 +33,108 @@ Or install it yourself as:
 
     $ gem install plaid
 
-The gem supports Ruby 2.2+ only.
+The gem supports Ruby 3.2.0+ only.
 
 ### Versioning
 
+Versions > 14 are generated from our OpenAPI schema.
+
 Each major version of `plaid-ruby` targets a specific version of the Plaid API:
 
-| API version | plaid-ruby release |
-| ----------- | ------------------ |
-| [`2020-09-14`][api-version-2020-09-14] (**latest**) | `12.x.x` |
-| [`2019-05-29`][api-version-2019-05-29] (**latest**) | `11.x.x`, `10.x.x`, `9.x.x`, `8.x.x`, `7.x.x` |
-| [`2018-05-22`][api-version-2018-05-22] | `6.x.x` |
-| `2017-03-08` | `5.x.x` |
+| API version                                         | plaid-ruby release                            |
+| --------------------------------------------------- | --------------------------------------------- |
+| [`2020-09-14`][api-version-2020-09-14] (**latest**) | `12.x.x` and higher                           |
+| [`2019-05-29`][api-version-2019-05-29]              | `11.x.x`, `10.x.x`, `9.x.x`, `8.x.x`, `7.x.x` |
+| [`2018-05-22`][api-version-2018-05-22]              | `6.x.x`                                       |
+| `2017-03-08`                                        | `5.x.x`                                       |
 
 For information about what has changed between versions and how to update your integration, head to the [version changelog][version-changelog].
 
+The plaid-ruby client library is typically updated on a monthly basis. The canonical source for the latest version number is the [client library changelog](https://github.com/plaid/plaid-ruby/blob/master/CHANGELOG.md). New versions are published as [GitHub tags](https://github.com/plaid/plaid-ruby/tags), not as Releases. New versions are also published on [RubyGems.org](https://rubygems.org/gems/plaid/).
 
-## Usage
+All users are strongly recommended to use a recent version of the library, as older versions do not contain support for new endpoints and fields. For more details, see the [Migration Guide](#migration-guide).
 
-This gem wraps the Plaid API, which is fully described in the [documentation](https://plaid.com/docs/api).
+## Getting started
 
-The RubyDoc for the gem is available [here](http://plaid.github.io/plaid-ruby/).
-
-### Creating a Plaid client
+### Create a client
 
 Create an instance of the client using the `client_id` and `secret` from your Plaid dashboard along with your environment of choice:
 
 ```ruby
 require 'plaid'
 
-client = Plaid::Client.new(env: :sandbox,
-                           client_id: '***',
-                           secret: '***')
+configuration = Plaid::Configuration.new
+configuration.server_index = Plaid::Configuration::Environment["sandbox"]
+configuration.api_key["PLAID-CLIENT-ID"] = "***"
+configuration.api_key["PLAID-SECRET"] = "***"
+
+api_client = Plaid::ApiClient.new(
+  configuration
+)
+
+client = Plaid::PlaidApi.new(api_client)
 ```
 
-The `env` field is the environment which the client will be running in. Your choices for the `env` field include:
+The `server_index` field is the environment which the client will be running in. Your choices for the `server_index` field are:
 
-- `: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.
+- `Plaid::Configuration::Environment["sandbox"]` allows you to do your initial integrations tests against preloaded data without being billed. More information about using the API sandbox can be found on the [API Sandbox documentation](https://plaid.com/docs/api#sandbox).
+- `Plaid::Configuration::Environment["production"]` is the production environment where you can test with real data and launch.
 
 ### 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: '***') do |builder|
-  Plaid::Client.build_default_connection(builder)
+configuration = Plaid::Configuration.new
+api_client = Plaid::ApiClient.new(
+  configuration
+)
+api_client.connection.options[:timeout] = 60*20 # 20 minutes
+```
+
+To use custom middleware, reinitialize the Faraday::Connection object:
 
-  # Increase network timeout
-  builder.options[:timeout] = 60*20    # 20 minutes
+```
+configuration = Plaid::Configuration.new
+api_client = Plaid::ApiClient.new(configuration)
+api_client.create_connection do |builder|
+  builder.use Faraday::Response::Logger
 end
 ```
 
+### Dates
+
+Dates and datetimes in requests, which are represented as strings in the API and previous versions of the client library, are represented in this version of the Ruby client library as Ruby `Date` or `DateTime` objects.
+
+Time zone information is required for request fields that accept datetimes. Failing to include time zone information (or passing in a string, instead of a `Date` or `DateTime` object) will result in an error. See the following examples for guidance on `Date` and `DateTime` usage.
+
+If the API reference documentation for a field specifies `format: date`, any of following are acceptable:
+
+```rb
+require 'date'
+
+# Not an exhaustive list of possible options
+a = Date.new(2022, 5, 5)
+b = Date.new(2022, 5, 5).to_date
+c = Date.parse('2022-05-05')
+d = Date.parse('2022-05-05').to_date
+e = Date.today
+```
+
+If the API reference documentation for a field specifies `format: date-time`, either of the following are acceptable:
+
+```rb
+require 'time'
+
+# Not an exhaustive list of possible options
+a = Time.parse("2022-05-06T22:35:49Z").to_datetime
+b = Date.parse("2022-05-06T22:35:49Z").to_datetime
+```
+
 ## Examples
 
+For more examples, see the [test suites](https://github.com/plaid/plaid-ruby/tree/master/test), [Quickstart](https://github.com/plaid/quickstart/tree/master/ruby), or [API Reference documentation](https://plaid.com/docs/api/).
+
 ### Create a new link_token
 
 ```ruby
@@ -83,12 +143,16 @@ user = User.find_by!(email: '***')
 client_user_id = user.id
 
 # Create the link_token with all of your configurations
-link_token_response = client.link_token.create(
-  user: { client_user_id: client_user_id.to_s },
-  client_name: 'My app',
-  products: %w[auth transactions],
-  country_codes: ['US'],
-  language: 'en'
+link_token_create_request = Plaid::LinkTokenCreateRequest.new({
+  :user => { :client_user_id => client_user_id.to_s },
+  :client_name => 'My app',
+  :products => %w[auth transactions],
+  :country_codes => ['US'],
+  :language => 'en'
+})
+
+link_token_response = client.link_token_create(
+  link_token_create_request
 )
 
 # Pass the result to your client-side app to initialize Link
@@ -98,168 +162,236 @@ link_token = link_token_response.link_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)`
+If you have a [Link](https://plaid.com/docs/link/) `public token`, use this function to get an `access_token`: `client.item_public_token_exchange(request)`
 
 An example of the function's usage if you have a `public_token` in hand:
 
 ```ruby
-response = client.item.public_token.exchange(public_token)
+request = Plaid::ItemPublicTokenExchangeRequest.new
+request.public_token = public_token
+
+response = client.item_public_token_exchange(request)
 access_token = response.access_token
 ```
 
-
 ### Deleting an item
 
 ```ruby
-require 'plaid'
-
-client = Plaid::Client.new(env: :sandbox,
-                           client_id: '***',
-                           secret: '***')
+request = Plaid::ItemPublicTokenExchangeRequest.new
+request.public_token = public_token
 
-exchange_token_response = client.item.public_token.exchange('[Plaid Link public_token]')
-access_token = exchange_token_response.access_token
+response = client.item_public_token_exchange(request)
+access_token = response.access_token
 
 # Provide the access_token for the Item you want to remove
-client.item.remove(access_token)
+item_remove_request = Plaid::ItemRemoveRequest.new
+item_remove_request.access_token = access_token
+
+client.item_remove(item_remove_request)
 ```
 
-### Get paginated transactions
+### Get paginated transactions (preferred method)
+
 ```ruby
-require 'plaid'
+request = Plaid::ItemPublicTokenExchangeRequest.new
+request.public_token = public_token
 
-client = Plaid::Client.new(env: :sandbox,
-                           client_id: '***',
-                           secret: '***')
+response = client.item_public_token_exchange(request)
+access_token = response.access_token
+
+transactions_sync_request = Plaid::TransactionsSyncRequest.new
+transactions_sync_request.access_token = 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_sync(transactions_sync_request)
+transactions = transaction_response.added
 
-transaction_response = client.transactions.get(access_token, '2016-07-12', '2017-01-09')
+# the transactions in the response are paginated, so make multiple calls while
+# updating the cursor to retrieve all transactions
+while transaction_response.has_more
+  transactions_sync_request = Plaid::TransactionsSyncRequest.new
+  transactions_sync_request.access_token = access_token
+  transactions_sync_request.cursor = transaction_response.next_cursor
+
+  transaction_response = client.transactions_sync(transactions_sync_request)
+  transactions += transaction_response.added
+end
+```
+
+### Get paginated transactions (older method)
+
+```ruby
+request = Plaid::ItemPublicTokenExchangeRequest.new
+request.public_token = public_token
+
+response = client.item_public_token_exchange(request)
+access_token = response.access_token
+
+transactions_get_request = Plaid::TransactionsGetRequest.new
+transactions_get_request.access_token = access_token
+transactions_get_request.start_date = "2020-01-01"
+transactions_get_request.end_date = "2021-01-01"
+
+transaction_response = client.transactions_get(transactions_get_request)
 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 < transaction_response['total_transactions']
-  transaction_response = client.transactions.get(access_token,
-                                                 '2016-07-12',
-                                                 '2017-01-09',
-                                                 offset: transactions.length)
+while transactions.length < transaction_response.total_transactions
+  options_payload = {}
+  options_payload[:offset] = transactions.length
+
+  transactions_get_request = Plaid::TransactionsGetRequest.new
+  transactions_get_request.access_token = access_token
+  transactions_get_request.start_date = "2020-01-01"
+  transactions_get_request.end_date = "2021-01-01"
+  transactions_get_request.options = options_payload
+
+  transaction_response = client.transactions_get(transactions_get_request)
   transactions += transaction_response.transactions
 end
-
 ```
 
-### Obtaining Item-related data
+### Get Auth data
 
-If you have an `access_token`, you can use following code to retreive data:
 ```ruby
-require 'plaid'
+request = Plaid::ItemPublicTokenExchangeRequest.new
+request.public_token = public_token
 
-client = Plaid::Client.new(env: :sandbox,
-                           client_id: '***',
-                           secret: '***')
+response = client.item_public_token_exchange(request)
+access_token = response.access_token
 
-exchange_token_response = client.item.public_token.exchange('[Plaid Link public_token]')
-access_token = exchange_token_response.access_token
+auth_get_request = Plaid::AuthGetRequest.new
+auth_get_request.access_token = access_token
 
-auth_response = client.auth.get(access_token)
+auth_response = client.auth_get(auth_get_request)
 auth = auth_response.auth
 ```
 
-### Create a Stripe bank_account_token
+### Institutions
+
+Financial institution information is available as shown below where the function arguments represent count and offset:
 
-Exchange a Plaid Link `public_token` for an API `access_token` and a Stripe `bank_account_token`:
 ```ruby
-require 'plaid'
+institutions_get_request = Plaid::InstitutionsGetRequest.new({
+  :count => 3,
+  :offset => 1,
+  :country_codes => ["US"],
+})
 
-client = Plaid::Client.new(env: :sandbox,
-                           client_id: '***',
-                           secret: '***')
+response = client.institutions_get(institutions_get_request)
+```
 
-exchange_token_response = client.item.public_token.exchange('[Plaid Link public_token]')
-access_token = exchange_token_response.access_token
+## Errors
 
-stripe_response = client.processor.stripe.bank_account_token.create(access_token, '[Account ID]')
-bank_account_token = stripe_response.stripe_bank_account_token
-```
+Any methods making API calls will result in an exception raised unless the response code is "200: Success" or
+"210: MFA Required".
 
-There are also a number of other methods you can use to retrieve data:
+`Plaid::ApiError` is returned in response to API internal server errors.
 
-* `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
-* `client.investments.transactions.get(access_token, ...)`: investment-account transactions
-* `client.investments.holdings.get(access_token, ...)`: investment-account holdings
+Read more about response codes and their meaning in the
+[Plaid 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).
+## Response Objects
+
+All API calls return a response object that is accessible only with dot notation
+(i.e., `response.foo.bar`) and not with bracket notation. Expected keys for all types of responses are defined,
+and any attempt to access an unknown key will cause `NoMethodError` exception.
+
+## Migration guide
+
+### 14.0.0 or later to latest
+
+Migrating from a version released on or after August 2021 to a recent version should involve very minor integration changes. Many customers will not need to make changes to their integrations at all. To see a list of all potentially-breaking changes since your current version, see the [client library changelog](https://github.com/plaid/plaid-ruby/blob/master/CHANGELOG.md) and search for "Breaking changes in this version". Breaking changes are annotated at the top of each major version header.
 
-### Categories
+### Pre-14.0.0 to latest
 
-You can request category information:
+Version 14.0.0 of the client library was released in August 2021 and contains multiple interface changes, as described below.
+
+#### Client initialization
+
+From:
 
 ```ruby
-categories = client.categories.get             # Array of all known categories
+client = Plaid::Client.new(env: :sandbox,
+                            client_id: client_id,
+                            secret: secret)
 ```
 
-### Institutions
-
-Financial institution information is available as shown below where the function arguments represent count and offset:
+To:
 
 ```ruby
-institutions = client.institutions.get(count: 3, offset: 1)
+configuration = Plaid::Configuration.new
+configuration.server_index = Plaid::Configuration::Environment["sandbox"]
+configuration.api_key["PLAID-CLIENT-ID"] = ENV["PLAID_RUBY_CLIENT_ID"]
+configuration.api_key["PLAID-SECRET"] = ENV["PLAID_RUBY_SECRET"]
+configuration.api_key["Plaid-Version"] = "2020-09-14"
+
+api_client = Plaid::ApiClient.new(
+  configuration
+)
+
+client = Plaid::PlaidApi.new(api_client)
 ```
 
-## Errors
+#### Endpoints
 
-Any methods making API calls will result in an exception raised unless the response code is "200: Success" or
-"210: MFA Required".
+All endpoint requests now take a request model and the functions have been renamed to include `_`.
 
-`Plaid::InvalidRequestError` is returned when the request is malformed and cannot be processed.
+From:
 
-`Plaid::InvalidInputError` is returned when all fields are provided and are in the correct format, but the values provided are incorrect in some way.
+```ruby
+response = client.auth.get(access_token)
+```
 
-`Plaid::RateLimitExceededError` returned when the request is valid but has exceeded established rate limits.
+To:
 
-`Plaid::APIError` is returned during planned maintenance windows and in response to API internal server errors.
+```ruby
+auth_get_request = Plaid::AuthGetRequest.new
+auth_get_request.access_token = access_token
 
-`Plaid::ItemError` 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.
+or
 
-`Plaid::InstitutionError` is returned when there are errors for the requested financial institution.
+auth_get_request = Plaid::AuthGetRequest.new({:access_token => access_token})
 
-Read more about response codes and their meaning in the
-[Plaid documentation](https://plaid.com/docs/api).
+response = client.auth_get(auth_get_request)
+```
 
-## Response Objects
+#### Errors
 
-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.
+From:
 
-## Network Timeout
+```ruby
+begin
+  client.auth.get(auth_get_request)
+rescue Plaid::PlaidAPIError => e
+  raise e if e.error_code != 'PRODUCT_NOT_READY'
+  sleep 1
+end
+```
 
-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").
+To:
 
-## Contributing
+```ruby
+begin
+  client.auth_get(auth_get_request)
+rescue Plaid::ApiError => e
+  json_response = JSON.parse(e.response_body)
+  if json_response["error_code"] != "PRODUCT_NOT_READY"
+end
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/plaid/plaid-ruby. See also [contributing guidelines](CONTRIBUTING.md).
+#### Date type differences
 
-## License
+See [Dates](#dates) for information on updates to date formats.
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+## Contributing
+
+Bug reports are welcome on GitHub. See also [contributing guidelines](CONTRIBUTING.md).
 
-### Legacy API
+## License
 
-If you're looking for a Ruby client that works with the legacy Plaid API, use the [`plaid-legacy` gem][2].
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
 
-[2]: https://github.com/plaid/plaid-ruby-legacy
 [version-changelog]: https://plaid.com/docs/api/versioning/
 [api-version-2018-05-22]: https://plaid.com/docs/api/versioning/#2018-05-22
 [api-version-2019-05-29]: https://plaid.com/docs/api/versioning/#2019-05-29

data/Rakefile

@@ -1,83 +1,12 @@
-require 'bundler/gem_tasks'
-require 'sdoc'
-require 'rdoc/task'
-require 'rake/testtask'
-require 'dotenv/load'
-require 'fileutils'
-require 'tmpdir'
-
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = 'doc/rdoc'
-  rdoc.generator = 'sdoc'
-  rdoc.main = 'README.md'
-
-  rdoc.rdoc_files.include('README.md', 'LICENSE.txt', 'lib/**/*.rb')
-  rdoc.markup = 'tomdoc'
-end
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "dotenv/load"
+require "fileutils"
 
 Rake::TestTask.new do |t|
-  t.libs << 'test'
-  t.test_files = FileList['test/test*.rb']
+  t.libs << "test"
+  t.test_files = FileList['test/*.rb']
   t.verbose = true
-  t.ruby_opts << '-rminitest/pride'
-end
-
-desc 'Update the gh-pages branch with doc/rdoc contents'
-task :update_gh_pages do
-  tmpdir = Dir::Tmpname.create('plaid_docs') {}
-
-  desc = `git describe`.chomp
-
-  sh "git clone --shared . #{tmpdir}"
-
-  Dir.chdir(tmpdir) do
-    sh 'git checkout gh-pages'
-    FileUtils.rm_rf Dir.glob("#{tmpdir}/*")
-  end
-
-  FileUtils.cp_r Dir.glob('doc/rdoc/*'), tmpdir
-
-  Dir.chdir(tmpdir) do
-    sh 'git add .'
-    sh 'git add --update .'
-    sh "git commit --allow-empty -m 'Regenerate docs for #{desc}'"
-    sh 'git push'
-  end
-
-  FileUtils.rm_rf tmpdir
+  t.ruby_opts << "-rminitest/pride"
+  t.warning = false
 end
-
-desc 'Generate rdoc and update gh-pages on GitHub'
-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]
-
-  all_creds.each do |cred|
-    raise "#{cred} is not set" unless ENV[cred]
-  end
-
-  Dir['test/vcr_cassettes/*'].each do |fn|
-    data = File.read(fn)
-    data0 = data.clone
-
-    all_creds.each do |cred|
-      data.gsub! ENV[cred], cred
-    end
-
-    next unless data != data0
-    File.open(fn, 'w') { |f| f.write data }
-
-    puts ">> Updated #{fn}"
-  end
-end
-
-task :test_stubbed do
-  ENV['STUB_API'] ||= '1'
-  Rake::Task['test'].invoke
-end
-
-task default: :test_stubbed

data/UPGRADING.md

@@ -1,3 +1,7 @@
+## Upgrading from 13.0.0 to 14.0.0
+
+See the [CHANGELOG](CHANGELOG.md) for what needs to be updated.
+
 ## 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.