sec_api 1.0.0

data/lib/sec_api/query.rb

@@ -0,0 +1,423 @@
+module SecApi
+  # Fluent query builder for SEC filing searches using Lucene query syntax.
+  #
+  # Builder Pattern Design:
+  # Uses the fluent builder pattern (like ActiveRecord) for query construction.
+  # Key aspects:
+  # - Intermediate methods (.ticker, .form_type, .date_range) return `self` for chaining
+  # - Terminal method (.search) executes the query and returns results
+  # - Each `client.query` call returns a NEW instance (stateless between calls)
+  # - Instance variables accumulate query parts until terminal method is called
+  #
+  # Why fluent builder? More readable than positional args for complex queries,
+  # allows optional filters, and familiar to Ruby developers from ActiveRecord.
+  #
+  # Provides a chainable, ActiveRecord-style interface for building and executing
+  # SEC filing queries. Each method returns `self` for chaining, with `.search`
+  # as the terminal method that executes the query.
+  #
+  # @example Basic ticker query
+  #   client.query.ticker("AAPL").search
+  #   #=> SecApi::Collections::Filings
+  #
+  # @example Multiple tickers
+  #   client.query.ticker("AAPL", "TSLA").search
+  #
+  # @example Query by CIK (leading zeros are automatically stripped)
+  #   client.query.cik("0000320193").search
+  #
+  # @example Filter by form type
+  #   client.query.form_type("10-K").search
+  #   client.query.form_type("10-K", "10-Q").search  # Multiple types
+  #
+  # @example Filter by date range
+  #   client.query.date_range(from: "2020-01-01", to: "2023-12-31").search
+  #   client.query.date_range(from: Date.new(2020, 1, 1), to: Date.today).search
+  #
+  # @example Combining multiple filters
+  #   client.query
+  #     .ticker("AAPL")
+  #     .form_type("10-K")
+  #     .date_range(from: "2020-01-01", to: "2023-12-31")
+  #     .search
+  #
+  # @example Full-text search for keywords
+  #   client.query.search_text("merger acquisition").search
+  #
+  # @example Limit results
+  #   client.query.ticker("AAPL").limit(10).search
+  #
+  # @example Combined search with all filters
+  #   client.query
+  #     .ticker("AAPL")
+  #     .form_type("8-K")
+  #     .search_text("acquisition")
+  #     .limit(20)
+  #     .search
+  #
+  # @example Query international filings (Form 20-F - foreign annual reports)
+  #   client.query.ticker("NMR").form_type("20-F").search
+  #
+  # @example Query Canadian filings (Form 40-F - Canadian annual reports under MJDS)
+  #   client.query.ticker("ABX").form_type("40-F").search
+  #
+  # @example Query foreign current reports (Form 6-K)
+  #   client.query.ticker("NMR").form_type("6-K").search
+  #
+  # @example Mix domestic and international forms
+  #   client.query.form_type("10-K", "20-F", "40-F").search
+  #
+  # @note International forms (20-F, 40-F, 6-K) are supported as first-class citizens.
+  #   No special handling required - they work identically to domestic forms (10-K, 10-Q, 8-K).
+  #
+  class Query
+    # Common domestic SEC form types for reference.
+    # @return [Array<String>] list of common domestic form types
+    # @note This is not an exhaustive list. The API accepts any form type string.
+    DOMESTIC_FORM_TYPES = %w[10-K 10-Q 8-K S-1 S-3 4 13F DEF\ 14A].freeze
+
+    # International SEC form types for foreign private issuers.
+    # @return [Array<String>] list of international form types
+    # @see https://www.sec.gov/divisions/corpfin/internatl/foreign-private-issuers-overview.shtml
+    INTERNATIONAL_FORM_TYPES = %w[20-F 40-F 6-K].freeze
+
+    # Combined list of common domestic and international form types.
+    # @return [Array<String>] list of all common form types
+    # @note This is not an exhaustive list. The API accepts any form type string.
+    ALL_FORM_TYPES = (DOMESTIC_FORM_TYPES + INTERNATIONAL_FORM_TYPES).freeze
+
+    # Creates a new Query builder instance.
+    #
+    # Query instances are typically obtained via {Client#query} rather than
+    # direct instantiation. Each call to `client.query` returns a fresh instance
+    # to ensure query chains start with clean state.
+    #
+    # @param client [SecApi::Client] The parent client for API access
+    # @return [SecApi::Query] A new query builder instance
+    #
+    # @example Via client (recommended)
+    #   query = client.query
+    #   query.ticker("AAPL").search
+    #
+    # @example Direct instantiation (advanced)
+    #   query = SecApi::Query.new(client)
+    #
+    # @api private
+    def initialize(client)
+      @_client = client
+      @query_parts = []
+      @from_offset = 0
+      @page_size = 50
+      @sort_config = [{"filedAt" => {"order" => "desc"}}]
+    end
+
+    # Filter filings by ticker symbol(s).
+    #
+    # @param tickers [Array<String>] One or more ticker symbols to filter by
+    # @return [self] Returns self for method chaining
+    #
+    # @example Single ticker
+    #   query.ticker("AAPL")  #=> Lucene: "ticker:AAPL"
+    #
+    # @example Multiple tickers
+    #   query.ticker("AAPL", "TSLA")  #=> Lucene: "ticker:(AAPL, TSLA)"
+    #
+    def ticker(*tickers)
+      tickers = tickers.flatten.map(&:to_s).map(&:upcase)
+
+      @query_parts << if tickers.size == 1
+        "ticker:#{tickers.first}"
+      else
+        "ticker:(#{tickers.join(", ")})"
+      end
+
+      self
+    end
+
+    # Filter filings by Central Index Key (CIK).
+    #
+    # @param cik_number [String, Integer] The CIK number (leading zeros are automatically stripped)
+    # @return [self] Returns self for method chaining
+    # @raise [ArgumentError] when CIK is empty or contains only zeros
+    #
+    # @example With leading zeros (automatically stripped)
+    #   query.cik("0000320193")  #=> Lucene: "cik:320193"
+    #
+    # @example Without leading zeros
+    #   query.cik("320193")  #=> Lucene: "cik:320193"
+    #
+    # @note The SEC API requires CIK values WITHOUT leading zeros.
+    #   This method automatically normalizes the input.
+    #
+    def cik(cik_number)
+      normalized_cik = cik_number.to_s.gsub(/^0+/, "")
+      raise ArgumentError, "CIK cannot be empty or zero" if normalized_cik.empty?
+      @query_parts << "cik:#{normalized_cik}"
+      self
+    end
+
+    # Filter filings by form type(s).
+    #
+    # Supports both domestic and international SEC form types. International forms
+    # (20-F, 40-F, 6-K) are treated as first-class citizens - no special handling required.
+    #
+    # @param types [Array<String>] One or more form types to filter by
+    # @return [self] Returns self for method chaining
+    #
+    # @example Single form type
+    #   query.form_type("10-K")  #=> Lucene: 'formType:"10-K"'
+    #
+    # @example Multiple form types
+    #   query.form_type("10-K", "10-Q")  #=> Lucene: 'formType:("10-K" OR "10-Q")'
+    #
+    # @example International form types
+    #   query.form_type("20-F")    # Foreign private issuer annual reports
+    #   query.form_type("40-F")    # Canadian issuer annual reports (MJDS)
+    #   query.form_type("6-K")     # Foreign private issuer current reports
+    #
+    # @example Mixed domestic and international
+    #   query.form_type("10-K", "20-F", "40-F")  # All annual reports
+    #   query.form_type("8-K", "6-K")            # All current reports
+    #
+    # @note Form types are case-sensitive. "10-K" and "10-k" are different.
+    # @note International forms work identically to domestic forms - no special API handling.
+    # @raise [ArgumentError] when no form types are provided
+    #
+    def form_type(*types)
+      types = types.flatten.map(&:to_s)
+      raise ArgumentError, "At least one form type is required" if types.empty?
+
+      @query_parts << if types.size == 1
+        "formType:\"#{types.first}\""
+      else
+        quoted_types = types.map { |t| "\"#{t}\"" }.join(" OR ")
+        "formType:(#{quoted_types})"
+      end
+
+      self
+    end
+
+    # Execute full-text search across filing content.
+    #
+    # Adds a full-text search clause to the query. The search terms are quoted
+    # to match the exact phrase. Combines with other filters using AND.
+    #
+    # @param keywords [String] The search terms to find in filing content
+    # @return [self] Returns self for method chaining
+    # @raise [ArgumentError] when keywords is nil, empty, or whitespace-only
+    #
+    # @example Search for a phrase
+    #   query.search_text("merger acquisition")
+    #   #=> Lucene: '"merger acquisition"'
+    #
+    # @example Combined with other filters
+    #   query.ticker("AAPL").form_type("8-K").search_text("acquisition")
+    #   #=> Lucene: 'ticker:AAPL AND formType:"8-K" AND "acquisition"'
+    #
+    def search_text(keywords)
+      raise ArgumentError, "Search keywords are required" if keywords.nil? || keywords.to_s.strip.empty?
+
+      # Escape backslashes first, then quotes for valid Lucene phrase syntax
+      # In gsub replacement, \\\\ (4 backslashes) produces \\ (2 actual backslashes)
+      escaped = keywords.to_s.strip.gsub("\\") { "\\\\" }.gsub('"', '\\"')
+      @query_parts << "\"#{escaped}\""
+      self
+    end
+
+    # Limit the number of results returned.
+    #
+    # Sets the maximum number of filings to return in the response. When not
+    # specified, defaults to 50 results.
+    #
+    # @param count [Integer, String] The maximum number of results (must be positive)
+    # @return [self] Returns self for method chaining
+    # @raise [ArgumentError] when count is zero or negative
+    #
+    # @example Limit to 10 results
+    #   query.ticker("AAPL").limit(10).search
+    #
+    # @example Default behavior (50 results)
+    #   query.ticker("AAPL").search  # Returns up to 50 filings
+    #
+    def limit(count)
+      count = count.to_i
+      raise ArgumentError, "Limit must be a positive integer" if count <= 0
+
+      @page_size = count
+      self
+    end
+
+    # Filter filings by date range.
+    #
+    # @param from [Date, Time, DateTime, String] Start date (inclusive)
+    # @param to [Date, Time, DateTime, String] End date (inclusive)
+    # @return [self] Returns self for method chaining
+    # @raise [ArgumentError] when from or to is nil
+    # @raise [ArgumentError] when from or to is an unsupported type
+    # @raise [ArgumentError] when string is not in ISO 8601 format (YYYY-MM-DD)
+    #
+    # @example With ISO 8601 strings
+    #   query.date_range(from: "2020-01-01", to: "2023-12-31")
+    #
+    # @example With Date objects
+    #   query.date_range(from: Date.new(2020, 1, 1), to: Date.today)
+    #
+    # @example With Time objects (including ActiveSupport::TimeWithZone)
+    #   query.date_range(from: 1.year.ago, to: Time.now)
+    #
+    def date_range(from:, to:)
+      raise ArgumentError, "from: is required" if from.nil?
+      raise ArgumentError, "to: is required" if to.nil?
+
+      from_date = coerce_date(from)
+      to_date = coerce_date(to)
+
+      @query_parts << "filedAt:[#{from_date} TO #{to_date}]"
+      self
+    end
+
+    # Executes the query and returns a lazy enumerator for automatic pagination.
+    #
+    # Convenience method that chains {#search} with {SecApi::Collections::Filings#auto_paginate}.
+    # Useful for backfill operations where you want to process all matching
+    # filings across multiple pages.
+    #
+    # @return [Enumerator::Lazy] lazy enumerator yielding {SecApi::Objects::Filing} objects
+    # @raise [PaginationError] when pagination state is invalid
+    # @raise [AuthenticationError] when API key is invalid (from search)
+    # @raise [RateLimitError] when rate limit exceeded (from search)
+    # @raise [NetworkError] when connection fails (from search)
+    # @raise [ServerError] when API returns 5xx error (from search)
+    #
+    # @example Multi-year backfill
+    #   client.query
+    #     .ticker("AAPL")
+    #     .form_type("10-K", "10-Q")
+    #     .date_range(from: 5.years.ago, to: Date.today)
+    #     .auto_paginate
+    #     .each { |filing| ingest(filing) }
+    #
+    # @see SecApi::Collections::Filings#auto_paginate
+    def auto_paginate
+      search.auto_paginate
+    end
+
+    # Execute the query and return filings.
+    #
+    # This is the terminal method that builds the Lucene query from accumulated
+    # filters and sends it to the sec-api.io API.
+    #
+    # @overload search
+    #   Execute the fluent query built via chained methods.
+    #   @return [SecApi::Collections::Filings] Collection of filing objects
+    #
+    # @overload search(query, options = {})
+    #   Execute a raw Lucene query string (backward-compatible signature).
+    #   @param query [String] Raw Lucene query string
+    #   @param options [Hash] Additional request options (from, size, sort)
+    #   @return [SecApi::Collections::Filings] Collection of filing objects
+    #   @deprecated Use the fluent builder methods instead
+    #
+    # @raise [SecApi::AuthenticationError] when API key is invalid
+    # @raise [SecApi::RateLimitError] when rate limit exceeded
+    # @raise [SecApi::NetworkError] when connection fails
+    # @raise [SecApi::ServerError] when API returns 5xx error
+    #
+    # @example Fluent builder (recommended)
+    #   client.query.ticker("AAPL").search
+    #
+    # @example Raw query (deprecated)
+    #   client.query.search("ticker:AAPL AND formType:\"10-K\"")
+    #
+    def search(query = nil, options = {})
+      if query.is_a?(String)
+        # Backward-compatible: raw query string passed directly
+        warn "[DEPRECATION] Passing raw Lucene query strings to #search is deprecated. " \
+          "Use the fluent builder instead: client.query.ticker('AAPL').form_type('10-K').search"
+        payload = {query: query}.merge(options)
+        response = @_client.connection.post("/", payload)
+        Collections::Filings.new(response.body)
+      else
+        # Fluent builder: build from accumulated query parts
+        lucene_query = to_lucene
+        payload = {
+          query: lucene_query,
+          from: @from_offset.to_s,
+          size: @page_size.to_s,
+          sort: @sort_config
+        }
+
+        # Store query context for pagination (excludes 'from' which changes per page)
+        query_context = {
+          query: lucene_query,
+          size: @page_size.to_s,
+          sort: @sort_config
+        }
+
+        response = @_client.connection.post("/", payload)
+        Collections::Filings.new(response.body, client: @_client, query_context: query_context)
+      end
+    end
+
+    # Returns the assembled Lucene query string for debugging/logging.
+    #
+    # @return [String] The Lucene query string built from accumulated filters
+    #
+    # @example
+    #   query.ticker("AAPL").cik("320193").to_lucene
+    #   #=> "ticker:AAPL AND cik:320193"
+    #
+    def to_lucene
+      @query_parts.join(" AND ")
+    end
+
+    # Execute a full-text search across SEC filings.
+    #
+    # @param query [String] Full-text search query
+    # @param options [Hash] Additional request options
+    # @return [SecApi::Collections::FulltextResults] Full-text search results
+    # @raise [SecApi::AuthenticationError] when API key is invalid
+    # @raise [SecApi::RateLimitError] when rate limit exceeded
+    # @raise [SecApi::NetworkError] when connection fails
+    # @raise [SecApi::ServerError] when API returns 5xx error
+    #
+    def fulltext(query, options = {})
+      response = @_client.connection.post("/full-text-search", {query: query}.merge(options))
+      Collections::FulltextResults.new(response.body)
+    end
+
+    private
+
+    # Coerces various date types to ISO 8601 string format (YYYY-MM-DD).
+    #
+    # Why coercion? Users may pass Date, Time, DateTime, or String depending on
+    # their codebase. The API expects ISO 8601 strings. Rather than force users
+    # to convert, we accept common types and normalize them. This improves DX
+    # without sacrificing type safety (invalid formats still raise ArgumentError).
+    #
+    # @param value [Date, Time, DateTime, String] The date value to coerce
+    # @return [String] ISO 8601 formatted date string
+    # @raise [ArgumentError] when value is an unsupported type
+    # @raise [ArgumentError] when string is not in ISO 8601 format (YYYY-MM-DD)
+    #
+    def coerce_date(value)
+      case value
+      when Date
+        value.strftime("%Y-%m-%d")
+      when Time, DateTime
+        value.to_date.strftime("%Y-%m-%d")
+      when String
+        unless value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          raise ArgumentError, "Date string must be in ISO 8601 format (YYYY-MM-DD), got: #{value.inspect}"
+        end
+        value
+      else
+        if defined?(ActiveSupport::TimeWithZone) && value.is_a?(ActiveSupport::TimeWithZone)
+          value.to_date.strftime("%Y-%m-%d")
+        else
+          raise ArgumentError, "Expected Date, Time, DateTime, or ISO 8601 string, got #{value.class}"
+        end
+      end
+    end
+  end
+end

data/lib/sec_api/rate_limit_state.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module SecApi
+  # Immutable value object representing rate limit state from sec-api.io response headers.
+  #
+  # This class uses Dry::Struct for type safety and immutability, ensuring thread-safe
+  # access to rate limit information. The state is extracted from HTTP response headers:
+  # - X-RateLimit-Limit: Total requests allowed per time window
+  # - X-RateLimit-Remaining: Requests remaining in current window
+  # - X-RateLimit-Reset: Unix timestamp when the limit resets
+  #
+  # @example Access rate limit state from client
+  #   client = SecApi::Client.new
+  #   client.query.ticker("AAPL").search
+  #
+  #   state = client.rate_limit_state
+  #   state.limit        # => 100
+  #   state.remaining    # => 95
+  #   state.reset_at     # => 2026-01-07 12:00:00 +0000
+  #
+  # @example Check if rate limit is exhausted
+  #   if client.rate_limit_state&.exhausted?
+  #     sleep_until(client.rate_limit_state.reset_at)
+  #   end
+  #
+  # @example Calculate percentage remaining for threshold checks
+  #   state = client.rate_limit_state
+  #   if state&.percentage_remaining && state.percentage_remaining < 10
+  #     # Less than 10% remaining, consider throttling
+  #   end
+  #
+  # @see SecApi::RateLimitTracker Thread-safe state storage
+  # @see SecApi::Middleware::RateLimiter Middleware that extracts headers
+  #
+  class RateLimitState < Dry::Struct
+    # Transform keys to allow string or symbol input
+    transform_keys(&:to_sym)
+
+    # Total requests allowed per time window (from X-RateLimit-Limit header).
+    # @return [Integer, nil] The total quota, or nil if header was not present
+    attribute? :limit, Types::Coercible::Integer.optional
+
+    # Requests remaining in current time window (from X-RateLimit-Remaining header).
+    # @return [Integer, nil] Remaining requests, or nil if header was not present
+    attribute? :remaining, Types::Coercible::Integer.optional
+
+    # Time when the rate limit window resets (from X-RateLimit-Reset header).
+    # @return [Time, nil] Reset time, or nil if header was not present
+    attribute? :reset_at, Types::Strict::Time.optional
+
+    # Checks if the rate limit has been exhausted.
+    #
+    # Returns true only when we know for certain that remaining requests is zero.
+    # Returns false if remaining is unknown (nil) or greater than zero.
+    #
+    # @return [Boolean] true if remaining requests is exactly 0, false otherwise
+    #
+    # @example
+    #   state = RateLimitState.new(limit: 100, remaining: 0, reset_at: Time.now + 60)
+    #   state.exhausted?  # => true
+    #
+    #   state = RateLimitState.new(limit: 100, remaining: 5, reset_at: Time.now + 60)
+    #   state.exhausted?  # => false
+    #
+    #   state = RateLimitState.new  # No headers received
+    #   state.exhausted?  # => false (unknown state, assume available)
+    #
+    def exhausted?
+      remaining == 0
+    end
+
+    # Checks if requests are available (not exhausted).
+    #
+    # Returns true if remaining is greater than zero OR if remaining is unknown.
+    # This conservative approach assumes requests are available when state is unknown.
+    #
+    # @return [Boolean] true if remaining > 0 or remaining is unknown, false if exhausted
+    #
+    # @example
+    #   state = RateLimitState.new(limit: 100, remaining: 5, reset_at: Time.now + 60)
+    #   state.available?  # => true
+    #
+    #   state = RateLimitState.new  # No headers received
+    #   state.available?  # => true (unknown state, assume available)
+    #
+    #   state = RateLimitState.new(limit: 100, remaining: 0, reset_at: Time.now + 60)
+    #   state.available?  # => false
+    #
+    def available?
+      !exhausted?
+    end
+
+    # Calculates the percentage of rate limit quota remaining.
+    #
+    # Returns nil if either limit or remaining is unknown, as percentage
+    # cannot be calculated without both values.
+    #
+    # @return [Float, nil] Percentage remaining (0.0 to 100.0), or nil if unknown
+    #
+    # @example Calculate percentage for threshold checking
+    #   state = RateLimitState.new(limit: 100, remaining: 25, reset_at: Time.now + 60)
+    #   state.percentage_remaining  # => 25.0
+    #
+    #   state = RateLimitState.new(limit: 100, remaining: 0, reset_at: Time.now + 60)
+    #   state.percentage_remaining  # => 0.0
+    #
+    # @example Handle unknown state
+    #   state = RateLimitState.new  # No headers received
+    #   state.percentage_remaining  # => nil
+    #
+    #   if (pct = state.percentage_remaining) && pct < 10
+    #     # Throttle when below 10%
+    #   end
+    #
+    def percentage_remaining
+      return nil if limit.nil? || remaining.nil?
+      return 0.0 if limit.zero?
+
+      (remaining.to_f / limit * 100).round(1)
+    end
+
+    # Override constructor to ensure immutability
+    def initialize(attributes = {})
+      super
+      freeze
+    end
+  end
+end

data/lib/sec_api/rate_limit_tracker.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Thread-safe manager for rate limit state and queue tracking.
+  #
+  # This class provides thread-safe storage and access to rate limit information
+  # using a Mutex for synchronization. Each Client instance owns its own tracker,
+  # ensuring rate limit state is isolated per-client.
+  #
+  # The tracker receives updates from the RateLimiter middleware and provides
+  # read access to the current state via the Client#rate_limit_state method.
+  # It also tracks the number of queued requests waiting for rate limit reset.
+  #
+  # @example Basic usage
+  #   tracker = SecApi::RateLimitTracker.new
+  #   tracker.update(limit: 100, remaining: 95, reset_at: Time.now + 60)
+  #
+  #   state = tracker.current_state
+  #   state.limit        # => 100
+  #   state.remaining    # => 95
+  #   state.available?   # => true
+  #
+  # @example Thread-safe concurrent access
+  #   tracker = SecApi::RateLimitTracker.new
+  #
+  #   threads = 10.times.map do |i|
+  #     Thread.new do
+  #       tracker.update(limit: 100, remaining: 100 - i, reset_at: Time.now + 60)
+  #       tracker.current_state  # Thread-safe read
+  #     end
+  #   end
+  #   threads.each(&:join)
+  #
+  # @example Per-client isolation
+  #   client1 = SecApi::Client.new
+  #   client2 = SecApi::Client.new
+  #
+  #   # Each client has independent rate limit tracking
+  #   client1.rate_limit_state  # Client 1's state
+  #   client2.rate_limit_state  # Client 2's state (independent)
+  #
+  # @see SecApi::RateLimitState Immutable state value object
+  # @see SecApi::Middleware::RateLimiter Middleware that updates this tracker
+  #
+  class RateLimitTracker
+    # Creates a new RateLimitTracker instance.
+    #
+    # @example
+    #   tracker = SecApi::RateLimitTracker.new
+    #   tracker.current_state  # => nil (no state yet)
+    #
+    def initialize
+      @mutex = Mutex.new
+      @state = nil
+      @queued_count = 0
+    end
+
+    # Updates the rate limit state with new values.
+    #
+    # Creates a new immutable RateLimitState object with the provided values.
+    # This method is thread-safe and can be called concurrently.
+    #
+    # @param limit [Integer, nil] Total requests allowed per time window
+    # @param remaining [Integer, nil] Requests remaining in current window
+    # @param reset_at [Time, nil] Time when the limit resets
+    # @return [RateLimitState] The newly created state
+    #
+    # @example
+    #   tracker.update(limit: 100, remaining: 95, reset_at: Time.now + 60)
+    #
+    def update(limit:, remaining:, reset_at:)
+      @mutex.synchronize do
+        @state = RateLimitState.new(
+          limit: limit,
+          remaining: remaining,
+          reset_at: reset_at
+        )
+      end
+    end
+
+    # Returns the current rate limit state.
+    #
+    # Returns nil if no rate limit information has been received yet.
+    # The returned RateLimitState is immutable and can be safely used
+    # outside the mutex lock.
+    #
+    # @return [RateLimitState, nil] The current state or nil if unknown
+    #
+    # @example
+    #   state = tracker.current_state
+    #   if state&.exhausted?
+    #     # Handle rate limit exhausted
+    #   end
+    #
+    def current_state
+      @mutex.synchronize { @state }
+    end
+
+    # Clears the current rate limit state.
+    #
+    # After calling reset!, current_state will return nil until
+    # new rate limit headers are received.
+    #
+    # @return [void]
+    #
+    # @example
+    #   tracker.update(limit: 100, remaining: 0, reset_at: Time.now)
+    #   tracker.reset!
+    #   tracker.current_state  # => nil
+    #
+    def reset!
+      @mutex.synchronize { @state = nil }
+    end
+
+    # Returns the current count of queued requests.
+    #
+    # When the rate limit is exhausted (remaining = 0), requests are queued
+    # until the rate limit resets. This method returns the current count of
+    # waiting requests.
+    #
+    # @return [Integer] Number of requests currently queued
+    #
+    # @example
+    #   tracker.queued_count  # => 3 (three requests waiting)
+    #
+    def queued_count
+      @mutex.synchronize { @queued_count }
+    end
+
+    # Increments the queued request counter.
+    #
+    # Called by the RateLimiter middleware when a request enters the queue.
+    #
+    # @return [Integer] The new queued count
+    #
+    def increment_queued
+      @mutex.synchronize do
+        @queued_count += 1
+      end
+    end
+
+    # Decrements the queued request counter.
+    #
+    # Called by the RateLimiter middleware when a request exits the queue.
+    #
+    # @return [Integer] The new queued count
+    #
+    def decrement_queued
+      @mutex.synchronize do
+        @queued_count = [@queued_count - 1, 0].max
+      end
+    end
+  end
+end