plaid 1.4.3 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8580b88cd18ddfec32569abeef15135a37209049
-  data.tar.gz: 4b23dd43db4013e15a0d78777e7b751c2918c5bc
+  metadata.gz: 3b8b2f76594f65f973077ad6cde5d686bf214e0f
+  data.tar.gz: f776703e98bdd32da28c1451c9686490eca81767
 SHA512:
-  metadata.gz: df9a31e7100ca2418f0ebdf469ea42630a8c3d0ed29fc1373efe5790ad2da25aebbeb2e39f10d4abd4ae892d787678026e704cbbac60bdd84d08777a95c3ea9c
-  data.tar.gz: 00cc4839fe0524bfbe90d15121bbfee0537ab0c4dbfb73c5c6c8334d32e3b808f6c88efeea46d9029739a21b23a06b3830fb8a0add17360874b538b8ef35d618
+  metadata.gz: e9518764f519d2f8cc5535e50a16aed204032cb39e9e700c77c58782548dce249af9a76ab306aaa824023db281c3859449d4c47fb576c1da5abd8fc24a6c926c
+  data.tar.gz: 0f378b719b774502fb0f88dda4b82c66e62921e7d16b58ffb01300d1a2e6e8d524231b4b98f3ca8c26bdc11c0937636300444d62e0392887ed6e0320b0647077

data/README.md

@@ -6,7 +6,7 @@ Ruby bindings for the Plaid API
 
 This version is a beta version that contains failing tests for the new 'info' endpoint. While these have been tested individually on real accounts the tests here will fail with the test accounts supplied. These will be updated soon with test credentials.
 
-Latest stable version: **1.4.3**
+Latest stable version: **1.5.0**
 
 This version removes the need to use 'type' in each additional call.
 
@@ -32,6 +32,7 @@ Or install it system wide as:
 
 Please read the great documentation at http://plaid.com/docs/ for more information.
 
+### Configuring Plaid
 Configure the gem with your customer id, secret key, and the environment path you would like to use.
 
 ```ruby
@@ -39,15 +40,78 @@ Plaid.config do |p|
     p.customer_id = 'Plaid provided customer ID here'
     p.secret = 'Plaid provided secret key here'
     p.environment_location = 'URL for the development or production environment'
+    # i.e. 'https://tartan.plaid.com/' for development, or
+    # 'https://api.plaid.com/' for production
 end
 ```
 
+### Creating a new Plaid User
 Authenticate a user to your desired level of api access (auth / connect).
 
 ```ruby
 user = Plaid.add_user('auth','plaid_test','plaid_good','wells')
 ```
 
+If the authentication requires a pin, you can pass it in as the fifth argument:
+
+```ruby
+user = Plaid.add_user('auth', 'plaid_test', 'plaid_good', 'usaa', '1234')
+```
+
+To add options such as `login_only` or `webhooks`, use the sixth argument:
+
+```ruby
+user = Plaid.add_user('auth','plaid_test','plaid_good','wells', nil, { login_only: true, webhooks: 'https://example.org/callbacks/plaid')
+```
+
+### Restoring a Plaid User using an access token
+
+```ruby
+user = Plaid.set_user('access_token')
+```
+
+```ruby
+user = Plaid.set_user('access_token', 'wells')
+```
+
+### Exchanging a Link public_token for a Plaid access_token
+
+```ruby
+Plaid.config do |p|
+    p.customer_id = 'test_id'
+    p.secret = 'test_secret'
+    p.environment_location = 'https://tartan.plaid.com'
+end
+
+# Exchange a Link public_token for a Plaid access_token
+exchangeTokenResponse = Plaid.exchange_token('test,chase,connected')
+
+# Use the API access_token to initialize a user
+# Note: This example assumes you are using Link with the "auth" product
+user = Plaid.set_user(exchangeTokenResponse.access_token, ['auth'])
+
+# Retrieve the user's accounts
+user.get('auth')
+
+# Print the name of each account
+user.accounts.each { |account| print account.meta['name'] + "\n"}
+```
+
+## Semantic Versioning
+
+Methods marked with `API: public` are officially supported by the gem maintainers. Since
+we are using semantic versioning (http://semver.org/spec/v2.0.0.html), the maintainers are
+commited to backwards-compatibility support for these API calls when we update the Minor
+version. So for example, going from version 1.4.x to 1.5.x will not change these public
+API calls.
+
+However, we may change these method signatures or even the gem architecture when updating
+the Major number. For example, we have some breaking changes in mind with version 2.0
+
+Methods marked with `API: semi-private` are used internally for consistency. While it is
+possible to monkey-patch against them for your own use, the maintainers make no gaurantees
+on backwards compatibility.
+
 ## Learn More
 
 Learn about the full functionality of the library on our [Wiki](https://github.com/plaid/plaid-ruby/wiki)
@@ -56,4 +120,4 @@ Learn about the full functionality of the library on our [Wiki](https://github.c
 
 We highly encourage helping out with the gem. Either adding more tests, building new helper classes, fixing bugs, or anything to increase overall quality.
 
-Learn more about best practices, submitting a pull request, and rules for the build on our [Wiki](https://github.com/plaid/plaid-ruby/wiki/Contribute!)
+Learn more about best practices, submitting a pull request, and rules for the build on our [Wiki](https://github.com/plaid/plaid-ruby/wiki/Contribute!)

data/lib/plaid/config.rb

@@ -1,13 +1,19 @@
 module Plaid
   module Configure
-    attr_writer :customer_id, :secret, :environment_location
+    attr_accessor :customer_id, :secret, :environment_location
 
     KEYS = [:customer_id, :secret, :environment_location]
 
     def config
       yield self
+
+      # Add trailing slash to api url if it is not present
+      if self.environment_location[-1] != '/'
+        self.environment_location += '/'
+      end
+
       self
     end
 
   end
-end
+end

data/lib/plaid/connection.rb

@@ -0,0 +1,121 @@
+require 'net/http'
+require 'json'
+require 'uri'
+module Plaid
+  class Connection
+    class << self
+      # API: semi-private
+      def post(path, options = {})
+        uri = build_uri(path)
+        options.merge!(client_id: Plaid.customer_id, secret: Plaid.secret)
+        res = Net::HTTP.post_form(uri,options)
+        parse_response(res)
+      end
+
+      # API: semi-private
+      def get(path, id = nil)
+        uri = build_uri(path,id)
+        res = Net::HTTP.get(uri)
+        parse_get_response(res)
+      end
+
+      # API: semi-private
+      def secure_get(path, access_token, options = {})
+        uri = build_uri(path)
+        options.merge!({access_token:access_token})
+        req = Net::HTTP::Get.new(uri)
+        req.body = URI.encode_www_form(options) if options
+        req.content_type = 'multipart/form-data'
+        res = Net::HTTP.start(uri.hostname, uri.port, :use_ssl => uri.scheme == 'https') { |http| http.request(req) }
+        parse_response(res)
+      end
+
+      # API: semi-private
+      def patch(path, options = {})
+        uri = build_uri(path)
+        options.merge!(client_id: Plaid.customer_id, secret: Plaid.secret)
+        req = Net::HTTP::Patch.new(uri)
+        req.body = URI.encode_www_form(options) if options
+        req.content_type = 'multipart/form-data'
+        res = Net::HTTP.start(uri.hostname, uri.port, :use_ssl => uri.scheme == 'https') { |http| http.request(req) }
+        parse_response(res)
+      end
+
+      # API: semi-private
+      def delete(path, options = {})
+        uri = build_uri(path)
+        options.merge!(client_id: Plaid.customer_id, secret: Plaid.secret)
+        req = Net::HTTP::Delete.new(uri)
+        req.body = URI.encode_www_form(options) if options
+        req.content_type = 'multipart/form-data'
+        Net::HTTP.start(uri.hostname, uri.port, :use_ssl => uri.scheme == 'https') { |http| http.request(req) }
+      end
+
+      # API: semi-private
+      # TODO: Refactor these to use symbols instead of strings
+      def error_handler(err, res = nil)
+        case err
+        when 'Bad Request'
+          puts res.body
+          raise 'The request was malformed. Did you check the API docs?'
+        when 'Unauthorized'
+          raise 'Access denied: Try using the correct credentials.'
+        when 'Corrupted token'
+          raise 'It appears that the access token has been corrupted'
+        else
+          raise err
+        end
+      end
+
+      protected
+
+      # API: semi-private
+      def build_uri(path, option = nil)
+        path = path + '/' + option unless option.nil?
+        URI.parse(Plaid.environment_location + path)
+      end
+
+      private
+
+      def parse_response(res)
+        body = JSON.parse(res.body)
+        case res.code.delete('.').to_i
+        when 200 then body
+        when 201 then { msg: 'Requires further authentication', body: body}
+        when 400 then error_handler('Bad Request',res)
+        when 401
+          case body['code']
+          when 1108 then error_handler('Institution not supported', res)
+          when 1105 then error_handler('Corrupted token', res)
+          when 1106 then error_handler('Corrupted public_token', res)
+          when 1107 then error_handler('Missing public_token', res)
+          when 1501 then error_handler('Not Found', res)
+          else error_handler('Unauthorized',res)
+          end
+        when 402
+          return {msg: 'User account is locked', body: body} if body['code'] == 1205
+          error_handler('Request Failed', res)
+        when 404
+          error_handler('Not Found',res)
+        else
+          error_handler('Server Error',res)
+        end
+      end
+
+      def parse_get_response(res)
+        body = JSON.parse(res)
+        return body if body.kind_of?(Array)
+
+        case body['code']
+        when nil
+          body
+        when 1301, 1401, 1501, 1601
+          error_handler('Not Found',body)
+        else
+          body
+        end
+      end
+
+    end
+  end
+end

data/lib/plaid/models/account.rb

@@ -0,0 +1,24 @@
+module Plaid
+  class Account
+    attr_accessor :available_balance, :current_balance, :institution_type, :meta, :transactions, :numbers, :name, :id, :type, :subtype
+
+    def initialize(hash)
+      @id   = hash['_id']
+      @name = hash['name']
+      @type = hash['type']
+      @meta = hash['meta']
+      @institution_type  = hash['institution_type']
+
+      if hash['balance']
+        @available_balance = hash['balance']['available']
+        @current_balance   = hash['balance']['current']
+      end
+
+      # Depository account only, "checkings" or "savings"
+      # Available on live data, but not on the test data
+      @subtype = hash['subtype']
+
+      @numbers = hash['numbers'] ? hash['numbers'] : 'Upgrade user to access routing information for this account'
+    end
+  end
+end

data/lib/plaid/models/category.rb

@@ -0,0 +1,17 @@
+module Plaid
+  class Category
+    attr_accessor :type, :hierarchy, :id
+
+    def initialize(fields = {})
+      @type = fields['type']
+      @hierarchy = fields['hierarchy']
+      @id = fields['id']
+    end
+
+    # API: semi-private
+    # This method takes an array returned from the API and instantiates all of the categories
+    def self.all(res)
+      res.map { |cat| new(cat) }
+    end
+  end
+end

data/lib/plaid/models/exchange_token_response.rb

@@ -0,0 +1,9 @@
+module Plaid
+  class ExchangeTokenResponse
+    attr_accessor :access_token
+
+    def initialize(fields = {})
+      @access_token = fields['access_token']
+    end
+  end
+end

data/lib/plaid/models/info.rb

@@ -0,0 +1,12 @@
+module Plaid
+  class Information
+    attr_accessor :names, :emails, :phone_numbers, :addresses
+
+    def initialize(hash)
+      @names = hash['names']
+      @emails = hash['emails']
+      @phone_numbers = hash['phone_numbers']
+      @addresses = hash['addresses']
+    end
+  end
+end

data/lib/plaid/models/institution.rb

@@ -0,0 +1,20 @@
+module Plaid
+  class Institution
+    attr_accessor :id, :name, :type, :has_mfa, :mfa
+
+    def initialize(fields = {})
+      @id = fields['id']
+      @name = fields['name']
+      @type = fields['type']
+      @has_mfa = fields['has_mfa']
+      @mfa = fields['mfa']
+    end
+
+    # API: semi-private
+    # This method takes an array returned from the API and instantiates all of the institutions
+    def self.all(res)
+      res.map { |inst| new(inst) }
+    end
+  end
+end
+

data/lib/plaid/models/transaction.rb

@@ -0,0 +1,23 @@
+module Plaid
+  class Transaction
+    attr_accessor :id, :account, :date, :amount, :name, :meta, :location, :pending, :score, :cat, :type, :category, :category_id
+
+    def initialize(fields = {})
+      @id = fields['_id']
+      @account = fields['_account']
+      @date = fields['date']
+      @amount = fields['amount']
+      @name = fields['name']
+      @location = fields['meta'].nil? ? {} : fields['meta']['location']
+      @pending = fields['pending']
+      @score = fields['score']
+      @cat = Category.new({ 'id' => fields['category_id'], 'hierarchy' => fields['category'], 'type' => fields['type'] })
+
+      # Here for backwards compatibility only.
+      @type = fields['type']
+      @category = fields['category']
+      @category_id = fields['category_id']
+      @meta = fields['meta']
+    end
+  end
+end

data/lib/plaid/models/user.rb

@@ -0,0 +1,192 @@
+require_relative 'account'
+require_relative 'transaction'
+require_relative 'info'
+require 'json'
+
+module Plaid
+  class User
+    attr_accessor :accounts, :transactions, :access_token, :type, :permissions, :api_res, :pending_mfa_questions, :info, :information
+
+    # API: public
+    # Use this method to select the MFA method
+    def select_mfa_method(selection, type=nil)
+      type = self.type if type.nil?
+      auth_path = self.permissions.last + '/step'
+      res = Connection.post(auth_path, { options: { send_method: selection }.to_json, access_token: self.access_token, type: type })
+      update(res, self.permissions.last)
+    end
+
+    # API: public
+    # Use this method to send back the MFA code or answer
+    def mfa_authentication(auth, type = nil)
+      type = self.type if type.nil?
+      auth_path = self.permissions.last + '/step'
+      res = Connection.post(auth_path, { mfa: auth, access_token: self.access_token, type: type })
+      self.accounts = []
+      self.transactions = []
+      update(res)
+    end
+
+    # API: public
+    # Use this method to find out API levels available for this user
+    def permit?(auth_level)
+      self.permissions.include? auth_level
+    end
+
+    # API: public
+    # Use this method to upgrade a user to another api level
+    def upgrade(api_level=nil)
+      if api_level.nil?
+        api_level = 'auth' unless self.permit? 'auth'
+        api_level = 'connect' unless self.permit? 'connect'
+      end
+      res = Connection.post('upgrade', { access_token: self.access_token, upgrade_to: api_level })
+
+      # Reset accounts and transaction
+      self.accounts = []
+      self.transactions = []
+      update(res)
+    end
+
+    # API: public
+    # Use this method to delete a user from the Plaid API
+    def delete_user
+      Connection.delete('info', { access_token: self.access_token })
+    end
+
+    ### Internal build methods
+    def initialize
+      self.accounts = []
+      self.transactions = []
+      self.permissions = []
+      self.access_token = ''
+      self.api_res = ''
+      self.info = {}
+    end
+
+    # API: semi-private
+    # This class method instantiates a new Account object and updates it with the results
+    # from the API
+    def self.build(res, api_level = nil)
+      self.new.update(res, api_level)
+    end
+
+    # API: semi-private
+    # This method updates Account with the results returned from the API
+    def update(res, api_level = nil)
+      self.permit! api_level
+
+      if res[:msg].nil?
+        populate_user!(res)
+        clean_up_user!
+      else
+        set_mfa_request!(res)
+      end
+
+      return self
+    end
+
+    # Internal helper methods
+
+    # API: semi-private
+    # Internal helper method to set the available API levels
+    def permit!(api_level)
+      return if api_level.nil? || self.permit?(api_level)
+      self.permissions << api_level
+    end
+
+    # API: semi-private
+    # Gets auth, connect, or info of the user
+    # TODO: (2.0) auth_level should be symbols instead of string
+    def get(auth_level, options = {})
+      return false unless self.permit? auth_level
+      case auth_level
+      when 'auth'
+        update(Connection.post('auth/get', access_token: self.access_token))
+      when 'connect'
+        payload = { access_token: self.access_token }.merge(options)
+        update(Connection.post('connect/get', payload))
+      when 'info'
+        update(Connection.secure_get('info', self.access_token))
+      else
+        raise "Invalid auth level: #{auth_level}"
+      end
+    end
+
+    # API: semi-private
+    def get_auth
+      get('auth')
+    end
+
+    # API: semi-private
+    def get_connect(options={})
+      get('connect', options)
+    end
+
+    # API: semi-private
+    def get_info
+      get('info')
+    end
+
+    # API: semi-private
+    # Helper method to update user information
+    # Requires 'info' api level
+    def update_info(username,pass,pin=nil)
+      return false unless self.permit? 'info'
+
+      payload = { username: username, password: pass, access_token: self.access_token }
+      payload.merge!(pin: pin) if pin
+      update(Plaid.patch('info', payload))
+    end
+
+    # API: semi-private
+    # Helper method to update user balance
+    def update_balance
+      update(Connection.post('balance', { access_token: self.access_token }))
+    end
+
+    private
+
+    def clean_up_user!
+      self.accounts.select! { |c| c.instance_of? Account }
+    end
+
+    def set_mfa_request!(res)
+      self.access_token = res[:body]['access_token']
+      self.pending_mfa_questions = res[:body]
+      self.api_res = res[:msg]
+    end
+
+    def populate_user!(res)
+      res['accounts'].each do |account|
+        if self.accounts.any? { |h| h == account['_id'] }
+          owned_account = self.accounts.find { |h| h == account['_id'] }
+          owned_account.new(account)
+        else
+          self.accounts << Account.new(account)
+        end
+      end if res['accounts']
+
+      res['transactions'].each do |transaction|
+        if self.transactions.any? { |t| t == transaction['_id'] }
+          owned_transaction = self.transactions.find { |h| h == transaction['_id'] }
+          owned_transaction.new(transaction)
+        else
+          self.transactions << Transaction.new(transaction)
+        end
+      end if res['transactions']
+
+      self.pending_mfa_questions = ''
+      self.information = Information.new(res['info']) if res['info']
+      self.api_res = 'success'
+
+      # TODO: Remove the following line when upgrading to V-2
+      self.info.merge!(res['info']) if res['info']
+      # End TODO
+
+      self.access_token = res['access_token'].split[0]
+      self.type = res['access_token'].split[1]
+    end
+
+  end
+end

data/lib/plaid/version.rb

@@ -1,3 +1,3 @@
 module Plaid
-  VERSION = '1.4.3'
+  VERSION = '1.5.0'
 end