samurai 0.0.5 → 0.2.1

data/.gitignore

@@ -1,3 +1,5 @@
 pkg/*
 *.gem
 .bundle
+doc
+TESTING

data/lib/samurai.rb

@@ -1,36 +1,41 @@
+# Author::    Graeme Rouse
+# Copyright:: Copyright (c) 2011 Arizona Bay, LLC
+
 module Samurai
+  SITE = 'https://samurai.feefighters.com/v1/'
+  DEFAULT_OPTIONS = {:site => SITE}
 
-  mattr_accessor :site
-  @@site = case Rails.env
-    when 'development'
-      'http://localhost:3002'
-    when 'staging'
-      'http://staging.api.ubergateway.com'
-    else
-      'http://api.ubergateway.com'
-    end << '/v1/'
+  # Gets the provider site that the gem is configured to hit
+  def self.site # ::nodoc::
+    @@options[:site]
+  end
   
-  mattr_accessor :merchant_key
-  @@merchant_key = nil
+  def self.merchant_key # ::nodoc::
+    @@options[:merchant_key]
+  end
   
-  mattr_accessor :merchant_password
-  @@merchant_password = nil
+  def self.merchant_password # ::nodoc::
+    @@options[:merchant_password]
+  end
   
-  mattr_accessor :gateway_token
-  @@gateway_token = nil
+  def self.gateway_token # ::nodoc::
+    @@options[:gateway_token]
+  end
+  
+  def self.options
+    @@options
+  end
   
-  def self.setup_site(site, merchant_key, merchant_password, gateway_token = nil)
-    site += '/v1/' unless site =~ /\/v1\/$/
-    @@site = site
-    @@merchant_key = merchant_key
-    @@merchant_password = merchant_password
-    @@gateway_token = gateway_token if gateway_token
+  def self.options=(value)
+    @@options = (value || {}).reverse_merge(DEFAULT_OPTIONS)
     Samurai::Base.setup_site!
   end
   
 end
 
+require 'samurai/cacheable_by_token'
 require 'samurai/base'
 require 'samurai/gateway'
 require 'samurai/payment_method'
 require 'samurai/transaction'
+require 'samurai/message'

data/lib/samurai/base.rb

@@ -1,6 +1,11 @@
+begin
+  require 'active_resource'
+rescue LoadError
+  require 'activeresource' # for older versions of activeresource
+end
 class Samurai::Base < ActiveResource::Base
-  
-  def self.setup_site!
+
+  def self.setup_site! # ::nodoc::
     self.site = Samurai.site
     self.user = Samurai.merchant_key
     self.password = Samurai.merchant_password

data/lib/samurai/cacheable_by_token.rb

@@ -0,0 +1,38 @@
+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
+  #  * memecached
+  #  * redis cache
+  def self.included(klass)
+    klass.send :cattr_accessor, :cache
+    klass.send :cache=, {}
+    klass.extend(ClassExtensions)
+  end
+  
+  module ClassExtensions
+    # 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]
+        # cache hit
+        self.cache[token]
+      else
+        # cache miss
+        obj = super(*arguments)
+        self.cache[obj.id] = obj
+      end
+    end
+  end
+  
+  # Overrides the ActiveResource +save+ method to update the current
+  # model in the cache
+  def save
+    super
+    # update self in the cache
+    self.class.cache[self.id] = self
+  end
+  
+end

data/lib/samurai/gateway.rb

@@ -1,27 +1,56 @@
 class Samurai::Gateway < Samurai::Base
-
+  
+  # Returns the default gateway specified by Samurai.gateway_token if you passed it into Samurai.setup_site.
   def self.the_gateway
     Samurai::Gateway.new(:id => Samurai.gateway_token)
   end
   
-  def purchase(payment_method_token, amount, descriptor)
+  # Convienince method that calls the purchase method on the defalt gateway.
+  def self.purchase(*args)
+    the_gateway.purchase(*args)
+  end
+
+  # Convienince method that calls the authorize method on the defalt gateway.
+  def self.authorize(*args)
+    the_gateway.authorize(*args)
+  end
+  
+  # Convienience 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 gateway, it is stored within samurai.feefighters.com only
+  # *+customer_reference+:: an identifier for the customer, this will appear in the gateway if supported
+  # *+billing_reference::+ an indentifier for the purchase, this will appear in the gateway if supported
+  # Returns a Samurai::Transaction containing the gateway'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. 
+  # 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 gateway, it is stored within samurai.feefighters.com only
+  # *+customer_reference+:: an identifier for the customer, this will appear in the gateway if supported
+  # *+billing_reference::+ an indentifier for the purchase, this will appear in the gateway if supported
+  # Returns a Samurai::Transaction containing the gateway's response.
+  def authorize(payment_method_token, amount, options = {})
+    execute(:authorize, options.merge(:payment_method_token => payment_method_token, :amount => amount))
+  end
+  
+  private
+  
+  def execute(action, options = {})
+    transaction = Samurai::Transaction.transaction_payload(options)
     # send a purchase request
-    resp = post(:purchase, 
-      :transaction => {
-        :amount => amount, 
-        :type => 'purchase', 
-        :payment_method_token => payment_method_token, 
-        :currency_code => 'USD',
-        :descriptor => descriptor
-      }
-    )
+    resp = post(action, {}, transaction)
     # return the response, wrapped in a Samurai::Transaction
     Samurai::Transaction.new.load_attributes_from_response(resp)
   end
-
-  # TODO implement this functionality
-  # def authorize
-  #   post(:authorize)
-  # end
   
 end

data/lib/samurai/message.rb

@@ -0,0 +1,10 @@
+class Samurai::Message < Samurai::Base # :nodoc:
+  def to_xml(options = {})
+    builder = options[:builder] || Builder::XmlMarkup.new(options)
+    builder.tag!(:message) do
+      self.attributes.each do |key, value|
+        builder.tag!(key, value)
+      end
+    end
+  end
+end

data/lib/samurai/payment_method.rb

@@ -1,6 +1,8 @@
 class Samurai::PaymentMethod < Samurai::Base
   
-  def id
+  include Samurai::CacheableByToken
+
+  def id # :nodoc:
     self.token
   end
   
@@ -8,6 +10,8 @@ class Samurai::PaymentMethod < Samurai::Base
     self.payment_method_token
   end
   
+  # Retains the payment method on samurai.feefighters.com. Retain a payment method if 
+  # it will not be used immediately. 
   def retain
     self.post(:retain)
   end

data/lib/samurai/transaction.rb

@@ -1,23 +1,54 @@
 class Samurai::Transaction < Samurai::Base
-
-  def id
-    self.reference_id
-  end
   
-  def token
+  include Samurai::CacheableByToken
+  
+  # Alias for transaction_token
+  def id # :nodoc:
     transaction_token
   end
+  alias_method :token, :id
+  
+  # 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 authroization.
+  def capture(amount = nil, options = {})
+    execute(:capture, {:amount => amount || self.amount}.reverse_merge(options))
+  end
   
-  def capture
-    
+  # Void this transaction. If the transaction has not yet been captured and settled it can be voided to 
+  # prevent any funds from transfering. 
+  def void(options = {})
+    execute(:void, options)
   end
   
-  def void
-    
+  # Create a credit or refund against the original transaction.
+  # 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))
   end
   
-  def credit
-    
+  private
+  
+  def execute(action, options = {})
+    resp = post(action, {}, self.class.transaction_payload(options))
+    # return the response, wrapped in a Samurai::Transaction
+    Samurai::Transaction.new.load_attributes_from_response(resp)
+  end
+  
+  # Builds an xml payload that represents the transaction data to submit to samuari.feefighters.com
+  def self.transaction_payload(options = {})
+    {
+      :amount => options[:amount],
+      :type => options[:type],
+      :payment_method_token => options[:payment_method_token],
+      :currency_code => options[:currency_code] || (options[:payment_method_token] && 'USD'), # currency code is only required for payloads that include the PMT
+      :descriptor => options[:descriptor],
+      :custom => options[:custom],
+      :customer_reference => options[:customer_reference],
+      :billing_reference => options[:billing_reference]
+    }.
+      reject{ |k,v| v.nil? }.
+      to_xml(:skip_instruct => true, :root => 'transaction', :dasherize => false)
   end
-
+  
 end

data/lib/samurai/version.rb

@@ -1,3 +1,3 @@
 module Samurai
-  VERSION = "0.0.5".freeze
+  VERSION = "0.2.1".freeze
 end

data/samurai.gemspec

@@ -13,8 +13,12 @@ Gem::Specification.new do |s|
 
   s.required_rubygems_version = ">= 1.3.5"
   # s.rubyforge_project         = "samurai"
+  
+  s.add_dependency "activerecord", ">= 2.2.2"
 
   s.add_development_dependency "bundler", ">= 1.0.0"
+  s.add_development_dependency "rspec", ">= 2.6.0"
+  s.add_development_dependency 'fakeweb'
 
   s.files        = `git ls-files`.split("\n")
   s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact

data/test/spec/authorization_spec.rb

@@ -0,0 +1,63 @@
+require 'test/spec_helper'
+
+describe "processing authorizations" do
+  
+  before :each do
+    register_transaction_response(:type => 'authorize')
+    @authorization = Samurai::Gateway.authorize(PAYMENT_METHOD_TOKEN, @@seed)
+  end
+  
+  it "should create a new authorization transaction" do
+    @authorization.gateway_response.success.should be_true
+  end
+
+  it "should find the authorization" do
+    register_transaction_response(:method => :get, :path => "transactions/#{@authorization.reference_id}", :type => 'authorize')
+    transaction = Samurai::Transaction.find(@authorization.reference_id)
+    transaction.reference_id.intern.should be_equal(@authorization.reference_id.intern)
+  end
+
+  it "should successfully capture" do
+    register_transaction_response(:method => :post, :path => "transactions/#{@authorization.id}/capture", :type => 'capture')
+    capture = @authorization.capture(@@seed)
+    capture.gateway_response.success.should be_true
+  end
+  
+  it "should capture an authorization without specifying an amount" do
+    register_transaction_response(:method => :post, :path => "transactions/#{@authorization.id}/capture", :type => 'capture', :amount => @@seed)
+    capture = @authorization.capture
+    capture.amount.intern.should be_equal "#{@@seed}".intern
+    capture.gateway_response.success.should be_true
+  end
+
+  it "should partially capture an authorization" do
+    register_transaction_response(:method => :post, :path => "transactions/#{@authorization.id}/capture", :type => 'capture', :amount => @@seed - 1.0)
+    capture = @authorization.capture(@@seed - 1.0)
+    capture.amount.intern.should be_equal "#{@@seed - 1.0}".intern
+    capture.gateway_response.success.should be_true
+  end
+
+  it "should void an authorization" do
+    register_transaction_response(:method => :post, :path => "transactions/#{@authorization.id}/void", :type => 'void', :amount => @@seed)
+    void = @authorization.void
+    void.gateway_response.success.should be_true
+  end
+
+  it "should credit an authorization for the full amount by default" do
+    register_transaction_response(:method => :post, :path => "transactions/#{@authorization.id}/credit", :type => 'credit', :amount => @@seed, :success => 'false')
+    credit = @authorization.credit
+    credit.amount.intern.should be_equal "#{@@seed}".intern
+    pending "the response is not successful since the authorization hasn't settled" do
+      credit.gateway_response.success.should be_true
+    end
+  end
+
+  it "should partially credit an authorization" do
+    register_transaction_response(:method => :post, :path => "transactions/#{@authorization.id}/credit", :type => 'credit', :amount => @@seed - 1.0, :success => 'false')
+    credit = @authorization.credit(@@seed - 1.0)
+    credit.amount.intern.should be_equal "#{@@seed - 1.0}".intern
+    pending "the response is not successful since the authorization hasn't settled" do
+      credit.gateway_response.success.should be_true
+    end
+  end
+end

data/test/spec/gateway_spec.rb

@@ -0,0 +1,37 @@
+require 'test/spec_helper'
+
+describe "Gateway actions" do
+  
+  it "should return an empty gateway" do
+    gateway = Samurai::Gateway.the_gateway
+    gateway.should_not be_nil
+  end
+  
+  it "should create a new purchase" do
+    register_transaction_response(:type => 'purchase')
+    
+    purchase = Samurai::Gateway.purchase(PAYMENT_METHOD_TOKEN, @@seed)
+    purchase.gateway_response.success.should be_true
+    # FakeWeb.last_request
+  end
+
+  it "should create a new purchase with tracking data" do
+    register_transaction_response(:type => 'purchase')
+    
+    purchase = Samurai::Gateway.purchase(PAYMENT_METHOD_TOKEN, @@seed, {
+      :descriptor => "A test purchase", 
+      :custom => "some optional custom data",
+      :billing_reference => "ABC123",
+      :customer_reference => "Customer (123)"
+    })
+    purchase.gateway_response.success.should be_true
+    # FakeWeb.last_request
+  end
+    
+  it "should create a non-new authorization" do
+    register_transaction_response(:type => 'authorize')
+    authorization = Samurai::Gateway.authorize(PAYMENT_METHOD_TOKEN, @@seed)
+    authorization.gateway_response.success.should be_true
+  end
+  
+end

data/test/spec/purchase_spec.rb

@@ -0,0 +1,33 @@
+require 'test/spec_helper'
+
+describe "processing purchases" do
+
+  before :each do
+    register_transaction_response(:type => 'purchase')
+    @purchase = Samurai::Gateway.purchase(PAYMENT_METHOD_TOKEN, @@seed)
+  end
+  
+  it "should process successfully" do
+    @purchase.gateway_response.success.should be_true
+  end
+
+  it "should be able to void a recent purchase" do
+    register_transaction_response(:method => :post, :path => "transactions/#{@purchase.id}/void", :type => 'void', :success => 'false')
+    void = @purchase.void
+    void.gateway_response.success.should be_true
+  end
+
+  it "should not be able to credit a recent purchase" do
+    register_transaction_response(:method => :post, :path => "transactions/#{@purchase.id}/credit", :type => 'void', :success => 'false')
+    credit = @purchase.credit
+    credit.gateway_response.success.should be_false
+  end
+
+  it "should be able to credit a settled purchase" do
+    pending "currently we cannot force settle a purchase, so can't test this properly" do
+      register_transaction_response(:method => :post, :path => "transactions/#{@purchase.id}/credit", :type => 'void', :success => 'false')
+      credit = @purchase.credit
+      credit.gateway_response.success.should be_true
+    end
+  end
+end

data/test/spec_helper.rb

@@ -0,0 +1,91 @@
+require 'ruby-debug'
+Debugger.start
+Debugger.settings[:autoeval] = true
+Debugger.settings[:autolist] = 5
+Debugger.settings[:reload_source_on_change] = true
+
+SITE = ENV['site'] || 'http://localhost:3002/v1/'
+USE_MOCK = !ENV['site']
+PAYMENT_METHOD_TOKEN = ENV['payment_method_token'] || 'asdf'
+
+RSpec.configure do |c|
+  c.before :all do
+    @@seed = rand(1000).to_f / 100.0
+  end
+  c.before :each do
+    @@seed += 1.0
+  end
+end
+
+require 'fakeweb'
+FakeWeb.allow_net_connect = !USE_MOCK
+
+require 'samurai'
+Samurai.options = {
+  :site => SITE, 
+  :merchant_key => ENV['merchant_key'] || 'e62c5a006cdd9908234193bc',
+  :merchant_password => ENV['merchant_password'] || '18e87d97b3a44b56fe07497e4812f14555db69df9e6ca16f', 
+  :gateway_token => ENV['gateway_token'] || 'af762c3499f77c5f181650a7'
+}
+
+def register_transaction_response(options)
+  return unless USE_MOCK
+  
+  options.symbolize_keys!
+
+  method = options[:method] && options[:method].to_sym || :post
+  type = options[:type]
+  path = options[:path] || "gateways/af762c3499f77c5f181650a7/#{type}"
+  payment_method_token = options[:payment_method_token] || PAYMENT_METHOD_TOKEN
+  amount = options[:amount] || 15.00
+  success = options[:success].blank? ? true : options[:success]
+  
+  FakeWeb.register_uri(method, 
+    "http://e62c5a006cdd9908234193bc:18e87d97b3a44b56fe07497e4812f14555db69df9e6ca16f@localhost:3002/v1/#{path}.xml", 
+    :body => <<-EOF
+    <transaction>
+    <reference_id>3dcFjTC7LDjIjTY3nkKjBVZ8qkZ</reference_id>
+    <transaction_token>53VFyQKYBmN9vKfA9mHCTs79L9a</transaction_token>
+    <created_at type="datetime">2011-04-22T17:57:56Z</created_at>
+    <descriptor>Custom descriptor here if your gateway supports it.</descriptor>
+    <custom>Any value you like.</custom>
+    <transaction_type>#{type}</transaction_type>
+    <amount>#{amount}</amount>
+    <currency_code>USD</currency_code>
+    <gateway_token>af762c3499f77c5f181650a7</gateway_token>
+    <gateway_response>
+      <success type="boolean">#{success}</success>
+      <messages type="array">
+        <message class="error" context="gateway.avs" key="country_not_supported" />
+        <message class="error" context="input.cvv" key="too_short" />
+      </messages>
+    </gateway_response>
+    <payment_method>
+      <payment_method_token>#{payment_method_token}</payment_method_token>
+        <created_at type="datetime">2011-02-12T20:20:46Z</created_at>
+        <updated_at type="datetime">2011-04-22T17:57:30Z</updated_at>
+        <custom>Any value you want us to save with this payment method.</custom>
+        <is_retained type="boolean">true</is_retained>
+        <is_redacted type="boolean">false</is_redacted>
+        <is_sensitive_data_valid type="boolean">true</is_sensitive_data_valid>
+        <messages type="array">
+          <message class="error" context="input.cvv" key="too_long" />
+          <message class="error" context="input.card_number" key="failed_checksum" />
+        </messages>
+        <last_four_digits>1111</last_four_digits>
+        <card_type>visa</card_type>
+        <first_name>Bob</first_name>
+        <last_name>Smith</last_name>
+        <expiry_month type="integer">1</expiry_month>
+        <expiry_year type="integer">2020</expiry_year>
+        <address_1 nil="true"></address_1>
+        <address_2 nil="true"></address_2>
+        <city nil="true"></city>
+        <state nil="true"></state>
+        <zip nil="true"></zip>
+        <country nil="true"></country>
+    </payment_method>
+  </transaction>
+  EOF
+  )
+end

metadata

@@ -5,9 +5,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 0
-  - 5
-  version: 0.0.5
+  - 2
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Graeme Rouse
@@ -16,13 +16,29 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-15 00:00:00 -07:00
+date: 2011-07-20 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: bundler
+  name: activerecord
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 2
+        - 2
+        version: 2.2.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -34,7 +50,37 @@ dependencies:
         - 0
         version: 1.0.0
   type: :development
-  version_requirements: *id001
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 2
+        - 6
+        - 0
+        version: 2.6.0
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
 description: If you are an online merchant and using samurai.feefighers.com, this gem will make your life easy. Integrate with the samuari.feefighters.com portal and process transaction.
 email: 
 - graeme@ubergateway.com
@@ -52,11 +98,17 @@ files:
 - Rakefile
 - lib/samurai.rb
 - lib/samurai/base.rb
+- lib/samurai/cacheable_by_token.rb
 - lib/samurai/gateway.rb
+- lib/samurai/message.rb
 - lib/samurai/payment_method.rb
 - lib/samurai/transaction.rb
 - lib/samurai/version.rb
 - samurai.gemspec
+- test/spec/authorization_spec.rb
+- test/spec/gateway_spec.rb
+- test/spec/purchase_spec.rb
+- test/spec_helper.rb
 has_rdoc: true
 homepage: http://rubygems.org/gems/samurai
 licenses: []