paystack_sdk 0.1.1 → 0.2.0

data/lib/paystack_sdk/utils/connection_utils.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../middleware/transport_errors"
+
 module PaystackSdk
   module Utils
     # The `ConnectionUtils` module provides shared functionality for creating
@@ -9,32 +11,92 @@ module PaystackSdk
       # The base URL for the Paystack API.
       BASE_URL = "https://api.paystack.co"
 
+      # Seconds to wait for the connection to open.
+      DEFAULT_OPEN_TIMEOUT = 5
+
+      # Seconds to wait for a response.
+      DEFAULT_TIMEOUT = 30
+
+      # Retries performed after the initial attempt.
+      DEFAULT_MAX_RETRIES = 2
+
+      # Base delay in seconds before the first retry (doubles each attempt).
+      DEFAULT_RETRY_INTERVAL = 0.5
+
+      # HTTP methods that only read data and are always safe to repeat.
+      SAFE_METHODS = %i[get head options].freeze
+
+      # Statuses worth retrying. 500 is excluded because it usually means a
+      # bug, not a transient fault.
+      RETRY_STATUSES = [429, 502, 503, 504].freeze
+
+      # Longest pause (seconds) between retries. If Paystack asks for a longer
+      # wait via `x-ratelimit-reset`, the request is not retried and the
+      # error is raised so the caller can decide.
+      MAX_RETRY_WAIT = 10
+
+      # Response header Paystack uses to say when the rate-limit window ends.
+      # @see https://paystack.com/docs/api/rate-limits/
+      RATE_LIMIT_RESET_HEADER = "x-ratelimit-reset"
+
       # Initializes a connection based on the provided parameters.
       #
       # @param connection [Faraday::Connection, nil] An existing connection object.
       # @param secret_key [String, nil] Optional API key to use for creating a new connection.
+      # @param options [Hash] Connection options, see {#create_connection}.
       # @return [Faraday::Connection] A connection object for API requests.
       # @raise [PaystackSdk::Error] If no connection or API key can be found.
-      def initialize_connection(connection = nil, secret_key: nil)
+      def initialize_connection(connection = nil, secret_key: nil, **options)
         if connection
+          unless options.empty?
+            raise ArgumentError,
+              "#{options.keys.join(", ")} cannot be used with a pre-built connection; configure the connection itself"
+          end
+
           connection
         elsif secret_key
-          create_connection(secret_key:)
+          create_connection(secret_key:, **options)
         else
           # Try to get API key from environment variable
           env_secret_key = ENV["PAYSTACK_SECRET_KEY"]
           raise AuthenticationError, "No connection or API key provided" unless env_secret_key
 
-          create_connection(secret_key: env_secret_key)
+          create_connection(secret_key: env_secret_key, **options)
         end
       end
 
       # Creates a new Faraday connection with the Paystack API.
       #
+      # Requests time out and are retried with exponential backoff on network
+      # failures and on 429/502/503/504 responses. Because this SDK moves
+      # money, retries are deliberately conservative:
+      #
+      # * Read-only requests (GET/HEAD/OPTIONS) are retried on any of the above.
+      # * Every other request is retried only on 429, where Paystack has
+      #   rejected it for exceeding the rate limit. A timeout or 5xx on a
+      #   write could mean it was processed, so it is never retried unless you
+      #   pass `retry_non_idempotent: true`.
+      #
+      # On a 429 the wait honours Paystack's `x-ratelimit-reset` header.
+      #
       # @param secret_key [String] The secret API key for authenticating with the Paystack API.
+      # @param timeout [Numeric] Seconds to wait for a response.
+      # @param open_timeout [Numeric] Seconds to wait for the connection to open.
+      # @param max_retries [Integer] Retries after the first attempt (0 disables retrying).
+      # @param retry_interval [Numeric] Base delay in seconds before the first retry.
+      # @param retry_non_idempotent [Boolean] Also retry writes on network failures and 5xx.
+      #   Only enable this if you supply your own deduplication (e.g. verify by reference).
       # @return [Faraday::Connection] A configured Faraday connection.
-      def create_connection(secret_key:)
-        Faraday.new(url: BASE_URL) do |conn|
+      def create_connection(secret_key:, timeout: DEFAULT_TIMEOUT, open_timeout: DEFAULT_OPEN_TIMEOUT,
+        max_retries: DEFAULT_MAX_RETRIES, retry_interval: DEFAULT_RETRY_INTERVAL,
+        retry_non_idempotent: false)
+        validate_connection_options!(timeout:, open_timeout:, max_retries:, retry_interval:)
+
+        Faraday.new(url: BASE_URL, request: {timeout:, open_timeout:}) do |conn|
+          conn.use Middleware::TransportErrors
+          if max_retries > 0
+            conn.request :retry, retry_options(max_retries, retry_interval, retry_non_idempotent)
+          end
           conn.request :json
           conn.response :json, content_type: /\bjson$/
           conn.headers["Authorization"] = "Bearer #{secret_key}"
@@ -43,6 +105,39 @@ module PaystackSdk
           conn.adapter Faraday.default_adapter
         end
       end
+
+      private
+
+      def validate_connection_options!(timeout:, open_timeout:, max_retries:, retry_interval:)
+        {timeout:, open_timeout:}.each do |name, value|
+          raise ArgumentError, "#{name} must be a positive number" unless value.is_a?(Numeric) && value > 0
+        end
+        raise ArgumentError, "max_retries must be a non-negative Integer" unless max_retries.is_a?(Integer) && max_retries >= 0
+        raise ArgumentError, "retry_interval must be a non-negative number" unless retry_interval.is_a?(Numeric) && retry_interval >= 0
+      end
+
+      def retry_options(max_retries, retry_interval, retry_non_idempotent)
+        {
+          max: max_retries,
+          interval: retry_interval,
+          interval_randomness: 0.5,
+          backoff_factor: 2,
+          max_interval: MAX_RETRY_WAIT,
+          rate_limit_reset_header: RATE_LIMIT_RESET_HEADER,
+          retry_statuses: RETRY_STATUSES,
+          methods: [],
+          exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed],
+          retry_if: ->(env, exception) { retryable_request?(env, exception, retry_non_idempotent) }
+        }
+      end
+
+      def retryable_request?(env, exception, retry_non_idempotent)
+        return true if SAFE_METHODS.include?(env.method)
+        return true if retry_non_idempotent
+
+        # Writes: only when Paystack rejected the request for rate limiting.
+        exception.is_a?(Faraday::RetriableResponse) && env.status == 429
+      end
     end
   end
 end

data/lib/paystack_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PaystackSdk
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/paystack_sdk/webhook.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require_relative "response"
+
+module PaystackSdk
+  # Helpers for receiving Paystack webhooks, independent of any web framework.
+  #
+  # Paystack signs every event with the `x-paystack-signature` header: a
+  # lowercase hex HMAC SHA512 of the raw request body, using your secret key.
+  # Verify it before doing anything with the event, and return a `200 OK`
+  # quickly (do long work in a background job): events that are not
+  # acknowledged are retried for 72 hours in live mode.
+  #
+  # @see https://paystack.com/docs/payments/webhooks/
+  #
+  # @example In a Rails controller
+  # ```ruby
+  #   def create
+  #     event = PaystackSdk::Webhook.construct_event(
+  #       payload: request.raw_post,
+  #       signature: request.headers["X-Paystack-Signature"],
+  #       secret: ENV.fetch("PAYSTACK_SECRET_KEY")
+  #     )
+  #     HandlePaystackEventJob.perform_later(event.payload)
+  #     head :ok
+  #   rescue PaystackSdk::WebhookError
+  #     head :bad_request
+  #   end
+  # ```
+  module Webhook
+    # Header Paystack puts the signature in. Rack and Rails expose it as
+    # `HTTP_X_PAYSTACK_SIGNATURE` or `request.headers["X-Paystack-Signature"]`.
+    SIGNATURE_HEADER = "x-paystack-signature"
+
+    # The only addresses Paystack sends webhooks from, for both test and live.
+    IP_ADDRESSES = %w[52.31.139.75 52.49.173.169 52.214.14.220].freeze
+
+    # Events Paystack documents. Paystack adds events over time, so an event
+    # outside this list is still returned by {Webhook.construct_event}.
+    EVENTS = %w[
+      charge.dispute.create charge.dispute.remind charge.dispute.resolve charge.success
+      customeridentification.failed customeridentification.success
+      dedicatedaccount.assign.failed dedicatedaccount.assign.success
+      invoice.create invoice.payment_failed invoice.update
+      paymentrequest.pending paymentrequest.success
+      refund.failed refund.pending refund.processed refund.processing
+      subscription.create subscription.disable subscription.expiring_cards subscription.not_renew
+      transfer.failed transfer.reversed transfer.success
+    ].freeze
+
+    # A verified webhook event.
+    class Event
+      # @return [String] The event name, e.g. "charge.success"
+      attr_reader :event
+
+      # @return [Hash] The parsed JSON body, string-keyed
+      attr_reader :payload
+
+      def initialize(payload)
+        @payload = payload
+        @event = payload["event"]
+      end
+
+      # @return [PaystackSdk::Response, nil] The event's `data`, wrapped for dot and hash access
+      def data
+        return @data if defined?(@data)
+
+        @data = payload.key?("data") ? Response.new(payload["data"]) : nil
+      end
+
+      # @return [Boolean] Whether Paystack documents this event name
+      def known?
+        EVENTS.include?(event)
+      end
+    end
+
+    class << self
+      # Computes the signature Paystack would send for a payload.
+      # Mostly useful in your own tests.
+      #
+      # @param payload [String] The raw request body
+      # @param secret [String] Your secret key
+      # @return [String] Lowercase hex HMAC SHA512
+      def sign(payload, secret)
+        OpenSSL::HMAC.hexdigest("SHA512", secret, payload)
+      end
+
+      # Checks a webhook's signature in constant time.
+      #
+      # @param payload [String] The raw request body, byte for byte. Not a parsed
+      #   or re-serialised version of it, which would not match.
+      # @param signature [String, nil] The `x-paystack-signature` header value
+      # @param secret [String] Your secret key
+      # @return [Boolean]
+      # @raise [ArgumentError] If the payload is not a String or the secret is blank
+      def valid_signature?(payload:, signature:, secret:)
+        unless payload.is_a?(String)
+          raise ArgumentError, "payload must be the raw request body (a String), not a parsed or re-serialised copy"
+        end
+        raise ArgumentError, "secret must not be blank" if secret.nil? || secret.to_s.empty?
+
+        expected = sign(payload, secret)
+        return false unless signature.is_a?(String) && signature.bytesize == expected.bytesize
+
+        OpenSSL.fixed_length_secure_compare(expected, signature)
+      end
+
+      # Like {valid_signature?} but raises when the signature is wrong.
+      #
+      # @return [true]
+      # @raise [PaystackSdk::InvalidSignatureError]
+      def verify!(payload:, signature:, secret:)
+        raise InvalidSignatureError unless valid_signature?(payload: payload, signature: signature, secret: secret)
+
+        true
+      end
+
+      # Verifies the signature, then parses the event. Nothing is parsed if the
+      # signature is wrong.
+      #
+      # @return [PaystackSdk::Webhook::Event]
+      # @raise [PaystackSdk::InvalidSignatureError] If the signature does not match
+      # @raise [PaystackSdk::InvalidPayloadError] If the signed body is not a JSON event
+      def construct_event(payload:, signature:, secret:)
+        verify!(payload: payload, signature: signature, secret: secret)
+
+        parsed = begin
+          JSON.parse(payload)
+        rescue JSON::ParserError
+          raise InvalidPayloadError, "Webhook body is not valid JSON"
+        end
+
+        unless parsed.is_a?(Hash) && parsed["event"].is_a?(String) && !parsed["event"].empty?
+          raise InvalidPayloadError, "Webhook body is not an event (missing \"event\")"
+        end
+
+        Event.new(parsed)
+      end
+
+      # Whether an address is one Paystack documents for webhooks. A second
+      # check alongside the signature, not a replacement for it.
+      #
+      # @param ip [String, nil]
+      # @return [Boolean]
+      def trusted_ip?(ip)
+        IP_ADDRESSES.include?(ip)
+      end
+    end
+  end
+end

data/lib/paystack_sdk.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/retry"
 require_relative "paystack_sdk/version"
 require_relative "paystack_sdk/client"
+require_relative "paystack_sdk/webhook"
 
 module PaystackSdk
   # Base error class for all Paystack SDK errors.
@@ -71,14 +73,23 @@ module PaystackSdk
 
   # Raised when rate limiting is encountered
   class RateLimitError < APIError
+    # @return [Integer, nil] Seconds until the rate-limit window ends, from the
+    #   `x-ratelimit-reset` header, or nil if Paystack did not send it
     attr_reader :retry_after
 
-    def initialize(retry_after)
+    def initialize(retry_after = nil)
       @retry_after = retry_after
-      super("Rate limit exceeded. Retry after #{retry_after} seconds")
+      super(retry_after ? "Rate limit exceeded. Retry after #{retry_after} seconds" : "Rate limit exceeded")
     end
   end
 
+  # Raised when a request could not reach Paystack (DNS, refused, reset, ...)
+  # after all retries were exhausted.
+  class ConnectionError < Error; end
+
+  # Raised when a request to Paystack timed out after all retries were exhausted.
+  class TimeoutError < ConnectionError; end
+
   # Raised when the server returns a 5xx error
   class ServerError < APIError
     attr_reader :status_code
@@ -88,4 +99,18 @@ module PaystackSdk
       super("#{message} (Status: #{status_code})")
     end
   end
+
+  # Base class for webhook errors.
+  class WebhookError < Error; end
+
+  # Raised when a webhook's signature does not match its payload.
+  # Treat the request as not coming from Paystack.
+  class InvalidSignatureError < WebhookError
+    def initialize(message = "Webhook signature does not match the payload")
+      super
+    end
+  end
+
+  # Raised when a correctly signed webhook body is not a JSON event.
+  class InvalidPayloadError < WebhookError; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paystack_sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Maxwell Nana Forson (theLazyProgrammer)
@@ -11,18 +11,38 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.13.1
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.13.1
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +99,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.25'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -115,18 +163,23 @@ files:
 - Rakefile
 - lib/paystack_sdk.rb
 - lib/paystack_sdk/client.rb
+- lib/paystack_sdk/middleware/transport_errors.rb
+- lib/paystack_sdk/request_helpers.rb
 - lib/paystack_sdk/resources/banks.rb
 - lib/paystack_sdk/resources/base.rb
 - lib/paystack_sdk/resources/charges.rb
 - lib/paystack_sdk/resources/customers.rb
+- lib/paystack_sdk/resources/extensions/charges.rb
+- lib/paystack_sdk/resources/miscellaneous.rb
+- lib/paystack_sdk/resources/refunds.rb
 - lib/paystack_sdk/resources/transactions.rb
 - lib/paystack_sdk/resources/transfer_recipients.rb
 - lib/paystack_sdk/resources/transfers.rb
-- lib/paystack_sdk/resources/verification.rb
 - lib/paystack_sdk/response.rb
 - lib/paystack_sdk/utils/connection_utils.rb
 - lib/paystack_sdk/validations.rb
 - lib/paystack_sdk/version.rb
+- lib/paystack_sdk/webhook.rb
 - mise.toml
 - sig/paystack_sdk.rbs
 homepage: https://github.com/nanafox/paystack_sdk

data/lib/paystack_sdk/resources/verification.rb

@@ -1,36 +0,0 @@
-require_relative "../validations"
-require_relative "base"
-
-module PaystackSdk
-  module Resources
-    class Verification < Base
-      # Resolve Bank Account
-      # @see https://paystack.com/docs/api/verification/#resolve-bank-account
-      def resolve_account(account_number:, bank_code:)
-        validate_presence!(value: account_number, name: "account_number")
-        validate_presence!(value: bank_code, name: "bank_code")
-        handle_response(@connection.get("/bank/resolve", {account_number: account_number, bank_code: bank_code}))
-      end
-
-      # Resolve Card BIN
-      # @see https://paystack.com/docs/api/verification/#resolve-card-bin
-      def resolve_card_bin(bin)
-        validate_presence!(value: bin, name: "bin")
-        handle_response(@connection.get("/decision/bin/#{bin}"))
-      end
-
-      # Validate Account
-      # @see https://paystack.com/docs/api/verification/#validate-account
-      # Required: account_number, account_name, account_type, bank_code, country_code, document_type
-      # Optional: document_number
-      def validate_account(params)
-        validate_required_params!(
-          payload: params,
-          required_params: %i[account_number account_name account_type bank_code country_code document_type],
-          operation_name: "Validate Account"
-        )
-        handle_response(@connection.post("/bank/validate", params))
-      end
-    end
-  end
-end