ruby-edgar 0.1.0

data/lib/edgar/entity_data.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Edgar
+  # Fetches and parses SEC submissions JSON for a CIK entity.
+  class EntityData
+    attr_reader :cik, :raw
+
+    def initialize(cik:)
+      @cik = cik.to_i
+      @raw = fetch_data
+    end
+
+    def name
+      @raw["name"]
+    end
+
+    def tickers
+      @raw["tickers"] || []
+    end
+
+    def exchanges
+      @raw["exchanges"] || []
+    end
+
+    def sic
+      @raw["sic"]
+    end
+
+    def sic_description
+      @raw["sicDescription"]
+    end
+
+    def ein
+      @raw["ein"]
+    end
+
+    def entity_type
+      @raw["entityType"]
+    end
+
+    def fiscal_year_end
+      @raw["fiscalYearEnd"]
+    end
+
+    def phone
+      @raw["phone"]
+    end
+
+    def website
+      @raw["website"]
+    end
+
+    def description
+      @raw["description"]
+    end
+
+    def category
+      @raw["category"]
+    end
+
+    def state_of_incorporation
+      @raw["stateOfIncorporation"]
+    end
+
+    def company?
+      %w[operating company].include?(entity_type)
+    end
+
+    def individual?
+      entity_type == "individual"
+    end
+
+    def bdc?
+      entity_type == "bdc"
+    end
+
+    def not_found?
+      @raw.key?("error") || @raw.empty?
+    end
+
+    def mailing_address
+      addr = @raw.dig("addresses", "mailing")
+      Address.new(addr) if addr
+    end
+
+    def business_address
+      addr = @raw.dig("addresses", "business")
+      Address.new(addr) if addr
+    end
+
+    def recent_filings
+      @raw.dig("filings", "recent") || {}
+    end
+
+    def filing_count
+      (all_filings_hash["form"] || []).length
+    end
+
+    def all_filings
+      @all_filings ||= merge_all_filings
+    end
+
+    def filings_files
+      @raw.dig("filings", "files") || []
+    end
+
+    def to_h
+      @raw
+    end
+
+    private
+
+    def all_filings_hash
+      all_filings
+    end
+
+    def merge_all_filings
+      result = deep_copy_filing_hash(recent_filings)
+      filings_files.each do |file_entry|
+        page = fetch_filings_page(file_entry["name"])
+        next unless page
+
+        merge_filing_hash(result, page)
+      end
+      result
+    end
+
+    def fetch_filings_page(filename)
+      url = Config.submissions_file_url(@cik, filename)
+      data = Edgar.http_client.download_json(url)
+      # Paginated submission pages have the filing arrays at the top level
+      # (not wrapped under "filings.recent" like the main page).
+      page = data.dig("filings", "recent")
+      page || data
+    rescue StandardError => e
+      warn "Failed to fetch submissions page #{filename}: #{e.message}"
+      nil
+    end
+
+    def deep_copy_filing_hash(hash)
+      return {} if hash.nil? || hash.empty?
+
+      hash.each_with_object({}) do |(k, v), result|
+        result[k] = v.is_a?(Array) ? v.dup : v
+      end
+    end
+
+    def merge_filing_hash(target, source)
+      return target unless source.is_a?(Hash)
+
+      source.each do |key, values|
+        next unless values.is_a?(Array)
+
+        target[key] = if target[key].is_a?(Array)
+                        target[key] + values
+                      else
+                        values.dup
+                      end
+      end
+      target
+    end
+
+    def fetch_data
+      url = Config.submissions_url(@cik)
+      Edgar.http_client.download_json(url)
+    rescue StandardError => e
+      { "error" => e.message }
+    end
+  end
+
+  # Mailing or business address parsed from SEC entity data.
+  class Address
+    attr_reader :street1, :street2, :city, :state_or_country, :zipcode, :state_or_country_desc
+
+    def initialize(data)
+      @street1 = data["street1"]
+      @street2 = data["street2"]
+      @city = data["city"]
+      @state_or_country = data["stateOrCountry"]
+      @zipcode = data["zipCode"]
+      @state_or_country_desc = data["stateOrCountryDescription"]
+    end
+
+    def to_s
+      parts = [@street1, @street2, @city, @state_or_country, @zipcode].compact
+      parts.join(", ")
+    end
+  end
+end

data/lib/edgar/entity_facts.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module Edgar
+  # XBRL financial facts (US-GAAP, IFRS, DEI) for a CIK entity.
+  class EntityFacts
+    attr_reader :cik, :raw
+
+    def initialize(cik:)
+      @cik = cik.to_i
+      @raw = fetch_facts
+    end
+
+    def available?
+      @raw.key?("facts")
+    end
+
+    def us_gaap
+      @raw.dig("facts", "us-gaap") || {}
+    end
+
+    def ifrs_full
+      @raw.dig("facts", "ifrs-full") || {}
+    end
+
+    def dei
+      @raw.dig("facts", "dei") || {}
+    end
+
+    def concepts
+      us_gaap.keys + ifrs_full.keys
+    end
+
+    def concept(name)
+      us_gaap[name] || ifrs_full[name] || dei[name]
+    end
+
+    def concept_values(name, limit: nil, annual: nil)
+      c = concept(name)
+      return [] unless c
+
+      units = c["units"]
+      return [] unless units
+
+      values = units.values.flatten
+
+      if annual
+        has_fp = values.first&.key?("fp")
+        if has_fp
+          fy_values = values.select { |v| v["fp"] == "FY" }
+          values = fy_values unless fy_values.empty?
+        end
+      end
+
+      # Sort by filed date desc, then end date desc (matching Python edgartools'
+      # max by (filing_date, period_end) semantics)
+      values = values.sort_by { |v| [v["filed"] || v["end"] || "", v["end"] || ""] }.reverse
+
+      values = values.first(limit) if limit
+      values
+    end
+
+    def income_statement(periods: 4)
+      concepts = %w[Revenues Revenue CostOfGoodsAndServicesSold
+                    GrossProfit OperatingExpenses
+                    OperatingIncomeLoss
+                    IncomeLossFromContinuingOperationsBeforeIncomeTaxExpenseBenefit
+                    IncomeTaxExpenseBenefit
+                    NetIncomeLoss]
+      extract_statement(concepts, periods)
+    end
+
+    def balance_sheet(periods: 4)
+      concepts = %w[Assets CurrentAssets CashAndCashEquivalentsAtCarryingValue
+                    AccountsReceivableNetCurrent
+                    PropertyPlantAndEquipmentNet
+                    AssetsCurrent LiabilitiesCurrent
+                    LongTermDebtCurrent Liabilities
+                    StockholdersEquity]
+      extract_statement(concepts, periods)
+    end
+
+    def cashflow_statement(periods: 4)
+      concepts = %w[NetCashProvidedByUsedInOperatingActivities
+                    NetCashProvidedByUsedInInvestingActivities
+                    NetCashProvidedByUsedInFinancingActivities
+                    CashAndCashEquivalentsPeriodIncreaseDecrease]
+      extract_statement(concepts, periods)
+    end
+
+    # Standardized financial accessors
+    # When +limit:+ is given, returns an array of raw fact hashes (legacy).
+    # Otherwise returns a single numeric value (matching Python edgartools).
+
+    def get_revenue(limit: nil, annual: true, period: nil)
+      # Matches Python edgartools EntityFacts concept variants
+      revenue_concepts = %w[RevenueFromContractWithCustomerExcludingAssessedTax
+                            SalesRevenueNet
+                            Revenues Revenue
+                            TotalRevenues NetSales]
+      if limit
+        revenue_concepts.each do |name|
+          vals = concept_values(name, limit: limit, annual: annual)
+          return vals unless vals.empty?
+        end
+      else
+        revenue_concepts.each do |name|
+          val = _select_value(name, annual: annual, period: period)
+          return val if val
+        end
+      end
+      nil
+    end
+
+    def get_net_income(limit: nil, annual: true, period: nil)
+      # Matches Python edgartools EntityFacts concept variants
+      net_income_concepts = %w[NetIncomeLoss ProfitLoss NetIncome
+                               NetEarnings NetIncomeLossAttributableToParent]
+      if limit
+        net_income_concepts.each do |name|
+          v = concept_values(name, limit: limit, annual: annual)
+          return v unless v.empty?
+        end
+      else
+        net_income_concepts.each do |name|
+          val = _select_value(name, annual: annual, period: period)
+          return val if val
+        end
+      end
+      nil
+    end
+
+    def get_operating_income(limit: nil, annual: true, period: nil)
+      # Matches Python edgartools EntityFacts concept variants
+      op_income_concepts = %w[OperatingIncomeLoss OperatingIncome
+                              IncomeLossFromOperations OperatingProfit]
+      if limit
+        op_income_concepts.each do |name|
+          v = concept_values(name, limit: limit, annual: annual)
+          return v unless v.empty?
+        end
+      else
+        op_income_concepts.each do |name|
+          val = _select_value(name, annual: annual, period: period)
+          return val if val
+        end
+      end
+      nil
+    end
+
+    def get_total_assets(limit: nil, annual: true, period: nil)
+      # Matches Python edgartools EntityFacts concept variants
+      asset_concepts = %w[Assets TotalAssets AssetsCurrent]
+      if limit
+        asset_concepts.each do |name|
+          v = concept_values(name, limit: limit, annual: annual)
+          return v unless v.empty?
+        end
+      else
+        asset_concepts.each do |name|
+          val = _select_value(name, annual: annual, period: period)
+          return val if val
+        end
+      end
+      nil
+    end
+
+    def get_total_liabilities(limit: nil, annual: true, period: nil)
+      # Matches Python edgartools EntityFacts concept variants
+      liability_concepts = %w[Liabilities TotalLiabilities LiabilitiesAndStockholdersEquity]
+      if limit
+        liability_concepts.each do |name|
+          v = concept_values(name, limit: limit, annual: annual)
+          return v unless v.empty?
+        end
+      else
+        liability_concepts.each do |name|
+          val = _select_value(name, annual: annual, period: period)
+          return val if val
+        end
+      end
+      nil
+    end
+
+    def get_shareholders_equity(limit: nil, annual: true, period: nil)
+      # Matches Python edgartools EntityFacts concept variants
+      equity_concepts = %w[StockholdersEquity ShareholdersEquity
+                           TotalEquity PartnersCapital MembersEquity]
+      if limit
+        equity_concepts.each do |name|
+          v = concept_values(name, limit: limit, annual: annual)
+          return v unless v.empty?
+        end
+      else
+        equity_concepts.each do |name|
+          val = _select_value(name, annual: annual, period: period)
+          return val if val
+        end
+      end
+      nil
+    end
+    alias get_stockholders_equity get_shareholders_equity
+
+    def get_gross_profit(limit: nil, annual: true, period: nil)
+      # Matches Python edgartools EntityFacts concept variants
+      gross_profit_concepts = %w[GrossProfit GrossMargin]
+      if limit
+        gross_profit_concepts.each do |name|
+          v = concept_values(name, limit: limit, annual: annual)
+          return v unless v.empty?
+        end
+      else
+        gross_profit_concepts.each do |name|
+          val = _select_value(name, annual: annual, period: period)
+          return val if val
+        end
+      end
+      nil
+    end
+
+    # Shares outstanding — tries DEI entity-level concept first,
+    # then falls back to US-GAAP balance sheet concept.
+    # Matches Python edgartools EntityFacts#shares_outstanding.
+    def shares_outstanding
+      # Try DEI entity-level concept first (most authoritative)
+      val = _select_value("EntityCommonStockSharesOutstanding", annual: false)
+      return val if val
+
+      # Fallback to US-GAAP balance sheet concept (covers multi-class cos like GOOG)
+      val = _select_value("CommonStockSharesOutstanding", annual: false)
+      return val if val
+
+      # Another fallback
+      _select_value("WeightedAverageNumberOfSharesOutstandingBasic", annual: false)
+    end
+
+    alias get_shares_outstanding shares_outstanding
+
+    # Trailing Twelve Months (TTM) calculations.
+    # Delegates to TTMCalculator which matches Python edgartools' TTMCalculator:
+    #   1. Classify facts by period duration (quarter: 70-120d, YTD_6M: 140-229d,
+    #      YTD_9M: 230-329d, annual: 330-420d)
+    #   2. Derive Q2=YTD_6M-Q1, Q3=YTD_9M-YTD_6M, Q4=FY-YTD_9M
+    #   3. Take 4 most recent quarters and sum them.
+
+    def ttm(concept_name)
+      values = concept_values(concept_name, limit: nil, annual: false)
+      return nil if values.empty?
+
+      TTMCalculator.new(values).calculate
+    end
+
+    def ttm_revenue
+      result = ttm("RevenueFromContractWithCustomerExcludingAssessedTax")
+      return result if result
+
+      ttm("Revenues")
+    end
+
+    def ttm_net_income
+      ttm("NetIncomeLoss")
+    end
+
+    def ttm_operating_income
+      ttm("OperatingIncomeLoss")
+    end
+
+    # Select the best single value for a concept, matching Python edgartools'
+    # _get_standardized_concept_value semantics.
+    # When +annual+ is true (default), prefers FY (fiscal-year) facts.
+    # When +period+ is given (e.g. "2025-FY"), filters to that specific period.
+    # When multiple facts exist, selects by (filed desc, end desc) matching
+    # Python's max by (filing_date, period_end).
+    # Matches Python edgartools' fallback: if annual: true yields no results
+    # (e.g. balance sheet instant facts), falls back to the most recent fact.
+    def _select_value(concept_name, annual: true, period: nil)
+      c = concept(concept_name)
+      return nil unless c
+
+      values = c["units"]&.values&.flatten || []
+      return nil if values.empty?
+
+      if annual && period.nil?
+        has_fp = values.first&.key?("fp")
+        if has_fp
+          fy_values = values.select { |v| v["fp"] == "FY" }
+          values = fy_values unless fy_values.empty?
+        end
+      end
+
+      if period
+        fy_str, fp_str = period.split("-")
+        values = values.select { |v| v["fy"].to_s == fy_str && v["fp"] == fp_str }
+      end
+
+      return nil if values.empty?
+
+      # Select by (filed desc, end desc) matching Python's
+      # max by (filing_date, period_end)
+      best = values.max_by { |v| [v["filed"] || v["end"] || "", v["end"] || ""] }
+
+      best["val"]
+    end
+
+    def extract_statement(concept_names, periods)
+      result = {}
+      concept_names.each do |name|
+        values = concept_values(name, limit: periods)
+        result[name] = values if values.any?
+      end
+      result
+    end
+
+    private
+
+    def fetch_facts
+      url = Config.company_facts_url(@cik)
+      Edgar.http_client.download_json(url)
+    rescue StandardError => e
+      { "error" => e.message }
+    end
+  end
+end

data/lib/edgar/filing.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Edgar
+  # A single SEC filing: form type, date, text, attachments, and XBRL data.
+  class Filing
+    attr_reader :cik, :company, :form, :filing_date, :accession_number
+
+    def initialize(cik:, company:, form:, filing_date:, accession_number:)
+      @cik = cik.to_i
+      @company = company
+      @form = form
+      @filing_date = filing_date.is_a?(Date) ? filing_date : Date.parse(filing_date.to_s)
+      @accession_number = accession_number
+      @sgml = nil
+      @homepage_soup = nil
+    end
+
+    def all_ciks
+      [@cik]
+    end
+
+    def multi_entity?
+      all_ciks.length > 1
+    end
+
+    def filing_url
+      primary = homepage.primary_html_document
+      return primary.url if primary
+
+      text_url
+    end
+
+    def homepage_url
+      Config.filing_homepage_url(@cik, @accession_number)
+    end
+
+    def text_url
+      Config.filing_text_url(@cik, @accession_number)
+    end
+
+    def base_dir
+      no_dashes = @accession_number.delete("-")
+      "#{Config::SEC_ARCHIVE_URL}/data/#{@cik}/#{no_dashes}"
+    end
+
+    def header
+      @header ||= FilingHeader.new(sgml)
+    end
+
+    def period_of_report
+      header.period_of_report
+    end
+
+    def sgml
+      @sgml ||= fetch_sgml
+    end
+
+    def homepage
+      @homepage ||= fetch_homepage
+    end
+
+    def html
+      doc = homepage.primary_html_document
+      doc ? download_attachment(doc) : ""
+    end
+
+    def xml
+      doc = homepage.primary_xml_document
+      doc ? download_attachment(doc) : ""
+    end
+
+    def text
+      sgml_text = sgml_raw_text
+      return sgml_text if sgml_text
+
+      download_text_file
+    end
+
+    def attachments
+      homepage.attachments
+    end
+
+    def exhibits
+      attachments.exhibits
+    end
+
+    def reports
+      attachments.reports
+    end
+
+    def statements
+      attachments.statements
+    end
+
+    def xbrl
+      doc = homepage.xbrl_document
+      return nil unless doc
+
+      content = download_attachment(doc)
+      XBRL::XBRL.new(content)
+    end
+
+    def section_markers
+      @section_markers ||= Edgar::FilingSections.extract_sections(sgml)
+    end
+
+    def sections
+      Edgar::FilingSections.find_sections(sgml, form_type: @form)
+    end
+
+    def obj
+      DataObjects.for(self)
+    end
+
+    def accession_no
+      @accession_number
+    end
+
+    def markdown
+      text = sgml
+      return "" if text.empty?
+
+      text
+        .gsub(/<[^>]+>/, "")
+        .gsub(/&[a-zA-Z]+;/, " ")
+        .gsub(/\n{3,}/, "\n\n")
+        .strip
+    end
+
+    def to_s
+      "#<Filing #{@form} #{@company} #{@filing_date} #{@accession_number}>"
+    end
+
+    private
+
+    def fetch_sgml
+      text = download_text_file
+      return "" unless text
+
+      text
+    end
+
+    def sgml_raw_text
+      Edgar.http_client.download_text(text_url)
+    rescue StandardError
+      nil
+    end
+
+    def download_text_file
+      Edgar.http_client.download_text(text_url)
+    rescue StandardError => e
+      warn "Failed to download filing text: #{e.message}"
+      ""
+    end
+
+    def fetch_homepage
+      FilingHomepage.new(homepage_url)
+    rescue StandardError => e
+      warn "Failed to fetch filing homepage: #{e.message}"
+      FilingHomepage.empty
+    end
+
+    def download_attachment(attachment)
+      Edgar.http_client.download_text(attachment.url)
+    rescue StandardError => e
+      warn "Failed to download attachment: #{e.message}"
+      ""
+    end
+  end
+end