paypal-rest-api 0.0.3 → 0.1.0

data/lib/paypal-api/response.rb

@@ -7,22 +7,29 @@ module PaypalAPI
   # PaypalAPI::Response object
   #
   class Response
+    # List of Net::HTTP responses that can be retried
+    RETRYABLE_RESPONSES = [
+      Net::HTTPServerError,    # 5xx
+      Net::HTTPConflict,       # 409
+      Net::HTTPTooManyRequests # 429
+    ].freeze
+
     # @return [Net::HTTP::Response] Original Net::HTTP::Response object
     attr_reader :http_response
 
-    # @return [Time] Time when request was sent
-    attr_reader :requested_at
+    # @return [Request] Request object
+    attr_reader :request
 
     #
     # Initializes Response object
     #
     # @param http_response [Net::HTTP::Response] original response
-    # @param requested_at [Time] Time when original response was requested
+    # @param request [Request] Request that generates this response
     #
     # @return [Response] Initialized Response object
     #
-    def initialize(http_response, requested_at:)
-      @requested_at = requested_at
+    def initialize(http_response, request:)
+      @request = request
       @http_response = http_response
       @http_status = nil
       @http_headers = nil
@@ -64,6 +71,36 @@ module PaypalAPI
       data.fetch(key.to_sym)
     end
 
+    # Checks http status code is 2xx
+    #
+    # @return [Boolean] Returns true if response has success status code (2xx)
+    def success?
+      http_response.is_a?(Net::HTTPSuccess)
+    end
+
+    # Checks http status code is not 2xx
+    #
+    # @return [Boolean] Returns true if response has not success status code
+    def failed?
+      !success?
+    end
+
+    # Checks if response status code is retriable (5xx, 409, 429)
+    # @api private
+    #
+    # @return [Boolean] Returns true if status code is retriable (5xx, 409, 429)
+    def retryable?
+      failed? && RETRYABLE_RESPONSES.any? { |retryable_class| http_response.is_a?(retryable_class) }
+    end
+
+    # Checks if response status code is unauthorized (401)
+    # @api private
+    #
+    # @return [Boolean] Returns true if status code is retriable (5xx, 409, 429)
+    def unauthorized?
+      http_response.is_a?(Net::HTTPUnauthorized)
+    end
+
     #
     # Instance representation string. Default was overwritten to hide secrets
     #

data/lib/paypal-api/webhook_verifier/certs_cache.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  class WebhookVerifier
+    #
+    # Stores certifiactes in-memory.
+    #
+    # New values are added to this in-memory cache and application cache.
+    # When fetching value it firstly looks to the memory cache and then to the app cache.
+    #
+    # @api private
+    #
+    class CertsCache
+      # Current application cache
+      # @api private
+      attr_reader :app_cache
+
+      # Hash storage of certificate public keys
+      # @api private
+      attr_reader :storage
+
+      # Initializes certificates cache
+      #
+      # @param app_cache [#fetch, nil] Application cache that can store
+      #   certificates between redeploys
+      #
+      # @return [CertsCache]
+      def initialize(app_cache)
+        @app_cache = app_cache || NullCache
+        @storage = {}
+      end
+
+      # Fetches value from cache
+      #
+      # @param key [String] Cache key
+      # @param block [Proc] Proc to fetch certificate text
+      #
+      # @return [OpenSSL::PKey::PKey] Certificate Public Key
+      def fetch(key, &block)
+        openssl_pub_key = read(key)
+        return openssl_pub_key if openssl_pub_key
+
+        cert_string = app_cache.fetch(key, &block)
+        cert = OpenSSL::X509::Certificate.new(cert_string)
+
+        write(key, cert.public_key)
+      end
+
+      private
+
+      def write(key, value)
+        storage[key] = value
+      end
+
+      def read(key)
+        storage[key]
+      end
+    end
+
+    #
+    # Null-object cache class.
+    # Implements only #read and #write method.
+    #
+    # @api private
+    #
+    class NullCache
+      # Just calls provided block
+      # @param _key [String] Cache key
+      # @return [String] block result
+      def self.fetch(_key)
+        yield
+      end
+    end
+  end
+end

data/lib/paypal-api/webhook_verifier.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module PaypalAPI
+  #
+  # Webhook Verifier
+  # @api private
+  #
+  class WebhookVerifier
+    # Error that can happen when verifying webhook when some required headers are missing
+    class MissingHeader < StandardError
+    end
+
+    # @return [Client] current client
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Verifies Webhook.
+    #
+    # It requires one-time request to download and cache certificate.
+    # If local verification returns false it tries to verify webhook online.
+    #
+    # @param webhook_id [String] Webhook ID provided by PayPal when registering webhook for your URL
+    # @param headers [Hash] webhook request headers
+    # @param raw_body [String] webhook request raw body string
+    #
+    # @return [Boolean]
+    def call(webhook_id:, headers:, raw_body:)
+      args = {
+        webhook_id: webhook_id,
+        raw_body: raw_body,
+        auth_algo: paypal_auth_algo(headers),
+        transmission_sig: paypal_transmission_sig(headers),
+        transmission_id: paypal_transmission_id(headers),
+        transmission_time: paypal_transmission_time(headers),
+        cert_url: paypal_cert_url(headers)
+      }
+
+      offline(**args) || online(**args)
+    end
+
+    private
+
+    def offline(webhook_id:, auth_algo:, transmission_sig:, transmission_id:, transmission_time:, cert_url:, raw_body:)
+      return false unless auth_algo.downcase.start_with?("sha256")
+
+      signature = paypal_signature(transmission_sig)
+      checked_data = "#{transmission_id}|#{transmission_time}|#{webhook_id}|#{Zlib.crc32(raw_body)}"
+      openssl_pub_key = download_and_cache_certificate(cert_url)
+
+      digest = OpenSSL::Digest.new("sha256", signature)
+      openssl_pub_key.verify(digest, signature, checked_data)
+    end
+
+    def online(webhook_id:, auth_algo:, transmission_sig:, transmission_id:, transmission_time:, cert_url:, raw_body:)
+      body = {
+        webhook_id: webhook_id,
+        auth_algo: auth_algo,
+        cert_url: cert_url,
+        transmission_id: transmission_id,
+        transmission_sig: transmission_sig,
+        transmission_time: transmission_time,
+        webhook_event: JSON.parse(raw_body)
+      }
+
+      response = client.webhooks.verify(body: body)
+      response[:verification_status] == "SUCCESS"
+    end
+
+    def paypal_signature(transmission_sig)
+      transmission_sig.unpack1("m") # decode base64
+    end
+
+    def paypal_transmission_sig(headers)
+      headers["paypal-transmission-sig"] || (raise MissingHeader, "No `paypal-transmission-sig` header")
+    end
+
+    def paypal_transmission_id(headers)
+      headers["paypal-transmission-id"] || (raise MissingHeader, "No `paypal-transmission-id` header")
+    end
+
+    def paypal_transmission_time(headers)
+      headers["paypal-transmission-time"] || (raise MissingHeader, "No `paypal-transmission-time` header")
+    end
+
+    def paypal_cert_url(headers)
+      headers["paypal-cert-url"] || (raise MissingHeader, "No `paypal-cert-url` header")
+    end
+
+    def paypal_auth_algo(headers)
+      headers["paypal-auth-algo"] || (raise MissingHeader, "No `paypal-auth-algo` header")
+    end
+
+    def download_and_cache_certificate(cert_url)
+      client.config.certs_cache.fetch("PaypalRestAPI.certificate.#{cert_url}") do
+        client.get(cert_url, headers: {"authorization" => nil}).http_body
+      end
+    end
+  end
+end

data/lib/paypal-api.rb

@@ -3,25 +3,26 @@
 #
 # PaypalAPI is a main gem module.
 #
-# It can store global PaypalAPI::Client for easier access to APIs.
-#
-# @example Initializing new global client
-#   PaypalAPI.client = PaypalAPI::Client.new(
-#     client_id: ENV.fetch('PAYPAL_CLIENT_ID'),
-#     client_secret: ENV.fetch('PAYPAL_CLIENT_SECRET'),
-#     live: false
-#   )
-#
-#   # And then call any APIs without mentioning the client
-#   PaypalAPI::Webhooks.list # or PaypalAPI.webhooks.list
-#
 module PaypalAPI
   class << self
     # Sets client
+    # @api public
+    #
+    # @example Initializing new global client
+    #   PaypalAPI.client = PaypalAPI::Client.new(
+    #     client_id: ENV.fetch('PAYPAL_CLIENT_ID'),
+    #     client_secret: ENV.fetch('PAYPAL_CLIENT_SECRET'),
+    #     live: false
+    #   )
+    #
+    # @return [Client] PaypalAPI client
     attr_writer :client
 
     # @!macro [new] request
     #
+    #   @api public
+    #   @example
+    #     PaypalAPI.$0("/path1/path2", query: query, body: body, headers: headers)
     #   @param path [String] Request path
     #   @param query [Hash, nil] Request query parameters
     #   @param body [Hash, nil] Request body parameters
@@ -61,44 +62,133 @@ module PaypalAPI
       end
     end
 
+    #
+    # Verifies Webhook
+    #
+    # It requires one-time request to download and cache certificate.
+    # If local verification returns false it tries to verify webhook online.
+    #
+    # @see Client#verify_webhook
+    #
+    def verify_webhook(webhook_id:, headers:, raw_body:)
+      client.verify_webhook(webhook_id: webhook_id, headers: headers, raw_body: raw_body)
+    end
+
+    #
+    # @!macro [new] api_collection
+    #   $0 APIs collection
+    #   @api public
+    #   @example
+    #     PaypalAPI.$0
+    #
+
     #
     # @!method authentication
+    #   @macro api_collection
     #   @return [Authentication]
     #
     # @!method authorized_payments
+    #   @macro api_collection
     #   @return [AuthorizedPayments]
     #
     # @!method captured_payments
+    #   @macro api_collection
     #   @return [CapturedPayments]
     #
     # @!method catalog_products
+    #   @macro api_collection
     #   @return [CatalogProducts]
     #
+    # @!method disputes
+    #   @macro api_collection
+    #   @return [Disputes]
+    #
+    # @!method invoice_templates
+    #   @macro api_collection
+    #   @return [InvoiceTemplates]
+    #
+    # @!method invoices
+    #   @macro api_collection
+    #   @return [Invoices]
+    #
     # @!method orders
+    #   @macro api_collection
     #   @return [Orders]
     #
+    # @!method payout_items
+    #   @macro api_collection
+    #   @return [PayoutItems]
+    #
+    # @!method payouts
+    #   @macro api_collection
+    #   @return [Payouts]
+    #
     # @!method refunds
+    #   @macro api_collection
     #   @return [Refunds]
     #
+    # @!method referenced_payout_items
+    #   @macro api_collection
+    #   @return [ReferencedPayoutItems]
+    #
+    # @!method referenced_payouts
+    #   @macro api_collection
+    #   @return [ReferencedPayouts]
+    #
     # @!method shipment_tracking
+    #   @macro api_collection
     #   @return [ShipmentTracking]
     #
     # @!method subscriptions
+    #   @macro api_collection
     #   @return [Subscriptions]
     #
+    # @!method subscription_plans
+    #   @macro api_collection
+    #   @return [SubscriptionPlans]
+    #
+    # @!method user_info
+    #   @macro api_collection
+    #   @return [UserInfo]
+    #
+    # @!method users
+    #   @macro api_collection
+    #   @return [Users]
+    #
     # @!method webhooks
+    #   @macro api_collection
     #   @return [Webhooks]
     #
+    # @!method webhook_events
+    #   @macro api_collection
+    #   @return [WebhookEvents]
+    #
+    # @!method webhook_lookups
+    #   @macro api_collection
+    #   @return [WebhookLookups]
+    #
     %i[
       authentication
       authorized_payments
       captured_payments
       catalog_products
+      disputes
+      invoice_templates
+      invoices
       orders
+      payout_items
+      payouts
       refunds
+      referenced_payout_items
+      referenced_payouts
       shipment_tracking
       subscriptions
+      subscription_plans
+      user_info
+      users
       webhooks
+      webhook_events
+      webhook_lookups
     ].each do |method_name|
       define_method(method_name) do
         client.public_send(method_name)
@@ -106,6 +196,10 @@ module PaypalAPI
     end
 
     # Globally set Client object
+    # @api public
+    # @example
+    #   PaypalAPI.client
+    # @return [Client]
     def client
       raise "#{name}.client must be set" unless @client
 
@@ -124,12 +218,26 @@ require_relative "paypal-api/network_error_builder"
 require_relative "paypal-api/request"
 require_relative "paypal-api/request_executor"
 require_relative "paypal-api/response"
+require_relative "paypal-api/webhook_verifier"
+require_relative "paypal-api/webhook_verifier/certs_cache"
 require_relative "paypal-api/api_collections/authentication"
 require_relative "paypal-api/api_collections/authorized_payments"
 require_relative "paypal-api/api_collections/captured_payments"
 require_relative "paypal-api/api_collections/catalog_products"
+require_relative "paypal-api/api_collections/disputes"
+require_relative "paypal-api/api_collections/invoice_templates"
+require_relative "paypal-api/api_collections/invoices"
 require_relative "paypal-api/api_collections/orders"
+require_relative "paypal-api/api_collections/payout_items"
+require_relative "paypal-api/api_collections/payouts"
 require_relative "paypal-api/api_collections/refunds"
+require_relative "paypal-api/api_collections/referenced_payout_items"
+require_relative "paypal-api/api_collections/referenced_payouts"
 require_relative "paypal-api/api_collections/shipment_tracking"
 require_relative "paypal-api/api_collections/subscriptions"
+require_relative "paypal-api/api_collections/subscription_plans"
+require_relative "paypal-api/api_collections/user_info"
+require_relative "paypal-api/api_collections/users"
 require_relative "paypal-api/api_collections/webhooks"
+require_relative "paypal-api/api_collections/webhook_events"
+require_relative "paypal-api/api_collections/webhook_lookups"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paypal-rest-api
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-12 00:00:00.000000000 Z
+date: 2024-08-30 00:00:00.000000000 Z
 dependencies: []
 description: PayPal REST API with no dependencies.
 email:
@@ -26,10 +26,22 @@ files:
 - lib/paypal-api/api_collections/authorized_payments.rb
 - lib/paypal-api/api_collections/captured_payments.rb
 - lib/paypal-api/api_collections/catalog_products.rb
+- lib/paypal-api/api_collections/disputes.rb
+- lib/paypal-api/api_collections/invoice_templates.rb
+- lib/paypal-api/api_collections/invoices.rb
 - lib/paypal-api/api_collections/orders.rb
+- lib/paypal-api/api_collections/payout_items.rb
+- lib/paypal-api/api_collections/payouts.rb
+- lib/paypal-api/api_collections/referenced_payout_items.rb
+- lib/paypal-api/api_collections/referenced_payouts.rb
 - lib/paypal-api/api_collections/refunds.rb
 - lib/paypal-api/api_collections/shipment_tracking.rb
+- lib/paypal-api/api_collections/subscription_plans.rb
 - lib/paypal-api/api_collections/subscriptions.rb
+- lib/paypal-api/api_collections/user_info.rb
+- lib/paypal-api/api_collections/users.rb
+- lib/paypal-api/api_collections/webhook_events.rb
+- lib/paypal-api/api_collections/webhook_lookups.rb
 - lib/paypal-api/api_collections/webhooks.rb
 - lib/paypal-api/client.rb
 - lib/paypal-api/config.rb
@@ -40,6 +52,8 @@ files:
 - lib/paypal-api/request_executor.rb
 - lib/paypal-api/response.rb
 - lib/paypal-api/version.rb
+- lib/paypal-api/webhook_verifier.rb
+- lib/paypal-api/webhook_verifier/certs_cache.rb
 - lib/paypal-rest-api.rb
 homepage: https://github.com/aglushkov/paypal-api
 licenses:
@@ -63,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.18
 signing_key:
 specification_version: 4
 summary: PayPal REST API