sec_api 1.0.0

data/lib/sec_api/structured_logger.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Provides structured JSON logging for SEC API operations.
+  #
+  # This module can be used directly or via the `default_logging` config option.
+  # All log events follow the `secapi.*` naming convention for easy filtering
+  # in log aggregation tools like ELK, Datadog, Splunk, or CloudWatch.
+  #
+  # @example Manual usage with Rails logger
+  #   SecApi::StructuredLogger.log_request(Rails.logger, :info,
+  #     request_id: "abc-123",
+  #     method: :get,
+  #     url: "https://api.sec-api.io/query"
+  #   )
+  #
+  # @example Using with default_logging
+  #   config = SecApi::Config.new(
+  #     api_key: "...",
+  #     logger: Rails.logger,
+  #     default_logging: true
+  #   )
+  #   # All requests/responses now logged automatically
+  #
+  # @example ELK Stack integration
+  #   # Configure Logstash to parse JSON logs:
+  #   # filter {
+  #   #   json { source => "message" }
+  #   # }
+  #   # Query in Kibana: event:"secapi.request.complete" AND status:>=400
+  #
+  # @example Datadog Logs integration
+  #   # Logs are automatically parsed as JSON by Datadog
+  #   # Create facets on: event, request_id, status, duration_ms
+  #   # Alert query: event:secapi.request.error count:>10
+  #
+  # @example Splunk integration
+  #   # Search: sourcetype=ruby_json event="secapi.request.*"
+  #   # | stats avg(duration_ms) by method
+  #
+  # @example CloudWatch Logs integration
+  #   # Filter pattern: { $.event = "secapi.request.error" }
+  #   # Metric filter: Count errors by request_id
+  #
+  module StructuredLogger
+    extend self
+
+    # Logs a request start event.
+    #
+    # @param logger [Logger] Logger instance (Ruby Logger or compatible interface)
+    # @param level [Symbol] Log level (:debug, :info, :warn, :error)
+    # @param request_id [String] Request correlation ID (UUID)
+    # @param method [Symbol] HTTP method (:get, :post, etc.)
+    # @param url [String] Request URL
+    # @return [void]
+    #
+    # @example Basic request logging
+    #   SecApi::StructuredLogger.log_request(logger, :info,
+    #     request_id: "550e8400-e29b-41d4-a716-446655440000",
+    #     method: :get,
+    #     url: "https://api.sec-api.io/query"
+    #   )
+    #   # Output: {"event":"secapi.request.start","request_id":"550e8400-...","method":"GET","url":"https://...","timestamp":"2024-01-15T10:30:00.123Z"}
+    #
+    def log_request(logger, level, request_id:, method:, url:)
+      log_event(logger, level, {
+        event: "secapi.request.start",
+        request_id: request_id,
+        method: method.to_s.upcase,
+        url: url,
+        timestamp: timestamp
+      })
+    end
+
+    # Logs a request completion event.
+    #
+    # @param logger [Logger] Logger instance
+    # @param level [Symbol] Log level (:debug, :info, :warn, :error)
+    # @param request_id [String] Request correlation ID (matches on_request)
+    # @param status [Integer] HTTP status code (200, 429, 500, etc.)
+    # @param duration_ms [Integer, Float] Request duration in milliseconds
+    # @param url [String] Request URL
+    # @param method [Symbol] HTTP method
+    # @return [void]
+    #
+    # @example Response logging with duration
+    #   SecApi::StructuredLogger.log_response(logger, :info,
+    #     request_id: "550e8400-e29b-41d4-a716-446655440000",
+    #     status: 200,
+    #     duration_ms: 150,
+    #     url: "https://api.sec-api.io/query",
+    #     method: :get
+    #   )
+    #   # Output: {"event":"secapi.request.complete","request_id":"550e8400-...","status":200,"duration_ms":150,"success":true,...}
+    #
+    def log_response(logger, level, request_id:, status:, duration_ms:, url:, method:)
+      log_event(logger, level, {
+        event: "secapi.request.complete",
+        request_id: request_id,
+        status: status,
+        duration_ms: duration_ms,
+        method: method.to_s.upcase,
+        url: url,
+        success: status < 400,
+        timestamp: timestamp
+      })
+    end
+
+    # Logs a retry attempt event.
+    #
+    # @param logger [Logger] Logger instance
+    # @param level [Symbol] Log level (typically :warn)
+    # @param request_id [String] Request correlation ID
+    # @param attempt [Integer] Retry attempt number (1-indexed)
+    # @param max_attempts [Integer] Maximum retry attempts configured
+    # @param error_class [String] Exception class name that triggered retry
+    # @param error_message [String] Exception message
+    # @param will_retry_in [Float] Seconds until next retry attempt
+    # @return [void]
+    #
+    # @example Retry logging
+    #   SecApi::StructuredLogger.log_retry(logger, :warn,
+    #     request_id: "550e8400-e29b-41d4-a716-446655440000",
+    #     attempt: 2,
+    #     max_attempts: 5,
+    #     error_class: "SecApi::ServerError",
+    #     error_message: "Internal Server Error",
+    #     will_retry_in: 4.0
+    #   )
+    #   # Output: {"event":"secapi.request.retry","request_id":"550e8400-...","attempt":2,"max_attempts":5,...}
+    #
+    def log_retry(logger, level, request_id:, attempt:, max_attempts:, error_class:, error_message:, will_retry_in:)
+      log_event(logger, level, {
+        event: "secapi.request.retry",
+        request_id: request_id,
+        attempt: attempt,
+        max_attempts: max_attempts,
+        error_class: error_class,
+        error_message: error_message,
+        will_retry_in: will_retry_in,
+        timestamp: timestamp
+      })
+    end
+
+    # Logs a request error event (final failure after all retries).
+    #
+    # @param logger [Logger] Logger instance
+    # @param level [Symbol] Log level (typically :error)
+    # @param request_id [String] Request correlation ID
+    # @param error [Exception] The exception that caused failure
+    # @param url [String] Request URL
+    # @param method [Symbol] HTTP method
+    # @return [void]
+    #
+    # @example Error logging
+    #   SecApi::StructuredLogger.log_error(logger, :error,
+    #     request_id: "550e8400-e29b-41d4-a716-446655440000",
+    #     error: SecApi::AuthenticationError.new("Invalid API key"),
+    #     url: "https://api.sec-api.io/query",
+    #     method: :get
+    #   )
+    #   # Output: {"event":"secapi.request.error","request_id":"550e8400-...","error_class":"SecApi::AuthenticationError",...}
+    #
+    def log_error(logger, level, request_id:, error:, url:, method:)
+      log_event(logger, level, {
+        event: "secapi.request.error",
+        request_id: request_id,
+        error_class: error.class.name,
+        error_message: error.message,
+        method: method.to_s.upcase,
+        url: url,
+        timestamp: timestamp
+      })
+    end
+
+    private
+
+    # Writes a structured log event to the logger.
+    #
+    # @param logger [Logger] Logger instance
+    # @param level [Symbol] Log level
+    # @param data [Hash] Event data to serialize as JSON
+    # @return [void]
+    # @api private
+    def log_event(logger, level, data)
+      logger.send(level) { data.to_json }
+    rescue
+      # Don't let logging errors break the request flow
+    end
+
+    # Returns current UTC timestamp in ISO8601 format with milliseconds.
+    #
+    # @return [String] ISO8601 timestamp (e.g., "2024-01-15T10:30:00.123Z")
+    # @api private
+    def timestamp
+      Time.now.utc.iso8601(3)
+    end
+  end
+end

data/lib/sec_api/types.rb

@@ -0,0 +1,32 @@
+require "dry-struct"
+require "dry/types"
+
+module SecApi
+  # Type definitions for Dry::Struct value objects.
+  #
+  # Why Dry::Types? (Architecture ADR-8: Value Object Strategy)
+  # - Type safety: Catches type mismatches at construction time, not runtime
+  # - Automatic coercion: API returns strings for numbers, Dry::Types handles conversion
+  # - Immutability: Combined with Dry::Struct, ensures thread-safe response objects
+  # - Documentation: Type declarations serve as inline documentation
+  #
+  # Why not plain Ruby classes? We handle financial data where type errors
+  # could lead to incorrect calculations. Explicit types prevent silent failures.
+  #
+  # This module includes Dry::Types and provides type definitions used across
+  # all value objects in the gem. The types ensure type safety and automatic
+  # coercion for API response data.
+  #
+  # @example Using types in a Dry::Struct
+  #   class MyStruct < Dry::Struct
+  #     attribute :name, SecApi::Types::String
+  #     attribute :count, SecApi::Types::Coercible::Integer
+  #     attribute :optional_field, SecApi::Types::String.optional
+  #   end
+  #
+  # @see https://dry-rb.org/gems/dry-types/ Dry::Types documentation
+  #
+  module Types
+    include Dry.Types()
+  end
+end

data/lib/sec_api/version.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Returns the gem version as a Gem::Version object.
+  #
+  # @return [Gem::Version] the version of the gem
+  #
+  # @example
+  #   SecApi.gem_version  # => #<Gem::Version "1.0.0">
+  #   SecApi.gem_version >= Gem::Version.new("1.0.0")  # => true
+  #
+  def self.gem_version
+    Gem::Version.new(VERSION::STRING)
+  end
+
+  # Version information for the sec_api gem.
+  #
+  # @example Access version string
+  #   SecApi::VERSION::STRING  # => "1.0.0"
+  #
+  # @example Access version components
+  #   SecApi::VERSION::MAJOR   # => 1
+  #   SecApi::VERSION::MINOR   # => 0
+  #   SecApi::VERSION::PATCH   # => 0
+  #
+  module VERSION
+    # @return [Integer] Major version number (breaking changes)
+    MAJOR = 1
+
+    # @return [Integer] Minor version number (new features, backwards compatible)
+    MINOR = 0
+
+    # @return [Integer] Patch version number (bug fixes)
+    PATCH = 0
+
+    # @return [String, nil] Pre-release identifier (e.g., "alpha", "beta", "rc1")
+    PRE = nil
+
+    # @return [String] Complete version string (e.g., "0.1.0" or "1.0.0-beta")
+    STRING = [MAJOR, MINOR, PATCH, PRE].compact.join(".")
+  end
+end

data/lib/sec_api/xbrl.rb

@@ -0,0 +1,220 @@
+module SecApi
+  # XBRL extraction proxy for converting SEC EDGAR XBRL filings to structured JSON.
+  #
+  # Extraction Workflow:
+  # 1. Client calls to_json() with URL, accession_no, or Filing object
+  # 2. Input is validated locally (URL format, accession format)
+  # 3. Request sent to sec-api.io XBRL-to-JSON endpoint
+  # 4. Response validated heuristically (has statements? valid structure?)
+  # 5. Data wrapped in immutable XbrlData Dry::Struct object
+  #
+  # Validation Philosophy (Architecture ADR-5):
+  # We use HEURISTIC validation (check structure, required sections) rather than
+  # full XBRL schema validation. Rationale:
+  # - sec-api.io handles taxonomy parsing - we trust their output structure
+  # - Full schema validation would require bundling 100MB+ taxonomy files
+  # - We validate what matters: required sections present, data types coercible
+  # - Catch malformed responses early with actionable error messages
+  #
+  # Provides access to the sec-api.io XBRL-to-JSON API, which extracts financial
+  # statement data from XBRL filings and returns structured, typed data objects.
+  # Supports both US GAAP and IFRS taxonomies.
+  #
+  # @example Extract XBRL data from a filing URL
+  #   client = SecApi::Client.new(api_key: "your_api_key")
+  #   xbrl = client.xbrl.to_json("https://www.sec.gov/Archives/edgar/data/320193/000032019323000106/aapl-20230930.htm")
+  #
+  #   # Access income statement data
+  #   revenue = xbrl.statements_of_income["RevenueFromContractWithCustomerExcludingAssessedTax"]
+  #   revenue.first.to_numeric  # => 394328000000.0
+  #
+  # @example Extract using accession number
+  #   xbrl = client.xbrl.to_json(accession_no: "0000320193-23-000106")
+  #
+  # @example Extract from Filing object
+  #   filing = client.query.ticker("AAPL").form_type("10-K").search.first
+  #   xbrl = client.xbrl.to_json(filing)
+  #
+  # @example Discover available XBRL elements
+  #   xbrl.element_names  # => ["Assets", "CashAndCashEquivalents", "Revenue", ...]
+  #   xbrl.taxonomy_hint  # => :us_gaap or :ifrs
+  #
+  # @note The gem returns element names exactly as provided by sec-api.io without
+  #   normalizing between US GAAP and IFRS taxonomies. Use {XbrlData#element_names}
+  #   to discover available elements in any filing.
+  #
+  # @see SecApi::XbrlData The immutable value object returned by {#to_json}
+  # @see SecApi::Fact Individual financial facts with periods and values
+  #
+  class Xbrl
+    # Pattern for validating SEC EDGAR URLs.
+    # @return [Regexp] regex pattern matching sec.gov domains
+    SEC_URL_PATTERN = %r{\Ahttps?://(?:www\.)?sec\.gov/}i
+
+    # Pattern for dashed accession number format (10-2-6 digits).
+    # @return [Regexp] regex pattern for format like "0000320193-23-000106"
+    # @example
+    #   "0000320193-23-000106".match?(ACCESSION_DASHED_PATTERN) # => true
+    ACCESSION_DASHED_PATTERN = /\A\d{10}-\d{2}-\d{6}\z/
+
+    # Pattern for undashed accession number format (18 consecutive digits).
+    # @return [Regexp] regex pattern for format like "0000320193230001060"
+    # @example
+    #   "0000320193230001060".match?(ACCESSION_UNDASHED_PATTERN) # => true
+    ACCESSION_UNDASHED_PATTERN = /\A\d{18}\z/
+
+    # Creates a new XBRL extraction proxy instance.
+    #
+    # XBRL instances are obtained via {Client#xbrl} and cached
+    # for reuse. Direct instantiation is not recommended.
+    #
+    # @param client [SecApi::Client] The parent client for API access
+    # @return [SecApi::Xbrl] A new XBRL proxy instance
+    # @api private
+    def initialize(client)
+      @_client = client
+    end
+
+    # Extracts XBRL financial data from an SEC filing and returns structured, immutable XbrlData object.
+    #
+    # @overload to_json(url)
+    #   Extract XBRL data from a SEC filing URL.
+    #   @param url [String] SEC EDGAR URL pointing to XBRL document
+    #   @return [SecApi::XbrlData] Immutable XBRL data object
+    #
+    # @overload to_json(accession_no:)
+    #   Extract XBRL data using an accession number.
+    #   @param accession_no [String] SEC accession number (e.g., "0000320193-23-000106")
+    #   @return [SecApi::XbrlData] Immutable XBRL data object
+    #
+    # @overload to_json(filing, options = {})
+    #   Extract XBRL data from a Filing object (backward compatible).
+    #   @param filing [Object] Filing object with xbrl_url and accession_number attributes
+    #   @param options [Hash] Optional parameters to pass to the XBRL extraction API
+    #   @return [SecApi::XbrlData] Immutable XBRL data object
+    #
+    # @raise [SecApi::ValidationError] When input is invalid or XBRL data validation fails
+    # @raise [SecApi::NotFoundError] When filing URL is invalid or has no XBRL data
+    # @raise [SecApi::AuthenticationError] When API key is invalid (401/403)
+    # @raise [SecApi::RateLimitError] When rate limit is exceeded (429) - automatically retried
+    # @raise [SecApi::ServerError] When sec-api.io returns 5xx errors - automatically retried
+    # @raise [SecApi::NetworkError] When connection fails or times out - automatically retried
+    #
+    # @example Extract XBRL data using URL string
+    #   client = SecApi::Client.new(api_key: "your_api_key")
+    #   xbrl_data = client.xbrl.to_json("https://www.sec.gov/Archives/edgar/data/320193/000032019323000106/aapl-20230930.htm")
+    #
+    # @example Extract XBRL data using accession number
+    #   xbrl_data = client.xbrl.to_json(accession_no: "0000320193-23-000106")
+    #
+    # @example Extract XBRL data from Filing object (backward compatible)
+    #   filing = client.query.ticker("AAPL").form_type("10-K").search.first
+    #   xbrl_data = client.xbrl.to_json(filing)
+    #
+    def to_json(input = nil, options = {}, **kwargs)
+      request_params = build_request_params(input, kwargs)
+      request_params.merge!(options) unless options.empty?
+
+      response = @_client.connection.get("/xbrl-to-json", request_params)
+
+      # Return XbrlData object instead of raw hash.
+      # XbrlData.from_api performs heuristic validation:
+      # - Checks at least one statement section exists
+      # - Dry::Struct validates type coercion (string/numeric values)
+      # - Fact objects validate period and value structure
+      # Error handling delegated to middleware (Story 1.2)
+      begin
+        XbrlData.from_api(response.body)
+      rescue Dry::Struct::Error, NoMethodError, TypeError => e
+        # Heuristic validation failed - data structure doesn't match expected format.
+        # This catches issues like missing required fields, wrong types, or malformed
+        # fact arrays. Provide actionable context for debugging.
+        accession = request_params[:"accession-no"] || "unknown"
+        raise ValidationError,
+          "XBRL data validation failed for filing #{accession}: #{e.message}. " \
+          "This may indicate incomplete or malformed filing data from sec-api.io. " \
+          "Check the filing URL and verify the XBRL document is available."
+      end
+    end
+
+    private
+
+    def build_request_params(input, kwargs)
+      # Handle keyword-only call: to_json(accession_no: "...")
+      if input.nil? && kwargs[:accession_no]
+        return build_params_from_accession_no(kwargs[:accession_no])
+      end
+
+      # Handle URL string input: to_json("https://...")
+      if input.is_a?(String)
+        return build_params_from_url(input)
+      end
+
+      # Handle Filing object input (backward compatibility): to_json(filing)
+      if input.respond_to?(:xbrl_url) && input.respond_to?(:accession_number)
+        return build_params_from_filing(input)
+      end
+
+      # Handle hash input with accession_no: to_json(accession_no: "...") passed as positional
+      if input.is_a?(Hash) && input[:accession_no]
+        return build_params_from_accession_no(input[:accession_no])
+      end
+
+      raise ValidationError, "Invalid input: expected URL string, accession_no keyword, or Filing object"
+    end
+
+    def build_params_from_url(url)
+      validate_url!(url)
+      {"xbrl-url": url}
+    end
+
+    def build_params_from_accession_no(accession_no)
+      normalized = normalize_accession_no(accession_no)
+      validate_accession_no!(normalized)
+      {"accession-no": normalized}
+    end
+
+    def build_params_from_filing(filing)
+      params = {}
+      params[:"xbrl-url"] = filing.xbrl_url unless filing.xbrl_url.to_s.empty?
+      params[:"accession-no"] = filing.accession_number unless filing.accession_number.to_s.empty?
+      params
+    end
+
+    def validate_url!(url)
+      begin
+        uri = URI.parse(url)
+        unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+          raise NotFoundError, "Filing not found: invalid URL format. URL must be a valid HTTP/HTTPS URL."
+        end
+      rescue URI::InvalidURIError
+        raise NotFoundError, "Filing not found: invalid URL format '#{url}'. Provide a valid SEC EDGAR URL."
+      end
+
+      unless url.match?(SEC_URL_PATTERN)
+        raise NotFoundError, "Filing not found: URL must be from sec.gov domain. Received: #{url}"
+      end
+    end
+
+    def validate_accession_no!(accession_no)
+      unless accession_no.match?(ACCESSION_DASHED_PATTERN)
+        raise ValidationError,
+          "Invalid accession number format: #{accession_no}. " \
+          "Expected format: XXXXXXXXXX-XX-XXXXXX (10-2-6 digits)"
+      end
+    end
+
+    def normalize_accession_no(accession_no)
+      # Already in dashed format
+      return accession_no if accession_no.match?(ACCESSION_DASHED_PATTERN)
+
+      # Convert undashed to dashed format: 0000320193230001060 -> 0000320193-23-000106
+      if accession_no.match?(ACCESSION_UNDASHED_PATTERN)
+        return "#{accession_no[0, 10]}-#{accession_no[10, 2]}-#{accession_no[12, 6]}"
+      end
+
+      # Return as-is for validation to catch
+      accession_no
+    end
+  end
+end

data/lib/sec_api.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Load Order Dependencies (Architecture ADR-1: Module Loading Strategy)
+#
+# This file establishes the load order for all SecApi modules. Order matters because:
+#
+# 1. Types FIRST: Dry::Types module must be defined before any Dry::Struct classes.
+#    Without this, attribute declarations in value objects will fail with NameError.
+#
+# 2. Errors BEFORE Middleware: Middleware raises typed errors, so error classes
+#    must be loaded first. Base classes before subclasses (Error → TransientError → RateLimitError).
+#
+# 3. Objects BEFORE Collections: Filings collection wraps Filing objects.
+#
+# 4. Helpers BEFORE dependents: DeepFreezable, CallbackHelper, etc. are mixed into
+#    other classes and must be available when those classes are defined.
+#
+# 5. Config BEFORE Client: Client validates config during initialization.
+#
+# Never use require_relative in individual files - all loading happens here.
+# This centralized approach prevents circular dependencies and makes the load
+# order explicit and auditable.
+
+require_relative "sec_api/version"
+require "dry-struct"
+require "dry-types"
+
+# === Foundation Layer ===
+# Types and utilities that everything else depends on
+
+# SecApi::Types module must load FIRST - Dry::Struct classes reference these types
+require "sec_api/types"
+require "sec_api/deep_freezable"
+require "sec_api/callback_helper"
+require "sec_api/structured_logger"
+require "sec_api/metrics_collector"
+require "sec_api/filing_journey"
+
+# === Error Hierarchy ===
+# Base classes before subclasses (Error → TransientError → RateLimitError)
+# Middleware references these error classes, so they must load first
+
+require "sec_api/errors/error"
+require "sec_api/errors/configuration_error"
+require "sec_api/errors/transient_error"
+require "sec_api/errors/permanent_error"
+require "sec_api/errors/rate_limit_error"
+require "sec_api/errors/server_error"
+require "sec_api/errors/network_error"
+require "sec_api/errors/reconnection_error"
+require "sec_api/errors/authentication_error"
+require "sec_api/errors/not_found_error"
+require "sec_api/errors/validation_error"
+require "sec_api/errors/pagination_error"
+
+# === State Tracking ===
+require "sec_api/rate_limit_state"
+require "sec_api/rate_limit_tracker"
+
+# === Middleware Layer ===
+# HTTP middleware for resilience and observability
+
+require "sec_api/middleware/instrumentation"
+require "sec_api/middleware/rate_limiter"
+require "sec_api/middleware/error_handler"
+
+# === Value Objects ===
+# Immutable Dry::Struct objects for API responses
+
+require "sec_api/objects/document_format_file"
+require "sec_api/objects/data_file"
+require "sec_api/objects/entity"
+require "sec_api/objects/filing"
+require "sec_api/objects/fulltext_result"
+require "sec_api/objects/period"
+require "sec_api/objects/fact"
+require "sec_api/objects/xbrl_data"
+require "sec_api/objects/extracted_data"
+require "sec_api/objects/stream_filing"
+
+# === Collections ===
+# Enumerable wrappers for API response arrays
+
+require "sec_api/collections/filings"
+require "sec_api/collections/fulltext_results"
+
+# === API Proxies ===
+# Domain-specific interfaces to API endpoints
+
+require "sec_api/query"
+require "sec_api/extractor"
+require "sec_api/mapping"
+require "sec_api/config"
+require "sec_api/client"
+require "sec_api/xbrl"
+require "sec_api/stream"
+
+# SecApi is a Ruby client library for the sec-api.io API.
+#
+# This gem provides programmatic access to 18+ million SEC EDGAR filings
+# with production-grade error handling, resilience, and observability.
+#
+# @example Basic usage
+#   client = SecApi::Client.new(api_key: "your_api_key")
+#   filings = client.query.ticker("AAPL").form_type("10-K").search
+#   filings.each { |f| puts "#{f.ticker}: #{f.form_type}" }
+#
+# @example Query with date range and full-text search
+#   filings = client.query
+#     .ticker("AAPL", "TSLA")
+#     .form_type("10-K", "10-Q")
+#     .date_range(from: "2020-01-01", to: "2023-12-31")
+#     .search_text("revenue growth")
+#     .search
+#
+# @example Entity resolution (ticker to CIK)
+#   entity = client.mapping.ticker("AAPL")
+#   puts "CIK: #{entity.cik}, Name: #{entity.name}"
+#
+# @example XBRL financial data extraction
+#   filing = client.query.ticker("AAPL").form_type("10-K").search.first
+#   xbrl = client.xbrl.to_json(filing)
+#   revenue = xbrl.statements_of_income["RevenueFromContractWithCustomerExcludingAssessedTax"]
+#
+# @example Real-time filing notifications
+#   client.stream.subscribe(tickers: ["AAPL"]) do |filing|
+#     puts "New filing: #{filing.form_type} at #{filing.filed_at}"
+#   end
+#
+# @see SecApi::Client Main entry point for API interactions
+# @see SecApi::Query Fluent query builder for filing searches
+# @see SecApi::Mapping Entity resolution endpoints
+# @see SecApi::Xbrl XBRL data extraction
+# @see SecApi::Stream Real-time WebSocket notifications
+#
+module SecApi
+end

data/sig/sec_api.rbs

@@ -0,0 +1,4 @@
+module SecApi
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end