dinie-sdk 1.0.0

data/sig/dinie/runtime/logger.rbs

@@ -0,0 +1,89 @@
+# Leveled logging + PII redaction (architecture §9, RB12). Mirrors `lib/dinie/runtime/logger.rb`.
+# Runtime-internal. `Middleware::Logging` subclasses `Faraday::Middleware` (untyped — no bundled
+# RBS; the informative-gate gap, story 013 / §21.3).
+
+module Dinie
+  module Internal
+    # Pure, stateless redaction + truncation helpers. `module_function`: instance methods (so
+    # `self`-typing + internal calls resolve) plus singleton aliases for the two `RuntimeLogger`
+    # calls externally (`LogRedaction.redact_headers` / `.format_body`).
+    module LogRedaction
+      REDACTED: String
+      MAX_BODY_BYTES: Integer
+      REDACTED_HEADERS: Set[String]
+      REDACTED_BODY_FIELDS: Set[String]
+      NOT_JSON: untyped
+
+      # Replace the value of any sensitive header with the mask (case-insensitive).
+      def redact_headers: (untyped headers) -> Hash[String, untyped]
+      def self.redact_headers: (untyped headers) -> Hash[String, untyped]
+
+      # Deep-copy `value`, masking any Hash key (case-insensitive) that names a PII/secret field.
+      def redact_body: (untyped value) -> untyped
+
+      def redact_hash: (Hash[untyped, untyped] hash) -> Hash[untyped, untyped]
+
+      # Render a body for logging: redact PII, serialize to JSON, then truncate.
+      def format_body: (untyped body) -> String?
+      def self.format_body: (untyped body) -> String?
+
+      def serialize_for_log: (untyped body) -> String
+      def truncate_body: (String text) -> String
+      def clip_to_bytes: (String text, Integer max_bytes) -> String
+      def parse_json: (String text) -> untyped
+      def safe_generate: (untyped value) -> String
+    end
+
+    # Leveled logging facade with PII redaction. Constructed by `Middleware::Logging`.
+    class RuntimeLogger
+      LEVELS: Hash[Symbol, Integer]
+      ENV_VAR: String
+
+      attr_reader level: Symbol
+
+      def initialize: (?level: (Symbol | String)?, ?logger: untyped, ?env: String?) -> void
+
+      # Whether a call at `level` would emit under the configured level.
+      def enabled?: (Symbol level) -> bool
+
+      def error: (untyped message) -> void
+      def warn: (untyped message) -> void
+      def info: (untyped message) -> void
+      def debug: (untyped message) -> void
+
+      # Log an outgoing request at `debug` with redacted headers + body and the correlation triple.
+      def log_request: (method: (Symbol | String), url: String, headers: untyped, body: untyped, correlation: Hash[Symbol, untyped]) -> void
+
+      # Log an incoming response at `debug` with redacted headers + body, duration, and request id.
+      def log_response: (status: Integer, url: String, headers: untyped, body: untyped, duration_ms: Numeric, request_id: String?, correlation: Hash[Symbol, untyped]) -> void
+
+      private
+
+      def emit: (Symbol level, untyped message) -> void
+      def emit_line: (String label, Hash[Symbol, untyped] fields, untyped headers, untyped body) -> void
+      def resolve_level: (untyped level, untyped env) -> Symbol
+      def valid_level?: (untyped value) -> bool
+    end
+
+    module Middleware
+      # Faraday response middleware — the logging hook point. `Faraday::Middleware` is untyped.
+      class Logging < Faraday::Middleware
+        ORIGIN_LOG_ID_KEY: Symbol
+        RETRY_COUNT_HEADER: String
+        REQUEST_ID_HEADER: String
+
+        def initialize: (untyped app, ?level: (Symbol | String)?, ?logger: untyped) -> void
+
+        def call: (untyped request_env) -> untyped
+
+        private
+
+        def log_request: (untyped env, Hash[Symbol, untyped] correlation) -> void
+        def log_response: (untyped env, Hash[Symbol, untyped] correlation, Float started) -> void
+        def correlate: (untyped request_headers) -> Hash[Symbol, untyped]
+        def monotonic_now: () -> Float
+        def elapsed_ms: (Float started) -> Numeric
+      end
+    end
+  end
+end

data/sig/dinie/runtime/model.rbs

@@ -0,0 +1,51 @@
+# Runtime model base + the `OMIT` sentinel (architecture §5.1, §6.2). Mirrors
+# `lib/dinie/runtime/model.rb`.
+
+module Dinie
+  module Internal
+    # The "argument not provided" sentinel (RB5). Compared by identity; exactly one frozen
+    # instance. Optional kwargs default to it and serializers drop any key still equal to it.
+    OMIT: Object
+
+    # Identity check for the OMIT sentinel.
+    def self.omitted?: (untyped value) -> bool
+
+    # Base class for every generated model: value-semantics POROs without `Data.define`
+    # (Ruby 3.1 floor). Subclasses declare fields with `attribute` (alphabetical, R-ORDER).
+    class Model
+      REDACTED_ATTRIBUTES: Array[Symbol]
+
+      # The declared attribute names, in declaration (R-ORDER) order.
+      def self.attributes: () -> Array[Symbol]
+
+      # Declare one or more attributes (defines an `attr_reader` for each; appends to `attributes`).
+      def self.attribute: (*Symbol | String names) -> void
+
+      # Carry the parent's attribute list into each subclass.
+      def self.inherited: (Class subclass) -> void
+
+      # Build a frozen instance from keyword arguments — one per declared attribute.
+      def initialize: (**untyped attrs) -> void
+
+      # Attributes in declaration (R-ORDER) order — deterministic.
+      def to_h: () -> Hash[Symbol, untyped]
+      alias to_hash to_h
+
+      # Enable pattern matching (`case model; in {status: "active"}`).
+      def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+
+      # Value-equality: same class and same attribute values.
+      def ==: (untyped other) -> bool
+      alias eql? ==
+
+      def hash: () -> Integer
+
+      # Like `to_h`, but with PII redacted — safe for logs and the console.
+      def inspect: () -> String
+
+      private
+
+      def validate_keys!: (Array[Symbol] expected, Hash[Symbol, untyped] attrs) -> void
+    end
+  end
+end

data/sig/dinie/runtime/multipart.rbs

@@ -0,0 +1,25 @@
+# Transport wrapper for a `multipart/form-data` request body (architecture §10/§14).
+# Mirrors `lib/dinie/runtime/multipart.rb`. Runtime-internal (the KYC upload seam).
+
+module Dinie
+  module Internal
+    class Multipart
+      CONTENT_TYPE: String
+      DEFAULT_FILE_CONTENT_TYPE: String
+      DEFAULT_FILE_FILENAME: String
+
+      attr_reader fields: Hash[Symbol, String]
+      attr_reader file: untyped
+
+      def initialize: (fields: Hash[Symbol, String], ?file: untyped) -> void
+
+      # The Faraday multipart body: scalar fields plus the wrapped `file` part when present.
+      def to_faraday_body: () -> Hash[Symbol, untyped]
+
+      private
+
+      def wrap_file: (untyped file) -> untyped
+      def multipart_part?: (untyped file) -> bool
+    end
+  end
+end

data/sig/dinie/runtime/paginator.rbs

@@ -0,0 +1,50 @@
+# `Dinie::Page` — one page of a cursor-paginated list + the auto-pagination engine
+# (architecture §11, RB8). Mirrors `lib/dinie/runtime/paginator.rb`. Part of the public surface.
+#
+# `Page` is generic over its item type so `list*` returns `Page[Customer]`, etc. The item type is
+# bound to `_Identifiable` (every list item responds to `#id` — the next page's cursor).
+
+module Dinie
+  # The structural bound on a `Page`'s items: every paginated item carries an `id` (the cursor).
+  interface _Identifiable
+    def id: () -> String
+  end
+
+  class Page[Elem < _Identifiable]
+    attr_reader data: Array[Elem]
+    attr_reader has_more: bool
+
+    NO_NEXT_PAGE_MESSAGE: String
+    UNSPECIFIED: untyped
+
+    # Build the FIRST page by invoking `fetch_page` with no cursor.
+    def self.from_fetch: [E < _Identifiable] (^(String?) -> Hash[Symbol, untyped] fetch_page) -> Page[E]
+
+    # Wrap a fetched `{ data:, has_more: }` envelope in a `Page`.
+    def self.build: [E < _Identifiable] (Hash[Symbol, untyped] envelope, ^(String?) -> Hash[Symbol, untyped] fetch_page) -> Page[E]
+
+    # A list endpoint is paginated iff its envelope carries `has_more`.
+    def self.paginated?: (untyped envelope) -> bool
+
+    def initialize: (data: Array[Elem], has_more: bool, fetch_page: ^(String?) -> Hash[Symbol, untyped]) -> void
+
+    # Whether a next page can be fetched.
+    def next_page?: () -> bool
+
+    # Fetch the next page (cursor = `id` of this page's last item). Guard with `next_page?`.
+    def next_page: () -> Page[Elem]
+
+    # Auto-paginate: yield every item of this page, then every following page. No block → `Enumerator`.
+    def each: () { (Elem item) -> void } -> self
+            | () -> Enumerator[Elem, self]
+    alias auto_paging_each each
+
+    # Yield page-by-page (manual control). No block → `Enumerator` over the pages.
+    def each_page: () { (Page[Elem] page) -> void } -> self
+                 | () -> Enumerator[Page[Elem], self]
+
+    # The first `count` items across pages (or the very first item), fetched lazily. (`count`
+    # defaults to a private sentinel, so the signature is loose; returns `Elem?` or `Array[Elem]`.)
+    def first: (?untyped count) -> untyped
+  end
+end

data/sig/dinie/runtime/rate_limit.rbs

@@ -0,0 +1,46 @@
+# Rate-limit snapshot + tracker (architecture §10, RB6). Mirrors `lib/dinie/runtime/rate_limit.rb`.
+# `reset_at` is the SDK's only `Time` — every body timestamp stays an `Integer` epoch.
+
+module Dinie
+  # The rate-limit snapshot read from the most recent response's `X-RateLimit-*` headers.
+  # Surfaced as `client.rate_limit`; `nil` until a response carries valid headers.
+  class RateLimit
+    attr_reader limit: Integer
+    attr_reader remaining: Integer
+    attr_reader reset_at: Time
+
+    def initialize: (limit: Integer, remaining: Integer, reset_at: Time) -> void
+
+    def to_h: () -> Hash[Symbol, untyped]
+    alias to_hash to_h
+
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+
+    def ==: (untyped other) -> bool
+    alias eql? ==
+
+    def hash: () -> Integer
+  end
+
+  module Internal
+    # Parses the three `X-RateLimit-*` headers and holds the most recent snapshot for `HttpClient`.
+    class RateLimitTracker
+      LIMIT_HEADER: String
+      REMAINING_HEADER: String
+      RESET_HEADER: String
+      EPOCH_THRESHOLD_SECONDS: Integer
+
+      # Latest snapshot, or `nil` before any valid headers.
+      def snapshot: () -> Dinie::RateLimit?
+
+      # Fold a response's headers into the snapshot (a header-less/garbage response is a no-op).
+      def update: (untyped headers) -> void
+
+      # Parse the three headers into a `RateLimit`, or `nil` when any is absent/unparseable.
+      def self.parse: (untyped headers) -> Dinie::RateLimit?
+      def self.parse_count: (untyped raw) -> Integer?
+      def self.parse_reset: (untyped raw) -> Time?
+      def self.header_value: (untyped headers, String name) -> untyped
+    end
+  end
+end

data/sig/dinie/runtime/request_options.rbs

@@ -0,0 +1,35 @@
+# Normalized per-call options, the trailing `request_options:` Hash (architecture §12, RB5).
+# Mirrors `lib/dinie/runtime/request_options.rb`.
+
+module Dinie
+  module Internal
+    class RequestOptions
+      attr_reader timeout: Numeric?
+      attr_reader idempotency_key: String?
+      attr_reader headers: Hash[String, String?]?
+      attr_reader max_retries: Integer?
+
+      # Pass a `RequestOptions` through, or build one from a Hash (string/symbol keys; `nil` → empty).
+      # Param is `untyped`: the body branches on `value.is_a?(self)`, which Steep cannot narrow on a
+      # union, so a precise union would mis-type the Hash branch.
+      def self.coerce: (untyped value) -> RequestOptions
+
+      def initialize: (?timeout: Numeric?, ?idempotency_key: String?, ?headers: Hash[untyped, untyped]?, ?max_retries: Integer?) -> void
+
+      def to_h: () -> Hash[Symbol, untyped]
+      alias to_hash to_h
+
+      def ==: (untyped other) -> bool
+      alias eql? ==
+
+      def hash: () -> Integer
+
+      private
+
+      def validate_timeout: (untyped value) -> Numeric?
+      def validate_max_retries: (untyped value) -> Integer?
+      def validate_string: (untyped value, Symbol key) -> String?
+      def validate_headers: (untyped value) -> Hash[String, String?]?
+    end
+  end
+end

data/sig/dinie/runtime/retry.rbs

@@ -0,0 +1,29 @@
+# Retry policy — pure decision + delay functions (architecture §10, RB15). Mirrors
+# `lib/dinie/runtime/retry.rb`. Runtime-internal: imported by `HttpClient`.
+
+module Dinie
+  module Internal
+    module Retry
+      RETRYABLE_STATUS: Set[Integer]
+      INITIAL_BACKOFF_SECONDS: Float
+      MAX_BACKOFF_SECONDS: Integer
+      JITTER_RATIO: Float
+      RETRYABLE_NETWORK_ERRORS: Array[untyped]
+
+      # `module_function`: declared as instance methods (so `self`-typing is the module) plus
+      # singleton aliases (so `Retry.should_retry?` resolves at the `HttpClient` call sites).
+
+      # True only for the retryable status set (`{408, 429, 500, 502, 503, 504}`).
+      def should_retry?: (Integer status) -> bool
+      def self.should_retry?: (Integer status) -> bool
+
+      # Whether a thrown transport error (no HTTP response) is worth retrying (timeout/conn failure).
+      def retryable_network_error?: (Exception error) -> bool
+      def self.retryable_network_error?: (Exception error) -> bool
+
+      # Seconds to wait before the next attempt (Retry-After wins; else backoff minus jitter).
+      def retry_delay: (Integer attempt, ?retry_after: (String | Array[String])?, ?retry_after_ms: (String | Array[String])?) -> Float
+      def self.retry_delay: (Integer attempt, ?retry_after: (String | Array[String])?, ?retry_after_ms: (String | Array[String])?) -> Float
+    end
+  end
+end

data/sig/dinie/runtime/token_manager.rbs

@@ -0,0 +1,51 @@
+# `TokenManager` — OAuth2 client_credentials token cache (architecture §10). Mirrors
+# `lib/dinie/runtime/token_manager.rb`. Runtime-internal: built/injected by `Dinie::Client`.
+# Faraday objects are `untyped` (no bundled RBS — informative-gate gap).
+
+module Dinie
+  module Internal
+    class TokenManager
+      TOKEN_PATH: String
+      SESSION_EXCHANGE_PATH: String
+      REFRESH_MARGIN_SECONDS: Integer
+      GRANT_BODY: String
+      FORM_CONTENT_TYPE: String
+      MISSING_ACCESS_TOKEN: String
+      MISSING_EXPIRES_IN: String
+
+      def initialize: (client_id: String, client_secret: String, ?base_url: String?, ?connection: untyped, ?refresh_margin_seconds: Integer, ?adapter: Symbol?, ?clock: untyped, ?code: String?) -> void
+
+      # Return a valid Bearer access token, acquiring or refreshing transparently.
+      def access_token: () -> String
+
+      # Drop the cached token so the next `access_token` re-authenticates (the 401 one-shot seam).
+      def invalidate!: () -> void
+
+      private
+
+      def token_valid?: () -> bool
+      def refresh_and_cache: () -> String
+      def fetch_token: () -> [ String, Numeric ]
+      def fetch_session_token: () -> [ String, Numeric ]
+      def fetch_partner_token: () -> [ String, Numeric ]
+      def fetch_client_credentials_token: () -> String
+      def exchange: (String cc_token, String code) -> [ String, Numeric ]
+      def request_exchange: (String cc_token, String code) -> untyped
+      def parse_exchange_response: (untyped raw_body) -> [ String, Numeric ]
+      def exchange_url: () -> String
+      def request_token: () -> untyped
+      def parse_token_response: (untyped raw_body) -> [ String, Numeric ]
+      def parse_json: (untyped raw_body) -> untyped
+      def valid_access_token?: (untyped value) -> bool
+      def valid_expires_in?: (untyped value) -> bool
+      def token_request_headers: () -> Hash[String, String]
+      def basic_credentials: () -> String
+      def token_url: () -> String
+      def success?: (Integer status) -> bool
+      def body_detail: (untyped response) -> String
+      def status_failure: (Integer status, String detail) -> String
+      def now: () -> Numeric
+      def build_connection: (Symbol? adapter) -> untyped
+    end
+  end
+end

data/sig/dinie/runtime/webhooks.rbs

@@ -0,0 +1,31 @@
+# `Dinie::Webhooks.extract` — webhook verification + per-type deserialization (RB11, §8).
+# Mirrors `lib/dinie/runtime/webhooks.rb`. `module_function`: methods are declared as instance
+# methods (Steep types `self` as the module inside them) and are also callable on the module
+# (`Dinie::Webhooks.extract`). Verification needs no client.
+
+module Dinie
+  module Webhooks
+    DEFAULT_TOLERANCE_SECONDS: Integer
+    WHSEC_PREFIX: String
+    SIGNATURE_VERSION: String
+
+    # Verify a Standard Webhooks v1 payload and return the deserialized, typed event. Never returns
+    # an unverified event.
+    def extract: (headers: Hash[untyped, untyped], body: String, secret: (String | Array[String]), ?tolerance_seconds: Integer) -> Dinie::Events::WebhookEventBase
+
+    def signed_payload: (untyped webhook_id, untyped timestamp, String body) -> String
+    def required_header: (Hash[untyped, untyped] headers, String name, untyped error_class) -> untyped
+    def lookup_header: (Hash[untyped, untyped] headers, String name) -> untyped
+    def fetch_header: (Hash[untyped, untyped] headers, String name) -> untyped
+    def verify_timestamp!: (untyped timestamp, Integer tolerance_seconds) -> void
+    def verify_signature!: (String payload, (String | Array[String]) secret, String signature_header) -> void
+    def normalize_secrets: ((String | Array[String]) secret) -> Array[untyped]
+    def parse_signature_header: (String header) -> Array[untyped]
+    def signatures_match?: (String payload, Array[untyped] secrets, Array[untyped] provided_signatures) -> bool
+    def decode_secret: (String secret) -> untyped
+    def deserialize_verified_event: (String body) -> Dinie::Events::WebhookEventBase
+
+    # Module-function aliases (callable as `Dinie::Webhooks.extract`).
+    def self.extract: (headers: Hash[untyped, untyped], body: String, secret: (String | Array[String]), ?tolerance_seconds: Integer) -> Dinie::Events::WebhookEventBase
+  end
+end

data/sig/dinie/version.rbs

@@ -0,0 +1,7 @@
+# RBS mirror of the public surface (architecture §5.2, story 013). Hand-written in V0.3;
+# emitted mechanically from the IR in V0.4. Doc-only — `steep check` consumes it; the gem
+# ships it (gemspec `sig/**/*.rbs`) for consumers' own type checking. `.yardopts` excludes `sig/`.
+
+module Dinie
+  VERSION: String
+end