ruby-edgar 0.1.0

data/lib/edgar/filings.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Edgar
+  # Enumerable collection of Filing objects with filter, sort, and summary.
+  class Filings
+    include Enumerable
+
+    attr_reader :entries, :original_state, :per_page
+
+    def initialize(entries = [], original_state: {}, page_index: 0, per_page: 100,
+                   all_entries: nil)
+      @page_index = page_index
+      @per_page = per_page
+      @all_entries = all_entries
+      @entries = entries.map do |e|
+        if e.is_a?(Filing)
+          e
+        elsif e.is_a?(Hash) || e.is_a?(FilingIndex::IndexEntry)
+          Filing.new(
+            cik: e[:cik] || e["cik"],
+            company: e[:company] || e["company"],
+            form: e[:form] || e["form"],
+            filing_date: e[:filing_date] || e["filing_date"],
+            accession_number: e[:accession_number] || e["accession_number"]
+          )
+        end
+      end.compact
+      @all_entries ||= @entries
+      @original_state = original_state
+    end
+
+    def each(&block)
+      @entries.each(&block)
+    end
+
+    def [](index)
+      if index.is_a?(Integer)
+        @entries[index]
+      else
+        @entries.find { |f| f.accession_number == index }
+      end
+    end
+
+    def length
+      @entries.length
+    end
+
+    def empty?
+      @entries.empty?
+    end
+
+    def latest(count = 1)
+      sorted = @entries.sort_by(&:filing_date).reverse
+      selected = sorted.first(count)
+      return selected.first if count == 1 && selected.length == 1
+
+      Filings.new(selected, original_state: @original_state)
+    end
+
+    def head(count = 10)
+      Filings.new(@entries.first(count), original_state: @original_state)
+    end
+
+    def tail(count = 10)
+      Filings.new(@entries.last(count), original_state: @original_state)
+    end
+
+    def sample(count = 1)
+      Filings.new(@entries.sample(count), original_state: @original_state)
+    end
+
+    def filter(form: nil, filing_date: nil, date: nil, cik: nil, ticker: nil,
+               exchange: nil, company_name: nil,
+               amendments: nil, date_start: nil, date_end: nil)
+      filtered = @entries.select do |f|
+        matches_filters?(f,
+                         form: form, cik: cik, ticker: ticker, company_name: company_name,
+                         exchange: exchange, filing_date: filing_date || date,
+                         date_start: date_start, date_end: date_end,
+                         amendments: amendments)
+      end
+
+      Filings.new(filtered, original_state: @original_state)
+    end
+
+    def find_by_company(company_name)
+      filter(company_name: company_name)
+    end
+
+    def current_page
+      @page_index + 1
+    end
+
+    def page(num = nil, per_page: nil)
+      p = num || (@page_index + 1)
+      pp = per_page || @per_page
+      start_idx = (p - 1) * pp
+      page_entries = @all_entries[start_idx, pp] || []
+      Filings.new(page_entries, original_state: @original_state,
+                                page_index: p - 1, per_page: pp,
+                                all_entries: @all_entries)
+    end
+
+    def next_page
+      next_start = (@page_index + 1) * @per_page
+      return self if next_start >= @all_entries.length
+
+      page(@page_index + 2)
+    end
+
+    def previous_page
+      return self if @page_index.zero?
+
+      page(@page_index)
+    end
+
+    def total_pages(per_page: nil)
+      pp = per_page || @per_page
+      pp.positive? ? (@all_entries.length.to_f / pp).ceil : 0
+    end
+
+    def group_by_form
+      @entries.group_by(&:form)
+    end
+
+    def to_a
+      @entries.dup
+    end
+
+    def to_hashes
+      @entries.map do |f|
+        {
+          cik: f.cik,
+          company: f.company,
+          form: f.form,
+          filing_date: f.filing_date,
+          accession_number: f.accession_number
+        }
+      end
+    end
+
+    def to_dict
+      to_hashes
+    end
+
+    def date_range
+      return nil if @entries.empty?
+
+      dates = @entries.map(&:filing_date)
+      { min: dates.min, max: dates.max }
+    end
+
+    def self.from_quarter(year, quarter, type: "company")
+      entries = FilingIndex.for(year, quarter, type: type)
+      new(entries)
+    end
+
+    def self.from_years(years, quarters: [1, 2, 3, 4])
+      years = Array(years)
+      all = years.flat_map do |y|
+        quarters.flat_map { |q| FilingIndex.for(y, q) }
+      end
+      new(all)
+    end
+
+    def summary
+      form_counts = group_by_form.transform_values(&:length)
+      date_range_str = if @entries.any?
+                         dates = @entries.map(&:filing_date)
+                         "#{dates.min} - #{dates.max}"
+                       else
+                         "N/A"
+                       end
+
+      {
+        count: @entries.length,
+        date_range: date_range_str,
+        form_counts: form_counts
+      }
+    end
+
+    private
+
+    def matches_filters?(filing, form: nil, cik: nil, ticker: nil, company_name: nil,
+                         exchange: nil, filing_date: nil,
+                         date_start: nil, date_end: nil, amendments: nil)
+      if form
+        form_list = Array(form)
+        # Match Python edgartools default behavior: include amendment (/A) variants
+        # unless amendments are explicitly excluded.
+        form_list = form_list.flat_map { |f| [f, "#{f}/A"] }.uniq unless amendments == false
+        return false unless form_list.include?(filing.form)
+      end
+      return false if cik && filing.cik != cik.to_i
+      return false if ticker && !filing.company&.downcase&.include?(ticker.downcase)
+      return false if company_name && !filing.company&.downcase&.include?(company_name.downcase)
+      return false if exchange && !exchange_match?(filing, exchange)
+      return false if filing_date && parse_date(filing_date) != filing.filing_date
+      return false if date_start && filing.filing_date < parse_date(date_start)
+      return false if date_end && filing.filing_date > parse_date(date_end)
+      return false if amendments == false && filing.form.to_s.end_with?("/A")
+
+      true
+    end
+
+    def exchange_match?(filing, exchange)
+      ex = Array(exchange).map(&:downcase)
+      entity_exchanges = EntityData.new(cik: filing.cik).exchanges.map(&:downcase)
+      (ex & entity_exchanges).any?
+    end
+
+    def parse_date(value)
+      value.is_a?(Date) ? value : Date.parse(value.to_s)
+    end
+  end
+end

data/lib/edgar/financials.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+module Edgar
+  # Wraps EntityFacts/FilingFacts with statement rendering and convenience
+  # accessors matching Python edgartools' Financials API.
+  class Financials
+    # Map ISO 4217 currency codes to symbols (matches Python edgartools)
+    CURRENCY_SYMBOLS = {
+      "USD" => "$",
+      "EUR" => "\u20AC",
+      "GBP" => "\u00A3",
+      "JPY" => "\u00A5",
+      "CAD" => "C$",
+      "CHF" => "Fr",
+      "AUD" => "A$",
+      "CNY" => "\u00A5",
+      "HKD" => "HK$",
+      "NZD" => "NZ$",
+      "SEK" => "kr",
+      "NOK" => "kr",
+      "DKK" => "kr",
+      "INR" => "\u20B9",
+      "BRL" => "R$",
+      "ZAR" => "R",
+      "MXN" => "Mex$",
+      "SGD" => "S$",
+      "TWD" => "NT$",
+      "KRW" => "\u20A9",
+      "RUB" => "\u20BD",
+      "PLN" => "z\u0142",
+      "TRY" => "\u20BA",
+      "ILS" => "\u20AA"
+    }.freeze
+
+    attr_reader :facts
+
+    def initialize(cik: nil, facts: nil)
+      @facts = facts || EntityFacts.new(cik: cik)
+    end
+
+    def available?
+      @facts.available?
+    end
+
+    def income_statement(periods: 4)
+      concepts = %w[Revenues Revenue
+                    RevenueFromContractWithCustomerExcludingAssessedTax
+                    RevenueFromContractWithCustomer
+                    CostOfGoodsAndServicesSold
+                    GrossProfit OperatingExpenses
+                    OperatingIncomeLoss
+                    NonoperatingIncomeExpensePlusInterestAndDividendIncome
+                    IncomeLossFromContinuingOperationsBeforeIncomeTaxExpenseBenefit
+                    IncomeTaxExpenseBenefit
+                    NetIncomeLoss
+                    EarningsPerShareBasic
+                    EarningsPerShareDiluted
+                    WeightedAverageNumberOfSharesOutstandingBasic
+                    WeightedAverageNumberOfDilutedSharesOutstanding]
+      extract_concepts(concepts, periods)
+    end
+
+    def balance_sheet(periods: 4)
+      concepts = %w[Assets CurrentAssets
+                    CashAndCashEquivalentsAtCarryingValue
+                    AccountsReceivableNetCurrent
+                    InventoryNet
+                    PropertyPlantAndEquipmentNet
+                    AssetsCurrent LiabilitiesCurrent
+                    LongTermDebtCurrent LongTermDebtNoncurrent
+                    Liabilities StockholdersEquity
+                    StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest
+                    RetainedEarningsAccumulatedDeficit
+                    CommonStocksIncludingAdditionalPaidInCapital
+                    TreasuryStockValue]
+      extract_concepts(concepts, periods)
+    end
+
+    def cashflow_statement(periods: 4)
+      concepts = %w[NetCashProvidedByUsedInOperatingActivities
+                    NetCashProvidedByUsedInInvestingActivities
+                    NetCashProvidedByUsedInFinancingActivities
+                    CashAndCashEquivalentsPeriodIncreaseDecrease
+                    CashAndCashEquivalentsAtCarryingValue]
+      extract_concepts(concepts, periods)
+    end
+
+    def statement_of_equity(periods: 4)
+      concepts = %w[StockholdersEquity
+                    StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest
+                    RetainedEarningsAccumulatedDeficit
+                    CommonStocksIncludingAdditionalPaidInCapital
+                    TreasuryStockValue
+                    AccumulatedOtherComprehensiveIncomeLossNetOfTax
+                    ComprehensiveIncomeNetOfTax
+                    Dividends]
+      extract_concepts(concepts, periods)
+    end
+
+    def comprehensive_income(periods: 4)
+      concepts = %w[ComprehensiveIncomeNetOfTax
+                    OtherComprehensiveIncomeLossNetOfTax
+                    ComprehensiveIncomeNetOfTaxAttributableToParent
+                    ComprehensiveIncomeNetOfTaxAttributableToNoncontrollingInterest]
+      extract_concepts(concepts, periods)
+    end
+
+    # Delegates to EntityFacts/FilingFacts for the 7 core EntityFacts accessors
+    def get_revenue(limit: nil, annual: true, period: nil)
+      @facts.get_revenue(limit: limit, annual: annual, period: period)
+    end
+
+    def get_net_income(limit: nil, annual: true, period: nil)
+      @facts.get_net_income(limit: limit, annual: annual, period: period)
+    end
+
+    def get_operating_income(limit: nil, annual: true, period: nil)
+      @facts.get_operating_income(limit: limit, annual: annual, period: period)
+    end
+
+    def get_total_assets(limit: nil, annual: true, period: nil)
+      @facts.get_total_assets(limit: limit, annual: annual, period: period)
+    end
+
+    def get_total_liabilities(limit: nil, annual: true, period: nil)
+      @facts.get_total_liabilities(limit: limit, annual: annual, period: period)
+    end
+
+    def get_shareholders_equity(limit: nil, annual: true, period: nil)
+      @facts.get_shareholders_equity(limit: limit, annual: annual, period: period)
+    end
+    alias get_stockholders_equity get_shareholders_equity
+
+    def get_gross_profit(limit: nil, annual: true, period: nil)
+      @facts.get_gross_profit(limit: limit, annual: annual, period: period)
+    end
+
+    # Financials-specific convenience accessors matching Python edgartools
+    # Financials API. These use @facts._select_value and @facts.concept_values
+    # since Python Financials implements them via XBRL statement rendering
+    # (not available in ruby-edgar yet).
+
+    def get_operating_cash_flow(limit: nil, annual: true, period: nil)
+      if limit
+        v = @facts.concept_values("NetCashProvidedByUsedInOperatingActivities", limit: limit, annual: annual)
+        v.empty? ? nil : v
+      else
+        @facts._select_value("NetCashProvidedByUsedInOperatingActivities", annual: annual, period: period)
+      end
+    end
+
+    def get_free_cash_flow(limit: nil, annual: true)
+      op = @facts._select_value("NetCashProvidedByUsedInOperatingActivities", annual: annual)
+      capex = @facts._select_value("PaymentsToAcquirePropertyPlantAndEquipment", annual: annual)
+      return nil unless op && capex
+
+      if limit
+        end_date = @facts.concept_values(
+          "NetCashProvidedByUsedInOperatingActivities", limit: 1, annual: annual
+        )&.first&.dig("end")
+        [{ "end" => end_date, "val" => op - capex.abs }]
+      else
+        op - capex.abs
+      end
+    end
+
+    def get_earnings_per_share(limit: nil, annual: true, period: nil)
+      if limit
+        v = @facts.concept_values("EarningsPerShareDiluted", limit: limit, annual: annual)
+        v = @facts.concept_values("EarningsPerShareBasic", limit: limit, annual: annual) if v.empty?
+        v.empty? ? nil : v
+      else
+        val = @facts._select_value("EarningsPerShareDiluted", annual: annual, period: period)
+        val || @facts._select_value("EarningsPerShareBasic", annual: annual, period: period)
+      end
+    end
+
+    def get_current_assets(limit: nil, annual: true, period: nil)
+      if limit
+        v = @facts.concept_values("AssetsCurrent", limit: limit, annual: annual)
+        v.empty? ? nil : v
+      else
+        @facts._select_value("AssetsCurrent", annual: annual, period: period)
+      end
+    end
+
+    def get_current_liabilities(limit: nil, annual: true, period: nil)
+      if limit
+        v = @facts.concept_values("LiabilitiesCurrent", limit: limit, annual: annual)
+        v.empty? ? nil : v
+      else
+        @facts._select_value("LiabilitiesCurrent", annual: annual, period: period)
+      end
+    end
+
+    def get_capital_expenditures(limit: nil, annual: true, period: nil)
+      if limit
+        v = @facts.concept_values("PaymentsToAcquirePropertyPlantAndEquipment", limit: limit, annual: annual)
+        v.empty? ? nil : v
+      else
+        @facts._select_value("PaymentsToAcquirePropertyPlantAndEquipment", annual: annual, period: period)
+      end
+    end
+
+    def get_shares_outstanding_basic(limit: nil, annual: true, period: nil)
+      concepts = %w[WeightedAverageNumberOfSharesOutstandingBasic
+                    EntityCommonStockSharesOutstanding
+                    CommonStockSharesOutstanding]
+      if limit
+        concepts.each do |name|
+          v = @facts.concept_values(name, limit: limit, annual: annual)
+          return v unless v.empty?
+        end
+      else
+        concepts.each do |name|
+          val = @facts._select_value(name, annual: annual, period: period)
+          return val if val
+        end
+      end
+      nil
+    end
+
+    def get_shares_outstanding_diluted(limit: nil, annual: true, period: nil)
+      if limit
+        v = @facts.concept_values("WeightedAverageNumberOfDilutedSharesOutstanding", limit: limit, annual: annual)
+        v = @facts.concept_values("DilutedAverageShares", limit: limit, annual: annual) if v.empty?
+        v.empty? ? nil : v
+      else
+        val = @facts._select_value("WeightedAverageNumberOfDilutedSharesOutstanding", annual: annual, period: period)
+        val || @facts._select_value("DilutedAverageShares", annual: annual, period: period)
+      end
+    end
+
+    def currency_symbol
+      # Try to find the currency from us-gaap units.
+      # EntityFacts returns Hash-format concepts with a "units" sub-hash.
+      # FilingFacts returns Array-format concepts with a "unit" string key.
+      @facts.us_gaap.each_value do |concept|
+        if concept.is_a?(Array)
+          # FilingFacts format: each element is a fact hash with "unit" key
+          concept.each do |v|
+            result = currency_from_unit(v["unit"])
+            return result if result
+          end
+        else
+          # EntityFacts format: concept hash with "units" sub-hash
+          units = concept["units"]
+          next unless units
+
+          units.each_key do |unit|
+            result = currency_from_unit(unit)
+            return result if result
+          end
+        end
+      end
+
+      # Fallback: try facts_map when us_gaap is empty (e.g. custom facts objects)
+      if @facts.respond_to?(:facts_map)
+        @facts.facts_map.each_value do |values|
+          next unless values.any?
+
+          values.each do |v|
+            result = currency_from_unit(v["unit"])
+            return result if result
+          end
+        end
+      end
+
+      # Default fallback (Python edgartools defaults to "$")
+      "$"
+    end
+
+    def financial_metrics
+      revenue = get_revenue
+      net_income = get_net_income
+      operating_income = get_operating_income
+      total_assets = get_total_assets
+      total_liabilities = get_total_liabilities
+      equity = get_stockholders_equity
+      ocf = get_operating_cash_flow
+      fcf = get_free_cash_flow
+      gross_profit = get_gross_profit
+      eps = get_earnings_per_share
+      current_assets = get_current_assets
+      current_liabilities = get_current_liabilities
+      capex = get_capital_expenditures
+      shares_basic = get_shares_outstanding_basic
+      shares_diluted = get_shares_outstanding_diluted
+
+      metrics = {
+        revenue: revenue,
+        operating_income: operating_income,
+        net_income: net_income,
+        total_assets: total_assets,
+        total_liabilities: total_liabilities,
+        stockholders_equity: equity,
+        current_assets: current_assets,
+        current_liabilities: current_liabilities,
+        operating_cash_flow: ocf,
+        capital_expenditures: capex,
+        free_cash_flow: fcf,
+        shares_outstanding_basic: shares_basic,
+        shares_outstanding_diluted: shares_diluted,
+        gross_profit: gross_profit,
+        eps: eps
+      }
+
+      # Calculate ratios (matching Python edgartools)
+      if current_assets && current_liabilities&.positive?
+        metrics[:current_ratio] = current_assets / current_liabilities.to_f
+      end
+
+      metrics[:debt_to_assets] = total_liabilities / total_assets.to_f if total_liabilities && total_assets&.positive?
+
+      metrics
+    end
+
+    class << self
+      def extract(filing)
+        xbrl = filing.xbrl
+        facts = if xbrl
+                  FilingFacts.new(xbrl, form_type: filing.form)
+                else
+                  EntityFacts.new(cik: filing.cik)
+                end
+        new(facts: facts)
+      rescue StandardError => e
+        warn "Failed to extract financials from filing: #{e.message}"
+        nil
+      end
+    end
+
+    private
+
+    # Look up a currency unit string in CURRENCY_SYMBOLS, returning either
+    # the mapped symbol or the raw unit if it looks like a currency code.
+    def currency_from_unit(unit)
+      return nil unless unit.is_a?(String)
+
+      sym = CURRENCY_SYMBOLS[unit]
+      return sym if sym
+      return unit if unit.length <= 3 && unit == unit.upcase
+
+      nil
+    end
+
+    def extract_concepts(concept_names, periods)
+      result = {}
+      concept_names.each do |name|
+        values = @facts.concept_values(name, limit: periods)
+        result[name] = { label: concept_label(name), values: values } if values.any?
+      end
+      result
+    end
+
+    def concept_label(concept_name)
+      concept = @facts.concept(concept_name)
+      concept ? concept["label"] : concept_name
+    end
+  end
+end

data/lib/edgar/http_client.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "zlib"
+require "stringio"
+
+module Edgar
+  # Faraday-based HTTP client with rate limiting, retries, and gzip handling.
+  class HTTPClient
+    class RateLimitError < StandardError; end
+    class SslVerificationError < StandardError; end
+
+    attr_reader :last_request_time
+
+    def initialize(
+      rate_limit: Config::EDGAR_RATE_LIMIT_PER_SEC,
+      timeout: Config::DEFAULT_TIMEOUT,
+      connect_timeout: Config::DEFAULT_CONNECT_TIMEOUT,
+      retries: 5
+    )
+      @rate_limit = rate_limit
+      @min_interval = 1.0 / rate_limit
+      @last_request_time = 0.0
+      @mutex = Mutex.new
+      @retries = retries
+
+      @connection = build_connection(timeout, connect_timeout)
+    end
+
+    def get(url, **options)
+      request(:get, url, **options)
+    end
+
+    def post(url, body: nil, **options)
+      request(:post, url, body: body, **options)
+    end
+
+    def download_text(url)
+      response = get(url)
+      decompress_body(url, response.body, response.headers)
+    end
+
+    def download_json(url)
+      response = get(url)
+      body = decompress_body(url, response.body, response.headers)
+      JSON.parse(body)
+    end
+
+    GZIP_MAGIC = [0x1f, 0x8b].freeze
+
+    private
+
+    def build_connection(timeout, connect_timeout)
+      Faraday.new do |f|
+        f.options[:timeout] = timeout
+        f.options[:open_timeout] = connect_timeout
+
+        f.request :retry, {
+          max: @retries,
+          interval: 1.0,
+          interval_randomness: 0.5,
+          backoff_factor: 2.0,
+          retry_statuses: [429, 500, 502, 503, 504],
+          retry_if: lambda { |env, _ex|
+            env.response&.status == 429 || env.response&.status&.between?(500, 599)
+          }
+        }
+
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def request(method, url, body: nil, **options)
+      rate_limit!
+
+      headers = {
+        "User-Agent" => Config.user_agent,
+        "Accept-Encoding" => "gzip, deflate"
+      }
+      headers.merge!(options[:headers]) if options[:headers]
+
+      response = @connection.run_request(method, url, body, headers)
+
+      raise RateLimitError, "429 Too Many Requests" if response.status == 429
+      raise SslVerificationError, "SSL verification failed for #{url}" if response.status == 525
+
+      raise "HTTP #{response.status} for #{url}" unless response.success?
+
+      response
+    end
+
+    def decompress_body(url, body, headers)
+      content_encoding = headers["content-encoding"].to_s.downcase
+      is_gz_url = url.to_s.end_with?(".gz")
+      is_gzip = content_encoding.include?("gzip") || is_gz_url
+
+      if is_gzip || body.bytes.first(2) == GZIP_MAGIC
+        Zlib::GzipReader.new(StringIO.new(body)).read
+      else
+        body
+      end
+    rescue Zlib::Error
+      body
+    end
+
+    def rate_limit!
+      @mutex.synchronize do
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_request_time
+        sleep(@min_interval - elapsed) if elapsed < @min_interval
+        @last_request_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end