pp-adaptive 0.0.2 → 0.0.3

data/README.md

@@ -1,17 +1,7 @@
 # A Ruby API for PayPal Adaptive Payments
 
-  - Current Status: Work-in-progress (don't use, API subject to major change)
-  - Working:
-    - setting up an explicit preapproval
-    - processing payments (for an explicit preapproval)
-  - Not working:
-    - executing pre-created payments
-    - changing options on a created payment
-    - refunds/cancellations
-    - minor things like currency conversion requests
-
 This gem provides access to PayPal's Adaptive Payments API using easy-to-use
-ruby classes.  The internals are largely backed by
+ruby classes. The internals are largely backed by
 [Virtus](https://github.com/solnic/virtus) and
 [RestClient](https://github.com/archiloque/rest-client), and so are easy to
 work with.
@@ -22,33 +12,243 @@ Via rubygems:
 
     gem install pp-adaptive
 
-## Setting up a Preapproval Agreement
+All API calls are made by calling `#execute` on the client, with the relevant
+request type. Naming conventions have been ruby-ized, but you should just
+follow along with the PayPal documentation to understand the inputs and outputs.
+
+Some aliases have been added, to make things simpler. Some example scenarios
+are outlined below, but due to the size of the API, this README does not aim
+in any way to be an exhaustive reproduction of the official Adaptive Payments
+documentation. Given the declarative, model-style, nature of the classes in
+this gem, it probably makes sense to just browse the source to know what
+fields are available.
+
+## Example API calls
+
+The following example should give you enough of an idea to be able to
+follow your senses and use this gem in your own applications.
+
+### Taking a regular payment
+
+A typical checkout payment request starts like this.
 
 ``` ruby
-    require 'pp-adaptive'
-    
-    client = AdaptivePayments::Client.new(
-      :user_id       => "your-api-user-id",
-      :password      => "your-api-password",
-      :signature     => "your-api-signature",
-      :app_id        => "your-app-id",
-      :sandbox       => false
-    )
-
-    response = client.execute(AdaptivePayments::PreapprovalRequest.new(
-      :ending_date      => DateTime.now.next_year,
-      :starting_date    => DateTime.now,
-      :max_total_amount => BigDecimal("950.00"),
-      :currency_code    => "USD",
-      :cancel_url       => "http://site.com/cancelled",
-      :return_url       => "http://site.com/completed"
-    ))
-    
-    if response.success?
-      puts "Preapproval key: #{response.preapproval_key}"
-    else
-      puts "#{response.ack_code}: #{response.error_message}"
-    end
+require "pp-adaptive"
+
+client = AdaptivePayments::Client.new(
+  :user_id       => "your-api-user-id",
+  :password      => "your-api-password",
+  :signature     => "your-api-signature",
+  :app_id        => "your-app-id",
+  :sandbox       => true
+)
+
+client.execute(:Pay,
+  :action_type     => "PAY",
+  :receiver_email  => "your@email.com",
+  :receiver_amount => 50,
+  :currency_code   => "USD",
+  :cancel_url      => "https://your-site.com/cancel",
+  :return_url      => "https://your-site.com/return"
+) do |response|
+
+  if response.success?
+    puts "Pay key: #{response.pay_key}"
+
+    # send the user to PayPal to make the payment
+    # e.g. https://www.sandbox.paypal.com/webscr?cmd=_ap-payment&paykey=abc
+    redirect_to client.payment_url(response)
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+
+end
 ```
 
-(Work in progress...)
+### Checking the payment status on return
+
+When the customer is sent back from PayPal to your `return_url`, you need to
+check if the payment was successful or not.
+
+``` ruby
+require "pp-adaptive"
+
+client = AdaptivePayments::Client.new(
+  :user_id       => "your-api-user-id",
+  :password      => "your-api-password",
+  :signature     => "your-api-signature",
+  :app_id        => "your-app-id",
+  :sandbox       => true
+)
+
+client.execute(:PaymentDetails, :pay_key => "pay-key-from-pay-request") do |response|
+  if response.success?
+    puts "Payment status: #{response.payment_exec_status}"
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+end
+```
+
+### Initiating a chained payment
+
+If you need to take a cut of a payment and forward the remainder onto one
+or more other recipients, you use a chained payment. This is just a regular
+PayRequest, except it includes multiple receivers, one of which is marked as
+'primary'.
+
+``` ruby
+require "pp-adaptive"
+
+client = AdaptivePayments::Client.new(
+  :user_id       => "your-api-user-id",
+  :password      => "your-api-password",
+  :signature     => "your-api-signature",
+  :app_id        => "your-app-id",
+  :sandbox       => true
+)
+
+client.execute(:Pay,
+  :action_type     => "PAY",
+  :currency_code   => "USD",
+  :cancel_url      => "https://your-site.com/cancel",
+  :return_url      => "https://your-site.com/return",
+  :receivers       => [
+    { :email => "your@email.com", :amount => 50, :primary => true },
+    { :email => "other@site.tld", :amount => 45 }
+  ]
+) do |response|
+
+  if response.success?
+    puts "Pay key: #{response.pay_key}"
+
+    # send the user to PayPal to make the payment
+    # e.g. https://www.sandbox.paypal.com/webscr?cmd=_ap-payment&paykey=abc
+    redirect_to client.payment_url(response)
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+
+end
+```
+
+In the above example, you get $5 from the $50 payment, with the remaining $45
+going to other@site.tld.
+
+### Setting up a Preapproval Agreement
+
+If you need to be able to take payments from a user's account on-demand, you
+get the user to authorize you for preapproved payments.
+
+``` ruby
+require "pp-adaptive"
+
+client = AdaptivePayments::Client.new(
+  :user_id       => "your-api-user-id",
+  :password      => "your-api-password",
+  :signature     => "your-api-signature",
+  :app_id        => "your-app-id",
+  :sandbox       => false
+)
+
+client.execute(:Preapproval,
+  :ending_date      => DateTime.now.next_year,
+  :starting_date    => DateTime.now,
+  :max_total_amount => BigDecimal("950.00"),
+  :currency_code    => "USD",
+  :cancel_url       => "http://site.com/cancelled",
+  :return_url       => "http://site.com/completed"
+) do |response|
+  # you may alternatively pass a PreapprovalRequest instance
+
+  if response.success?
+    puts "Preapproval key: #{response.preapproval_key}"
+
+    # send the user to PayPal to give their approval
+    # e.g. https://www.paypal.com/webscr?cmd=_ap-preapproval&preapprovalkey=abc
+    redirect_to client.preapproval_url(response)
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+
+end
+```
+
+### Taking a payment using an existing Preapproval
+
+To take a payment from a user who has previously authorized you for preapproved
+payments, just pass the `pay_key` in the usual PayRequest.
+
+``` ruby
+require "pp-adaptive"
+
+client = AdaptivePayments::Client.new(
+  :user_id       => "your-api-user-id",
+  :password      => "your-api-password",
+  :signature     => "your-api-signature",
+  :app_id        => "your-app-id",
+  :sandbox       => false
+)
+
+client.execute(:Pay,
+  :preapproval_key => "existing-preapproval-key",
+  :action_type     => "PAY",
+  :receiver_email  => "your@email.com",
+  :receiver_amount => 50,
+  :currency_code   => "USD",
+  :cancel_url      => "https://your-site.com/cancel",
+  :return_url      => "https://your-site.com/return"
+) do |response|
+
+  if response.success?
+    puts "Pay key: #{response.pay_key}"
+    puts "Status: #{response.payment_exec_status}"
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+
+end
+```
+
+### Issuing a refund
+
+If you have the pay_key from a previously made payment (up to 60 days), you
+can send a RefundRequest.
+
+``` ruby
+require "pp-adaptive"
+
+client = AdaptivePayments::Client.new(
+  :user_id       => "your-api-user-id",
+  :password      => "your-api-password",
+  :signature     => "your-api-signature",
+  :app_id        => "your-app-id",
+  :sandbox       => false
+)
+
+client.execute(:Refund, :pay_key => "the-pay-key") do |response|
+  if response.success?
+    puts "Refund sent"
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+end
+```
+
+You can also do partial refunds by passing an `amount` field in the request.
+
+### Other API calls
+
+Adaptive Payments is a very extensive API with a lot of endpoints and a lot
+of fields within each request. It wouldn't be wise to attempt to document them
+all here, but the official API documentation covers everything in detail.
+
+https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_AdaptivePayments.pdf
+
+Just ruby-ize the fields (i.e. underscores, not camel case) and open up the
+request/response classes in this repository to get a feel for how this all works.
+
+## License & Copyright
+
+Copyright © Flippa.com Pty Ltd. Licensed under the MIT license. See the
+LICENSE file for details.

data/lib/pp-adaptive/abstract_request.rb

@@ -28,6 +28,17 @@ module AdaptivePayments
         @operation
       end
 
+      # Get the request class for the given operation.
+      #
+      # @param [Symbol] operation
+      #   the name of the operation
+      #
+      # @return [AbstractRequest]
+      #   the request subclass
+      def for_operation(name)
+        AdaptivePayments.const_get(name.to_s + "Request")
+      end
+
       # Given a JSON string, return the corresponding response.
       #
       # @param [String] json

data/lib/pp-adaptive/client.rb

@@ -2,6 +2,7 @@ require "rest-client"
 require "virtus"
 
 module AdaptivePayments
+  # The principle hub through which all requests and responses are passed.
   class Client
     include Virtus
 
@@ -11,45 +12,135 @@ module AdaptivePayments
     attribute :app_id,    String, :header => "X-PAYPAL-APPLICATION-ID"
     attribute :device_ip, String, :header => "X-PAYPAL-DEVICE-IPADDRESS"
 
+    # Initialize the client with the given options.
+    #
+    # Options can also be passed via the accessors, if prefered.
+    #
+    # @option [String] user_id
+    #   the adaptive payments API user id
+    #
+    # @option [String] password
+    #   the adaptive payments API password
+    #
+    # @option [String] signature
+    #   the adaptive payments API signature
+    #
+    # @option [String] app_id
+    #   the app ID given to use adaptive payments
+    #
+    # @option [String] device_ip
+    #   the IP address of the user, optional
+    #
+    # @option [Boolean] sandbox
+    #   true if using the sandbox, not production
     def initialize(options = {})
       super
       self.sandbox = options[:sandbox]
     end
 
+    # Turn on/off sandbox mode.
     def sandbox=(flag)
       @sandbox = !!flag
     end
 
+    # Test if the client is using the sandbox.
+    #
+    # @return [Boolean]
+    #   true if using the sandbox
     def sandbox?
       !!@sandbox
     end
 
-    def execute(request)
-      base_url = if sandbox?
-        "https://svcs.sandbox.paypal.com/AdaptivePayments"
-      else
-        "https://svcs.paypal.com/AdaptivePayments"
-      end
+    # Execute a Request.
+    #
+    # @example
+    #   response = client.execute(:Refund, pay_key: "abc", amount: 42)
+    #   puts response.ack_code
+    #
+    # @params [Symbol] operation_name
+    #   The name of the operation to perform.
+    #   This maps with the name of the Request class.
+    #
+    # @params [Hash] attributes
+    #   attributes used to build the request
+    #
+    # @return [AbstractResponse]
+    #   a response object for the given operation
+    #
+    # @yield [AbstractResponse]
+    #   optional way to receive the return value
+    def execute(*args)
+      request =
+        case args.size
+        when 1 then args[0]
+        when 2 then AbstractRequest.for_operation(args[0]).new(args[1])
+        else
+          raise ArgumentError, "Invalid arguments: #{args.size} for (1..2)"
+        end
 
-      resource = RestClient::Resource.new(base_url, :headers => headers)
+      resource = RestClient::Resource.new(api_url, :headers => headers)
       response = resource[request.class.operation.to_s].post(
         request.to_json,
         :content_type => :json,
         :accept       => :json
       )
-      request.class.build_response(response)
+      request.class.build_response(response).tap do |res|
+        yield res if block_given?
+      end
+    rescue RestClient::Exception => e
+      raise AdaptivePayments::Exception, e
+    end
+
+    # When initiating a preapproval, get the URL on paypal.com to send the user to.
+    #
+    # @param [PreapprovalResponse] response
+    #   the response when setting up the preapproval
+    #
+    # @return [String]
+    #   the URL on paypal.com to send the user to
+    def preapproval_url(response)
+      [
+        "https://www.",
+        ("sandbox." if sandbox?),
+        "paypal.com/webscr?cmd=_ap-preapproval&preapprovalkey=",
+        response.preapproval_key
+      ].join
+    end
+
+    # When initiating a payment, get the URL on paypal.com to send the user to.
+    #
+    # @param [PayResponse] response
+    #   the response when setting up the payment
+    #
+    # @return [String]
+    #   the URL on paypal.com to send the user to
+    def payment_url(response)
+      [
+        "https://www.",
+        ("sandbox." if sandbox?),
+        "paypal.com/webscr?cmd=_ap-payment&paykey=",
+        response.preapproval_key
+      ].join
     end
 
     private
 
+    def api_url
+      [
+        "https://svcs.",
+        ("sandbox." if sandbox?),
+        "paypal.com/AdaptivePayments"
+      ].join
+    end
+
     def headers
       base_headers = {
         "X-PAYPAL-RESPONSE-DATA-FORMAT" => "JSON",
         "X-PAYPAL-REQUEST-DATA-FORMAT"  => "JSON"
       }
-      attributes.inject(base_headers) do |hash, (attr, value)|
-        next hash if value.nil?
-        hash.merge(self.class.attributes[attr].options[:header] => value)
+      attribute_set.inject(base_headers) do |hash, attr|
+        next hash if self[attr.name].nil?
+        hash.merge(attr.options[:header] => self[attr.name])
       end
     end
   end

data/lib/pp-adaptive/exception.rb

@@ -0,0 +1,4 @@
+module AdaptivePayments
+  class Exception < RuntimeError
+  end
+end

data/lib/pp-adaptive/support/json_model.rb

@@ -74,11 +74,11 @@ module AdaptivePayments
       private
 
       def attribute_key(key)
-        Hash[attributes.map { |attr| [attr.options.fetch(:param, attr.name).to_s, attr.name.to_sym] }][key] || key.to_sym
+        Hash[attribute_set.map { |attr| [attr.options.fetch(:param, attr.name).to_s, attr.name.to_sym] }][key] || key.to_sym
       end
 
       def attribute_value(key, value)
-        return unless attribute = attributes[attribute_key(key)]
+        return unless attribute = attribute_set[attribute_key(key)]
 
         case attribute
           when Node
@@ -98,8 +98,9 @@ module AdaptivePayments
       # @return [Hash]
       #   the JSON representation in ruby Hash form
       def to_hash
-        attributes.inject({}) { |hash, (key, value)| value.nil? ? hash : hash.merge(json_key(key) => json_value(value)) } \
-          .reject { |key, value| value.kind_of?(Enumerable) && value.none? }
+        Hash[attribute_set.map{ |a| [a.name, self[a.name]] }].
+          inject({}) { |hash, (key, value)| value.nil? ? hash : hash.merge(json_key(key) => json_value(value)) }.
+          reject { |key, value| value.kind_of?(Enumerable) && value.none? }
       end
 
       # Convert this JsonModel into a JSON string for transport to the PayPal API
@@ -113,8 +114,8 @@ module AdaptivePayments
       private
 
       def json_key(key)
-        if self.class.attributes[key]
-          self.class.attributes[key].options.fetch(:param, key).to_s
+        if self.class.attribute_set[key]
+          self.class.attribute_set[key].options.fetch(:param, key).to_s
         else
           key.to_s
         end

data/lib/pp-adaptive/version.rb

@@ -1,3 +1,3 @@
 module AdaptivePayments
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/pp-adaptive.rb

@@ -1,5 +1,7 @@
 require "pp-adaptive/version"
 
+require "pp-adaptive/exception"
+
 require "pp-adaptive/support/aliases"
 require "pp-adaptive/support/json_model"
 require "pp-adaptive/support/coerced_array"

data/pp-adaptive.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.email       = ["chris@w3style.co.uk"]
   s.homepage    = "https://github.com/"
   s.summary     = %q{Rubygem for working with PayPal's Adaptive Payments API}
-  s.description = %q{Currently provides just a subset of PayPal's API, for setting up preapproval agreements and taking payments}
+  s.description = %q{Provides complete access to PayPal's Adaptive Payments API}
 
   s.rubyforge_project = "pp-adaptive"
 
@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_runtime_dependency     "rest-client"
-  s.add_runtime_dependency     "virtus",      ">= 0.0.9"
+  s.add_runtime_dependency     "virtus",      ">= 0.5.1"
   s.add_runtime_dependency     "json"
-  s.add_development_dependency "rspec",       ">= 2.6"
+  s.add_development_dependency "rspec",       ">= 2.10"
 end

data/spec/public/client_spec.rb

@@ -1,8 +1,8 @@
 require "spec_helper"
 
 describe AdaptivePayments::Client do
-  let(:rest_client)   { double(:post => nil).tap { |d| d.stub(:[] => d) } }
-  let(:request_class) { stub(:operation => :Test, :build_response => nil) }
+  let(:rest_client)   { double(:post => '{}').tap { |d| d.stub(:[] => d) } }
+  let(:request_class) { stub(:operation => :Refund, :build_response => nil) }
   let(:request)       { stub(:class => request_class, :to_json => '{}') }
   let(:client)        { AdaptivePayments::Client.new }
 
@@ -82,4 +82,16 @@ describe AdaptivePayments::Client do
     request_class.should_receive(:build_response).and_return(response)
     client.execute(request).should == response
   end
+
+  it "allows passing a Symbol + Hash instead of a full request object" do
+    client.execute(:Refund, {}).should be_a_kind_of(AdaptivePayments::RefundResponse)
+  end
+
+  it "yields the response object" do
+    response = stub(:response)
+    request_class.should_receive(:build_response).and_return(response)
+    ret_val = nil
+    client.execute(request) { |r| ret_val = r }
+    ret_val.should == response
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pp-adaptive
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-21 00:00:00.000000000 Z
+date: 2012-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &70143741610300 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,21 +21,31 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70143741610300
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: virtus
-  requirement: &70143741609800 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.0.9
+        version: 0.5.1
   type: :runtime
   prerelease: false
-  version_requirements: *70143741609800
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.1
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70143741609380 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,20 +53,29 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70143741609380
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70143741608840 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.10'
   type: :development
   prerelease: false
-  version_requirements: *70143741608840
-description: Currently provides just a subset of PayPal's API, for setting up preapproval
-  agreements and taking payments
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.10'
+description: Provides complete access to PayPal's Adaptive Payments API
 email:
 - chris@w3style.co.uk
 executables: []
@@ -76,6 +95,7 @@ files:
 - lib/pp-adaptive/client.rb
 - lib/pp-adaptive/convert_currency_request.rb
 - lib/pp-adaptive/convert_currency_response.rb
+- lib/pp-adaptive/exception.rb
 - lib/pp-adaptive/execute_payment_request.rb
 - lib/pp-adaptive/execute_payment_response.rb
 - lib/pp-adaptive/get_payment_options_request.rb
@@ -189,7 +209,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: pp-adaptive
-rubygems_version: 1.8.11
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Rubygem for working with PayPal's Adaptive Payments API