pesapal 1.5.4 → 1.5.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3b26553cb2a95d21e6fd641daaec3809cf30cde
+  data.tar.gz: 9a408042e8bcdda57fea54e511361e93506d30c5
+SHA512:
+  metadata.gz: 6e2cba8e4386972f74739ff5f65b546e381aeebadf2de31bcbb50170f1fcecbd1a36c92f20472d4ec97afe3182e18fc2667f6c9af03a22e82b67100b74e292f8
+  data.tar.gz: ad4568489f4e04edff4ce2e233f773683efdafb199b38cb6a1bcc8d261c191a004243047159f9a98a7dc57543a76b214e53731d4ad3970e101f1fae5139b4cd6

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.gitignore

@@ -1,12 +1,18 @@
-# Ignore bundler config #
+# Bundler #
 /.bundle
-
-# Ignore bundled gems #
 /vendor/bundle
 
-# Ignore all logfiles and tempfiles #
+# Coveralls #
+/coverage/
+
+# Jekyll #
+_site
+
+# Yard #
+.yardoc/*
+
+# Gem #
 /log/*
 /tmp/*
-
-# Other Files #
+Gemfile.lock
 *.gem

data/.yardopts

@@ -0,0 +1,12 @@
+'lib/pesapal/**/*.rb'
+
+--title 'Pesapal Ruby Gem'
+--markup=markdown
+--markup-provider=redcarpet
+--protected
+--no-private
+
+-
+CHANGELOG.md
+LICENSE.md
+README.md

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+v1.5.5
+------
+
+* Improve code formatting
+* Add comprehensive inline documentation (Yard)
+* Move documentation from gem to it's own homepage, separate content from it's
+  own code e.g. we shouldn't have to update the gem each time we update the
+  README. This is also good because the only documentation that should go to
+  RubyDoc.info is inline (generated by Yard) which sticks with the version that it
+  was written for making it easy for someone to refer to documentation for old
+  versions.
+* Write tests, coverage now at 98%
+* Fix query_payment_details call "can't split nil String" error due to calling wrong endpoint
+
 v1.5.4
 ------
 

data/{LICENSE.txt → LICENSE.md}

@@ -1,4 +1,7 @@
-Copyright (c) 2013 King'ori Maina
+License
+=======
+
+Copyright (c) 2013-2014 King'ori Maina
 
 MIT License
 
@@ -6,7 +9,7 @@ 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
+distribute, sub-license, 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:
 

data/README.md

@@ -1,29 +1,23 @@
-Pesapal RubyGem
+[Pesapal RubyGem][2]
 ===============
 
 <a href="http://badge.fury.io/rb/pesapal"><img src="https://badge.fury.io/rb/pesapal@2x.png" alt="Gem Version" height="18"></a>
 [![Build Status](https://travis-ci.org/itsmrwave/pesapal-gem.png?branch=master)](https://travis-ci.org/itsmrwave/pesapal-gem)
 [![Code Climate](https://codeclimate.com/github/itsmrwave/pesapal-gem.png)](https://codeclimate.com/github/itsmrwave/pesapal-gem)
+[![Coverage Status](https://coveralls.io/repos/itsmrwave/pesapal-gem/badge.png)](https://coveralls.io/r/itsmrwave/pesapal-gem)
 [![Dependency Status](https://gemnasium.com/itsmrwave/pesapal-gem.png)](https://gemnasium.com/itsmrwave/pesapal-gem)
 
 
-Make authenticated Pesapal API calls without the fuss! Handles all the [oAuth
-stuff][1] abstracting any direct interaction with the API endpoints so that you
-can focus on what matters. _Building awesome_.
+Basically it's a gem that makes it easy to integrate your app with
+[Pesapal][1]'s payment gateway. It Handles all the [oAuth stuff][3] abstracting
+any direct interaction with the API endpoints so that you can focus on what
+matters. _Building awesome_.
 
-This gem, in a nutshell, allows you to easily post an order, query payment
-status and fetch payment details.
+The gem should be [up on RubyGems.org][4], it's [accompanying RubyDoc reference
+here][9], the [CHANGELOG here][5] and [all the releases here][6].
 
-In case you are having any issues using this gem please **_do not_** email me
-directly, I'd rather you submit [issues (and even requests) here][6]. This way,
-other people get to share in the conversation that would have been private and
-out of their reach.
-
-The gem should be [up on RubyGems.org][7], it's [accompanying RubyDoc reference
-here][13], the [CHANGELOG here][21] and [all the releases here][12].
-
-If you are [feeling generous and want to contribute, feel free][9]. See [current
-contributors][19].
+[Check out the homepage for details][2] i.e. on usage, support, issues,
+contributing, testing etc.
 
 _Ps: No 3rd party oAuth library dependencies, it handles all the oAuth flows on
 it's own so your app is one dependency less._
@@ -49,247 +43,29 @@ For Rails, you need to run the generator to create sample pesapal.yml file:
     rails generate pesapal:install
 
 
-Usage
------
-
-
-### Initialization ###
-
-There are 2 ways to initialize the Pesapal object:
-
-1. YAML config at `/config/pesapal.yml`
-2. Config hash
-
-Initialize Pesapal object and choose the environment, there are two environments;
-`:development` and `:production`. They determine if the code will interact
-with the testing or the live Pesapal API.
-
-```ruby
-# Sets environment intelligently to 'Rails.env' (if Rails) or :development (if non-Rails)
-pesapal = Pesapal::Merchant.new
-
-# Sets environment to :development
-pesapal = Pesapal::Merchant.new(:development)
-
-# Sets environment to :production
-pesapal = Pesapal::Merchant.new(:production)
-```
-
-####Option 1####
-
-In the above case, the configuration has already been loaded (at application
-start by initializer) from a YAML file located at `"/config/pesapal.yml"`. The
-appropriate credentials are picked depending on set environment.
-
-This is the recommended method if using Rails.
-
-
-####Option 2####
-
-If you do not wish to use the YAML config method then the object is set up with
-some bogus credentials which would not work anyway and therefore, the other
-option 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
-environments and since this is like an override, there's the assumption that you
-chose the right one).
-
-Recommended if not using Rails.
-
-```ruby
-# 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: You can change the environment using `pesapal.set_env(:development)`
-(example) if for some reason you want to override what was set in the
-constructor. This method also changes the API endpoints appropriately._
-
-
-###YAML Configuration###
-
-The YAML file should look something like this. If you ran the generator you
-should have it already in place with some default values. Feel free to change
-them appropriately.
-
-```yaml
-development:
-  callback_url: 'http://0.0.0.0:3000/pesapal/callback'
-  consumer_key: '<YOUR_DEV_CONSUMER_KEY>'
-  consumer_secret: '<YOUR_DEV_CONSUMER_SECRET>'
-
-production:
-  callback_url: 'http://1.2.3.4:3000/pesapal/callback'
-  consumer_key: '<YOUR_PROD_CONSUMER_KEY>'
-  consumer_secret: '<YOUR_PROD_CONSUMER_SECRET>'
-```
-
-
-### Posting An Order ###
-
-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
-#set order details
-pesapal.order_details = { :amount => 1000,
-                          :description => 'this is the transaction description',
-                          :type => 'MERCHANT',
-                          :reference => '808-707-606',
-                          :first_name => 'Swaleh',
-                          :last_name => 'Mdoe',
-                          :email => 'user@example.com',
-                          :phonenumber => '+254722222222',
-                          :currency => 'KES'
-                        }
-```
-
-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 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._
-
-
-### Querying Payment Status ###
-
-Use this to query the status of the transaction. When a transaction is posted to
-Pesapal, it may be in a PENDING, COMPLETED, FAILED or INVALID state. If the
-transaction is PENDING, the payment may complete or fail at a later stage.
-
-Both the unique merchant reference generated by your system (compulsory) and the
-pesapal transaction tracking id (optional) are input parameters to this method
-but if you don't ensure that the merchant reference is unique for each order on
-your system, you may get INVALID as the response. Because of this, it is
-recommended that you provide both the merchant reference and transaction
-tracking id as parameters to guarantee uniqueness.
-
-```ruby
-# option 1: using merchant reference only
-payment_status = pesapal.query_payment_status("<MERCHANT_REFERENCE>")
-
-# option 2: using merchant reference and transaction id (recommended)
-payment_status = pesapal.query_payment_status("<MERCHANT_REFERENCE>","<TRANSACTION_ID>")
-```
-
-
-### Querying Payment Details ###
-
-Same as querying payment status above, but the return value contains more
-information (and is a hash as opposed to a string).
-
-```ruby
-# pass in merchant reference and transaction id
-payment_details = pesapal.query_payment_details("<MERCHANT_REFERENCE>","<TRANSACTION_ID>")
-```
-
-The result is a hash that looks something like this ...
-
-```
-{
-  :method => "<PAYMENT_METHOD>",
-  :status => "<PAYMENT_STATUS>",
-  :merchant_reference => "<MERCHANT_REFERENCE>",
-  :transaction_tracking_id => "<TRANSACTION_ID>"
-}
-```
-
-
-### IPN Listening ###
-
-Use the `ipn_listener` method to listen to Pesapal IPN calls to easily create an
-appropriate response, example below.
-
-```ruby
-# pass in the notification type, merchant reference and transaction id
-response_to_ipn = pesapal.ipn_listener("<NOTIFICATION_TYPE>", "<MERCHANT_REFERENCE>","<TRANSACTION_ID>")
-```
-
-The variable, `response_to_ipn`, now holds a response as the one shown below.
-Using the status you can customise any actions (e.g. database inserts and
-updates) and finally, it's upto you to send the `:response` back to pesapal. The
-hard part is done for you.
-
-```
-{
-  :status => "<PAYMENT_STATUS>",
-  :response => "<IPN_RESPONSE>"
-}
-```
-
-_Ps: Refer to Pesapal official documentation to make sure you understand what
-data Pesapal sends to IPN and what result they expect back._
-
-
-Contributing & Testing
-----------------------
-
-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]
-3. [Fork it][8]
-4. Create your feature branch (`git checkout -b BRANCH_NAME`)
-5. Make your changes, write tests for them if necessary & run `bundle exec rspec spec`
-6. Commit your changes (`git commit -am 'AWESOME COMMIT MESSAGE'`)
-7. Push to the branch (`git push origin BRANCH_NAME`)
-8. Create new pull request and we can [have the conversations here][17]
-
-_Ps: By the time we have a conversation your [pull request tests should pass on Travis-CI][22] or if they aren't at least you know why._
-
+Contributors
+------------
 
-References
-----------
+Special thanks to:
 
-* [oAuth 1.0 Spec][1]
-* [Developing a RubyGem using Bundler][2]
-* [RailsGuides][20]
-* [Make your own gem][3]
-* [Pesapal API Reference (Official)][4]
-* [Pesapal Step-By-Step Reference (Official)][18]
-* [Pesapal PHP API Reference (Unofficial)][5]
+* [Isaac Mogetutu][10] ([@mogetutu][11])
 
 
 License
 -------
 
-[King'ori J. Maina][10] © 2013. The [MIT License bundled therein][11] is a
+[King'ori J. Maina][7] © 2013-2014. The [MIT License bundled therein][8] is a
 permissive license that is short and to the point. It lets people do anything
 they want as long as they provide attribution and waive liability.
 
-[1]: http://oauth.net/core/1.0/
-[2]: https://github.com/radar/guides/blob/master/gem-development.md
-[3]: http://guides.rubygems.org/make-your-own-gem/
-[4]: http://developer.pesapal.com/how-to-integrate/api-reference
-[5]: https://github.com/itsmrwave/pesapal-php#pesapal-php-api-reference-unofficial
-[6]: https://github.com/itsmrwave/pesapal-gem/issues
-[7]: http://rubygems.org/gems/pesapal
-[8]: https://github.com/itsmrwave/pesapal-gem/fork
-[9]: https://github.com/itsmrwave/pesapal-gem#contributing
-[10]: http://kingori.co/
-[11]: https://github.com/itsmrwave/pesapal-gem/blob/master/LICENSE.txt
-[12]: https://github.com/itsmrwave/pesapal-gem/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-gem/pulls
-[18]: http://developer.pesapal.com/how-to-integrate/step-by-step
-[19]: https://github.com/itsmrwave/pesapal-gem/graphs/contributors
-[20]: http://guides.rubyonrails.org/
-[21]: https://github.com/itsmrwave/pesapal-gem/blob/master/CHANGELOG.md#changelog
+[1]: https://www.pesapal.com/
+[2]: http://itsmrwave.github.io/pesapal-gem
+[3]: http://oauth.net/core/1.0/
+[4]: http://rubygems.org/gems/pesapal
+[5]: https://raw.githubusercontent.com/itsmrwave/pesapal-gem/master/CHANGELOG.md
+[6]: https://github.com/itsmrwave/pesapal-gem/releases/
+[7]: http://kingori.co/
+[8]: https://raw.githubusercontent.com/itsmrwave/pesapal-gem/master/LICENSE.md
+[9]: http://rubydoc.info/gems/pesapal/
+[10]: http://mogetutu.com/
+[11]: https://github.com/mogetutu

data/Rakefile

@@ -1 +1 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'

data/lib/generators/pesapal/install_generator.rb

@@ -1,4 +1,7 @@
 module Pesapal
+  # Since generators are not specific to this project, it's preferable you refer
+  # to the official documentation on the Rails site here;
+  # http://guides.rubyonrails.org/generators.html
   module Generators
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates", __FILE__)

data/lib/pesapal.rb

@@ -1,10 +1,10 @@
 require 'htmlentities'
 require 'net/http'
 
+require 'pesapal/helper/details'
+require 'pesapal/helper/post'
+require 'pesapal/helper/status'
 require 'pesapal/merchant'
-require 'pesapal/merchant/details'
-require 'pesapal/merchant/post'
-require 'pesapal/merchant/status'
 require 'pesapal/oauth'
 require 'pesapal/version'
 

data/lib/pesapal/helper/details.rb

@@ -0,0 +1,53 @@
+module Pesapal
+  # Pesapal helper modules.
+  module Helper
+    # Contains helper methods relating to any queries for payment details. See
+    # {Pesapal::Merchant#query_payment_details} source.
+    module Details
+      # Prepares parameters to be used during the QueryPaymentDetails oAuth 1.0 call.
+      #
+      # The QueryPaymentDetails oAuth 1.0 call requires the following parameters;
+      #
+      # 1. `oauth_consumer_key` - your Pesapal consumer key sent to you via email or obtained from the dashboard
+      # 2. `oauth_nonce` - a random string, uniquely generated for each request. See [section 8 of the oAuth 1.0 spec][3]
+      # 3. `oauth_signature` - the signature as defined in the oAuth 1.0 spec under [section 9 of the oAuth 1.0 spec][2]
+      # 4. `oauth_signature_method` - `HMAC-SHA1` (do not change). See [section 9.2 of the oAuth 1.0 spec][1]
+      # 5. `oauth_timestamp` - number of seconds since January 1, 1970 00:00:00 GMT, also known as Unix Time. See [section 8 of the oAuth 1.0 spec][3]
+      # 6. `oauth_version` - `1.0` (do not change)
+      # 7. `pesapal_merchant_reference` - the transaction merchant reference (same as `merchant_reference` defined below)
+      # 8. `pesapal_transaction_tracking_id` - the transaction tracking id (same as `transaction_tracking_id` defined below)
+      #
+      # This method generates all the above **except** the `oauth_signature` which
+      # is generated later by {Pesapal::Oauth.generate_oauth_signature} since
+      # generation of this `oauth_signature` requires these parameters as inputs
+      # anyway. See [section 9.2.1 of the oAuth 1.0 spec][1] for more details.
+      #
+      # [1]: http://oauth.net/core/1.0/#anchor16
+      # [2]: http://oauth.net/core/1.0/#signing_process
+      # [3]: http://oauth.net/core/1.0/#nonce
+      # [4]: http://oauth.net/core/1.0/
+      #
+      # @param consumer_key [String] your Pesapal consumer key sent to you via
+      #   email or obtained from the dashboard
+      #
+      # @param merchant_reference [String] the unique id generated for the
+      #   transaction by your application before posting the order
+      #
+      # @param transaction_tracking_id [String] the unique id assigned by Pesapal
+      #   to the transaction after it's posted
+      #
+      # @return [Hash] parameters to be used in generating the oAuth 1.0 URL query parameters and the `oauth_signature` itself.
+      def self.set_parameters(consumer_key, merchant_reference, transaction_tracking_id)
+        timestamp = Time.now.to_i.to_s
+        { :oauth_consumer_key => consumer_key,
+          :oauth_nonce => "#{timestamp}" + Pesapal::Oauth.generate_nonce(12),
+          :oauth_signature_method => 'HMAC-SHA1',
+          :oauth_timestamp => "#{timestamp}",
+          :oauth_version => '1.0',
+          :pesapal_merchant_reference => merchant_reference,
+          :pesapal_transaction_tracking_id => transaction_tracking_id
+        }
+      end
+    end
+  end
+end