gocardless_pro 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bc56592c0c41639dd981845de276d9634b423c9c
+  data.tar.gz: 54d4dd9ed407bb39e3ce73de1fe0acfab24d3b61
+SHA512:
+  metadata.gz: 48da3d84a089b8b8de211e397c21bdb8c4c495c743b22286a90f975a2858be91469f80e0d14be88efeb29592f4829ac69a371177daae2a918d7374bb85b5297b
+  data.tar.gz: c328b8e0cd31285c2979c80bf79854e65b672352d3f7fdc3c0df4f655de32f91a34cdbab950a164fccc5974ef1859790578919eafe210ff0a207b0e2ecb0a137

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 GoCardless
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# Ruby Client for GoCardless Pro API
+
+- [YARD Docs](http://gocardless.github.io/pro-client-ruby/)
+- [GoCardless Pro API Docs](https://developer.gocardless.com/pro/)
+- [RubyGems](https://rubygems.org/gems/gocardless_pro)
+
+This client is still in beta and is subject to change. Until a stable major version is released you should expect breaking changes.
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'gocardless_pro'
+```
+
+And then load it into your application:
+
+```ruby
+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`, which is enumerable.
+- 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 the live one.
+
+```rb
+@client = GoCardlessPro::Client.new(
+  token: ENV["GOCARDLESS_TOKEN"]
+)
+```
+
+### GET requests
+
+You can make a request to get a list of resources using the `list` method:
+
+```rb
+@client.customers.list
+```
+
+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).
+
+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.list(params: { limit: 400 })
+```
+
+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|
+  p customer.given_name
+end
+```
+
+In the case where a url parameter is needed, the method signature will contain required arguments:
+
+```rb
+@client.customers.get(customers_id)
+```
+
+As with list, the last argument can be an options hash, with any URL parameters given under the `params` key:
+
+```rb
+@client.customers.get(customers_id, params: { limit: 200 })
+```
+
+### POST/PUT Requests
+
+For POST and PUT requests you need to pass in the body in under the `params` key:
+
+```rb
+@client.customers.create(
+  params: {
+    first_name: "Pete",
+    last_name: "Hamilton",
+    ...
+  }
+)
+```
+
+As with GET requests, if any parameters are required they come first:
+
+```rb
+@client.customers.update(customer_id, {...})
+```
+
+### Custom Headers
+
+If you need to pass in a custom header to an endpoint, you can pass in a `headers` object to the options hash:
+
+```rb
+@client.helpers.mandate({
+  params: {
+    account_number: 200000,
+    ...
+  },
+  headers: {
+    'Accept': 'application/pdf'
+  }
+})
+```
+
+There are very few endpoints in the API that require custom headers. Currently, the only ones that do are [helpers](https://developer.gocardless.com/pro/#api-endpoints-helpers).
+
+### Handling failures
+
+When an API returns an error, the client __will raise__ an error that corresponds to the type of error. All errors subclass `GoCardless::Error`. There are four errors that could be thrown:
+
+- `GoCardless::GoCardlessError`
+- `GoCardless::InvalidApiUsageError`
+- `GoCardless::InvalidStateError`
+- `GoCardless::ValidationError`
+
+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:
+
+- `#documentation_url`
+- `#message`
+- `#type`
+- `#code`
+- `#request_id`
+- `#errors`
+
+## 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).
+
+1. Add backports to your Gemfile
+   ```gem 'backports'```
+2. Require lazy enumerables
+   ```require 'backports/2.0.0/enumerable/lazy.rb'```
+
+## 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!__

data/circle.yml

@@ -0,0 +1,3 @@
+machine:
+  ruby:
+    version: 2.0.0-p353

data/demo.rb

@@ -0,0 +1,9 @@
+ require_relative 'lib/gocardless_pro'
+
+@client = GoCardlessPro::Client.new(
+  access_token: ENV["GOCARDLESS_TOKEN"],
+  environment: :sandbox
+)
+
+puts "Your first customer:"
+puts "-> #{@client.customers.list.records.first.inspect}"

data/gocardless_pro.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gocardless_pro/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "gocardless_pro"
+  spec.version       = GoCardlessPro::VERSION
+  spec.authors       = %w(GoCardless)
+  spec.email         = %w(engineering@gocardless.com)
+  spec.summary       = %q{A gem for calling the GoCardless Pro API}
+  spec.homepage      = "https://github.com/gocardless/gocardless-pro-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  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 'yard', '~> 0.8.7.6'
+
+  spec.add_dependency 'faraday', ['>= 0.8.9', '< 0.10']
+end

data/lib/gocardless_pro.rb

@@ -0,0 +1,73 @@
+# encoding: utf-8
+#
+# WARNING: Do not edit by hand, this file was generated by Crank:
+#
+#   https://github.com/gocardless/crank
+#
+
+require 'json'
+require 'zlib'
+require 'faraday'
+require 'time'
+
+require 'uri'
+
+module GoCardlessPro
+end
+
+version_file = 'gocardless_pro/version'
+
+if File.file? File.expand_path("#{version_file}.rb", File.dirname(__FILE__))
+  require_relative version_file
+else
+  GoCardlessPro::VERSION = ''
+end
+
+require_relative 'gocardless_pro/api_service'
+require_relative 'gocardless_pro/list_response'
+require_relative 'gocardless_pro/error'
+require_relative 'gocardless_pro/error/validation_error'
+require_relative 'gocardless_pro/error/gocardless_error'
+require_relative 'gocardless_pro/error/invalid_api_usage_error'
+require_relative 'gocardless_pro/error/invalid_state_error'
+require_relative 'gocardless_pro/paginator'
+require_relative 'gocardless_pro/request'
+require_relative 'gocardless_pro/response'
+
+require_relative 'gocardless_pro/resources/creditor'
+require_relative 'gocardless_pro/services/creditors_service'
+
+require_relative 'gocardless_pro/resources/creditor_bank_account'
+require_relative 'gocardless_pro/services/creditor_bank_accounts_service'
+
+require_relative 'gocardless_pro/resources/customer'
+require_relative 'gocardless_pro/services/customers_service'
+
+require_relative 'gocardless_pro/resources/customer_bank_account'
+require_relative 'gocardless_pro/services/customer_bank_accounts_service'
+
+require_relative 'gocardless_pro/resources/event'
+require_relative 'gocardless_pro/services/events_service'
+
+require_relative 'gocardless_pro/resources/helper'
+require_relative 'gocardless_pro/services/helpers_service'
+
+require_relative 'gocardless_pro/resources/mandate'
+require_relative 'gocardless_pro/services/mandates_service'
+
+require_relative 'gocardless_pro/resources/payment'
+require_relative 'gocardless_pro/services/payments_service'
+
+require_relative 'gocardless_pro/resources/payout'
+require_relative 'gocardless_pro/services/payouts_service'
+
+require_relative 'gocardless_pro/resources/redirect_flow'
+require_relative 'gocardless_pro/services/redirect_flows_service'
+
+require_relative 'gocardless_pro/resources/refund'
+require_relative 'gocardless_pro/services/refunds_service'
+
+require_relative 'gocardless_pro/resources/subscription'
+require_relative 'gocardless_pro/services/subscriptions_service'
+
+require_relative 'gocardless_pro/client.rb'

data/lib/gocardless_pro/api_service.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+#
+# WARNING: Do not edit by hand, this file was generated by Crank:
+#
+#   https://github.com/gocardless/crank
+#
+require 'uri'
+require 'base64'
+
+module GoCardlessPro
+  # GoCardless Pro API
+  class ApiService
+    # Initialize an APIService
+    #
+    # @param url [String] the URL to make requests to
+    # @param key [String] the API Key ID to use
+    # @param secret [String] the API key secret to use
+    # @param options [Hash] additional options to use when creating the service
+    def initialize(url, token, options = {})
+      @url = url
+      root_url, @path_prefix = unpack_url(url)
+      http_adapter = options[:http_adapter] || [:net_http]
+      @connection = Faraday.new(url: root_url) do |faraday|
+        faraday.adapter(*http_adapter)
+      end
+
+      @headers = options[:default_headers] || {}
+      @headers['Authorization'] = "Bearer #{token}"
+    end
+
+    # Make a request to the API
+    #
+    # @param method [Symbol] the method to use to make the request
+    # @param path [String] the URL (without the base domain) to make the request to
+    # @param options [Hash] the options hash
+    def make_request(method, path, options = {})
+      fail ArgumentError, 'options must be a hash' unless options.is_a?(Hash)
+      options[:headers] ||= {}
+      options[:headers] = @headers.merge(options[:headers])
+      Request.new(@connection, method, @path_prefix + path, options).request
+    end
+
+    # inspect the API Service
+    def inspect
+      url = URI.parse(@url)
+      url.password = 'REDACTED' unless url.password.nil?
+      "#<GoCardlessPro::Client url=\"#{url}\">"
+    end
+    alias_method :to_s, :inspect
+
+    private
+
+    def unpack_url(url)
+      path = URI.parse(url).path
+      [URI.join(url).to_s, path == '/' ? '' : path]
+    end
+  end
+end

data/lib/gocardless_pro/client.rb

@@ -0,0 +1,135 @@
+module GoCardlessPro
+  # A class for working with and talking to the GoCardless API
+  class Client
+    extend Forwardable
+
+    # Access to the service for creditor to make API calls
+    def creditors
+      @creditors ||= Services::CreditorsService.new(@api_service)
+    end
+
+    # Access to the service for creditor_bank_account to make API calls
+    def creditor_bank_accounts
+      @creditor_bank_accounts ||= Services::CreditorBankAccountsService.new(@api_service)
+    end
+
+    # Access to the service for customer to make API calls
+    def customers
+      @customers ||= Services::CustomersService.new(@api_service)
+    end
+
+    # Access to the service for customer_bank_account to make API calls
+    def customer_bank_accounts
+      @customer_bank_accounts ||= Services::CustomerBankAccountsService.new(@api_service)
+    end
+
+    # Access to the service for event to make API calls
+    def events
+      @events ||= Services::EventsService.new(@api_service)
+    end
+
+    # Access to the service for helper to make API calls
+    def helpers
+      @helpers ||= Services::HelpersService.new(@api_service)
+    end
+
+    # Access to the service for mandate to make API calls
+    def mandates
+      @mandates ||= Services::MandatesService.new(@api_service)
+    end
+
+    # Access to the service for payment to make API calls
+    def payments
+      @payments ||= Services::PaymentsService.new(@api_service)
+    end
+
+    # Access to the service for payout to make API calls
+    def payouts
+      @payouts ||= Services::PayoutsService.new(@api_service)
+    end
+
+    # Access to the service for redirect_flow to make API calls
+    def redirect_flows
+      @redirect_flows ||= Services::RedirectFlowsService.new(@api_service)
+    end
+
+    # Access to the service for refund to make API calls
+    def refunds
+      @refunds ||= Services::RefundsService.new(@api_service)
+    end
+
+    # Access to the service for subscription to make API calls
+    def subscriptions
+      @subscriptions ||= Services::SubscriptionsService.new(@api_service)
+    end
+
+    # Get a Client configured to use HTTP Basic authentication with the GC Api
+    #
+    # @param options [Hash<Symbol,String>] configuration for creating the client
+    # @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.
+    # @return [Client] A client configured to use the API with HTTP Basic
+    #   authentication.
+    #
+    def initialize(options)
+      access_token = options.delete(:access_token) || fail('No Access Token given to GoCardless Client')
+      environment = options.delete(:environment) || :live
+      url = options.delete(:url) || url_for_environment(environment)
+      options = custom_options(options)
+      @api_service = ApiService.new(url, access_token, options)
+    end
+
+    private
+
+    def url_for_environment(environment)
+      if environment === :live
+        'https://api.gocardless.com'
+      elsif environment === :sandbox
+        'https://api-sandbox.gocardless.com'
+      else
+        fail "Unknown environment key: #{environment}"
+      end
+    end
+
+    # Get customized options.
+    def custom_options(options)
+      return default_options if options.nil?
+
+      return default_options.merge(options) unless options[:default_headers]
+
+      opts = default_options.merge(options)
+      opts[:default_headers] = default_options[:default_headers].merge(options[:default_headers])
+
+      opts
+    end
+
+    # Get the default options.
+    def default_options
+      {
+        default_headers: {
+          'GoCardless-Version' => '2015-04-29',
+          'User-Agent' => "#{user_agent}",
+          'Content-Type' => 'application/json'
+        }
+      }
+    end
+
+    def user_agent
+      @user_agent ||=
+        begin
+          gem_name = 'gocardless_pro'
+          gem_info = "#{gem_name}"
+          gem_info += "/v#{ GoCardlessPro::VERSION}" if defined?(GoCardlessPro::VERSION)
+          ruby_engine = defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby'
+          ruby_version = RUBY_VERSION
+          ruby_version += " p#{RUBY_PATCHLEVEL}" if defined?(RUBY_PATCHLEVEL)
+          comment = ["#{ruby_engine} #{ruby_version}"]
+          comment << "gocardless_pro v#{ GoCardlessPro::VERSION}"
+          comment << "faraday v#{Faraday::VERSION}"
+          comment << RUBY_PLATFORM if defined?(RUBY_PLATFORM)
+          "#{gem_info} (#{comment.join('; ')})"
+        end
+    end
+  end
+end