moiper 0.1.1 → 0.1.2

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+script: bundle exec rspec -bfd spec
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby
+  - ree
+  - rbx-18mode
+  - rbx-19mode

data/README.md

@@ -1,5 +1,7 @@
 # Moiper
 
+[![Build Status](https://travis-ci.org/reu/moiper.png?branch=master)](https://travis-ci.org/reu/moiper)
+
 [Moip payment service](http://moip.com.br/) integration library.
 
 ## Installation
@@ -59,7 +61,7 @@ You need to redirect your user to the url returned by `response.checkout_url`. A
 
 ### Notifications
 
-Moip will notify your application about order updates through [NASP](http://labs.moip.com.br/referencia/nasp/). Moiper provides a Rails controller helper to you can easily intercept these notifications with the `moip_notification` method.
+Moip will notify your application about order updates through [NASP](http://labs.moip.com.br/referencia/nasp/). Moiper provides a Rails controller helper so you can easily intercept these notifications with the `moip_notification` method.
 
 ```ruby
 class OrdersController < ApplicationController
@@ -81,6 +83,14 @@ class OrdersController < ApplicationController
 end
 ```
 
+If you are not using Rails, you can manually instantiate a Moiper::Notification class by passing the POST parameters received from Moip's request.
+
+```ruby
+post "/moip/callback" do
+  notification = Moiper::Notification.new(params)
+end
+```
+
 #### Payment Status
 
 Following are the possible payment statuses returned by the `Moip::Notification#payment_status`.

data/lib/moiper.rb

@@ -6,31 +6,47 @@ require "moiper/notification"
 require "moiper/railtie" if defined? Rails
 
 module Moiper
+  # The available Moip entrypoints
+  # @see http://labs.moip.com.br/referencia/autenticacao_api/#ambientes
+  #   The Moip's official documentation regarding its entrypoints
   API_ENTRYPOINTS = {
     :sandbox    => "https://desenvolvedor.moip.com.br/sandbox/",
     :production => "https://www.moip.com.br/"
   }
 
   class << self
-    # Set Moip's API token
+    # @!group Configurable options
+
+    # @return [String] Moip's API token
     attr_accessor :token
 
-    # Set Moip's API key
+    # @return [String] Moip's API key
     attr_accessor :key
 
     # Define if requests should be made against Moip's sandbox
     # environment. This is specially usefull when running
-    # on development or test mode. Default is false.
+    # on development or test mode. Default is false
+    #
+    # @see http://labs.moip.com.br/referencia/autenticacao_api/#sandbox
+    #   Moip's official documentation regarding sandbox activation
     #
-    #  Moiper.sandbox = true
+    # @example
+    #   Moiper.sandbox = true
     #
+    # @return [Boolean] current sandbox state
     attr_accessor :sandbox
 
-    # Configure Moiper options.
+    # @!endgroup
+
+    # Configure Moiper's options
+    #
+    # @yieldparam config [Moiper]
+    # @return [void]
     #
-    #  Moiper.configure do |config|
-    #    config.sandbox = true
-    #  end
+    # @example
+    #   Moiper.configure do |config|
+    #     config.sandbox = true
+    #   end
     #
     def configure(&block)
       yield self
@@ -41,7 +57,7 @@ module Moiper
       sandbox == true
     end
 
-    # Returns the Moip API entrypoint based on the current environment
+    # @return [String] the Moip API entrypoint based on the current environment
     def api_entrypoint
       sandbox? ? API_ENTRYPOINTS[:sandbox] : API_ENTRYPOINTS[:production]
     end

data/lib/moiper/notification.rb

@@ -1,5 +1,7 @@
 module Moiper
   class Notification
+    # @see http://labs.moip.com.br/parametro/statuspagamento/
+    #   The list of payment status on the Moip's official documentation
     PAYMENT_STATUSES = {
       1 => :authorized,
       2 => :started,
@@ -11,6 +13,8 @@ module Moiper
       9 => :reimbursed
     }
 
+    # @see http://labs.moip.com.br/parametro/instituicaopagamento/
+    #   The list of financial institutions on the Moip's official documentation
     FINANCIAL_INSTITUTIONS = {
       1 => "MoIP",
       3 => "Visa",
@@ -25,6 +29,8 @@ module Moiper
       88 => "Banrisul"
     }
 
+    # @see http://labs.moip.com.br/parametro/formapagamento/
+    #   The list of payment methods on the Moip's official documentation
     PAYMENT_METHODS = {
       "BoletoBancario" => :payment_form,
       "CartaoDeCredito" => :credit_card,
@@ -41,38 +47,57 @@ module Moiper
       @params = params
     end
 
+    # @return [String] informed unique identifier
     def id
       params["id_transacao"]
     end
 
+    # @return [Float] amount paid by the user
     def price
       params["valor"].to_i / 100.0
     end
 
+    # @return [Symbol] payment status
+    # @see PAYMENT_STATUSES The full list of possible payment statuses
+    #   returned
     def payment_status
       PAYMENT_STATUSES[params["status_pagamento"].to_i]
     end
 
+    # @return [Integer] the internal Moip identifier for this transaction
     def moip_id
       params["cod_moip"].to_i
     end
 
+    # @return [String] financial institution name
+    # @see FINANCIAL_INSTITUTIONS The full list of possible financial
+    #   institutions returned
     def financial_institution
       FINANCIAL_INSTITUTIONS[params["forma_pagamento"].to_i]
     end
 
+    # @return [String] payment method used by this transaction
+    # @see PAYMENT_METHODS The full list of possible payment
+    #   method returned
     def payment_method
       PAYMENT_METHODS[params["tipo_pagamento"]]
     end
 
+    # @return [Integer] number of quotas that the payment was
+    #   divided
     def quotas
       params["parcelas"].to_i
     end
 
+    # @return [String] user email address
     def user_email
       params["email_consumidor"]
     end
 
+    # @return [String] additional information provided by the financial
+    #   institution regarding this transaction when it has a canceled status
+    # @see http://labs.moip.com.br/referencia/classificacao-de-cancelamento/
+    #   The Moip's official documentation regarting payment cancelling
     def additional_info
       params["classificacao"]
     end

data/lib/moiper/notification_controller_helper.rb

@@ -1,5 +1,32 @@
 module Moiper
   module NotificationControllerHelper
+    # Helper method to abstract how to create a notification during the Moip's
+    # NASP request.
+    #
+    # @see http://labs.moip.com.br/referencia/nasp/ Moip's NASP documentation
+    #
+    # @param data [Hash] controller parameters
+    # @yieldparam [Notification] notification update from Moip
+    # @return [Notification]
+    #
+    # @example Usage inside a Rails controller
+    #   class OrdersController < ApplicationController
+    #     include Moiper::NotificationControllerHelper
+    #
+    #     def confirm
+    #       moip_notification do |notification|
+    #         # Here you can update your database with updated information.
+    #         # Ex:
+    #         @order = Order.find_by_unique_identifier(notification.id)
+    #         @order.update_attribute :status, notification.payment_status
+    #         @order.save
+    #
+    #         # Moip will recognize the request as successfully if the statuses
+    #         # are 200, 201, 202, 203, 204, 205, 206 or 207.
+    #         head 200
+    #       end
+    #     end
+    #   end
     def moip_notification(data = params, &block)
       notification = Notification.new(data)
       yield notification if block_given?

data/lib/moiper/payment.rb

@@ -2,27 +2,44 @@ require "nokogiri"
 
 module Moiper
   class Payment
-    # The unique ID you can set for this payment. This is usefull to keep
-    # trak of which payment we will receive on the Moip's notification process.
+    # @return [String] the unique ID you can set for this payment. This is usefull to keep
+    #   track of which payment we will receive on the Moip's notification process
     attr_accessor :id
 
-    # The description of the purchase.
+    # @return [String] the description of the purchase
     attr_accessor :description
 
-    # The amount to be billed from the user.
+    # @return [Float] the amount to be billed from the user
     attr_accessor :price
 
-    # The URL where the user will be redirected after he finishes the
-    # payment process.
+    # @return [Float] the amount to be increased from the final price
+    attr_accessor :accretion
+
+    # @return [Float] the amount to be deducted from the final price
+    attr_accessor :deduction
+
+    # @return [String] the URL where the user will be redirected after he finishes the
+    #   payment process.
     attr_accessor :return_url
 
-    # The URL where Moip will send notifications about your purchase updates.
+    # @return [String] the URL where Moip will send notifications about your purchase updates
     attr_accessor :notification_url
 
     # Create a new Moip Payment request
+    #
+    # @param [Hash] options the options to create the payment with
+    # @option options [String] :description {#description}
+    # @option options [String, #to_s] :id {#id}
+    # @option options [#to_f] :price {#price}
+    # @option options [#to_f] :accretion {#accretion}
+    # @option options [#to_f] :deduction {#deduction}
+    # @option options [String, #to_s] :return_url {#return_url}
+    # @option options [String, #to_s] :notification_url {#notification_url}
+    #
+    # @raise [ArgumentError] if description or price options are blank
     def initialize(options = {})
-      raise ArgumentError if options[:description].nil? || options[:description].empty?
-      raise ArgumentError if options[:price].nil? || options[:price].to_f <= 0
+      raise ArgumentError, "You must inform a description" if options[:description].nil? || options[:description].empty?
+      raise ArgumentError, "You must inform a price" if options[:price].nil? || options[:price].to_f <= 0
 
       options.each do |attribute, value|
         send "#{attribute}=", value
@@ -30,6 +47,7 @@ module Moiper
     end
 
     # Create the payment XML representation
+    # @return [String] Moip's formatted XML
     def to_xml
       builder = Nokogiri::XML::Builder.new(:encoding => "UTF-8") do |xml|
         xml.EnviarInstrucao {
@@ -39,6 +57,8 @@ module Moiper
 
             xml.Valores {
               xml.Valor price, :moeda => "BRL"
+              xml.Acrescimo accretion, :moeda => "BRL" if accretion
+              xml.Deducao deduction, :moeda => "BRL" if deduction
             }
 
             xml.URLNotificacao notification_url if notification_url
@@ -50,6 +70,8 @@ module Moiper
       builder.to_xml
     end
 
+    # Send a new payment request to Moip
+    # @return [Response] the Moip response
     def checkout
       request = Request.new
       request.process(to_xml)

data/lib/moiper/railtie.rb

@@ -2,6 +2,7 @@ module Moiper
   class Railtie < Rails::Railtie
     # Expose Moiper's configuration to the Rails application configuration.
     #
+    # @example
     #   module MyApplication
     #     class Application < Rails::Application
     #       config.moiper.sandbox = true
@@ -11,10 +12,13 @@ module Moiper
     #   end
     config.moiper = Moiper
 
+    # Load notification controller helper
     initializer "load notification controller helper" do
       require "moiper/notification_controller_helper"
     end
 
+    # Automatically read and configure Moiper with the content
+    # of the config/moiper.yml file if it is present
     initializer "load moiper.yml file" do
       config_file = Rails.root.join("config", "moiper.yml")
 

data/lib/moiper/request.rb

@@ -5,13 +5,17 @@ module Moiper
   class Request
     CA_FILE = File.expand_path(File.dirname(__FILE__)) + "/cacert.pem"
 
-    attr_reader :response
-
+    # Process a given payload
+    # @param payload [String]
+    # @return [Response] the response from Moip
     def process(payload)
-      @response = post(payload)
-      Response.new(@response.body)
+      response = post(payload)
+      Response.new(response.body)
     end
 
+    # @!group HTTP handling
+
+    # @return [Net::HTTP::Session] the http session client
     def client
       @client ||= Net::HTTP.new(uri.host, uri.port).tap do |http|
         http.use_ssl = true
@@ -20,6 +24,9 @@ module Moiper
       end
     end
 
+    # @return [Net::HTTP::Post] the http POST request already
+    #   configured with the right agent, content type and
+    #   basic authentication headers
     def request
       @request ||= Net::HTTP::Post.new(uri.path).tap do |request|
         request.basic_auth Moiper.token, Moiper.key
@@ -28,6 +35,8 @@ module Moiper
       end
     end
 
+    # @!endgroup
+
     private
 
     def post(payload)
@@ -39,6 +48,8 @@ module Moiper
       @uri ||= URI(Moiper.api_entrypoint + path)
     end
 
+    # @api private
+    # @return [String] path where the request should be made
     def path
       "ws/alpha/EnviarInstrucao/Unica"
     end

data/lib/moiper/response.rb

@@ -1,21 +1,29 @@
 module Moiper
   class Response
+    # @param body [String] the response body from Moip
     def initialize(body)
       @body = body
     end
 
+    # Detects if the response was successfully
+    # @return [Boolean]
     def success?
       parsed_body.css("Status").text == "Sucesso"
     end
 
+    # @return [String, nil] the URL which the user should be redirected
+    #   to finish payment process or nil if the request was not successfully
     def checkout_url
       Moiper.api_entrypoint + "Instrucao.do?token=" + token if success?
     end
 
+    # @return [String] the response token
     def token
       parsed_body.css("Token").text
     end
 
+    # List the possible errors returned by Moip
+    # @return [Array<String>]
     def errors
       parsed_body.css("Erro").map(&:text)
     end

data/lib/moiper/version.rb

@@ -1,4 +1,3 @@
 module Moiper
-  # Specify the current gem version
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/spec/moiper/payment_spec.rb

@@ -82,6 +82,8 @@ describe Moiper::Payment do
       Moiper::Payment.new(
         :description      => "A chair",
         :price            => 1.99,
+        :accretion        => 0.5,
+        :deduction        => 0.3,
         :id               => "some unique id",
         :return_url       => "http://example.org/thank_you",
         :notification_url => "http://example.org/moip/notification"
@@ -99,9 +101,16 @@ describe Moiper::Payment do
     it { doc.at_css("InstrucaoUnica > URLNotificacao").should_not be_nil }
 
     it { doc.at_css("InstrucaoUnica > IdProprio").text.should eq "some unique id"}
+
     it { doc.at_css("Valores > Valor").text.should eq "1.99"}
     it { doc.at_css("Valores > Valor").attributes["moeda"].value.should eq "BRL"}
 
+    it { doc.at_css("Valores > Acrescimo").text.should eq "0.5"}
+    it { doc.at_css("Valores > Acrescimo").attributes["moeda"].value.should eq "BRL"}
+
+    it { doc.at_css("Valores > Deducao").text.should eq "0.3"}
+    it { doc.at_css("Valores > Deducao").attributes["moeda"].value.should eq "BRL"}
+
     it { doc.at_css("InstrucaoUnica > URLRetorno").text.should eq "http://example.org/thank_you" }
     it { doc.at_css("InstrucaoUnica > URLNotificacao").text.should eq "http://example.org/moip/notification" }
 

data/spec/moiper/request_spec.rb

@@ -34,8 +34,7 @@ describe Moiper::Request do
     end
 
     it "has the correct user agent" do
-      headers = Hash[subject.each_capitalized.to_a]
-      headers["User-Agent"].should eq "Moiper/#{Moiper::VERSION}"
+      subject.get_fields("user-agent")[0].should eq "Moiper/#{Moiper::VERSION}"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moiper
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-23 00:00:00.000000000 Z
+date: 2013-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &2152746220 !ruby/object:Gem::Requirement
+  requirement: &2160708660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152746220
+  version_requirements: *2160708660
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2152745700 !ruby/object:Gem::Requirement
+  requirement: &2160708220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152745700
+  version_requirements: *2160708220
 description: Moip payment service integration library.
 email:
 - rnavarro1@gmail.com
@@ -41,6 +41,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -76,7 +77,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1028028193519655170
+      hash: -1487992565957500539
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -85,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1028028193519655170
+      hash: -1487992565957500539
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.11