plaid 1.7.1 → 2.0.0.alpha

data/UPGRADING.md

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

@@ -1,100 +1,63 @@
 require 'plaid/version'
-require 'plaid/config'
 require 'plaid/errors'
-
-require 'plaid/models/user'
-require 'plaid/models/institution'
-require 'plaid/models/category'
-require 'plaid/models/exchange_token_response'
-
-require 'json'
-
+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 'uri'
+
+# Public: The Plaid namespace.
 module Plaid
-  autoload :Connection, 'plaid/connection'
+  # Public: Available Plaid products.
+  PRODUCTS = %i(connect auth info income risk).freeze
 
-  class << self
-    # Configures the gem with the public, private, and environment vars
-    include Configure
+  class <<self
+    # Public: The default Client.
+    attr_accessor :client
 
-    # API: public
-    # Use this to create a new Plaid user
-    # Required parameters:
-    #   api_level, username, password, type
-    # TODO: Rename this to something more descriptive for 2.0, such as 'create_user`
-    def add_user(api_level, username, password, type, pin = nil, options = nil)
-      payload = { username: username, password: password, type: type }
-
-      payload[:pin]     = pin if pin
-      payload[:options] = options.is_a?(Hash) ? JSON.generate(options) : options if options
-
-      res = Connection.post(api_level, payload)
-      User.build(res, api_level)
-    end
-
-    # API: public
-    # Exchange a Plaid Link public_token for a Plaid access_token
-    # Required parameters:
-    #   public_token
-    #   account_id (optional)
-    def exchange_token(public_token, account_id = nil)
-      payload = { public_token: public_token }
-      # include the account id, if set
-      payload[:account_id] = account_id if account_id
-
-      res = Connection.post('exchange_token', payload)
-      ExchangeTokenResponse.new(res)
-    end
-
-    # API: public
-    # Use this to restore a user from Plaid based upon the access token
-    # TODO: Rename this to something more descriptive for 2.0, such as 'get_user'
-    def set_user(token, api_levels=[], institution_type=nil)
-      _user = User.new
-      _user.access_token = fully_qualified_token(token, institution_type)
-      _user.permissions = api_levels
-      api_levels.each { |l| _user.get(l) }
-      _user
-    end
+    # 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
 
-    # API: public
-    # Given an access code and query options, use this to get a dataset of
-    # transactions and accounts for # a given user. See /connect/get endpoint
+    # Public: A helper function to ease configuration.
     #
-    # Returns a User object with accounts and transactions within
-    # the date range given
-    # Examples:
-    #   Plaid.transactions 'test_wells', account: 'QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK'
-    def transactions(token, options = {})
-      _user = User.new
-      _user.access_token = token
-      _user.permit! 'connect'
-
-      # TODO: For 2.0, submit all data as JSON
-      options = JSON.generate(options) if options.kind_of?(Hash)
-
-      _user.get_connect(options: options)
-      _user
-    end
-
-    # API: public
-    # Returns the fully-qualified token based upon type
-    # Note: Don't see this documented in the Plaid API docs, need to investigate this
-    def fully_qualified_token(token, institution_type)
-      institution_type.nil? ? token : token + '_' + institution_type
-    end
-
-    # API: public
-    # Builds an institution object and returns when the institution details exist
-    def institution(id = nil)
-      res = Connection.get('institutions', id)
-      id.nil? ? Institution.all(res) : Institution.new(res)
+    # 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
 
-    # API: public
-    # Builds an category object and returns when the category details exist
-    def category(id = nil)
-      res = Connection.get('categories', id)
-      id.nil? ? Category.all(res) : Category.new(res)
+    # 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,67 @@
+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, :api), or a full String URL like
+    #       'https://tartan.plaid.com'.
+    def env=(env)
+      case env
+      when :tartan, :api
+        @env = "https://#{env}.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, :api), or a ' \
+                               "full URL, like 'https://tartan.plaid.com'"
+        end
+      else
+        raise ArgumentError, 'Invalid value for Plaid::Client.env' \
+                             " (#{env.inspect}): " \
+                             'must be :tartan, :api, or a full URL, ' \
+                             "e.g. 'https://tartan.plaid.com'"
+      end
+    end
+
+    # Public: Construct a Client instance.
+    #
+    # env       - The Symbol (:tartan, :api), 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