gocardless_pro 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f9bf930f0861c969e5518b00a10e9751691b4505
-  data.tar.gz: 3ca0cd94ef9b840cacf9e5aa3ddd7fb843404ed3
+  metadata.gz: b558be54b18a323263272b8629c8f7f57c5b034b
+  data.tar.gz: b7f920a9a2c6861183603d02bd19c803c245108f
 SHA512:
-  metadata.gz: a86b8b85b3e57c6b199d8dbea5591bb3a393f339e2e506a939a82a2bdc22cb8df5361f1f4e4288604b29d3debdfde3b2a7ebb1d8895c640a456e4d795c3b5477
-  data.tar.gz: 2bf60b407e6fdc07d2e582274197bff176b03f9fc4d30f25591943ab0479121ab9ea388c56c931d0bfe6d14aa5276d1e7e983faaa06fd212ed900ca84d83e4b3
+  metadata.gz: df5272b94fa8d97a0945fcc393e69a97558ce9dd4701c54049e6d4e66aea4b0521e3c3f2dc5783a3aebedb6f19a791e85fe40f016487e41726688f3341a72ac4
+  data.tar.gz: 42cc33ed47c7e8fa42f23d7e1b3e99bc7f19e7de0891adb82b9c62de102945982ceec33e7a2c5e111c9eabc9268c4a772d1d221bbd8938b4030f168c82a6ba9f

data/README.md

@@ -2,11 +2,11 @@
 
 A Ruby client for the GoCardless API. For full details of the GoCardless API, see the [API docs](https://developer.gocardless.com/pro/).
 
-[![Gem Version](https://badge.fury.io/rb/statesman.png)](http://badge.fury.io/rb/gocardless_pro)
+[![Gem Version](https://badge.fury.io/rb/gocardless_pro.svg)](http://badge.fury.io/rb/gocardless_pro)
 [![Build Status](https://travis-ci.org/gocardless/gocardless-pro-ruby.svg?branch=master)](https://travis-ci.org/gocardless/gocardless-pro-ruby)
 
 - ["Getting started" guide](https://developer.gocardless.com/getting-started/api/introduction/?lang=ruby) with copy and paste Ruby code samples
-- [API Reference](https://developer.gocardless.com/api-reference/2015-07-06)
+- [API Reference](https://developer.gocardless.com/api-reference)
 
 ## Usage Examples
 
@@ -115,6 +115,11 @@ For POST and PUT requests you need to pass in the body in under the `params` key
 )
 ```
 
+When creating a resource, the library will automatically include a randomly-generated
+[idempotency key](https://developer.gocardless.com/api-reference/#making-requests-idempotency-keys)
+- this means that if a request appears to fail but is in fact successful (for example due
+to a timeout), you will not end up creating multiple duplicates of the resource.
+
 If any parameters are required they come first:
 
 ```rb
@@ -125,7 +130,7 @@ If any parameters are required they come first:
 
 Custom headers can be provided for a POST request under the `headers` key.
 
-The most common use of a custom header would be to set an [idempotency key](https://developer.gocardless.com/pro/#making-requests-idempotency-keys) when making a request:
+The most common use of a custom header would be to set a custom [idempotency key](https://developer.gocardless.com/pro/#making-requests-idempotency-keys) when making a request:
 
 ```rb
 @client.customers.create(
@@ -142,7 +147,7 @@ The most common use of a custom header would be to set an [idempotency key](http
 
 ### Handling failures
 
-When the API returns an error, the client will raise a corresponding one. There are four classes of error which could be thrown, allof which subclass `GoCardlessPro::Error`:
+When the API returns an error, the client will raise a corresponding one. There are four classes of error which could be thrown, all of which subclass `GoCardlessPro::Error`:
 
 - `GoCardlessPro::GoCardlessError`
 - `GoCardlessPro::InvalidApiUsageError`
@@ -151,6 +156,8 @@ When the API returns an error, the client will raise a corresponding one. There
 
 These errors are fully documented in the [API documentation](https://developer.gocardless.com/api-reference/#overview-errors).
 
+When the API returns an `invalid_state` error due to an `idempotent_creation_conflict`, where possible, the library will automatically retrieve the existing record which was created using the idempotency key.
+
 All errors have the following methods to facilitate access to information in the API response:
 
 - `#documentation_url`
@@ -160,6 +167,8 @@ All errors have the following methods to facilitate access to information in the
 - `#request_id`
 - `#errors`
 
+If a timeout occurs, and the request being made is idempotent, the library will automatically retry the request up to 3 times before giving up and raising a `Faraday::TimeoutError` error.
+
 ### Using the OAuth API
 
 The API includes [OAuth](https://developer.gocardless.com/pro/2015-07-06/#guides-oauth) functionality, which allows you to work with other users' GoCardless accounts. Once a user approves you, you can use the GoCardless API on their behalf and receive their webhooks.

data/lib/gocardless_pro.rb

@@ -24,6 +24,7 @@ end
 
 require_relative 'gocardless_pro/api_service'
 require_relative 'gocardless_pro/list_response'
+require_relative 'gocardless_pro/middlewares/raise_gocardless_errors'
 require_relative 'gocardless_pro/error'
 require_relative 'gocardless_pro/error/validation_error'
 require_relative 'gocardless_pro/error/gocardless_error'

data/lib/gocardless_pro/api_service.rb

@@ -23,6 +23,8 @@ module GoCardlessPro
       connection_options = options[:connection_options]
 
       @connection = Faraday.new(root_url, connection_options) do |faraday|
+        faraday.response :raise_gocardless_errors
+
         faraday.adapter(*http_adapter)
       end
 

data/lib/gocardless_pro/client.rb

@@ -116,7 +116,9 @@ module GoCardlessPro
         default_headers: {
           'GoCardless-Version' => '2015-07-06',
           'User-Agent' => "#{user_agent}",
-          'Content-Type' => 'application/json'
+          'Content-Type' => 'application/json',
+          'GoCardless-Client-Library' => 'gocardless-pro-ruby',
+          'GoCardless-Client-Version' => '2.0.0'
         }
       }
     end
@@ -124,8 +126,7 @@ module GoCardlessPro
     def user_agent
       @user_agent ||=
         begin
-          gem_name = 'gocardless_pro'
-          gem_info = "#{gem_name}"
+          gem_info = 'gocardless-pro-ruby'
           gem_info += "/v#{GoCardlessPro::VERSION}" if defined?(GoCardlessPro::VERSION)
 
           ruby_engine = defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby'

data/lib/gocardless_pro/error/invalid_state_error.rb

@@ -1,5 +1,22 @@
 module GoCardlessPro
   # Thrown when the API returns an invalid state error
   class InvalidStateError < Error
+    IDEMPOTENT_CREATION_CONFLICT = 'idempotent_creation_conflict'.freeze
+    CONFLICTING_RESOURCE_ID = 'conflicting_resource_id'.freeze
+
+    def idempotent_creation_conflict?
+      !idempotent_creation_conflict_error.nil?
+    end
+
+    def conflicting_resource_id
+      return unless idempotent_creation_conflict?
+      idempotent_creation_conflict_error['links'][CONFLICTING_RESOURCE_ID]
+    end
+
+    private
+
+    def idempotent_creation_conflict_error
+      errors.find { |error| error['reason'] == IDEMPOTENT_CREATION_CONFLICT }
+    end
   end
 end

data/lib/gocardless_pro/middlewares/raise_gocardless_errors.rb

@@ -0,0 +1,50 @@
+module GoCardlessPro
+  module Middlewares
+    class RaiseGoCardlessErrors < Faraday::Response::Middleware
+      API_ERROR_STATUSES = 501..599
+      CLIENT_ERROR_STATUSES = 400..500
+
+      def on_complete(env)
+        if !json?(env) || API_ERROR_STATUSES.include?(env.status)
+          fail ApiError, generate_error_data(env)
+        end
+
+        if CLIENT_ERROR_STATUSES.include?(env.status)
+          json_body ||= JSON.parse(env.body) unless env.body.empty?
+          error_type = json_body['error']['type']
+          fail(error_class_for_type(error_type), json_body['error'])
+        end
+      end
+
+      private
+
+      def error_class_for_type(type)
+        {
+          validation_failed: GoCardlessPro::ValidationError,
+          gocardless: GoCardlessPro::GoCardlessError,
+          invalid_api_usage: GoCardlessPro::InvalidApiUsageError,
+          invalid_state: GoCardlessPro::InvalidStateError
+        }.fetch(type.to_sym)
+      end
+
+      def generate_error_data(env)
+        {
+          'message' => "Something went wrong with this request\n" \
+                       "code: #{env.status}\n" \
+                       "headers: #{env.response_headers}\n" \
+                       "body: #{env.body}",
+          'code' => env.status
+        }
+      end
+
+      def json?(env)
+        content_type = env.response_headers['Content-Type'] ||
+                       env.response_headers['content-type'] || ''
+
+        content_type.include?('application/json')
+      end
+    end
+  end
+end
+
+Faraday::Response.register_middleware raise_gocardless_errors: GoCardlessPro::Middlewares::RaiseGoCardlessErrors

data/lib/gocardless_pro/request.rb

@@ -1,6 +1,11 @@
+require 'securerandom'
+
 module GoCardlessPro
   # A class that wraps an API request
   class Request
+    MAX_NETWORK_RETRIES = 3
+    RETRY_DELAY = 0.5
+
     # Initialize a request class, which makes calls to the API
     # @param connection
     # @param method [Symbol] the method to make the request with
@@ -13,6 +18,7 @@ module GoCardlessPro
       @path = path
       @headers = options.delete(:headers) || {}
       @envelope_name = options.delete(:envelope_key)
+      @retry_failures = options.delete(:retry_failures) { true }
       @given_options = options
 
       @request_body = request_body
@@ -21,11 +27,34 @@ module GoCardlessPro
         @request_body = @request_body.to_json
         @headers['Content-Type'] ||= 'application/json'
       end
+
+      @headers['Idempotency-Key'] ||= SecureRandom.uuid if @method == :post
     end
 
     # Make the request and wrap it in a Response object
     def request
-      Response.new(make_request)
+      if @retry_failures
+        with_retries { Response.new(make_request) }
+      else
+        Response.new(make_request)
+      end
+    end
+
+    def with_retries
+      requests_attempted = 0
+      total_requests_allowed = MAX_NETWORK_RETRIES + 1
+
+      begin
+        yield
+      rescue => exception
+        if requests_attempted < total_requests_allowed && should_retry?(exception)
+          requests_attempted += 1
+          sleep(RETRY_DELAY)
+          retry
+        else
+          raise exception
+        end
+      end
     end
 
     # Make the API request
@@ -57,5 +86,13 @@ module GoCardlessPro
         {}
       end
     end
+
+    private
+
+    def should_retry?(exception)
+      return true if exception.is_a?(Faraday::TimeoutError)
+      return true if exception.is_a?(Faraday::ConnectionFailed)
+      return true if exception.is_a?(GoCardlessPro::ApiError)
+    end
   end
 end

data/lib/gocardless_pro/resources/creditor.rb

@@ -61,7 +61,7 @@ module GoCardlessPro
 
       # Return the links that the resource has
       def links
-        @links_links ||= Links.new(@links)
+        @creditor_links ||= Links.new(@links)
       end
 
       # Provides the creditor resource as a hash of all its readable attributes
@@ -71,7 +71,7 @@ module GoCardlessPro
 
       class Links
         def initialize(links)
-          @links = links
+          @links = links || {}
         end
 
         def default_eur_payout_account

data/lib/gocardless_pro/resources/creditor_bank_account.rb

@@ -12,15 +12,15 @@ module GoCardlessPro
     # Represents an instance of a creditor_bank_account resource returned from the API
 
     # Creditor Bank Accounts hold the bank details of a
-    # [creditor](#whitelabel-partner-endpoints-creditors). These are the bank
-    # accounts which your [payouts](#core-endpoints-payouts) will be sent to.
-
-    #  #
-    # Note that creditor bank accounts must be unique, and so you will
-    # encounter a `bank_account_exists` error if you try to create a duplicate
-    # bank account. You may wish to handle this by updating the existing record
-    # instead, the ID of which will be provided as
-    # `links[creditor_bank_account]` in the error response.
+    # [creditor](#core-endpoints-creditors). These are the bank accounts which
+    # your [payouts](#core-endpoints-payouts) will be sent to.
+    #
+    # Note
+    # that creditor bank accounts must be unique, and so you will encounter a
+    # `bank_account_exists` error if you try to create a duplicate bank account.
+    # You may wish to handle this by updating the existing record instead, the
+    # ID of which will be provided as `links[creditor_bank_account]` in the
+    # error response.
     class CreditorBankAccount
       attr_reader :account_holder_name
       attr_reader :account_number_ending
@@ -56,7 +56,7 @@ module GoCardlessPro
 
       # Return the links that the resource has
       def links
-        @links_links ||= Links.new(@links)
+        @creditor_bank_account_links ||= Links.new(@links)
       end
 
       # Provides the creditor_bank_account resource as a hash of all its readable attributes
@@ -66,7 +66,7 @@ module GoCardlessPro
 
       class Links
         def initialize(links)
-          @links = links
+          @links = links || {}
         end
 
         def creditor

data/lib/gocardless_pro/resources/customer_bank_account.rb

@@ -57,7 +57,7 @@ module GoCardlessPro
 
       # Return the links that the resource has
       def links
-        @links_links ||= Links.new(@links)
+        @customer_bank_account_links ||= Links.new(@links)
       end
 
       # Provides the customer_bank_account resource as a hash of all its readable attributes
@@ -67,7 +67,7 @@ module GoCardlessPro
 
       class Links
         def initialize(links)
-          @links = links
+          @links = links || {}
         end
 
         def customer

data/lib/gocardless_pro/resources/event.rb

@@ -43,7 +43,7 @@ module GoCardlessPro
 
       # Return the links that the resource has
       def links
-        @links_links ||= Links.new(@links)
+        @event_links ||= Links.new(@links)
       end
 
       # Provides the event resource as a hash of all its readable attributes
@@ -53,7 +53,7 @@ module GoCardlessPro
 
       class Links
         def initialize(links)
-          @links = links
+          @links = links || {}
         end
 
         def mandate

data/lib/gocardless_pro/resources/mandate.rb

@@ -50,7 +50,7 @@ module GoCardlessPro
 
       # Return the links that the resource has
       def links
-        @links_links ||= Links.new(@links)
+        @mandate_links ||= Links.new(@links)
       end
 
       # Provides the mandate resource as a hash of all its readable attributes
@@ -60,7 +60,7 @@ module GoCardlessPro
 
       class Links
         def initialize(links)
-          @links = links
+          @links = links || {}
         end
 
         def creditor

data/lib/gocardless_pro/resources/payment.rb

@@ -13,12 +13,12 @@ module GoCardlessPro
 
     # Payment objects represent payments from a
     # [customer](#core-endpoints-customers) to a
-    # [creditor](#whitelabel-partner-endpoints-creditors), taken against a
-    # Direct Debit [mandate](#core-endpoints-mandates).
+    # [creditor](#core-endpoints-creditors), taken against a Direct Debit
+    # [mandate](#core-endpoints-mandates).
     #
-    # GoCardless
-    # will notify you via a [webhook](#appendix-webhooks) whenever the state of
-    # a payment changes.
+    # GoCardless will notify
+    # you via a [webhook](#appendix-webhooks) whenever the state of a payment
+    # changes.
     class Payment
       attr_reader :amount
       attr_reader :amount_refunded
@@ -56,7 +56,7 @@ module GoCardlessPro
 
       # Return the links that the resource has
       def links
-        @links_links ||= Links.new(@links)
+        @payment_links ||= Links.new(@links)
       end
 
       # Provides the payment resource as a hash of all its readable attributes
@@ -66,7 +66,7 @@ module GoCardlessPro
 
       class Links
         def initialize(links)
-          @links = links
+          @links = links || {}
         end
 
         def creditor

data/lib/gocardless_pro/resources/payout.rb

@@ -12,10 +12,9 @@ module GoCardlessPro
     # Represents an instance of a payout resource returned from the API
 
     # Payouts represent transfers from GoCardless to a
-    # [creditor](#whitelabel-partner-endpoints-creditors). Each payout contains
-    # the funds collected from one or many [payments](#core-endpoints-payments).
-    # Payouts are created automatically after a payment has been successfully
-    # collected.
+    # [creditor](#core-endpoints-creditors). Each payout contains the funds
+    # collected from one or many [payments](#core-endpoints-payments). Payouts
+    # are created automatically after a payment has been successfully collected.
     class Payout
       attr_reader :amount
       attr_reader :arrival_date
@@ -23,6 +22,7 @@ module GoCardlessPro
       attr_reader :currency
       attr_reader :deducted_fees
       attr_reader :id
+      attr_reader :payout_type
       attr_reader :reference
       attr_reader :status
 
@@ -38,6 +38,7 @@ module GoCardlessPro
         @deducted_fees = object['deducted_fees']
         @id = object['id']
         @links = object['links']
+        @payout_type = object['payout_type']
         @reference = object['reference']
         @status = object['status']
         @response = response
@@ -49,7 +50,7 @@ module GoCardlessPro
 
       # Return the links that the resource has
       def links
-        @links_links ||= Links.new(@links)
+        @payout_links ||= Links.new(@links)
       end
 
       # Provides the payout resource as a hash of all its readable attributes
@@ -59,7 +60,7 @@ module GoCardlessPro
 
       class Links
         def initialize(links)
-          @links = links
+          @links = links || {}
         end
 
         def creditor