paypal_api 0.3.0

data/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*~

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

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

data/README.markdown

@@ -0,0 +1,161 @@
+# Paypal Api Gem
+
+a ruby library to handle the entire paypal api.
+
+paypals documentation sucks, and there do not appear to be any officially supported paypal gems.
+the gems that do exist do not cover the entire api.
+
+# Usage
+
+## Interfacing with the gem:
+```ruby
+require "paypal_api"
+
+request = Paypal::PaymentsPro.do_direct_payment # returns instance of Paypal::DoDirectPaymentRequest
+
+# Set required fields
+request.first_name = "mark"
+request.last_name = "winton"
+request.amt = 10.00
+
+# Add a list type field
+request.item.push {
+	:l_email => "bro@dudeman.com",
+	:l_amt => 23.0
+}
+
+response = request.make
+
+response.success? # true if successful
+
+response[:correlation_id] # correlation id string returned by paypal
+response[:transaction_id] # transaction id string, not return on all calls
+```
+
+## Configure
+
+```ruby
+Paypal::Request.version = "84.0"
+Paypal::Request.environment = "development" # or "production"
+Paypal::Request.user = "user_api1.something.com"
+Paypal::Request.pwd = "some_password_they_gave_you"
+Paypal::Request.signature = "some_signature"
+```
+
+paypal api credentials for production can be found here: [https://www.paypal.com/us/cgi-bin/webscr?cmd=_profile-api-signature](https://www.paypal.com/us/cgi-bin/webscr?cmd=_profile-api-signature)
+
+sandbox credentials can be found here: [https://developer.paypal.com/cgi-bin/devscr?cmd=_certs-session&login_access=0](https://developer.paypal.com/cgi-bin/devscr?cmd=_certs-session&login_access=0)
+
+## Rails
+
+if you'd like to have multi environment configuration in rails, place a file at `config/paypal.yml` and the gem will read from it accordingly
+
+```yml
+test:
+  environment: "sandbox"
+  username: "user_api1.something.com"
+  password: "some_password_they_gave_you"
+  signature: "some_signature"
+
+production:
+  environment: "production"
+  username: <%= ENV["PAYPAL_USERNAME"] %>
+  password: <%= ENV["PAYPAL_PASSWORD"] %>
+  signature: <%= ENV["PAYPAL_SIGNATURE"] %>
+```
+
+# Current Status
+
+alpha
+
+the work i've done so far is in order to get up and running on a project. once the project is settled, i'll be spending
+some more time making the gem complete. once i feel it is in the beta stage i will push it to the official ruby gems
+repository. in order to get to that stage, i will need to add support for adaptive payments, express checkout, etc...
+
+# How To Contribute
+
+right now the most help i could use is in writing the specs for the various api calls from the Payments Pro api. i will be working on
+separating out the different access methods shortly (there's a huge difference between how to call the Payments Pro api vs the Adaptive Payments api).
+
+as this is my first gem, i could also use help with some of the niceties with rails. ideally there will be a generator for migrating your db
+to store ipn messages, and a generated class with callbacks to handle the various cases. this will probably take a lot of effort since there
+are many intricacies in the meanings of the different ipn's.
+
+for contributing to the api method request specs, look at `lib/paypal_api/apis/payments_pro.rb`
+
+this is my first gem, so i'll be excited for any contributions :'(
+
+# Paypal API Checklist
+
+here's a list of api methods, and whether or not they are implemented (please take a look at `lib/paypal_api/apis/payments_pro.rb` if you'd
+like to contribute, i've made it pretty easy to add compatibility for a new api call)
+
+## Payments Pro
+
+* do_direct_payment - &#10003;
+
+* do_reference_transaction - &#10003;
+
+* do_capture - &#10003;
+
+* do_void - &#10003;
+
+* get_recurring_payments_profile_details - started
+
+* address_verify
+
+* bill_outstanding_amount
+
+* callback
+
+* create_recurring_payments_profile
+
+* do_authorization
+
+* do_express_checkout_payment
+
+* do_nonreferenced_credit
+
+* do_reauthorization
+
+* get_balance
+
+* get_billing_agreement_customer_details
+
+* get_express_checkout_details
+
+* get_transaction_details
+
+* manage_pending_transaction_status
+
+* manage_recurring_payments_profile_status
+
+* refund_transaction
+
+* set_customer_billing_agreement
+
+* set_express_checkout
+
+* transaction_search
+
+* update_recurring_payments_profile
+
+## Mass Pay
+
+note that you need to request that paypal enable mass pay for your account before it will work
+
+* mass_pay - &#10003;
+
+## Instant Pay Notifications
+
+## Express Checkout
+
+## Adaptive Payments
+
+## Adaptive Accounts
+
+## Invoicing
+
+## Button Manager
+
+## Permissions

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/init.rb

@@ -0,0 +1 @@
+require "paypal_api"

data/lib/paypal_api/apis/api.rb

@@ -0,0 +1,149 @@
+module Paypal
+	module Formatters
+		def escape_uri_component(string)
+			string = string.to_s
+			return URI.escape(string, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
+		end
+
+		def to_key(symbol)
+			return symbol.to_s.gsub(/[^a-z0-9]/i, "").upcase
+		end
+	end
+
+	class Api
+
+		attr_accessor :request
+
+		protected
+
+			def self.set_accessor(klass, name, type = nil)
+				set_reader(klass, name, type)
+				set_writer(klass, name, type)
+			end
+
+			# writers should validate before assigning value
+			def self.set_writer(klass, field, type)
+				klass.class_eval do
+					define_method("#{field}=") do |val|
+						# arbitrary value
+						if type.nil?
+							instance_variable_set("@#{field}", val)
+						# special types
+						elsif type.class == Regexp
+							if match = type.match(val)
+								instance_variable_set("@#{field}", match[0])
+							else
+								raise Paypal::InvalidParameter, "#{field} expects a string that matches #{type}"
+							end
+						elsif type.class == Optional
+							instance_variable_set("@#{field}", type.parse(val))
+						elsif type.class == Enum
+							instance_variable_set("@#{field}", type.parse(val))
+						elsif type.class == Coerce
+							instance_variable_set("@#{field}", type.parse(val))
+						elsif type.class == Default
+							instance_variable_set("@#{field}", type.parse(val))
+						# custom type
+						elsif type.class == Proc && type.call(val)
+							instance_variable_set("@#{field}", val)
+						# is_a type
+						elsif type == val.class
+							instance_variable_set("@#{field}",val)
+						else
+							raise Paypal::InvalidParameter, "#{field}'s spec was set incorrectly"
+						end
+					end
+				end
+			end
+
+			def self.set_reader(klass, m, type, constant = false)
+				variable = "@#{m}"
+
+				klass.class_eval do
+					define_method(m) do
+						if constant
+							return type
+						elsif type.class == Default
+							instance_variable_set(variable, type.value) unless instance_variable_defined?(variable)
+							instance_variable_get(variable)
+						else
+							instance_variable_get(variable)
+						end
+					end
+				end
+			end
+
+			def self.set_sequential_reader(klass, k, v)
+				variable = "@#{k}"
+
+				klass.class_eval do
+					define_method(k) do
+						instance_variable_set(variable, v.clone) unless instance_variable_defined?(variable)
+						instance_variable_get(variable)
+					end
+				end
+			end
+
+			# collected from set request signature
+			def self.set_required(klass, keys)
+				klass.class_eval do
+					@required = keys
+				end
+			end
+
+			# collected from set request signature
+			def self.set_sequential(klass, keys)
+				klass.class_eval do
+					@sequential = keys
+				end
+			end
+
+			def self.symbol_to_camel(symbol)
+				return symbol.to_s.downcase.split("_").map(&:capitalize).join
+			end
+
+			def self.set_request_signature(name, hash)
+				# create request object
+				class_name = "#{self.symbol_to_camel name}Request"
+				self.class.class_eval <<-EOS
+				  class Paypal::#{class_name} < Request; end
+				EOS
+				klass = Kernel.const_get("Paypal").const_get(class_name)
+
+				# add setters/getters
+				required = []
+				sequential = []
+				hash.each do |k,v|
+					if v.class == String || v.class == Fixnum || v.class == Float
+						set_reader klass, k, v, true
+					elsif v.class == Sequential
+						set_sequential_reader klass, k, v
+					else
+						set_accessor klass, k, v
+					end
+
+					required.push(k) unless v.class == Optional || v.class == Sequential
+					sequential.push(k) if v.class == Sequential
+				end
+
+				# set which keys are required for the request
+				set_required(klass, required)
+				set_sequential(klass, sequential)
+
+				# create api method
+				self.class_eval <<-EOS
+					def self.#{name}(hash = {})
+						return #{klass}.new(hash)
+					end
+				EOS
+			end
+
+			# TODO: make this useful :'(
+			# def set_response_signature(hash)
+			# 	hash.each do |k,v|
+			# 		set_reader k, v
+			# 	end
+			# end
+	end
+
+end

data/lib/paypal_api/apis/mass_pay.rb

@@ -0,0 +1,25 @@
+module Paypal
+	class MassPay < Paypal::Api
+		set_request_signature :mass_pay, {
+			:method => "MassPay",
+			:email_subject => Optional.new(String), # max 255 char
+			:currency_code => Default.new("USD", String),
+			:receiver_type => Default.new("EmailAddress", Enum.new(:email_address => "EmailAddress", :user_id => "UserID")),
+			:payee => Sequential.new({
+				:email => String,
+				:amt => Float,
+				:unique_id => Optional.new(String)
+			}, 250, lambda {|key, i| "L_#{key.to_s.gsub("_","").upcase}#{i}"})
+		}
+	end
+
+	class MassPayRequest
+
+		protected
+			def validate!
+				if @payee.length == 0
+					raise Paypal::InvalidRequest, "you pust provide at least one payee"
+				end
+			end
+	end
+end

data/lib/paypal_api/apis/payments_pro.rb

@@ -0,0 +1,155 @@
+module Paypal
+	class PaymentsPro < Paypal::Api
+
+		set_request_signature :do_direct_payment, {
+
+			# DoDirectPayment Request Fields
+			:method => "DoDirectPayment",
+			:payment_action => Optional.new(Enum.new("Authorization", "Sale")),
+			:ip_address =>	/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/,
+			:return_mf_details => Optional.new(
+				Coerce.new( lambda do |val|
+					return [1, "1", true].include?(val) ? 1 : 0
+				end)
+			),
+
+
+			# Credit Card Details Fields
+			:credit_card_type => Optional.new(Enum.new("Visa", "MasterCard", "Discover", "Amex", "Maestro")),
+			:acct => /\d+/, # this should be better
+			:exp_date => /^\d{6}$/, # "MMYYYY"
+			:cvv2 => /^\d{3,4}$/,
+			:start_date => Optional.new(/^\d{6}$/), # maestro only
+			:issue_number => Optional.new(/^\d{,2}$/), #maestro only
+
+
+			# Payer Information Fields
+			:email => Optional.new(/email/), # max 127 char
+			:first_name => String, # max 25 char
+			:last_name => String, # max 25 char
+
+
+			# Address Fields
+			:street => String, # max 100 char
+			:street_2 => Optional.new(String), # max 100 char
+			:city => String, # max 40 char
+			:state => String, # max 40 char
+			:country_code => Default.new("US", /^[a-z]{2}$/i),
+			:zip => String, # max 20 char
+			:ship_to_phone_num => Optional.new(String), # max 20 char
+
+
+			# Payment Details Fields
+			:amt => Float, # complicated: https://www.x.com/developers/paypal/documentation-tools/api/dodirectpayment-api-operation-nvp
+			:currency_code => Default.new("USD", /^[a-z]{3}$/i),
+
+			# TODO:
+			:item_amt => Optional.new,
+			:shipping_amt => Optional.new,
+			:insurance_amt => Optional.new,
+			:shipdisc_amt => Optional.new,
+			:handling_amt => Optional.new,
+			:tax_amt => Optional.new,
+
+			:desc => Optional.new(String), # max 127 char
+			:custom => Optional.new(String), # max 256 char
+			:inv_num => Optional.new(String), # max 127 char
+			:button_source => Optional.new(String), # max 32 char
+
+			:notify_url => Optional.new, # hard to tell if this is part of this api or not from the wording in the docs
+			:recurring => Default.new("N", lambda {|anything| "Y" }),
+
+
+			# TODO: Payment Details Item Fields
+			# TODO: Ebay Item Payment Details Item Fields
+			# TODO: Ship To Address Fields
+			# TODO: 3D Secure Request Fields (U.K. Merchants Only)
+
+		}
+
+		set_request_signature :do_reference_transaction, {
+			:method => "DoReferenceTransaction",
+			:reference_id => String,
+			:payment_action => Default.new("Sale", Enum.new("Authorization", "Sale")),
+			:return_mf_details => Optional.new(
+				Coerce.new( lambda do |val|
+					return [1, "1", true].include?(val) ? 1 : 0
+				end)
+			),
+			:soft_descriptor =>Optional.new(lambda {|val|
+				if val.match(/^([a-z0-9]|\.|-|\*| )*$/i) && val.length <= 22
+					return true
+				else
+					return false
+				end
+			}),
+
+			# ship to address fields
+			:ship_to_name => Optional.new(String), # max 32
+			:ship_to_street => Optional.new(String), # max 100
+			:ship_to_street_2 => Optional.new(String), # max 100
+			:ship_to_city => Optional.new(String), # max 40
+			:ship_to_state => Optional.new(String), # max 40
+			:ship_to_zip => Optional.new(String), # max 20
+			:ship_to_country => Optional.new(String), # max 2
+			:ship_to_phone_num => Optional.new(/[0-9+-]+/), # max 20
+
+			# payment details fields
+			:amt => Float,
+			:currency_code => Default.new("USD", /^[a-z]{3}$/i),
+
+			# TODO:
+			:item_amt => Optional.new,
+			:shipping_amt => Optional.new,
+			:insurance_amt => Optional.new,
+			:shipdisc_amt => Optional.new,
+			:handling_amt => Optional.new,
+			:tax_amt => Optional.new,
+
+			:desc => Optional.new(String), # max 127 char
+			:custom => Optional.new(String), # max 256 char
+			:inv_num => Optional.new(String), # max 127 char
+			:button_source => Optional.new(String), # max 32 char
+
+			:notify_url => Optional.new, # hard to tell if this is part of this api or not from the wording in the docs
+			:recurring => Default.new("N", lambda {|anything| "Y" }),
+
+			:item => Sequential.new({
+					:l_item_category => Enum.new("Digital", "Physical")
+				})
+
+		}
+
+		set_request_signature :do_capture, {
+			:method => "DoCapture",
+			:authorization_id => String, # max 19 char
+			:amt => Float,
+			:currency_code => Default.new("USD", /^[a-z]{3}$/i),
+			:complete_type => Default.new("Complete", Enum.new("Complete", "NotComplete")),
+			:inv_num => Optional.new(String), # max 127 char
+			:note => Optional.new(String), # max 255 char
+			:soft_descriptor => Optional.new(lambda {|val|
+				if val.match(/^([a-z0-9]|\.|-|\*| )*$/i) && val.length <= 22
+					return true
+				else
+					return false
+				end
+			}),
+
+			:store_id => Optional.new(String), # max 50 char
+			:terminal_id => Optional.new(String) # max 50 char
+		}
+
+		set_request_signature :do_void, {
+			:method => "DoVoid",
+			:authorization_id => String, # Note: If you are voiding a transaction that has been reauthorized, use the ID from the original authorization, and not the reauthorization.
+			:note => Optional.new(String) # max 255 char
+		}
+
+		set_request_signature :get_recurring_payments_profile_details, {
+			:method => "GetRecurringPaymentsProfileDetails",
+			:profile_id => String # max 19 char
+		}
+
+	end
+end

data/lib/paypal_api/support/parameter.rb

@@ -0,0 +1,195 @@
+
+module Paypal
+
+	class Api
+
+		class Parameter
+			attr_accessor :value
+
+			def initialize(value)
+				@value = value
+			end
+
+			def parse(anything)
+				@value = anything
+				return @value
+			end
+
+			def parameter_parse(val)
+				if @parameter.class == Class
+					if val.class == @parameter
+						return val
+					else
+						raise Paypal::InvalidParameter, "'#{val}'' is not of type #{@parameter.class}"
+					end
+				elsif @parameter.class == Regexp
+					match = @parameter.match(val)
+					if match
+						return match[0]
+					else
+						raise Paypal::InvalidParameter, "'#{val}' does not match #{@parameter}"
+					end
+				elsif @parameter.class < Parameter
+					return @parameter.parse(val)
+				else
+					raise Paypal::InvalidParameter, "#{@parameter.class} is an invalid parameter specification"
+				end
+			end
+		end
+
+		class Sequential < Parameter
+			include Paypal::Formatters
+
+			attr_accessor :list
+
+			# allows you to specify an optional key -> paypal_key proc due to nonstandard key formatting
+			def initialize(hash = {}, limit = nil, key_proc = nil)
+				@list = []
+				@schema = hash
+				@required = hash.map{|(k,v)| k if v.class != Optional }.compact
+				@key_proc = key_proc if key_proc
+				@limit = limit
+			end
+
+			# necessary because sequential stores request state, need a new list created for each
+			# 	request instance
+			def clone
+				return self.class.new(@schema, @limit, @key_proc)
+			end
+
+			def length
+				return @list.length
+			end
+
+			def push(hash)
+				raise Paypal::InvalidParameter, "missing required parameter for sequential field" unless (@required - hash.keys).empty?
+				raise Paypal::InvalidParameter, "field cannot have more than #{@limit} items, #{@list.length} provided" if !@limit.nil? && @list.length == @limit
+
+				hash.each do |k,val|
+					type = @schema[k]
+
+					if type.nil?
+						hash[k] = val
+					elsif type.class == Regexp
+						if match = type.match(val)
+							hash[k] = match[0]
+						else
+							raise Paypal::InvalidParameter, "'#{val}' did not match #{type}"
+						end
+					elsif [Optional, Enum, Coerce, Default].include?(type.class)
+						hash[k] = type.parse(val)
+					elsif type.class == Proc && type.call(val)
+						hash[k] = val
+					elsif type == val.class
+						hash[k] = val
+					else
+						raise Paypal::InvalidParameter, "#{type.class} is an invalid parameter specification"
+					end
+				end
+
+				@list.push(hash)
+			end
+
+			def to_key(symbol, i)
+				if @key_proc
+					return @key_proc.call(symbol, i)
+				else
+					return symbol.to_s.split("_", 2).map{|s| s.gsub("_", "") }.join("_").gsub(/[^a-z0-9_]/i, "").upcase + "#{i}"
+				end
+			end
+
+			def to_query_string
+				output = ""
+				@list.each_index do |i|
+					@list[i].each do |(k,v)|
+						output = "#{output}&#{to_key(k, i)}=#{escape_uri_component(@list[i][k])}"
+					end
+				end
+				return output
+			end
+
+		end
+
+		class Coerce < Parameter
+
+			attr_reader :method
+
+			def initialize(method)
+				@method = method
+			end
+
+			def parse(val)
+				return @method.call(val)
+			end
+		end
+
+		class Enum < Parameter
+
+			# needs to return the exact string if given instead of symbol
+			attr_reader :allowed_values
+
+			def initialize(*values)
+				if values.length == 1 && values[0].is_a?(::Hash)
+					@hash_enum = true
+					@allowed_values = values[0]
+				else
+					@allowed_values = values
+				end
+			end
+
+			def parse(val)
+				if @hash_enum
+					if @allowed_values.include?(val)
+						return @allowed_values[val]
+					else
+						raise Paypal::InvalidParameter, "'#{val}' must be a key in #{@allowed_values.keys}"
+					end
+				else
+					if @allowed_values.include?(normalize(val))
+						return normalize(val)
+					else
+						raise Paypal::InvalidParameter, "'#{val}' must be one of #{@allowed_values}"
+					end
+				end
+			end
+
+			def normalize(val)
+				return val if val.class == String
+				return Paypal::Api.symbol_to_camel(val) if val.class == Symbol
+				return nil
+			end
+		end
+
+		class Hash < Parameter
+
+		end
+
+		# Optional and Default can take other parameters as input
+
+		class Optional < Parameter
+			def initialize(parameter = nil)
+				@parameter = parameter.is_a?(Sequential) ? parameter.clone : parameter
+			end
+
+			def parse(val)
+				return parameter_parse(val)
+			end
+		end
+
+
+		class Default < Parameter
+
+			def initialize(value, parameter)
+				@value = value
+				@parameter = parameter.is_a?(Sequential) ? parameter.clone : parameter
+			end
+
+			def parse(val)
+				return parameter_parse(val)
+			end
+
+		end
+
+	end
+
+end