gocardless_pro 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 692eca4366bdf3a3a890788b76f755784d369047
-  data.tar.gz: 810cdf0fa7569856376b29afbc1df49327ae0842
+  metadata.gz: ecf319e84ed4dfe44efbdbccfa3b78fd3a2d21fa
+  data.tar.gz: 62778f5f199f97beda830c8135d76c9b3b9db140
 SHA512:
-  metadata.gz: b095b6ab731eb0335966c3adfb0707b4e694ea0b2e2383d8bef7656efe68bd5bb03079ccc137d05027108e2079fb21242df45c1956757ac8adb11bb0b96f2904
-  data.tar.gz: b94783f280f48c02f83041fef6271f710b224a53ae52af84f8e228f594ea71611b010f123adf33cf1ba4a08179ba7b19b1c300f0381faf1db6c66558df53c760
+  metadata.gz: c44529e6d3b9d177f5c4cceded3dfb02dae73ee6c7ef5427e28574e6bb5466b804d01d4b519e60c91a948dc9b4409320701746214a4ae3f8d4e88239757a85a6
+  data.tar.gz: d0539445ad58e6dbb99e1394466261ed8e8d7b415148bf5f55ff48e0cbbe8f440d68aead63008f30bc7f0ba921b8507e447004711476c614f32eec157db7aebc

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+
+rvm:
+  - 2.3.0
+  - 2.2
+  - 2.1
+  - 2.0.0
+
+sudo: false
+
+script:
+  - bundle exec rspec spec

data/README.md

@@ -1,7 +1,17 @@
-# Ruby Client for GoCardless Pro API
+# Ruby Client for the GoCardless API
 
-- [GoCardless Pro API Docs](https://developer.gocardless.com/pro/)
-- [RubyGems](https://rubygems.org/gems/gocardless_pro)
+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)
+[![Build Status](https://travis-ci.org/gocardless/gocardless-pro-ruby.svg?branch=master)](https://travis-ci.org/gocardless/gocardless-pro-ruby)
+
+
+## Usage Examples
+
+This README will use `customers` throughout but each of the resources in the
+[API](https://developer.gocardless.com/pro/) is available in this library.
+
+### Installation
 
 Add this line to your application's Gemfile:
 
@@ -15,16 +25,11 @@ And then load it into your application:
 require 'gocardless_pro'
 ```
 
-## Usage Examples
-
-- In the case of a single response, the client will return you an instance of the resource
-- In the case of list responses, the client will return an instance of `ListResponse`.
-- You can also call `#all` to get a lazily paginated list of resource that will deal with making extra API requests to paginate through all the data
-
 ### Initialising the client
 
 The client is initialised with an Access Token.
-You can also pass in `environment` as `:sandbox` to make requests to the sandbox environment rather than production.
+You can also pass in `environment` as `:sandbox` to make requests to the sandbox
+environment rather than production.
 
 ```rb
 @client = GoCardlessPro::Client.new(
@@ -34,41 +39,61 @@ You can also pass in `environment` as `:sandbox` to make requests to the sandbox
 
 ### GET requests
 
-You can make a request to get a list of resources using the `list` method:
+You can get details about one or many resources in the API by calling the
+`#get`, `#list` and `#all` methods.
+
+#### Getting a single resource
+
+To request a single resource, use the `#get` method:
 
 ```rb
-@client.customers.list
+@client.customers.get(customer_id)
 ```
 
-This README will use `customers` throughout but each of the resources in the API is available in this library. They are defined in [`gocardless.rb`](https://github.com/gocardless/pro-client-ruby/blob/master/lib/gocardless_pro.rb#L87).
+A call to `get` returns an instance of the resource:
 
-If you need to pass any options, the last (or in the absence of URL params, the only) argument is an options hash. This is used to pass query parameters for `GET` requests:
+```rb
+p @client.customers.get(customer_id).given_name
+```
+
+#### Getting a list of resources
+
+To get a list of resources, use the `#list` method:
 
 ```rb
-@client.customers.list(params: { limit: 400 })
+@client.customers.list
 ```
 
 A call to `list` returns an instance of `GoCardlessPro::ListResponse`. You can call `records` on this to iterate through results:
 
 ```rb
-@client.customers.list.records do |customer|
+@client.customers.list.records.each do |customer|
   p customer.given_name
 end
 ```
 
-In the case where a url parameter is needed, the method signature will contain required arguments:
+If you need to pass any options, the last (or in the absence of URL params, the only) argument is an options hash. This is used to pass query parameters for `GET` requests:
 
 ```rb
-@client.customers.get(customers_id)
+@client.customers.list(params: { limit: 400 })
 ```
 
-As with list, the last argument can be an options hash, with any URL parameters given under the `params` key:
+#### Getting all resources
+
+If you want to get all of the records for a given resource type, you can use the
+`#all` method to get a lazily paginated list. `#all` will deal with making extra
+API requests to paginate through all the data for you:
 
 ```rb
-@client.customers.get(customers_id, params: { limit: 200 })
+@client.customers.all.each do |customer|
+  p customer.given_name
+end
 ```
 
-Both individual resource and `ListResponse` instances provide an `api_response` method, which lets you access the following properties of the request:
+#### Raw response details
+
+In addition to providing details of the requested resource(s), all GET requests
+give you access the following properties of the response:
 
 - `status`
 - `headers`
@@ -88,15 +113,34 @@ For POST and PUT requests you need to pass in the body in under the `params` key
 )
 ```
 
-As with GET requests, if any parameters are required they come first:
+If any parameters are required they come first:
 
 ```rb
 @client.customers.update(customer_id, {...})
 ```
 
+### Custom headers
+
+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:
+
+```rb
+@client.customers.create(
+  params: {
+    first_name: "Pete",
+    last_name: "Hamilton",
+    ...
+  },
+  headers: {
+    "Idempotency-Key": "1f9630a9-0487-418d-bd37-8b77793c9985"
+  }
+)
+```
+
 ### Handling failures
 
-When an API returns an error, the client __will raise__ an error that corresponds to the type of error. All errors subclass `GoCardlessPro::Error`. There are four errors that could be thrown:
+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`:
 
 - `GoCardlessPro::GoCardlessError`
 - `GoCardlessPro::InvalidApiUsageError`
@@ -105,7 +149,7 @@ When an API returns an error, the client __will raise__ an error that correspond
 
 These errors are fully documented in the [API documentation](https://developer.gocardless.com/pro/#overview-errors).
 
-The error has the following methods to allow you to access the information from the API response:
+All errors have the following methods to facilitate access to information in the API response:
 
 - `#documentation_url`
 - `#message`
@@ -123,12 +167,11 @@ OAuth simply provides a means by which you obtain an access token - once you hav
 We recommend using the [oauth2](https://github.com/intridea/oauth2) gem to handle the authorisation process and gain a token. For an example of this in action, see our [open-source OAuth demo app](https://github.com/gocardless/oauth-demo/blob/master/app.rb#L46).
 
 ## Supporting Ruby < 2.0.0
-
 The client only supports Ruby >= 2.0.0 out of the box due to our use of
 Enumerable::Lazy for lazy loading of paginated API resources.
 
-However, support for previous ruby versions can be added using a gem such as
-[backports](https://github.com/marcandre/backports).
+If you wish to use this gem with a previous ruby version, you should be able to
+do so with the [backports](https://github.com/marcandre/backports) gem:
 
 1. Add backports to your Gemfile
    ```gem 'backports'```
@@ -137,4 +180,4 @@ However, support for previous ruby versions can be added using a gem such as
 
 ## Contributing
 
-This client is auto-generated from Crank, a toolchain that we hope to soon open source. Issues should for now be reported on this repository. __Please do not modify the source code yourself, your changes will be overriden!__
+This client is auto-generated from Crank, a toolchain that we hope to open source soon. For now, issues should be reported on this repository. __Please do not modify the source code yourself, your changes will be overriden!__

data/gocardless_pro.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'rspec', '~> 3.1'
   spec.add_development_dependency 'webmock', '~> 1.18'
-  spec.add_development_dependency 'rubocop', '~> 0.30.0'
+  spec.add_development_dependency 'rubocop', '~> 0.35.1'
   spec.add_development_dependency 'yard', '~> 0.8.7.6'
 
   spec.add_dependency 'faraday', ['>= 0.8.9', '< 0.10']

data/lib/gocardless_pro/api_service.rb

@@ -8,7 +8,7 @@ require 'uri'
 require 'base64'
 
 module GoCardlessPro
-  # GoCardless Pro API
+  # GoCardless API
   class ApiService
     # Initialize an APIService
     #
@@ -20,7 +20,9 @@ module GoCardlessPro
       @url = url
       root_url, @path_prefix = unpack_url(url)
       http_adapter = options[:http_adapter] || [:net_http]
-      @connection = Faraday.new(url: root_url) do |faraday|
+      connection_options = options[:connection_options]
+
+      @connection = Faraday.new(root_url, connection_options) do |faraday|
         faraday.adapter(*http_adapter)
       end
 

data/lib/gocardless_pro/client.rb

@@ -74,6 +74,7 @@ module GoCardlessPro
     # @option options [Symbol] :environment the environment to connect to - one of `:live` or `:sandbox`.
     # @option options [Symbol] :access_token the API token
     # @option options [Symbol] :url the full URL used to make requests to. If you specify this, it will be used over the `environment` option.
+    # @option options [Symbol] :connection_options `Faraday` connection options hash, e.g. `{ request: { timeout: 3 } }`.
     # @return [Client] A client configured to use the API with HTTP Basic
     #   authentication.
     #
@@ -125,7 +126,7 @@ module GoCardlessPro
         begin
           gem_name = 'gocardless_pro'
           gem_info = "#{gem_name}"
-          gem_info += "/v#{ GoCardlessPro::VERSION}" if defined?(GoCardlessPro::VERSION)
+          gem_info += "/v#{GoCardlessPro::VERSION}" if defined?(GoCardlessPro::VERSION)
 
           ruby_engine = defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby'
 

data/lib/gocardless_pro/error.rb

@@ -6,6 +6,7 @@ module GoCardlessPro
     # intialize a new error
     #  @param error the error from the API
     def initialize(error)
+      fail ArgumentError, 'GoCardless errors expect a hash' unless error.is_a?(Hash)
       @error = error
     end
 
@@ -19,6 +20,16 @@ module GoCardlessPro
       @error['message']
     end
 
+    def to_s
+      if errors.any?
+        errors
+          .map { |err| "#{err['field']} #{err['message']}" }
+          .join(', ')
+      else
+        @error['message']
+      end
+    end
+
     # access the type from the response
     def type
       @error['type']
@@ -36,7 +47,7 @@ module GoCardlessPro
 
     # access the errors from the response
     def errors
-      @error['errors']
+      @error.fetch('errors', [])
     end
   end
 end

data/lib/gocardless_pro/resources/mandate.rb

@@ -26,6 +26,8 @@ module GoCardlessPro
 
       attr_reader :next_possible_charge_date
 
+      attr_reader :payments_require_approval
+
       attr_reader :reference
 
       attr_reader :scheme
@@ -41,6 +43,7 @@ module GoCardlessPro
         @links = object['links']
         @metadata = object['metadata']
         @next_possible_charge_date = object['next_possible_charge_date']
+        @payments_require_approval = object['payments_require_approval']
         @reference = object['reference']
         @scheme = object['scheme']
         @status = object['status']

data/lib/gocardless_pro/resources/payout.rb

@@ -20,6 +20,8 @@ module GoCardlessPro
     class Payout
       attr_reader :amount
 
+      attr_reader :arrival_date
+
       attr_reader :created_at
 
       attr_reader :currency
@@ -35,6 +37,7 @@ module GoCardlessPro
         @object = object
 
         @amount = object['amount']
+        @arrival_date = object['arrival_date']
         @created_at = object['created_at']
         @currency = object['currency']
         @id = object['id']

data/lib/gocardless_pro/resources/redirect_flow.rb

@@ -11,27 +11,28 @@ require 'uri'
 module GoCardlessPro
   # A module containing classes for each of the resources in the GC Api
   module Resources
-    # Redirect flows enable you to use GoCardless Pro's [hosted payment
+    # Redirect flows enable you to use GoCardless' [hosted payment
     # pages](https://pay-sandbox.gocardless.com/AL000000AKFPFF) to set up mandates
     # with your customers. These pages are fully compliant and have been
-    # translated into Dutch, French, German, Italian, Portuguese and Spanish.
-    #
+    # translated into Dutch, French, German, Italian, Portuguese, Spanish and
+    # Swedish.
     #
     # The overall flow is:
     #
-    # 1. You [create](#create-a-redirect-flow)
-    # a redirect flow for your customer, and redirect them to the returned
-    # redirect url, e.g. `https://pay.gocardless.com/flow/RE123`.
+    # 1. You
+    # [create](#create-a-redirect-flow) a redirect flow for your customer, and
+    # redirect them to the returned redirect url, e.g.
+    # `https://pay.gocardless.com/flow/RE123`.
+    #
+    # 2. Your customer supplies
+    # their name, email, address, and bank account details, and submits the form.
+    # This securely stores their details, and redirects them back to your
+    # `success_redirect_url` with `redirect_flow_id=RE123` in the querystring.
     #
-    # 2. Your
-    # customer supplies their name, email, address, and bank account details, and
-    # submits the form. This securely stores their details, and redirects them
-    # back to your `success_redirect_url` with `redirect_flow_id=RE123` in the
-    # querystring.
     #
-    # 3. You [complete](#complete-a-redirect-flow) the
-    # redirect flow, which creates a [customer](#core-endpoints-customers),
-    # [customer bank account](#core-endpoints-customer-bank-accounts), and
+    # 3. You [complete](#complete-a-redirect-flow) the redirect flow, which
+    # creates a [customer](#core-endpoints-customers), [customer bank
+    # account](#core-endpoints-customer-bank-accounts), and
     # [mandate](#core-endpoints-mandates), and returns the ID of the mandate. You
     # may wish to create a [subscription](#core-endpoints-subscriptions) or
     # [payment](#core-endpoints-payments) at this point.

data/lib/gocardless_pro/services/bank_details_lookups_service.rb

@@ -12,8 +12,17 @@ module GoCardlessPro
     class BankDetailsLookupsService < BaseService
       # Performs a bank details lookup.
       #
+      # As part of the lookup a modulus check and
+      # reachability check are performed.
+      #
       # Bank account details may be supplied
       # using [local details](#appendix-local-bank-details) or an IBAN.
+      #
+      # _Note:_
+      # Usage of this endpoint is monitored. If your organisation relies on GoCardless
+      # for
+      # modulus or reachability checking but not for payment collection, please
+      # get in touch.
       # Example URL: /bank_details_lookups
       # @param options [Hash] parameters as a hash, under a params key.
       def create(options = {})
@@ -25,6 +34,7 @@ module GoCardlessPro
         response = make_request(:post, path, options)
 
         return if response.body.nil?
+
         Resources::BankDetailsLookup.new(unenvelope_body(response.body), response)
       end
 

data/lib/gocardless_pro/services/creditor_bank_accounts_service.rb

@@ -22,6 +22,7 @@ module GoCardlessPro
         response = make_request(:post, path, options)
 
         return if response.body.nil?
+
         Resources::CreditorBankAccount.new(unenvelope_body(response.body), response)
       end
 
@@ -59,11 +60,12 @@ module GoCardlessPro
       # @param identity       # Unique identifier, beginning with "BA".
       # @param options [Hash] parameters as a hash, under a params key.
       def get(identity, options = {})
-        path = sub_url('/creditor_bank_accounts/:identity',           'identity' => identity)
+        path = sub_url('/creditor_bank_accounts/:identity', 'identity' => identity)
 
         response = make_request(:get, path, options)
 
         return if response.body.nil?
+
         Resources::CreditorBankAccount.new(unenvelope_body(response.body), response)
       end
 
@@ -80,7 +82,7 @@ module GoCardlessPro
       # @param identity       # Unique identifier, beginning with "BA".
       # @param options [Hash] parameters as a hash, under a params key.
       def disable(identity, options = {})
-        path = sub_url('/creditor_bank_accounts/:identity/actions/disable',           'identity' => identity)
+        path = sub_url('/creditor_bank_accounts/:identity/actions/disable', 'identity' => identity)
 
         params = options.delete(:params) || {}
         options[:params] = {}
@@ -88,6 +90,7 @@ module GoCardlessPro
         response = make_request(:post, path, options)
 
         return if response.body.nil?
+
         Resources::CreditorBankAccount.new(unenvelope_body(response.body), response)
       end
 

data/lib/gocardless_pro/services/creditors_service.rb

@@ -22,6 +22,7 @@ module GoCardlessPro
         response = make_request(:post, path, options)
 
         return if response.body.nil?
+
         Resources::Creditor.new(unenvelope_body(response.body), response)
       end
 
@@ -59,11 +60,12 @@ module GoCardlessPro
       # @param identity       # Unique identifier, beginning with "CR".
       # @param options [Hash] parameters as a hash, under a params key.
       def get(identity, options = {})
-        path = sub_url('/creditors/:identity',           'identity' => identity)
+        path = sub_url('/creditors/:identity', 'identity' => identity)
 
         response = make_request(:get, path, options)
 
         return if response.body.nil?
+
         Resources::Creditor.new(unenvelope_body(response.body), response)
       end
 
@@ -74,7 +76,7 @@ module GoCardlessPro
       # @param identity       # Unique identifier, beginning with "CR".
       # @param options [Hash] parameters as a hash, under a params key.
       def update(identity, options = {})
-        path = sub_url('/creditors/:identity',           'identity' => identity)
+        path = sub_url('/creditors/:identity', 'identity' => identity)
 
         params = options.delete(:params) || {}
         options[:params] = {}
@@ -82,6 +84,7 @@ module GoCardlessPro
         response = make_request(:put, path, options)
 
         return if response.body.nil?
+
         Resources::Creditor.new(unenvelope_body(response.body), response)
       end