pesapal 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fb392cdf96d61bb012553fb244ff25d396a3e03e
-  data.tar.gz: 3580ef2eb4210bb084fdec5d27d7906b9a14acac
+  metadata.gz: 44aef97bfcafb5b7ce0a7db59a613eccb7dbacd7
+  data.tar.gz: 87b26cead15de174dffe376207ba2c788483b38a
 SHA512:
-  metadata.gz: d9d551c448a513f52cd3b77ed1f344ff55039cd5bd84d2fcd2eea00cd1d087d264c7dd13cd41638ba438e182764daf4b84d0f8631be629986a39ab1af5494567
-  data.tar.gz: 249a9fd1d7aa8cd95d28118f8b96a83df53061ed94e5c5e8bdb770324768c580cc5c4c9a5d1eec1bbe686e8ce8604ce800130cdc06c993dbc3e0f3a8f9a1a45a
+  metadata.gz: 47c85fc5ae2a65a9158bda4ec6966ea0ddd3836e8d0e2a3fc9d223e3aef8780a82c8473beb8e7881a85c1eb9dfe99e08304c6c7fa6a403e127129e97465904a9
+  data.tar.gz: 59e945655938a5a6def127f44eae00c4c3b75727348e43602605495a98bdbd0fb7cf635e24e0523c5bdbc4abb7505bac7d5b41bd87309a5fff384f319d7bf2e5

data/README.md

@@ -14,10 +14,15 @@ been laid. If you are [feeling generous and want to contribute, feel free][9].
 
 Submit [issues and requests here][6] and [find all the releases here][12].
 
-The gem should be [up on RubyGems.org][7] and it's [accompanying RubyDoc reference][13] here.
+The gem should be [up on RubyGems.org][7] and it's [accompanying RubyDoc reference here][13].
 
 _Ps: No 3rd party oAuth library dependencies, it handles all the oAuth flows on
-it's own so it's light on your app._
+it's own so your app is one dependency less._
+
+_Ps 2: We are still at pre-release stage ... target is version 1.0.0 for a
+public release (suitable for production deployment with the basic functionality
+in place). As a result always check the documentation carefully on upgrades to
+mitigate breaking changes._
 
 
 Installation
@@ -39,39 +44,69 @@ Or install it yourself as:
 Usage
 -----
 
+
 ### Setup ###
 
 Initialize Pesapal object and choose the mode, there are two modes;
-`:development` and `:production`. They determine if you the code will interact
-with Pesapal for testing or for a live deployment.
+`:development` and `:production`. They determine if the code will interact
+with the testing or the live Pesapal API.
 
 ```ruby
 # initiate pesapal object set to development mode
 pesapal = Pesapal::Merchant.new(:development)
 ```
 
-Now set the Pesapal credentials. This assumes that you've chosen the appropriate
-credentials as they differ based on the mode chosen above (Pesapal provide the
-keys). Replace the placeholders below with your own credentials.
+You can set the configuration details from a YAML file at the location of
+your choice upon initialization as shown in the example below for a Rails app.
+The second parameter is optional and has a default value of
+`"#{Rails.root}/config/pesapal.yml"` if left out as in the example above.
 
 ```ruby
-# set pesapal api credentials
-pesapal.credentials = { :consumer_key => '<YOUR_CONSUMER_KEY>',
-                        :consumer_secret => '<YOUR_CONSUMER_SECRET>' 
-                    }
+# initiate pesapal object set to development mode and use the YAML file found at
+# the specified location
+pesapal = Pesapal::Merchant.new(:development, "<PATH_TO_YAML_FILE>")
+```
+
+And the YAML file should look something like this. Feel free to change to the
+appropriate values.
+
+```yaml
+development:
+    callback_url: 'http://0.0.0.0:3000/pesapal/callback'
+    consumer_key: '<YOUR_CONSUMER_KEY>'
+    consumer_secret: '<YOUR_CONSUMER_SECRET>'
+
+production:
+    callback_url: 'http://1.2.3.4:3000/pesapal/callback'
+    consumer_key: '<YOUR_CONSUMER_KEY>'
+    consumer_secret: '<YOUR_CONSUMER_SECRET>'
 ```
 
-By default the callback is set to `http://0.0.0.0:3000/pesapal/callback` on instantiation but you can easily set it to whatever works for you as shown below.
+If the YAML file does not exist, then the object is set up with some bogus
+credentials which would not work anyway and therefore, the next logical step is
+that you set them yourself. Which, you can do using a hash as shown below
+(please note that Pesapal provides different keys for different modes and since
+this is like an override, there's the assumption that you chose the right one).
 
 ```ruby
-pesapal.callback_url = 'WHATEVER_URL_YOU_WANT'
+# set pesapal api configuration manually (override YAML & bogus credentials)
+pesapal.config = {  :callback_url => 'http://0.0.0.0:3000/pesapal/callback'
+                    :consumer_key => '<YOUR_CONSUMER_KEY>',
+                    :consumer_secret => '<YOUR_CONSUMER_SECRET>'
+                  }
 ```
 
+_Ps: Make sure this hash has the appropriate values before running any methods
+that interact with the API as the methods pick from these values. This means
+that you can also override them at runtime for a truly dynamic/complex app that
+might have different values for different scenarios._
+
+
 ### Post Order ###
 
-Once you've set up the credentials, set up the order details in a hash as shown
-in the example below ... all keys **MUST** be present. If there's one that you
-wish to ignore just leave it with a blank string but make sure it's included
+Once you've finalized the configuration, set up the order details in a hash as
+shown in the example below ... all keys **MUST** be present. If there's one that
+you wish to ignore just leave it with a blank string but make sure it's included
 e.g. the phonenumber.
 
 ```ruby
@@ -89,24 +124,34 @@ pesapal.order_details = { :amount => 1000,
 
 Then generate the transaction url as below. In the example, the value is
 assigned to the variable `order_url` which you can pass on to the templating
-system of your to generate an iframe.
+system of your choice to generate an iframe. Please note that this method
+utilizes all that information set in the previous steps in generating the url so
+it's important that it's the last step in the post order process.
 
 ```ruby
 # generate transaction url
 order_url = pesapal.generate_order_url
+
+# order_url will a string with the url example;
+# http://demo.pesapal.com/API/PostPesapalDirectOrderV4?oauth_callback=http%3A%2F%2F1.2.3.4%3A3000%2Fpesapal%2Fcallback&oauth_consumer_key=A9MXocJiHK1P4w0M%2F%2FYzxgIVMX557Jt4&oauth_nonce=13804335543pDXs4q3djsy&oauth_signature=BMmLR0AVInfoBI9D4C38YDA9eSM%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1380433554&oauth_version=1.0&pesapal_request_data=%26lt%3B%3Fxml%20version%3D%26quot%3B1.0%26quot%3B%20encoding%3D%26quot%3Butf-8%26quot%3B%3F%26gt%3B%26lt%3BPesapalDirectOrderInfo%20xmlns%3Axsi%3D%26quot%3Bhttp%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%26quot%3B%20xmlns%3Axsd%3D%26quot%3Bhttp%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%26quot%3B%20Amount%3D%26quot%3B1000%26quot%3B%20Description%3D%26quot%3Bthis%20is%20the%20transaction%20description%26quot%3B%20Type%3D%26quot%3BMERCHANT%26quot%3B%20Reference%3D%26quot%3B808%26quot%3B%20FirstName%3D%26quot%3BSwaleh%26quot%3B%20LastName%3D%26quot%3BMdoe%26quot%3B%20Email%3D%26quot%3Bj%40kingori.co%26quot%3B%20PhoneNumber%3D%26quot%3B%2B254722222222%26quot%3B%20xmlns%3D%26quot%3Bhttp%3A%2F%2Fwww.pesapal.com%26quot%3B%20%2F%26gt%3B
 ```
 
+_Ps: Please note the `:callback_url` value in the `pesapal.config` hash ...
+after the user successfully posts the order, the response will be sent to this
+url. Refer to [official Pesapal Step-By-Step integration guide][18] for more
+details._
+
 
 Contributing
 ------------
 
-1. [Fork it][8]
-2. Create your feature branch (`git checkout -b wip-my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature with awesome'`)
-4. Push to the branch (`git push origin wip-my-new-feature`)
-5. Create new pull request
-
-_Ps: Please prefix branch name with 'wip-' ... means 'work in progress'._
+1. Make sure you've read the [M.O. ★][14] ([blog article here][16])
+2. Especially [the part about my conventions when writing and merging new features][15]
+2. [Fork it][8]
+2. Create your feature branch (`git checkout -b BRANCH_NAME`)
+3. Commit your changes (`git commit -am 'AWESOME COMMIT MESSAGE'`)
+4. Push to the branch (`git push origin BRANCH_NAME`)
+5. Create new pull request and we can [have the conversations here][17]
 
 
 References
@@ -116,6 +161,7 @@ References
 * [Developing a RubyGem using Bundler][2]
 * [Make your own gem][3]
 * [Pesapal API Reference (Official)][4]
+* [Pesapal Step-By-Step Reference (Official)][18]
 * [Pesapal PHP API Reference (Unofficial)][5]
 
 
@@ -139,3 +185,8 @@ they want as long as they provide attribution and waive liability.
 [11]: https://github.com/itsmrwave/pesapal-rubygem/blob/master/LICENSE.txt
 [12]: https://github.com/itsmrwave/pesapal-rubygem/releases/
 [13]: http://rubydoc.info/gems/pesapal/
+[14]: https://github.com/itsmrwave/mo
+[15]: https://github.com/itsmrwave/mo/tree/master/convention#-convention
+[16]: http://kingori.co/articles/2013/09/modus-operandi/
+[17]: https://github.com/itsmrwave/pesapal-rubygem/pulls
+[18]: http://developer.pesapal.com/how-to-integrate/step-by-step

data/lib/pesapal/merchant.rb

@@ -2,7 +2,7 @@ module Pesapal
     
     class Merchant
 
-        attr_accessor :callback_url, :credentials, :order_details
+        attr_accessor :config, :order_details
         attr_reader :api_domain, :api_endpoints
 
         def api_domain
@@ -13,12 +13,8 @@ module Pesapal
             @api_endpoints
         end
 
-        def callback_url
-            @callback_url
-        end
-
-        def credentials
-            @credentials
+        def config
+            @config
         end
 
         def order_details
@@ -27,6 +23,10 @@ module Pesapal
 
         private
 
+            def mode
+                @mode
+            end
+
             def params
                 @params
             end
@@ -42,32 +42,21 @@ module Pesapal
         public
 
             # constructor
-            def initialize(mode = :development)
-
-                # convert symbol to string and downcase
-                mode.to_s.downcase!
+            def initialize(mode = :development, path_to_file = "#{Rails.root}/config/pesapal.yml")
 
                 # initialize
                 @params = nil
                 @post_xml = nil
                 @token_secret = nil
 
-                # set the credentials from the config (if initializers/pesapal.rb
-                # exists they should have set these values)
-                @credentials = nil
+                # convert symbol to string and downcase
+                @mode = "#{mode.to_s.downcase}"
 
-                # set the callback url that the iframe will respond to
-                @callback_url = 'http://0.0.0.0:3000/pesapal/callback'
+                # set the credentials
+                set_configuration_from_yaml path_to_file
 
                 # set api endpoints depending on the mode
-                @api_endpoints = {}
-                if mode == 'development'
-                    set_endpoints_development
-                elseif mode == 'production'
-                    set_endpoints_production
-                else
-                    set_endpoints_development
-                end
+                set_endpoints
             end
 
             # generate pesapal order url (often iframed)
@@ -78,7 +67,7 @@ module Pesapal
                 @post_xml = Pesapal::Post::generate_post_xml @order_details
 
                 # initialize setting of @params (oauth_signature left empty) ... this gene
-                @params = Pesapal::Post::set_parameters(@callback_url, @credentials[:consumer_key], @post_xml)
+                @params = Pesapal::Post::set_parameters(@credentials[:callback_url], @credentials[:consumer_key], @post_xml)
 
                 # generate oauth signature and add signature to the request parameters
                 @params[:oauth_signature] = Pesapal::Oauth::generate_oauth_signature("GET", @api_endpoints[:postpesapaldirectorderv4], @params, @credentials[:consumer_secret], @token_secret)
@@ -91,24 +80,60 @@ module Pesapal
 
         private
 
-            # set all endpoint for use in development mode
-            def set_endpoints_development
-                @api_domain = 'http://demo.pesapal.com'
-                set_endpoints @api_domain
+            # set endpoints
+            def set_endpoints
+
+                if @mode == 'production'
+                    @api_domain = 'https://www.pesapal.com'
+                else
+                    @api_domain = 'http://demo.pesapal.com'
+                end
+
+                @api_endpoints = {}
+                @api_endpoints[:postpesapaldirectorderv4] = "#{@api_domain}/API/PostPesapalDirectOrderV4"
+                @api_endpoints[:querypaymentstatus] = "#{@api_domain}/API/QueryPaymentStatus"
+                @api_endpoints[:querypaymentstatusbymerchantref] = "#{@api_domain}/API/QueryPaymentStatus"
+                @api_endpoints[:querypaymentdetails] = "#{@api_domain}/API/QueryPaymentDetails"
             end
 
-            # set all enpoints for use in production mode
-            def set_endpoints_production
-                @api_domain = "https://www.pesapal.com"
-                set_endpoints @api_domain
+            # set credentialts through hash, uses default if nothing is input
+            def set_configuration(consumer_details = {})
+
+                # set the configuration
+                @config = { :callback_url => 'http://0.0.0.0:3000/pesapal/callback'
+                            :consumer_key => '<YOUR_CONSUMER_KEY>',
+                            :consumer_secret => '<YOUR_CONSUMER_SECRET>' 
+                        }
+
+                valid_config_keys = @config.keys
+
+                consumer_details.each { |k,v| @config[k.to_sym] = v if valid_config_keys.include? k.to_sym }
             end
 
-            # set endpoints
-            def set_endpoints(domain_string)
-                @api_endpoints[:postpesapaldirectorderv4] = "#{domain_string}/API/PostPesapalDirectOrderV4"
-                @api_endpoints[:querypaymentstatus] = "#{domain_string}/API/QueryPaymentStatus"
-                @api_endpoints[:querypaymentstatusbymerchantref] = "#{domain_string}/API/QueryPaymentStatus"
-                @api_endpoints[:querypaymentdetails] = "#{domain_string}/API/QueryPaymentDetails"
+            # set configuration through yaml file
+            def set_configuration_from_yaml(path_to_file)
+
+                if File.exist?(path_to_file)
+
+                    # load file, read it and parse the YAML
+                    begin
+                        loaded_config = YAML::load(IO.read(path_to_file))
+                    rescue Errno::ENOENT
+                        logger.info("YAML configuration file couldn't be found. Using defaults."); return
+                    rescue Psych::SyntaxError
+                        logger.info("YAML configuration file contains invalid syntax. Using defaults."); return
+                    end
+
+                    # pick the correct settings depending on the the mode and
+                    # set it appropriately. this file is expected to have the
+                    # settings for development and production
+                    set_configuration loaded_config[@mode]
+
+                else
+
+                    # in this case default values will be set
+                    set_configuration
+                end 
             end
     end
 end

data/lib/pesapal/version.rb

@@ -1,3 +1,3 @@
 module Pesapal
-    VERSION = "0.0.3"
+    VERSION = "0.1.0"
 end

data/pesapal.gemspec

@@ -5,12 +5,12 @@ require "pesapal/version"
 Gem::Specification.new do |spec|
     spec.name          = "pesapal"
     spec.version       = Pesapal::VERSION
-    spec.date          = "2013-09-28"
+    spec.date          = "2013-10-01"
     spec.authors       = ["Job King'ori Maina"]
     spec.email         = ["j@kingori.co"]
     spec.description   = "Make authenticated Pesapal API calls without the fuss!"
     spec.summary       = "Make authenticated Pesapal API calls without the fuss! Handles all the oAuth stuff abstracting any direct interaction with the API endpoints so that you can focus on what matters. Building awesome."
-    spec.homepage      = "https://github.com/itsmrwave/pesapal-rubygem#pesapal-rubygem"
+    spec.homepage      = "http://rubydoc.info/gems/pesapal/"
     spec.license       = "MIT"
 
     spec.files         = `git ls-files`.split($/)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pesapal
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Job King'ori Maina
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-28 00:00:00.000000000 Z
+date: 2013-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -70,7 +70,7 @@ files:
 - lib/pesapal/oauth.rb
 - lib/pesapal/version.rb
 - pesapal.gemspec
-homepage: https://github.com/itsmrwave/pesapal-rubygem#pesapal-rubygem
+homepage: http://rubydoc.info/gems/pesapal/
 licenses:
 - MIT
 metadata: {}