plaid 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1d12271b5f68498843347df5493efca85a54331
-  data.tar.gz: 77bd4a0ef5b50a6ac420a2067484a425d71b5f5b
+  metadata.gz: 275751fae8bd5e8b06ab3b12d577fb9287663fbd
+  data.tar.gz: 5b079f65196433ea7edfe0d27e5bcc917d4bc4f0
 SHA512:
-  metadata.gz: 53b474fb7b12fbc2acb335aab4f072dd5d4ad96dcbc07b2a77fae42a73630b9ed7881336c7cab7e24a7b85543b666f07738eb8237df3eac8847a803244c71227
-  data.tar.gz: d9935d472dd1cc6841a94acee6049c637777c5d9c19384b6c43443f867906ffa1631465a5707676628794c84189f4ab90df9adcb6364e208bf861601c711e033
+  metadata.gz: a2da99035165898c5634a704a12ee0a47f021df841e33a1172c7503b219a66451b60f6fb1bbf39f6c833ea450eeb00c13d0302dca56a8a3526b60a64126a6e6c
+  data.tar.gz: 53d4916be3b84f6833add1df715fad9de680391d13c4ff46969a1680d276507e46232a513f935d195a9e6515f2fa172a24e9b943c851846e02612caa7cb217ed

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 2.1.0. 19-Oct-2016
+
+* Documentation fixes (@ishmael).
+* Fix `Transaction#to_s` behavior (@michel-tricot).
+* PATCH `/:product/step` flow.
+* Use the same client in `User#upgrade` (@betesh).
+* Webhook object (@zshannon).
+* `processor_token` access in `User.exchange_token` (@gylaz).
+* Raise `ServerError` in case server returned an empty response body.
+
 # 2.0.0. 24-May-2016
 
 * Use `~> 1.0` spec for multi_json dependency.

data/README.md

@@ -34,7 +34,7 @@ Configure the gem with your client id, secret, and the environment you would lik
 Plaid.config do |p|
   p.client_id = '<<< Plaid provided client ID >>>'
   p.secret = '<<< Plaid provided secret key >>>'
-  p.env = :tartan  # or :api for production
+  p.env = :tartan  # or :production
 end
 ```
 
@@ -86,7 +86,7 @@ user = Plaid::User.exchange_token('public_token')   # bound to :connect product
 With more options:
 
 ```ruby
-user2 = Plaid::User.exchange_token('public_token', account_id: '...', product: :auth)
+user2 = Plaid::User.exchange_token('public_token', 'account_id', product: :auth)
 ```
 
 If you want to [move money via Stripe's ACH
@@ -210,6 +210,55 @@ ltis = Plaid::LongTailInstitution.all(count: 20, offset: 20) # A page
 res  = Plaid::LongTailInstitution.search(query: 'c')         # Lookup by name
 ```
 
+### Webhooks
+
+You can register to receive [Webhooks](https://plaid.com/docs/api/#webhook) from Plaid when your users have new events. If you do, you'll receive `POST` requests with JSON.
+
+E.g. Initial Transaction Webhook:
+```json
+{
+ "message": "Initial transaction pull finished",
+ "access_token": "xxxxx",
+ "total_transactions": 123,
+ "code": 0
+}
+```
+
+You should parse that JSON into a Ruby Hash with String keys (eg. `webhook_hash = JSON.parse(json_string)`). Then, you can convert that Hash into a Ruby object using `Plaid::Webhook`:
+
+```ruby
+webhook = Plaid::Webhook.new(webhook_hash)
+
+# Was that the Initial Transaction Webhook?
+webhook.initial_transaction?
+access_token = webhook.access_token
+total_transactions = webhook.total_transactions
+
+# Or did Historical Transactions become available?
+webhook.historical_transaction?
+access_token = webhook.access_token
+total_transactions = webhook.total_transactions
+
+# Or did Normal Transactions become available?
+webhook.normal_transaction?
+access_token = webhook.access_token
+total_transactions = webhook.total_transactions
+
+# Or maybe a transaction was removed?
+webhook.removed_transaction?
+access_token = webhook.access_token
+removed_transactions_ids = webhook.removed_transactions_ids
+
+# Or was the User's Webhook Updated?
+webhook.user_webhook_updated?
+access_token = webhook.access_token
+
+# Otherwise, was it an error?
+webhook.error_response?
+# Which error?
+error = webhook.error
+```
+
 ### Custom clients
 
 It's possible to use several Plaid environments and/or credentials in one app by
@@ -224,7 +273,7 @@ Plaid.config do |p|
 end
 
 # Creating a custom client
-api = Plaid::Client.new(client_id: 'client_id_2', 'secret_2', env: :api)
+api = Plaid::Client.new(client_id: 'client_id_2', secret: 'secret_2', env: :production)
 
 # Tartan user (using default client)
 user1 = Plaid::User.create(:connect, 'wells', 'plaid_test', 'plaid_good')

data/lib/plaid.rb

@@ -8,6 +8,7 @@ require 'plaid/transaction'
 require 'plaid/info'
 require 'plaid/income'
 require 'plaid/client'
+require 'plaid/webhook'
 
 require 'uri'
 

data/lib/plaid/connector.rb

@@ -95,6 +95,10 @@ module Plaid
       @request = request
       @response = http.request(@request)
 
+      if @response.body.nil? || @response.body.empty?
+        raise Plaid::ServerError.new(0, 'Server error', 'Try to connect later')
+      end
+
       # All responses are expected to have a JSON body, so we always parse,
       # not looking at the status code.
       @body = MultiJson.load(@response.body)

data/lib/plaid/transaction.rb

@@ -110,7 +110,7 @@ module Plaid
     #
     # Returns a String.
     def inspect
-      "#<Plaid::Transaction id=#{id.inspect}, account_id=#{id.inspect}, " \
+      "#<Plaid::Transaction id=#{id.inspect}, account_id=#{account_id.inspect}, " \
       "date=#{date}, amount=#{amount.inspect}, name=#{name.inspect}, " \
       "pending=#{pending.inspect}>"
     end

data/lib/plaid/user.rb

@@ -7,6 +7,9 @@ module Plaid
     # Public: The access token for authenticated user.
     attr_reader :access_token
 
+    # Public: The processor token for a given account and authenticated user.
+    attr_reader :processor_token
+
     # Public: The current product. Provides a context for #update and #delete
     # calls. See Plaid::PRODUCTS.
     attr_reader :product
@@ -146,7 +149,7 @@ module Plaid
     # 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.
+    #                contains an MFA response.
     # stripe_token - The String stripe bank account token.
     # client       - The Plaid::Client instance used to connect to the API
     #                (default is to use global Plaid client - Plaid.client).
@@ -207,7 +210,13 @@ module Plaid
         payload[:options] = MultiJson.dump(options)
       end
       conn = Connector.new(product, :step, auth: true)
-      response = conn.post(payload)
+
+      # Use PATCH if we are in context of User#update.
+      response = if @mfa_patch
+                   conn.patch(payload)
+                 else
+                   conn.post(payload)
+                 end
 
       @mfa_required = conn.mfa?
       parse_response(response)
@@ -261,8 +270,17 @@ module Plaid
 
       payload[:pin] = pin if pin
 
-      parse_response(Connector.new(product, auth: true, client: client)
-                              .patch(payload))
+      conn = Connector.new(product, auth: true, client: client)
+      resp = conn.patch(payload)
+
+      if conn.mfa?
+        @mfa_required = true
+      end
+
+      parse_response(resp)
+
+      # A note for User#mfa_step to send PATCH request too
+      @mfa_patch = true
 
       self
     end
@@ -321,7 +339,7 @@ module Plaid
       response = Connector.new(:upgrade, auth: true, client: client)
                           .post(payload)
 
-      User.new product, response: response
+      User.new product, response: response, client: client
     end
 
     # Public: Get the current user tied to another product.
@@ -443,6 +461,8 @@ module Plaid
     # Internal: Set up attributes from Add User response.
     def parse_response(response)
       @access_token = response['access_token']
+      @processor_token = response['processor_token']
+
       return parse_mfa_response(response) if mfa?
 
       @mfa_type = @mfa = nil

data/lib/plaid/version.rb

@@ -1,3 +1,3 @@
 module Plaid
-  VERSION = '2.0.0'.freeze
+  VERSION = '2.1.0'.freeze
 end

data/lib/plaid/webhook.rb

@@ -0,0 +1,130 @@
+module Plaid
+  # Public: Representation of a webhook.
+  class Webhook
+    # Public: The String human readable explanation of this webhook request.
+    # E.g. "Initial transaction pull finished".
+    attr_reader :message
+
+    # Public: The String access token for authenticated user.
+    attr_reader :access_token
+
+    # Public: The Integer number of transactions available in Plaid.
+    # E.g. 124
+    attr_reader :total_transactions
+
+    # Public: The Integer code denoting the type of webhook this is. E.g. 0
+    attr_reader :code
+
+    # Public: Initialize a Webhook instance.
+    #
+    # fields - The Hash with fields.
+    def initialize(fields)
+      @message = fields['message']
+      @access_token = fields['access_token']
+      @total_transactions = fields['total_transactions']
+      @code = fields['code']
+      # present only for Removed Transaction Webhook
+      @removed_transactions = fields['removed_transactions']
+      # present only for Error Response Webhook
+      @resolve = fields['resolve']
+    end
+
+    # Public: Share the type of Webhook this is from its code
+    #
+    # Returns String webhook type
+    def type
+      Webhook::CODEX[code] || 'ERROR_RESPONSE'
+    end
+
+    # Public: Detect if the webhook is Initial Transaction Webhook. Occurs
+    # once the initial transaction pull has finished.
+    #
+    # Returns true if it is.
+    def initial_transaction?
+      code == Webhook::INITIAL_TRANSACTION
+    end
+
+    # Public: Detect if the webhook is Historical Transaction Webhook. Occurs
+    # once the historical transaction pull has completed, shortly after the
+    # initial transaction pull.
+    #
+    # Returns true if it is.
+    def historical_transaction?
+      code == Webhook::HISTORICAL_TRANSACTION
+    end
+
+    # Public: Detect if the webhook is Normal Transaction Webhook. Occurs at
+    # set intervals throughout the day as data is updated from the financial
+    # institutions.
+    #
+    # Returns true if it is.
+    def normal_transaction?
+      code == Webhook::NORMAL_TRANSACTION
+    end
+
+    # Public: Detect if the webhook is Removed Transaction Webhook. Occurs when
+    # transactions have been removed from our system.
+    #
+    # Returns true if it is.
+    def removed_transaction?
+      code == Webhook::REMOVED_TRANSACTION
+    end
+
+    # Public: Detect if the webhook is User's Webhook Updated. Occurs when an
+    # user's webhook is updated via a PATCH request without credentials.
+    #
+    # Returns true if it is.
+    def user_webhook_updated?
+      code == Webhook::USER_WEBHOOK_UPDATED
+    end
+
+    # Public: Detect if the webhook is Error Response Webhook. Triggered when
+    # an error has occurred. Includes the relevant Plaid error code with
+    # details on both the error type and steps for error resolution.
+    #
+    # Returns true if it is.
+    def error_response?
+      Webhook::CODEX[code].nil?
+    end
+
+    # Public: Get transaction IDs that were removed.
+    #
+    # Returns Array[String] or nil
+    def removed_transactions_ids
+      @removed_transactions
+    end
+
+    # Public: Get a Plaid::Error instance if this is an Error Response Webhook
+    #
+    # Returns Plaid::Error or nil
+    def error
+      if error_response?
+        Plaid::PlaidError.new @code, @message, @resolve
+      end
+    end
+
+    # Public: Get a String representation of the transaction.
+    #
+    # Returns a String.
+    def inspect
+      "#<Plaid::Webhook type=#{type.inspect} code=#{code.inspect}, access_token=#{access_token.inspect}, " \
+      "total_transactions=#{total_transactions.inspect}, message=#{message.inspect}>"
+    end
+
+    # Public: Get a String representation of the transaction.
+    #
+    # Returns a String.
+    alias to_s inspect
+
+    private
+
+    Webhook::ERROR_RESPONSE = -1
+    codex = {}
+    ['initial transaction', 'historical transaction', 'normal transaction', 'removed transaction', 'user webhook updated'].each_with_index do |event, idx|
+      name = event.split.map(&:upcase).join('_')
+      codex[idx + 1] = name
+      const_set name, idx + 1
+    end
+    CODEX = codex.freeze
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plaid
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Oleg Dashevskii
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-24 00:00:00.000000000 Z
+date: 2016-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -138,6 +138,7 @@ files:
 - lib/plaid/transaction.rb
 - lib/plaid/user.rb
 - lib/plaid/version.rb
+- lib/plaid/webhook.rb
 - plaid.gemspec
 homepage: https://github.com/plaid/plaid-ruby
 licenses:
@@ -159,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby bindings for Plaid