supreme 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Fingertips, Manfred Stienstra <manfred@fngtps.com>
+
+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,67 @@
+A Ruby client that allows you to do iDEAL transactions through the [Mollie iDEAL API](http://www.mollie.nl/betaaldiensten/ideal).
+
+## Install
+
+$ gem install supreme
+
+## Payment flow
+
+You start by setting the mode of the library to either :test or :live. The default is :test, so
+for tests you don't have to change anything.
+  
+    Supreme.mode = :live
+
+You can choose to set the partner (client) id globally so you don't have to include it with every
+call.
+
+    Supreme.partner_id = '000000'
+
+Then you get a list of supported banks. Note that this list can change at any time, so be conservative
+with caching these values.
+
+    Supreme.api.bank_list #=> [["ABN AMRO", "0031"], ["Postbank", "0721"], ["Rabobank", "0021"]]
+
+When the user has selected a bank, you start a transaction.
+
+    transaction = Supreme.api.fetch(
+      :bank_id => '0031',
+      :amount => 1299,
+      :description => 'A fluffy bunny',
+      :return_url => 'http://example.com/payments/as45re/thanks',
+      :report_url => 'http://example.com/payments/as45re'
+    )
+    transaction.transaction_id #=> '482d599bbcc7795727650330ad65fe9b'
+
+Keep the transaction_id around for reference and redirect the customer to the indicated URL.
+
+    Location: #{transaction.url}
+
+Once the transaction is done you will receive a GET on the report_url with a ‘transaction_id’ parameter
+to indicate that the transaction has changed state. You will need to check the status of the transaction.
+  
+    status = Supreme.api.check(
+      :transaction_id => '482d599bbcc7795727650330ad65fe9b'
+    )
+  
+    # Note that the status will only be paid? after the first check, for each consecutive call
+    # paid? will be false regardless of the outcome of the transaction.
+    #
+    # We use success? and make sure we don't deliver the product more than once.
+    if status.success?
+      # Update the local status of the payment
+    end
+
+When the customer returns to your site it returns with its transaction_id attached to your provided URL.
+You can present a page depending on the status of the payment.
+
+## Errors
+
+When an error occurs you get a Supreme::Error object instead of the response object you expected.
+
+    status = Supreme.api.check(
+      :transaction_id => '482d599bbcc7795727650330ad65fe9b'
+    )
+    
+    if status.error?
+      log("#{status.message} (#{status.code})")
+    end

data/lib/supreme.rb

@@ -0,0 +1,47 @@
+# Supreme is a Ruby for doing iDEAL transactions through the Mollie iDEAL API.
+# http://www.mollie.nl/betaaldiensten/ideal
+#
+# To get going read the documentation for Supreme and Supreme::API.
+
+require 'supreme/uri'
+require 'supreme/api'
+require 'supreme/version'
+require 'supreme/response'
+
+module Supreme
+  class << self
+    # Holds either :test or :live to signal whether to run in test or live mode. The default
+    # value is :test.
+    attr_accessor :mode
+    
+    # Your Mollie Partner ID, you can find it under ‘Accountgegevens’ in the settings for your account on mollie.nl.
+    attr_accessor :partner_id
+  end
+  
+  # Returns an instance of the API with settings from the Supreme class accessors. If you need to handle
+  # multiple accounts in your application you will need to instantiate multiple API instances yourself.
+  def self.api
+    Supreme::API.new(
+      :mode       => mode,
+      :partner_id => partner_id
+    )
+  end
+  
+  # Resets the class back to the default settings
+  def self.reset!
+    self.mode = :test
+    self.partner_id = nil
+  end
+  
+  reset!
+  
+  private
+  
+  def self.translate_hash_keys(translation, hash)
+    translated = {}
+    hash.each do |key, value|
+      new_key = translation[key.to_sym] || translation[key.to_s] ||key
+      translated[new_key.to_s] = value
+    end; translated
+  end
+end

data/lib/supreme/api.rb

@@ -0,0 +1,148 @@
+require 'uri'
+require 'rest'
+
+module Supreme
+  class API
+    ENDPOINT = ::URI.parse("https://secure.mollie.nl/xml/ideal")
+    
+    attr_accessor :mode, :partner_id
+    
+    # Creates a new API instance. Normally you would use <tt>Supreme.api</tt> to create an
+    # API instance. If you have to interact with multiple accounts in one process you can
+    # instantiate the API class youself.
+    #
+    # === Options
+    #
+    # * <tt>:mode</tt> – Holds either :test or :live to signal whether to run in test or live mode. The default value is :test.
+    # * <tt>:partner_id</tt> – Your Mollie Partner ID, you can find it under ‘Accountgegevens’ in the settings for your account on mollie.nl.
+    #
+    # === Example
+    #
+    #   api = Supreme::API.new(:partner_id => '9834234')
+    #   api.test? #=> true
+    #   api.banklist
+    def initialize(options={})
+      self.mode = options[:mode] || options['mode'] || :test
+      self.partner_id = options[:partner_id] || options['partner_id']
+    end
+    
+    # Returns true when we're in test mode and false otherwise
+    def test?
+      self.mode.to_sym == :test
+    end
+    
+    # Requests a list of available banks. Turns a Banklist response.
+    # Use Banklist#to_a to get a list of hashes with actual information.
+    #
+    #   Supreme.api.banklist.to_a # => [{ :id => '1006', :name => 'ABN AMRO Bank' }, …]
+    #
+    # Returns a Supreme::Error when the call fails.
+    def banklist
+      response = get('banklist')
+      log('Banklist response', response.body)
+      Supreme::Response.for(response.body, Supreme::Banklist)
+    end
+    
+    # Starts a new payment by sending payment information. It also configures how the iDEAL
+    # provider handles payment status information. It returns a Supreme::Transaction response
+    # object.
+    #
+    # Returns a Supreme::Error when the call fails.
+    #
+    # === Options
+    #
+    # Note that the <tt>:description</tt> option has a character limit of 29 characters.
+    # Anything after the 29 characters will be silently removed by the API. Note that
+    # this description might be handled by ancient bank systems and anything but ASCII
+    # characters might be mangled or worse.
+    #
+    # ==== Required
+    #
+    # * <tt>:bank_id</tt> – The bank selected by the customer from the <tt>banklist</tt>.
+    # * <tt>:amount</tt> – The amount you want to charge in cents (EURO) (ie. €12,99 is 1299)
+    # * <tt>:description</tt> – Describe what the payment is for (max 29 characters) (ie. ‘Fluffy Bunny (sku 1234)’ )
+    # * <tt>:report_url</tt> – You will receive a GET to this URL with the transaction_id appended in the query (ie. http://example.com/payments?transaction_id=23ad33)
+    # * <tt>:return_url</tt> – The customer is redirected to this URL after the payment is complete. The transaction_id is appended as explained for <tt>:report_url</tt>
+    #
+    # ==== Optional
+    #
+    # * <tt>:partner_id</tt> – Your Mollie Partner ID, you can find it under ‘Accountgegevens’ in the settings for your account on mollie.nl. Note that the Partner ID is only optional if you've set it either on the API instance or using <tt>Supreme.partner_id</tt>.
+    # * <tt>:profile_key</tt> – When your account receives payment from different websites or companies you can set up company profiles. See the Mollie documentation for more information: http://www.mollie.nl/support/documentatie/betaaldiensten/ideal/.
+    #
+    # === Example
+    #
+    #   transaction = Supreme.api.fetch({
+    #     :bank_id => '0031',
+    #     :amount => 1299,
+    #     :description => '20 credits for your account',
+    #     :report_url => 'http://example.com/payments/ad74hj23',
+    #     :return_url => 'http://example.com/payments/ad74hj23/thanks'
+    #   })
+    #   @purchase.update_attributes!(:transaction_id => transaction.transaction_id)
+    #
+    # See the Supreme::Transaction class for more information.
+    def fetch(options)
+      options = options.dup
+      options[:partner_id] ||= partner_id
+      response = get('fetch', Supreme.translate_hash_keys({
+        :partner_id => :partnerid,
+        :return_url => :returnurl,
+        :report_url => :reporturl
+      }, options))
+      log('Fetch response', response.body)
+      Supreme::Response.for(response.body, Supreme::Transaction)
+    end
+    
+    # Requests the status information for a payment. It returns a Supreme::Status
+    # response object.
+    #
+    # Returns a Supreme::Error when the call fails.
+    #
+    # === Options
+    #
+    # * <tt>:transaction_id</tt> – The transaction ID you received earlier when setting up the transaction.
+    #
+    # == Example
+    #
+    #   status = Supreme.api.check(:transaction_id => '482d599bbcc7795727650330ad65fe9b')
+    #   if status.paid?
+    #     @purchase.paid!
+    #   end
+    #
+    # See the Supreme::Status class for more information.
+    def check(options)
+      options = options.dup
+      options[:partner_id] ||= partner_id
+      response = get('check', Supreme.translate_hash_keys({
+        :partner_id => :partnerid,
+      }, options))
+      log('Status response', response.body)
+      Supreme::Response.for(response.body, Supreme::Status)
+    end
+    
+    private
+    
+    def endpoint
+      ENDPOINT.dup
+    end
+    
+    def query(options={})
+      options = options.dup
+      options[:testmode] = 'true' if test?
+      options == {} ? nil : Supreme::URI.generate_query(options)
+    end
+    
+    def get(action, options={})
+      options = options.dup
+      options[:a] = action
+      url = endpoint
+      url.query = query(options)
+      log('GET', url.to_s)
+      REST.get(url.to_s)
+    end
+    
+    def log(thing, contents)
+      $stderr.write("\n#{thing}:\n\n#{contents}\n") if $DEBUG
+    end
+  end
+end

data/lib/supreme/response.rb

@@ -0,0 +1,133 @@
+require 'rexml/document'
+
+module Supreme
+  # The base class for all response classes.
+  class Response
+    attr_accessor :body
+    
+    def initialize(body)
+      @body = body
+    end
+    
+    def error?
+      false
+    end
+    
+    # Return an instance of a reponse class based on the contents of the body
+    def self.for(response_body, klass)
+      body = REXML::Document.new(response_body).root
+      if body.elements["/response/item"]
+        ::Supreme::Error.new(body)
+      else
+        klass.new(body)
+      end
+    end
+    
+    protected
+    
+    def text(path)
+      @body.get_text(path).to_s
+    end
+  end
+  
+  # Response to a banklist request
+  class Banklist < Response
+    def to_a
+      @body.get_elements('//bank').map do |issuer|
+        { :id => issuer.get_text('bank_id').to_s, :name => issuer.get_text('bank_name').to_s }
+      end
+    end
+  end
+  
+  # Response to a fetch request
+  class Transaction < Response
+    def transaction_id
+      text('//transaction_id')
+    end
+    
+    def amount
+      text('//amount')
+    end
+    
+    def url
+      text('//URL')
+    end
+  end
+  
+  # Response to a check request
+  class Status < Response
+    def transaction_id
+      text('//transaction_id')
+    end
+    
+    def amount
+      text('//amount')
+    end
+    
+    def currency
+      text('//currency')
+    end
+    
+    def paid
+      text('//payed')
+    end
+    
+    # A payment will return paid? for just one request. If you issue it too early you might never
+    # get a truthy value from this.
+    def paid?
+      paid == 'true'
+    end
+    
+    # Returns the status of the payment. This is probably the best way to check if the payment has
+    # succeeded. It returns one of the following values:
+    #
+    # * <tt>Open</tt> – Payment is still processing.
+    # * <tt>Success</tt> – The payment was successful.
+    # * <tt>Cancelled</tt> – The payment was explicitly cancelled by the customer.
+    # * <tt>Failure</tt> – The payment failed.
+    # * <tt>Expired</tt> – The customer abandoned the payment, we don't expect them to finish it.
+    # * <tt>CheckedBefore</tt> – You've requested the payment status before.
+    #
+    # You can also check the status of the payment with one of the boolean accessors: open?, success?,
+    # cancelled?, failed?, expired?, and checked_before?.
+    def status
+      text('//status')
+    end
+    
+    [
+      ['Open', :open?],
+      ['Success', :success?],
+      ['Cancelled', :cancelled?],
+      ['Failure', :failed?],
+      ['Expired', :expired?],
+      ['CheckedBefore', :checked_before?]
+    ].each do |expected, accessor|
+      define_method accessor do
+        status == expected
+      end
+    end
+    
+    def customer
+      {
+        'name' => text('//consumerName'),
+        'account' => text('//consumerAccount'),
+        'city' => text('//consumerCity')
+      }
+    end
+  end
+  
+  # Response was an error
+  class Error < Response
+    def error?
+      true
+    end
+    
+    def code
+      text('//errorcode')
+    end
+    
+    def message
+      text('//message')
+    end
+  end
+end

data/lib/supreme/uri.rb

@@ -0,0 +1,88 @@
+module Supreme
+  class URI
+    # Borrowed from uri/common.rb, with modifications to support 1.8.x
+    # https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb
+    
+    TBLENCWWWCOMP_ = {} # :nodoc:
+    TBLDECWWWCOMP_ = {} # :nodoc:
+    
+    # Encode given +s+ to URL-encoded form data.
+    #
+    # This method doesn't convert *, -, ., 0-9, A-Z, _, a-z, but does convert SP
+    # (ASCII space) to + and converts others to %XX.
+    #
+    # This is an implementation of
+    # http://www.w3.org/TR/html5/forms.html#url-encoded-form-data
+    #
+    # See URI.decode_www_form_component, URI.encode_www_form
+    def self.encode_www_form_component(s)
+      str = s.to_s
+      if RUBY_VERSION < "1.9" && $KCODE =~ /u/i
+        str.gsub(/([^ a-zA-Z0-9_.-]+)/) do
+          '%' + $1.unpack('H2' * Rack::Utils.bytesize($1)).join('%').upcase
+        end.tr(' ', '+')
+      else
+        if TBLENCWWWCOMP_.empty?
+          tbl = {}
+          256.times do |i|
+            tbl[i.chr] = '%%%02X' % i
+          end
+          tbl[' '] = '+'
+          begin
+            TBLENCWWWCOMP_.replace(tbl)
+            TBLENCWWWCOMP_.freeze
+          rescue
+          end
+        end
+        str.gsub(/[^*\-.0-9A-Z_a-z]/) {|m| TBLENCWWWCOMP_[m]}
+      end
+    end
+    
+    # Decode given +str+ of URL-encoded form data.
+    #
+    # This decods + to SP.
+    #
+    # See URI.encode_www_form_component, URI.decode_www_form
+    def self.decode_www_form_component(str, enc=nil)
+      if TBLDECWWWCOMP_.empty?
+        tbl = {}
+        256.times do |i|
+          h, l = i>>4, i&15
+          tbl['%%%X%X' % [h, l]] = i.chr
+          tbl['%%%x%X' % [h, l]] = i.chr
+          tbl['%%%X%x' % [h, l]] = i.chr
+          tbl['%%%x%x' % [h, l]] = i.chr
+        end
+        tbl['+'] = ' '
+        begin
+          TBLDECWWWCOMP_.replace(tbl)
+          TBLDECWWWCOMP_.freeze
+        rescue
+        end
+      end
+      raise ArgumentError, "invalid %-encoding (#{str})" unless /\A(?:%[0-9a-fA-F]{2}|[^%])*\z/ =~ str
+      str.gsub(/\+|%[0-9a-fA-F]{2}/) {|m| TBLDECWWWCOMP_[m]}
+    end
+    
+    def self.decode(value)
+      Supreme::URI.decode_www_form_component(value)
+    end
+    
+    def self.encode(value)
+      Supreme::URI.encode_www_form_component(value).gsub("%7E", '~').gsub("+", "%20")
+    end
+    
+    def self.parse_query(query_string)
+      return [] if query_string.to_s.strip == ''
+      query_string.strip.split('&').inject([]) do |parsed, pair|
+        parsed << pair.split('=', 2).map { |x| decode(x) }
+      end
+    end
+    
+    def self.generate_query(pairs)
+      pairs.inject([]) do |parts, (key, value)|
+        parts << "#{encode(key)}=#{encode(value)}"
+      end.join('&')
+    end
+  end
+end

data/lib/supreme/version.rb

@@ -0,0 +1,3 @@
+module Supreme
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification 
+name: supreme
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Manfred Stienstra
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-02-11 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: nap
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: 
+email: 
+- manfred@fngtps.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- lib/supreme/api.rb
+- lib/supreme/response.rb
+- lib/supreme/uri.rb
+- lib/supreme/version.rb
+- lib/supreme.rb
+- README.md
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/Fingertips/Supreme
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Ruby implementation of the Mollie iDEAL API
+test_files: []
+