zaypay 1.0.1 → 1.0.2

data/lib/zaypay/error.rb

@@ -1,6 +1,7 @@
 module Zaypay
+  # Errors that can be raised by the Zaypay gem
   class Error < StandardError
-     def initialize(type = nil, message = "default message")
+     def initialize(type = nil, message = "Error thrown by the Zaypay gem.")
        @type = type
        super(message)
      end

data/lib/zaypay/price_setting.rb

@@ -1,40 +1,102 @@
 module Zaypay
   require 'yaml'
+  
+  # PriceSetting instances allows you to communicate to the Zaypay platform.
+  #
+  # It is basically a Ruby wrapper for the Zaypay-API, which provides you a bunch of payment-related methods, as well as some utility methods.
   class PriceSetting
     include HTTParty
-    attr_reader :price_setting_id, :key
+    attr_reader :price_setting_id, :api_key
     attr_accessor :locale, :payment_method_id
 
     base_uri 'https://secure.zaypay.com'
     headers :Accept => 'application/xml'
 
-    def initialize(price_setting_id=nil, key=nil)
-      @price_setting_id, @key = price_setting_id, key
+    # Creates instances of Zaypay::PriceSetting.
+    # 
+    # To instantiate, one must provide a PriceSetting-id and its API-Key.
+    # You can obtain these information once you have created a PriceSetting on the Zaypay platform (http://www.zaypay.com).
+    #
+    # You can also call the "one-arg" or the "no-args" version of the initializer,
+    # but to do that, you must first create config/zaypay.yml in your Rails app, see the {file:/README.rdoc README} file.
+    #
+    # @param [Integer] price_setting_id your PriceSetting's id
+    # @param [String] api_key your PriceSetting's api-key
+    def initialize(price_setting_id=nil, api_key=nil)
+      @price_setting_id, @api_key = price_setting_id, api_key
       select_settings
     end
 
-    def locale_for_ip(ip)
-      get "/#{ip}/pay/#{price_setting_id}/locale_for_ip" do |data|
-        parts = data[:locale].split('-')
-        {:country => parts[1], :language => parts[0]}
+    def locale=(arg)
+      case arg
+      when Hash
+        if arg.has_key?(:language) && arg.has_key?(:country)
+          @locale = Zaypay::Util.stringify_locale_hash(arg)
+        else
+          raise Zaypay::Error.new(:locale_not_set, "The hash you provided was invalid. Please make sure it contains the keys :language and :country")
+        end
+      when String
+        @locale = arg
       end
     end
-
+    
+    # Returns the default locale as a string for a given ip_address, with the first part representing the language, the second part the country
+    #
+    # This method comes in handy when you want to preselect the language and country when your customer creates a payment on your website.
+    #
+    # = Example: 
+    #    # We take an ip-address from Great Britain for example:
+    #    ip = "212.58.226.75"
+    #    @price_setting.locale_string_for_ip(ip)
+    #    => 'en-GB'
+    #
+    # Also see {#locale_for_ip}
+    # @param [String] ip an ip-address (e.g. from your site's visitors)
+    # @return [String] a string that represents the default locale for the given IP, in a language-country format.
     def locale_string_for_ip(ip)
       get "/#{ip}/pay/#{price_setting_id}/locale_for_ip" do |data|
         parts = data[:locale].split('-')
         Zaypay::Util.stringify_locale_hash({:country => parts[1], :language => parts[0]})
       end
     end
+    
+    # Returns the default locale as a hash for a given ip_address.
+    #
+    # It is similar to {#locale_string_for_ip}, except that this method returns the locale as a hash
+    # This method comes in handy when you want to preselect only the langauge or the country for your customer
+    #
+    # = Example: 
+    #    # We take an ip-address from Great Britain for example:
+    #    ip = "212.58.226.75"
+    #    @price_setting.locale_string_for_ip(ip)
+    #    => { :country => 'GB', :language => 'en' }
+    #
+    # @param [String] ip an ip-address (e.g. from your site's visitors)
+    # @return [Hash] a hash with :country and :language as keys
+    def locale_for_ip(ip)
+      get "/#{ip}/pay/#{price_setting_id}/locale_for_ip" do |data|
+        parts = data[:locale].split('-')
+        {:country => parts[1], :language => parts[0]}
+      end
+    end
 
-    def ip_country_is_configured?(ip, options={})
+    # Returns a country as a Hash, if the country of the given IP has been configured for your Price Setting.
+    #
+    # If the country of the given IP has been configured for this Price Setting, it returns a hash with *:country* and *:locale* subhashes, else it returns *nil*.
+    #
+    # @param [String] ip an ip-address (e.g. from your site's visitors)
+    # @return [Hash] a hash containing *:country* and *:locale* subhashes
+    def country_has_been_configured_for_ip(ip, options={})
       # options can take a :amount key
       locale  = locale_for_ip(ip)
       country = list_countries(options).select{ |c| c.has_value? locale[:country] }.first
       {:country => country, :locale => locale} if country
     end
 
-    # returns a hash containing keys countries and languages
+    # Returns a hash containing the countries and languages that are available to your Price Setting.
+    #
+    # @param [Hash] options an options-hash that can take an *:amount* option, in case you want to use dynamic amounts
+    # @return [Hash] a hash containing subhashes of countries and languages
     def list_locales(options={})
       get "/#{options[:amount]}/pay/#{price_setting_id}/list_locales" do |data|
         {:countries => Zaypay::Util.arrayify_if_not_an_array(data[:countries][:country]),
@@ -42,20 +104,31 @@ module Zaypay
       end
     end
 
-    # returns an array with countries
+    # Returns an array of countries that are available to your Price Setting.
+    #
+    # @param [Hash] options an options-hash that can take an *:amount* option, in case you want to use dynamic pricing
+    # @return [Array] an array of countries, each represented by a hash with *:code* and *:name*
     def list_countries(options={})
       get "/#{options[:amount]}/pay/#{price_setting_id}/list_locales" do |data|
         Zaypay::Util.arrayify_if_not_an_array(data[:countries][:country])
       end
     end
 
-    # returns an array with languages
+    # Returns an array of languages that are available to your Price Setting.
+    #
+    # @param [Hash] options an options-hash that can take an *:amount* option, in case you want to use dynamic pricing
+    # @return [Array] an array of languages, each represented by a hash with *:code*, *:english_name*, *:native_name*
     def list_languages(options={})
       get "/#{options[:amount]}/pay/#{price_setting_id}/list_locales" do |data|
         data[:languages][:language]
       end
     end
 
+    # Returns an array of payment methods that are available to your Price Setting with a given locale
+    #
+    # @param [Hash] options an options-hash that can take an *:amount* option, in case you want to use dynamic amounts
+    # @return [Array] an array of payment methods, each represented by a hash.
+    # @raise [Zaypay::Error] in case you call this method before setting a locale
     def list_payment_methods(options={})
       raise Zaypay::Error.new(:locale_not_set, "locale was not set for your price setting") if @locale.nil?
       get "/#{options[:amount]}/#{@locale}/pay/#{price_setting_id}/payments/new" do |data|
@@ -63,7 +136,21 @@ module Zaypay
       end
     end
 
-    # Example: @price_setting.create_payment(:custom_variable => "my value", :payalogue_id => payalogue_id, :amount => optional_amount )
+    # Creates a payment on the Zaypay platform.
+    # 
+    # You can provide an options-hash, which will add additional data to your payment. The following keys have special functionalities:
+    #
+    #   :amount        # Enables dynamic pricing. It must be an integer representing the price in cents.
+    #   :payalogue_id  # Adds the URL of the payalogue specified to your payment as :payalogue_url.
+    #
+    # Any other keys will be added to a key named :your_variables, which can be used for your future reference. Please check the {file:/README.rdoc README} for the structure of the payment returned.
+    #
+    # = Example: 
+    #    @price_setting.create_payment(:payalogue_id => payalogue_id, :amount => optional_amount, :my_variable_1 => "value_1", :my_variable_2 => "value_2")
+    # 
+    # @param [Hash] options an options-hash that can take an *:amount*, *:payalogue_id* as options, and any other keys can be used as your custom variables for your own reference
+    # @return [Hash] a hash containing data of the payment you just created
+    # @raise [Zaypay::Error] in case you call this method before setting a *locale* or a *payment_method_id*
     def create_payment(options={})
       raise Zaypay::Error.new(:locale_not_set, "locale was not set for your price setting") if @locale.nil?
       raise Zaypay::Error.new(:payment_method_id_not_set, "payment_method_id was not set for your price setting") if @payment_method_id.nil?
@@ -75,18 +162,35 @@ module Zaypay
       end
     end
 
+    # Returns the specified payment as a hash.
+    #
+    # @param [Integer] payment_id your payment's id
+    # @return [Hash] a hash containing data of the specified payment
     def show_payment(payment_id)
       get "///pay/#{price_setting_id}/payments/#{payment_id}" do |data|
         payment_hash data
       end
     end
 
+    # Submits a verification code to the Zaypay platform.
+    #
+    # In some countries, the end-user must submit a verification code in order to complete a payment. Please refer to the {file:/README.rdoc README} for more details
+    # 
+    # @param [Integer] payment_id the id of the payment that needs to be finalized
+    # @param [Integer] verification_code a code that the end-user receives through an sms and that he must submit to complete this payment
+    # @return [Hash] a hash containing data of the specified payment
     def verification_code(payment_id, verification_code)
       post "///pay/#{price_setting_id}/payments/#{payment_id}/verification_code", :verification_code => verification_code do |data|
         payment_hash data
       end
     end
 
+    # Posts a request to the Zaypay platform to mark that you have delivered the 'goodies' to your customer. 
+    #
+    # Please refer to {file:/README.rdoc README} for more details.
+    #
+    # @param [Integer] payment_id the payment's id
+    # @return [Hash] a hash containing data of the specified payment
     def mark_payload_provided(payment_id)
       post "///pay/#{price_setting_id}/payments/#{payment_id}/mark_payload_provided" do |data|
         payment_hash data
@@ -95,7 +199,7 @@ module Zaypay
 
     protected
     def select_settings
-      unless @price_setting_id and @key
+      unless @price_setting_id and @api_key
         begin
           config = YAML.load_file("#{Rails.root}/config/zaypay.yml")
         rescue => e
@@ -107,8 +211,8 @@ module Zaypay
         raise config_error unless config
 
         @price_setting_id = config['default'] unless @price_setting_id
-        @key = config[@price_setting_id]
-        if @key.nil? || @price_setting_id.nil?
+        @api_key = config[@price_setting_id]
+        if @api_key.nil? || @price_setting_id.nil?
           raise config_error
         end
       end
@@ -130,7 +234,7 @@ module Zaypay
     end
 
     def default_query
-      {:key => key}
+      {:key => api_key}
     end
 
     def payment_hash(data)

data/lib/zaypay/util.rb

@@ -1,6 +1,19 @@
 module Zaypay
+  
+  # A class containing some utility methods.
   class Util
 
+    # Symbolize keys recursively - Not just for hashes within a Hash, but also for hashes within an Array.
+    #
+    # = Example:
+    # 
+    #   hashie = { 'a' => 'A', 'b' => ['B'], 'c' => [ {'cc' => 'CC'} ], 'd' => { 'e' => 'E', :f => { :ff => 'FF' } } }
+    #   Zaypay::Util.uber_symbolize(hashie)
+    #
+    #   => { :a => "A", :b => ["B"], :c => [ {:cc=>"CC"} ], :d => { :e => "E", :f => { :ff => "FF" } } } 
+    #
+    # @param data A hash or an array that you want to symbolize recursively
+    # @return A hash or an array that has been symbolized recursively for you
     def self.uber_symbolize(data)
       if data.is_a?(Hash)
         data.keys.each do |key|
@@ -16,13 +29,22 @@ module Zaypay
       data
     end
 
+    # Turns a hash with *:language* and *:country* keys to a string that represents the locale
+    # 
+    # = Example:
+    #
+    #   Zaypay::Util.stringify_locale_hash( { :country=>"NL", :language=>"nl" } ) 
+    #   => 'nl-NL'
+    #
+    # @param [Hash] locale_hash a hash that represents the locale
+    # @return [String] a string representing the locale in the format "language-country"
     def self.stringify_locale_hash(locale_hash)
       locale_hash[:language] << '-' << locale_hash[:country]
     end
 
+    # Wraps something in an array if it is not an array
     def self.arrayify_if_not_an_array(obj)
       obj.is_a?(Array) ? obj : [obj]
     end
-
   end
 end

data/lib/zaypay/version.rb

@@ -1,3 +1,3 @@
 module Zaypay
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/test/price_setting_test.rb

@@ -24,7 +24,7 @@ class PriceSettingTest < Test::Unit::TestCase
           YAML.expects(:load_file).with('anywhere/config/zaypay.yml').returns({ @price_setting_id => @api_key, "default"=>@price_setting_id})
           ps = Zaypay::PriceSetting.new
           assert_equal @price_setting_id, ps.price_setting_id
-          assert_equal @api_key, ps.key
+          assert_equal @api_key, ps.api_key
         end
         should "raise Error if yml is blank" do
           error = assert_raise Zaypay::Error do
@@ -56,7 +56,7 @@ class PriceSettingTest < Test::Unit::TestCase
           YAML.expects(:load_file).never
           ps = Zaypay::PriceSetting.new(@price_setting_id, @api_key)
           assert_equal @price_setting_id, ps.price_setting_id
-          assert_equal @api_key, ps.key
+          assert_equal @api_key, ps.api_key
         end
       end
 
@@ -66,7 +66,7 @@ class PriceSettingTest < Test::Unit::TestCase
             YAML.expects(:load_file).with('anywhere/config/zaypay.yml').returns({@price_setting_id => @api_key})
             ps = Zaypay::PriceSetting.new(@price_setting_id)
             assert_equal @price_setting_id, ps.price_setting_id
-            assert_equal @api_key, ps.key
+            assert_equal @api_key, ps.api_key
           end
         end
         context "without a valid yml file" do  
@@ -82,6 +82,22 @@ class PriceSettingTest < Test::Unit::TestCase
       end
     end
 
+    context "#locale=()" do
+      context "string as arg" do
+        should 'return set locale as a string' do
+          @ps.locale = 'nl-NL'
+          assert_equal 'nl-NL', @ps.locale
+        end
+      end
+      
+      context "hash as arg" do
+        should 'return set locale as a string' do
+          @ps.locale = {:country=>"NL", :language=>"nl"} 
+          assert_equal 'nl-NL', @ps.locale
+        end
+      end
+    end
+    
     context "#locale_for_ip" do
       setup do
         FakeWeb.register_uri(:get,"#{@base_uri}/#{@ip}/pay/#{@ps.price_setting_id}/locale_for_ip?key=#{@api_key}", :body => 'test/locale_for_ip.xml', :content_type => "text/xml")
@@ -449,7 +465,7 @@ class PriceSettingTest < Test::Unit::TestCase
                                                   {:query => {:key => @api_key}, :headers => @headers }).returns @ip_response
           Zaypay::PriceSetting.expects(:get).with("#{@base_uri}//pay/#{@ps.price_setting_id}/list_locales", 
                                                   {:query => {:key => @api_key}, :headers => @headers }).returns @single_country_response
-          assert_nil @ps.ip_country_is_configured?(@ip)
+          assert_nil @ps.country_has_been_configured_for_ip(@ip)
         end
       end
 
@@ -464,7 +480,7 @@ class PriceSettingTest < Test::Unit::TestCase
                                                     {:query => {:key => @api_key}, :headers => @headers }).returns @ip_response
             Zaypay::PriceSetting.expects(:get).with("#{@base_uri}//pay/#{@ps.price_setting_id}/list_locales", 
                                                     {:query => {:key => @api_key}, :headers => @headers }).returns @multi_country_response
-            assert_equal({:country => {:name => 'Netherlands', :code => 'NL'}, :locale => {:country => 'NL', :language => 'nl'}} , @ps.ip_country_is_configured?(@ip))
+            assert_equal({:country => {:name => 'Netherlands', :code => 'NL'}, :locale => {:country => 'NL', :language => 'nl'}} , @ps.country_has_been_configured_for_ip(@ip))
           end
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zaypay
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-24 00:00:00.000000000 Z
+date: 2012-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -155,6 +155,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.2.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.2.1
 description: This gem provides you a PriceSetting class which allows you to send request
   to the Zaypay API in order to create payments, display payment details and contains
   other useful methods. Pleases refer to http://zaypay.com/developers for more information