plaid-legacy 3.0.0

data/UPGRADING.md

@@ -0,0 +1,60 @@
+## 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/bin/console

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'plaid'
+require 'pry'
+
+Plaid.config do |p|
+  p.env = :tartan
+  p.client_id = ENV['PLAID_CLIENT_ID']
+  p.secret = ENV['PLAID_SECRET']
+end
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/plaid.rb

@@ -0,0 +1,64 @@
+require 'plaid/version'
+require 'plaid/errors'
+require 'plaid/connector'
+require 'plaid/category'
+require 'plaid/institution'
+require 'plaid/user'
+require 'plaid/transaction'
+require 'plaid/info'
+require 'plaid/income'
+require 'plaid/client'
+require 'plaid/webhook'
+
+require 'uri'
+
+# Public: The Plaid namespace.
+module Plaid
+  # Public: Available Plaid products.
+  PRODUCTS = %i(connect auth info income risk).freeze
+
+  class <<self
+    # Public: The default Client.
+    attr_accessor :client
+
+    # Public: The Integer read timeout for requests to Plaid HTTP API.
+    # Should be specified in seconds. Default value is 120 (2 minutes).
+    attr_accessor :read_timeout
+
+    # Public: A helper function to ease configuration.
+    #
+    # Yields self.
+    #
+    # Examples
+    #
+    #   Plaid.configure do |p|
+    #     p.client_id = 'Plaid provided client ID here'
+    #     p.secret = 'Plaid provided secret key here'
+    #     p.env = :tartan
+    #     p.read_timeout = 300   # it's 5 minutes, yay!
+    #   end
+    #
+    # Returns nothing.
+    def config
+      client = Client.new
+      yield client
+      self.client = client
+    end
+
+    # Internal: Symbolize keys (and values) for a hash.
+    #
+    # hash   - The Hash with string keys (or nil).
+    # values - The Boolean flag telling the function to symbolize values
+    #          as well.
+    #
+    # Returns a Hash with keys.to_sym (or nil if hash is nil).
+    def symbolize_hash(hash, values: false)
+      return unless hash
+      return hash.map { |h| symbolize_hash(h) } if hash.is_a?(Array)
+
+      hash.each_with_object({}) do |(k, v), memo|
+        memo[k.to_sym] = values ? v.to_sym : v
+      end
+    end
+  end
+end

data/lib/plaid/account.rb

@@ -0,0 +1,144 @@
+require 'plaid/risk'
+
+module Plaid
+  # Public: Representation of user account data.
+  class Account
+    # Public: The String unique ID of the account. E.g.
+    # "QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK".
+    attr_reader :id
+
+    # Public: The String account ID unique to the accounts of a particular
+    # access token. E.g. "KdDjmojBERUKx3JkDd9RuxA5EvejA4SENO4AA".
+    attr_reader :item_id
+
+    # Public: The Float value of the current balance for the account.
+    attr_reader :current_balance
+
+    # Public: The Float value of the available balance for the account.
+    #
+    # The Available Balance is the Current Balance less any outstanding holds
+    # or debits that have not yet posted to the account. Note that not all
+    # institutions calculate the Available Balance. In the case that Available
+    # Balance is unavailable from the institution, Plaid will either return an
+    # Available Balance value of null or only return a Current Balance.
+    attr_reader :available_balance
+
+    # Public: The Symbol institution type, e.g. :wells.
+    attr_reader :institution
+
+    # Public: The Hash with additional information pertaining to the account
+    # such as the limit, name, or last few digits of the account number. E.g.
+    # {"name": "Plaid Savings", "number": "9606" }.
+    attr_reader :meta
+
+    # Public: The Symbol account type. One of :depository, :credit, :loan,
+    # :mortgage, :brokerage, and :other.
+    attr_reader :type
+
+    # Public: The String account subtype. E.g. "savings".
+    #
+    # Read more about subtypes in the Plaid API docs.
+    attr_reader :subtype
+
+    # Public: The Hash with account and routing numbers for the account.
+    #
+    # This attribute would be nil unless you used Auth product for the user.
+    #
+    # The Hash contains Symbol keys and String values. E.g.
+    # {routing: "021000021", account: "9900009606", wireRouting: "021000021"}.
+    attr_reader :numbers
+
+    # Public: The Risk information associated with the account.
+    #
+    # This attribute would be nil unless you used Risk product for the user.
+    attr_reader :risk
+
+    def initialize(hash)
+      @id          = hash['_id']
+      @item_id     = hash['_item']
+      @meta        = hash['meta']
+      @type        = hash['type'].to_sym
+      @subtype     = hash['subtype']
+      @institution = hash['institution_type'].to_sym
+
+      unless (bal = hash['balance']).nil?
+        @available_balance = bal['available']
+        @current_balance   = bal['current']
+      end
+
+      if (risk = hash['risk'])
+        @risk = Plaid::Risk.new(risk)
+      end
+
+      @numbers = Plaid.symbolize_hash(hash['numbers'])
+    end
+
+    # Public: Get a String representation of the account.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::Account id=#{id.inspect}, type=#{type.inspect}, " \
+      "name=#{name.inspect}, institution=#{institution.inspect}>"
+    end
+
+    # Public: Get a String representation of the account.
+    #
+    # Returns a String.
+    alias to_s inspect
+
+    # Public: Get the account name.
+    #
+    # The name is obtained from #meta Hash.
+    #
+    # Returns the String name.
+    def name
+      meta && meta['name']
+    end
+
+    # Internal: Merge account information.
+    #
+    # accounts     - The Array of Account instances.
+    # new_accounts - The Array of Account instances.
+    #
+    # Returns accounts.
+    def self.merge(accounts, new_accounts)
+      # Index accounts by their ID.
+      #
+      # Same as index = accounts.index_by(&:id) in ActiveSupport.
+      index = Hash[accounts.map { |a| [a.id, a] }]
+
+      new_accounts.each do |acc|
+        if (old_acc = index[acc.id])
+          old_acc.update_from(acc)
+        else
+          accounts << acc
+        end
+      end
+
+      accounts
+    end
+
+    # Internal: Update account information.
+    #
+    # All fields which are not nil in another are copied to self.
+    #
+    # another - The Account instance with new information.
+    #
+    # Returns self.
+    def update_from(another)
+      # A sanity check. Nobody would want to update information from totally
+      # different account!
+      if id != another.id
+        raise ArgumentError, 'Plaid::Account#update_from: id != another.id!'
+      end
+
+      %i(item_id meta name type subtype institution available_balance
+         current_balance numbers risk).each do |field|
+        value = another.send(field)
+        instance_variable_set("@#{field}", value) unless value.nil?
+      end
+
+      self
+    end
+  end
+end

data/lib/plaid/category.rb

@@ -0,0 +1,62 @@
+module Plaid
+  # Public: A class which encapsulates information about a Plaid category.
+  class Category
+    # Public: The String category ID, e.g. "21010006".
+    attr_reader :id
+
+    # Public: The Symbol category type. One of :special, :place, :digital.
+    attr_reader :type
+
+    # Public: The Array of String hierarchy. E.g.
+    # ["Food and Drink", "Nightlife"].
+    attr_reader :hierarchy
+
+    # Internal: Initialize a Category with given fields.
+    def initialize(fields)
+      @type = fields['type'].to_sym
+      @hierarchy = fields['hierarchy']
+      @id = fields['id']
+    end
+
+    # Public: Get a String representation of Category.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::Category id=#{id.inspect}, type=#{type.inspect}, " \
+      "hierarchy=#{hierarchy.inspect}>"
+    end
+
+    # Public: Get a String representation of Category.
+    #
+    # Returns a String.
+    alias to_s inspect
+
+    # Public: Get information about all available categories.
+    #
+    # Does a GET /categories call.
+    #
+    # client - The Plaid::Client instance used to connect
+    #          (default: Plaid.client).
+    #
+    # Returns an Array of Category instances.
+    def self.all(client: nil)
+      Connector.new(:categories, client: client).get.map do |category_data|
+        new(category_data)
+      end
+    end
+
+    # Public: Get information about a given category.
+    #
+    # Does a GET /categories/:id call.
+    #
+    # id     - the String category ID (e.g. "17001013").
+    # client - The Plaid::Client instance used to connect
+    #          (default: Plaid.client).
+    #
+    # Returns a Category instance or raises Plaid::NotFoundError if category
+    # with given id is not found.
+    def self.get(id, client: nil)
+      new Connector.new(:categories, id, client: client).get
+    end
+  end
+end

data/lib/plaid/client.rb

@@ -0,0 +1,69 @@
+module Plaid
+  # Public: A class encapsulating client_id, secret, and Plaid API URL.
+  class Client
+    # Public: The String Plaid account client ID to authenticate requests.
+    attr_accessor :client_id
+
+    # Public: The String Plaid account secret to authenticate requests.
+    attr_accessor :secret
+
+    # Public: Plaid environment, i.e. String base URL of the API site.
+    #
+    # E.g. 'https://tartan.plaid.com'.
+    attr_reader :env
+
+    # Public: Set Plaid environment to use.
+    #
+    # env - The Symbol (:tartan, :production), or a full String URL like
+    #       'https://tartan.plaid.com'.
+    def env=(env)
+      case env
+      when :tartan
+        @env = 'https://tartan.plaid.com/'
+      when :production
+        @env = 'https://api.plaid.com/'
+      when String
+        begin
+          URI.parse(env)
+          @env = env
+        rescue
+          raise ArgumentError, 'Invalid URL in Plaid::Client.env' \
+                               " (#{env.inspect}). " \
+                               'Specify either Symbol (:tartan, :production),' \
+                               " or a full URL, like 'https://tartan.plaid.com'"
+        end
+      else
+        raise ArgumentError, 'Invalid value for Plaid::Client.env' \
+                             " (#{env.inspect}): " \
+                             'must be :tartan, :production, or a full URL, ' \
+                             "e.g. 'https://tartan.plaid.com'"
+      end
+    end
+
+    # Public: Construct a Client instance.
+    #
+    # env       - The Symbol (:tartan, :production), or a full String URL like
+    #             'https://tartan.plaid.com'.
+    # client_id - The String Plaid account client ID to authenticate requests.
+    # secret    - The String Plaid account secret to authenticate requests.
+    def initialize(env: nil, client_id: nil, secret: nil)
+      env && self.env = env
+      self.client_id = client_id
+      self.secret = secret
+    end
+
+    # Public: Check if client_id is configured.
+    #
+    # Returns true if it is.
+    def client_id_configured?
+      @client_id.is_a?(String) && !@client_id.empty?
+    end
+
+    # Public: Check if client_id is configured.
+    #
+    # Returns true if it is.
+    def secret_configured?
+      @secret.is_a?(String) && !@secret.empty?
+    end
+  end
+end

data/lib/plaid/connector.rb

@@ -0,0 +1,172 @@
+require 'net/http'
+require 'uri'
+require 'multi_json'
+
+module Plaid
+  # Internal: A class encapsulating HTTP requests to the Plaid API servers
+  class Connector
+    attr_reader :uri, :http, :request, :response, :body
+
+    # Internal: Default read timeout for HTTP calls.
+    DEFAULT_TIMEOUT = 120
+
+    # Internal: Prepare to run request.
+    #
+    # path    - The String path without leading slash. E.g. 'connect'
+    # subpath - The String subpath. E.g. 'get'
+    # auth    - The Boolean flag indicating that client_id and secret should be
+    #           included into the request payload.
+    # client  - The Plaid::Client instance used to connect
+    #           (default: Plaid.client).
+    def initialize(path, subpath = nil, auth: false, client: nil)
+      @auth = auth
+      @client = client || Plaid.client
+      verify_configuration
+
+      path = File.join(@client.env, path.to_s)
+      path = File.join(path, subpath.to_s) if subpath
+
+      @uri = URI.parse(path)
+
+      @http = Net::HTTP.new(@uri.host, @uri.port)
+      @http.use_ssl = true
+
+      @http.read_timeout = Plaid.read_timeout || DEFAULT_TIMEOUT
+    end
+
+    # Internal: Run GET request.
+    #
+    # Returns the parsed JSON response body.
+    def get(payload = {})
+      payload = with_credentials(payload)
+
+      @uri.query = URI.encode_www_form(payload) unless payload.empty?
+
+      run Net::HTTP::Get.new(@uri)
+    end
+
+    # Internal: Run POST request.
+    #
+    # Adds client_id and secret to the payload if @auth is true.
+    #
+    # payload - The Hash with data.
+    #
+    # Returns the parsed JSON response body.
+    def post(payload)
+      post_like payload, Net::HTTP::Post.new(@uri.path)
+    end
+
+    # Internal: Run PATCH request.
+    #
+    # Adds client_id and secret to the payload if @auth is true.
+    #
+    # payload - The Hash with data.
+    #
+    # Returns the parsed JSON response body.
+    def patch(payload)
+      post_like payload, Net::HTTP::Patch.new(@uri.path)
+    end
+
+    # Internal: Run DELETE request.
+    #
+    # Adds client_id and secret to the payload if @auth is true.
+    #
+    # payload - The Hash with data.
+    #
+    # Returns the parsed JSON response body.
+    def delete(payload)
+      post_like payload, Net::HTTP::Delete.new(@uri.path)
+    end
+
+    # Internal: Check if MFA response received.
+    #
+    # Returns true if response has code 201.
+    def mfa?
+      @response.is_a?(Net::HTTPCreated)
+    end
+
+    private
+
+    # Internal: Run the request and process the response.
+    #
+    # Returns the parsed JSON body or raises an appropriate exception (a
+    # descendant of Plaid::PlaidError).
+    def run(request)
+      @request = request
+      @response = http.request(@request)
+
+      if @response.body.nil? || @response.body.empty?
+        raise Plaid::ServerError.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 = MultiJson.load(@response.body)
+
+      case @response
+      when Net::HTTPSuccess, Net::HTTPCreated
+        @body
+      else
+        raise_error
+      end
+    end
+
+    # Internal: Run POST-like request.
+    #
+    # payload - The Hash with posted data.
+    # request - The Net::HTTPGenericRequest descendant instance.
+    def post_like(payload, request)
+      request.set_form_data(with_credentials(payload))
+
+      run request
+    end
+
+    # Internal: Raise an error with the class depending on @response.
+    #
+    # Returns an Array with arguments.
+    def raise_error
+      klass = case @response
+              when Net::HTTPBadRequest then Plaid::BadRequestError
+              when Net::HTTPUnauthorized then Plaid::UnauthorizedError
+              when Net::HTTPPaymentRequired then Plaid::RequestFailedError
+              when Net::HTTPNotFound then Plaid::NotFoundError
+              else
+                Plaid::ServerError
+              end
+
+      raise klass.new(body['code'], body['message'], body['resolve'])
+    end
+
+    # Internal: Verify that Plaid environment is properly configured.
+    #
+    # Raises NotConfiguredError if anything is wrong.
+    def verify_configuration
+      raise_not_configured(:env, auth: false) unless @client.env
+      return unless @auth
+
+      !@client.client_id_configured? && raise_not_configured(:client_id)
+      !@client.secret_configured? && raise_not_configured(:secret)
+    end
+
+    # Internal: Raise a NotConfiguredError exception with proper message.
+    def raise_not_configured(field, auth: true)
+      message = "You must set Plaid::Client.#{field} before using any methods"
+      message << ' which require authentication' if auth
+      message << "! It's current value is #{@client.send(field).inspect}. " \
+                 'E.g. add a Plaid.config do .. end block somewhere in the ' \
+                 'initialization code of your program.'
+
+      raise NotConfiguredError, message
+    end
+
+    # Internal: Merge credentials to the payload if needed.
+    def with_credentials(payload)
+      if @auth
+        payload.merge(client_id: @client.client_id,
+                      secret: @client.secret)
+      else
+        payload
+      end
+    end
+  end
+end