paypal_api 0.3.4 → 0.3.5

data/README.markdown

@@ -7,33 +7,125 @@ the gems that do exist do not cover the entire api.
 
 # Usage
 
-## Interfacing with the gem:
+i want interaction with the gem to be flat and straight-forward, with clear mapping between the api docs and the gem. right now
+the only place where i break this is for "list type" fields, where it makes sense to treat it more like a ruby array.
+all keys are ruby style (snake_case), and should automatically get converted to the proper formatting for you.
+
+if you don't add all the required fields to the request, it will raise `Paypal::InvalidRequest` exceptions. if you try to set the wrong
+type to a field, it will raise `Paypal::InvalidParameter` exceptions.
+
+### Payments Pro Example
+
+the most useful methods, imo, are do_direct_payment, do_reference_
+
 ```ruby
 require "paypal_api"
 
-request = Paypal::PaymentsPro.do_direct_payment # returns instance of Paypal::DoDirectPaymentRequest
+# create request
+request = Paypal::PaymentsPro.do_reference_transaction # returns instance of Paypal::DoDirectPaymentRequest
 
-# Set required fields
-request.first_name = "mark"
-request.last_name = "winton"
+# set required fields
+request.reference_id = "other_paypal_transaction_id"
+request.payment_action = :authorization
 request.amt = 10.00
 
-# Add a list type field
-request.item.push {
-	:email => "bro@dudeman.com",
-	:amt => 23.0
+# make request
+response = request.make
+
+# usable information
+response.success? # true if successful
+response[:correlation_id] # correlation id string returned by paypal
+transaction_id = response[:transaction_id] # transaction id string, not return on all calls
+
+# in this example, since the first request was an authorization, you can then capture it
+request2 = Paypal::PaymentsPro.do_capture # returns instance of Paypal::DoCaptureRequest
+
+request2.authorization_id = transaction_id
+request2.amt = 10.00
+
+response2 = request2.make
+
+response2.success?
+```
+
+### Adaptive Payments Example
+
+even though the api's are very different, they should be abstracted the same way
+
+```ruby
+require "paypal_api"
+
+request = Paypal::AdaptivePayments.pay # returns instance of Paypal::PayRequest
+
+# set required fields
+request.cancel_url = "http://www.test.com/cancel"
+request.return_url = "http://www.test.com/return"
+request.ip_address = "192.168.1.1"
+
+# add a list type field
+request.receiver.push {
+  :email => "bro@dudeman.com",
+  :amount => 23.0
 }
 
+# make request
 response = request.make
 
+# usable information
 response.success? # true if successful
+response[:pay_key] # usually what you use this api method for
 
-response[:correlation_id] # correlation id string returned by paypal
-response[:transaction_id] # transaction id string, not return on all calls
+# in adaptive payments flows, sometimes you need to redirect to paypal
+response.redirect_url
+# used if you want the payment flow without the client leaving your site (see below)
+response.embedded_url
+
+# errors
+response.error_message # populated by paypal response error when request fails
+response.error_code # populated by paypal response error
+response.error_field # some api calls let you know which field caused the issue
+```
+
+for adaptive payments and preapprovals, sometimes you want to use the paypal javascript libraries
+and their associated "embedded" payment flows. `response.embedded_url` gives you what you need for this.
+note that you also need to include one of their js libraries.
+
+```javascript
+// include one of their libraries asynchronously:
+// minibrowser library: https://www.paypalobjects.com/js/external/dg.js
+// embedded library: https://www.paypalobjects.com/js/external/apdg.js
+window.paypalAsyncInit = function () {
+  window.paypalController = new PAYPAL.apps.DGFlow({expType: "mini"});
+};
+
+(function(d){
+var js, id = 'paypal-sdk'; if (d.getElementById(id)) {return;}
+js = d.createElement('script'); js.id = id; js.async = true;
+js.src = "https://www.paypalobjects.com/js/external/dg.js";
+d.getElementsByTagName('head')[0].appendChild(js);
+js.onload = window.paypalAsyncInit;
+}(document));
+
+
+// later, after receiving embedded_url from the server:
+window.paypalController.startFlow(embeddUrl);
 ```
 
+### More
+
+the actual api method definitions should be more or less readable as is (if not, you can call me a jerk, i sorry). look in
+`lib/paypal_api/apis/` for reference, until i document each method.
+
 ## Configure
 
+it's hard to navigate paypals terribly organized everything, here are some links to help you find what you need:
+
+* paypal api credentials for production: [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: [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)
+* where to tell paypal what your ipn callback url is: [https://www.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-ipn-notify](https://www.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-ipn-notify)
+
+### Simple Configuration
+
 ```ruby
 Paypal::Request.version = "84.0"
 Paypal::Request.environment = "development" # or "production"
@@ -42,11 +134,7 @@ 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
+### Configure For 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
 
@@ -68,7 +156,7 @@ production:
 
 ## Ipn Messages
 
-there is an ipn message model generator: `rails generate paypal:ipn_message`, it will create
+there is an ipn message model generator: `$ rails generate paypal:ipn_message`, it will create
 a migration and the IpnMessage model.
 
 you must edit the route and add a handler like so:
@@ -98,8 +186,10 @@ end
 
 ## Testing
 
-i'm an rspec kinda guy. note that i have test for actual requests against the paypal
-sandbox server, but they are off by default. remove the line about `:slow_paypal` in
+you can run the tests: `$ bundle exec rspec spec`
+
+i'm an rspec kinda guy, hopefully you are ok with that. note that i have tests for actual requests against the paypal
+sandbox server, but they are turned off by default. remove the line about `:slow_paypal` in
 `spec/spec_helper.rb` to turn these back on.
 
 also note that, for the Adaptive Payments api, an application id is required, for testing,
@@ -115,14 +205,40 @@ repository. in order to get to that stage, i will need to add support for adapti
 
 # 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).
+right now the most help i could use is in writing the signatures for the various api calls from the Payments Pro and
+Adaptive Payments apis (or any others really).
 
-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.
+i've tried to make it easy to contribute, signatures are created pretty easily:
 
-for contributing to the api method request specs, look at `lib/paypal_api/apis/payments_pro.rb`
+```ruby
+# lib/paypal_api/apis/payments_pro.rb
+
+module Paypal
+  class PaymentsPro < Paypal::Api
+
+    set_request_signature :do_capture, {
+      :method => "DoCapture",
+      :authorization_id => String,
+      :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),
+      :note => Optional.new(String),
+      :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),
+      :terminal_id => Optional.new(String)
+    }
+
+  end
+end
+```
 
 this is my first gem, so i'll be excited for any contributions :'(
 
@@ -192,8 +308,6 @@ note that you need to request that paypal enable mass pay for your account befor
 
 * mass_pay - &#10003;
 
-## Instant Pay Notifications
-
 ## Express Checkout
 
 ## Adaptive Payments

data/lib/paypal_api/apis/adaptive_payments.rb

@@ -5,6 +5,7 @@
 module Paypal
 
 	class AdaptivePaymentsResponse < Response
+
 		def initialize(stringio)
 			@raw_response = stringio.class == StringIO ? stringio.read : stringio
 			@parsed_response = CGI.parse(@raw_response)
@@ -30,6 +31,17 @@ module Paypal
 			end
 		end
 
+		def redirect_url
+			"#{self.base_url}/webscr?cmd=_ap-#{command}&#{command_key}=#{command_value}" if webscr?
+		end
+
+		# requires https://www.paypalobjects.com/js/external/dg.js (lightbox)
+		#  	or https://www.paypalobjects.com/js/external/apdg.js (minibrowser)
+		# 	to be added to the page
+		def embedded_url
+			"#{self.base_url}/webapps/adaptivepayment/flow/pay?payKey=#{self[:pay_key]}#{"&preapprovalkey=#{self[:preapproval_key]}" if command == :preapproval}" if webscr?
+		end
+
 		protected
 
 			def symbol_to_key(symbol)
@@ -40,6 +52,28 @@ module Paypal
 					return Paypal::Api.symbol_to_lower_camel(symbol)
 				end
 			end
+
+			def base_url
+				Paypal::Request.environment == "production" ? "https://www.paypal.com" : "https://www.sandbox.paypal.com"
+			end
+
+		private
+
+			def command_key
+				return command == :preapproval ? "preapprovalkey" : "payKey"
+			end
+
+			def command_value
+				return command == :preapproval ? self[:preapproval_key] : self[:pay_key]
+			end
+
+			def command
+				return self[:preapproval_key] ? :preapproval : :payment
+			end
+
+			def webscr?
+				return true if self[:pay_key] || self[:preapproval_key]
+			end
 	end
 
 	class AdaptivePaymentsRequest < Request

data/lib/paypal_api/support/parameter.rb

@@ -134,6 +134,7 @@ module Paypal
 					@allowed_values = values[0]
 				else
 					@allowed_values = values
+					@normalized_values = @allowed_values.inject({}){|acc, v| acc[normalize(v)] = v; acc}
 				end
 			end
 
@@ -145,8 +146,9 @@ module Paypal
 						raise Paypal::InvalidParameter, "'#{val}' must be a key in #{@allowed_values.keys}"
 					end
 				else
-					if @allowed_values.include?(normalize(val))
-						return normalize(val)
+					normed = normalize(val)
+					if @normalized_values.include?(normed)
+						return @normalized_values[normed]
 					else
 						raise Paypal::InvalidParameter, "'#{val}' must be one of #{@allowed_values}"
 					end
@@ -154,9 +156,7 @@ module Paypal
 			end
 
 			def normalize(val)
-				return val if val.class == String
-				return Paypal::Api.symbol_to_camel(val) if val.class == Symbol
-				return nil
+				return val.to_s.downcase.gsub(/[^a-z0-9]/,"")
 			end
 		end
 

data/lib/paypal_api/version.rb

@@ -1,3 +1,3 @@
 module Paypal
-  VERSION = "0.3.4"
+  VERSION = "0.3.5"
 end

data/spec/support/parameter_spec.rb

@@ -19,6 +19,14 @@ describe Paypal::Api::Parameter do
 			}.to raise_exception(Paypal::InvalidParameter)
 		end
 
+		it "should allow lookup on normalized matching" do
+			param = @api::Enum.new("This", "FirstTest", "SaweetDude")
+
+			param.parse(:this).should eq("This")
+			param.parse(:first_test).should eq("FirstTest")
+			param.parse(:saweet_dude).should eq("SaweetDude")
+		end
+
 		describe "hash enumerations" do
 			before(:each) do
 				@param = @api::Enum.new({:thing => "OK", :that => "TEO"})

data/spec/unit/adaptive_payments_response_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+
+describe Paypal::AdaptivePaymentsResponse do
+	describe "for pay requests" do
+		before(:each) do
+			@response = Paypal::AdaptivePaymentsResponse.new("responseEnvelope.timestamp=2012-02-29T13%3A40%3A17.074-08%3A00&responseEnvelope.ack=Success&responseEnvelope.correlationId=722689b427b7c&responseEnvelope.build=2486531&payKey=AP-1W763567RM6393227&paymentExecStatus=CREATED")
+		end
+
+		describe "embedded url" do
+			it "should create a proper embedded url" do
+				@response.embedded_url.should include("/webapps/adaptivepayment/flow/pay?payKey=")
+			end
+		end
+
+		describe "redirect url" do
+			it "should create a proper redirect url" do
+				@response.redirect_url.should include("/webscr?cmd=_ap-")
+			end
+		end
+
+		it "should know about production vs sandbox" do
+			Paypal::Request.environment = "production"
+			@response.redirect_url.should_not include("sandbox")
+			Paypal::Request.environment = "something else"
+			@response.redirect_url.should include("sandbox")
+		end
+	end
+
+	describe "for payapproval requests" do
+		it "should create a proper redirect url" do
+
+		end
+	end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paypal_api
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-01 00:00:00.000000000Z
+date: 2012-03-02 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70244225979560 !ruby/object:Gem::Requirement
+  requirement: &70244405693760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.1'
   type: :runtime
   prerelease: false
-  version_requirements: *70244225979560
+  version_requirements: *70244405693760
 - !ruby/object:Gem::Dependency
   name: ruby-debug19
-  requirement: &70244225978140 !ruby/object:Gem::Requirement
+  requirement: &70244405693180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70244225978140
+  version_requirements: *70244405693180
 - !ruby/object:Gem::Dependency
   name: rspec-rails
-  requirement: &70244225976180 !ruby/object:Gem::Requirement
+  requirement: &70244405692480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: '2.6'
   type: :development
   prerelease: false
-  version_requirements: *70244225976180
+  version_requirements: *70244405692480
 - !ruby/object:Gem::Dependency
   name: generator_spec
-  requirement: &70244225974780 !ruby/object:Gem::Requirement
+  requirement: &70244405691920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -54,7 +54,7 @@ dependencies:
         version: 0.8.5
   type: :development
   prerelease: false
-  version_requirements: *70244225974780
+  version_requirements: *70244405691920
 description: alpha - currently covers part of payments pro and all of mass pay
 email:
 - matt.handler@gmail.com
@@ -92,6 +92,7 @@ files:
 - spec/support/parameter_spec.rb
 - spec/support/request_spec.rb
 - spec/support/response_spec.rb
+- spec/unit/adaptive_payments_response_spec.rb
 - spec/unit/adaptive_payments_spec.rb
 - spec/unit/api_spec.rb
 - spec/unit/mass_pay_spec.rb
@@ -126,6 +127,7 @@ test_files:
 - spec/support/parameter_spec.rb
 - spec/support/request_spec.rb
 - spec/support/response_spec.rb
+- spec/unit/adaptive_payments_response_spec.rb
 - spec/unit/adaptive_payments_spec.rb
 - spec/unit/api_spec.rb
 - spec/unit/mass_pay_spec.rb