omnipay 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c3c13dede2e2ea788ee716eb834b225b1cae1ca9
-  data.tar.gz: 949abeb3bde942deb0c11d8c011814b692f538f1
+  metadata.gz: b70c2a69c944278d12c7d4d28dba68f9a4cdc7b7
+  data.tar.gz: e1957fbd18a16d08f9e624fe527dcc856f52f568
 SHA512:
-  metadata.gz: afbd5ccc734ef955631e111ded2dbf447dc63ae3658069d7b72c1c8210dbee2eb707a989f5057dc0ec112f0a7dcfa43660b6f8d0aaa6b76a80155b6883331d09
-  data.tar.gz: d419fd51650c301b5c2a379fea3a11192921b1b585f146726af5ed2d933d0c1054afd28ac1c6d41cafb443e835e2075554048a85aa59faeddb8cb23af40934c3
+  metadata.gz: 1d8b70552a9695e6adadccb9b710b5c9070bbed9d86cdb8ae6bf2dbd529f8c70a6eda5ff5ab9d528085291814e67cf549d3af40d1422556258c2b13f008a8eba
+  data.tar.gz: 16eb68cb0f62b6b1bd5984b234a04dc9b2afdaf6d51347c77fd2ffc1112ef8ad363781616cac3e806c9e66ea4a79dfbafb00085f74fd6352cab29fb1890a78d0

data/lib/omnipay.rb

@@ -1,5 +1,6 @@
 require 'singleton'
 
+# The root Omnipay module. Used for defining its global configuration
 module Omnipay
 
   autoload :Gateway, 'omnipay/gateway'
@@ -9,22 +10,38 @@ module Omnipay
   autoload :AutosubmitForm, 'omnipay/autosubmit_form'
   autoload :Signer, 'omnipay/signer'
 
-  # Error codes
+  # Error code for an untreatable response
   INVALID_RESPONSE = :invalid_response
+
+  # Error code for a user-initiated payment failure
   CANCELATION = :cancelation
+
+  # Error code for a valid response but a failed payment
   PAYMENT_REFUSED = :payment_refused
+
+  # Error code for a signature mismatch
   WRONG_SIGNATURE = :wrong_signature
 
-  # Configuration
+
+  # The global Omnipay configuration singleton
   class Configuration
     include Singleton
     attr_accessor :secret_token
   end
 
+  # Accessor to the global configuration
+  # @return [Configuration]
   def self.configuration
     Configuration.instance
   end
 
+  # Allows to configure omnipay via a block
+  #
+  # Example use : 
+  # 
+  #   Omnipay.configure do |config|
+  #     config.secret_token = "a-secret-token"
+  #   end
   def self.configure
     yield configuration
   end

data/lib/omnipay/adapter.rb

@@ -1,13 +1,18 @@
-# Glue between the rack middleware and the adapter implementation
-# Responsible for initializing, configuring the adapter, and formatting
-# the responses for use in the middleware
-
 module Omnipay
 
+  # Wrapper around an actual adapter implementation. Responsible mainly for handling its initialization with
+  # a static or dynamic (block) configuration
   class Adapter
 
+    # The adapter's unique identifier. Will be passed to the dynamic configuration block.
     attr_reader :uid
 
+
+    # @param uid [String] The adapter's unique identifier
+    # @param callback_url [String] The absolute URL to be used for the user redirection after the payment
+    # @param config [Hash] A static adapter configuration
+    # @param dynamic_config [String => Hash] A dynamic config block. Takes the uid as an input and returns the adapter's configuration
+    # @return [Adapter]
     def initialize(uid, callback_url, config, dynamic_config)
       @uid = uid
       @callback_url = callback_url
@@ -17,14 +22,23 @@ module Omnipay
       @strategy = build_strategy
     end
 
+    # Is there a valid adapter configuration for the given parameters. Checks notably if the given uid is valid in case of a dyncamic configuration.
+    # @return [Boolean]
     def valid?
       @strategy != nil
     end
 
-    def request_phase(amount, opts)
+    # Proxy to the adapter's implementation's request_phase method
+    # @param amount [Integer] The amount to pay, in **cents**
+    # @param opts [Hash] The custom GET parameters sent to the omnipay payment url
+    # @return [Array] The array containing the redirection method (GET or POST), its url, its get or post params, and the unique associated transaction id
+    def request_phase(amount, opts = {})
       @strategy.request_phase(amount, opts)
     end
 
+    # Proxy to the adapter's implementation's callback_phase method
+    # @param params [Hash] The GET/POST params sent by the payment gateway to the callback url
+    # @return [Hash] The omnipay response environment. Contains the response success status, the amount payed, the error message if any, ...
     def callback_hash(params)
       @strategy.callback_hash(params)
     end

data/lib/omnipay/adapters/sample_adapter.rb

@@ -0,0 +1,117 @@
+module Omnipay
+  module Adapters
+
+    # This is a sample Omnipay adapter implementation for a fictive payment gateway. You can use it as a boilerplate to develop your own.
+    #
+    # This adapter will take two arguments in its configuration :
+    # * *api_key* [String - mandatory] : given by the payment gateway, used for authenticating to their API
+    # * *sandbox* [Boolean - optional] : whether the payment should be done in a sandbox or with the real payment page
+    # It may then be initialized like this in a rack application
+    #   use Omnipay::Gateway, 
+    #         :uid => 'my-gateway',
+    #         :adapter => Omnipay::Adapters::SampleAdapter
+    #         :config => {
+    #           :api_key => 'my-api-key',
+    #           :sandbox => (ENV['RACK_ENV'] != 'production')
+    #         }
+
+    class SampleAdapter
+
+      # The adapters initialization
+      # @param callback_url [String] the absolute callback URL the user should be redirected to after the payment. Will be generated by Omnipay. Example value : "http\://\www\.my-host.tld/pay/my-gateway/callback"
+      # @param config [Hash] the adapter's configuration as defined in the application's omnipay config file. For the example above in a dev environment, the value would be {:api_key => 'my-api-key', :sandbox => true}. It is up to you to decide which fields are mandatory, and to both check them in this initializer and specify them in your documentation. In this case :
+      #   * *:api_key* [String] (mandatory) : the API key given for your fictive gateway's account
+      #   * *:sandbox* [Boolean] (optional) : whether to use a sandboxed payment page, or a real one. Defaults to true
+      # @return [SampleAdapter]
+      def initialize(callback_url, config = {})
+        @callback_url = callback_url
+
+        @api_key = config[:api_key]
+        raise ArgumentError.new("Missing api_key") unless @api_key
+
+        @mode = (config[:sandbox] == false) ? 'production' : 'sandbox'
+      end
+
+
+      # Responsible for determining the redirection to the payment page for a given amount
+      # 
+      # @param amount [Integer] the amount **in cents** that the user has to pay
+      # @param params [Hash] the GET parameters sent to the omnipay payment URL. Can be used to specify transaction-specific variables (the locale to use, the payment page's title, ...). Please use the following keys if you need to, for consistency among adapters :
+      #  * *locale* The ISO 639-1 locale code for the payment page
+      #  * *title* The title to display on the payment page
+      #  * *transaction_id* The transaction id to use, if you want the user to be able to force it
+      # @return [Array] an array containing the 4 following values :
+      #  * +[String]+ 'GET' or 'POST' : the HTTP method to use for redirecting to the payment page
+      #  * +[String]+ the absolute URL of the payment page. Example : "https\://my-provider.tld/sc12fdg57df"
+      #  * +[Hash]+   the GET or POST parameters to send to the payment page
+      #  * +[String]+ the unique transaction_id given by the payment provider for the upcoming payment. Has to be accessible in the callback phase. 
+
+      def request_phase(amount, params={})
+        amount_in_dollar = amount * 1.0 / 100
+        locale = params[:locale] || 'en'
+
+        transaction = build_new_transaction(amount_in_dollars, locale)
+
+        uri = URI(transaction.payment_url)
+
+        method = 'GET'
+        url = "#{uri.scheme}://#{uri.host}#{uri.path}"
+        get_params = Rack::Utils.parse_query(uri.query)
+        transaction_id = transaction.id
+
+        return [
+          method,
+          url,
+          get_params,
+          transaction_id
+        ]
+
+      end
+     
+
+      # @param params [Hash] the GET/POST parameters sent by the payment gateway to the callback url
+      # @return [Hash] the resulting response hash which will be accessible in the application. Must contain the following values :
+      #  * *:success* (+Boolean+) | Did the payment occur or not?
+      #  * *:amount* (+Integer+) <i>if successful</i> | The amount <b>in cents</b> actually payed
+      #  * *:transaction_id* (+String+) <i>if successful</i> | The id of the transaction. Must match the one returned in the request phase.
+      #  * *:error* (+Symbol+) <i>if failed</i> | The reason why the payment was not successful. The available values are :
+      #    * _Omnipay::CANCELED_ : The payment didn't occur because of the user.
+      #    * _Omnipay::PAYMENT_REFUSED_ : The payment didn't occue because of an error on the gateway's side.
+      #    * _Omnipay::INVALID_RESPONSE_ : The response from the gateway cannot be parsed. The payment may or may not have occured.
+      #  * *:error_message* (+String+) <i>if failed</i> | A more detailed error message / stack trace, for logging purposes
+
+      def callback_hash(params)
+
+        transaction_id = params[:transaction_id]
+        transaction = fetch_transaction(transaction_id)
+
+        if !transaction
+          return { :success => false, :error => Omnipay::INVALID_RESPONSE, :error_message => "No transaction found with id #{transaction_id}"}
+        end
+
+        if transaction.success
+          { :success => true, :amount => (transaction.amount*100).to_i, :transaction_id => transaction_id }
+        else
+          if transaction.canceled
+            { :success => false, :error => Omnipay::CANCELATION }
+          else
+            { :success => false, :error => Omnipay::PAYMENT_REFUSED, :error_message => "Transaction #{transaction_id} was not successful : #{transaction.error}" }
+          end
+        end
+      end
+
+
+      private
+
+      def build_new_transaction(amount, locale)
+        # TODO        
+      end
+
+      def fetch_transaction(transaction_id)
+        # TODO
+      end
+
+    end
+
+  end
+end

data/lib/omnipay/autosubmit_form.rb

@@ -1,36 +1,52 @@
-# Builds an html page with an autosubmitted form, to handle POST redirections
 module Omnipay
+
+  # This class is responsible for generating an html page which will redirect its visitor to an arbitrary url,
+  # with arbitrary POST parameters in the request body.
+  # 
+  # It does so by including an hidden form in the page, and submitting it via javascript on page load.
+  # 
   class AutosubmitForm
 
     HEADER = <<-HEADER
 <!DOCTYPE html>
 <html>
   <head>
-    <script type="text/javascript">
-      window.onload=function(){
-        document.getElementById('autosubmit-form').submit();
-      }
-    </script>
+    <title>You are being redirected</title>
   </head>
-
   <body>
     <h1>Redirecting...</h1>
     HEADER
 
     FOOTER = <<-FOOTER
+    <script type="text/javascript">
+      document.getElementById('autosubmit-form').submit();
+    </script>
   </body>
 </html>
 FOOTER
 
+
+    # Initializes the form with its action, and its inputs name/value pairs
+    # 
+    # @param action [String] The url the form must be submitted to. Will be the value of its <action> attribute
+    # @param fields [Hash] The key/value pairs of parameters to be sent as POST to the action. Will be a set of hidden <inputs> in the form.
+    #
+    # @return [AutosubmitForm]
     def initialize(action, fields)
       @action = action
       @fields = fields.map{|name, value| {:name => name, :value => value}}
     end
 
+
+    # Returns the full html page
+    # @return [String]
     def html
       HEADER + form_html + FOOTER
     end
 
+
+    private
+
     def form_html
 "    <form method=\"POST\" id=\"autosubmit-form\" action=\"#{@action}\">\n" + 
       @fields.map{|field|

data/lib/omnipay/callback_phase.rb

@@ -1,14 +1,19 @@
-# Class responsible for updating the request env in the callback phase
-
 module Omnipay
+
+  # Class responsible for the processing in a gateway's callback phase. It updates the request's environemnt with the formatted Omnipay response given by the apdater's implementation.
   class CallbackPhase
 
+    # @param request [Rack::Request] The request corresponding to the redirection from the payment gateway to the application.
+    # @param adapter [Adapter] The adapter instance of the gateway having catched this request
+    # @return [CallbackPhase]
     def initialize(request, adapter)
       @request = request
       @adapter = adapter
     end
 
 
+    # Actually set the request's environment variable 'omnipay.response' with the formatted summary of the payment transaction.
+    # @note Should only be called once because of the signatures lifetime
     def update_env!
 
       # The request params, keys symbolized

data/lib/omnipay/gateway.rb

@@ -2,11 +2,27 @@ require 'rack'
 
 module Omnipay
 
-  # Gateway middleware
+  # This is the actual Rack middleware
+  # 
+  # It is associated with an adapter instance, and 
+  # responsible for monitoring the incoming request
+  # and - depending on their path - forwarding them
+  # for processing to a RequestPhase or CallbackPhase
+  # instance for processing
   class Gateway
 
     BASE_PATH = '/pay'
 
+    # @param app [Rack application] : The rack app it should forward to if the request doens't match a monitored path
+    # 
+    # @param options [Hash] : must contains the following configuration options
+    #  * :uid : the subpath to monitor
+    #  * :adapter : the adapter class to use 
+    #  * :config : the config hash which will be passed at the adapter for initialization
+    # 
+    # The gateway may be initialized with a block returning a hash instead of a hash. In this case, the
+    # block's only argument is the uid, and the returned hash must contain the adapter class and its configuration
+
     def initialize(app, options={}, &block)
       @app = app
 
@@ -18,7 +34,8 @@ module Omnipay
       @request = nil
     end
 
-
+    # The standard rack middleware call. Will be processed by an instance of RequestPhase or CallbackPhase if the
+    # path matches the adapter's uid. Will forward to the app otherwise
     def call(env)
 
       # Get the current request

data/lib/omnipay/request_phase.rb

@@ -1,13 +1,18 @@
-# Class responsible for formatting the redirection in the request phase
-
 module Omnipay
+
+  # Class responsible for formatting the redirection in the request phase
   class RequestPhase
 
+    # @param request [Rack::Request] The request corresponding to the redirection from the payment gateway to the application.
+    # @param adapter [Adapter] The adapter instance of the gateway having catched this request
+    # @return [RequestPhase]
     def initialize(request, adapter)
       @request = request
       @adapter = adapter
     end
 
+    # Returns the rack response for redirecting the user to the payment page. Can be a 302 redirect if a GET redirection, or an AutosubmittedForm for POST redirections
+    # @return [Rack::Response]
     def response
       method, url, params, transaction_id = @adapter.request_phase(amount, adapter_params)
 

data/lib/omnipay/signer.rb

@@ -1,30 +1,33 @@
-# Class responsible for signing the outgoing payments in the request phase, 
-# and validating them in the callback phase
-
 require 'openssl'
 
 module Omnipay
+
+  # Class responsible for computing a signature of a payment.
   class Signer
 
+    # @param transaction_id [String] the transactions's unique identifier
+    # @param amount [Integer] the amount **in cents** of the transaction
+    # @param context [Hash] the transaction's context hash
+    # @return [Signer]
     def initialize(transaction_id, amount, context)
       @transaction_id = transaction_id
       @amount = amount
       @context = context || {}
     end
 
+    # Actually computes the signature
+    # @return [String] The computed signature
     def signature
       to_sign = "#{secret_token}:#{@transaction_id}:#{@amount}:#{self.class.hash_to_string @context}"
       CGI.escape(Base64.encode64(OpenSSL::HMAC.digest('sha1', secret_token, to_sign)))
     end
 
+    private
 
-    # Unique key : to configure globally
     def secret_token
       Omnipay.configuration.secret_token
     end
 
-    private
-
     def self.hash_to_string(hash)
       # key/values appended by alphabetical key order
       hash.sort_by{|k,_|k}.flatten.join('')

data/lib/omnipay/version.rb

@@ -1,3 +1,3 @@
 module Omnipay
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnipay
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - ClicRDV
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-10 00:00:00.000000000 Z
+date: 2014-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -51,6 +51,7 @@ files:
 - lib/omnipay/adapters/mangopay.rb
 - lib/omnipay/adapters/mangopay/client.rb
 - lib/omnipay/adapters/oneclicpay.rb
+- lib/omnipay/adapters/sample_adapter.rb
 - lib/omnipay/autosubmit_form.rb
 - lib/omnipay/callback_phase.rb
 - lib/omnipay/gateway.rb
@@ -81,3 +82,4 @@ signing_key:
 specification_version: 4
 summary: Payment gateway abstraction for rack applications.
 test_files: []
+has_rdoc: