fat_zebra 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.yardoc
+doc/

data/FatZebra.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "fat_zebra/version"
+
+Gem::Specification.new do |s|
+  s.name        = "fat_zebra"
+  s.version     = FatZebra::VERSION
+  s.authors     = ["Matthew Savage"]
+  s.email       = ["matt@amasses.net"]
+  s.homepage    = ""
+  s.summary     = %q{Fat Zebra payments gem - integrate your ruby app with Fat Zebra}
+  s.description = %q{Provides integration with the Fat Zebra internet payment gateway (www.fatzebra.com.au), including purchase, refund, auth, capture and recurring billing functionality.}
+
+  s.rubyforge_project = "fat_zebra"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "yard-tomdoc"
+  
+
+  s.add_runtime_dependency "rest-client"
+  s.add_runtime_dependency "json"
+end

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in FatZebra.gemspec
+gemspec

data/README.markdown

@@ -0,0 +1,19 @@
+Ruby API Library for Fat Zebra
+==============================
+
+Further (better) readme content coming soon - I promise!
+
+General Usage:
+
+ 1. Add the gem to your project (i.e. Gemfile or otherwise)
+ 2. Create a new FatZebra::Gateway object, and pass it your username, token, and true or false for using test mode.
+ 4. Call the purchase() method on the gateway object.
+ 5. Examine the result.
+
+More details to follow (structure of request/response objects etc).
+
+Documentation for the Fat Zebra API can be found at http://docs.fatzebra.com.au
+
+As always, patches, pull requests, comments, issues etc welcome.
+
+For support please visit https://www.fatzebra.com.au/help or email support@fatzebra.com.au

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec
+
+begin
+	require 'yard'
+	desc "Run the YARDdoc task"
+	task :yard do
+		exec "yardoc --plugin yard-tomdoc"
+	end
+rescue LoadError
+	puts "Please install the Yard gem to create docs"
+end

data/lib/fat_zebra/constants.rb

@@ -0,0 +1 @@
+GATEWAY_SERVER = "gateway.fatzebra.com.au"

data/lib/fat_zebra/errors.rb

@@ -0,0 +1,4 @@
+module FatZebra
+	class InvalidArgumentError < StandardError; end
+	class RequestError < StandardError; end
+end

data/lib/fat_zebra/gateway.rb

@@ -0,0 +1,215 @@
+module FatZebra
+	class Gateway
+		attr_accessor :username, :token, :gateway_server, :options
+		
+		DEFAULT_OPTIONS = {:secure => true}
+
+		# Public: initializes a new gateway object
+		#
+		# username - merchants username
+		# token - merchants token for authentication
+		# gateway_service - the server for the gateway, defaults to 'gateway.fatzebra.com.au'
+		#
+		# Returns a new FatZebra::Gateway instance
+		def initialize(username, token, gateway_server = GATEWAY_SERVER, options = {})
+			self.username = username
+			self.token = token
+			self.gateway_server = gateway_server
+			self.options = DEFAULT_OPTIONS.merge(options)
+
+			require_field :username, :token, :gateway_server
+		end
+
+		# Public: Performs a purchase transaction against the gateway
+		#
+		# amount - the amount as an integer e.g. (1.00 * 100).to_i
+		# card_holder - the card holders name
+		# card_number - the customers credit card number
+		# card_expiry - the customers card expiry date (as Date or string [mm/yyyy])
+		# cvv - the credit card verification value (cvv, cav, csc etc)
+		# reference - a reference for the purchase
+		# customer_ip - the customers IP address (for fraud prevention)
+		#
+		# Returns a new FatZebra::Models::Purchase object
+		def purchase(amount, card_holder, card_number, card_expiry, cvv, reference, customer_ip)
+			params = {
+				:amount => amount,
+				:card_holder => card_holder,
+				:card_number => card_number,
+				:card_expiry => extract_date(card_expiry),
+				:cvv => cvv,
+				:reference => reference,
+				:customer_ip => customer_ip
+			}
+
+			response = make_request(:post, "purchases", params)
+			FatZebra::Models::Response.new(response)
+		end
+
+		def purchases(id = nil)
+			if id.nil?
+				response = make_request(:get, "purchases")
+				# handle list response
+			else
+				response = make_request(:get, "purchases/#{id}.json")
+				puts response.inspect
+			end
+		end
+
+		# Public: Performs an authorization transaction against the gateway
+		# Note: Successful transactions must then be captured for funds to settle.
+		#
+		# amount - the amount as an integer e.g. (1.00 * 100).to_i
+		# card_number - the customers credit card number
+		# card_expiry - the customers card expiry date
+		# cvv - the credit card verification value (cvv, cav, csc etc)
+		# reference - a reference for the purchase
+		# customer_ip - the customers IP address (for fraud prevention)
+		#
+		# Returns a new FatZebra::Models::Purchase object
+		def authorize(amount, card_number, card_expiry, cvv, reference, customer_ip)
+			raise "Sorry we haven't compelted this functionality yet."
+		end
+
+		# Public: Captures a pre-authorized transaction
+		#
+		# transaction_id - the authorization ID
+		# amount - the amount to capture, as an integer
+		#
+		# Returns a new FatZebra::Models::Purchase object
+		def capture(transaction_id, amount)
+			raise "Sorry we haven't compelted this functionality yet."
+		end
+
+		# Public: Refunds a transaction
+		#
+		# transaction_id - the ID of the original transaction to be refunded
+		# amount - the amount to be refunded, as an integer
+		# reference - the reference for the refund
+		#
+		# Returns a new FatZebra::Models::Refund object
+		def refund(transaction_id, amount, reference)
+			raise "Sorry we haven't compelted this functionality yet."
+		end
+
+		# Public: Pings the Fat Zebra service
+		# 
+		# nonce - the data to be echoed back
+		#
+		# Returns true if reply is valid, false if times out or otherwise
+		def ping(nonce = SecureRandom.hex)	
+			begin
+				response = RestClient.get(build_url("ping") + "?echo=#{nonce}")
+				response = JSON.parse(response)
+
+				response["echo"] == nonce
+			rescue => e
+				return false
+			end
+		end
+
+
+		private
+		# Private: Extracts the date value from a Date/DateTime value
+		#
+		# value - the string or date value to extract the value from
+		#
+		# Returns date string as MM/YYYY
+		def extract_date(value)
+			if value.is_a?(String)
+				return value
+			elsif value.respond_to?(:strftime)
+				return value.strftime("%m/%Y")
+			end
+		end
+
+		# Private: Verifies a require field is present and has a value
+		#
+		# fields - array of fields required to be present
+		#
+		# Returns nil
+		# Raises InvalidArgumentError if field is missing
+		def require_field(*fields)
+			fields.each do |field|
+				val = self.send(field)
+				raise InvalidArgumentError, "Parameter #{field} is required", caller if (val.nil? || val.to_s.length == 0)
+			end
+		end
+
+		# Public: Builds the URL for the request
+		# If data is provided it will append as name/value pairs for a get request
+		#
+		# resource - the resource to append to the URL (e.g. purchases for https://something.com/purchases)
+		# data (optional) - a hash of the data name value pairs - if nil it will be ignored
+		#
+		# Returns the URL as a string
+		def build_url(resource, data = nil)
+			proto = case options[:secure]
+			when true
+				"https://"
+			when false
+				"http://"
+			end
+			url = "#{proto}#{self.gateway_server}/#{resource}"
+			unless data.nil?
+				url = url + "?"
+				data.each do |key, value|
+					url += "#{key}=#{value}" # TODO: URL Encode this
+				end
+			end
+
+			url
+		end
+
+		# Public: Builds a new RestClient resource object
+		#
+		# uri - the full URI for the request
+		# method - the method for the request - either :post or :get
+		# data - the data for the request - only required for :get methods
+		#
+		# Returns a new RestClient resource
+		def get_resource(uri, method = :post, data = nil)
+			url = build_url(uri, (method == :get ? data : nil))
+			ssl_options = options[:secure] ? {
+				:ssl_ca_file =>  File.expand_path(File.dirname(__FILE__) + "/../../vendor/cacert.pem"),
+  				:verify_ssl => OpenSSL::SSL::VERIFY_PEER
+  			} : {}
+
+  			opts = {:user => self.username, :password => self.token}
+			RestClient::Resource.new(build_url(uri), opts.merge(ssl_options))
+		end
+
+		# Public: Performs the HTTP(s) request and returns a response object, handing errors etc
+		#
+		# method - the request method (:post or :get)
+		# resource - the resource for the request
+		# data - a hash of the data for the request
+		#
+		# Returns hash of response data
+		def make_request(method, resource, data = nil)
+			resource = get_resource(resource, method, data)
+
+			payload = (method == :post) ? data.to_json : {}
+
+			resource.send(method, payload) do |response, request, result, &block|
+				case response.code
+				when 201
+					JSON.parse(response)
+				when 200
+					JSON.parse(response)
+				when 400
+					raise RequestError, "Bad Data"
+				when 401
+					raise RequestError, "Unauthorized, please check your username and token"
+				when 404	
+					raise RequestError, "Requested URL not found"
+				when 500
+					raise RequestError, "Server Error, please check https://www.fatzebra.com.au"
+				when 501
+					raise RequestError, "Problem processing your request - please check your data"
+				end
+
+			end
+		end
+	end
+end

data/lib/fat_zebra/models/base.rb

@@ -0,0 +1,11 @@
+module FatZebra
+	module Models
+		class Base
+			def initialize(attrs = {})
+				attrs.each do |key, val|
+					self.send("#{key}=", val) if self.respond_to?("#{key}=")
+				end
+			end
+		end
+	end
+end

data/lib/fat_zebra/models/purchase.rb

@@ -0,0 +1,7 @@
+module FatZebra
+	module Models
+		class Purchase < Base
+			attr_accessor :id, :amount, :reference
+		end
+	end
+end

data/lib/fat_zebra/models/refund.rb

@@ -0,0 +1,11 @@
+module FatZebra
+	module Models
+		class Refund < Base
+			attr_accessor :amonut, :reference, :transaction_id, :original_transaction_id
+
+			def original_transaction
+				@original_transaction ||= Purchase.find(self.original_transaction_id)
+			end
+		end
+	end
+end

data/lib/fat_zebra/models/response.rb

@@ -0,0 +1,28 @@
+module FatZebra
+	module Models
+		class Response
+			attr_accessor :successful, :result, :errors, :test
+			def initialize(response, type = :purchase)
+				self.test = response["test"]
+				self.successful = response["successful"]
+				self.errors = response["errors"]
+				case type
+					when :purchase
+						self.result = Purchase.new(response["response"])
+						alias purchase result
+					when :refund
+						self.result = Refund.new(response["response"])
+						alias refund result
+				end
+			end
+
+			def successful?
+				self.successful
+			end
+
+			def test?
+				self.test
+			end
+		end
+	end
+end

data/lib/fat_zebra/version.rb

@@ -0,0 +1,3 @@
+module FatZebra
+  VERSION = "0.0.1"
+end

data/lib/fat_zebra.rb

@@ -0,0 +1,11 @@
+require 'securerandom'
+require 'json'
+require 'rest_client'
+require 'fat_zebra/errors'
+require "fat_zebra/version"
+require 'fat_zebra/constants'
+require 'fat_zebra/gateway'
+require 'fat_zebra/models/base'
+require 'fat_zebra/models/purchase'
+require 'fat_zebra/models/refund'
+require 'fat_zebra/models/response'

data/spec/gateway_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+TEST_USER = "TEST"
+TEST_TOKEN = "TEST"
+TEST_LOCAL = true
+
+describe FatZebra::Gateway do
+	before :each do
+		# Setup the gateway for testing
+		server = TEST_LOCAL == true ? "fatapi.dev" : "gateway.fatzebra.com.au"
+		@gw = FatZebra::Gateway.new(TEST_USER, TEST_TOKEN, server, {:secure => !TEST_LOCAL})
+	end
+
+	it "should require username and token are provided" do
+		lambda { FatZebra::Gateway.new("test", nil) }.should raise_exception(FatZebra::InvalidArgumentError)
+	end
+
+	it "should require that the gateway_server arg is not nil or empty" do
+		lambda { FatZebra::Gateway.new("test", "test", "") }.should raise_exception(FatZebra::InvalidArgumentError)	
+	end
+
+	it "should load a valid instance of the gateway" do
+		@gw.ping.should be_true
+	end
+
+	it "should perform a purchase" do
+		result = @gw.purchase(10000, "Matthew Savage", "5123456789012346", "05/2013", 123, "TEST#{rand}", "1.2.3.4")
+		result.should be_successful
+		result.errors.should be_empty
+	end
+
+	it "should fetch a purchase" do
+		result = @gw.purchase(10000, "Matthew Savage", "5123456789012346", "05/2013", 123, "TES#{rand}T", "1.2.3.4")
+		@gw.purchases(result.purchase.id)
+	end
+end

data/spec/models/purchase_spec.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+describe FatZebra::Models::Purchase do
+	subject { FatZebra::Models::Purchase.new }
+
+	it "should be instance of base" do
+		# subject.should be_instance_of(FatZebra::Models::Base)
+	end
+end

data/spec/models/refund_spec.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+describe FatZebra::Models::Refund do
+	subject { FatZebra::Models::Refund.new }
+
+	it "should be instance of base" do
+		# subject.should be_instance_of(FatZebra::Models::Base)
+	end
+end

data/spec/models/response_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe FatZebra::Models::Response do
+	
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'fat_zebra' # and any other gems you need
+
+RSpec.configure do |config|
+  
+end