dinie-sdk-sandbox 1.1.0

data/lib/dinie/runtime/errors.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Dinie
+  # Root of every error the SDK raises.
+  class Error < StandardError; end
+
+  # Base for everything that originates from talking to the Dinie API.
+  #
+  # `code` and `request_id` are first-class here so every API error answers them (a
+  # connection error simply carries `nil`). The extraction logic that reads them off the
+  # RFC 9457 body / response headers lives once in {APIStatusError}, never per marker
+  # class — mirroring the V0.2 freeze and the future generator's "emit once into the base".
+  class APIError < Error
+    # @return [String, nil] machine-readable error code from the Problem Details `code` extension
+    attr_reader :code
+
+    # @return [String, nil] per-request correlation id (from `x-request-id`, body fallback)
+    attr_reader :request_id
+
+    # @param message [String, nil]
+    # @param code [String, nil]
+    # @param request_id [String, nil]
+    def initialize(message = nil, code: nil, request_id: nil)
+      super(message)
+      @code = code
+      @request_id = request_id
+    end
+  end
+
+  # A request never produced a response (DNS failure, socket reset, timeout…). Client-side:
+  # there is no server response to describe, so it lives in `runtime/`.
+  class APIConnectionError < APIError
+    # @param message [String]
+    def initialize(message = "Connection error.")
+      super
+    end
+  end
+
+  # The request exceeded the configured timeout.
+  class APITimeoutError < APIConnectionError
+    # @param message [String]
+    def initialize(message = "Request timed out.")
+      super
+    end
+  end
+
+  # The API returned a non-2xx response. Base of the openapi-mirrored marker catalog
+  # (`generated/errors/registry.rb`); the markers are empty subclasses and inherit this
+  # constructor, so {Internal::Errors.from_response} can build any of them uniformly.
+  class APIStatusError < APIError
+    # @return [Integer] HTTP status code
+    attr_reader :status
+    # @return [Hash] raw response headers
+    attr_reader :headers
+    # @return [Hash, String, nil] parsed Problem Details, raw body text, or nil
+    attr_reader :body
+    # @return [String, nil] Problem Details `type` URL
+    attr_reader :type
+    # @return [String, nil] Problem Details `title`
+    attr_reader :title
+    # @return [String, nil] Problem Details `detail`
+    attr_reader :detail
+    # @return [String, nil] Problem Details `instance`
+    attr_reader :instance
+
+    # @param status [Integer]
+    # @param body [Hash, String, nil] parsed Problem Details (symbol keys), raw text, or nil
+    # @param headers [Hash]
+    # @param request_id [String, nil]
+    def initialize(status:, body:, headers:, request_id: nil)
+      @status = status
+      @headers = headers
+      @body = body
+      problem = body.is_a?(Hash) ? body : nil
+      @type = string_field(problem, :type)
+      @title = string_field(problem, :title)
+      @detail = string_field(problem, :detail)
+      @instance = string_field(problem, :instance)
+      super(self.class.build_message(status, body, request_id),
+            code: string_field(problem, :code), request_id: request_id)
+    end
+
+    # @api private
+    # @return [String]
+    def self.build_message(status, body, request_id)
+      summary = message_summary(body)
+      suffix = request_id.nil? ? "" : " (request_id: #{request_id})"
+      summary ? "#{status} #{summary}#{suffix}" : "#{status} status code (no body)#{suffix}"
+    end
+
+    # @api private
+    def self.message_summary(body)
+      if body.is_a?(Hash)
+        body[:detail] || body[:title]
+      elsif body.is_a?(String) && !body.empty?
+        body
+      end
+    end
+    private_class_method :message_summary
+
+    private
+
+    def string_field(problem, key)
+      return nil unless problem
+
+      value = problem[key]
+      value.is_a?(String) ? value : nil
+    end
+  end
+
+  # ── Client-side errors (outside the APIError tree — no server response) ────────
+
+  # OAuth2 client-credentials token acquisition/refresh failed.
+  class OAuthError < Error; end
+
+  # A session-mode token was successfully exchanged once but has since expired (via
+  # {Dinie::Internal::TokenManager#invalidate!} or TTL). Session tokens are single-use:
+  # once expired the original authorization code cannot be re-exchanged. Callers should
+  # surface this to the consumer so they can obtain a fresh code.
+  class SessionTokenExpiredError < Error; end
+
+  # A webhook payload failed HMAC signature verification.
+  class WebhookSignatureError < Error; end
+
+  # A webhook timestamp fell outside the tolerance window.
+  class WebhookTimestampError < Error; end
+
+  # A webhook signature verified, but the payload's `type` is not in the openapi event
+  # catalog, so there is no per-type deserializer for it. Raising (rather than passing the
+  # raw event through) is deliberate — a new event `type` is a contract change. The
+  # unrecognized `type` is preserved on {#event_type}.
+  class UnknownWebhookEventError < Error
+    # @return [String] the unrecognized (but verified) webhook event `type`
+    attr_reader :event_type
+
+    # @param event_type [String]
+    def initialize(event_type)
+      @event_type = event_type
+      super("Unknown webhook event type: #{event_type.inspect}. It is not in the openapi event " \
+            "catalog (generated/events). If Dinie added a new event type, the SDK must be updated " \
+            "from the contract before it can deserialize this payload.")
+    end
+  end
+
+  # Parse a `Retry-After` value to **seconds**, capped at 60 (architecture §7/§10).
+  #
+  # Precedence mirrors the retry loop: a `Retry-After-Ms` value (milliseconds) wins, then
+  # `Retry-After` as delta-seconds, then `Retry-After` as an HTTP-date (delta from now).
+  # Each argument accepts a String or an Array (the first element is used, for repeated
+  # headers). A past HTTP-date clamps to 0; an abusive value clamps to 60. Returns the wait
+  # in seconds (Float) or `nil` when nothing parseable was given.
+  #
+  # Public runtime helper, consumed by the transport's retry loop (story 003) and usable in
+  # custom post-`RateLimitError` logic.
+  #
+  # @param retry_after [String, Array<String>, nil] the `Retry-After` header value
+  # @param retry_after_ms [String, Array<String>, nil] the `Retry-After-Ms` header value
+  # @return [Float, nil] seconds to wait (0..60), or nil
+  def self.parse_retry_after(retry_after = nil, retry_after_ms: nil)
+    seconds = retry_after_ms_seconds(retry_after_ms) || retry_after_seconds(retry_after)
+    return nil if seconds.nil?
+
+    seconds.clamp(0.0, RETRY_AFTER_CAP_SECONDS.to_f)
+  end
+
+  # Maximum honored `Retry-After`, in seconds (architecture §10 — verbatim from the V0.2 freeze).
+  RETRY_AFTER_CAP_SECONDS = 60
+
+  # @api private
+  def self.retry_after_ms_seconds(value)
+    raw = first_header_value(value)
+    return nil if raw.nil?
+
+    ms = Float(raw, exception: false)
+    ms.nil? ? nil : ms / 1000.0
+  end
+
+  # @api private
+  def self.retry_after_seconds(value)
+    raw = first_header_value(value)&.strip
+    return nil if raw.nil? || raw.empty?
+
+    seconds = Float(raw, exception: false)
+    return seconds if seconds
+
+    http_date_delta(raw)
+  end
+
+  # @api private
+  def self.http_date_delta(raw)
+    Time.httpdate(raw) - Time.now
+  rescue ArgumentError
+    nil
+  end
+
+  # @api private
+  def self.first_header_value(value)
+    raw = value.is_a?(Array) ? value.first : value
+    raw&.to_s
+  end
+
+  private_class_method :retry_after_ms_seconds, :retry_after_seconds, :http_date_delta, :first_header_value
+
+  module Internal
+    # The transport-agnostic error dispatcher. Builds the right {Dinie::APIError} from an
+    # HTTP error response and reads the RFC 9457 Problem Details body.
+    #
+    # This is the controlled runtime → generated seam (architecture §4): it references the
+    # **generated** constant {Dinie::Internal::ERROR_REGISTRY} (defined in
+    # `generated/errors/registry.rb`). The reference is the forcing-function — if the error
+    # surface changes without regenerating the table, dispatch specs break. The runtime
+    # never `require`s the generated layer; the barrel loads the registry before any call.
+    module Errors
+      # Header carrying the per-request correlation id, surfaced as `error.request_id`.
+      REQUEST_ID_HEADER = "x-request-id"
+
+      module_function
+
+      # Build the typed error for an HTTP error response: dispatch by Problem Details `type`
+      # URL, then by HTTP status, then by the ≥500 band fallback. The body is parsed as JSON
+      # once (symbol keys); a non-JSON body is preserved as raw text.
+      #
+      # @param status [Integer] HTTP status code
+      # @param headers [Hash] response headers
+      # @param body [String, nil] raw response body
+      # @param force [Class, nil] when given, skip dispatch and build this exact class
+      #   (used by the transport to guarantee an `AuthError` on a persistent 401)
+      # @return [Dinie::APIStatusError]
+      def from_response(status:, headers: {}, body: nil, force: nil)
+        record = parse_problem(body)
+        type_url = string_value(record, :type)
+        request_id = header_request_id(headers) || string_value(record, :request_id)
+        ctor = force || dispatch(type_url, status)
+        ctor.new(status: status, body: record || presentable_body(body), headers: headers || {},
+                 request_id: request_id)
+      end
+
+      # @api private
+      def dispatch(type_url, status)
+        registry = Dinie::Internal::ERROR_REGISTRY
+        (type_url && registry[:by_type][type_url]) ||
+          registry[:by_status][status] ||
+          fallback_ctor(status)
+      end
+
+      # @api private
+      def fallback_ctor(status)
+        return Dinie::Internal::ERROR_REGISTRY[:fallback_5xx] if status >= 500
+
+        Dinie::APIStatusError
+      end
+
+      # @api private
+      def parse_problem(body)
+        return nil unless body.is_a?(String) && !body.empty?
+
+        parsed = JSON.parse(body, symbolize_names: true)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      # @api private
+      def presentable_body(body)
+        body.is_a?(String) && !body.empty? ? body : nil
+      end
+
+      # @api private
+      def header_request_id(headers)
+        value = header_lookup(headers, REQUEST_ID_HEADER)
+        value.is_a?(Array) ? value.first : value
+      end
+
+      # @api private
+      def header_lookup(headers, name)
+        return nil unless headers.respond_to?(:each)
+
+        target = name.downcase
+        headers.each { |key, value| return value if key.to_s.downcase == target }
+        nil
+      end
+
+      # @api private
+      def string_value(record, key)
+        return nil unless record
+
+        value = record[key]
+        value.is_a?(String) ? value : nil
+      end
+    end
+  end
+end

data/lib/dinie/runtime/http.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "faraday"
+require "faraday/multipart"
+require "faraday/net_http_persistent"
+require_relative "multipart"
+
+module Dinie
+  module Internal
+    # `HttpClient` — the request-lifecycle orchestrator and heart of the runtime (architecture
+    # §10, RB15), porting `sdk-js` `src/runtime/http.ts`. It owns one `Faraday::Connection` per
+    # {Dinie::Client} (adapter `:net_http_persistent` — a real connection pool with keep-alive,
+    # thread-safe) and, for every logical request, runs the full lifecycle:
+    #
+    #   1. mint an `X-Idempotency-Key` ONCE, before the loop, for non-GET writes, so every
+    #      retry of the same logical request reuses it (never a duplicate resource);
+    #   2. obtain a Bearer token from the injected `TokenManager`;
+    #   3. assemble headers (auth, telemetry, idempotency, retry-count, content-type);
+    #   4. dispatch through Faraday — **one round-trip per call**; the retry loop is ours;
+    #   5. fold `X-RateLimit-*` headers into the snapshot `client.rate_limit` reads;
+    #   6. on success (< 300), parse and return the raw body (resources deserialize);
+    #   7. on 401, run the one-shot re-auth (`token_manager.invalidate!` + a fresh token), then
+    #      give up with `AuthError` if a second 401 follows (no loop);
+    #   8. on a retryable status (`{408,429,500,502,503,504}`) or a transient transport error,
+    #      back off (`Retry.retry_delay`) and retry while attempts remain, bumping
+    #      `X-Dinie-Retry-Count`;
+    #   9. otherwise map the response to a typed error via {Errors.from_response}.
+    #
+    # ── DI seam (architecture §10, RB15) ──
+    # The `TokenManager` is **injected** (`HttpClient.new(token_manager:, …)`). Story 004 builds
+    # the real, concurrency-safe one; specs inject a fake. `auth_headers` is `token_manager
+    # .access_token`; the 401 one-shot is `token_manager.invalidate!`. No global/singleton, no
+    # placeholder hack — this is what lets `with_options` (story 004) clone a client while
+    # sharing the same token cache.
+    #
+    # ── controlled runtime → generated seam (openapi-SoT forcing function, architecture §4) ──
+    # The rule is "runtime/ never imports generated/". This module is one declared exception:
+    # it references {Dinie::AuthError} (forced on a persistent 401) and dispatches non-2xx
+    # responses through {Errors.from_response}, which reads the **generated**
+    # {Dinie::Internal::ERROR_REGISTRY}. The reference is the forcing function — an error not in
+    # `openapi.yaml` is not in `generated/`, so there is nowhere to dispatch it.
+    #
+    # Runtime-internal: {Dinie::Client} and the resources construct and call it; it is not part
+    # of the public SDK surface.
+    #
+    # The ClassLength cop is disabled below: the request lifecycle (prepare → loop → dispatch →
+    # error/retry/re-auth → parse) is one cohesive orchestrator; splitting it across classes would
+    # scatter the lifecycle and obscure the parity with `sdk-js` `http.ts`.
+    class HttpClient # rubocop:disable Metrics/ClassLength
+      # Default production API base URL — carries the `/api/v3` version prefix (openapi
+      # `servers[0]`). Resource paths are bare (`/customers`), so the version lives here.
+      DEFAULT_BASE_URL = "https://api.dinie.com.br/api/v3"
+      # Default per-request timeout, in **seconds** (RB17 — Faraday idiom; the TS SDK uses ms).
+      DEFAULT_TIMEOUT_SECONDS = 30
+      # Default retry budget after the first attempt.
+      DEFAULT_MAX_RETRIES = 3
+      # `Content-Type` for JSON request bodies.
+      JSON_CONTENT_TYPE = "application/json"
+      # Methods that auto-carry an `X-Idempotency-Key` when the caller does not say otherwise.
+      AUTO_IDEMPOTENT_METHODS = %i[post patch].freeze
+      # `User-Agent` sent on every request (architecture §5.1, telemetry AC). The api-version comes
+      # from the generated constant {Dinie::Generated::API_VERSION} (== openapi info.version).
+      USER_AGENT = format(
+        "Dinie-SDK-Ruby/%<sdk>s (api-version=%<api>s; ruby/%<rt>s)",
+        sdk: Dinie::VERSION, api: Dinie::Generated::API_VERSION, rt: RUBY_VERSION
+      ).freeze
+
+      # Normalized, per-call request descriptor threaded through the retry loop. Keeping it in
+      # one struct holds the helper signatures small (and the body is serialized once, up front).
+      # `http_method` (not `method`) avoids shadowing `Object#method`.
+      PreparedRequest = Struct.new(
+        :http_method, :url, :body, :content_type, :idempotency_key, :max_retries, :timeout, :header_overrides,
+        keyword_init: true
+      )
+      private_constant :PreparedRequest
+
+      # @param token_manager [#access_token, #invalidate!] injected OAuth2 token source (story 004)
+      # @param base_url [String, nil] API base URL (default {DEFAULT_BASE_URL})
+      # @param timeout [Numeric] per-request timeout in seconds (default {DEFAULT_TIMEOUT_SECONDS})
+      # @param max_retries [Integer] retry budget after the first attempt (default {DEFAULT_MAX_RETRIES})
+      # @param idempotency [Boolean] auto-generate `X-Idempotency-Key` on POST/PATCH (default true)
+      # @param adapter [Symbol, nil] Faraday adapter (default `:net_http_persistent`)
+      # @param connection [Faraday::Connection, nil] injected connection (pool-sharing/test seam);
+      #   requests use absolute URLs, so its `url_prefix` is irrelevant
+      # @param sleeper [#call, nil] backoff sleep (tests inject an instant, recording spy)
+      def initialize(token_manager:, base_url: nil, timeout: DEFAULT_TIMEOUT_SECONDS, # rubocop:disable Metrics/ParameterLists
+                     max_retries: DEFAULT_MAX_RETRIES, idempotency: true, adapter: nil,
+                     connection: nil, sleeper: nil)
+        @token_manager = token_manager
+        @base_url = (base_url || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+        @timeout = timeout
+        @max_retries = max_retries
+        @idempotency = idempotency
+        @rate_limit_tracker = RateLimitTracker.new
+        @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+        @connection = connection || build_connection(adapter)
+      end
+
+      # Latest rate-limit snapshot (read by `client.rate_limit`); `nil` before the first
+      # response that carried valid `X-RateLimit-*` headers.
+      #
+      # @return [Dinie::RateLimit, nil]
+      def rate_limit
+        @rate_limit_tracker.snapshot
+      end
+
+      # Run one logical request end-to-end and return the parsed body (resources deserialize it).
+      # `204`/empty bodies return `nil`; a JSON body is parsed with symbol keys; a non-JSON body
+      # is returned as raw text.
+      #
+      # @param method [Symbol, String] HTTP method (`:get`, `:post`, `:patch`, `:delete`, …)
+      # @param path [String] bare resource path (e.g. `/customers`); the base URL adds `/api/v3`
+      # @param query [Hash, nil] query params (`nil` values are dropped)
+      # @param body [Object, nil] request body (Hash/Array → JSON; String passed through)
+      # @param idempotent [Boolean, nil] force/suppress the idempotency key; `nil` ⇒ auto on POST/PATCH
+      # @param request_options [Dinie::Internal::RequestOptions, Hash, nil] per-call overrides
+      # @return [Object, nil] the parsed response body
+      # @raise [Dinie::APIStatusError] a typed error for any non-2xx that is not retried
+      # @raise [Dinie::AuthError] a 401 that persists after the one-shot re-auth
+      # @raise [Dinie::APITimeoutError] the request timed out and the retry budget is exhausted
+      # @raise [Dinie::APIConnectionError] a transport failure
+      def request(method:, path:, query: nil, body: nil, idempotent: nil, request_options: nil) # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        options = RequestOptions.coerce(request_options)
+        normalized_method = method.to_s.downcase.to_sym
+        serialized_body, content_type = serialize_body(body)
+        execute(PreparedRequest.new(
+                  http_method: normalized_method,
+                  url: build_full_url(path, query),
+                  body: serialized_body,
+                  content_type: content_type,
+                  idempotency_key: resolve_idempotency_key(idempotent, normalized_method, options),
+                  max_retries: options.max_retries || @max_retries,
+                  timeout: options.timeout || @timeout,
+                  header_overrides: options.headers
+                ))
+      end
+
+      private
+
+      # The retry loop. `attempt` increments on every continued path (a transport retry, a
+      # status retry, AND the 401 one-shot), so `X-Dinie-Retry-Count` mirrors the TS SDK exactly.
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
+      def execute(prepared)
+        attempt = 0
+        reauthed = false
+        loop do
+          token = @token_manager.access_token
+          headers = build_headers(prepared, token, attempt)
+
+          begin
+            response = dispatch(prepared, headers)
+          rescue Faraday::Error => e
+            raise translate_network_error(e) unless Retry.retryable_network_error?(e) && attempt < prepared.max_retries
+
+            sleep_for(Retry.retry_delay(attempt))
+            attempt += 1
+            next
+          end
+
+          @rate_limit_tracker.update(response.headers)
+          status = response.status
+          return parse_body(response) if status < 300
+
+          # 401 one-shot: drop the cached token, re-auth once, retry.
+          if status == 401 && !reauthed
+            @token_manager.invalidate!
+            reauthed = true
+            attempt += 1
+            next
+          end
+          # Persistent 401 after the one-shot: give up with a typed AuthError (no loop). Forcing
+          # the class guarantees the type even if the body lacks the openapi `type` URL.
+          raise build_error(response, force: Dinie::AuthError) if status == 401
+
+          if Retry.should_retry?(status) && attempt < prepared.max_retries
+            sleep_for(Retry.retry_delay(attempt,
+                                        retry_after: header(response, "retry-after"),
+                                        retry_after_ms: header(response, "retry-after-ms")))
+            attempt += 1
+            next
+          end
+
+          raise build_error(response)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
+
+      # One Faraday round-trip. Absolute URL ⇒ the connection's `url_prefix` is irrelevant, so
+      # `base_url='…/api/v3'` never collides with a leading-slash resource path.
+      def dispatch(prepared, headers)
+        @connection.run_request(prepared.http_method, prepared.url, prepared.body, headers) do |req|
+          req.options.timeout = prepared.timeout
+          req.options.open_timeout = prepared.timeout
+        end
+      end
+
+      # Assemble the outgoing headers: Bearer auth, telemetry, the Idempotency-Key (when
+      # present), `X-Dinie-Retry-Count` on retries, and `Content-Type` when there is a body. A
+      # caller header with a `nil` value removes the matching default; any other value overrides.
+      def build_headers(prepared, token, attempt)
+        headers = base_headers(token)
+        headers["content-type"] = prepared.content_type unless prepared.content_type.nil?
+        headers["x-idempotency-key"] = prepared.idempotency_key unless prepared.idempotency_key.nil?
+        headers["x-dinie-retry-count"] = attempt.to_s if attempt.positive?
+        apply_header_overrides(headers, prepared.header_overrides)
+      end
+
+      # Auth + telemetry defaults present on every request (architecture §5.1).
+      def base_headers(token)
+        {
+          "authorization" => "Bearer #{token}",
+          "accept" => JSON_CONTENT_TYPE,
+          "user-agent" => USER_AGENT,
+          "x-dinie-sdk-language" => "ruby",
+          "x-dinie-sdk-version" => Dinie::VERSION,
+          "x-dinie-sdk-runtime" => "ruby/#{RUBY_VERSION}"
+        }
+      end
+
+      # Apply per-call header overrides: `nil` removes a default, any String replaces it.
+      def apply_header_overrides(headers, overrides)
+        return headers if overrides.nil?
+
+        overrides.each do |key, value|
+          lower = key.to_s.downcase
+          if value.nil?
+            headers.delete(lower)
+          else
+            headers[lower] = value
+          end
+        end
+        headers
+      end
+
+      # Resolve the `X-Idempotency-Key` (architecture §10). A per-call override always wins —
+      # even when auto-idempotency is opted out globally, an explicit key is an explicit opt-in.
+      # Otherwise a key is auto-minted for POST/PATCH unless opted out. `nil` ⇒ send no key.
+      def resolve_idempotency_key(idempotent, method, options)
+        idempotent = AUTO_IDEMPOTENT_METHODS.include?(method) if idempotent.nil?
+        return nil unless idempotent
+        return options.idempotency_key unless options.idempotency_key.nil?
+        return nil unless @idempotency
+
+        Idempotency.generate_key
+      end
+
+      # Serialize a request body: a {Multipart} becomes a Faraday multipart body tagged with a bare
+      # `multipart/form-data` content type (Faraday's `:multipart` middleware appends the boundary
+      # and encodes it — story 009); a Hash/Array → JSON; a String is assumed already-serialized
+      # JSON; `nil` sends no body. Returns `[body_or_nil, content_type_or_nil]`.
+      def serialize_body(body)
+        return [nil, nil] if body.nil?
+        return [body.to_faraday_body, Multipart::CONTENT_TYPE] if body.is_a?(Multipart)
+        return [body, JSON_CONTENT_TYPE] if body.is_a?(String)
+
+        [JSON.generate(body), JSON_CONTENT_TYPE]
+      end
+
+      # Read + parse a successful response body. `204`/empty ⇒ `nil`; JSON ⇒ parsed with symbol
+      # keys (resources read `raw[:field]`); non-JSON ⇒ raw text.
+      def parse_body(response)
+        return nil if response.status == 204
+
+        body = response.body
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body, symbolize_names: true)
+      rescue JSON::ParserError
+        body
+      end
+
+      # Prepend the base URL and append the query string. Absolute URLs sidestep Faraday's
+      # leading-slash base-path replacement (the trap `sdk-js` handles via `#basePath`).
+      def build_full_url(path, query)
+        url = "#{@base_url}#{path}"
+        encoded = encode_query(query)
+        return url if encoded.empty?
+
+        "#{url}#{path.include?("?") ? "&" : "?"}#{encoded}"
+      end
+
+      # Encode query params, dropping `nil` values.
+      def encode_query(query)
+        return "" if query.nil? || query.empty?
+
+        URI.encode_www_form(query.compact)
+      end
+
+      # First value of a (possibly repeated) response header.
+      def header(response, name)
+        value = response.headers[name]
+        value.is_a?(Array) ? value.first : value
+      end
+
+      # Build the typed error for a non-2xx response (story 002 dispatch). `body` is the raw
+      # String (JSON is parsed inside `from_response`); `force` skips dispatch (persistent 401).
+      def build_error(response, force: nil)
+        Errors.from_response(status: response.status, headers: response.headers.to_h,
+                             body: response.body, force: force)
+      end
+
+      # Map an exhausted/non-retryable transport error to the right connection-error class.
+      def translate_network_error(error)
+        return Dinie::APITimeoutError.new if error.is_a?(Faraday::TimeoutError)
+
+        Dinie::APIConnectionError.new(error.message)
+      end
+
+      def sleep_for(seconds)
+        @sleeper.call(seconds)
+      end
+
+      # Standalone fallback connection, used only when no `connection:` is injected (tests, direct
+      # use). The composed SDK always injects the SHARED connection built by {Dinie::Client}, which
+      # is where the story 005 logging middleware mounts (so it also observes the TokenManager's
+      # token POST). This builder is intentionally plain — do NOT mount logging here.
+      def build_connection(adapter)
+        Faraday.new(url: @base_url) do |faraday|
+          faraday.request(:multipart)
+          faraday.adapter(adapter || :net_http_persistent)
+        end
+      end
+    end
+  end
+end

data/lib/dinie/runtime/idempotency.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Dinie
+  module Internal
+    # Idempotency-Key generation (architecture §10, RB15; mirrors `sdk-js` `idempotency.ts`).
+    #
+    # One job: mint a fresh auto-generated key. The `dinie-sdk-retry-` prefix lets the Dinie
+    # backend tell an SDK-generated key apart from a partner-supplied one.
+    #
+    # The *policy* around the key lives in {HttpClient} (story 003), NOT here:
+    #   - only non-GET writes get one (auto on POST/PATCH),
+    #   - the key is generated ONCE before the retry loop, so every attempt of the same logical
+    #     request reuses it (a retry must never create a duplicate resource),
+    #   - a caller can override it via `request_options[:idempotency_key]`,
+    #   - the whole behavior can be opted out globally with `idempotency: false`.
+    #
+    # Runtime-internal: consumed directly by {HttpClient}, not part of the public surface.
+    module Idempotency
+      # Prefix marking a key as SDK-auto-generated (vs. partner-supplied) on the backend.
+      KEY_PREFIX = "dinie-sdk-retry-"
+
+      module_function
+
+      # A fresh auto-generated Idempotency-Key: `dinie-sdk-retry-<uuid v4>`.
+      #
+      # @return [String]
+      def generate_key
+        "#{KEY_PREFIX}#{SecureRandom.uuid}"
+      end
+    end
+  end
+end