gocardless 0.1.0

data/.gitignore

@@ -0,0 +1,10 @@
+lib/*seed*.rb
+lib/example.rb
+lib/*test*.rb
+doc/
+Gemfile.lock
+gocardless*.gem
+.yardoc
+.yardopts
+gocardless-*.gem
+gocardless-ruby.zip

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,12 @@
+source :rubygems
+
+gemspec
+
+group :development do
+  gem "guard", "~> 0.8.8"
+  if RUBY_PLATFORM.downcase.include?("darwin")
+    gem "guard-rspec", "~> 0.5.4"
+    gem "rb-fsevent", "~> 0.4.3.1"
+    gem "growl_notify", "~> 0.0.3"
+  end
+end

data/Guardfile

@@ -0,0 +1,6 @@
+guard 'rspec', :version => 2, :cli => '--color --format doc' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/gocardless/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch('lib/gocardless.rb') { "spec/gocardless_spec.rb" }
+  watch('spec/spec_helper.rb') { "spec" }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 GoCardless
+
+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,15 @@
+![GoCardless](https://gocardless.com/resources/logo.png)
+
+## GoCardless Ruby Client Library
+
+The GoCardless Ruby client provides a simple Ruby interface to the GoCardless
+API.
+
+If you want to use the library as an individual merchant, refer to the
+[merchant guide](https://gocardless.com/docs/ruby/merchant_client_guide). If
+you want to support multiple merchant accounts, see the
+[partner guide](https://gocardless.com/docs/ruby/partner_client_guide).
+
+The full API reference is available at on
+[rubydoc.info](http://rubydoc.info/github/gocardless/gocardless-ruby/master/frames).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb'].reject { |f| f.match(/seed|example/) }
+end
+

data/gocardless.gemspec

@@ -0,0 +1,22 @@
+require File.expand_path('../lib/gocardless/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.add_runtime_dependency "oauth2", "~> 0.5.0.rc1"
+  gem.add_runtime_dependency "json", "~> 1.5.3"
+
+  gem.add_development_dependency 'rspec', '~> 2.6'
+  gem.add_development_dependency 'mocha', '~> 0.9.12'
+  gem.add_development_dependency "yard", "~> 0.7.3"
+  gem.add_development_dependency "redcarpet", "~> 1.17.2"
+
+  gem.authors = ["Harry Marr"]
+  gem.description = %q{A Ruby wrapper for the GoCardless API}
+  gem.email = ['harry@gocardless.com']
+  gem.files = `git ls-files`.split("\n")
+  gem.homepage = 'https://github.com/gocardless/gocardless-ruby'
+  gem.name = 'gocardless'
+  gem.require_paths = ['lib']
+  gem.summary = %q{Ruby wrapper for the GoCardless API}
+  gem.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.version = GoCardless::VERSION.dup
+end

data/lib/gocardless.rb

@@ -0,0 +1,32 @@
+module GoCardless
+  require 'gocardless/errors'
+  require 'gocardless/utils'
+  require 'gocardless/resource'
+  require 'gocardless/subscription'
+  require 'gocardless/pre_authorization'
+  require 'gocardless/user'
+  require 'gocardless/bill'
+  require 'gocardless/payment'
+  require 'gocardless/merchant'
+  require 'gocardless/client'
+
+  class << self
+    attr_accessor :environment
+    attr_reader :account_details, :client
+
+    def account_details=(details)
+      raise ClientError.new("You must provide a token") unless details[:token]
+      @account_details = details
+      @client = Client.new(details)
+    end
+
+    %w(new_subscription_url new_pre_authorization_url new_bill_url confirm_resource).each do |name|
+      class_eval <<-EOM
+        def #{name}(*args)
+          raise ClientError.new('Need to set account_details first') unless @client
+          @client.send(:#{name}, *args)
+        end
+      EOM
+    end
+  end
+end

data/lib/gocardless/bill.rb

@@ -0,0 +1,44 @@
+module GoCardless
+  class Bill < Resource
+    self.endpoint = '/bills/:id'
+
+    creatable
+
+    attr_accessor :amount
+    attr_accessor :source_type
+    attr_accessor :description
+
+    # @attribute source_id
+    # @return [Integer] the ID of the bill's source (eg subscription, pre_authorization)
+    attr_accessor :source_id
+
+    reference_accessor :merchant_id, :user_id, :payment_id
+    date_accessor :created_at
+
+    def source
+      klass = GoCardless.const_get(Utils.camelize(source_type.to_s))
+      klass.find_with_client(client, @source_id)
+    end
+
+    def source=(obj)
+      klass = obj.class.to_s.split(':').last
+      if !%w{Subscription PreAuthorization}.include?(klass)
+        raise ArgumentError, ("Object must be an instance of Subscription or "
+                              "PreAuthorization")
+      end
+      @source_id = obj.id
+      @source_type = Utils.underscore(klass)
+    end
+
+    def save
+      save_data({
+        :bill => {
+          :pre_authorization_id => self.source_id,
+          :amount => self.amount,
+          :description => self.description,
+        }
+      })
+      self
+    end
+  end
+end

data/lib/gocardless/client.rb

@@ -0,0 +1,352 @@
+require 'rubygems'
+require 'json'
+require 'oauth2'
+require 'openssl'
+require 'uri'
+require 'cgi'
+require 'time'
+
+module GoCardless
+  class Client
+    BASE_URLS = {
+      :production => 'https://gocardless.com',
+      :sandbox    => 'https://sandbox.gocardless.com',
+    }
+    API_PATH = '/api/v1'
+
+    class << self
+      def base_url=(url)
+        @base_url = url.sub(%r|/$|, '')
+      end
+
+      def base_url
+        @base_url || BASE_URLS[GoCardless.environment || :production]
+      end
+
+      def api_url
+        "#{base_url}#{API_PATH}"
+      end
+    end
+
+    def initialize(args = {})
+      Utils.symbolize_keys! args
+      @app_id = args[:app_id]
+      @app_secret = args[:app_secret]
+      raise ClientError.new("You must provide an app_id") unless @app_id
+      raise ClientError.new("You must provide an app_secret") unless @app_secret
+
+      @oauth_client = OAuth2::Client.new(@app_id, @app_secret,
+                                         :site => self.class.base_url,
+                                         :token_url => '/oauth/access_token')
+
+      self.access_token = args[:token] if args[:token]
+    end
+
+    # Generate the OAuth authorize url
+    # @param [Hash] options parameters to be included in the url.
+    #   +:redirect_uri+ is required.
+    # @return [String] the authorize url
+    def authorize_url(options)
+      raise ArgumentError, ':redirect_uri required' unless options[:redirect_uri]
+      params = {
+        :client_id => @app_id,
+        :response_type => 'code',
+        :scope => 'manage_merchant'
+      }
+      @oauth_client.authorize_url(params.merge(options))
+    end
+    alias :new_merchant_url :authorize_url
+
+    # @method fetch_access_token(auth_code, options)
+    # @param [String] auth_code to exchange for the access_token
+    # @return [String] the access_token required to make API calls to resources
+    def fetch_access_token(auth_code, options)
+      raise ArgumentError, ':redirect_uri required' unless options[:redirect_uri]
+      @access_token = @oauth_client.auth_code.get_token(auth_code, options)
+      self.access_token
+    end
+
+    # @return [String] a serialized form of the access token with its scope
+    def access_token
+      if @access_token
+        scope = @access_token.params[:scope] || @access_token.params['scope']
+        "#{@access_token.token} #{scope}".strip
+      end
+    end
+
+    # Set the client's access token
+    #
+    # @param [String] token a string with format <code>"#{token} #{scope}"</code>
+    #   (as returned by {#access_token})
+    def access_token=(token)
+      token, scope = token.split(' ', 2)
+      if scope.nil?
+        raise ArgumentError, ('Access token missing scope. Use format '
+                              '<token> <scope>')
+      end
+      @access_token = OAuth2::AccessToken.new(@oauth_client, token)
+      @access_token.params['scope'] = scope
+    end
+
+    # Issue an GET request to the API server
+    #
+    # @note this method is for internal use
+    # @param [String] path the path that will be added to the API prefix
+    # @param [Hash] params query string parameters
+    # @return [Hash] hash the parsed response data
+    def api_get(path, params = {})
+      request(:get, "#{API_PATH}#{path}", :params => params).parsed
+    end
+
+    # Issue a POST request to the API server
+    #
+    # @note this method is for internal use
+    # @param [String] path the path that will be added to the API prefix
+    # @param [Hash] data a hash of data that will be sent as the request body
+    # @return [Hash] hash the parsed response data
+    def api_post(path, data = {})
+      request(:post, "#{API_PATH}#{path}", :data => data).parsed
+    end
+
+    # Issue a PUT request to the API server
+    #
+    # @note this method is for internal use
+    # @param [String] path the path that will be added to the API prefix
+    # @param [Hash] data a hash of data that will be sent as the request body
+    # @return [Hash] hash the parsed response data
+    def api_put(path, data = {})
+      request(:put, "#{API_PATH}#{path}", :data => data).parsed
+    end
+
+    # @method merchant
+    # @return [Merchant] the merchant associated with the client's access token
+    def merchant
+      raise ClientError, 'Access token missing' unless @access_token
+      Merchant.new_with_client(self, api_get("/merchants/#{merchant_id}"))
+    end
+
+    # @method subscripton(id)
+    # @param [String] id of the subscription
+    # @return [Subscription] the subscription matching the id requested
+    def subscription(id)
+      Subscription.find_with_client(self, id)
+    end
+
+    # @method pre_authorization(id)
+    # @param [String] id of the pre_authorization
+    # @return [PreAuthorization] the pre_authorization matching the id requested
+    def pre_authorization(id)
+      PreAuthorization.find_with_client(self, id)
+    end
+
+    # @method user(id)
+    # @param [String] id of the user
+    # @return [User] the User matching the id requested
+    def user(id)
+      User.find_with_client(self, id)
+    end
+
+    # @method bill(id)
+    # @param [String] id of the bill
+    # @return [Bill] the Bill matching the id requested
+    def bill(id)
+      Bill.find_with_client(self, id)
+    end
+
+    # @method payment(id)
+    # @param [String] id of the payment
+    # @return [Payment] the payment matching the id requested
+    def payment(id)
+      Payment.find_with_client(self, id)
+    end
+
+    # Create a new bill under a given pre-authorization
+    # @see PreAuthorization#create_bill
+    #
+    # @param [Hash] attrs must include +:pre_authorization_id+ and +:amount+
+    # @return [Bill] the created bill object
+    def create_bill(attrs)
+      Bill.new_with_client(self, attrs).save
+    end
+
+    # Generate the URL for creating a new subscription. The parameters passed
+    # in define various attributes of the subscription. Redirecting a user to
+    # the resulting URL will show them a page where they can approve or reject
+    # the subscription described by the parameters. Note that this method
+    # automatically includes the nonce, timestamp and signature.
+    #
+    # @param [Hash] params the subscription parameters
+    # @return [String] the generated URL
+    def new_subscription_url(params)
+      new_limit_url(:subscription, params)
+    end
+
+    # Generate the URL for creating a new pre authorization. The parameters
+    # passed in define various attributes of the pre authorization. Redirecting
+    # a user to the resulting URL will show them a page where they can approve
+    # or reject the pre authorization described by the parameters. Note that
+    # this method automatically includes the nonce, timestamp and signature.
+    #
+    # @param [Hash] params the pre authorization parameters
+    # @return [String] the generated URL
+    def new_pre_authorization_url(params)
+      new_limit_url(:pre_authorization, params)
+    end
+
+    # Generate the URL for creating a new bill. The parameters passed in define
+    # various attributes of the bill. Redirecting a user to the resulting URL
+    # will show them a page where they can approve or reject the bill described
+    # by the parameters. Note that this method automatically includes the
+    # nonce, timestamp and signature.
+    #
+    # @param [Hash] params the bill parameters
+    # @return [String] the generated URL
+    def new_bill_url(params)
+      new_limit_url(:bill, params)
+    end
+
+    # Confirm a newly-created subscription, pre-authorzation or one-off
+    # payment. This method also checks that the resource response data includes
+    # a valid signature and will raise a {SignatureError} if the signature is
+    # invalid.
+    #
+    # @param [Hash] params the response parameters returned by the API server
+    # @return [Resource] the confirmed resource object
+    def confirm_resource(params)
+      params = Utils.symbolize_keys(params)
+      # Only pull out the relevant parameters, other won't be included in the
+      # signature so will cause false negatives
+      keys = [:resource_id, :resource_type, :resource_uri, :state, :signature]
+      params = Hash[params.select { |k,v| keys.include? k }]
+      (keys - [:state]).each do |key|
+        raise ArgumentError, "Parameters missing #{key}" if !params.key?(key)
+      end
+
+      if signature_valid?(params)
+        data = {
+          :resource_id => params[:resource_id],
+          :resource_type => params[:resource_type],
+        }
+
+        credentials = Base64.encode64("#{@app_id}:#{@app_secret}")
+        credentials = credentials.gsub(/\s/, '')
+        headers = {
+          'Authorization' => "Basic #{credentials}"
+        }
+        request(:post, "#{self.class.api_url}/confirm", :data => data,
+                                                        :headers => headers)
+
+        # Initialize the correct class according to the resource's type
+        klass = GoCardless.const_get(Utils.camelize(params[:resource_type]))
+        klass.find_with_client(self, params[:resource_id])
+      else
+        raise SignatureError, 'An invalid signature was detected'
+      end
+    end
+
+  private
+
+    # Convert a hash into query-string style parameters
+    def encode_params(params, ns = nil)
+      params.map do |key,val|
+        key = ns ? "#{ns}[#{key.is_a?(Integer) ? '' : key.to_s}]" : key.to_s
+        case val
+        when Hash
+          encode_params(val, key)
+        when Array
+          encode_params(Hash[(1..val.length).zip(val)], key)
+        else
+          "#{CGI.escape(key)}=#{CGI.escape(val.to_s)}"
+        end
+      end.sort * '&'
+    end
+
+    # Send a request to the GoCardless API servers
+    #
+    # @param [Symbol] method the HTTP method to use (e.g. +:get+, +:post+)
+    # @param [String] path the path fragment of the URL
+    # @option [String] body the request body
+    # @option [Hash] params query string parameters
+    def request(method, path, opts = {})
+      raise ClientError, 'Access token missing' unless @access_token
+      opts[:headers] = {} if opts[:headers].nil?
+      opts[:headers]['Accept'] = 'application/json'
+      opts[:headers]['Content-Type'] = 'application/json' unless method == :get
+      opts[:body] = JSON.generate(opts[:data]) if !opts[:data].nil?
+      header_keys = opts[:headers].keys.map(&:to_s)
+      if header_keys.map(&:downcase).include?('authorization')
+        @oauth_client.request(method, path, opts)
+      else
+        @access_token.send(method, path, opts)
+      end
+    rescue OAuth2::Error => err
+      raise GoCardless::ApiError.new(err.response)
+    end
+
+    # Add a signature to a Hash of parameters. The signature will be generated
+    # from the app secret and the provided parameters, and should be used
+    # whenever signed data needs to be sent to GoCardless (e.g. when creating
+    # a new subscription). The signature will be added to the hash under the
+    # key +:signature+.
+    #
+    # @param [Hash] params the parameters to sign
+    # @return [Hash] the parameters with the new +:signature+ key
+    def sign_params(params)
+      msg = encode_params(params)
+      digest = OpenSSL::Digest::Digest.new('sha256')
+      params[:signature] = OpenSSL::HMAC.hexdigest(digest, @app_secret, msg)
+      params
+    end
+
+    # Check if a hash's :signature is valid
+    #
+    # @param [Hash] params the parameters to check
+    # @return [Boolean] whether or not the signature is valid
+    def signature_valid?(params)
+      params = params.clone
+      signature = params.delete(:signature)
+      sign_params(params)[:signature] == signature
+    end
+
+    # Generate a random base64-encoded string
+    #
+    # @return [String] a randomly generated string
+    def generate_nonce
+      Base64.encode64((0...45).map { rand(256).chr }.join).strip
+    end
+
+    # Generate the URL for creating a limit of type +type+, including the
+    # provided params, nonce, timestamp and signature
+    #
+    # @param [Symbol] type the limit type (+:subscription+, etc)
+    # @param [Hash] params the bill parameters
+    # @return [String] the generated URL
+    def new_limit_url(type, limit_params)
+      url = URI.parse("#{self.class.base_url}/connect/#{type}s/new")
+
+      limit_params[:merchant_id] = merchant_id
+      redirect_uri = limit_params.delete(:redirect_uri)
+
+      params = {
+        :nonce       => generate_nonce,
+        :timestamp   => Time.now.getutc.strftime('%Y-%m-%dT%H:%M:%SZ'),
+        :client_id   => @app_id,
+        type         => limit_params,
+      }
+      params[:redirect_uri] = redirect_uri unless redirect_uri.nil?
+
+      sign_params(params)
+
+      url.query = encode_params(params)
+      url.to_s
+    end
+
+    def merchant_id
+      raise ClientError, 'Access token missing' unless @access_token
+      scope = @access_token.params['scope'].split
+      perm = scope.select {|p| p.start_with?('manage_merchant:') }.first
+      perm.split(':')[1]
+    end
+  end
+end
+