paypal-rest-api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 161078b6b9ff7513fe6634bc4e37c181374858dec0cac4261d5cc662d115787c
-  data.tar.gz: 60346804bbd8a930f695a922a6ce07adaefca26e25f7777e70de0d9f5d87a01a
+  metadata.gz: 4e1ec764b9c93fe1fb6fe6f49e2fca6d5e0280a1182b0c4c4f54bee84c43b98d
+  data.tar.gz: c03728c11831a20270e38f111165747634298a3ca4d8bf97a26de9da9baa53b1
 SHA512:
-  metadata.gz: e340f1e223aa903aed6fde693f4a16dc9cdf0ef3d474a633e171b7890eb016d8c42ef593117385419bd07c366bb257bbc0adbbcab8b193cb150523cd3dcaee46
-  data.tar.gz: 74f017ec1aabca6d9a55599bacc32ee7d7d2c425ec109ec076d2f8072819d95047a07d763ed7b5ba0bd4b96a3b91a3aa3b2404d1a0602c2704028661b544a18b
+  metadata.gz: 26ca09bb472c049aa9a5cfa81485e11180dc5d1d19776e960beebb6f9db485b9d58ddda18f232943affb1b3d4c27e55ec3c82b4a55be92f16be6ea5c2f836b7e
+  data.tar.gz: f082f9263cffbc5a7a0561557284685eed6c2c2c67204d8c89271e82dedc007b63e3e616e49fc5a86925986df7c52b6afd5e053061785b2909d703c0017db4e7

data/README.md

@@ -8,7 +8,7 @@ bundle add paypal-rest-api
 
 ## Features
 
-- Supported Ruby 2.6 - current Head
+- Supported Ruby Versions - *(2.6 .. 3.3), head, jruby-9.4, truffleruby-24*
 - No dependencies;
 - Automatic authorization & reauthorization;
 - Auto-retries (configured);
@@ -35,7 +35,11 @@ PaypalAPI.client = PaypalAPI::Client.new(
 )
 
 # in your business logic
-response = PaypalAPI::Orders.show(order_id)
+PaypalAPI.live? # => false
+PaypalAPI.api_url # => "https://api-m.sandbox.paypal.com"
+PaypalAPI.web_url # => "https://sandbox.paypal.com"
+
+response = between redeploys::Orders.show(order_id)
 response = PaypalAPI::Orders.create(body: body)
 ```
 
@@ -49,6 +53,10 @@ client = PaypalAPI::Client.new(
   live: false
 )
 
+client.live? # => false
+client.api_url # => "https://api-m.sandbox.paypal.com"
+client.web_url # => "https://sandbox.paypal.com"
+
 response = client.orders.show(order_id)
 response = client.orders.create(body: body)
 ```
@@ -91,7 +99,7 @@ response.request # Request that generates this response
 
 ## Configuration options
 
-PaypalAPI client accepts this additional options: `:live`, `:retries`, `:http_opts`
+PaypalAPI client accepts this additional options: `:live`, `:retries`, `:http_opts`, `:cache`
 
 ### Option `:live`
 
@@ -108,8 +116,8 @@ client = PaypalAPI::Client.new(
 ### Option `:retries`
 
 This is a Hash with retries configuration.
-By default retries are enabled, 3 retries with 0.25, 0.75, 1.5 seconds delay.
-Default config: `{enabled: true, count: 3, sleep: [0.25, 0.75, 1.5]}`.
+By default retries are enabled, 4 retries with 0, 0.25, 0.75, 1.5 seconds delay.
+Default config: `{enabled: true, count: 4, sleep: [0, 0.25, 0.75, 1.5]}`.
 New options are merged with defaults.
 Please keep `sleep` array same size as `count`.
 
@@ -139,17 +147,33 @@ client = PaypalAPI::Client.new(
 )
 ```
 
+### Option `:cache`
+
+This option can be added to save certificates to between redeploys to validate
+webhooks offline. By default this gem has only in-memory caching.
+Cache object must response to standard caching `#fetch(key, &block)` method.
+
+By default it is `nil`, so downloaded certificates will be downloaded again after
+redeploys.
+
+```ruby
+client = PaypalAPI::Client.new(
+  cache: Rails.cache
+  # ...
+)
+```
+
 ## Webhoooks verification
 
 Webhooks can be verified [offline](https://developer.paypal.com/api/rest/webhooks/rest/#link-selfverificationmethod)
 or [online](https://developer.paypal.com/api/rest/webhooks/rest/#link-postbackmethod).
 Method `PaypalAPI.verify_webhook(webhook_id:, headers:, raw_body:)`
-verifies webhook. It to verify webhook OFFLINE and it fallbacks
-to ONLINE if offline verification returns false to be sure you don't miss a
+verifies webhook. It verifies webhook OFFLINE and fallbacks
+to ONLINE if initial verification returns false to be sure you don't miss a
 valid webhook.
 
-When some required header is missing it will raise
-`PaypalAPI::WebhooksVerifier::MissingHeader` error.
+When some required header is missing the
+`PaypalAPI::WebhooksVerifier::MissingHeader` error will be raised.
 
 Example of Rails controller with webhook verification:
 
@@ -192,9 +216,17 @@ Callbacks are registered on `client` object.
 Each callback receive `request` and `context` variables.
 `context` can be modified manually to save state between callbacks.
 
-`:after_success` and `:after_fail` callbacks have additional `response` argument
+Arguments:
+
+- `:before` - (request, context)
+- `:after_success` - (request, context, response)
+- `:after_fail` - (request, context, response)
+- `:after_network_error` - (request, context, error)
+
+`Context` argument contains `retries_enabled` and `retries_count` and
+`retry_number` keys by default.
 
-`:after_network_error` callback has additional `error` argument
+Examples:
 
 ```ruby
 PaypalAPI.client.add_callback(:before) do |request, context|
@@ -202,7 +234,7 @@ PaypalAPI.client.add_callback(:before) do |request, context|
   context[:starts_at] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 end
 
-PaypalAPI.client.add_callback(:after) do |request, context, response|
+PaypalAPI.client.add_callback(:after_success) do |request, context, response|
   ends_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   duration = ends_at - context[:starts_at]
 
@@ -229,7 +261,7 @@ end
 
 PaypalAPI.client.add_callback(:after_network_error) do |request, context, error|
   SomeLogger.error(
-    'PaypalAPI network connection error'
+    'PaypalAPI network connection error',
     method: request.method,
     uri: request.uri.to_s,
     error: error.message,
@@ -316,15 +348,15 @@ All API endpoints accept this parameters:
 
 ### Payments
 
-- `PaypalAPI::AuthorizedPayment.show`
-- `PaypalAPI::AuthorizedPayment.capture`
-- `PaypalAPI::AuthorizedPayment.reauthorize`
-- `PaypalAPI::AuthorizedPayment.void`
+- `PaypalAPI::AuthorizedPayments.show`
+- `PaypalAPI::AuthorizedPayments.capture`
+- `PaypalAPI::AuthorizedPayments.reauthorize`
+- `PaypalAPI::AuthorizedPayments.void`
 
 <!-- -->
 
-- `PaypalAPI::CapturedPayment.show`
-- `PaypalAPI::CapturedPayment.refund`
+- `PaypalAPI::CapturedPayments.show`
+- `PaypalAPI::CapturedPayments.refund`
 
 <!-- -->
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

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

@@ -43,7 +43,7 @@ module PaypalAPI
 
         default_headers = {
           "content-type" => "application/x-www-form-urlencoded",
-          "authorization" => "Basic #{["#{client.config.client_id}:#{client.config.client_secret}"].pack("m0")}"
+          "authorization" => "Basic #{["#{client.env.client_id}:#{client.env.client_secret}"].pack("m0")}"
         }
 
         client.post(PATH, query: query, body: body, headers: merge_headers!(default_headers, headers))

data/lib/paypal-api/client.rb

@@ -5,7 +5,18 @@ module PaypalAPI
   # PaypalAPI Client
   #
   class Client
-    attr_reader :config, :callbacks
+    # Paypal environment
+    attr_reader :env
+
+    # Gem Configuration
+    #
+    # @return [Config] Gem Configuration
+    attr_reader :config
+
+    # Registered callbacks
+    #
+    # @return [Hash] Registered callbacks
+    attr_reader :callbacks
 
     # Initializes Client
     # @api public
@@ -18,15 +29,9 @@ module PaypalAPI
     #
     # @return [Client] Initialized client
     #
-    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,
-        cache: cache
-      )
+    def initialize(client_id:, client_secret:, live: false, http_opts: nil, retries: nil, cache: nil)
+      @env = PaypalAPI::Environment.new(client_id: client_id, client_secret: client_secret, live: live)
+      @config = PaypalAPI::Config.new(http_opts: http_opts, retries: retries, cache: cache)
 
       @callbacks = {
         before: [],
@@ -38,10 +43,34 @@ module PaypalAPI
       @access_token = nil
     end
 
+    # Checks if PayPal LIVE environment enabled
+    # @return [Boolean] Checks if PayPal LIVE environment enabled
+    def live?
+      env.live?
+    end
+
+    # Checks if PayPal SANDBOX environment enabled
+    # @return [Boolean] Checks if PayPal SANDBOX environment enabled
+    def sandbox?
+      env.sandbox?
+    end
+
+    # Base API URL
+    # @return [String] Base API URL
+    def api_url
+      env.api_url
+    end
+
+    # Base WEB URL
+    # @return [String] Base WEB URL
+    def web_url
+      env.web_url
+    end
+
     # Registers callback
     #
     # @param callback_name [Symbol] Callback name.
-    #   Allowed values: :before, :after_success, :after_faile, :after_network_error
+    #   Allowed values: :before, :after_success, :after_fail, :after_network_error
     #
     # @param block [Proc] Block that must be call
     #   For `:before` callback proc should accept 2 params -
@@ -89,6 +118,7 @@ module PaypalAPI
 
     #
     # Verifies Webhook
+    #
     # It requires one-time request to download and cache certificate.
     # If local verification returns false it tries to verify webhook online.
     #
@@ -98,7 +128,7 @@ module PaypalAPI
     #  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
+    #      headers = request.headers # must respond to #[] to get headers
     #      body = request.raw_post # must be a raw String body
     #
     #      webhook_is_valid = PaypalAPI.verify_webhook(webhook_id: webhook_id, headers: headers, body: body)

data/lib/paypal-api/config.rb

@@ -2,71 +2,32 @@
 
 module PaypalAPI
   #
-  # Stores configuration for PaypalAPI Client
+  # Stores client requests configuration
   #
   class Config
-    # Live PayPal URL
-    LIVE_URL = "https://api-m.paypal.com"
-
-    # Sandbox PayPal URL
-    SANDBOX_URL = "https://api-m.sandbox.paypal.com"
-
     # Default config options
     DEFAULTS = {
-      live: false,
       http_opts: {}.freeze,
-      retries: {enabled: true, count: 3, sleep: [0.25, 0.75, 1.5].freeze}.freeze
+      retries: {enabled: true, count: 4, sleep: [0, 0.25, 0.75, 1.5].freeze}.freeze
     }.freeze
 
-    attr_reader :client_id, :client_secret, :live, :http_opts, :retries, :certs_cache
+    attr_reader :http_opts, :retries, :certs_cache
 
     # Initializes Config
     #
-    # @param client_id [String] PayPal client id
-    # @param client_secret [String] PayPal client secret
-    # @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)
+    #   Must respond to #fetch(key, &block)
     #
     # @return [Client] Initialized config object
     #
-    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)
+    def initialize(http_opts: nil, retries: {}, cache: nil)
+      @http_opts = http_opts || DEFAULTS[:http_opts]
+      @retries = DEFAULTS[:retries].merge(retries || {})
       @certs_cache = WebhookVerifier::CertsCache.new(cache)
 
       freeze
     end
-
-    # @return [String] PayPal live or sandbox URL
-    def url
-      live ? LIVE_URL : SANDBOX_URL
-    end
-
-    #
-    # Instance representation string. Default was overwritten to hide secrets
-    #
-    def inspect
-      "#<#{self.class.name} live: #{live}>"
-    end
-
-    alias_method :to_s, :inspect
-
-    private
-
-    def with_default(option_name, value)
-      default = DEFAULTS.fetch(option_name)
-
-      case value
-      when NilClass then default
-      when Hash then default.merge(value)
-      else value
-      end
-    end
   end
 end

data/lib/paypal-api/environment.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  # Sandbox API PayPal URL
+  SANDBOX_API_URL = "https://api-m.sandbox.paypal.com"
+
+  # Live API PayPal URL
+  LIVE_API_URL = "https://api-m.paypal.com"
+
+  # Sandbox PayPal Web URL
+  SANDBOX_WEB_URL = "https://sandbox.paypal.com"
+
+  # Live PayPal Web URL
+  LIVE_WEB_URL = "https://paypal.com"
+
+  #
+  # PayPal environment info
+  #
+  class Environment
+    # PayPal client_id
+    attr_accessor :client_id
+
+    # PayPal client_secret
+    attr_reader :client_secret
+
+    # PayPal API base URL
+    attr_reader :api_url
+
+    # PayPal web URL
+    attr_reader :web_url
+
+    # Initializes Environment
+    #
+    # @param client_id [String] PayPal client id
+    # @param client_secret [String] PayPal client secret
+    # @param live [Boolean] PayPal live/sandbox mode
+    #
+    # @return [Client] Initialized config object
+    #
+    def initialize(client_id:, client_secret:, live: false)
+      @live = live || false
+      @api_url = live ? LIVE_API_URL : SANDBOX_API_URL
+      @web_url = live ? LIVE_WEB_URL : SANDBOX_WEB_URL
+      @client_id = client_id
+      @client_secret = client_secret
+      freeze
+    end
+
+    #
+    # Instance representation string. Default was overwritten to hide secrets
+    # @return [String]
+    #
+    def inspect
+      "#<#{self.class.name} live: #{@live}>"
+    end
+
+    alias_method :to_s, :inspect
+
+    #
+    # Checks if live environment enabled
+    # @return [Boolean]
+    #
+    def live?
+      @live
+    end
+
+    #
+    # Checks if sandbox environment enabled
+    # @return [Boolean]
+    #
+    def sandbox?
+      !live?
+    end
+  end
+end

data/lib/paypal-api/request.rb

@@ -107,7 +107,7 @@ module PaypalAPI
     end
 
     def build_http_uri(path, query)
-      uri = URI.join(client.config.url, path)
+      uri = URI.join(client.env.api_url, path)
       uri.query = URI.encode_www_form(query) if query && !query.empty?
       uri
     end

data/lib/paypal-api/request_executor.rb

@@ -5,7 +5,7 @@ module PaypalAPI
   # Executes PaypalAPI::Request and returns PaypalAPI::Response or raises PaypalAPI::Error
   #
   class RequestExecutor
-    attr_reader :client, :request, :http_opts, :context, :retries, :callbacks, :callbacks_context
+    attr_reader :client, :request, :http_opts, :retries, :callbacks, :callbacks_context
 
     def initialize(client, request)
       @client = client
@@ -13,7 +13,7 @@ module PaypalAPI
       @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]}
+      @callbacks_context = {retries_enabled: retries[:enabled], retries_count: retries[:count]}
     end
 
     #
@@ -35,8 +35,10 @@ module PaypalAPI
 
       run_callbacks(:before)
       response = execute_net_http_request
-    rescue *NetworkErrorBuilder::ERRORS => error
-      will_retry = !retries_limit_reached?(retry_number)
+    rescue => error
+      raise error if NetworkErrorBuilder::ERRORS.none? { |network_error_class| error.is_a?(network_error_class) }
+
+      will_retry = retries[:enabled] && !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
@@ -48,7 +50,7 @@ module PaypalAPI
         run_callbacks(:after_success, response)
         response
       else
-        will_retry = retryable?(response, retry_number)
+        will_retry = retries[:enabled] && retryable?(response, retry_number)
         callbacks_context[:will_retry] = will_retry
         run_callbacks(:after_fail, response)
         will_retry ? retry_request(retry_number) : response
@@ -104,7 +106,7 @@ module PaypalAPI
     end
 
     def run_callbacks(callback_name, resp = nil)
-      callbacks[callback_name].each { |callback| callback.call(request, context, resp) }
+      callbacks[callback_name].each { |callback| callback.call(request, callbacks_context, resp) }
     end
   end
 end

data/lib/paypal-api.rb

@@ -210,6 +210,7 @@ end
 
 require_relative "paypal-api/access_token"
 require_relative "paypal-api/api_collection"
+require_relative "paypal-api/environment"
 require_relative "paypal-api/client"
 require_relative "paypal-api/config"
 require_relative "paypal-api/error"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paypal-rest-api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-30 00:00:00.000000000 Z
+date: 2024-09-02 00:00:00.000000000 Z
 dependencies: []
 description: PayPal REST API with no dependencies.
 email:
@@ -45,6 +45,7 @@ files:
 - lib/paypal-api/api_collections/webhooks.rb
 - lib/paypal-api/client.rb
 - lib/paypal-api/config.rb
+- lib/paypal-api/environment.rb
 - lib/paypal-api/error.rb
 - lib/paypal-api/failed_request_error_builder.rb
 - lib/paypal-api/network_error_builder.rb