paystack_sdk 0.1.0 → 0.2.0

data/lib/paystack_sdk/response.rb

@@ -60,6 +60,19 @@ module PaystackSdk
     # @return [Integer] The status code of the API response
     attr_reader :status_code
 
+    # Pagination metadata that Paystack returns with list responses
+    # (e.g. `total`, `page`, `pageCount`, `perPage`).
+    #
+    # @return [Response, nil] The wrapped `meta` object, or nil if the response has none
+    #
+    # @example
+    #   response = transactions.list
+    #   response.meta.total       # => 40
+    #   response.meta.pageCount   # => 2
+    def meta
+      @meta ||= wrap_value(@raw_meta) if @raw_meta
+    end
+
     # Initializes a new Response object
     #
     # @param response [Faraday::Response, Hash, Array] The raw API response or data
@@ -75,23 +88,22 @@ module PaystackSdk
         @api_message = extract_api_message(@body)
         @message = @api_message
         @raw_data = extract_data_from_body(@body)
+        @raw_meta = @body["meta"] if @body.is_a?(Hash) && @body["meta"].is_a?(Hash)
 
         case @status_code
         when 200..299
           @success = true
+        when 429
+          # Rate limiting - raise so callers can back off (the connection
+          # already retries automatically unless max_retries is 0)
+          raise RateLimitError.new(rate_limit_reset(response))
         when 400..499
           # Client errors - return unsuccessful response for user to handle
           @success = false
           @error_message = @api_message || "Client error"
 
           # Still raise for authentication issues as these are usually config problems
-          if @status_code == 401
-            raise AuthenticationError.new(@api_message || "Authentication failed")
-          end
-        when 429
-          # Rate limiting - raise as users need to implement retry logic
-          retry_after = response.headers["Retry-After"]
-          raise RateLimitError.new(retry_after || 30)
+          raise AuthenticationError.new(@api_message || "Authentication failed") if @status_code == 401
         when 500..599
           # Server errors - raise as these indicate Paystack infrastructure issues
           raise ServerError.new(@status_code, @api_message)
@@ -104,6 +116,7 @@ module PaystackSdk
         @error_message = response.error_message
         @api_message = response.api_message
         @raw_data = response.raw_data
+        @raw_meta = response.raw_meta
       else
         @success = true
         @raw_data = response
@@ -125,6 +138,34 @@ module PaystackSdk
       @success
     end
 
+    # Whether this response is a successful payment: the call succeeded and the transaction's
+    # `status` is "success". Paystack's docs say to confirm the amount and currency as well, so
+    # pass the ones you expect and they are compared too.
+    #
+    # @param amount [Integer, nil] The amount (in the currency's subunit) you expect
+    # @param currency [String, nil] The currency you expect, e.g. "GHS"
+    # @return [Boolean]
+    #
+    # @example
+    #   response = client.transactions.verify(reference: ref)
+    #   response.paid?(amount: 5000, currency: "GHS")
+    def paid?(amount: nil, currency: nil)
+      return false unless success? && status?(:success)
+      return false if amount && field(:amount) != amount
+      return false if currency && field(:currency).to_s.upcase != currency.to_s.upcase
+
+      true
+    end
+
+    # Whether the `status` field in the response data equals the given value, e.g.
+    # `response.status?(:send_pin)` on a charge. Paystack names the values; none are assumed here.
+    #
+    # @param value [String, Symbol]
+    # @return [Boolean]
+    def status?(value)
+      field(:status).to_s == value.to_s
+    end
+
     # Check if the response failed
     #
     # @return [Boolean] true if the API request failed
@@ -153,6 +194,14 @@ module PaystackSdk
       @body
     end
 
+    # One field of a Hash response body, whichever way it is keyed; nil otherwise.
+    def field(name)
+      return nil unless @raw_data.is_a?(Hash)
+
+      @raw_data.key?(name) ? @raw_data[name] : @raw_data[name.to_s]
+    end
+    private :field
+
     # Access hash values via methods (dot notation)
     # Allows accessing data attributes directly: response.attribute_name
     #
@@ -183,7 +232,8 @@ module PaystackSdk
         super
     end
 
-    # Access data via hash/array notation
+    # Access data via hash/array notation.
+    # Hash keys can be given as strings or symbols, whichever way the data is keyed.
     #
     # @param key [Object] The key or index to access
     # @return [Object, Response] The value for the given key or index
@@ -191,19 +241,19 @@ module PaystackSdk
       return nil unless @raw_data
 
       if @raw_data.is_a?(Hash)
-        value = @raw_data[key.is_a?(String) ? key.to_sym : key]
-        wrap_value(value)
+        actual_key = lookup_key(key)
+        wrap_value(@raw_data[actual_key]) unless actual_key.nil?
       elsif @raw_data.is_a?(Array) && key.is_a?(Integer)
         wrap_value(@raw_data[key])
       end
     end
 
-    # Check if key exists in hash
+    # Check if key exists in hash (as a string or a symbol)
     #
     # @param key [Symbol, String] The key to check
     # @return [Boolean] Whether the key exists
     def key?(key)
-      @raw_data.is_a?(Hash) && @raw_data.key?(key.is_a?(String) ? key.to_sym : key)
+      @raw_data.is_a?(Hash) && !lookup_key(key).nil?
     end
 
     # Iterate through hash entries or array items
@@ -211,7 +261,7 @@ module PaystackSdk
     # @yield [key, value] For hashes, passes each key-value pair
     # @yield [value] For arrays, passes each item
     # @return [Response, Enumerator] Self for chaining or Enumerator if no block given
-    def each(&block)
+    def each
       return enum_for(:each) unless block_given?
 
       if @raw_data.is_a?(Hash)
@@ -231,7 +281,7 @@ module PaystackSdk
     #   @return [Integer] The number of items
     # @!method empty?
     #   @return [Boolean] Whether the collection is empty
-    [:size, :length, :count, :empty?].each do |method_name|
+    %i[size length count empty?].each do |method_name|
       define_method(method_name) do
         @raw_data.send(method_name) if @raw_data.respond_to?(method_name)
       end
@@ -242,15 +292,43 @@ module PaystackSdk
     #   @return [Object, Response] The first item, wrapped if necessary
     # @!method last
     #   @return [Object, Response] The last item, wrapped if necessary
-    [:first, :last].each do |method_name|
+    %i[first last].each do |method_name|
       define_method(method_name) do
         return nil unless @raw_data.is_a?(Array)
+
         wrap_value(@raw_data.send(method_name))
       end
     end
 
+    protected
+
+    # @return [Hash, nil] The unwrapped `meta` from the response body
+    attr_reader :raw_meta
+
     private
 
+    # Finds the key actually used in the data for a string or symbol lookup.
+    #
+    # @return [Object, nil] The key present in the data, or nil if there is none
+    def lookup_key(key)
+      return key if @raw_data.key?(key)
+
+      alternate = case key
+      when String then key.to_sym
+      when Symbol then key.to_s
+      end
+      alternate if !alternate.nil? && @raw_data.key?(alternate)
+    end
+
+    # Seconds until the rate-limit window ends, from Paystack's
+    # `x-ratelimit-reset` header (nil if absent, not numeric, negative or not finite).
+    def rate_limit_reset(response)
+      seconds = Float(response.headers["x-ratelimit-reset"])
+      (seconds.finite? && seconds >= 0) ? seconds.ceil : nil
+    rescue ArgumentError, TypeError
+      nil
+    end
+
     # Extract the identifier from an error response
     # This looks for common patterns in error messages to find resource identifiers
     #
@@ -261,9 +339,7 @@ module PaystackSdk
 
       # First try to get identifier from the message
       message = body["message"].to_s.downcase
-      if message =~ /with (id|code|reference|email): ([^\s]+)/i
-        return $2
-      end
+      return ::Regexp.last_match(2) if message =~ /with (id|code|reference|email): ([^\s]+)/i
 
       # If not found in message, try to extract from error code
       if body["code"]&.match?(/^(transaction|customer)_/)
@@ -288,6 +364,7 @@ module PaystackSdk
     # @return [Hash, Array, nil] The data from the response
     def extract_data_from_body(body)
       return body unless body.is_a?(Hash)
+
       body["data"] || body
     end
 

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/validations.rb

@@ -37,9 +37,9 @@ module PaystackSdk
     # @param name [String] Name of the parameter for error messages
     # @raise [PaystackSdk::InvalidFormatError] If input is not a hash
     def validate_hash!(input:, name: "Payload")
-      unless input.is_a?(Hash)
-        raise PaystackSdk::InvalidFormatError.new(name, "Hash")
-      end
+      return if input.is_a?(Hash)
+
+      raise PaystackSdk::InvalidFormatError.new(name, "Hash")
     end
 
     # Validates that required parameters are present in a payload.
@@ -53,10 +53,10 @@ module PaystackSdk
         !payload.key?(param) && !payload.key?(param.to_s)
       end
 
-      unless missing_params.empty?
-        param = missing_params.first
-        raise PaystackSdk::MissingParamError.new(param)
-      end
+      return if missing_params.empty?
+
+      param = missing_params.first
+      raise PaystackSdk::MissingParamError.new(param)
     end
 
     # Validates that a value is present (not nil or empty).
@@ -91,9 +91,9 @@ module PaystackSdk
     # @param name [String] Name of the parameter for error messages
     # @raise [PaystackSdk::InvalidFormatError] If reference format is invalid
     def validate_reference_format!(reference:, name: "Reference")
-      unless reference.to_s.match?(/^[a-zA-Z0-9._=-]+$/)
-        raise PaystackSdk::InvalidFormatError.new(name, "alphanumeric characters and the following: -, ., =")
-      end
+      return if reference.to_s.match?(/^[a-zA-Z0-9._=-]+$/)
+
+      raise PaystackSdk::InvalidFormatError.new(name, "alphanumeric characters and the following: -, ., =")
     end
 
     # Validates a date string format.
@@ -106,6 +106,7 @@ module PaystackSdk
     def validate_date_format!(date_str:, name: "Date", allow_nil: true)
       if date_str.nil?
         raise PaystackSdk::MissingParamError.new(name) unless allow_nil
+
         return
       end
 
@@ -136,13 +137,14 @@ module PaystackSdk
     def validate_allowed_values!(value:, allowed_values:, name: "Parameter", allow_nil: true)
       if value.nil?
         raise PaystackSdk::MissingParamError.new(name) unless allow_nil
+
         return
       end
 
-      unless allowed_values.include?(value)
-        allowed_list = allowed_values.join(", ")
-        raise PaystackSdk::InvalidValueError.new(name, "must be one of: #{allowed_list}")
-      end
+      return if allowed_values.include?(value)
+
+      allowed_list = allowed_values.join(", ")
+      raise PaystackSdk::InvalidValueError.new(name, "must be one of: #{allowed_list}")
     end
 
     # Validates an email format.
@@ -154,12 +156,13 @@ module PaystackSdk
     def validate_email!(email:, name: "Email", allow_nil: false)
       if email.nil?
         raise PaystackSdk::MissingParamError.new(name) unless allow_nil
+
         return
       end
 
-      unless email.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
-        raise PaystackSdk::InvalidFormatError.new(name, "valid email address")
-      end
+      return if email.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+
+      raise PaystackSdk::InvalidFormatError.new(name, "valid email address")
     end
 
     # Validates a currency code format.
@@ -171,12 +174,13 @@ module PaystackSdk
     def validate_currency!(currency:, name: "Currency", allow_nil: true)
       if currency.nil?
         raise PaystackSdk::MissingParamError.new(name) unless allow_nil
+
         return
       end
 
-      unless currency.to_s.match?(/\A[A-Z]{3}\z/)
-        raise PaystackSdk::InvalidFormatError.new(name, "3-letter ISO code (e.g., NGN, USD, GHS)")
-      end
+      return if currency.to_s.match?(/\A[A-Z]{3}\z/)
+
+      raise PaystackSdk::InvalidFormatError.new(name, "3-letter ISO code (e.g., NGN, USD, GHS)")
     end
 
     # Validates multiple fields at once.

data/lib/paystack_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PaystackSdk
-  VERSION = "0.1.0"
+  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