paypal-rest-api 0.0.3 → 0.1.0

data/lib/paypal-api/api_collections/webhooks.rb

@@ -46,7 +46,7 @@ module PaypalAPI
       # @macro request
       #
       def show(webhook_id, query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
+        client.get("/v1/notifications/webhooks/#{encode(webhook_id)}", query: query, body: body, headers: headers)
       end
 
       #
@@ -58,7 +58,7 @@ module PaypalAPI
       # @macro request
       #
       def update(webhook_id, query: nil, body: nil, headers: nil)
-        client.patch("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
+        client.patch("/v1/notifications/webhooks/#{encode(webhook_id)}", query: query, body: body, headers: headers)
       end
 
       #
@@ -70,7 +70,7 @@ module PaypalAPI
       # @macro request
       #
       def delete(webhook_id, query: nil, body: nil, headers: nil)
-        client.delete("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
+        client.delete("/v1/notifications/webhooks/#{encode(webhook_id)}", query: query, body: body, headers: headers)
       end
 
       #
@@ -81,54 +81,8 @@ module PaypalAPI
       # @param webhook_id [String] Webhook ID
       # @macro request
       #
-      def list_event_types(webhook_id, query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks/#{webhook_id}/event-types", query: query, body: body, headers: headers)
-      end
-
-      #
-      # Create webhook lookup
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-lookup_post
-      #
-      # @macro request
-      #
-      def create_lookup(query: nil, body: nil, headers: nil)
-        client.post("/v1/notifications/webhooks-lookup", query: query, body: body, headers: headers)
-      end
-
-      #
-      # List webhook lookups
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-lookup_list
-      #
-      # @macro request
-      #
-      def list_lookups(query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks-lookup", query: query, body: body, headers: headers)
-      end
-
-      #
-      # Show webhook lookup details
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-lookup_get
-      #
-      # @param webhook_lookup_id [String] Webhook lookup ID
-      # @macro request
-      #
-      def show_lookup(webhook_lookup_id, query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks-lookup/#{webhook_lookup_id}", query: query, body: body, headers: headers)
-      end
-
-      #
-      # Delete webhook lookup
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-lookup_delete
-      #
-      # @param webhook_lookup_id [String] Webhook lookup ID
-      # @macro request
-      #
-      def delete_lookup(webhook_lookup_id, query: nil, body: nil, headers: nil)
-        client.delete("/v1/notifications/webhooks-lookup/#{webhook_lookup_id}", query: query, body: body, headers: headers)
+      def event_types(webhook_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks/#{encode(webhook_id)}/event-types", query: query, body: body, headers: headers)
       end
 
       #
@@ -141,63 +95,6 @@ module PaypalAPI
       def verify(query: nil, body: nil, headers: nil)
         client.post("/v1/notifications/verify-webhook-signature", query: query, body: body, headers: headers)
       end
-
-      #
-      # Lists available events to which any webhook can subscribe
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-event-types_list
-      #
-      # @macro request
-      #
-      def list_available_events(query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks-event-types", query: query, body: body, headers: headers)
-      end
-
-      #
-      # List event notifications
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-events_list
-      #
-      # @macro request
-      #
-      def list_events(query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks-events", query: query, body: body, headers: headers)
-      end
-
-      #
-      # Show event notification details
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-events_get
-      #
-      # @param event_id [String] Event ID
-      # @macro request
-      #
-      def show_event(event_id, query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks-events/#{event_id}", query: query, body: body, headers: headers)
-      end
-
-      #
-      # Resend event notification
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-events_resend
-      #
-      # @param event_id [String] Event ID
-      # @macro request
-      #
-      def resend_event(event_id, query: nil, body: nil, headers: nil)
-        client.post("/v1/notifications/webhooks-events/#{event_id}/resend", query: query, body: body, headers: headers)
-      end
-
-      #
-      # Simulate webhook event
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#simulate-event_post
-      #
-      # @macro request
-      #
-      def simulate_event(query: nil, body: nil, headers: nil)
-        client.post("/v1/notifications/simulate-event", query: query, body: body, headers: headers)
-      end
     end
 
     include APIs

data/lib/paypal-api/client.rb

@@ -5,9 +5,10 @@ module PaypalAPI
   # PaypalAPI Client
   #
   class Client
-    attr_reader :config
+    attr_reader :config, :callbacks
 
     # Initializes Client
+    # @api public
     #
     # @param client_id [String] PayPal client id
     # @param client_secret [String] PayPal client secret
@@ -17,18 +18,49 @@ module PaypalAPI
     #
     # @return [Client] Initialized client
     #
-    def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil)
+    def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil, cache: nil)
       @config = PaypalAPI::Config.new(
         client_id: client_id,
         client_secret: client_secret,
         live: live,
         http_opts: http_opts,
-        retries: retries
+        retries: retries,
+        cache: cache
       )
 
+      @callbacks = {
+        before: [],
+        after_success: [],
+        after_fail: [],
+        after_network_error: []
+      }.freeze
+
       @access_token = nil
     end
 
+    # Registers callback
+    #
+    # @param callback_name [Symbol] Callback name.
+    #   Allowed values: :before, :after_success, :after_faile, :after_network_error
+    #
+    # @param block [Proc] Block that must be call
+    #   For `:before` callback proc should accept 2 params -
+    #    request [Request], context [Hash]
+    #
+    #   For `:after_success` callback proc should accept 3 params -
+    #     request [Request], context [Hash], response [Response]
+    #
+    #   For `:after_fail` callback proc should accept 3 params -
+    #     request [Request], context [Hash], error [StandardError]
+    #
+    #   For `:after_network_error` callback proc should accept 3 params -
+    #     request [Request], context [Hash], response [Response]
+    #
+    # @return [void]
+    def add_callback(callback_name, &block)
+      callbacks.fetch(callback_name) << block
+    end
+
     #
     # Checks cached access token is expired and returns it or generates new one
     #
@@ -44,16 +76,48 @@ module PaypalAPI
     # @return [AccessToken] new AccessToken object
     #
     def refresh_access_token
+      requested_at = Time.now
       response = authentication.generate_access_token
 
       @access_token = AccessToken.new(
-        requested_at: response.requested_at,
+        requested_at: requested_at,
         expires_in: response.fetch(:expires_in),
         access_token: response.fetch(:access_token),
         token_type: response.fetch(:token_type)
       )
     end
 
+    #
+    # Verifies Webhook
+    # It requires one-time request to download and cache certificate.
+    # If local verification returns false it tries to verify webhook online.
+    #
+    # @api public
+    # @example
+    #
+    #  class Webhooks::PaypalController < ApplicationController
+    #    def create
+    #      webhook_id = ENV['PAYPAL_WEBHOOK_ID'] # PayPal registered webhook ID for current URL
+    #      headers = request.headers # must be a Hash
+    #      body = request.raw_post # must be a raw String body
+    #
+    #      webhook_is_valid = PaypalAPI.verify_webhook(webhook_id: webhook_id, headers: headers, body: body)
+    #      webhook_is_valid ? handle_webhook_event(body) : log_error(webhook_id, headers, body)
+    #
+    #      head :no_content
+    #    end
+    #  end
+    #
+    # @param webhook_id [String] webhook_id provided by PayPal when webhook was registered
+    # @param headers [Hash,#[]] webhook request headers
+    # @param raw_body [String] webhook request raw body string
+    #
+    # @return [Boolean] webhook event is valid
+    #
+    def verify_webhook(webhook_id:, headers:, raw_body:)
+      WebhookVerifier.new(self).call(webhook_id: webhook_id, headers: headers, raw_body: raw_body)
+    end
+
     # @!macro [new] request
     # @param path [String] Request path
     # @param query [Hash, nil] Request query parameters
@@ -127,16 +191,51 @@ module PaypalAPI
       CatalogProducts.new(self)
     end
 
+    # @return [Disputes] Disputes APIs collection
+    def disputes
+      Disputes.new(self)
+    end
+
+    # @return [InvoiceTemplates] InvoiceTemplates APIs collection
+    def invoice_templates
+      InvoiceTemplates.new(self)
+    end
+
+    # @return [Invoices] Invoices APIs collection
+    def invoices
+      Invoices.new(self)
+    end
+
     # @return [Orders] Orders APIs collection
     def orders
       Orders.new(self)
     end
 
+    # @return [PayoutItems] PayoutItems APIs collection
+    def payout_items
+      PayoutItems.new(self)
+    end
+
+    # @return [Payouts] Payouts APIs collection
+    def payouts
+      Payouts.new(self)
+    end
+
     # @return [Redunds] Refunds APIs collection
     def refunds
       Refunds.new(self)
     end
 
+    # @return [ReferencedPayoutItems] ReferencedPayoutItems APIs collection
+    def referenced_payout_items
+      ReferencedPayoutItems.new(self)
+    end
+
+    # @return [ReferencedPayouts] ReferencedPayouts APIs collection
+    def referenced_payouts
+      ReferencedPayouts.new(self)
+    end
+
     # @return [ShipmentTracking] Shipment Tracking APIs collection
     def shipment_tracking
       ShipmentTracking.new(self)
@@ -147,16 +246,41 @@ module PaypalAPI
       Subscriptions.new(self)
     end
 
+    # @return [SubscriptionPlans] Subscription Plans APIs collection
+    def subscription_plans
+      SubscriptionPlans.new(self)
+    end
+
+    # @return [UserInfo] User Info APIs collection
+    def user_info
+      UserInfo.new(self)
+    end
+
+    # @return [Users] Users Management APIs collection
+    def users
+      Users.new(self)
+    end
+
     # @return [Webhooks] Webhooks APIs collection
     def webhooks
       Webhooks.new(self)
     end
 
+    # @return [WebhookEvents] Webhook Events APIs collection
+    def webhook_lookups
+      WebhookLookups.new(self)
+    end
+
+    # @return [WebhookEvents] Webhook Lookups APIs collection
+    def webhook_events
+      WebhookEvents.new(self)
+    end
+
     private
 
     def execute_request(http_method, path, query: nil, body: nil, headers: nil)
       request = Request.new(self, http_method, path, query: query, body: body, headers: headers)
-      RequestExecutor.call(request)
+      RequestExecutor.new(self, request).call
     end
   end
 end

data/lib/paypal-api/config.rb

@@ -18,7 +18,7 @@ module PaypalAPI
       retries: {enabled: true, count: 3, sleep: [0.25, 0.75, 1.5].freeze}.freeze
     }.freeze
 
-    attr_reader :client_id, :client_secret, :live, :http_opts, :retries
+    attr_reader :client_id, :client_secret, :live, :http_opts, :retries, :certs_cache
 
     # Initializes Config
     #
@@ -27,15 +27,19 @@ module PaypalAPI
     # @param live [Boolean] PayPal live/sandbox mode
     # @param http_opts [Hash] Net::Http opts for all requests
     # @param retries [Hash] Retries configuration
+    # @param cache [#read, nil] Application cache to store certificates to validate webhook events locally.
+    #   Must respond to #read(key) and #write(key, expires_in: Integer)
     #
     # @return [Client] Initialized config object
     #
-    def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil)
+    def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil, cache: nil)
       @client_id = client_id
       @client_secret = client_secret
       @live = with_default(:live, live)
       @http_opts = with_default(:http_opts, http_opts)
       @retries = with_default(:retries, retries)
+      @certs_cache = WebhookVerifier::CertsCache.new(cache)
+
       freeze
     end
 

data/lib/paypal-api/request.rb

@@ -19,8 +19,8 @@ module PaypalAPI
     # @return [Net::HTTPRequest] Generated Net::HTTPRequest
     attr_reader :http_request
 
-    # @return [Time, nil] Time when request was sent
-    attr_accessor :requested_at
+    # @return [Hash, nil, Object] Custom context that can be set/changed in callbacks
+    attr_accessor :context
 
     # rubocop:disable Metrics/ParameterLists
 
@@ -40,48 +40,80 @@ module PaypalAPI
     def initialize(client, request_type, path, body: nil, query: nil, headers: nil)
       @client = client
       @http_request = build_http_request(request_type, path, body: body, query: query, headers: headers)
-      @requested_at = nil
+      @context = nil
     end
     # rubocop:enable Metrics/ParameterLists
 
+    # @return [String] HTTP request method name
+    def method
+      http_request.method
+    end
+
+    # @return [String] HTTP request method name
+    def path
+      http_request.path
+    end
+
+    # @return [URI] HTTP request URI
+    def uri
+      http_request.uri
+    end
+
+    # @return [String] HTTP request body
+    def body
+      http_request.body
+    end
+
+    # @return [Hash] HTTP request headers
+    def headers
+      http_request.each_header.to_h
+    end
+
     private
 
     def build_http_request(request_type, path, body:, query:, headers:)
-      uri = request_uri(path, query)
-      http_request = request_type.new(uri)
+      uri = build_http_uri(path, query)
+      http_request = request_type.new(uri, "accept-encoding" => nil)
 
-      add_headers(http_request, headers || {})
-      add_body(http_request, body)
+      build_http_headers(http_request, body, headers || {})
+      build_http_body(http_request, body)
 
       http_request
     end
 
-    def add_headers(http_request, headers)
-      headers.each { |key, value| http_request[key] = value }
+    def build_http_headers(http_request, body, headers)
+      headers = normalize_headers(headers)
+
+      unless headers.key?("authorization")
+        http_request["authorization"] = client.access_token.authorization_string
+      end
+
+      unless headers.key?("content-type")
+        http_request["content-type"] = "application/json" if body
+      end
 
-      http_request["content-type"] ||= "application/json"
-      http_request["authorization"] ||= client.access_token.authorization_string
-      http_request["paypal-request-id"] ||= SecureRandom.uuid if idempotent?(http_request)
+      unless headers.key?("paypal-request-id")
+        http_request["paypal-request-id"] = SecureRandom.uuid unless http_request.is_a?(Net::HTTP::Get)
+      end
+
+      headers.each { |key, value| http_request[key] = value }
     end
 
-    def add_body(http_request, body)
+    def build_http_body(http_request, body)
       return unless body
 
-      json?(http_request) ? http_request.body = JSON.dump(body) : http_request.set_form_data(body)
+      is_json = http_request["content-type"].include?("json")
+      is_json ? http_request.body = JSON.dump(body) : http_request.set_form_data(body)
     end
 
-    def request_uri(path, query)
+    def build_http_uri(path, query)
       uri = URI.join(client.config.url, path)
       uri.query = URI.encode_www_form(query) if query && !query.empty?
       uri
     end
 
-    def idempotent?(http_request)
-      http_request.method != Net::HTTP::Get::METHOD
-    end
-
-    def json?(http_request)
-      http_request["content-type"].include?("json")
+    def normalize_headers(headers)
+      headers.empty? ? headers : headers.transform_keys { |key| key.to_s.downcase }
     end
   end
 end

data/lib/paypal-api/request_executor.rb

@@ -5,91 +5,106 @@ module PaypalAPI
   # Executes PaypalAPI::Request and returns PaypalAPI::Response or raises PaypalAPI::Error
   #
   class RequestExecutor
-    # List of Net::HTTP responses that must be retried
-    RETRYABLE_RESPONSES = [
-      Net::HTTPServerError,    # 5xx
-      Net::HTTPConflict,       # 409
-      Net::HTTPTooManyRequests # 429
-    ].freeze
-
-    class << self
-      #
-      # Executes prepared Request, handles retries and preparation of errors
-      #
-      # @param [Request] request
-      #
-      # @return [Response] Response
-      #
-      def call(request)
-        http_response = execute(request)
-        response = Response.new(http_response, requested_at: request.requested_at)
-        raise FailedRequestErrorBuilder.call(request: request, response: response) unless http_response.is_a?(Net::HTTPSuccess)
+    attr_reader :client, :request, :http_opts, :context, :retries, :callbacks, :callbacks_context
+
+    def initialize(client, request)
+      @client = client
+      @request = request
+      @http_opts = {use_ssl: request.uri.is_a?(URI::HTTPS), **client.config.http_opts}
+      @retries = client.config.retries
+      @callbacks = client.callbacks
+      @callbacks_context = {retries_count: retries[:count]}
+    end
 
-        response
-      end
+    #
+    # Executes prepared Request, handles retries and preparation of errors
+    #
+    # @return [Response] Response
+    #
+    def call
+      response = execute_request
+      raise FailedRequestErrorBuilder.call(request: request, response: response) if response.failed?
+
+      response
+    end
+
+    private
 
-      private
+    def execute_request(retry_number: 0)
+      callbacks_context[:retry_number] = retry_number
 
-      def execute(request, retry_number: 0)
-        http_response = execute_http_request(request)
-      rescue *NetworkErrorBuilder::ERRORS => error
-        retry_on_network_error(request, error, retry_number)
+      run_callbacks(:before)
+      response = execute_net_http_request
+    rescue *NetworkErrorBuilder::ERRORS => error
+      will_retry = !retries_limit_reached?(retry_number)
+      callbacks_context[:will_retry] = will_retry
+      run_callbacks(:after_network_error, error)
+      raise NetworkErrorBuilder.call(request: request, error: error) unless will_retry
+
+      retry_request(retry_number)
+    else
+      if response.success?
+        callbacks_context.delete(:will_retry)
+        run_callbacks(:after_success, response)
+        response
       else
-        retryable?(request, http_response, retry_number) ? retry_request(request, retry_number) : http_response
+        will_retry = retryable?(response, retry_number)
+        callbacks_context[:will_retry] = will_retry
+        run_callbacks(:after_fail, response)
+        will_retry ? retry_request(retry_number) : response
       end
+    end
 
-      def execute_http_request(request)
-        http_request = request.http_request
-        http_opts = request.client.config.http_opts
-        uri = http_request.uri
-        request.requested_at = Time.now
+    def execute_net_http_request
+      uri = request.uri
 
-        Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, **http_opts) do |http|
+      http_response =
+        Net::HTTP.start(uri.hostname, uri.port, **http_opts) do |http|
           http.max_retries = 0 # we have custom retries logic
-          http.request(http_request)
+          http.request(request.http_request)
         end
-      end
 
-      def retry_on_network_error(request, error, retry_number)
-        raise NetworkErrorBuilder.call(request: request, error: error) if retries_limit_reached?(request, retry_number)
+      Response.new(http_response, request: request)
+    end
 
-        retry_request(request, retry_number)
-      end
+    def retry_request(current_retry_number)
+      sleep_time = retry_sleep_seconds(current_retry_number)
+      sleep(sleep_time) if sleep_time.positive?
+      execute_request(retry_number: current_retry_number + 1)
+    end
 
-      def retry_request(request, current_retry_number)
-        sleep(retry_sleep_seconds(request, current_retry_number))
-        execute(request, retry_number: current_retry_number + 1)
-      end
+    def retries_limit_reached?(retry_number)
+      retry_number >= retries[:count]
+    end
 
-      def retries_limit_reached?(request, retry_number)
-        retry_number >= request.client.config.retries[:count]
-      end
+    def retry_sleep_seconds(current_retry_number)
+      seconds_per_retry = retries[:sleep]
+      seconds_per_retry[current_retry_number] || seconds_per_retry.last || 1
+    end
 
-      def retry_sleep_seconds(request, current_retry_number)
-        seconds_per_retry = request.client.config.retries[:sleep]
-        seconds_per_retry[current_retry_number] || seconds_per_retry.last || 1
-      end
+    def retryable?(response, retry_number)
+      response.failed? &&
+        !retries_limit_reached?(retry_number) &&
+        retryable_request?(response)
+    end
 
-      def retryable?(request, http_response, retry_number)
-        !http_response.is_a?(Net::HTTPSuccess) &&
-          !retries_limit_reached?(request, retry_number) &&
-          retryable_request?(request, http_response)
-      end
+    def retryable_request?(response)
+      return true if response.retryable?
 
-      def retryable_request?(request, http_response)
-        return true if RETRYABLE_RESPONSES.any? { |retryable_class| http_response.is_a?(retryable_class) }
+      retry_unauthorized?(response)
+    end
 
-        retry_unauthorized?(request, http_response)
-      end
+    def retry_unauthorized?(response)
+      return false unless response.unauthorized? # 401
+      return false if request.path == Authentication::PATH # it's already an Authentication request
 
-      def retry_unauthorized?(request, http_response)
-        return false unless http_response.is_a?(Net::HTTPUnauthorized) # 401
-        return false if http_response.uri.path == Authentication::PATH # it's already an Authentication request
+      # set new access-token
+      request.http_request["authorization"] = client.refresh_access_token.authorization_string
+      true
+    end
 
-        # set new access-token
-        request.http_request["authorization"] = request.client.refresh_access_token.authorization_string
-        true
-      end
+    def run_callbacks(callback_name, resp = nil)
+      callbacks[callback_name].each { |callback| callback.call(request, context, resp) }
     end
   end
 end