plaid 1.7.1 → 2.0.0.alpha

data/lib/plaid/connector.rb

@@ -0,0 +1,168 @@
+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)
+
+      # 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

data/lib/plaid/errors.rb

@@ -1,27 +1,37 @@
 module Plaid
+  # Public: Exception to throw when there are configuration problems
+  class NotConfiguredError < StandardError; end
+
+  # Internal: Base class for Plaid errors
   class PlaidError < StandardError
-    attr_reader :code
-    attr_reader :resolve
-    
+    attr_reader :code, :resolve
+
+    # Internal: Initialize a error with proper attributes.
+    #
+    # code    - The Integer code (e.g. 1501).
+    # message - The String message, describing the error.
+    # resolve - The String description how to fix the error.
     def initialize(code, message, resolve)
-      super(message)
       @code = code
       @resolve = resolve
+
+      super "Code #{@code}: #{message}. #{resolve}"
     end
   end
 
-  class BadRequest < PlaidError
-  end
+  # Public: Exception which is thrown when Plaid API returns a 400 response.
+  class BadRequestError    < PlaidError; end
 
-  class Unauthorized < PlaidError
-  end
+  # Public: Exception which is thrown when Plaid API returns a 401 response.
+  class UnauthorizedError  < PlaidError; end
 
-  class RequestFailed < PlaidError
-  end
+  # Public: Exception which is thrown when Plaid API returns a 402 response.
+  class RequestFailedError < PlaidError; end
 
-  class NotFound < PlaidError
-  end
+  # Public: Exception which is thrown when Plaid API returns a 404 response.
+  class NotFoundError      < PlaidError; end
 
-  class ServerError < PlaidError
-  end
+  # Public: Exception which is thrown when Plaid API returns a response which
+  # is neither 2xx, nor 4xx. Presumably 5xx.
+  class ServerError        < PlaidError; end
 end

data/lib/plaid/income.rb

@@ -0,0 +1,106 @@
+module Plaid
+  # Public: Representation of Income data.
+  class Income
+    # Public: The class encapsulating an income stream.
+    class Stream
+      # Public: The Float monthly income associated with the income stream.
+      # E.g. 5700.
+      attr_reader :monthly_income
+
+      # Public: The Float representation of Plaid's confidence in the income
+      # data associated with this particular income stream, with 0 being
+      # the lowest confidence and 1 being the highest. E.g. 0.9.
+      attr_reader :confidence
+
+      # Public: The Integer extent of data found for this income stream.
+      # E.g. 314.
+      attr_reader :days
+
+      # Public: The String name of the entity associated with this income
+      # stream. E.g. "APPLE INC".
+      attr_reader :name
+
+      # Internal: Initialize a Stream.
+      #
+      # fields - The Hash with fields (keys are Strings).
+      def initialize(fields)
+        @monthly_income = fields['monthly_income']
+        @confidence = fields['confidence']
+        @days = fields['days']
+        @name = fields['name']
+      end
+
+      # Public: Get a String representation of the Stream.
+      #
+      # Returns a String.
+      def inspect
+        "#<Plaid::Income::Stream name=#{name.inspect}, " \
+          "monthly_income=#{monthly_income.inspect}, " \
+          "confidence=#{confidence.inspect}, " \
+          "days=#{days.inspect}>"
+      end
+
+      # Public: Get a String representation of the Stream.
+      #
+      # Returns a String.
+      alias to_s inspect
+    end
+
+    # Public: The Array of Stream.
+    attr_reader :income_streams
+
+    # Public: The Numeric sum of user's income over the past 365 days. If Plaid
+    # has less than 365 days of data this will be less than a full year income.
+    # E.g. 67000.
+    attr_reader :last_year_income
+
+    # Public: The last_year_income interpolated to value before taxes. This is
+    # the minimum pre-tax salary that assumes a filing status of single with
+    # zero dependents. E.g. 73700.
+    attr_reader :last_year_income_before_tax
+
+    # Public: The Numeric user's income extrapolated over a year based on
+    # current, active income streams. Income streams become inactive if they
+    # have not recurred for more than two cycles. For example, if a weekly
+    # paycheck hasn't been seen for the past two weeks, it is no longer active.
+    # E.g. 69800.
+    attr_reader :projected_yearly_income
+
+    # Public: The projected_yearly_income interpolated to value before taxes.
+    # This is the minimum pre-tax salary that assumes a filing status of single
+    # with zero dependents. E.g. 75600.
+    attr_reader :projected_yearly_income_before_tax
+
+    # Public: The Integer max number of income streams present at the same time
+    # over the past 365 days. E.g. 314.
+    attr_reader :max_number_of_overlapping_income_streams
+
+    # Public: The Integer total number of distinct income streams received over
+    # the past 365 days. E.g. 2.
+    attr_reader :number_of_income_streams
+
+    def initialize(fields)
+      @income_streams = fields['income_streams'].map { |is| Stream.new(is) }
+
+      %w(last_year_income last_year_income_before_tax projected_yearly_income
+         projected_yearly_income_before_tax number_of_income_streams
+         max_number_of_overlapping_income_streams).each do |field|
+        instance_variable_set "@#{field}", fields[field]
+      end
+    end
+
+    # Public: Get a String representation of Income.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::Income last_year_income=#{last_year_income.inspect}, " \
+        "projected_yearly_income=#{projected_yearly_income.inspect}, " \
+        "number_of_income_streams=#{number_of_income_streams.inspect}, ...>"
+    end
+
+    # Public: Get a String representation of Income.
+    #
+    # Returns a String.
+    alias to_s inspect
+  end
+end

data/lib/plaid/info.rb

@@ -0,0 +1,65 @@
+module Plaid
+  # Public: Representation of user information.
+  class Info
+    # Public: The Array of String user names.
+    #
+    # E.g. ["Frodo Baggins", "Samwise Gamgee"].
+    attr_reader :names
+
+    # Public: The Array of Hash user emails information.
+    #
+    # E.g. [{data: "frodo.baggins@plaid.com", type: :primary}, ...]
+    attr_reader :emails
+
+    # Public: The Array of Hash user phone number information.
+    #
+    # E.g. [{data: "111-222-3456", type: :work, primary: false},
+    #       {data: "123-456-7891", type: :mobile, primary: true}]
+    attr_reader :phone_numbers
+
+    # Public: The Array of Hash user address information.
+    #
+    # E.g. [{ primary: true, data: {
+    #                          "street" => "1 Hobbit Way",
+    #                          "city" => "The Shire",
+    #                          "state" => "CA",
+    #                          "zip" => "94108"}}]
+    attr_reader :addresses
+
+    # Internal: Construct the Info object.
+    def initialize(fields)
+      @names = fields['names']
+      @emails = fields['emails'].map do |h|
+        symbolize_values Plaid.symbolize_hash(h), :type
+      end
+
+      @phone_numbers = fields['phone_numbers'].map do |h|
+        symbolize_values Plaid.symbolize_hash(h), :type
+      end
+
+      @addresses = fields['addresses'].map do |h|
+        Plaid.symbolize_hash(h)
+      end
+    end
+
+    # Public: Get a String representation of Info object.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::Info names=#{names.inspect}, ...>"
+    end
+
+    # Public: Get a String representation of Info object.
+    #
+    # Returns a String.
+    alias to_s inspect
+
+    private
+
+    def symbolize_values(hash, *keys)
+      hash.each do |k, v|
+        hash[k] = v.to_sym if keys.include?(k)
+      end
+    end
+  end
+end

data/lib/plaid/institution.rb

@@ -0,0 +1,240 @@
+module Plaid
+  # Public: A class encapsulating information about a Financial Institution
+  # supported by Plaid.
+  class Institution
+    # Public: The String institution ID. E.g. "5301a93ac140de84910000e0".
+    attr_reader :id
+
+    # Public: The String institution name. E.g. "Bank of America".
+    attr_reader :name
+
+    # Public: The String institution shortname, or "type" per Plaid API docs.
+    # E.g. "bofa".
+    attr_reader :type
+
+    # Public: The Boolean flag telling if the institution requires MFA.
+    attr_reader :has_mfa
+
+    # Public: Returns true if the institution requires MFA.
+    alias has_mfa? has_mfa
+
+    # Public: The Hash with MFA options available. E.g. ["code", "list",
+    # "questions(3)"]. This means that you are allowed to request a list of
+    # possible MFA options, use code-based MFA and questions MFA (there are 3
+    # questions).
+    attr_reader :mfa
+
+    # Public: The Hash with credential labels, how they are exactly named by
+    # the institution. E.g. {"username": "Online ID", "password": "Password"}.
+    attr_reader :credentials
+
+    # Public: An Array with Symbol product names supported by the institution.
+    # E.g. [:connect, :auth, :balance, :info, :income, :risk]. See
+    # Plaid::PRODUCTS.
+    attr_reader :products
+
+    # Internal: Initialize an Institution with given fields.
+    def initialize(fields)
+      @id = fields['id']
+      @name = fields['name']
+      @type = fields['type']
+      @has_mfa = fields['has_mfa']
+      @mfa = fields['mfa']
+      @credentials = fields['credentials']
+      @products = fields['products'].map(&:to_sym)
+    end
+
+    # Public: Get a String representation of the institution.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::Institution id=#{id.inspect}, type=#{type.inspect}, " \
+      "name=#{name.inspect}>"
+    end
+
+    # Public: Get a String representation of the institution.
+    #
+    # Returns a String.
+    alias to_s inspect
+
+    # Public: Get information about the Financial Institutions currently
+    # supported by Plaid.
+    #
+    # Does a GET /institutions call.
+    #
+    # client - The Plaid::Client instance used to connect
+    #          (default: Plaid.client).
+    #
+    # Returns an Array of Institution instances.
+    def self.all(client: nil)
+      Connector.new(:institutions, client: client).get.map do |idata|
+        new(idata)
+      end
+    end
+
+    # Public: Get information about a given Financial Institution.
+    #
+    # Does a GET /institutions/:id call.
+    #
+    # id     - the String institution ID (e.g. "5301a93ac140de84910000e0").
+    # client - The Plaid::Client instance used to connect
+    #          (default: Plaid.client).
+    #
+    # Returns an Institution instance or raises Plaid::NotFoundError if
+    # institution with given id is not found.
+    def self.get(id, client: nil)
+      new Connector.new(:institutions, id, client: client).get
+    end
+  end
+
+  ##############################################################################
+
+  # Public: A class encapsulating information about a "long tail" Financial
+  # Institution supported by Plaid.
+  class LongTailInstitution
+    # Public: The String ID of the institution. Same as type. E.g. "bofa".
+    attr_reader :id
+
+    # Public: The String short name ("type") of the institution. E.g. "bofa".
+    attr_reader :type
+
+    # Public: The String institution name. E.g. "Bank of America".
+    attr_reader :name
+
+    # Public: The Hash with supported products as keys and booleans as values.
+    #
+    # E.g. { auth: true, balance: true, connect: true, info: true }.
+    attr_reader :products
+
+    # Public: The String "forgotten password" URL.
+    attr_reader :forgotten_password_url
+
+    # Public: The String "account locked" URL.
+    attr_reader :account_locked_url
+
+    # Public: The String "account setup" URL.
+    attr_reader :account_setup_url
+
+    # Public: The String video (???).
+    attr_reader :video
+
+    # Public: The Array of Hashes with login fields information.
+    #
+    # E.g. [{ name: 'username', label: 'Online ID', type: 'text' },
+    #       { name: 'password', label: 'Password', type: 'password' }].
+    attr_reader :fields
+
+    # Public: The Hash with color information for the institution.
+    #
+    # E.g. { primary: 'rgba(220,20,48,1)',
+    #        darker: 'rgba(180,11,35,1)',
+    #        gradient: ['rgba(250,20,51,1)', 'rgba(227,24,55,1)'] }.
+    attr_reader :colors
+
+    # Public: The String with base64 encoded logo.
+    attr_reader :logo
+
+    # Public: ???.
+    attr_reader :name_break
+
+    # Internal: Initialize the LongTailInstitution instance.
+    def initialize(hash)
+      %w(id type name video logo).each do |f|
+        instance_variable_set "@#{f}", hash[f]
+      end
+
+      @products = Plaid.symbolize_hash(hash['products'])
+      @forgotten_password_url = hash['forgottenPassword']
+      @account_locked_url = hash['accountLocked']
+      @account_setup_url = hash['accountSetup']
+      @fields = hash['fields'].map { |fld| Plaid.symbolize_hash(fld) }
+      @colors = Plaid.symbolize_hash(hash['colors'])
+      @name_break = hash['nameBreak']
+    end
+
+    # Public: Get a String representation of the institution.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::LongTailInstitution id=#{id.inspect}, name=#{name.inspect}, " \
+        '...>'
+    end
+
+    # Public: Get a String representation of the institution.
+    #
+    # Returns a String.
+    alias to_s inspect
+
+    # Public: Lookup a "long tail" Financial Institution by ID.
+    #
+    # Does a GET /institutions/search call with id param.
+    #
+    # id - the String institution ID (e.g. 'bofa').
+    # client - The Plaid::Client instance used to connect
+    #          (default: Plaid.client).
+    #
+    # Returns an Institution instance or nil if institution with given id is not
+    # found.
+    def self.get(id, client: nil)
+      client ||= Plaid.client
+
+      # If client_id is set, use it, no authentication otherwise
+      auth = client && !client.client_id.nil?
+      conn = Connector.new(:institutions, :search, auth: auth, client: client)
+      resp = conn.get(id: id)
+
+      case resp
+      when Hash
+        new resp
+      when Array
+        raise 'Non-empty array returned by /institutions/search with id' \
+          unless resp.empty?
+
+        nil
+      else
+        raise 'Unexpected result returned by /institutions/search with id: ' \
+          "#{resp.inspect}"
+      end
+    end
+
+    # Public: Get information about the "long tail" institutions supported
+    # by Plaid via partnerships.
+    #
+    # Does a POST /institutions/longtail call.
+    #
+    # count  - The Integer number of results to retrieve (default: 50).
+    # offset - The Integer number of results to skip forward from the
+    #          beginning of the list (default: 0).
+    # client - The Plaid::Client instance used to connect
+    #          (default: Plaid.client).
+    #
+    # Returns an Array of LongTailInstitution instances.
+    def self.all(count: 50, offset: 0, client: nil)
+      conn = Connector.new(:institutions, :longtail, auth: true, client: client)
+      resp = conn.post(count: count, offset: offset)
+      resp.map { |lti_data| new(lti_data) }
+    end
+
+    # Public: Search "long tail" institutions.
+    #
+    # query   - The String search query to match against the full list of
+    #           institutions. Partial matches are returned making this useful
+    #           for autocompletion purposes.
+    # product - The Symbol product name to filter by, one of Plaid::PRODUCTS
+    #           (e.g. :info, :connect, etc.). Only valid when query is
+    #           specified. If nil, results are not filtered by product
+    #           (default: nil).
+    # client - The Plaid::Client instance used to connect
+    #          (default: Plaid.client).
+    def self.search(query: nil, product: nil, client: nil)
+      raise ArgumentError, 'query must be specified' \
+        unless query.is_a?(String) && !query.empty?
+
+      payload = { q: query }
+      payload[:p] = product.to_s if product
+
+      resp = Connector.new(:institutions, :search, client: client).get(payload)
+      resp.map { |lti_data| new(lti_data) }
+    end
+  end
+end