sec_api 1.0.0

data/lib/sec_api/objects/period.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module SecApi
+  # Immutable value object representing a time period for XBRL facts.
+  #
+  # Periods can be either:
+  # - Duration: has start_date and end_date (for income statement items)
+  # - Instant: has instant date (for balance sheet items)
+  #
+  # @example Duration period (income statement)
+  #   period = SecApi::Period.new(
+  #     start_date: Date.new(2022, 9, 25),
+  #     end_date: Date.new(2023, 9, 30)
+  #   )
+  #   period.duration? # => true
+  #
+  # @example Instant period (balance sheet)
+  #   period = SecApi::Period.new(instant: Date.new(2023, 9, 30))
+  #   period.instant? # => true
+  #
+  class Period < Dry::Struct
+    transform_keys(&:to_sym)
+
+    attribute? :start_date, Types::JSON::Date.optional
+    attribute? :end_date, Types::JSON::Date.optional
+    attribute? :instant, Types::JSON::Date.optional
+
+    # Returns true if this is a duration period (has start/end dates)
+    #
+    # @return [Boolean]
+    def duration?
+      !start_date.nil? && !end_date.nil?
+    end
+
+    # Returns true if this is an instant period (point-in-time)
+    #
+    # @return [Boolean]
+    def instant?
+      !instant.nil?
+    end
+
+    def initialize(attributes)
+      super
+      freeze
+    end
+
+    # Parses API response data into a Period object.
+    #
+    # @param data [Hash] API response with camelCase or snake_case keys
+    # @return [Period] Immutable Period object
+    #
+    # @example
+    #   Period.from_api({"startDate" => "2023-01-01", "endDate" => "2023-12-31"})
+    #   Period.from_api({"instant" => "2023-09-30"})
+    #
+    def self.from_api(data)
+      # Defensive nil check for direct calls (Fact.from_api validates period presence)
+      return nil if data.nil?
+
+      start_date = data[:startDate] || data["startDate"] || data[:start_date] || data["start_date"]
+      end_date = data[:endDate] || data["endDate"] || data[:end_date] || data["end_date"]
+      instant = data[:instant] || data["instant"]
+
+      validate_structure!(instant, start_date, end_date, data)
+
+      new(
+        start_date: start_date,
+        end_date: end_date,
+        instant: instant
+      )
+    end
+
+    # Validates that period has either instant OR (start_date AND end_date).
+    #
+    # @param instant [String, nil] Instant date value
+    # @param start_date [String, nil] Start date value
+    # @param end_date [String, nil] End date value
+    # @param data [Hash] Original data for error message
+    # @raise [ValidationError] when period structure is invalid
+    #
+    def self.validate_structure!(instant, start_date, end_date, data)
+      has_instant = !instant.nil?
+      has_duration = !start_date.nil? && !end_date.nil?
+
+      return if has_instant || has_duration
+
+      raise ValidationError, "XBRL period has invalid structure. " \
+        "Expected 'instant' or 'startDate'/'endDate'. " \
+        "Received: #{data.inspect}"
+    end
+
+    private_class_method :validate_structure!
+  end
+end

data/lib/sec_api/objects/stream_filing.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module SecApi
+  module Objects
+    # Immutable value object representing a real-time filing from the Stream API.
+    #
+    # StreamFiling contains the filing metadata delivered via WebSocket when
+    # a new filing is published to the SEC EDGAR system. The structure matches
+    # the sec-api.io Stream API message format.
+    #
+    # @example Accessing filing attributes
+    #   stream.subscribe do |filing|
+    #     puts "#{filing.ticker}: #{filing.form_type}"
+    #     puts "Filed at: #{filing.filed_at}"
+    #     puts "Details: #{filing.link_to_filing_details}"
+    #   end
+    #
+    # @note All instances are frozen (immutable) for thread-safety.
+    #
+    class StreamFiling < Dry::Struct
+      include DeepFreezable
+
+      # Transform incoming keys from camelCase to snake_case
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] accession_no
+      #   @return [String] SEC accession number (e.g., "0001193125-24-123456")
+      attribute :accession_no, Types::String
+
+      # @!attribute [r] form_type
+      #   @return [String] SEC form type (e.g., "10-K", "8-K", "10-Q")
+      attribute :form_type, Types::String
+
+      # @!attribute [r] filed_at
+      #   @return [String] Filing timestamp in ISO 8601 format
+      attribute :filed_at, Types::String
+
+      # @!attribute [r] cik
+      #   @return [String] SEC Central Index Key
+      attribute :cik, Types::String
+
+      # @!attribute [r] ticker
+      #   @return [String, nil] Stock ticker symbol (may be nil for some filers)
+      attribute? :ticker, Types::String.optional
+
+      # @!attribute [r] company_name
+      #   @return [String] Company name as registered with SEC
+      attribute :company_name, Types::String
+
+      # @!attribute [r] link_to_filing_details
+      #   @return [String] URL to filing details page on sec-api.io
+      attribute :link_to_filing_details, Types::String
+
+      # @!attribute [r] link_to_txt
+      #   @return [String, nil] URL to plain text version of filing
+      attribute? :link_to_txt, Types::String.optional
+
+      # @!attribute [r] link_to_html
+      #   @return [String, nil] URL to HTML version of filing
+      attribute? :link_to_html, Types::String.optional
+
+      # @!attribute [r] period_of_report
+      #   @return [String, nil] Reporting period date (e.g., "2024-01-15")
+      attribute? :period_of_report, Types::String.optional
+
+      # @!attribute [r] entities
+      #   @return [Array<Hash>, nil] Related entities from the filing
+      attribute? :entities, Types::Array.of(Types::Hash).optional
+
+      # @!attribute [r] document_format_files
+      #   @return [Array<Hash>, nil] Filing document files metadata
+      attribute? :document_format_files, Types::Array.of(Types::Hash).optional
+
+      # @!attribute [r] data_files
+      #   @return [Array<Hash>, nil] XBRL and other data files
+      attribute? :data_files, Types::Array.of(Types::Hash).optional
+
+      # @!attribute [r] received_at
+      #   @return [Time] Timestamp when this filing was received by the client.
+      #     Used for calculating delivery latency from sec-api.io to client.
+      #     Defaults to Time.now when filing is created.
+      attribute :received_at, Types::Time.default { Time.now }
+
+      # Override constructor to ensure deep immutability.
+      #
+      # @api private
+      def initialize(attributes)
+        super
+        deep_freeze(entities) if entities
+        deep_freeze(document_format_files) if document_format_files
+        deep_freeze(data_files) if data_files
+        freeze
+      end
+
+      # Returns the preferred filing URL (HTML if available, otherwise TXT).
+      #
+      # This convenience method provides a single access point for the filing
+      # document URL, preferring the HTML version when available.
+      #
+      # @return [String, nil] the filing URL or nil if neither available
+      # @example
+      #   filing.url #=> "https://sec.gov/Archives/..."
+      #
+      def url
+        return link_to_html unless link_to_html.nil? || link_to_html.empty?
+        return link_to_txt unless link_to_txt.nil? || link_to_txt.empty?
+        nil
+      end
+
+      # Alias for {#url}. Returns the preferred filing URL.
+      #
+      # @return [String, nil] the filing URL or nil if neither available
+      # @see #url
+      #
+      def filing_url
+        url
+      end
+
+      # Alias for {#accession_no}. Returns the SEC accession number.
+      #
+      # Provides compatibility with Filing object API naming conventions.
+      #
+      # @return [String] SEC accession number (e.g., "0001193125-24-123456")
+      # @see #accession_no
+      #
+      def accession_number
+        accession_no
+      end
+
+      # Alias for {#link_to_html}. Returns URL to HTML version of filing.
+      #
+      # @return [String, nil] URL to HTML version of filing
+      # @see #link_to_html
+      #
+      def html_url
+        link_to_html
+      end
+
+      # Alias for {#link_to_txt}. Returns URL to plain text version of filing.
+      #
+      # @return [String, nil] URL to plain text version of filing
+      # @see #link_to_txt
+      #
+      def txt_url
+        link_to_txt
+      end
+
+      # Calculate delivery latency in milliseconds.
+      #
+      # Measures time between when the filing was published to sec-api.io
+      # (filed_at) and when it was received by the client (received_at).
+      #
+      # @return [Integer, nil] Latency in milliseconds, or nil if timestamps unavailable
+      # @example
+      #   filing.latency_ms #=> 1523
+      #
+      def latency_ms
+        return nil unless filed_at && received_at
+
+        filed_time = Time.parse(filed_at)
+        ((received_at - filed_time) * 1000).round
+      rescue ArgumentError
+        nil  # Invalid date string
+      end
+
+      # Calculate delivery latency in seconds.
+      #
+      # @return [Float, nil] Latency in seconds, or nil if timestamps unavailable
+      # @example
+      #   filing.latency_seconds #=> 1.523
+      #
+      def latency_seconds
+        ms = latency_ms
+        ms ? ms / 1000.0 : nil
+      end
+
+      # Check if filing was delivered within the specified latency threshold.
+      #
+      # The default threshold of 120 seconds (2 minutes) corresponds to NFR1.
+      #
+      # @param seconds [Numeric] Maximum acceptable latency in seconds (default: 120)
+      # @return [Boolean] true if latency is within threshold, false otherwise
+      # @example
+      #   filing.within_latency_threshold?      #=> true (if < 2 minutes)
+      #   filing.within_latency_threshold?(60)  #=> false (if > 1 minute)
+      #
+      def within_latency_threshold?(seconds = 120)
+        latency = latency_seconds
+        return false if latency.nil?
+        latency <= seconds
+      end
+    end
+  end
+end

data/lib/sec_api/objects/xbrl_data.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module SecApi
+  # Immutable value object representing XBRL financial data extracted from SEC filings.
+  #
+  # Heuristic Validation Strategy (Architecture ADR-5):
+  # Rather than validating against full XBRL taxonomies (US GAAP, IFRS), we use
+  # heuristic checks that verify data integrity without bundling 100MB+ schema files:
+  #
+  # 1. Structure validation: At least one statement section must be present
+  # 2. Type validation: Dry::Struct enforces correct types via coercion
+  # 3. Fact validation: Each Fact object validates period and value structure
+  # 4. Deep freeze: Immutability enforced at construction time
+  #
+  # Why not full schema validation?
+  # - sec-api.io already validates against taxonomies - we trust their parsing
+  # - Schema files are huge and change with each taxonomy release
+  # - Our heuristics catch the failures that matter: malformed responses, missing data
+  # - Full validation would add latency and complexity without practical benefit
+  #
+  # This class uses Dry::Struct for type safety and immutability, ensuring thread-safe
+  # access to financial data. All nested structures are deeply frozen to prevent modification.
+  #
+  # The structure mirrors the sec-api.io XBRL-to-JSON response format:
+  # - statements_of_income: Income statement elements (e.g., Revenue, NetIncome)
+  # - balance_sheets: Balance sheet elements (e.g., Assets, Liabilities)
+  # - statements_of_cash_flows: Cash flow statement elements
+  # - cover_page: Document and entity information (DEI taxonomy)
+  #
+  # @example Create XbrlData from API response
+  #   xbrl_data = SecApi::XbrlData.from_api(api_response)
+  #   revenue_facts = xbrl_data.statements_of_income["RevenueFromContractWithCustomerExcludingAssessedTax"]
+  #   latest_revenue = revenue_facts.first.to_numeric # => 394328000000.0
+  #
+  # @example Access balance sheet data
+  #   assets_facts = xbrl_data.balance_sheets["Assets"]
+  #   assets_facts.each do |fact|
+  #     puts "#{fact.period.instant}: #{fact.to_numeric}"
+  #   end
+  #
+  # @example Access IFRS filing data (20-F, 40-F)
+  #   # IFRS uses simpler element names than US GAAP
+  #   xbrl_data = client.xbrl.to_json("https://www.sec.gov/path/to/20f-filing.htm")
+  #
+  #   # IFRS: "Revenue" vs US GAAP: "RevenueFromContractWithCustomerExcludingAssessedTax"
+  #   revenue_facts = xbrl_data.statements_of_income["Revenue"]
+  #   revenue_facts&.first&.to_numeric  # => 52896000000.0
+  #
+  #   # IFRS: "Equity" vs US GAAP: "StockholdersEquity"
+  #   equity_facts = xbrl_data.balance_sheets["Equity"]
+  #   equity_facts&.first&.to_numeric  # => 53087000000.0
+  #
+  #   # Use element_names to discover what's available
+  #   xbrl_data.element_names.grep(/Revenue|Equity/)
+  #   # => ["Equity", "Revenue"]
+  #
+  # @note Taxonomy Transparency - Element Names Are NOT Normalized
+  #   This gem returns element names exactly as provided by sec-api.io, without any
+  #   normalization between US GAAP and IFRS taxonomies. This design decision ensures:
+  #
+  #   - **Accuracy:** You see exactly what the company reported
+  #   - **No data loss:** Taxonomy-specific nuances are preserved
+  #   - **Predictability:** The gem never modifies financial data
+  #
+  #   Users are responsible for knowing which elements to access based on the filing's
+  #   taxonomy. Use {#element_names} to discover available elements in any filing.
+  #
+  # @note US GAAP Taxonomy Common Elements
+  #   US domestic filings (10-K, 10-Q) use US GAAP taxonomy with verbose element names:
+  #
+  #   **Income Statement:**
+  #   - RevenueFromContractWithCustomerExcludingAssessedTax (revenue)
+  #   - CostOfGoodsAndServicesSold (cost of goods sold)
+  #   - NetIncomeLoss (net income)
+  #   - GrossProfit (gross profit)
+  #   - OperatingIncomeLoss (operating income)
+  #
+  #   **Balance Sheet:**
+  #   - Assets (total assets)
+  #   - Liabilities (total liabilities)
+  #   - StockholdersEquity (shareholders' equity)
+  #   - CashAndCashEquivalentsAtCarryingValue (cash)
+  #   - AccountsReceivableNetCurrent (accounts receivable)
+  #
+  #   **Cash Flow Statement:**
+  #   - NetCashProvidedByUsedInOperatingActivities (operating cash flow)
+  #   - NetCashProvidedByUsedInInvestingActivities (investing cash flow)
+  #   - NetCashProvidedByUsedInFinancingActivities (financing cash flow)
+  #
+  # @note IFRS Taxonomy Common Elements
+  #   Foreign issuer filings (20-F, 40-F) often use IFRS taxonomy with simpler element names:
+  #
+  #   **Income Statement:**
+  #   - Revenue (revenue)
+  #   - CostOfSales (cost of sales)
+  #   - ProfitLoss (net income/profit)
+  #   - GrossProfit (gross profit)
+  #
+  #   **Balance Sheet:**
+  #   - Assets (total assets - same as US GAAP)
+  #   - Liabilities (total liabilities - same as US GAAP)
+  #   - Equity (shareholders' equity - NOT StockholdersEquity)
+  #
+  #   **Cash Flow Statement:**
+  #   - CashFlowsFromUsedInOperatingActivities (operating cash flow)
+  #   - CashFlowsFromUsedInInvestingActivities (investing cash flow)
+  #   - CashFlowsFromUsedInFinancingActivities (financing cash flow)
+  #
+  #   Note: Element names are NOT normalized between taxonomies. Users working with
+  #   international filings should use {#element_names} to discover available elements.
+  #
+  # @see https://dry-rb.org/gems/dry-struct/ Dry::Struct documentation
+  # @see https://sec-api.io/docs/xbrl-to-json sec-api.io XBRL-to-JSON API
+  #
+  class XbrlData < Dry::Struct
+    include DeepFreezable
+
+    # Transform keys to allow string or symbol input
+    transform_keys(&:to_sym)
+
+    # Statement hash type: element_name => Array of Fact objects
+    StatementHash = Types::Hash.map(Types::String, Types::Array.of(Fact)).optional
+
+    # Statements of income (income statement elements)
+    attribute? :statements_of_income, StatementHash
+
+    # Balance sheets (balance sheet elements)
+    attribute? :balance_sheets, StatementHash
+
+    # Statements of cash flows (cash flow statement elements)
+    attribute? :statements_of_cash_flows, StatementHash
+
+    # Cover page (document and entity information from DEI taxonomy)
+    attribute? :cover_page, StatementHash
+
+    # Checks if this XbrlData object has valid structure.
+    #
+    # Returns true if at least one financial statement section is present.
+    # This method is useful for defensive programming when XbrlData objects
+    # are created via the constructor directly (bypassing from_api validation).
+    #
+    # Note: Objects created via from_api are guaranteed valid, as validation
+    # happens at construction time and raises ValidationError on failure.
+    #
+    # @return [Boolean] true if structure is valid, false otherwise
+    #
+    # @example Check validity before processing
+    #   xbrl_data = client.xbrl.to_json(filing_url)
+    #   if xbrl_data.valid?
+    #     process_financial_data(xbrl_data)
+    #   end
+    #
+    # @example Always true for from_api objects
+    #   xbrl_data = XbrlData.from_api(response)  # Raises if invalid
+    #   xbrl_data.valid?  # => true (guaranteed)
+    #
+    def valid?
+      [statements_of_income, balance_sheets, statements_of_cash_flows, cover_page].any?
+    end
+
+    # Returns all unique element names across all financial statements.
+    #
+    # This method is essential for discovering what XBRL elements are available
+    # in a filing. Element names vary by taxonomy (US GAAP vs IFRS) and by company.
+    # The gem does NOT normalize element names between taxonomies.
+    #
+    # @return [Array<String>] Sorted, unique element names from all statements
+    #
+    # @example Discover available elements in US GAAP filing
+    #   xbrl_data = client.xbrl.to_json(filing_url)
+    #   xbrl_data.element_names
+    #   # => ["Assets", "CostOfGoodsAndServicesSold", "DocumentType", ...]
+    #
+    # @example Search for revenue-related elements
+    #   xbrl_data.element_names.grep(/Revenue/)
+    #   # => ["RevenueFromContractWithCustomerExcludingAssessedTax", ...]
+    #
+    # @example Discover elements in IFRS filing (20-F, 40-F)
+    #   ifrs_data = client.xbrl.to_json("https://www.sec.gov/path/to/20f.htm")
+    #   ifrs_data.element_names.grep(/Revenue|Profit/)
+    #   # => ["ProfitLoss", "Revenue"]  # Simpler names than US GAAP
+    #
+    # @note Use this method to understand what data is available before accessing
+    #   specific elements. This is especially important for international filings
+    #   where element names differ from US GAAP conventions.
+    #
+    def element_names
+      names = []
+      names.concat(statements_of_income.keys) if statements_of_income
+      names.concat(balance_sheets.keys) if balance_sheets
+      names.concat(statements_of_cash_flows.keys) if statements_of_cash_flows
+      names.concat(cover_page.keys) if cover_page
+      names.uniq.sort
+    end
+
+    # Attempts to detect the taxonomy used in this XBRL filing based on element names.
+    #
+    # This method uses heuristics to guess whether the filing uses US GAAP or IFRS
+    # taxonomy. Detection is based on characteristic element name patterns:
+    #
+    # - **US GAAP indicators:** Verbose element names like "StockholdersEquity",
+    #   "RevenueFromContractWithCustomerExcludingAssessedTax",
+    #   "NetCashProvidedByUsedInOperatingActivities"
+    #
+    # - **IFRS indicators:** Simpler element names like "Equity", "Revenue",
+    #   "ProfitLoss", "CashFlowsFromUsedInOperatingActivities"
+    #
+    # @return [Symbol] :us_gaap, :ifrs, or :unknown
+    #
+    # @example Detect taxonomy before processing
+    #   xbrl_data = client.xbrl.to_json(filing_url)
+    #   case xbrl_data.taxonomy_hint
+    #   when :us_gaap
+    #     revenue = xbrl_data.statements_of_income["RevenueFromContractWithCustomerExcludingAssessedTax"]
+    #   when :ifrs
+    #     revenue = xbrl_data.statements_of_income["Revenue"]
+    #   else
+    #     # Fall back to element_names discovery
+    #     revenue_key = xbrl_data.element_names.find { |n| n.include?("Revenue") }
+    #     revenue = xbrl_data.statements_of_income[revenue_key]
+    #   end
+    #
+    # @note This is a best-effort heuristic and may not be 100% accurate.
+    #   Some filings may use mixed element naming conventions or custom elements
+    #   that don't clearly indicate either taxonomy. Always verify with {#element_names}
+    #   when uncertain. For authoritative taxonomy information, refer to the filing's
+    #   original XBRL instance document.
+    #
+    def taxonomy_hint
+      names = element_names
+
+      # US GAAP indicators - verbose, specific naming patterns
+      us_gaap_patterns = [
+        /StockholdersEquity/,
+        /RevenueFromContractWithCustomer/,
+        /CostOfGoodsAndServicesSold/,
+        /NetCashProvidedByUsedIn/,
+        /NetIncomeLoss/,
+        /CommonStockSharesOutstanding/,
+        /OperatingLeaseLiability/,
+        /PropertyPlantAndEquipmentNet/
+      ]
+
+      # IFRS indicators - simpler, shorter naming patterns
+      ifrs_patterns = [
+        /\AEquity\z/,  # Exact match for "Equity" (vs "StockholdersEquity")
+        /\ARevenue\z/,  # Exact match for "Revenue"
+        /\AProfitLoss\z/,
+        /\ACostOfSales\z/,
+        /CashFlowsFromUsedIn/  # Substring match: IFRS variants like "CashFlowsFromUsedInOperatingActivities"
+      ]
+
+      us_gaap_score = us_gaap_patterns.count { |pattern| names.any? { |name| name.match?(pattern) } }
+      ifrs_score = ifrs_patterns.count { |pattern| names.any? { |name| name.match?(pattern) } }
+
+      return :us_gaap if us_gaap_score > ifrs_score && us_gaap_score > 0
+      return :ifrs if ifrs_score > us_gaap_score && ifrs_score > 0
+      :unknown
+    end
+
+    # Override constructor to ensure deep immutability
+    def initialize(attributes)
+      super
+      deep_freeze(statements_of_income) if statements_of_income
+      deep_freeze(balance_sheets) if balance_sheets
+      deep_freeze(statements_of_cash_flows) if statements_of_cash_flows
+      deep_freeze(cover_page) if cover_page
+      freeze
+    end
+
+    # Parses sec-api.io XBRL-to-JSON response into an XbrlData object.
+    #
+    # @param data [Hash] API response with camelCase section keys
+    # @return [XbrlData] Immutable XbrlData object
+    #
+    # @example
+    #   response = {
+    #     StatementsOfIncome: {
+    #       RevenueFromContractWithCustomerExcludingAssessedTax: [
+    #         {value: "394328000000", decimals: "-6", unitRef: "usd", period: {...}}
+    #       ]
+    #     },
+    #     BalanceSheets: {...},
+    #     StatementsOfCashFlows: {...},
+    #     CoverPage: {...}
+    #   }
+    #   xbrl_data = XbrlData.from_api(response)
+    #
+    def self.from_api(data)
+      statements_of_income = parse_statement_section(data, :StatementsOfIncome, "StatementsOfIncome")
+      balance_sheets = parse_statement_section(data, :BalanceSheets, "BalanceSheets")
+      statements_of_cash_flows = parse_statement_section(data, :StatementsOfCashFlows, "StatementsOfCashFlows")
+      cover_page = parse_statement_section(data, :CoverPage, "CoverPage")
+
+      validate_has_statements!(statements_of_income, balance_sheets, statements_of_cash_flows, cover_page, data)
+
+      new(
+        statements_of_income: statements_of_income,
+        balance_sheets: balance_sheets,
+        statements_of_cash_flows: statements_of_cash_flows,
+        cover_page: cover_page
+      )
+    end
+
+    # Validates that at least one financial statement section is present.
+    #
+    # This is the core heuristic validation check. Rationale:
+    # - Valid XBRL filings always have at least one statement section
+    # - Empty responses indicate filing doesn't have XBRL data (older filings)
+    # - Malformed responses from API errors will also fail this check
+    # - We don't validate specific element names - those vary by taxonomy
+    #
+    # @param statements_of_income [Hash, nil] Parsed income statement
+    # @param balance_sheets [Hash, nil] Parsed balance sheet
+    # @param statements_of_cash_flows [Hash, nil] Parsed cash flow statement
+    # @param cover_page [Hash, nil] Parsed cover page
+    # @param original_data [Hash] Original API response for error context
+    # @raise [ValidationError] when all statement sections are nil
+    #
+    def self.validate_has_statements!(statements_of_income, balance_sheets, statements_of_cash_flows, cover_page, original_data)
+      has_any_statement = [statements_of_income, balance_sheets, statements_of_cash_flows, cover_page].any?
+
+      return if has_any_statement
+
+      raise ValidationError, "XBRL response contains no financial statements. " \
+        "Expected at least one of: StatementsOfIncome, BalanceSheets, StatementsOfCashFlows, CoverPage. " \
+        "Received keys: #{original_data.keys.inspect}"
+    end
+
+    private_class_method :validate_has_statements!
+
+    # Parses a statement section from API response.
+    #
+    # @param data [Hash] Full API response
+    # @param symbol_key [Symbol] Symbol key for the section
+    # @param string_key [String] String key for the section
+    # @return [Hash, nil] Parsed section or nil if not present
+    #
+    def self.parse_statement_section(data, symbol_key, string_key)
+      section = data[symbol_key] || data[string_key]
+      return nil if section.nil?
+
+      result = {}
+      section.each do |element_name, facts_array|
+        # Convert element name to string (preserve original taxonomy name)
+        element_key = element_name.to_s
+        result[element_key] = facts_array.map { |fact_data| Fact.from_api(fact_data) }
+      end
+      result
+    end
+
+    private_class_method :parse_statement_section
+  end
+end