nombaone 0.1.0

data/lib/nombaone/errors.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Nombaone
+  # Every public error code the API can emit, vendored verbatim from the
+  # platform's `PUBLIC_ERROR_CODES`. Each constant's value is its own name
+  # (e.g. `Nombaone::ErrorCode::CUSTOMER_NOT_FOUND == "CUSTOMER_NOT_FOUND"`),
+  # so you can branch on `error.code == Nombaone::ErrorCode::CUSTOMER_NOT_FOUND`
+  # without memorizing strings.
+  #
+  # The list is a **closed catalog shipped open**: a code the API adds tomorrow
+  # is still parsed and surfaced on {APIError#code} as a plain string — it just
+  # will not have a named constant here yet, and never breaks your code today.
+  module ErrorCode
+    # The full public catalog, in wire order.
+    ALL = %w[
+      CLIENT_INVALID_REQUEST
+      CLIENT_VALIDATION_FAILED
+      CLIENT_FORBIDDEN
+      CLIENT_ROUTE_NOT_FOUND
+      CLIENT_RESOURCE_NOT_FOUND
+      CLIENT_CONFLICT
+      INVALID_CURSOR
+      API_KEY_MISSING
+      API_KEY_INVALID
+      API_KEY_SCOPE_FORBIDDEN
+      API_KEY_ENVIRONMENT_MISMATCH
+      API_KEY_HOST_MISMATCH
+      IDEMPOTENCY_KEY_MISSING
+      IDEMPOTENCY_KEY_REUSED
+      IDEMPOTENCY_IN_PROGRESS
+      RATE_LIMIT_EXCEEDED
+      PLATFORM_MAINTENANCE
+      WEBHOOK_SIGNATURE_INVALID
+      CUSTOMER_NOT_FOUND
+      CUSTOMER_EMAIL_TAKEN
+      PLAN_NOT_FOUND
+      PLAN_NAME_TAKEN
+      PLAN_ALREADY_ARCHIVED
+      PLAN_HAS_ACTIVE_SUBSCRIBERS
+      PRICE_NOT_FOUND
+      PRICE_PLAN_MISMATCH
+      PRICE_ALREADY_INACTIVE
+      PRICE_TIERED_NOT_SUPPORTED
+      PAYMENT_METHOD_NOT_FOUND
+      PAYMENT_METHOD_NOT_ACTIVE
+      PAYMENT_METHOD_KIND_MISMATCH
+      MANDATE_NOT_ACTIVE
+      MANDATE_MAX_AMOUNT_EXCEEDED
+      MANDATE_CONSENT_PENDING
+      SUBSCRIPTION_NOT_FOUND
+      SUBSCRIPTION_ILLEGAL_TRANSITION
+      SUBSCRIPTION_VERSION_CONFLICT
+      SUBSCRIPTION_NOT_TERMINAL
+      SUBSCRIPTION_PAYMENT_METHOD_REQUIRED
+      INVOICE_NOT_FOUND
+      INVOICE_ALREADY_FINALIZED
+      INVOICE_ALREADY_PAID
+      INVOICE_NOT_VOIDABLE
+      SUBSCRIPTION_SCHEDULE_NOT_FOUND
+      SUBSCRIPTION_SCHEDULE_CONFLICT
+      SUBSCRIPTION_SCHEDULE_INVALID_EFFECTIVE_AT
+      PRORATION_NOT_APPLICABLE
+      PRORATION_INTERVAL_SWITCH_UNSUPPORTED
+      COUPON_NOT_FOUND
+      COUPON_EXPIRED
+      COUPON_MAX_REDEMPTIONS_REACHED
+      COUPON_INVALID_DEFINITION
+      COUPON_ALREADY_APPLIED
+      DISCOUNT_NOT_FOUND
+      CREDIT_GRANT_NOT_FOUND
+      CREDIT_GRANT_ALREADY_VOIDED
+      CREDIT_INSUFFICIENT_BALANCE
+      CREDIT_INVALID_AMOUNT
+      DUNNING_NO_OPEN_INVOICE
+      DUNNING_ATTEMPT_NOT_FOUND
+      DUNNING_CARD_UPDATE_REQUIRED
+      DUNNING_ALREADY_TERMINAL
+      SETTLEMENT_NOT_FOUND
+      SETTLEMENT_SUBACCOUNT_NOT_FOUND
+      REFUND_ALREADY_REFUNDED
+      REFUND_AMOUNT_EXCEEDS_NET
+      ESCROW_LOCKED
+      PAYOUT_EXCEEDS_AVAILABLE
+      QUOTA_EXCEEDED
+      EXAMPLE_NOT_FOUND
+      SYSTEM_INTERNAL_ERROR
+      SYSTEM_UPSTREAM_ERROR
+    ].freeze
+
+    ALL.each { |code| const_set(code, code) }
+  end
+
+  # Base class for everything this SDK raises — API failures, connection
+  # problems, webhook verification failures, and client misconfiguration.
+  # Rescue `Nombaone::Error` to catch anything the SDK can throw.
+  #
+  # @example
+  #   begin
+  #     nombaone.subscriptions.create(customer_id: cus, price_id: prc)
+  #   rescue Nombaone::Error => e
+  #     warn e.message
+  #   end
+  class Error < StandardError; end
+
+  # A non-2xx response from the API. Carries everything the error envelope
+  # said: the stable {#code} to branch on, the {#hint} telling you how to fix
+  # it, the {#doc_url} into the error reference, per-field validation errors on
+  # 422s, and the {#request_id} to quote to support.
+  #
+  # Subclasses are keyed by HTTP status so `rescue` reads naturally:
+  # {AuthenticationError}, {RateLimitError}, {ValidationError}, ….
+  # Branch on {#code} (stable) or the class (by HTTP status), never on the
+  # message (it may be reworded).
+  class APIError < Error
+    # @return [Integer] HTTP status of the response.
+    attr_reader :status_code
+    # @return [String] stable machine-readable error code — branch on this.
+    attr_reader :code
+    # @return [String] actionable guidance from the API on what to do next.
+    attr_reader :hint
+    # @return [String] deep link to this code's entry in the error reference.
+    attr_reader :doc_url
+    # @return [Hash{String => Array<String>}, nil] per-field validation errors,
+    #   present on 422 responses.
+    attr_reader :fields
+    # @return [String, nil] the request id — include it when contacting support.
+    attr_reader :request_id
+
+    # @api private
+    def initialize(message, status_code:, code:, hint: "", doc_url: "", fields: nil,
+                   request_id: nil)
+      # Surface the hint in the raised message itself — the fix should arrive
+      # with the failure, without a docs tab.
+      super(hint.nil? || hint.empty? ? message : "#{message} — #{hint}")
+      @status_code = status_code
+      @code = code
+      @hint = hint || ""
+      @doc_url = doc_url || ""
+      @fields = fields
+      @request_id = request_id
+    end
+
+    # Build the right {APIError} subclass from a raw response.
+    #
+    # @param status [Integer]
+    # @param body [Object, nil] the parsed JSON body (nil if it was not JSON).
+    # @param headers [#[]] response headers, looked up case-insensitively by
+    #   lowercase name.
+    # @return [APIError]
+    # @api private
+    def self.from_response(status, body, headers)
+      parsed = parse_error_body(body)
+      code = parsed[:code] || default_code_for_status(status)
+      message = parsed[:message] || "Request failed with status #{status}"
+      details = {
+        status_code: status,
+        code: code,
+        hint: parsed[:hint] || "",
+        doc_url: parsed[:doc_url] || "",
+        request_id: parsed[:request_id] || headers["x-request-id"],
+        fields: parsed[:fields],
+      }
+
+      klass = CLASS_FOR_STATUS[status] || (status >= 500 ? ServerError : APIError)
+      return klass.new(message, **details) unless status == 429
+
+      RateLimitError.new(
+        message,
+        retry_after: numeric(headers["retry-after"]),
+        limit: numeric(headers["x-ratelimit-limit"]),
+        remaining: numeric(headers["x-ratelimit-remaining"]),
+        **details,
+      )
+    end
+
+    # @api private
+    def self.default_code_for_status(status)
+      DEFAULT_CODE_FOR_STATUS.fetch(status, ErrorCode::SYSTEM_INTERNAL_ERROR)
+    end
+
+    # Pull `{ error: { code, message, hint, docUrl, fields }, meta: { requestId } }`
+    # out of a parsed body, tolerating any missing or malformed piece — a proxy
+    # 502 page must degrade to a clean error, never crash the parser.
+    #
+    # @api private
+    def self.parse_error_body(body)
+      return {} unless body.is_a?(Hash)
+
+      error = body["error"]
+      out = {}
+      if error.is_a?(Hash)
+        out[:code] = error["code"] if error["code"].is_a?(String)
+        out[:message] = error["message"] if error["message"].is_a?(String)
+        out[:hint] = error["hint"] if error["hint"].is_a?(String)
+        out[:doc_url] = error["docUrl"] if error["docUrl"].is_a?(String)
+        out[:fields] = error["fields"] if error["fields"].is_a?(Hash)
+      end
+      meta = body["meta"]
+      out[:request_id] = meta["requestId"] if meta.is_a?(Hash) && meta["requestId"].is_a?(String)
+      out
+    end
+
+    # @api private
+    def self.numeric(value)
+      return nil if value.nil?
+
+      Integer(value)
+    rescue ArgumentError, TypeError
+      Float(value, exception: false)
+    end
+
+    private_class_method :parse_error_body, :numeric
+  end
+
+  # 400 — the request could not be understood.
+  class BadRequestError < APIError; end
+  # 401 — missing, invalid, revoked, or wrong-environment API key.
+  class AuthenticationError < APIError; end
+  # 403 — valid key, but not allowed (missing scope, foreign resource).
+  class PermissionDeniedError < APIError; end
+  # 404 — no resource at that id in this environment.
+  class NotFoundError < APIError; end
+  # 409 — conflicts with current state (including idempotency in-progress/reuse).
+  class ConflictError < APIError; end
+  # 422 — one or more fields invalid; see {APIError#fields}.
+  class ValidationError < APIError; end
+  # 5xx — something failed on NombaOne's side; safe to retry (the SDK already did).
+  class ServerError < APIError; end
+
+  # 429 — slow down; retry after {#retry_after} seconds. The SDK retries these
+  # automatically, honoring `Retry-After`.
+  class RateLimitError < APIError
+    # @return [Integer, Float, nil] seconds until the rate-limit window rolls
+    #   over (`Retry-After`).
+    attr_reader :retry_after
+    # @return [Integer, Float, nil] your request cap (`X-RateLimit-Limit`).
+    attr_reader :limit
+    # @return [Integer, Float, nil] requests left in the window
+    #   (`X-RateLimit-Remaining`).
+    attr_reader :remaining
+
+    # @api private
+    def initialize(message, retry_after: nil, limit: nil, remaining: nil, **details)
+      super(message, **details)
+      @retry_after = retry_after
+      @limit = limit
+      @remaining = remaining
+    end
+  end
+
+  # The request never completed — DNS failure, connection reset, or a
+  # caller-initiated cancellation.
+  class ConnectionError < Error; end
+
+  # A single attempt exceeded its timeout budget. Retried automatically.
+  class TimeoutError < ConnectionError; end
+
+  # Webhook signature or timestamp verification failed. Reject the delivery.
+  class WebhookVerificationError < Error; end
+
+  class APIError
+    # Subclass dispatch by HTTP status (429 is special-cased in `from_response`).
+    CLASS_FOR_STATUS = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => ValidationError,
+    }.freeze
+
+    # The code to assume when the error body is missing or unusable.
+    DEFAULT_CODE_FOR_STATUS = {
+      400 => ErrorCode::CLIENT_INVALID_REQUEST,
+      401 => ErrorCode::API_KEY_INVALID,
+      403 => ErrorCode::CLIENT_FORBIDDEN,
+      404 => ErrorCode::CLIENT_RESOURCE_NOT_FOUND,
+      409 => ErrorCode::CLIENT_CONFLICT,
+      422 => ErrorCode::CLIENT_VALIDATION_FAILED,
+      429 => ErrorCode::RATE_LIMIT_EXCEEDED,
+      502 => ErrorCode::SYSTEM_UPSTREAM_ERROR,
+      503 => ErrorCode::SYSTEM_UPSTREAM_ERROR,
+      504 => ErrorCode::SYSTEM_UPSTREAM_ERROR,
+    }.freeze
+  end
+end

data/lib/nombaone/internal/http_client.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "openssl"
+
+module Nombaone
+  module Internal
+    # One raw HTTP round-trip's outcome: status, lower-cased headers, and the
+    # unparsed body string.
+    Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+    # What the transport hands back on success: the unwrapped `data`, optional
+    # cursor `pagination`, the `request_id`, and the raw {Response}.
+    Result = Struct.new(:data, :pagination, :request_id, :response, keyword_init: true)
+
+    # The default connection: a single `Net::HTTP` round-trip. Returns a
+    # {Response} for **any** HTTP status (2xx, 4xx, 5xx alike) and raises only
+    # on transport failure — a timeout ({Nombaone::TimeoutError}) or an
+    # unreachable/broken connection ({Nombaone::ConnectionError}). Distinguishing
+    # our own read timeout (a specific `Net::*Timeout`) from a caller's own
+    # `Timeout.timeout` (a bare `Timeout::Error`, left to propagate) is what
+    # lets the SDK retry the former and never retry the latter.
+    class NetHTTPConnection
+      METHOD_CLASSES = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete,
+      }.freeze
+
+      # @return [Nombaone::Internal::Response]
+      # @raise [Nombaone::TimeoutError, Nombaone::ConnectionError]
+      def execute(method:, url:, headers:, body:, timeout:)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+        response = http.request(build_request(method, uri, headers, body))
+        Response.new(status: response.code.to_i, headers: header_hash(response),
+                     body: response.body)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+        raise Nombaone::TimeoutError, "The request to NombaOne timed out after #{timeout}s."
+      rescue SocketError, SystemCallError, OpenSSL::SSL::SSLError, IOError,
+             Net::HTTPBadResponse, Net::ProtocolError => e
+        raise Nombaone::ConnectionError, "Could not reach the NombaOne API: #{e.message}"
+      end
+
+      private
+
+      def build_request(method, uri, headers, body)
+        klass = METHOD_CLASSES.fetch(method) { raise ArgumentError, "unsupported method #{method}" }
+        request = klass.new(uri)
+        headers.each { |name, value| request[name] = value }
+        request.body = body unless body.nil?
+        request
+      end
+
+      def header_hash(response)
+        headers = {}
+        response.each_header { |name, value| headers[name.downcase] = value }
+        headers
+      end
+    end
+
+    # Executes one logical API call: builds the request, runs the retry loop,
+    # parses the response envelope, and returns a {Result} or raises a typed
+    # error.
+    #
+    # Money-safety invariants enforced here and nowhere else:
+    #
+    # * The `Idempotency-Key` for a POST is computed **once, before the retry
+    #   loop**, so every automatic retry replays the same logical operation
+    #   instead of creating a new one.
+    # * A caller-initiated cancellation is never retried; only timeouts,
+    #   connection failures, 408/429/5xx, and our own in-flight idempotency
+    #   conflict are.
+    class HTTPClient
+      # The version prefix is applied here, at exactly one place — never in a
+      # resource path.
+      API_PREFIX = "/v1"
+
+      # Statuses retried unconditionally (409 is retried only for
+      # `IDEMPOTENCY_IN_PROGRESS`, handled in {#retryable?}).
+      RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+
+      # @api private
+      def initialize(api_key:, base_url:, timeout:, max_retries:, connection:,
+                     default_headers: nil, sleeper: nil)
+        @api_key = api_key
+        @base_url = base_url
+        @timeout = timeout
+        @max_retries = max_retries
+        @connection = connection
+        @default_headers = default_headers
+        @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      end
+
+      # @param method [Symbol] :get :post :patch :put :delete
+      # @param path [String] path below `/v1`, segments already encoded.
+      # @param query [Hash{String => String}, nil] wire-ready query params.
+      # @param body [Hash, nil] wire-ready (camelCase) body, or nil for no body.
+      # @param options [Hash] per-call options (idempotency_key, headers,
+      #   timeout, max_retries, cancel_when).
+      # @return [Nombaone::Internal::Result]
+      def request(method:, path:, query: nil, body: nil, options: nil)
+        options ||= {}
+        timeout = options[:timeout] || @timeout
+        max_retries = [options[:max_retries] || @max_retries, 0].max
+        cancel_when = options[:cancel_when]
+
+        url = build_url(path, query)
+        headers = build_headers(method, body, options)
+        payload = body.nil? ? nil : JSON.generate(body)
+
+        attempt = 0
+        loop do
+          raise_if_canceled(cancel_when)
+
+          begin
+            response = @connection.execute(
+              method: method, url: url, headers: headers, body: payload, timeout: timeout,
+            )
+          rescue Nombaone::TimeoutError, Nombaone::ConnectionError => e
+            raise e if attempt >= max_retries
+
+            wait(Util.backoff_seconds(attempt))
+            attempt += 1
+            next
+          end
+
+          parsed = parse_json(response.body)
+          return build_result(response, parsed) if success_status?(response.status)
+
+          error = APIError.from_response(response.status, parsed, response.headers)
+          raise error unless attempt < max_retries && retryable?(response.status, error)
+
+          retry_after = Util.retry_after_seconds(response.headers["retry-after"])
+          wait(retry_after || Util.backoff_seconds(attempt))
+          attempt += 1
+        end
+      end
+
+      private
+
+      def build_url(path, query)
+        url = "#{@base_url}#{API_PREFIX}#{path}"
+        return url if query.nil? || query.empty?
+
+        "#{url}?#{URI.encode_www_form(query)}"
+      end
+
+      def build_headers(method, body, options)
+        computed = {
+          "authorization" => "Bearer #{@api_key}",
+          "accept" => "application/json",
+          "user-agent" => "nombaone-ruby/#{Nombaone::VERSION}",
+        }
+        computed["content-type"] = "application/json" unless body.nil?
+        if method == :post
+          computed["idempotency-key"] = options[:idempotency_key] || Util.generate_idempotency_key
+        end
+        Util.merge_headers(computed, @default_headers, options[:headers])
+      end
+
+      def success_status?(status)
+        status.between?(200, 299)
+      end
+
+      def retryable?(status, error)
+        RETRYABLE_STATUSES.include?(status) ||
+          (status == 409 && error.code == ErrorCode::IDEMPOTENCY_IN_PROGRESS)
+      end
+
+      def raise_if_canceled(cancel_when)
+        return unless cancel_when.respond_to?(:call) && cancel_when.call
+
+        raise Nombaone::ConnectionError, "The request was canceled before it completed."
+      end
+
+      def wait(seconds)
+        @sleeper.call(seconds) if seconds&.positive?
+      end
+
+      def parse_json(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def build_result(response, parsed)
+        unless parsed.is_a?(Hash) && parsed["success"] == true && parsed.key?("data")
+          raise APIError.new(
+            "The API returned a response that was not a valid NombaOne envelope.",
+            status_code: response.status,
+            code: ErrorCode::SYSTEM_INTERNAL_ERROR,
+            request_id: response.headers["x-request-id"],
+          )
+        end
+
+        request_id = parsed.dig("meta", "requestId")
+        request_id = response.headers["x-request-id"] unless request_id.is_a?(String)
+
+        Result.new(
+          data: parsed["data"],
+          pagination: parse_pagination(parsed["pagination"]),
+          request_id: request_id,
+          response: response,
+        )
+      end
+
+      def parse_pagination(raw)
+        return nil unless raw.is_a?(Hash) && [true, false].include?(raw["hasMore"])
+
+        {
+          limit: raw["limit"].is_a?(Integer) ? raw["limit"] : 0,
+          has_more: raw["hasMore"],
+          next_cursor: raw["nextCursor"].is_a?(String) ? raw["nextCursor"] : nil,
+        }
+      end
+    end
+  end
+end

data/lib/nombaone/internal/util.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "cgi"
+require "time"
+
+module Nombaone
+  # @api private
+  # Internal building blocks. Nothing here is part of the public API; it may
+  # change between minor versions.
+  module Internal
+    # Sentinel for "the caller did not supply this optional argument."
+    #
+    # Optional keyword params default to {OMIT}. A key left as {OMIT} is
+    # dropped from the request body entirely; an explicit `nil` is preserved
+    # and sent as JSON `null` (the documented way to *clear* a nullable field
+    # such as a customer's phone). This is the one reliable way in Ruby to tell
+    # "absent" apart from "explicitly null."
+    OMIT = Object.new
+    OMIT.define_singleton_method(:inspect) { "#<Nombaone omitted>" }
+    OMIT.freeze
+
+    # Pure, dependency-free helpers shared across the transport and resources.
+    module Util
+      module_function
+
+      # Keys whose *values* are arbitrary user JSON and must never have their
+      # inner keys rewritten (a customer's `metadata`, a sandbox webhook
+      # `payload`). The key name itself is still normalized (both are already
+      # single words, so normalization is a no-op).
+      PRESERVE_VALUE_KEYS = %w[metadata payload].freeze
+
+      # Convert a snake_case key to the camelCase name the wire expects.
+      # The wire field name is law; this is the single place the SDK's
+      # idiomatic Ruby names become it (`customer_id` → `customerId`,
+      # `amount_in_kobo` → `amountInKobo`, `plan_ref` → `planRef`).
+      #
+      # @param key [String, Symbol]
+      # @return [String]
+      def camelize(key)
+        parts = key.to_s.split("_")
+        return parts.first.to_s if parts.length <= 1
+
+        head, *tail = parts
+        (head + tail.map { |word| word.empty? ? "" : word[0].upcase + word[1..] }.join)
+      end
+
+      # Recursively rewrite Hash keys to camelCase, except that the value of a
+      # {PRESERVE_VALUE_KEYS} key is passed through untouched.
+      #
+      # @param value [Object]
+      # @return [Object]
+      def deep_camelize_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, val), out|
+            out[camelize(key)] =
+              PRESERVE_VALUE_KEYS.include?(key.to_s) ? val : deep_camelize_keys(val)
+          end
+        when Array
+          value.map { |item| deep_camelize_keys(item) }
+        else
+          value
+        end
+      end
+
+      # Prepare a request body hash for the wire: drop omitted keys (keeping
+      # explicit `nil`s so nullable fields can be cleared), then camelize.
+      #
+      # @param hash [Hash]
+      # @return [Hash]
+      def serialize_body(hash)
+        deep_camelize_keys(hash.reject { |_, v| OMIT.equal?(v) })
+      end
+
+      # Prepare query params: drop omitted **and** nil filters (an absent
+      # filter, not a null one), camelize keys, and stringify values.
+      #
+      # @param hash [Hash]
+      # @return [Hash{String => String}]
+      def serialize_query(hash)
+        hash.each_with_object({}) do |(key, value), out|
+          next if OMIT.equal?(value) || value.nil?
+
+          out[camelize(key)] = value.to_s
+        end
+      end
+
+      # Percent-encode one URL path segment. Ids come from user input, so they
+      # are never trusted raw; this matches JavaScript's `encodeURIComponent`
+      # for the characters that appear in NombaOne ids.
+      #
+      # @param value [String]
+      # @return [String]
+      def encode_path_segment(value)
+        CGI.escape(value.to_s).gsub("+", "%20")
+      end
+
+      # A fresh idempotency key for one logical POST. Computed once, before the
+      # retry loop, so every automatic retry replays the same operation.
+      #
+      # @return [String]
+      def generate_idempotency_key
+        SecureRandom.uuid
+      end
+
+      # Full-jitter exponential backoff, in seconds: a random delay in
+      # `[0, min(8, 0.5 * 2**attempt))`. Jitter keeps a fleet of retrying
+      # clients from stampeding the API in lockstep.
+      #
+      # @param attempt [Integer] zero-based attempt index.
+      # @return [Float]
+      def backoff_seconds(attempt)
+        rand * [8.0, 0.5 * (2**attempt)].min
+      end
+
+      # Parse a `Retry-After` header into seconds. Accepts delta-seconds or an
+      # HTTP-date; returns nil when absent or unparseable so the caller falls
+      # back to its own backoff.
+      #
+      # @param raw [String, nil]
+      # @return [Float, nil]
+      def retry_after_seconds(raw)
+        return nil if raw.nil?
+
+        seconds = Float(raw, exception: false)
+        return [seconds, 0.0].max if seconds
+
+        date = begin
+          Time.httpdate(raw)
+        rescue ArgumentError
+          nil
+        end
+        date ? [date - Time.now, 0.0].max : nil
+      end
+
+      # Merge header layers left-to-right; later layers win. A `nil` value
+      # deletes a header (lets a caller strip an SDK default for one request).
+      # Header names are case-insensitive, so everything is lowercased once.
+      #
+      # @param layers [Array<Hash, nil>]
+      # @return [Hash{String => String}]
+      def merge_headers(*layers)
+        layers.each_with_object({}) do |layer, out|
+          next unless layer
+
+          layer.each do |name, value|
+            key = name.to_s.downcase
+            value.nil? ? out.delete(key) : out[key] = value.to_s
+          end
+        end
+      end
+    end
+  end
+end