plaid 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 23f868bb29f987801f40bb8666471898caa9a51b
-  data.tar.gz: 2acc57e2e3f6e7df16b336078b26c0f85032f1c6
+  metadata.gz: 4f8aeb4ddef4c58a7a03b9902450a8b87fc82296
+  data.tar.gz: d9b2daf9205549d39fa5a4f25700ddfae73cf6d7
 SHA512:
-  metadata.gz: 76a97718db8ed7e5072c5ed55ccaf0bc9c281d412d6806b6f1da972bd0b3f46e86fde3fb62eebb6e511e568241f38d6b3fa0fc6ec488f0183cbc3688113439f1
-  data.tar.gz: 50a9f87dd4fb6f77cd6af0ebefaec70c20ef9d2d0b3266bb4e00da7f03a7b3e19d91b7e46fe98799fb22aab506d5f6e6307ec166369e150569c90721b10621aa
+  metadata.gz: 51e64249b4daad06dd8dd03d648b721204d3383ae493289b1dccf85e80ec2fe5892a83b388d4ec8ac2b417dd47732dafb1f3658a3cfb790947cb94b1866d2aaa
+  data.tar.gz: 2ab1e1bb607cb87ddaaa3a0adc52946b18dbac5e4112f8db945226985fafd2b93ef10d763eba101cd0ac2fea688c8cec455e660caacab9b8f0972a307d1135f2

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 3.0.0. 17-Jan-2017
+
+* Add `/institutions/all` and `/institutions/all/search` endpoints, see [UPGRADING.md](UPGRADING.md#upgrading-from-2xx-to-300)
+
 # 2.2.0. 03-Nov-2016
 
 * Add `Transaction#reference_number` (@ericbirdsall).

data/README.md

@@ -199,15 +199,13 @@ cat  = Plaid::Category.get('17001013') # A single category by its ID
 
 ### Institutions
 
-Financial institution information is available via `Plaid::Institution` and `Plaid::LongTailInstitution`:
+Financial institution information is available via `Plaid::Institution`.
 
 ```ruby
-insts = Plaid::Institution.all                               # Array of all major financial institutions
+insts = Plaid::Institution.all(count: 20, offset: 20)        # A page
 inst  = Plaid::Institution.get('5301a93ac140de84910000e0')   # A single institution by its ID
 
-lti  = Plaid::LongTailInstitution.get('bofa')                # A single one
-ltis = Plaid::LongTailInstitution.all(count: 20, offset: 20) # A page
-res  = Plaid::LongTailInstitution.search(query: 'c')         # Lookup by name
+res  = Plaid::Institution.search(query: 'c')         # Lookup by name
 ```
 
 ### Webhooks
@@ -281,8 +279,8 @@ user1 = Plaid::User.create(:connect, 'wells', 'plaid_test', 'plaid_good')
 # Api user (using api client)
 user2 = Plaid::User.create(:connect, 'wells', 'plaid_test', 'plaid_good', client: api)
 
-# Lookup a long tail institution in production
-res = Plaid::LongTailInstitution.search(query: 'c', client: api)
+# Lookup an institution in production
+res = Plaid::Institution.search(query: 'c', client: api)
 ```
 
 The `client` option can be passed to the following methods:
@@ -294,9 +292,8 @@ The `client` option can be passed to the following methods:
 * `Category.get`
 * `Institution.all`
 * `Institution.get`
-* `LongTailInstitution.all`
-* `LongTailInstitution.search`
-* `LongTailInstitution.get`
+* `Institution.search`
+* `Institution.search_by_id`
 
 ### Errors
 

data/UPGRADING.md

@@ -1,3 +1,18 @@
+## Upgrading from 2.x.x to 3.0.0
+
+Version 3.0.0 makes `Plaid::Institution` use new `institutions/all` endpoint
+of Plaid API which unites "native" and "long tail" institutions.
+`Plaid::LongTailInstitution` class is removed, its functionality is
+concentrated in `Plaid::Institution`.
+
+Use `Plaid::Institution.all` instead of `Plaid::LongTailInstitution.all` (the
+semantics is the same, with added products param).
+
+Use `Plaid::Institution.search` instead of `Plaid::LongTailInstitution.search`.
+
+Use `Plaid::Institution.search_by_id` instead of `Plaid::LongTailInstitution.get`.
+
+
 ## Upgrading from 1.x to 2.0.0
 
 Make sure you use Ruby 2.0 or higher.

data/lib/plaid/institution.rb

@@ -19,7 +19,7 @@ module Plaid
     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
+    # "questions(3)"]. In this case 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
@@ -60,38 +60,123 @@ module Plaid
     # Public: Get information about the Financial Institutions currently
     # supported by Plaid.
     #
-    # Does a GET /institutions call.
+    # Does a POST /institutions/all call. The result is paginated (count,
+    # offset params) and filtered by products. If the products param is
+    # specified, only institutions which support all of the products mentioned
+    # will be returned.
     #
-    # client - The Plaid::Client instance used to connect
-    #          (default: Plaid.client).
+    # 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).
+    # products - The Array of product Symbols (see Plaid::PRODUCTS) or nil.
+    #            E.g. [:connect, :auth]. Default: nil.
+    # 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)
+    def self.all(count: 50, offset: 0, products: nil, client: nil)
+      conn = Connector.new(:institutions, :all, auth: true, client: client)
+      payload = {
+        count: count,
+        offset: offset
+      }
+
+      if products
+        payload[:products] = MultiJson.encode(Array(products))
       end
+
+      resp = conn.post(payload)
+
+      Page.new(resp['total_count'],
+               resp['results'].map { |item| new(item) })
     end
 
     # Public: Get information about a given Financial Institution.
     #
-    # Does a GET /institutions/:id call.
+    # Does a GET /institutions/all/:id call.
     #
-    # id     - the String institution ID (e.g. "5301a93ac140de84910000e0").
+    # id     - the String institution ID (e.g. "5301a93ac140de84910000e0", or
+    #          "ins_109263").
     # 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
+      new Connector.new('institutions/all', id, client: client).get
+    end
+
+    # Public: Search Financial 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).
+    #
+    # Returns an Array of SearchResultInstitution.
+    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/all', :search, client: client).get(payload)
+      resp.map { |inst| SearchResultInstitution.new(inst) }
+    end
+
+    # Public: Lookup a Financial Institution by ID.
+    #
+    # Does a GET /institutions/all/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 SearchResultInstitution instance or nil if institution with
+    # given id is not found.
+    def self.search_by_id(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/all', :search, auth: auth, client: client)
+      resp = conn.get(id: id)
+
+      case resp
+      when Hash
+        SearchResultInstitution.new resp
+      when Array
+        raise 'Non-empty array returned by /institutions/all/search with id' \
+          unless resp.empty?
+
+        nil
+      else
+        raise 'Unexpected result returned by /institutions/all/search with id: ' \
+          "#{resp.inspect}"
+      end
     end
   end
 
-  ##############################################################################
+  # Public: A page of results.
+  class Page < Array
+    # Public: The total number of institutions in all pages
+    attr_reader :total_count
+
+    def initialize(total_count, records)
+      @total_count = total_count
+      super records
+    end
+  end
 
-  # Public: A class encapsulating information about a "long tail" Financial
-  # Institution supported by Plaid.
-  class LongTailInstitution
+  # Public: A class encapsulating information about a Financial Institution
+  # supported by Plaid.
+  class SearchResultInstitution
     # Public: The String ID of the institution. Same as type. E.g. "bofa".
     attr_reader :id
 
@@ -137,7 +222,7 @@ module Plaid
     # Public: ???.
     attr_reader :name_break
 
-    # Internal: Initialize the LongTailInstitution instance.
+    # Internal: Initialize the SearchResultInstitution instance.
     def initialize(hash)
       %w(id type name video logo).each do |f|
         instance_variable_set "@#{f}", hash[f]
@@ -156,7 +241,7 @@ module Plaid
     #
     # Returns a String.
     def inspect
-      "#<Plaid::LongTailInstitution id=#{id.inspect}, name=#{name.inspect}, " \
+      "#<Plaid::SearchResultInstitution id=#{id.inspect}, name=#{name.inspect}, " \
         '...>'
     end
 
@@ -164,77 +249,5 @@ module Plaid
     #
     # 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

data/lib/plaid/version.rb

@@ -1,3 +1,3 @@
 module Plaid
-  VERSION = '2.2.0'.freeze
+  VERSION = '3.0.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plaid
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Oleg Dashevskii
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-03 00:00:00.000000000 Z
+date: 2017-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -160,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby bindings for Plaid