spreedly-core-ruby 0.1.0

data/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2011 403 Labs, LLC <http://www.403labs.com>
+
+SpreedlyCore library is free software: you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+SpreedlyCore library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
+General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+

data/README.md

@@ -0,0 +1,213 @@
+SpreedlyCore
+======
+
+SpreedlyCore is a Ruby library for accessing the [Spreedly Core API](https://spreedlycore.com/).
+
+The beauty behind Spreedly Core is that you lower your
+[PCI Compliance](https://www.pcisecuritystandards.org/) risk 
+by storing credit card information on their service while still having access
+to make payments and credits. This is possible by having your customers POST their
+credit card info to the spreedly core service while embedding a transparent
+redirect URL back to your application. See "Submit payment form" on
+[the quick start guide](https://spreedlycore.com/manual/quickstart)
+how the magic happens.
+
+
+Quickstart
+----------
+
+RubyGems:
+
+    gem install spreedly_core
+    irb
+    require 'rubygems'
+    require 'spreedly_core'
+    SpreedlyCore.configure("Your API Login", "Your API Secret", "Test Gateway Token")
+See the [quickstart guide](https://spreedlycore.com/manual/quickstart) for
+information regarding tokens.
+
+We'll now look up the payment method stored on SpreedlyCore using token param
+from the transparent redirect URL
+ 
+    payment_token = SpreedlyCore::PaymentMethod.find(payment_token)
+    transaction = payment_token.purchase(100)
+
+Test Integration
+----------
+    
+Since your web form handles the creation of payment methods on their service,
+integration testing can be a bit of a headache. No worries though:
+
+    require 'spreedly_core'
+    require 'spreedly_core/test_extensions'
+    SpreedlyCore.configure("Your API Login", "Your API Secret", "Test Gateway Token")
+    master_card_data = SpreedlyCore::TestHelper.cc_data(:master) # Lookup test credit card data
+    token = SpreedlyCore::PaymentMethod.create_test_token(master_card_data)
+
+You now have access to a payment method token, which can be used just like your
+application would use it. Note, you should use a test gateway since you are
+actually hitting the Spreedly Core service. Let's use the test credit card
+payment method to make a purchase:
+    
+    payment_method = SpreedlyCore::PaymentMethod.find(token)
+    purchase_transaction = payment_method.purchase(100)
+    purchase_transaction.succeeded? # true
+
+Let's now use a credit card that is configured to fail upon purchase:
+
+    master_card_data = SpreedlyCore::TestHelper.cc_data(:master, :card_type => :failed)
+    token = SpreedlyCore::PaymentMethod.create_test_token(master_card_data)
+    payment_method = SpreedlyCore::PaymentMethod.find(token)
+    purchase_transaction = payment_method.purchase(100)
+    purchase_transaction.succeeded? # false
+
+Other test cards available include :visa, :american_express, and :discover
+    
+Usage
+----------
+
+Using spreedly_core in irb:
+
+    require 'spreedly_core'
+    require 'spreedly_core/test_extensions' # allow creating payment methods from the command line
+    SpreedlyCore.configure("Your API Login", "Your API Secret", "Test Gateway Token")
+    # or if loading from YAML for example, configure takes a hash as well
+    SpreedlyCore.configure(:login => "Your API Login", :secret => "Your API Secret",
+                           :token => "Test Gateway Token")       
+    master_card_data = SpreedlyCore::TestHelper.cc_data(:master)
+    token = SpreedlyCore::PaymentMethod.create_test_token(master_card_data)
+
+
+Look up a payment method:
+
+    payment_method = SpreedlyCore::PaymentMethod.find(token)
+
+Retain a payment method for later use:
+
+    retain_transaction = payment_method.retain
+    retain_transaction.succeeded? # true
+
+Redact a previously retained payment method:
+
+    redact_transaction = payment_method.redact
+    redact_transaction.succeeded?
+
+Make a purchase against a payment method:
+
+    purchase_transaction = payment_method.purchase(100) 
+    purchase_transaction.succeeded? # true
+
+Make an authorize request against a payment method, then capture the payment
+
+    authorize = payment_method.authorize(100)
+    authorize.succeeded? # true
+    capture = authorize.capture(50) # Capture only half of the authorized amount
+    capture.succeeded? # true
+
+    authorize = payment_method.authorize(100)
+    authorize.succeeded? # true
+    authorized.capture # Capture the full amount
+    capture.succeeded? # true
+    
+Void a previous purchase:
+
+    purchase_transaction.void # void the purchase
+
+Credit a previous purchase:
+
+    purchase_transaction = payment_method.purchase(100) # make a purchase
+    purchase_transaction.credit
+    purchase_transaction.succeeded? # true 
+
+Credit part of a previous purchase:
+
+    purchase_transaction = payment_method.purchase(100) # make a purchase
+    purchase_transaction.credit(50) # provide a partial credit
+    purchase_transaction.succeeded? # true 
+
+Handling Exceptions:
+
+There are 2 types of exceptions which can be raised by the library:
+
+  1.  SpreedlyCore::TimeOutError is raised if communication with SpreedlyCore
+      takes longer than 10 seconds     
+  2.  SpreedlyCore::InvalidResponse is raised when the response code is
+      unexpected (I.E. we expect a HTTP response code of 200 bunt instead got a
+      500) or if the response does not contain an expected attribute. For
+      example, the response from retaining a payment method should contain an XML
+      attribute of "transaction". If this is not found (for example a HTTP
+      response 404 or 500 is returned), then an InvalidResponse is raised.
+
+      
+Both TimeOutError and InvalidResponse subclass SpreedlyCore::Error.
+
+Look up a payment method that does not exist:
+
+    begin
+      payment_method = SpreedlyCore::PaymentMethod.find("NOT-FOUND")
+    rescue SpreedlyCore::InvalidResponse => e
+      puts e.inspect
+    end  
+
+   
+Additional Field Validation
+----------
+
+
+The Spreedyly Core API provides validation of the credit card number, CVE, and
+first and last name. In most cases this is enough, however sometimes you want to
+enforce the billing information as well. This can be accomplished via:
+
+    require 'spreedly_core'
+    require 'spreedly_core/test_extensions'
+    SpreedlyCore.configure("Your API Login", "Your API Secret", "Test Gateway Token")
+    SpreedlyCore::PaymentMethod.additional_required_cc_fields :address1, :city, :state, :zip
+    master_card_data = SpreedlyCore::TestHelper.cc_data(:master)
+    token = SpreedlyCore::PaymentMethod.create_test_token(master_card_data)
+    payment_method = SpreedlyCore::PaymentMethod.find(token)
+    payment_method.valid? # returns false
+    payment_method.errors # ["Address1 can't be blank", "City can't be blank", "State can't be blank", "Zip can't be blank"]
+    master_card_data = SpreedlyCore::TestHelper.cc_data(:master, :credit_card => {:address1 => "742 Evergreen Terrace", :city => "Springfield", :state => "IL", 62701})
+    payment_method = SpreedlyCore::PaymentMethod.find(token)
+    payment_method.valid? # returns true
+    payment_method.errors # []
+
+   
+Configuring SpreedlyCore with Rails
+----------
+
+Inside your Rails project create config/spreedly_core.yml formatted like config/database.yml. For example:
+
+    development:
+      login: <Login Key>
+      secret: <Secret Key>
+      gateway_token: 'JncEWj22g59t3CRB1VnPXmUUgKc' # this is the test gateway, replace with your real gateway in production
+    test:
+      login: <Login Key>
+      secret: <Secret Key>
+      gateway_token: 'JncEWj22g59t3CRB1VnPXmUUgKc' # this is the test gateway, replace with your real gateway in production
+    production:
+      login: <Login Key>
+      secret: <Secret Key>
+      gateway_token: 'JncEWj22g59t3CRB1VnPXmUUgKc' # this is the test gateway, replace with your real gateway in production
+
+Then create config/initializers/spreedly_core.rb with the following:
+
+    config = YAML.load(File.read(RAILS_ROOT + '/config/spreedly_core.yml'))[RAILS_ENV]
+    SpreedlyCore.configure(config)
+
+Optionally require additional credit card fields:
+
+    SpreedlyCore::PaymentMethod.additional_required_cc_fields :address1, :city, :state, :zip  
+
+Contributing
+------------
+
+Once you've made your commits:
+
+1. [Fork](http://help.github.com/forking/) SpreedlyCore
+2. Create a topic branch - `git checkout -b my_branch`
+3. Push to your branch - `git push origin my_branch`
+4. Create a [Pull Request](http://help.github.com/pull-requests/) from your branch
+5. Profit! 
+

data/Rakefile

@@ -0,0 +1,34 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "someproject #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/lib/spreedly_core.rb

@@ -0,0 +1,72 @@
+require 'set'
+
+require 'httparty'
+
+require 'spreedly_core/base'
+require 'spreedly_core/payment_method'
+require 'spreedly_core/gateway'
+require 'spreedly_core/test_gateway'
+require 'spreedly_core/transactions'
+
+module SpreedlyCore
+  # Hash of user friendly credit card name to SpreedlyCore API name
+  CARD_TYPES = {
+    "Visa" => "visa",
+    "MasterCard" => "master",
+    "American Express" => "american_express",
+    "Discover" => "discover"
+  }
+
+  class Error < RuntimeError; end
+  # Custom exception which occurs when a request to SpreedlyCore times out
+  # See SpreedlyCore::Base.default_timeout 
+  class TimeOutError < Error; end
+  class InvalidResponse < Error
+    def initialize(response, message)
+      super("#{message}\nResponse:\n#{response.inspect}")
+    end
+  end
+
+  # Configure SpreedlyCore with a particular account.
+  # Strongly prefers environment variables for credentials
+  # and will issue a stern warning should they not be present.
+  # Reluctantly accepts :login and :secret as options
+  def self.configure(options = {})
+    login = ENV['SPREEDLYCORE_API_LOGIN']
+    secret = ENV['SPREEDLYCORE_API_SECRET']
+
+    if options[:api_login]
+      Kernel.warn("ENV and arg both present for api_login. Defaulting to arg value") if login
+      login = options[:api_login]
+    end
+
+    if options[:api_secret]
+      Kernel.warn("ENV and arg both present for api_secret. Defaulting to arg value") if login
+      secret = options[:api_secret]
+    end
+
+    if options[:api_login] || options[:api_secret]
+      Kernel.warn("It is STRONGLY preferred that you house your Spreedly Core credentials only in environment variables.")
+      Kernel.warn("This gem prefers only environment variables named SPREEDLYCORE_API_LOGIN and SPREEDLYCORE_API_SECRET.")
+    end
+
+    if login.nil? || secret.nil?
+      raise ArgumentError.new("You must provide a login and a secret. Gem will look for ENV['SPREEDLYCORE_API_LOGIN'] and ENV['SPREEDLYCORE_API_SECRET'], but you may also pass in a hash with :api_login and :api_secret keys.")
+    end
+    Base.configure(login, secret, options)
+  end
+
+  def self.gateway_token=(gateway_token)
+    Base.gateway_token = gateway_token
+  end
+
+  # returns the configured SpreedlyCore login
+  def self.login; Base.login; end
+
+  # A container for a response from a payment gateway
+  class Response < Base
+    attr_reader(:success, :message, :avs_code, :avs_message, :cvv_code,
+                :cvv_message, :error_code, :error_detail, :created_at,
+                :updated_at) 
+  end
+end

data/lib/spreedly_core/base.rb

@@ -0,0 +1,95 @@
+module SpreedlyCore
+  # Base class for all SpreedlyCore API requests
+  class Base
+    include HTTParty
+    
+    # Net::HTTP::Options is configured to not have a body.
+    # Lets give it the body it's always dreamed of
+    Net::HTTP::Options::RESPONSE_HAS_BODY = true
+    
+    format :xml
+
+    # timeout requests after 10 seconds
+    default_timeout 10
+
+    #base_uri "https://spreedlycore.com/#{API_VERSION}"
+    base_uri "http://core.spreedly.dev:11001/#{API_VERSION}"
+
+    def self.configure(login, secret, options = {})
+      @@login = login
+      self.basic_auth(@@login, secret)
+      @@gateway_token = options.delete(:gateway_token)
+    end
+
+    def self.login; @@login; end
+    def self.gateway_token; @@gateway_token; end
+    def self.gateway_token=(gateway_token); @@gateway_token = gateway_token; end
+
+    # make a post request to path
+    # If the request succeeds, provide the respones to the &block
+    def self.verify_post(path, options={}, &block)
+      verify_request(:post, path, options, 200, 201, 422, &block)
+    end
+
+    # make a put request to path
+    # If the request succeeds, provide the respones to the &block
+    def self.verify_put(path, options={}, &block)
+      verify_request(:put, path, options,  &block)
+    end
+
+    # make a get request to path
+    # If the request succeeds, provide the respones to the &block
+    def self.verify_get(path, options={}, &block)
+      verify_request(:get, path, options, 200, &block)
+    end
+
+    # make an options request to path
+    # If the request succeeds, provide the respones to the &block
+    def self.verify_options(path, options={}, &block)
+      verify_request(:options, path, options, 200, &block)
+    end
+
+    # make a request to path using the HTTP method provided as request_type
+    # *allowed_codes are passed in, verify the response code (200, 404, etc)
+    # is one of the allowed codes.
+    # If *allowed_codes is empty, don't check the response code, but set an instance
+    # variable on the object created in the block containing the response code.
+    def self.verify_request(request_type, path, options, *allowed_codes, &block)
+      begin 
+        response = self.send(request_type, path, options)
+      rescue Timeout::Error, Errno::ETIMEDOUT => e
+        raise TimeOutError.new("Request to #{path} timed out. Is Spreedly Core down?")
+      end
+        
+      if allowed_codes.any? && !allowed_codes.include?(response.code)
+        raise InvalidResponse.new(response, "Error retrieving #{path}. Got status of #{response.code}. Expected status to be in #{allowed_codes.join(",")}")
+      end
+
+      if options.has_key?(:has_key) &&
+          (response.parsed_response.nil? || !response.parsed_response.has_key?(options[:has_key]))
+        raise InvalidResponse.new(response, "Expected parsed response to contain key '#{options[:has_key]}'")
+      end
+
+      block.call(response).tap do |obj|
+        obj.instance_variable_set("@http_code", response.code)
+      end
+    end
+
+    # Given a hash of attrs, assign instance variables using the hash key as the
+    # attribute name and hash value as the attribute value
+    #
+    def initialize(attrs={})
+      attrs.each do |k, v|
+        instance_variable_set("@#{k}", v)
+      end
+      # errors may be nil, empty, a string, or an array of strings. 
+      @errors = if @errors.nil? || @errors["error"].blank?
+                  []
+                elsif @errors["error"].is_a?(String)
+                  [@errors["error"]]
+                else
+                  @errors["error"]
+                end
+    end
+  end
+end

data/lib/spreedly_core/gateway.rb

@@ -0,0 +1,23 @@
+module SpreedlyCore
+  class Gateway < Base
+    attr_reader(:name, :token, :gateway_type, :auth_modes, :supports_capture,
+                :supports_authorize, :supports_purchase, :supports_void,
+                :supports_credit, :redacted)
+
+    # returns an array of Gateway which are supported
+    def self.supported_gateways
+      verify_options("/gateways.xml") do |response|
+        response.parsed_response["gateways"]["gateway"].map{|h| new(h) }
+      end
+    end
+
+    def initialize(attrs={})
+      attrs.merge!(attrs.delete("characteristics") || {})
+      super(attrs)
+    end
+
+    def use!
+      self.class.gateway_token = self.token
+    end
+  end
+end