plaid 1.4.3 → 1.5.0

data/lib/plaid.rb

@@ -1,54 +1,96 @@
 require 'plaid/version'
 require 'plaid/config'
-require 'plaid/util'
 
-require 'plaid/add_user'
-require 'plaid/user/user'
-require 'plaid/institution/institution'
-require 'plaid/category/category'
+require 'plaid/models/user'
+require 'plaid/models/institution'
+require 'plaid/models/category'
+require 'plaid/models/exchange_token_response'
+
+require 'json'
 
 module Plaid
+  autoload :Connection, 'plaid/connection'
+
   class << self
     # Configures the gem with the public, private, and environment vars
-    include Plaid::Configure
+    include Configure
+
+    # 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 }
 
-    # Include the utility classes used throughout the gem
-    include Plaid::Util
+      payload[:pin]     = pin if pin
+      payload[:options] = options.is_a?(Hash) ? JSON.generate(options) : options if options
 
-    # Includes the method to authenticate the user. Defined in auth.rb
-    include Plaid::AddUser
+      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
+    def exchange_token(public_token)
+      payload = { public_token: public_token }
 
-    # Builds the user object and returns on successful authentication
-    def user(res,api_level=nil)
-      @user = Plaid::User.new
-      @user.new(res,api_level)
+      res = Connection.post('exchange_token', payload)
+      ExchangeTokenResponse.new(res)
     end
 
-    def existing_user(token,api_level=[],type=nil)
-      @user = Plaid::User.new
-      @user.access_token = token
-      api_level.each { |i|
-        @user.permissions << i
-        @user.get_auth if i == 'auth'
-        @user.get_connect if i == 'connect'
-        @user.get_info if i == 'info'
-      } unless api_level.empty?
-      @user
+    # 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) }
+      return _user
     end
 
-    # Builds an institution object and returns when the institution details exist
-    def institution(id=nil)
-      @institution = Plaid::Institution.new
-      res = self.get('institutions',id)
-      id.nil? ? @institution.instantiate_all_institutions(res) : @institution.instantiate_one_institution(res)
+    # 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
+    #
+    # 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)
+      return _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
 
-    # Builds an institution object and returns when the category details exist
-    def category(id=nil)
-      @category = Plaid::Category.new
-      res = self.get('categories',id)
-      id.nil? ? @category.instantiate_all_categories(res) : @category.instantiate_one_category(res)
+    # 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)
     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)
+    end
   end
-end
+end

data/plaid.gemspec

@@ -21,4 +21,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~>3.1'
-end
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'pry-stack_explorer'
+end

data/spec/account_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper.rb'
+
+RSpec.describe Plaid::Account do
+  # API: semi-private
+  describe '.new' do
+    subject { Plaid::Account.new(results) }
+
+    def self.with_results(_results, &examples)
+      context "with results #{_results}" do
+        let(:results) { _results }
+        instance_eval(&examples)
+      end
+    end
+
+    with_results('name' => 'Name') do it { expect(subject.name).to eql('Name') } end
+    with_results('_id' =>  'ID')   do it { expect(subject.id).to   eql('ID') }   end
+    with_results('type' => 'Type') do it { expect(subject.type).to eql('Type') } end
+    with_results('type' => 'STyp') do it { expect(subject.type).to eql('STyp') } end
+    with_results('meta' => nil)    do it { expect(subject.meta).to be_nil }      end
+    with_results('meta' => {})     do it { expect(subject.meta).to eql({}) }     end
+
+    with_results('balance' => { 'available' => 100.00 } ) do it { expect(subject.available_balance).to eql(100.00) } end
+    with_results('balance' => { 'current'   => 200.00 } ) do it { expect(subject.current_balance).to   eql(200.00) } end
+
+    with_results('institution_type' => 'Type') do it { expect(subject.institution_type).to eql('Type') } end
+
+    with_results('numbers' => nil) do
+      it { expect(subject.numbers).to eql('Upgrade user to access routing information for this account') }
+    end
+
+    with_results('numbers' => {}) do
+      it { expect(subject.numbers).to eql({}) }
+    end
+  end
+end

data/spec/category_spec.rb

@@ -1,22 +1,13 @@
 require 'spec_helper.rb'
-# Category specs
-describe '#Category' do
-
-  before :all do
-    Plaid.config do |p|
-      p.customer_id = 'test_id'
-      p.secret = 'test_secret'
-      p.environment_location = 'https://tartan.plaid.com/'
-    end
-  end
 
+RSpec.describe Plaid::Category do
   context 'when a single category is found' do
-    category = Plaid.category('17001013')
-    it { expect(category.class).to eq (Plaid::Category) }
+    let(:category) { Plaid.category('17001013') }
+    it { expect(category).to be_kind_of(Plaid::Category) }
   end
 
   context 'when all categories are found' do
-    category = Plaid.category
+    let(:category) { Plaid.category }
     it { expect(category).to be_kind_of(Array)}
   end
 
@@ -24,4 +15,4 @@ describe '#Category' do
     it { expect { Plaid.category('dumb_cat') }.to raise_error }
   end
 
-end
+end

data/spec/config_spec.rb

@@ -1,40 +1,69 @@
-# Configuration specs - used in gem configuration
-describe '.config' do
-  context 'has valid dev keys' do
+require 'spec_helper.rb'
+
+RSpec.describe 'Plaid.config' do
+  around(:each) do |example|
+    old_customer_id          = Plaid.customer_id
+    old_secret               = Plaid.secret
+    old_environment_location = Plaid.environment_location
+
     Plaid.config do |p|
-      p.customer_id = 'test_id'
-      p.secret = 'test_secret'
-      p.environment_location = 'https://tartan.plaid.com/'
+      p.customer_id          = customer_id
+      p.secret               = secret
+      p.environment_location = environment_location
     end
-    res = Plaid.add_user('connect','plaid_test','plaid_good','wells')
-    it { expect(res).to be_instance_of Plaid::User }
-  end
 
-  context 'has valid production keys' do
+    example.run
+
     Plaid.config do |p|
-      p.customer_id = 'test_id'
-      p.secret = 'test_secret'
-      p.environment_location = 'https://api.plaid.com/'
+      p.customer_id          = old_customer_id
+      p.secret               = old_secret
+      p.environment_location = old_environment_location
     end
-    res = Plaid.add_user('connect','plaid_test','plaid_good','wells')
-    it { expect(res).to be_instance_of Plaid::User }
   end
 
-  context 'has invalid dev keys' do
-    Plaid.config do |p|
-      p.customer_id = 'test_id'
-      p.secret = 'test_bad'
-      p.environment_location = 'https://tartan.plaid.com/'
+  let(:customer_id) { 'test_id' }
+  let(:secret)      { 'test_secret' }
+  let(:dev_url)  { 'https://tartan.plaid.com/' }
+  let(:prod_url) { 'https://api.plaid.com/' }
+
+
+  let(:user) { Plaid.add_user('connect','plaid_test','plaid_good','wells') }
+
+  context ':environment_location' do
+    context 'with trailing slash' do
+      let(:environment_location) { 'http://example.org/' }
+      it 'should leave it as-is' do
+        expect(Plaid.environment_location).to eql(environment_location)
+      end
+    end
+
+    context 'without trailing slash' do
+      let(:environment_location) { 'http://example.org' }
+      it 'should add a trailing slash' do
+        expect(Plaid.environment_location).to eql(environment_location + '/')
+      end
     end
-    it { expect{Plaid.add_user('connect','plaid_bad','plaid_bad','wells')}.to raise_error }
+  end
+
+  context 'has valid dev keys' do
+    let(:environment_location) { dev_url }
+    it { expect(user).to be_instance_of Plaid::User }
+  end
+
+  context 'has valid production keys' do
+    let(:environment_location) { prod_url }
+    it { expect(user).to be_instance_of Plaid::User }
+  end
+
+  context 'has invalid dev keys' do
+    let(:secret) { 'test_bad' }
+    let(:environment_location) { dev_url }
+    it { expect { user }.to raise_error }
   end
 
   context 'has invalid production keys' do
-    Plaid.config do |p|
-      p.customer_id = 'test_id'
-      p.secret = 'test_bad'
-      p.environment_location = 'https://api.plaid.com/'
-    end
-    it { expect{Plaid.add_user('connect','plaid_bad','plaid_bad','wells')}.to raise_error }
+    let(:secret) { 'test_bad' }
+    let(:environment_location) { prod_url }
+    it { expect { user }.to raise_error }
   end
-end
+end

data/spec/institution_spec.rb

@@ -1,25 +1,17 @@
-# Institution specs
-describe '#Institution' do
-
-  before :all do
-    Plaid.config do |p|
-      p.customer_id = 'test_id'
-      p.secret = 'test_secret'
-      p.environment_location = 'https://tartan.plaid.com/'
-    end
-  end
+require 'spec_helper.rb'
 
+RSpec.describe Plaid::Institution do
   context 'when a single institution is found' do
-    institution = Plaid.institution('5301a93ac140de84910000e0')
-    it { expect(institution.class).to eq(Plaid::Institution) }
+    let(:institution) { Plaid.institution('5301a93ac140de84910000e0') }
+    it { expect(institution).to be_kind_of(Plaid::Institution) }
   end
 
   context 'when all institutions are found' do
-    institution = Plaid.institution
+    let(:institution) { Plaid.institution }
     it { expect(institution).to be_kind_of(Array) }
   end
 
   context 'when institution is not found' do
     it { expect { Plaid.institution('dumb_bank') }.to raise_error }
   end
-end
+end

data/spec/plaid_spec.rb

@@ -0,0 +1,258 @@
+require 'spec_helper.rb'
+# Authentication flow specs - returns Plaid::User
+RSpec.describe Plaid do
+  let(:api_level) { raise "Define let(:api_level)" }
+  let(:username)  { raise "Define let(:username)" }
+  let(:password)  { raise "Define let(:password)" }
+  let(:type)      { raise "Define let(:type)" }
+  let(:pin)       { nil }
+  let(:options)   { nil }
+
+  describe '.add_user' do
+    let(:user) { Plaid.add_user api_level, username, password, type, pin, options }
+
+    context 'with correct credentials for single user auth' do
+      let(:username)  { 'plaid_test' }
+      let(:password)  { 'plaid_good' }
+      let(:type)      { 'wells' }
+
+      context 'and "connect" level of api access' do
+        let(:api_level) { 'connect' }
+
+        it { expect(user.accounts).not_to be_empty }
+
+        context 'with webhook' do
+          let(:options) { { login_only: true, webhook: 'test.com/test.endpoint.aspx' } }
+          it { expect(user.accounts).not_to be_empty }
+        end
+
+        context 'when account is locked' do
+          let(:password) { 'plaid_locked' }
+          it { expect(user.api_res).to eq 'User account is locked' }
+        end
+
+        context 'with connection options' do
+          context 'when requests pending transactions from an institution' do
+            let(:options) { { pending: true } }
+            it { expect(user.accounts).not_to be_empty }
+          end
+
+          context 'when login only is true' do
+            let(:options) { { login_only: true } }
+            it { expect(user.accounts).not_to be_empty }
+          end
+
+          context 'sets a start date for transactions' do
+            let(:options) { { login_only: true, start_date: '10 days ago'} }
+            it { expect(user.accounts).not_to be_empty }
+          end
+
+          context 'sets an end date for transactions' do
+            let(:options) { { login_only: true, end_date: '10 days ago'} }
+            it { expect(user.accounts).not_to be_empty }
+          end
+
+          context 'sets start and end dates for transactions' do
+            let(:options) { { gte: "05/10/2014" , lte: "06/10/2014" } }
+            it { expect(user.transactions).not_to be_nil }
+          end
+
+          pending 'with JSON-encoded string for options'
+        end
+      end
+
+      context 'and "auth" level of api access' do
+        let(:api_level) { 'auth' }
+        it { expect(user.accounts.first.numbers).not_to be_empty }
+      end
+
+      context 'and "info" level of api access' do
+        let(:api_level) { 'info' }
+        it { expect(user.info).not_to be_empty }
+      end
+    end
+
+    context 'with incorrect credentials for single factor auth' do
+      # Set up correct credentials. Override with bad element
+      # within each context block
+      let(:username)  { 'plaid_test' }
+      let(:password)  { 'plaid_good' }
+      let(:type)      { 'wells' }
+
+      context 'at "auth" level api access' do
+        let(:api_level) { 'auth' }
+
+        context 'using incorrect password' do
+          let(:password) { 'plaid_bad' }
+          it { expect { user }.to raise_error }
+        end
+
+        context 'using incorrect username' do
+          let(:username) { 'plaid_bad' }
+          it { expect { user }.to raise_error }
+        end
+      end
+
+      context 'at "connect" level api access' do
+        let(:api_level) { 'connect' }
+
+        context 'using incorrect password' do
+          let(:password) { 'plaid_bad' }
+          it { expect { user }.to raise_error }
+        end
+
+        context 'using incorrect username' do
+          let(:username) { 'plaid_bad' }
+          it { expect { user }.to raise_error }
+        end
+      end
+
+      context 'at "info" level api access' do
+        let(:api_level) { 'info' }
+
+        context 'using incorrect password' do
+          let(:password) { 'plaid_bad' }
+          it { expect { user }.to raise_error }
+        end
+
+        context 'using incorrect username' do
+          let(:username) { 'plaid_bad' }
+          it { expect { user }.to raise_error }
+        end
+      end
+    end
+
+    context 'when institution requires PIN' do
+      let(:api_level) { 'connect' }
+      let(:username)  { 'plaid_test' }
+      let(:password)  { 'plaid_good' }
+      let(:type)      { 'usaa' }
+
+      context 'using correct PIN' do
+        let(:pin) { '1234' }
+        it { expect(user.api_res).to eq 'Requires further authentication' }
+      end
+
+      context 'using incorrect PIN' do
+        let(:pin) { '0000' }
+        it { expect { user }.to raise_error }
+      end
+    end
+
+    context 'when institution requires MFA' do
+      let(:api_level) { 'connect' }
+      let(:username)  { 'plaid_test' }
+      let(:password)  { 'plaid_good' }
+      let(:type)      { 'bofa' }
+
+      context 'with only standard credentials' do
+        it { expect(user.api_res).to eq 'Requires further authentication' }
+      end
+
+      context 'with options' do
+        context 'with webhook' do
+          let(:options) { { login_only: true, webhook: 'test.com/test.endpoint.aspx' } }
+          it { expect(user.api_res).to eq 'Requires further authentication' }
+        end
+
+        context 'requests a list of options for code based MFA' do
+          let(:type) { 'citi' }
+          let(:options) { { list: true } }
+
+          it { expect(user.pending_mfa_questions).not_to be_nil }
+        end
+      end
+    end
+  end
+
+  describe '.set_user' do
+    subject { Plaid.set_user(access_token) }
+    let(:access_token) { 'test' }
+
+    it { expect(subject.access_token).to eq(access_token)}
+
+    context 'gets a valid user with accounts and transactions' do
+      let(:user) { Plaid.set_user('test_wells',['connect']) }
+      it { expect(user.transactions).not_to be_empty }
+    end
+
+    context 'gets a valid user with accounts' do
+      let(:user) { Plaid.set_user('test_wells',['auth']) }
+      it { expect(user.accounts).not_to be_empty }
+    end
+
+    #TODO: Fully vet the info api endpoint for the beta functions before adding this as a supported function.
+    pending 'need to vet the info api endpoint' do
+      context 'gets a valid user with info' do
+        let(:user) { Plaid.set_user('test_wells',['info']) }
+        it { expect(user.accounts).to be_truthy}
+      end
+
+      context 'gets a fully validated user with all access granted' do
+        let(:user) { Plaid.set_user('test_wells',['connect','info','auth']) }
+        it { expect(user.transactions).to be_truthy}
+      end
+    end
+  end
+
+  describe '.exchange_token' do
+    subject { Plaid.exchange_token('test,chase,connected') }
+
+    it { expect(subject.access_token).to eql('test_chase') }
+  end
+
+  describe '.transactions' do
+    subject { Plaid.transactions(access_token, options) }
+    let(:access_token) { 'test_wells' }
+    let(:options)      { nil }
+
+    context 'without options' do
+      it 'should return all accounts' do
+        expect(subject.accounts).not_to be_empty
+      end
+
+      it 'should return all transactions' do
+        expect(subject.transactions).not_to be_empty
+      end
+    end
+
+    context 'when filering by account' do
+      let(:options) { { account: account } }
+      let(:account) { 'QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK' }
+
+      it 'should return a subset of transactions' do
+        expect(subject.transactions.size).to eql(2)
+      end
+
+      it 'should only return transactions from the requested account' do
+        expect(subject.transactions.map(&:account).uniq).to eql([account])
+      end
+    end
+
+    context 'when filtering by date' do
+      let(:options) { { gte: "2014-07-24", lte: "2014-07-25" } }
+
+      it 'should return a subset of transactions' do
+        expect(subject.transactions.size).to eql(1)
+      end
+
+      it 'should only return transactions from the requested date range' do
+        expect(subject.transactions.map(&:date).uniq).to eql(['2014-07-24'])
+      end
+    end
+
+    context 'when filtering by account and date' do
+      let(:options) { { account: account , gte: "2014-07-24", lte: "2014-07-25" } }
+      let(:account) { 'XARE85EJqKsjxLp6XR8ocg8VakrkXpTXmRdOo' }
+
+      it 'should return a subset of transactions' do
+        expect(subject.transactions.size).to eql(1)
+      end
+
+      it 'should only return transactions from the requested account and date range' do
+        expect(subject.transactions.map(&:date).uniq).to eql(['2014-07-24'])
+        expect(subject.transactions.map(&:account).uniq).to eql([account])
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,4 +1,11 @@
 require 'bundler/setup'
 Bundler.setup
 
-require 'plaid'
+require 'plaid'
+require 'pry' if ENV['DEBUG']
+
+Plaid.config do |p|
+  p.customer_id = 'test_id'
+  p.secret = 'test_secret'
+  p.environment_location = 'https://tartan.plaid.com/'
+end

data/spec/transaction_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper.rb'
+
+RSpec.describe Plaid::Transaction do
+  # API: semi-private
+  describe '.new' do
+    # The reason this looks weird is because it is. This will be refactored for 2.0
+    subject { Plaid::Transaction.new(results) }
+
+    def self.with_results(_results, &examples)
+      context "with results #{_results}" do
+        let(:results) { _results }
+        instance_eval(&examples)
+      end
+    end
+
+    with_results('_id'      =>  'ID')       do it { expect(subject.id).to       eql('ID') }       end
+    with_results('_account' =>  'acct')     do it { expect(subject.account).to  eql('acct') }     end
+    with_results('date'     => '00/00/00')  do it { expect(subject.date).to     eql('00/00/00') } end
+    with_results('amount'   => 100.00)      do it { expect(subject.amount).to   eql(100.00) }     end
+    with_results('name'     =>  'Name')     do it { expect(subject.name).to     eql('Name') }     end
+    with_results('meta'     => {} )         do it { expect(subject.meta).to     eql({}) }         end
+    with_results('meta'     => {'location' => 'Location'}) do it { expect(subject.location).to eql('Location') } end
+    with_results('pending'  =>  true)       do it { expect(subject.pending).to  eql(true) }       end
+    with_results('score'    =>  200)        do it { expect(subject.score).to    eql(200) }        end
+    with_results('type'     =>  'Type')     do it { expect(subject.type).to     eql('Type') }     end
+
+    with_results('category'    => 'Category') do it { expect(subject.category).to    eql('Category') } end
+    with_results('category_id' => 100)        do it { expect(subject.category_id).to eql(100) } end
+  end
+end