sec_api 1.0.0

data/lib/sec_api/objects/entity.rb

@@ -0,0 +1,92 @@
+require "dry/struct"
+
+module SecApi
+  # Value objects namespace for immutable, thread-safe data structures.
+  #
+  # All objects in this namespace are Dry::Struct subclasses that are frozen
+  # on construction. They represent API response data in a type-safe manner.
+  #
+  # @see SecApi::Objects::Filing SEC filing metadata
+  # @see SecApi::Objects::Entity Company/issuer entity information
+  # @see SecApi::Objects::StreamFiling Real-time filing notification
+  # @see SecApi::Objects::XbrlData XBRL financial data
+  #
+  module Objects
+    # Represents a company or issuer entity from SEC EDGAR.
+    #
+    # Entity objects are returned from mapping API calls and contain
+    # identifying information such as CIK, ticker, company name, and
+    # regulatory details. All instances are immutable (frozen).
+    #
+    # @example Entity from ticker resolution
+    #   entity = client.mapping.ticker("AAPL")
+    #   entity.cik      # => "0000320193"
+    #   entity.ticker   # => "AAPL"
+    #   entity.name     # => "Apple Inc."
+    #
+    # @example Entity from CIK resolution
+    #   entity = client.mapping.cik("320193")
+    #   entity.ticker   # => "AAPL"
+    #
+    # @see SecApi::Mapping Entity resolution API
+    #
+    class Entity < Dry::Struct
+      transform_keys { |key| key.to_s.underscore }
+      transform_keys(&:to_sym)
+
+      attribute :cik, Types::String
+      attribute? :name, Types::String.optional
+      attribute? :irs_number, Types::String.optional
+      attribute? :state_of_incorporation, Types::String.optional
+      attribute? :fiscal_year_end, Types::String.optional
+      attribute? :type, Types::String.optional
+      attribute? :act, Types::String.optional
+      attribute? :file_number, Types::String.optional
+      attribute? :film_number, Types::String.optional
+      attribute? :sic, Types::String.optional
+      attribute? :ticker, Types::String.optional
+      attribute? :exchange, Types::String.optional
+      attribute? :cusip, Types::String.optional
+
+      # Override constructor to ensure immutability
+      def initialize(attributes)
+        super
+        freeze
+      end
+
+      # Creates an Entity from API response data.
+      #
+      # Normalizes camelCase keys from the API to snake_case and handles
+      # both symbol and string keys in the input hash.
+      #
+      # @param data [Hash] API response hash with entity data
+      # @return [Entity] Immutable entity object
+      #
+      # @example
+      #   data = { cik: "0000320193", companyName: "Apple Inc.", ticker: "AAPL" }
+      #   entity = Entity.from_api(data)
+      #   entity.name  # => "Apple Inc."
+      #
+      def self.from_api(data)
+        # Non-destructive normalization - create new hash instead of mutating input
+        normalized = {
+          cik: data[:cik] || data["cik"],
+          name: data[:name] || data[:companyName] || data["name"] || data["companyName"],
+          irs_number: data[:irs_number] || data[:irsNo] || data["irs_number"] || data["irsNo"],
+          state_of_incorporation: data[:state_of_incorporation] || data[:stateOfIncorporation] || data["state_of_incorporation"] || data["stateOfIncorporation"],
+          fiscal_year_end: data[:fiscal_year_end] || data[:fiscalYearEnd] || data["fiscal_year_end"] || data["fiscalYearEnd"],
+          type: data[:type] || data["type"],
+          act: data[:act] || data["act"],
+          file_number: data[:file_number] || data[:fileNo] || data["file_number"] || data["fileNo"],
+          film_number: data[:film_number] || data[:filmNo] || data["film_number"] || data["filmNo"],
+          sic: data[:sic] || data["sic"],
+          ticker: data[:ticker] || data["ticker"],
+          exchange: data[:exchange] || data["exchange"],
+          cusip: data[:cusip] || data["cusip"]
+        }
+
+        new(normalized)
+      end
+    end
+  end
+end

data/lib/sec_api/objects/extracted_data.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module SecApi
+  # Represents extracted data from SEC filings
+  #
+  # This immutable value object wraps extraction results from the sec-api.io
+  # Extractor endpoint. All attributes are optional to handle varying API
+  # response structures across different form types.
+  #
+  # @example Creating from API response
+  #   api_response = {
+  #     "text" => "Full extracted text...",
+  #     "sections" => { "risk_factors" => "Risk content..." },
+  #     "metadata" => { "source_url" => "https://..." }
+  #   }
+  #   data = SecApi::ExtractedData.from_api(api_response)
+  #   data.text       # => "Full extracted text..."
+  #   data.sections   # => { risk_factors: "Risk content..." }
+  #
+  # @example Thread-safe concurrent access
+  #   threads = 10.times.map do
+  #     Thread.new { data.text; data.sections }
+  #   end
+  #   threads.each(&:join) # No race conditions
+  class ExtractedData < Dry::Struct
+    include DeepFreezable
+
+    # Transform keys to allow string or symbol input
+    transform_keys(&:to_sym)
+
+    # Full extracted text (if extracting entire filing)
+    # @return [String, nil]
+    attribute? :text, Types::String.optional
+
+    # Structured sections (risk_factors, financials, etc.)
+    # API returns hash like { "risk_factors": "...", "financials": "..." }
+    # @return [Hash{Symbol => String}, nil]
+    attribute? :sections, Types::Hash.map(Types::Symbol, Types::String).optional
+
+    # Metadata about extraction
+    # Flexible hash to handle varying API response structures
+    # @return [Hash, nil]
+    attribute? :metadata, Types::Hash.optional
+
+    # Explicit freeze for immutability and thread safety
+    # Deep freeze all nested hashes and strings to ensure thread safety
+    # @param attributes [Hash] The attributes hash
+    def initialize(attributes)
+      super
+      text&.freeze
+      deep_freeze(sections) if sections
+      deep_freeze(metadata) if metadata
+      freeze
+    end
+
+    # Normalize API response (handle string vs symbol keys)
+    #
+    # @param data [Hash] The raw API response
+    # @return [ExtractedData] The normalized extracted data object
+    def self.from_api(data)
+      new(
+        text: data["text"] || data[:text],
+        sections: normalize_sections(data["sections"] || data[:sections]),
+        metadata: data["metadata"] || data[:metadata] || {}
+      )
+    end
+
+    # Access a specific section by name using dynamic method dispatch
+    #
+    # Allows convenient access to sections via method calls instead of hash access.
+    # Returns nil for missing sections (no NoMethodError raised for section names).
+    # Methods with special suffixes (!, ?, =) still raise NoMethodError.
+    #
+    # @param name [Symbol] The section name to access
+    # @param args [Array] Additional arguments (ignored)
+    # @return [String, nil] The section content or nil if not present
+    #
+    # @example Access risk factors section
+    #   extracted.risk_factors  # => "Risk factor text..."
+    #
+    # @example Access missing section
+    #   extracted.nonexistent   # => nil (no error)
+    def method_missing(name, *args)
+      # Only handle zero-argument calls (getter-style)
+      return super if args.any?
+
+      # Don't intercept bang, predicate, or setter methods
+      name_str = name.to_s
+      return super if name_str.end_with?("!", "?", "=")
+
+      # Return section content if sections exist, nil otherwise
+      sections&.[](name)
+    end
+
+    # Support respond_to? for sections that exist in the hash
+    #
+    # Only responds true for section names that are actually present
+    # in the sections hash. This allows proper Ruby introspection.
+    #
+    # @param name [Symbol] The method name to check
+    # @param include_private [Boolean] Whether to include private methods
+    # @return [Boolean] true if section exists in hash
+    def respond_to_missing?(name, include_private = false)
+      sections&.key?(name) || super
+    end
+
+    # Normalize sections hash to symbol keys
+    #
+    # @param sections [Hash, nil] The sections hash from API
+    # @return [Hash{Symbol => String}, nil]
+    private_class_method def self.normalize_sections(sections)
+      return nil unless sections
+      sections.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/sec_api/objects/fact.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module SecApi
+  # Immutable value object representing a single XBRL fact from SEC filings.
+  #
+  # A fact represents a single data point in financial statements, containing
+  # the value along with its context (period, units, precision).
+  #
+  # @example Creating a Fact with all attributes
+  #   fact = SecApi::Fact.new(
+  #     value: "394328000000",
+  #     decimals: "-6",
+  #     unit_ref: "usd",
+  #     period: SecApi::Period.new(start_date: "2022-09-25", end_date: "2023-09-30")
+  #   )
+  #   fact.to_numeric # => 394328000000.0
+  #
+  # @example Creating from API response
+  #   fact = SecApi::Fact.from_api({
+  #     "value" => "394328000000",
+  #     "decimals" => "-6",
+  #     "unitRef" => "usd",
+  #     "period" => {"startDate" => "2022-09-25", "endDate" => "2023-09-30"}
+  #   })
+  #
+  class Fact < Dry::Struct
+    include DeepFreezable
+
+    transform_keys(&:to_sym)
+
+    # The raw value from the XBRL document (always a string from API)
+    attribute :value, Types::String
+
+    # Precision indicator (e.g., "-6" means millions)
+    attribute? :decimals, Types::String.optional
+
+    # Currency or unit reference (e.g., "usd", "shares")
+    attribute? :unit_ref, Types::String.optional
+
+    # Time period for this fact (duration or instant)
+    attribute? :period, Period.optional
+
+    # Optional dimensional breakdown (for segment-level data)
+    attribute? :segment, Types::Hash.optional
+
+    # Converts the string value to a Float for calculations.
+    #
+    # @return [Float] Numeric value (0.0 for non-numeric strings)
+    #
+    # @example
+    #   fact = Fact.new(value: "394328000000")
+    #   fact.to_numeric # => 394328000000.0
+    #
+    def to_numeric
+      value.to_f
+    end
+
+    # Checks if the value can be safely converted to a numeric type.
+    #
+    # This predicate is useful for filtering facts before numeric operations,
+    # as XBRL facts may contain text values like "N/A" or formatted strings
+    # like "1,000,000" that won't convert properly.
+    #
+    # Supports:
+    # - Integers (positive and negative)
+    # - Decimals (positive and negative)
+    # - Scientific notation (e.g., "1.5e10", "-2.5E-3")
+    # - Leading/trailing whitespace around valid numbers
+    #
+    # Does NOT support (returns false):
+    # - Comma-formatted numbers ("1,000,000")
+    # - Currency symbols ("$100")
+    # - Percentages ("10%")
+    # - Text values ("N/A", "none")
+    # - Empty or whitespace-only strings
+    #
+    # @return [Boolean] true if value is a valid numeric string
+    #
+    # @example Check before conversion
+    #   fact = Fact.new(value: "394328000000")
+    #   fact.numeric?  # => true
+    #   fact.to_numeric  # => 394328000000.0
+    #
+    # @example Filter numeric facts
+    #   facts.select(&:numeric?).map(&:to_numeric)
+    #
+    # @note Leading plus signs (+123) return false as XBRL values use
+    #   unadorned positive numbers. Only explicit minus signs are supported.
+    #
+    def numeric?
+      return false if value.strip.empty?
+
+      # Match integers, decimals, and scientific notation
+      # Allows optional leading/trailing whitespace, minus sign only (no +)
+      !!value.match?(/\A\s*-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\s*\z/)
+    end
+
+    def initialize(attributes)
+      super
+      deep_freeze(segment) if segment
+      freeze
+    end
+
+    # Parses API response data into a Fact object.
+    #
+    # @param data [Hash] API response with camelCase or snake_case keys
+    # @return [Fact] Immutable Fact object
+    #
+    # @example
+    #   Fact.from_api({
+    #     "value" => "1000000",
+    #     "decimals" => "-3",
+    #     "unitRef" => "usd",
+    #     "period" => {"instant" => "2023-09-30"}
+    #   })
+    #
+    def self.from_api(data)
+      raw_value = data[:value] || data["value"]
+
+      if raw_value.nil?
+        raise ValidationError, "XBRL fact missing required 'value' field. " \
+          "Received: #{data.inspect}"
+      end
+
+      period_data = data[:period] || data["period"]
+
+      if period_data.nil?
+        raise ValidationError, "XBRL fact missing required 'period' field. " \
+          "Received: #{data.inspect}"
+      end
+
+      segment_data = data[:segment] || data["segment"]
+
+      normalized = {
+        value: raw_value.to_s,
+        decimals: data[:decimals] || data["decimals"],
+        unit_ref: data[:unitRef] || data["unitRef"] || data[:unit_ref] || data["unit_ref"],
+        period: Period.from_api(period_data),
+        segment: segment_data
+      }
+
+      new(normalized)
+    end
+  end
+end

data/lib/sec_api/objects/filing.rb

@@ -0,0 +1,197 @@
+require "dry/struct"
+require "sec_api/objects/data_file"
+require "sec_api/objects/document_format_file"
+require "sec_api/objects/entity"
+
+module SecApi
+  module Objects
+    # Represents an SEC filing with complete metadata.
+    #
+    # Filing objects are immutable (frozen) and thread-safe for concurrent access.
+    # All date strings are automatically coerced to Ruby Date objects via Dry::Types.
+    #
+    # @example Accessing filing metadata
+    #   filing = client.query.where(ticker: "AAPL").first
+    #   filing.ticker         #=> "AAPL"
+    #   filing.form_type      #=> "10-K"
+    #   filing.accession_no   #=> "0000320193-24-000001"
+    #   filing.filed_at       #=> #<Date: 2024-01-15>
+    #   filing.filing_url     #=> "https://sec.gov/..."
+    #
+    # @see SecApi::Collections::Filings
+    class Filing < Dry::Struct
+      transform_keys { |key| key.to_s.underscore }
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] id
+      #   @return [String] unique filing identifier
+      attribute :id, Types::String
+
+      # @!attribute [r] cik
+      #   @return [String] SEC Central Index Key (e.g., "320193")
+      attribute :cik, Types::String
+
+      # @!attribute [r] ticker
+      #   @return [String] company stock ticker symbol (e.g., "AAPL")
+      attribute :ticker, Types::String
+
+      # @!attribute [r] company_name
+      #   @return [String] company name (e.g., "Apple Inc")
+      attribute :company_name, Types::String
+
+      # @!attribute [r] company_name_long
+      #   @return [String] full company name (e.g., "Apple Inc.")
+      attribute :company_name_long, Types::String
+
+      # @!attribute [r] form_type
+      #   @return [String] SEC form type. Includes both domestic forms (10-K, 10-Q, 8-K, etc.)
+      #     and international forms (20-F, 40-F, 6-K for foreign private issuers).
+      #   @note Filing objects handle all form types uniformly - no special handling for
+      #     international forms. The same structure applies to domestic and foreign filings.
+      #   @see SecApi::Query::INTERNATIONAL_FORM_TYPES
+      #   @see SecApi::Query::DOMESTIC_FORM_TYPES
+      #   @example Domestic filing
+      #     filing.form_type  #=> "10-K"
+      #   @example Foreign private issuer annual report
+      #     filing.form_type  #=> "20-F"
+      #   @example Canadian issuer annual report (MJDS)
+      #     filing.form_type  #=> "40-F"
+      #   @example Foreign current report
+      #     filing.form_type  #=> "6-K"
+      attribute :form_type, Types::String
+
+      # @!attribute [r] period_of_report
+      #   @return [String] reporting period end date
+      attribute :period_of_report, Types::String
+
+      # @!attribute [r] filed_at
+      #   @return [Date] filing date (automatically coerced from string via Dry::Types)
+      attribute :filed_at, Types::JSON::Date
+
+      # @!attribute [r] txt_url
+      #   @return [String] URL to plain text filing
+      attribute :txt_url, Types::String
+
+      # @!attribute [r] html_url
+      #   @return [String] URL to HTML filing
+      attribute :html_url, Types::String
+
+      # @!attribute [r] xbrl_url
+      #   @return [String] URL to XBRL filing
+      attribute :xbrl_url, Types::String
+
+      # @!attribute [r] filing_details_url
+      #   @return [String] URL to filing details page
+      attribute :filing_details_url, Types::String
+
+      # @!attribute [r] entities
+      #   @return [Array<Entity>] associated entities
+      attribute :entities, Types::Array.of(Entity)
+
+      # @!attribute [r] documents
+      #   @return [Array<DocumentFormatFile>] document format files
+      attribute :documents, Types::Array.of(DocumentFormatFile)
+
+      # @!attribute [r] data_files
+      #   @return [Array<DataFile>] associated data files
+      attribute :data_files, Types::Array.of(DataFile)
+
+      # @!attribute [r] accession_number
+      #   @return [String] SEC accession number (e.g., "0000320193-24-000001")
+      attribute :accession_number, Types::String
+
+      # @!attribute [r] description
+      #   @return [String, nil] optional filing description
+      attribute? :description, Types::String.optional
+
+      # @!attribute [r] series_and_classes_contracts_information
+      #   @return [Array<Hash>, nil] series and classes/contracts info (mutual funds, ETFs)
+      attribute? :series_and_classes_contracts_information, Types::Array.of(Types::Hash).optional
+
+      # @!attribute [r] effectiveness_date
+      #   @return [String, nil] effectiveness date for registration statements
+      attribute? :effectiveness_date, Types::String.optional
+
+      # Override constructor to ensure immutability
+      def initialize(attributes)
+        super
+        freeze
+      end
+
+      # Returns the preferred filing URL (HTML if available, otherwise TXT).
+      #
+      # @return [String, nil] the filing URL or nil if neither available
+      # @example
+      #   filing.url #=> "https://sec.gov/Archives/..."
+      def url
+        return html_url unless html_url.nil? || html_url.empty?
+        return txt_url unless txt_url.nil? || txt_url.empty?
+        nil
+      end
+
+      # Alias for {#accession_number}.
+      #
+      # @return [String] SEC accession number
+      # @example
+      #   filing.accession_no #=> "0000320193-24-000001"
+      def accession_no
+        accession_number
+      end
+
+      # Alias for {#url}. Returns the preferred filing URL.
+      #
+      # @return [String, nil] the filing URL or nil if neither available
+      # @example
+      #   filing.filing_url #=> "https://sec.gov/Archives/..."
+      def filing_url
+        url
+      end
+
+      # Creates a Filing from API response data.
+      #
+      # Normalizes camelCase keys from the API to snake_case and recursively
+      # builds nested Entity, DocumentFormatFile, and DataFile objects.
+      #
+      # @param data [Hash] API response hash with filing data
+      # @return [Filing] Immutable filing object
+      #
+      # @example
+      #   data = { id: "abc123", ticker: "AAPL", formType: "10-K", ... }
+      #   filing = Filing.from_api(data)
+      #   filing.form_type  # => "10-K"
+      #
+      def self.from_api(data)
+        data[:company_name] = data.delete(:companyName) if data.key?(:companyName)
+        data[:company_name_long] = data.delete(:companyNameLong) if data.key?(:companyNameLong)
+        data[:form_type] = data.delete(:formType) if data.key?(:formType)
+        data[:period_of_report] = data.delete(:periodOfReport) if data.key?(:periodOfReport)
+        data[:filed_at] = data.delete(:filedAt) if data.key?(:filedAt)
+        data[:txt_url] = data.delete(:linkToTxt) if data.key?(:linkToTxt)
+        data[:html_url] = data.delete(:linkToHtml) if data.key?(:linkToHtml)
+        data[:xbrl_url] = data.delete(:linkToXbrl) if data.key?(:linkToXbrl)
+        data[:filing_details_url] = data.delete(:linkToFilingDetails) if data.key?(:linkToFilingDetails)
+        data[:documents] = data.delete(:documentFormatFiles) if data.key?(:documentFormatFiles)
+        data[:data_files] = data.delete(:dataFiles) if data.key?(:dataFiles)
+        data[:accession_number] = data.delete(:accessionNo) if data.key?(:accessionNo)
+        data[:series_and_classes_contracts_information] = data.delete(:seriesAndClassesContractsInformation) if data.key?(:seriesAndClassesContractsInformation)
+        data[:effectiveness_date] = data.delete(:effectivenessDate) if data.key?(:effectivenessDate)
+
+        entities = data[:entities].map do |entity|
+          Entity.from_api(entity)
+        end
+
+        documents = data[:documents].map do |document|
+          DocumentFormatFile.from_api(document)
+        end
+
+        data_files = data[:data_files].map do |data_file|
+          DataFile.from_api(data_file)
+        end
+        data[:entities] = entities
+        data[:documents] = documents
+        data[:data_files] = data_files
+        new(data)
+      end
+    end
+  end
+end

data/lib/sec_api/objects/fulltext_result.rb

@@ -0,0 +1,66 @@
+require "dry/struct"
+
+module SecApi
+  module Objects
+    # Represents a full-text search result from SEC EDGAR filings.
+    #
+    # FulltextResult objects are returned from full-text search queries and
+    # contain metadata about filings that match search terms. All instances
+    # are immutable (frozen).
+    #
+    # @example Full-text search results
+    #   results = client.query.fulltext("merger acquisition")
+    #   results.each do |result|
+    #     puts "#{result.ticker}: #{result.description}"
+    #     puts "Filed on: #{result.filed_on}"
+    #     puts "URL: #{result.url}"
+    #   end
+    #
+    # @see SecApi::Query#fulltext Full-text search method
+    # @see SecApi::Collections::FulltextResults Collection wrapper
+    #
+    class FulltextResult < Dry::Struct
+      transform_keys { |key| key.to_s.underscore }
+      transform_keys(&:to_sym)
+
+      attribute :cik, Types::String
+      attribute :ticker, Types::String
+      attribute :company_name_long, Types::String
+      attribute :form_type, Types::String
+      attribute :url, Types::String
+      attribute :type, Types::String
+      attribute :description, Types::String
+      attribute :filed_on, Types::String
+
+      # Creates a FulltextResult from API response data.
+      #
+      # Normalizes camelCase keys from the API to snake_case format.
+      #
+      # @param data [Hash] API response hash with result data
+      # @return [FulltextResult] Immutable result object
+      #
+      # @example Create from API response
+      #   data = {
+      #     cik: "0000320193",
+      #     ticker: "AAPL",
+      #     companyNameLong: "Apple Inc.",
+      #     formType: "10-K",
+      #     filingUrl: "https://sec.gov/...",
+      #     type: "10-K",
+      #     description: "Annual report",
+      #     filedAt: "2024-01-15"
+      #   }
+      #   result = FulltextResult.from_api(data)
+      #   result.company_name_long  # => "Apple Inc."
+      #
+      def self.from_api(data)
+        data[:company_name_long] = data.delete(:companyNameLong) if data.key?(:companyNameLong)
+        data[:form_type] = data.delete(:formType) if data.key?(:formType)
+        data[:url] = data.delete(:filingUrl) if data.key?(:filingUrl)
+        data[:filed_on] = data.delete(:filedAt) if data.key?(:filedAt)
+
+        new(data)
+      end
+    end
+  end
+end