dinie-sdk 1.0.0

data/sig/dinie/generated/types/customer_bank_account.rbs

@@ -0,0 +1,26 @@
+# `CustomerBankAccount` + the `CustomerBankAccountKind` enum module (architecture §3.3, §6).
+# Mirrors `lib/dinie/generated/types/customer_bank_account.rb`.
+
+module Dinie
+  module CustomerBankAccountKind
+    CHECKING: String
+    SAVING: String
+    PAYMENT: String
+    ALL: Array[String]
+  end
+
+  class CustomerBankAccount < Internal::Model
+    attr_reader bank_id: String
+    attr_reader bank_name: String
+    attr_reader branch: String
+    attr_reader digit: String
+    attr_reader id: bank_account_id
+    attr_reader kind: customer_bank_account_kind
+    attr_reader number: String
+    attr_reader updated_at: Integer
+
+    def self.deserialize: (Hash[Symbol, untyped] raw) -> CustomerBankAccount
+
+    def self.serialize_upsert: (bank_id: String, branch: String, digit: String, kind: String, number: String) -> Hash[Symbol, untyped]
+  end
+end

data/sig/dinie/generated/types/enums.rbs

@@ -0,0 +1,66 @@
+# Enum literal-union aliases + the named-constant modules (architecture §3.3). The wire value
+# surfaces as a plain `String`; RBS carries the literal union (the type TS encodes natively), and
+# the frozen constant modules name the values for discoverability. Aliases are doc-only (any
+# `String` is assignable); the unions document the closed set.
+
+module Dinie
+  type customer_status = "creating" | "pending_kyc" | "under_review" | "active" | "denied"
+  type credential_status = "active" | "revoked"
+  type credit_offer_status = "available" | "accepted" | "expired"
+  type loan_status = "awaiting_signatures" | "processing" | "active" | "finished" | "cancelled" | "error"
+  type transaction_status = "pending" | "paid" | "overdue" | "partially_paid"
+  type transaction_type = "installment"
+  type webhook_endpoint_status = "active" | "disabled"
+  type customer_bank_account_kind = "checking" | "saving" | "payment"
+
+  module CustomerStatus
+    CREATING: String
+    PENDING_KYC: String
+    UNDER_REVIEW: String
+    ACTIVE: String
+    DENIED: String
+    ALL: Array[String]
+  end
+
+  module CredentialStatus
+    ACTIVE: String
+    REVOKED: String
+    ALL: Array[String]
+  end
+
+  module CreditOfferStatus
+    AVAILABLE: String
+    ACCEPTED: String
+    EXPIRED: String
+    ALL: Array[String]
+  end
+
+  module LoanStatus
+    AWAITING_SIGNATURES: String
+    PROCESSING: String
+    ACTIVE: String
+    FINISHED: String
+    CANCELLED: String
+    ERROR: String
+    ALL: Array[String]
+  end
+
+  module TransactionStatus
+    PENDING: String
+    PAID: String
+    OVERDUE: String
+    PARTIALLY_PAID: String
+    ALL: Array[String]
+  end
+
+  module TransactionType
+    INSTALLMENT: String
+    ALL: Array[String]
+  end
+
+  module WebhookEndpointStatus
+    ACTIVE: String
+    DISABLED: String
+    ALL: Array[String]
+  end
+end

data/sig/dinie/generated/types/ids.rbs

@@ -0,0 +1,21 @@
+# Resource ID aliases (architecture §3.3). Ruby has no zero-cost nominal typing, so each prefixed
+# id is a plain `String`; the prefix/pattern lives in the contract + the conformance harness, and
+# here as a doc-only RBS alias (the `comparison.md` "nominal typing available" axis). `ID_PATTERNS`
+# is `Internal::` (not the frozen surface).
+
+module Dinie
+  # Doc-only id aliases (each resolves to `String`). The prefix is documented; not enforced by type.
+  type api_client_id = String         # `dinie_ci_…`
+  type bank_account_id = String       # `ba_…`
+  type credit_offer_id = String       # `co_…`
+  type customer_id = String           # `cust_…` (NOT `cus_`)
+  type event_id = String              # `evt_…`
+  type loan_id = String               # `ln_…`
+  type simulation_id = String         # `sim_…`
+  type transaction_id = String        # `tx_…`
+  type webhook_endpoint_id = String   # `we_…`
+
+  module Internal
+    ID_PATTERNS: Hash[Symbol, Regexp]
+  end
+end

data/sig/dinie/generated/types/kyc/attachment.rbs

@@ -0,0 +1,14 @@
+# `Kyc::AttachmentResponse` — the `POST /customers/{id}/kyc-attachments` response body
+# (architecture §6.3). Mirrors `lib/dinie/generated/types/kyc/attachment.rb`. Read-only.
+
+module Dinie
+  module Kyc
+    class AttachmentResponse < Internal::Model
+      attr_reader id: String
+      attr_reader requirement: Requirement
+      attr_reader uploaded_at: Integer
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> AttachmentResponse
+    end
+  end
+end

data/sig/dinie/generated/types/kyc/common.rbs

@@ -0,0 +1,42 @@
+# KYC shared leaf types + the dispatch error (architecture §6.3). Mirrors
+# `lib/dinie/generated/types/kyc/common.rb`. `Dinie::Kyc` is the complexity hotspot (~41 types).
+
+module Dinie
+  module Kyc
+    type kyc_review_status = "pending" | "accepted" | "rejected"
+    type kyc_subject_type = "applicant" | "co_owner"
+
+    module ReviewStatus
+      PENDING: String
+      ACCEPTED: String
+      REJECTED: String
+      ALL: Array[String]
+    end
+
+    module SubjectType
+      APPLICANT: String
+      CO_OWNER: String
+      ALL: Array[String]
+    end
+
+    # Identifies who a person-specific requirement is about (applicant or company co-owner).
+    class Subject < Internal::Model
+      attr_reader id: String
+      attr_reader name: String
+      attr_reader subject_type: kyc_subject_type
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> Subject
+    end
+
+    # One uploaded-evidence slot (`{attachment_type, submitted_at}`).
+    class Attachment < Internal::Model
+      attr_reader attachment_type: String
+      attr_reader submitted_at: Integer?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> Attachment
+    end
+
+    # The shared error for an unknown discriminator value (never a silent `nil`).
+    def self.dispatch_error: (String union, String discriminator, untyped value) -> Dinie::Error
+  end
+end

data/sig/dinie/generated/types/kyc/requirements.rbs

@@ -0,0 +1,117 @@
+# KYC requirement types + the `KycRequirement` discriminated union (DS-DISCRIMINATED — the
+# headline rule). Mirrors `lib/dinie/generated/types/kyc/requirements.rb`. Base + nine subclasses;
+# partners discriminate by CLASS (`case requirement; when Dinie::Kyc::IdentityRequirement`).
+
+module Dinie
+  module Kyc
+    # Abstract base for the nine requirement variants. Declares no attributes; never instantiated.
+    class Requirement < Internal::Model
+    end
+
+    # Identity-document requirement (CNH or RG). Person-specific (carries a `Subject`).
+    class IdentityRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader subject: Subject
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> IdentityRequirement
+    end
+
+    # Selfie requirement. Person-specific.
+    class SelfieRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader subject: Subject
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> SelfieRequirement
+    end
+
+    # Proof-of-address requirement. Person-specific.
+    class ProofOfAddressRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader subject: Subject
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> ProofOfAddressRequirement
+    end
+
+    # Company-document (CCMEI) requirement. Company-wide — no subject.
+    class CompanyDocumentRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> CompanyDocumentRequirement
+    end
+
+    # EI/MEI documents requirement. Company-wide.
+    class EiMeiDocumentsRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> EiMeiDocumentsRequirement
+    end
+
+    # Income-statement (DRE) requirement. Company-wide.
+    class IncomeStatementRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> IncomeStatementRequirement
+    end
+
+    # Articles-of-association (contrato social) requirement. Company-wide.
+    class ArticlesOfAssociationRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> ArticlesOfAssociationRequirement
+    end
+
+    # EIRELI incorporation-statement requirement. Company-wide.
+    class EireliIncorporationStatementRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> EireliIncorporationStatementRequirement
+    end
+
+    # Co-owner email-collection requirement (for CCB digital signature). Person-specific.
+    class EmailRequirement < Requirement
+      attr_reader label: String
+      attr_reader mandatory: bool
+      attr_reader requirement_id: String
+      attr_reader requirement_type: String
+      attr_reader subject: Subject
+      attr_reader submitted: Submitted?
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> EmailRequirement
+    end
+
+    # Hydrate any wire requirement by dispatching on the explicit `requirement_type` discriminator.
+    def self.deserialize_requirement: (Hash[Symbol, untyped] raw) -> Requirement
+  end
+end

data/sig/dinie/generated/types/kyc/submitted.rbs

@@ -0,0 +1,21 @@
+# KYC submitted-evidence family (DS-FAMILY — one model for all ten variants) + the implicit
+# identity CNH|RG dispatch (DS-IMPLICIT). Mirrors `lib/dinie/generated/types/kyc/submitted.rb`.
+
+module Dinie
+  module Kyc
+    class Submitted < Internal::Model
+      attr_reader attachments: Array[Attachment]
+      attr_reader evidence_type: String
+      attr_reader review_reason: String?
+      attr_reader review_status: kyc_review_status
+
+      def self.deserialize: (Hash[Symbol, untyped] raw) -> Submitted
+    end
+
+    # Hydrate any non-identity `*Submitted` (the uniform DS-FAMILY path).
+    def self.deserialize_submitted: (Hash[Symbol, untyped] raw) -> Submitted
+
+    # Hydrate the identity `submitted` oneOf by dispatching on the const `evidence_type`.
+    def self.deserialize_identity_submitted: (Hash[Symbol, untyped] raw) -> Submitted
+  end
+end

data/sig/dinie/generated/types/kyc/uploads.rbs

@@ -0,0 +1,24 @@
+# KYC upload request serialization + the `KycUpload` discriminated union (DS-DISCRIMINATED-REQUEST,
+# DS-MULTIPART). Mirrors `lib/dinie/generated/types/kyc/uploads.rb`. `serialize_upload` returns an
+# `UploadForm` (a keyword-init `Struct`).
+
+module Dinie
+  module Kyc
+    FILE_UPLOAD_EVIDENCE_TYPES: Array[String]
+
+    # The deterministic multipart representation of a KYC upload (a keyword-init `Struct`): the
+    # ordered scalar `fields` plus the optional binary `file`.
+    class UploadForm
+      attr_accessor fields: Hash[Symbol, untyped]
+      attr_accessor file: untyped
+
+      def self.new: (?fields: Hash[Symbol, untyped], ?file: untyped) -> UploadForm
+      def initialize: (?fields: Hash[Symbol, untyped], ?file: untyped) -> void
+    end
+
+    # Serialize a KYC upload to its `UploadForm` (the scalar field-map + optional binary `file`) by
+    # dispatching on the explicit `evidence_type` discriminator. (Called from the customers resource
+    # via a `**upload` splat — see the §21.3 note on the splat idiom + Steep's static keyword check.)
+    def self.serialize_upload: (evidence_type: String, requirement_id: String, attachment_type: String, ?file: untyped, ?value: String) -> UploadForm
+  end
+end

data/sig/dinie/generated/types/loan.rbs

@@ -0,0 +1,32 @@
+# `Loan` + its `CreateLoanRequest` dump — a contracted loan (`ln_…`) (architecture §3.3, §6).
+# Mirrors `lib/dinie/generated/types/loan.rb`. Read model AND request body.
+
+module Dinie
+  class Loan < Internal::Model
+    attr_reader annual_cet_rate: Float
+    attr_reader annual_interest_rate: Float
+    attr_reader ccb_number: String?
+    attr_reader created_at: Integer
+    attr_reader credit_offer_id: credit_offer_id
+    attr_reader customer_id: customer_id
+    attr_reader disbursement_method: String?
+    attr_reader first_due_date: String
+    attr_reader id: loan_id
+    attr_reader installment_amount: money
+    attr_reader installment_count: Integer
+    attr_reader iof_amount: Float?
+    attr_reader monthly_cet_rate: Float
+    attr_reader monthly_interest_rate: Float
+    attr_reader principal_amount: Float?
+    attr_reader requested_amount: money
+    attr_reader signing_url: String?
+    attr_reader simulation_id: simulation_id
+    attr_reader status: loan_status
+    attr_reader total_amount: money
+    attr_reader updated_at: Integer
+
+    def self.deserialize: (Hash[Symbol, untyped] raw) -> Loan
+
+    def self.serialize_create: (credit_offer_id: String, simulation_id: String, installment_count: Integer, installment_amount: Float, first_due_date: String) -> Hash[Symbol, untyped]
+  end
+end

data/sig/dinie/generated/types/money.rbs

@@ -0,0 +1,6 @@
+# `Money` is a plain `Float` (BRL), doc-only (architecture §3.3, §21.2). No runtime class —
+# the value IS a `Float` (mirrors the TS `type Money = number`).
+
+module Dinie
+  type money = Float
+end

data/sig/dinie/generated/types/simulation.rbs

@@ -0,0 +1,28 @@
+# `Simulation` + its `CreateSimulationRequest` dump — credit-offer pricing (`sim_…`)
+# (architecture §3.3, §6). Mirrors `lib/dinie/generated/types/simulation.rb`. Read model AND
+# request body; every field required (no optional members).
+
+module Dinie
+  class Simulation < Internal::Model
+    attr_reader annual_cet_rate: Float
+    attr_reader annual_interest_rate: Float
+    attr_reader created_at: Integer
+    attr_reader credit_offer_id: credit_offer_id
+    attr_reader fee_amount: money
+    attr_reader first_due_date: String
+    attr_reader id: simulation_id
+    attr_reader installment_amount: money
+    attr_reader installment_count: Integer
+    attr_reader interest_amount: money
+    attr_reader iof_amount: money
+    attr_reader monthly_cet_rate: Float
+    attr_reader monthly_interest_rate: Float
+    attr_reader principal_amount: money
+    attr_reader requested_amount: money
+    attr_reader total_amount: money
+
+    def self.deserialize: (Hash[Symbol, untyped] raw) -> Simulation
+
+    def self.serialize_create: (installment_count: Integer, requested_amount: Float) -> Hash[Symbol, untyped]
+  end
+end

data/sig/dinie/generated/types/transaction.rbs

@@ -0,0 +1,24 @@
+# `Transaction` — one installment of a loan (`tx_…`), read-only (architecture §3.3, §6).
+# Mirrors `lib/dinie/generated/types/transaction.rb`.
+
+module Dinie
+  class Transaction < Internal::Model
+    attr_reader amount_due: money
+    attr_reader amount_paid: money
+    attr_reader amount_remaining: money
+    attr_reader created_at: Integer
+    attr_reader days_overdue: Integer
+    attr_reader due_date: String
+    attr_reader fees: money
+    attr_reader id: transaction_id
+    attr_reader interest: money
+    attr_reader loan_id: loan_id
+    attr_reader paid_at: Integer?
+    attr_reader principal: money
+    attr_reader status: transaction_status
+    attr_reader type: transaction_type
+    attr_reader updated_at: Integer
+
+    def self.deserialize: (Hash[Symbol, untyped] raw) -> Transaction
+  end
+end

data/sig/dinie/generated/types/webhook_endpoint.rbs

@@ -0,0 +1,38 @@
+# `WebhookEndpoint` family — REST management types (architecture §3.2, §3.3, §6). Mirrors
+# `lib/dinie/generated/types/webhook_endpoint.rb`. NOT the webhook runtime (that is `Events::*`).
+
+module Dinie
+  class WebhookEndpoint < Internal::Model
+    attr_reader created_at: Integer
+    attr_reader description: String
+    attr_reader events: Array[String]
+    attr_reader id: webhook_endpoint_id
+    attr_reader status: webhook_endpoint_status
+    attr_reader updated_at: Integer
+    attr_reader url: String
+
+    def self.deserialize: (Hash[Symbol, untyped] raw) -> WebhookEndpoint
+
+    def self.serialize_create: (url: String, ?events: Array[String], ?description: String) -> Hash[Symbol, untyped]
+
+    def self.serialize_update: (?url: String, ?events: Array[String], ?description: String, ?status: String) -> Hash[Symbol, untyped]
+  end
+
+  # The creation-only endpoint — `WebhookEndpoint` plus `secret` (the contract's allOf).
+  class WebhookEndpointWithSecret < WebhookEndpoint
+    attr_reader secret: String
+
+    def self.deserialize: (Hash[Symbol, untyped] raw) -> WebhookEndpointWithSecret
+  end
+
+  # The result of `webhook_endpoints.rotate_secret` — the new signing secret + old-secret deadline.
+  class WebhookSecretRotation < Internal::Model
+    attr_reader id: webhook_endpoint_id
+    attr_reader previous_secret_expires_at: Integer
+    attr_reader secret: String
+
+    def self.deserialize: (Hash[Symbol, untyped] raw) -> WebhookSecretRotation
+
+    def self.serialize_rotate_secret: (?expire_current_in: Integer) -> Hash[Symbol, untyped]
+  end
+end

data/sig/dinie/runtime/errors.rbs

@@ -0,0 +1,106 @@
+# Error hierarchy + the `from_response` dispatcher + `parse_retry_after` (architecture §7, §10).
+# Mirrors `lib/dinie/runtime/errors.rb`. The 8 server-response markers are empty subclasses of
+# `APIStatusError` declared in `generated/errors/registry.rbs`.
+
+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` / `request_id`
+  # are first-class on every API error.
+  class APIError < Error
+    attr_reader code: String?
+    attr_reader request_id: String?
+
+    def initialize: (?String? message, ?code: String?, ?request_id: String?) -> void
+  end
+
+  # A request never produced a response (DNS failure, socket reset, timeout). Client-side.
+  class APIConnectionError < APIError
+    def initialize: (?String message) -> void
+  end
+
+  # The request exceeded the configured timeout.
+  class APITimeoutError < APIConnectionError
+    def initialize: (?String message) -> void
+  end
+
+  # The API returned a non-2xx response. Base of the openapi-mirrored marker catalog.
+  class APIStatusError < APIError
+    attr_reader status: Integer
+    attr_reader headers: Hash[untyped, untyped]
+    attr_reader body: (Hash[Symbol, untyped] | String | nil)
+    attr_reader type: String?
+    attr_reader title: String?
+    attr_reader detail: String?
+    attr_reader instance: String?
+
+    def initialize: (status: Integer, body: (Hash[Symbol, untyped] | String | nil), headers: Hash[untyped, untyped], ?request_id: String?) -> void
+
+    def self.build_message: (Integer status, untyped body, String? request_id) -> String
+    def self.message_summary: (untyped body) -> String?
+
+    private
+
+    def string_field: (Hash[Symbol, untyped]? problem, Symbol key) -> String?
+  end
+
+  # OAuth2 client-credentials token acquisition/refresh failed (client-side).
+  class OAuthError < Error
+  end
+
+  # A session-mode token was successfully exchanged once but has since expired.
+  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 catalog.
+  class UnknownWebhookEventError < Error
+    attr_reader event_type: String
+
+    def initialize: (String event_type) -> void
+  end
+
+  # Maximum honored `Retry-After`, in seconds.
+  RETRY_AFTER_CAP_SECONDS: Integer
+
+  # Parse a `Retry-After` value to seconds, capped at 60. Each argument accepts a String or an
+  # Array (first element used). Returns the wait in seconds, or `nil` when nothing parseable.
+  def self.parse_retry_after: (?(String | Array[String])? retry_after, ?retry_after_ms: (String | Array[String])?) -> Float?
+
+  def self.retry_after_ms_seconds: (untyped value) -> Float?
+  def self.retry_after_seconds: (untyped value) -> Float?
+  def self.http_date_delta: (String raw) -> Float?
+  def self.first_header_value: (untyped value) -> String?
+
+  module Internal
+    # The transport-agnostic error dispatcher (the controlled runtime → generated seam, §4).
+    # `module_function`: methods are declared as instance methods (Steep types `self` as the module
+    # inside them) and are also callable on the module (`Errors.from_response`).
+    module Errors
+      REQUEST_ID_HEADER: String
+
+      # Build the typed error for an HTTP error response: dispatch by Problem Details `type` URL,
+      # then HTTP status, then the ≥500 band fallback.
+      def from_response: (status: Integer, ?headers: Hash[untyped, untyped], ?body: String?, ?force: untyped) -> Dinie::APIStatusError
+      def dispatch: (String? type_url, Integer status) -> untyped
+      def fallback_ctor: (Integer status) -> untyped
+      def parse_problem: (untyped body) -> Hash[Symbol, untyped]?
+      def presentable_body: (untyped body) -> String?
+      def header_request_id: (untyped headers) -> untyped
+      def header_lookup: (untyped headers, String name) -> untyped
+      def string_value: (Hash[Symbol, untyped]? record, Symbol key) -> String?
+
+      # Module-function alias (callable as `Errors.from_response`).
+      def self.from_response: (status: Integer, ?headers: Hash[untyped, untyped], ?body: String?, ?force: untyped) -> Dinie::APIStatusError
+    end
+  end
+end

data/sig/dinie/runtime/http.rbs

@@ -0,0 +1,59 @@
+# `HttpClient` — request-lifecycle orchestrator (architecture §10, RB15). Mirrors
+# `lib/dinie/runtime/http.rb`. Runtime-internal: constructed/called by `Dinie::Client` + resources.
+# Faraday objects (connection, response, env) are `untyped` — `faraday` ships no bundled RBS
+# (the documented informative-gate gap, story 013 / §21.3).
+
+module Dinie
+  module Internal
+    class HttpClient
+      DEFAULT_BASE_URL: String
+      DEFAULT_TIMEOUT_SECONDS: Integer
+      DEFAULT_MAX_RETRIES: Integer
+      API_VERSION: String
+      JSON_CONTENT_TYPE: String
+      AUTO_IDEMPOTENT_METHODS: Array[Symbol]
+      USER_AGENT: String
+
+      # Per-call request descriptor threaded through the retry loop (a private keyword-init Struct).
+      class PreparedRequest
+        attr_accessor http_method: Symbol
+        attr_accessor url: String
+        attr_accessor body: untyped
+        attr_accessor content_type: String?
+        attr_accessor idempotency_key: String?
+        attr_accessor max_retries: Integer
+        attr_accessor timeout: Numeric
+        attr_accessor header_overrides: Hash[String, String?]?
+
+        def self.new: (**untyped) -> PreparedRequest
+        def initialize: (**untyped) -> void
+      end
+
+      def initialize: (token_manager: untyped, ?base_url: String?, ?timeout: Numeric, ?max_retries: Integer, ?idempotency: bool, ?adapter: Symbol?, ?connection: untyped, ?sleeper: untyped) -> void
+
+      # Latest rate-limit snapshot (read by `client.rate_limit`).
+      def rate_limit: () -> Dinie::RateLimit?
+
+      # Run one logical request end-to-end and return the parsed body (resources deserialize it).
+      def request: (method: (Symbol | String), path: String, ?query: Hash[untyped, untyped]?, ?body: untyped, ?idempotent: bool?, ?request_options: (Dinie::Internal::RequestOptions | Hash[untyped, untyped] | nil)) -> untyped
+
+      private
+
+      def execute: (untyped prepared) -> untyped
+      def dispatch: (untyped prepared, Hash[String, untyped] headers) -> untyped
+      def build_headers: (untyped prepared, String token, Integer attempt) -> Hash[String, untyped]
+      def base_headers: (String token) -> Hash[String, String]
+      def apply_header_overrides: (Hash[String, untyped] headers, Hash[String, String?]? overrides) -> Hash[String, untyped]
+      def resolve_idempotency_key: (bool? idempotent, Symbol method, Dinie::Internal::RequestOptions options) -> String?
+      def serialize_body: (untyped body) -> [ untyped, String? ]
+      def parse_body: (untyped response) -> untyped
+      def build_full_url: (String path, Hash[untyped, untyped]? query) -> String
+      def encode_query: (Hash[untyped, untyped]? query) -> String
+      def header: (untyped response, String name) -> untyped
+      def build_error: (untyped response, ?force: Class?) -> Dinie::APIStatusError
+      def translate_network_error: (untyped error) -> Dinie::APIError
+      def sleep_for: (Numeric seconds) -> untyped
+      def build_connection: (Symbol? adapter) -> untyped
+    end
+  end
+end

data/sig/dinie/runtime/idempotency.rbs

@@ -0,0 +1,15 @@
+# Idempotency-Key generation (architecture §10, RB15). Mirrors `lib/dinie/runtime/idempotency.rb`.
+# Runtime-internal: consumed by `HttpClient`, not part of the public surface.
+
+module Dinie
+  module Internal
+    module Idempotency
+      KEY_PREFIX: String
+
+      # `module_function`: instance method + singleton alias (called as `Idempotency.generate_key`).
+      # A fresh auto-generated Idempotency-Key: `dinie-sdk-retry-<uuid v4>`.
+      def generate_key: () -> String
+      def self.generate_key: () -> String
+    end
+  end
+end