samurai 0.2.18 → 0.2.19

data/lib/samurai.rb

@@ -1,6 +1,19 @@
-# Author::    Graeme Rouse
-# Copyright:: Copyright (c) 2011 Arizona Bay, LLC
+# Samurai Gem
+# -----------------
 
+# Core Samurai Module
+# Contains accessors for the important Samurai configuration settings
+#
+# To configure the Samurai gem:
+#
+# ```ruby
+# require 'samurai'
+# Samurai.options = {
+#   :merchant_key => 'a1ebafb6da5238fb8a3ac9f6',
+#   :merchant_password => 'ae1aa640f6b735c4730fbb56',
+#   :processor_token => '69ac9c704329bb067d427bf0'
+# }
+# ```
 module Samurai
   SITE = 'https://api.samurai.feefighters.com/v1/'
   DEFAULT_OPTIONS = {:site => SITE}
@@ -33,6 +46,7 @@ module Samurai
 
 end
 
+# Require each of the samurai components
 require 'samurai/cacheable_by_token'
 require 'samurai/base'
 require 'samurai/processor'
@@ -40,7 +54,6 @@ require 'samurai/payment_method'
 require 'samurai/transaction'
 require 'samurai/message'
 require 'samurai/processor_response'
-
 require 'samurai/rails'
 
 

data/lib/samurai/base.rb

@@ -3,10 +3,16 @@ begin
 rescue LoadError
   require 'activeresource' # for older versions of activeresource
 end
+
+# Samurai::Base
+# -----------------
+
+# Base class that all Samurai ActiveResource models inherit from
+# Provides some common error-handling functionality, as well as the AR site settings
 class Samurai::Base < ActiveResource::Base
   self.format = ActiveResource::Formats::XmlFormat
 
-  def self.setup_site! # :nodoc:
+  def self.setup_site!
     self.site = Samurai.site
     self.user = Samurai.merchant_key
     self.password = Samurai.merchant_password

data/lib/samurai/cacheable_by_token.rb

@@ -1,7 +1,13 @@
+# Samurai::CacheableByToken
+# -----------------
+
+# Module for enabling caching of ActiveResource classes by token
+# Essentially functions as a simple Identity Map
 module Samurai::CacheableByToken
   
   # The default cache stores the values for the duration of the request
   # Different caching strategies can be employed to keep the data around longer:
+  #
   #  * class variables
   #  * Rails.cache
   #  * memcached
@@ -13,7 +19,7 @@ module Samurai::CacheableByToken
   end
   
   module ClassExtensions
-    # Override the ActiveResource +find+ method to query the cache before hitting the provider.
+    # Override the ActiveResource `find` method to query the cache before hitting the provider.
     def find(*arguments)
       token = arguments.first
       if token.is_a?(String) && self.cache[token]
@@ -27,7 +33,7 @@ module Samurai::CacheableByToken
     end
   end
   
-  # Overrides the ActiveResource +save+ method to update the current
+  # Overrides the ActiveResource `save` method to update the current
   # model in the cache
   def save
     super

data/lib/samurai/message.rb

@@ -1,4 +1,9 @@
-class Samurai::Message < Samurai::Base # :nodoc:
+# Samurai::Message
+# -----------------
+
+# Simple class for serializing Samurai <message> responses
+class Samurai::Message < Samurai::Base
+
   def to_xml(options = {})
     builder = options[:builder] || Builder::XmlMarkup.new(options)
     builder.tag!(:message) do
@@ -7,4 +12,5 @@ class Samurai::Message < Samurai::Base # :nodoc:
       end
     end
   end
+
 end

data/lib/samurai/payment_method.rb

@@ -1,18 +1,24 @@
 require 'active_resource/version'
+
+# Samurai::PaymentMethod
+# -----------------
+
+# Samurai credit card tokenization, including retaining & redacting Payment Methods
 class Samurai::PaymentMethod < Samurai::Base
   
   include Samurai::CacheableByToken
 
-  def id # :nodoc:
+  def id
     self.token
   end
   
-  # Alias for +payment_method_token+
+  # Alias for `payment_method_token`
   def token
     self.payment_method_token
+    # self.attributes["payment_method_token"]
   end
   
-  # Retains the payment method on api.samurai.feefighters.com. Retain a payment method if
+  # Retains the payment method on `api.samurai.feefighters.com`. Retain a payment method if
   # it will not be used immediately. 
   def retain
     self.post(:retain)
@@ -28,17 +34,18 @@ class Samurai::PaymentMethod < Samurai::Base
     @custom_data ||= self.custom && (JSON.parse(self.custom) rescue {}).symbolize_keys
   end
 
+  # Override base error processing with specific PaymentMethod behavior
+  # Examine the `<messages>` array, and add an error to the Errors object for each `<message>`
   def process_response_errors
     if respond_to?(:messages) && self.messages
       self.messages.each do |message|
-        #if (message.respond_to?(:subclass) && message.subclass == 'error')
-          self.errors.add message.context.gsub(/\./, ' '), message.key
-        #end
+        self.errors.add message.context.gsub(/\./, ' '), message.key
       end
     end
   end
   protected :process_response_errors
 
+  # Setup the PaymentMethod schema for ActiveResource, so that new objects contain empty attributes
   KNOWN_ATTRIBUTES = [
     :first_name, :last_name, :address_1, :address_2, :city, :state, :zip,
     :card_number, :cvv, :expiry_month, :expiry_year
@@ -57,7 +64,7 @@ class Samurai::PaymentMethod < Samurai::Base
     end
   end
 
-  # Prepare a new PaymentMethod for use with a transparent redirect form
+  # Convenience method for preparing a new PaymentMethod for use with a transparent redirect form
   def self.for_transparent_redirect(params)
     if params[:payment_method_token].blank?
       Samurai::PaymentMethod.new(params)

data/lib/samurai/processor.rb

@@ -1,3 +1,8 @@
+# Samurai::Processor
+# -----------------
+
+# This class represents a Samurai Processor connection
+# It can be used to create purchase & authorize transactions
 class Samurai::Processor < Samurai::Base
   
   # Returns the default processor specified by Samurai.processor_token if you passed it into Samurai.setup_site.
@@ -17,34 +22,40 @@ class Samurai::Processor < Samurai::Base
   
   # Convenience method to authorize and capture a payment_method for a particular amount in one transaction.
   # Parameters:
-  # +payment_method_token+:: token identifying the payment method to authorize
-  # +amount+:: amount to authorize
-  # options:: an optional has of additional values to pass in accepted values are:
-  # *+descriptor+:: descriptor for the transaction
-  # *+custom+:: custom data, this data does not get passed to the processor, it is stored within api.samurai.feefighters.com only
-  # *+customer_reference+:: an identifier for the customer, this will appear in the processor if supported
-  # *+billing_reference::+ an identifier for the purchase, this will appear in the processor if supported
+  #
+  # * `payment_method_token`: token identifying the payment method to authorize
+  # * `amount`: amount to authorize
+  # * `options`: an optional has of additional values to pass in accepted values are:
+  #   * `descriptor`: descriptor for the transaction
+  #   * `custom`: custom data, this data does not get passed to the processor, it is stored within `api.samurai.feefighters.com` only
+  #   * `customer_reference`: an identifier for the customer, this will appear in the processor if supported
+  #   * `billing_reference`: an identifier for the purchase, this will appear in the processor if supported
+  #
   # Returns a Samurai::Transaction containing the processor's response.
   def purchase(payment_method_token, amount, options = {})
     execute(:purchase, options.merge(:payment_method_token => payment_method_token, :amount => amount))
   end
 
-  # Authorize a payment_method for a particular amount. 
+  # Authorize a payment_method for a particular amount.
   # Parameters:
-  # +payment_method_token+:: token identifying the payment method to authorize
-  # +amount+:: amount to authorize
-  # options:: an optional has of additional values to pass in accepted values are:
-  # *+descriptor+:: descriptor for the transaction
-  # *+custom+:: custom data, this data does not get passed to the processor, it is stored within api.samurai.feefighters.com only
-  # *+customer_reference+:: an identifier for the customer, this will appear in the processor if supported
-  # *+billing_reference::+ an identifier for the purchase, this will appear in the processor if supported
+  #
+  # * `payment_method_token`: token identifying the payment method to authorize
+  # * `amount`: amount to authorize
+  #
+  # * options: an optional has of additional values to pass in accepted values are:
+  #   * `descriptor`: descriptor for the transaction
+  #   * `custom`: custom data, this data does not get passed to the processor, it is stored within api.samurai.feefighters.com only
+  #   * `customer_reference`: an identifier for the customer, this will appear in the processor if supported
+  #   * `billing_reference`: an identifier for the purchase, this will appear in the processor if supported
+  #
   # Returns a Samurai::Transaction containing the processor's response.
   def authorize(payment_method_token, amount, options = {})
     execute(:authorize, options.merge(:payment_method_token => payment_method_token, :amount => amount))
   end
   
   private
-  
+
+  # Make the actual ActiveResource POST request, process the response
   def execute(action, options = {})
     transaction = Samurai::Transaction.transaction_payload(options)
     begin

data/lib/samurai/processor_response.rb

@@ -1,5 +1,10 @@
+# Samurai::ProcessorResponse
+# -----------------
+
+# Simple class for serializing Samurai <processor_response> entities
 class Samurai::ProcessorResponse < Samurai::Base
 
+  # Helper method for accessing the AVS result code from the response messages
   def avs_result_code
     avs_result_code_message = self.messages.find {|m| m.context=='processor.avs_result_code' || m.context=='gateway.avs_result_code' }
     avs_result_code_message && avs_result_code_message.key

data/lib/samurai/rails/helpers.rb

@@ -1,5 +1,10 @@
 require 'pathname'
 
+# Samurai::Rails::Helpers
+# -----------------
+
+# Helper module containing useful methods that can be called from Rails controllers
+# Useful for setting up objects properly for a Transparent Redirect, or displaying errors on payment forms
 module Samurai::Rails
   module Helpers
 

data/lib/samurai/rails/views.rb

@@ -1,5 +1,19 @@
 require 'pathname'
 
+# Samurai::Rails::Views
+# -----------------
+
+# Helper module containing methods designed to be called inside Rails views
+# These methods render Samurai partials that ship with the gem,
+# making it possible to create a payment form, and display transaction errors, in a single line of code
+# eg:
+#
+# ```ruby
+# <%= render Samurai::Rails::Views.errors %>
+# <%= render Samurai::Rails::Views.payment_form
+#       :redirect_url => purchase_article_orders_url(@article),
+#       :sandbox => true %>
+# ```
 module Samurai::Rails
   class Views
     class << self

data/lib/samurai/transaction.rb

@@ -1,14 +1,18 @@
+# Samurai::Transaction
+# -----------------
+
+# This class represents a Samurai Transaction
+# It can be used to query Transactions & capture/void/credit/reverse
 class Samurai::Transaction < Samurai::Base
-  
   include Samurai::CacheableByToken
   
-  # Alias for transaction_token
-  def id # :nodoc:
+  # Alias for `transaction_token`
+  def id
     transaction_token
   end
   alias_method :token, :id
   
-  # Captures an authorization. Optionally specify an +amount+ to do a partial capture of the initial
+  # Captures an authorization. Optionally specify an `amount` to do a partial capture of the initial
   # authorization. The default is to capture the full amount of the authorization.
   def capture(amount = nil, options = {})
     execute(:capture, {:amount => amount || self.amount}.reverse_merge(options))
@@ -21,7 +25,7 @@ class Samurai::Transaction < Samurai::Base
   end
   
   # Create a credit or refund against the original transaction.
-  # Optionally accepts an +amount+ to credit, the default is to credit the full 
+  # Optionally accepts an `amount` to credit, the default is to credit the full
   # value of the original amount
   def credit(amount = nil, options = {})
     execute(:credit, {:amount => amount || self.amount}.reverse_merge(options))
@@ -43,7 +47,8 @@ class Samurai::Transaction < Samurai::Base
   end
 
   private
-  
+
+  # Make the actual ActiveResource POST request, process the response
   def execute(action, options = {})
     begin
       resp = post(action, {}, self.class.transaction_payload(options))
@@ -59,6 +64,8 @@ class Samurai::Transaction < Samurai::Base
     end
   end
 
+  # Override base error processing with specific Transaction behavior
+  # Examine the `<processor_response><messages>` array, and add an error to the Errors object for each `<message>`
   def process_response_errors
     if self.processor_response && self.processor_response.messages
       self.processor_response.messages.each do |message|
@@ -86,6 +93,7 @@ class Samurai::Transaction < Samurai::Base
       to_xml(:skip_instruct => true, :root => 'transaction', :dasherize => false)
   end
 
+  # Setup the Transaction schema for ActiveResource, so that new objects contain empty attributes
   KNOWN_ATTRIBUTES = [
     :amount, :type, :payment_method_token, :currency_code,
     :descriptor, :custom, :customer_reference, :billing_reference, :processor_response

data/lib/samurai/version.rb

@@ -1,3 +1,3 @@
 module Samurai
-  VERSION = "0.2.18".freeze
+  VERSION = "0.2.19".freeze
 end

data/samurai.gemspec

@@ -28,4 +28,4 @@ Gem::Specification.new do |s|
   s.files        = `git ls-files`.split("\n")
   s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
   s.require_path = 'lib'
-end
+end

data/spec/lib/authorization_spec.rb

@@ -3,8 +3,8 @@ require 'spec_helper'
 describe "processing authorizations" do
   
   before :each do
-    payment_method_token = PAYMENT_METHOD_TOKENS[:success]
-    @authorization = Samurai::Processor.authorize(payment_method_token, @@seed)
+    payment_method_token = create_payment_method(default_payment_method_params)[:payment_method_token]
+    @authorization = Samurai::Processor.authorize(payment_method_token, 1.0, :billing_reference=>rand(1000))
   end
   
   it "should create a new authorization transaction" do
@@ -17,19 +17,19 @@ describe "processing authorizations" do
   end
 
   it "should successfully capture" do
-    capture = @authorization.capture(@@seed)
+    capture = @authorization.capture(1.0)
     capture.processor_response.success.should be_true
   end
   
   it "should capture an authorization without specifying an amount" do
     capture = @authorization.capture
-    capture.amount.intern.should be_equal "#{@@seed}".intern
+    capture.amount.intern.should be_equal "#{1.0}".intern
     capture.processor_response.success.should be_true
   end
 
   it "should partially capture an authorization" do
-    capture = @authorization.capture(@@seed - 1.0)
-    capture.amount.intern.should be_equal "#{@@seed - 1.0}".intern
+    capture = @authorization.capture(1.0 - BigDecimal('0.5'))
+    capture.amount.intern.should be_equal "#{1.0 - BigDecimal('0.5')}".intern
     capture.processor_response.success.should be_true
   end
 
@@ -40,15 +40,15 @@ describe "processing authorizations" do
 
   it "should credit an authorization for the full amount by default" do
     credit = @authorization.credit
-    credit.amount.intern.should be_equal "#{@@seed}".intern
+    credit.amount.intern.should be_equal "#{1.0}".intern
     pending "the response is not successful since the authorization hasn't settled" do
       credit.processor_response.success.should be_true
     end
   end
 
   it "should partially credit an authorization" do
-    credit = @authorization.credit(@@seed - 1.0)
-    credit.amount.intern.should be_equal "#{@@seed - 1.0}".intern
+    credit = @authorization.credit(1.0 - BigDecimal('0.5'))
+    credit.amount.intern.should be_equal "#{1.0 - BigDecimal('0.5')}".intern
     pending "the response is not successful since the authorization hasn't settled" do
       credit.processor_response.success.should be_true
     end

data/spec/lib/{generate_docs_spec.rb → generate_docs_spec.rb.bak}

@@ -1,7 +1,6 @@
 require 'spec_helper'
 
 describe "generate documentation" do
-  include TransparentRedirectHelper
   include ResponseLoggerHelper
 
   before(:all) do
@@ -61,7 +60,9 @@ describe "generate documentation" do
       @params.delete 'credit_card[card_number]'
       data = create_payment_method(@params)
       log_request_response! data[:request], data[:response]
-      data[:payment_method_token].should be_nil
+      data[:payment_method_token].should =~ /^[0-9a-z]{24}$/
+      Samurai::PaymentMethod.find data[:payment_method_token]
+      log_http!
     end
 
     it 'should create the payment method with invalid card_number format' do
@@ -99,12 +100,6 @@ describe "generate documentation" do
       log_http!
       purchase.processor_response.success.should be_true
     end    
-    it 'should create an invalid transaction' do
-      lambda do
-        Samurai::Processor.purchase(@data[:payment_method_token], '')
-      end.should raise_error(ActiveResource::ServerError)
-      log_http!
-    end
   end
 
   describe 'with a declined card' do
@@ -123,12 +118,6 @@ describe "generate documentation" do
       log_http!
       purchase.processor_response.success.should be_false
     end
-    it 'should create an invalid transaction' do
-      lambda do
-        Samurai::Processor.purchase(@data[:payment_method_token], '')
-      end.should raise_error(ActiveResource::ServerError)
-      log_http!
-    end
   end
 
   describe 'with an expired card' do
@@ -147,12 +136,6 @@ describe "generate documentation" do
       log_http!
       purchase.processor_response.success.should be_false
     end
-    it 'should create an invalid transaction' do
-      lambda do
-        Samurai::Processor.purchase(@data[:payment_method_token], '')
-      end.should raise_error(ActiveResource::ServerError)
-      log_http!
-    end
   end
 
   describe 'with  a card with incorrect cvv' do
@@ -171,12 +154,6 @@ describe "generate documentation" do
       log_http!
       purchase.processor_response.success.should be_false
     end
-    it 'should create an invalid transaction' do
-      lambda do
-        Samurai::Processor.purchase(@data[:payment_method_token], '')
-      end.should raise_error(ActiveResource::ServerError)
-      log_http!
-    end
   end
 
   describe 'with an nonexistant card' do
@@ -196,12 +173,6 @@ describe "generate documentation" do
       log_http!
       purchase.processor_response.success.should be_false
     end
-    it 'should create an invalid transaction' do
-      lambda do
-        Samurai::Processor.purchase(@data[:payment_method_token], '')
-      end.should raise_error(ActiveResource::ServerError)
-      log_http!
-    end
   end
 
 end