plaid 1.7.1 → 2.0.0.alpha

data/lib/plaid/risk.rb

@@ -0,0 +1,34 @@
+module Plaid
+  # Public: Representation of risk data (per account).
+  class Risk
+    # Public: The Float comprehensive risk score associated with the account,
+    # where 0 is the lowest risk and 1 is the highest. E.g. 0.5.
+    attr_reader :score
+
+    # Public: The Hash with Symbol reasons and associated Float subscores
+    # contributing to the overall risk score.
+    #
+    # E.g. { transaction_amounts: 0.78, foreign_fees: 0.96, ... }.
+    attr_reader :reason
+
+    # Internal: Construct a Risk object.
+    #
+    # fields - The Hash with fields.
+    def initialize(fields)
+      @score = fields['score']
+      @reason = Plaid.symbolize_hash(fields['reason'])
+    end
+
+    # Public: Get a String representation of Risk.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::Risk score=#{score.inspect}, ..."
+    end
+
+    # Public: Get a String representation of Risk.
+    #
+    # Returns a String.
+    alias to_s inspect
+  end
+end

data/lib/plaid/transaction.rb

@@ -0,0 +1,123 @@
+# coding: utf-8
+require 'date'
+
+module Plaid
+  # Public: Representation of a transaction.
+  class Transaction
+    # Public: The String unique ID of the transaction. E.g.
+    # "0AZ0De04KqsreDgVwM1RSRYjyd8yXxSDQ8Zxn".
+    attr_reader :id
+
+    # Public: The String ID of the account in which this transaction occurred.
+    # E.g. "XARE85EJqKsjxLp6XR8ocg8VakrkXpTXmRdOo".
+    attr_reader :account_id
+
+    # Public: The Date that the transaction took place.
+    # E.g. #<Date: 2016-04-28 ...>
+    attr_reader :date
+
+    # Public: The settled dollar value as Float. Positive values when
+    # money moves out of the account; negative values when money moves
+    # in. E.g. 0.10 (10 cents).
+    attr_reader :amount
+
+    # Public: The String descriptive name of the transaction. E.g.
+    # "Golden Crepes".
+    attr_reader :name
+
+    # Public: The Hash with additional information regarding the
+    # transaction. The keys are Symbols. E.g.
+    # { location: { "city": "San Francisco", "state": "CA" } }
+    attr_reader :meta
+
+    # Public: The Hash with location information obtained from the
+    # meta field. The keys are Strings.
+    #
+    # E.g. {"address" => "262 W 15th St",
+    #       "city" => "New York",
+    #       "state" => "NY",
+    #       "zip" => "10011",
+    #       "coordinates" => {
+    #         "lat" => 40.740352,
+    #         "lon" => -74.001761
+    #       }}
+    attr_reader :location
+
+    # Public: The Boolean flag which identifies the transaction as
+    # pending or unsettled.
+    attr_reader :pending
+
+    # Public: The Hash with numeric representation of Plaid confidence
+    # in the meta data attached to the transaction. In the case of a
+    # score <.9 Plaid will default to guaranteed and known
+    # information. E.g.
+    #
+    # {location: {
+    #    "address" => 1,
+    #    "city" => 1,
+    #    "state" => 1
+    #  }, name: 0.9}.
+    attr_reader :score
+
+    # Public: The Hash transaction type.
+    #
+    # E.g. {:primary => :place}.
+    attr_reader :type
+
+    # Public: The Array of String category hierarchy.
+    #
+    # E.g. ["Food and Drink", "Restaurants"].
+    attr_reader :category_hierarchy
+
+    # Public: The String Category ID.
+    #
+    # E.g. "13005000".
+    attr_reader :category_id
+
+    # Public: The String ID of a posted transaction's associated
+    # pending transaction - where applicable.
+    attr_reader :pending_transaction_id
+
+    # Public: Initialize a Transaction instance.
+    #
+    # fields - The Hash with fields.
+    def initialize(fields)
+      @id = fields['_id']
+      @account_id = fields['_account']
+
+      @date = fields['date'] && Date.parse(fields['date'])
+      @amount = fields['amount']
+      @name = fields['name']
+      @meta = Plaid.symbolize_hash(fields['meta'])
+      @location = (@meta && @meta[:location]) || {}
+      @pending = fields['pending']
+      @pending_transaction_id = fields['_pendingTransaction']
+      @score = Plaid.symbolize_hash(fields['score'])
+
+      @type = Plaid.symbolize_hash(fields['type'], values: true)
+      @category_hierarchy = fields['category']
+      @category_id = fields['category_id']
+    end
+
+    # Public: Detect if the transaction is pending or unsettled.
+    #
+    # Returns true if it is.
+    def pending?
+      pending
+    end
+
+    # Public: Get a String representation of the transaction.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::Transaction id=#{id.inspect}, account_id=#{id.inspect}, " \
+      "date=#{date}, amount=#{amount.inspect}, name=#{name.inspect}, " \
+      "pending=#{pending.inspect}>"
+    end
+
+    # Public: Get a String representation of the transaction.
+    #
+    # Returns a String.
+    alias to_s inspect
+  end
+end

data/lib/plaid/user.rb

@@ -0,0 +1,430 @@
+require_relative 'account'
+
+module Plaid
+  # Public: A class which encapsulates the authenticated user for all Plaid
+  # products.
+  class User
+    # Public: The access token for authenticated user.
+    attr_reader :access_token
+
+    # Public: The current product. Provides a context for #update and #delete
+    # calls. See Plaid::PRODUCTS.
+    attr_reader :product
+
+    # Public: The Array of Account instances providing accounts information
+    # for the user.
+    attr_reader :accounts
+
+    # Public: The Array of Transactions provided by initial call to User.create.
+    #
+    # If the :login_only option of User.create is set to false, the initial
+    # 30-day transactional data are returned during the API call. This attribute
+    # contains them.
+    attr_reader :initial_transactions
+
+    # Public: The Symbol MFA type to be used (or nil, if no MFA required).
+    #
+    # E.g. :questions, :list, or :device.
+    attr_reader :mfa_type
+
+    # Public: The MFA data (Hash or Array of Hash) or nil, if no MFA required.
+    #
+    # E.g. [{ question: "What was the name of your first pet?" }]
+    # or
+    # [{ mask: 't..t@plaid.com', type: 'email' },
+    #  { mask: 'xxx-xxx-5309',   type: 'phone' }]
+    # or
+    # { message: 'Code sent to xxx-xxx-5309' }
+    attr_reader :mfa
+
+    # Internal: The Plaid::Client instance used to make queries.
+    attr_reader :client
+
+    # Public: Create (add) a user.
+    #
+    # product     - The Symbol product name you are adding the user to, one of
+    #               Plaid::PRODUCTS (e.g. :info, :connect, etc.).
+    # institution - The String/Symbol financial institution type that you
+    #               want to access (e.g. :wells).
+    # username    - The String username associated with the financial
+    #               institution.
+    # password    - The String password associated with the financial
+    #               institution.
+    # pin         - The String PIN number associated with the financial
+    #               institution (default: nil).
+    # options     - the Hash options (default: {}):
+    #               :list       - The Boolean flag which would request the
+    #                             available send methods if the institution
+    #                             requires code-based MFA credential (default:
+    #                             false).
+    #               :webhook    - The String webhook URL. Used with :connect,
+    #                             :income, and :risk products (default: nil).
+    #               :pending    - The Boolean flag requesting to return
+    #                             pending transactions. Used with :connect
+    #                             product (default: false).
+    #               :login_only - The Boolean option valid for initial
+    #                             authentication only. If set to false, the
+    #                             initial request will return transaction data
+    #                             based on the start_date and end_date.
+    #               :start_date - The start Date from which to return
+    #                             transactions (default: 30 days ago).
+    #               :end_date   - The end Date to which transactions
+    #                             will be collected (default: today).
+    # client      - The Plaid::Client instance used to connect to the API
+    #               (default is to use global Plaid client - Plaid.client).
+    #
+    # Returns a Plaid::User instance.
+    def self.create(product, institution, username, password,
+                    pin: nil, options: nil, client: nil)
+      check_product product
+
+      payload = { username: username, password: password,
+                  type: institution.to_s }
+      payload[:pin] = pin if pin
+      payload[:options] = MultiJson.dump(options) if options
+
+      conn = Connector.new(product, auth: true, client: client)
+      resp = conn.post(payload)
+
+      new product, response: resp, mfa: conn.mfa?, client: client
+    end
+
+    # Public: Get User instance in case user access token is known.
+    #
+    # No requests are made, but the returned User instance is ready to be
+    # used.
+    #
+    # product - The Symbol product name you want to use, one of
+    #           Plaid::PRODUCTS (e.g. :info, :connect, etc.).
+    # token   - The String access token for the user.
+    # client  - The Plaid::Client instance used to connect to the API
+    #           (default is to use global Plaid client - Plaid.client).
+    #
+    # Returns a Plaid::User instance.
+    def self.load(product, token, client: nil)
+      new check_product(product), access_token: token, client: client
+    end
+
+    # Public: Exchange a Link public_token for an API access_token.
+    #
+    # public_token - The String Link public_token.
+    # account_id   - The String account ID.
+    # product      - The Symbol product name (default: :connect).
+    # client       - The Plaid::Client instance used to connect to the API
+    #                (default is to use global Plaid client - Plaid.client).
+    #
+    # Returns a new User with access token obtained from Plaid and default
+    # product set to product.
+    def self.exchange_token(public_token, account_id = nil,
+                            product: :connect, client: nil)
+      check_product product
+
+      payload = { public_token: public_token }
+      payload[:account_id] = account_id if account_id
+
+      response = Connector.new(:exchange_token, auth: true, client: client)
+                          .post(payload)
+      new product, response: response, client: client
+    end
+
+    # Internal: Initialize a User instance.
+    #
+    # product      - The Symbol product name.
+    # access_token - The String access token obtained from Plaid.
+    # response     - The Hash response body to parse.
+    # mfa          - The Boolean flag indicating that response body
+    #              - contains an MFA response.
+    # client       - The Plaid::Client instance used to connect to the API
+    #                (default is to use global Plaid client - Plaid.client).
+    def initialize(product, access_token: nil, response: nil, mfa: nil,
+                   client: nil)
+      @product = product
+      @client = client
+      @access_token = access_token if access_token
+      @mfa_required = mfa
+      @accounts = @initial_transactions = @info = @risk = @income = nil
+
+      parse_response(response) if response
+    end
+
+    # Public: Find out if MFA is required based on last request.
+    #
+    # After calling e.g. User.create you might need to make an additional
+    # authorization step if MFA is required by the financial institution.
+    #
+    # Returns true if this step is needed, a falsey value otherwise.
+    def mfa?
+      @mfa_required
+    end
+
+    # Public: Submit MFA information.
+    #
+    # info        - The String with MFA information (default: nil).
+    # send_method - The Hash with code send method information.
+    #               E.g. { type: 'phone' } or { mask: '123-...-4321' }.
+    #               Default is first available email.
+    #
+    # Returns true if whole MFA process is completed, false otherwise.
+    def mfa_step(info = nil, send_method: nil)
+      payload = { access_token: access_token }
+      payload[:mfa] = info if info
+      payload[:send_method] = MultiJson.dump(send_method) if send_method
+
+      conn = Connector.new(product, :step, auth: true)
+      response = conn.post(payload)
+
+      @mfa_required = conn.mfa?
+      parse_response(response)
+    end
+
+    # Public: Get transactions.
+    #
+    # Does a /connect/get call. Updates self.accounts with latest information.
+    #
+    # pending    - the Boolean flag requesting to return pending transactions.
+    # account_id - the String Account ID (default: nil). If this argument is
+    #              present, only transactions for given account will be
+    #              requested.
+    # start_date - The start Date (inclusive).
+    # end_date   - The end Date (inclusive).
+    #
+    # Returns an Array of Transaction records.
+    def transactions(pending: false, account_id: nil,
+                     start_date: nil, end_date: nil)
+      options = { pending: pending }
+      options[:account] = account_id if account_id
+      options[:gte] = start_date.to_s if start_date
+      options[:lte] = end_date.to_s if end_date
+
+      response = Connector.new(:connect, :get, auth: true, client: client)
+                          .post(access_token: access_token,
+                                options: MultiJson.dump(options))
+      update_accounts(response)
+      build_objects(response['transactions'], Transaction)
+    end
+
+    # Public: Update user credentials.
+    #
+    # Updates the user credentials for the current product. See
+    # User#for_product.
+    #
+    # username    - The String username associated with the financial
+    #               institution.
+    # password    - The String password associated with the financial
+    #               institution.
+    # pin         - The String PIN number associated with the financial
+    #               institution (default: nil).
+    #
+    # Returns self.
+    def update(username, password, pin = nil)
+      payload = {
+        access_token: access_token,
+        username: username,
+        password: password
+      }
+
+      payload[:pin] = pin if pin
+
+      parse_response(Connector.new(product, auth: true, client: client)
+                              .patch(payload))
+
+      self
+    end
+
+    # Public: Delete the user.
+    #
+    # Makes a delete request and freezes self to prevent further modifications
+    # to the object.
+    #
+    # Returns self.
+    def delete
+      Connector.new(product, auth: true, client: client)
+               .delete(access_token: access_token)
+
+      freeze
+    end
+
+    # Public: Upgrade the user.
+    #
+    # For an existing user that has been added via any of products (:connect,
+    # :auth, :income, :info, or :risk), you can upgrade that user to have
+    # functionality with other products.
+    #
+    # Does a POST /upgrade request.
+    #
+    # See also User#for_product.
+    #
+    # product - The Symbol product name you are upgrading the user to, one of
+    #           Plaid::PRODUCTS.
+    #
+    # Returns another User record with the same access token, but tied to the
+    # new product.
+    def upgrade(product)
+      payload = { access_token: access_token, upgrade_to: product.to_s }
+      response = Connector.new(:upgrade, auth: true, client: client)
+                          .post(payload)
+
+      User.new product, response: response
+    end
+
+    # Public: Get the current user tied to another product.
+    #
+    # No API request is made, just the current product is changed.
+    #
+    # product - The Symbol product you are selecting, one of Plaid::PRODUCTS.
+    #
+    # See also User#upgrade.
+    #
+    # Returns a new User instance.
+    def for_product(product)
+      User.load product, access_token, client: client
+    end
+
+    # Public: Get auth information for the user (routing numbers for accounts).
+    #
+    # Not only this method returns the new data, but it updates self.accounts as
+    # well.
+    #
+    # The method does a POST /auth/get request.
+    #
+    # sync - The Boolean flag which, if true, causes auth information to be
+    #        rerequested from the server. Otherwise cached version is returned,
+    #        if it exists.
+    #
+    # Returns an Array of Account with numbers baked in.
+    def auth(sync: false)
+      if sync || !@accounts || !@accounts[0] || !@accounts[0].numbers
+        response = Connector.new(:auth, :get, auth: true, client: client)
+                            .post(access_token: access_token)
+
+        update_accounts(response)
+      end
+
+      accounts
+    end
+
+    # Public: Get info for the user.
+    #
+    # Does a POST /info/get request.
+    #
+    # sync - The Boolean flag which, if true, causes information to be
+    #        rerequested from the server. Otherwise cached version is returned,
+    #        if it exists.
+    #
+    # Returns a Plaid::Info instance.
+    def info(sync: false)
+      if sync || !@info
+        parse_response(Connector.new(:info, :get, auth: true, client: client)
+                                .post(access_token: access_token))
+      end
+
+      @info
+    end
+
+    # Public: Get income information for the user.
+    #
+    # Does a POST /income/get request.
+    #
+    # sync - The Boolean flag which, if true, causes income information to be
+    #        rerequested from the server. Otherwise cached version is returned,
+    #        if it exists.
+    #
+    # Returns a Plaid::Income instance.
+    def income(sync: false)
+      if sync || !@income
+        parse_response(Connector.new(:income, :get, auth: true, client: client)
+                                .post(access_token: access_token))
+      end
+
+      @income
+    end
+
+    # Public: Get risk data for the user's accounts.
+    #
+    # Does a POST /risk/get request.
+    #
+    # sync - The Boolean flag which, if true, causes risk information to be
+    #        rerequested from the server. Otherwise cached version is returned,
+    #        if it exists.
+    #
+    # Returns an Array of accounts with risk attribute set.
+    def risk(sync: false)
+      if sync || !@accounts || !@accounts[0] || !@accounts[0].risk
+        parse_response(Connector.new(:risk, :get, auth: true, client: client)
+                                .post(access_token: access_token))
+      end
+
+      @accounts
+    end
+
+    # Public: Get current account balance.
+    #
+    # Does a POST /balance request.
+    #
+    # Returns an Array of Plaid::Account.
+    def balance
+      response = Connector.new(:balance, auth: true, client: client)
+                          .post(access_token: access_token)
+
+      update_accounts(response)
+    end
+
+    private
+
+    # Internal: Validate the product name.
+    def self.check_product(product)
+      if Plaid::PRODUCTS.include?(product)
+        product
+      else
+        raise ArgumentError, "product (#{product.inspect}) must be one of " \
+                             "Plaid products (#{Plaid::PRODUCTS.inspect})"
+      end
+    end
+
+    private_class_method :check_product
+
+    # Internal: Set up attributes from Add User response.
+    def parse_response(response)
+      @access_token = response['access_token']
+      return parse_mfa_response(response) if mfa?
+
+      @mfa_type = @mfa = nil
+
+      update_accounts(response) if response['accounts']
+
+      if (trans = response['transactions'])
+        @initial_transactions = build_objects(trans, Transaction)
+      end
+
+      if (income = response['income'])
+        @income = Plaid::Income.new(income)
+      end
+
+      return unless (i = response['info'])
+      @info = Plaid::Info.new(i)
+    end
+
+    # Internal: Parse an MFA response
+    def parse_mfa_response(response)
+      @mfa_type = response['type'].to_sym
+      @mfa = Plaid.symbolize_hash(response['mfa'])
+    end
+
+    # Internal: Convert an array of data into an array of objects, encapsulating
+    # that data.
+    def build_objects(data, klass)
+      data ? data.map { |element| klass.new(element) } : []
+    end
+
+    # Internal: Update account data from the response.
+    def update_accounts(response)
+      new_accounts = build_objects(response['accounts'], Account)
+
+      if @accounts
+        Account.merge @accounts, new_accounts
+      else
+        @accounts = new_accounts
+      end
+    end
+  end
+end