ruby-edgar 0.1.0

data/lib/edgar/ttm_calculator.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Edgar
+  # Calculates Trailing Twelve Months (TTM) values from quarterly financial facts.
+  #
+  # Matches Python edgartools' TTMCalculator algorithm:
+  #   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.
+  # Falls back to fp-based quarterly selection when values lack start dates.
+  class TTMCalculator
+    QUARTER_MIN_DAYS = 70
+    QUARTER_MAX_DAYS = 120
+    YTD_6M_MIN_DAYS = 140
+    YTD_6M_MAX_DAYS = 229
+    YTD_9M_MIN_DAYS = 230
+    YTD_9M_MAX_DAYS = 329
+    ANNUAL_MIN_DAYS = 330
+    ANNUAL_MAX_DAYS = 420
+
+    PERIODIC_FORMS = %w[10-K 10-K/A 10-Q 10-Q/A 20-F 20-F/A 40-F 40-F/A 6-K 6-K/A].freeze
+
+    def initialize(values)
+      @values = values
+    end
+
+    # Returns a hash with "end" and "val" keys, or nil if insufficient data.
+    def calculate
+      all_quarters = quarterize(@values)
+      return nil if all_quarters.length < 4
+
+      ttm_qs = all_quarters.last(4)
+      sum = ttm_qs.sum { |v| v["val"].to_f }
+      { "end" => ttm_qs.last["end"], "val" => sum }
+    end
+
+    private
+
+    def quarterize(values)
+      quarters, ytd_6m, ytd_9m, annual_facts = classify_by_duration(values)
+
+      return fp_based_quarters(values) if all_empty?(quarters, ytd_6m, ytd_9m, annual_facts)
+
+      quarters = dedup_by_end(quarters)
+      ytd_6m = dedup_by_end(ytd_6m)
+      ytd_9m = dedup_by_end(ytd_9m)
+      annual_facts = dedup_by_end(annual_facts)
+
+      derived = []
+      derived.concat(derive_q2(quarters, ytd_6m))
+      derived.concat(derive_q3(ytd_6m, ytd_9m))
+      derived.concat(derive_q4(quarters, ytd_9m, annual_facts))
+
+      all_quarters = quarters + derived
+      all_quarters = dedup_by_end(all_quarters)
+      all_quarters.sort_by { |v| v["end"] || v["start"] || "" }
+    end
+
+    def all_empty?(*arrays)
+      arrays.all?(&:empty?)
+    end
+
+    def classify_by_duration(values)
+      quarters = []
+      ytd_6m = []
+      ytd_9m = []
+      annual_facts = []
+
+      values.each do |v|
+        days = duration_days(v["start"], v["end"])
+        next unless days
+
+        if days.between?(QUARTER_MIN_DAYS, QUARTER_MAX_DAYS)
+          quarters << v
+        elsif days.between?(YTD_6M_MIN_DAYS, YTD_6M_MAX_DAYS)
+          ytd_6m << v
+        elsif days.between?(YTD_9M_MIN_DAYS, YTD_9M_MAX_DAYS)
+          ytd_9m << v
+        elsif days.between?(ANNUAL_MIN_DAYS, ANNUAL_MAX_DAYS)
+          annual_facts << v
+        end
+      end
+
+      [quarters, ytd_6m, ytd_9m, annual_facts]
+    end
+
+    def fp_based_quarters(values)
+      has_fp = values.first&.key?("fp")
+      return [] unless has_fp
+
+      quarterly = values.select { |v| %w[Q1 Q2 Q3 Q4].include?(v["fp"]) }
+      quarterly.sort_by { |v| v["end"] || v["start"] || "" }
+    end
+
+    def duration_days(start_str, end_str)
+      return nil unless start_str && end_str
+
+      (Date.parse(end_str) - Date.parse(start_str)).to_i
+    rescue ArgumentError
+      nil
+    end
+
+    def dedup_by_end(values)
+      return [] if values.empty?
+
+      by_end = {}
+      values.each do |v|
+        key = v["end"]
+        next unless key
+
+        existing = by_end[key]
+        by_end[key] = v if existing.nil? || (filing_priority(v) <=> filing_priority(existing)).positive?
+      end
+      by_end.values.sort_by { |v| v["end"] || "" }
+    end
+
+    def filing_priority(value)
+      form = value["form"] || ""
+      tier = PERIODIC_FORMS.include?(form) ? 1 : 0
+      [tier, value["filed"] || ""]
+    end
+
+    def derive_q2(quarters, ytd_6m)
+      derived = []
+      ytd_6m.each do |ytd6|
+        q1 = find_prior_by_end(quarters, before: ytd6["end"])
+        next unless q1
+
+        q2_val = ytd6["val"].to_f - q1["val"].to_f
+        next if q2_val.negative?
+
+        derived << { "val" => q2_val, "end" => ytd6["end"], "fp" => "Q2" }
+      end
+      derived
+    end
+
+    def derive_q3(ytd_6m, ytd_9m)
+      derived = []
+      ytd_9m.each do |ytd9|
+        ytd6 = find_prior_by_end(ytd_6m, before: ytd9["end"])
+        next unless ytd6
+
+        q3_val = ytd9["val"].to_f - ytd6["val"].to_f
+        next if q3_val.negative?
+
+        derived << { "val" => q3_val, "end" => ytd9["end"], "fp" => "Q3" }
+      end
+      derived
+    end
+
+    def derive_q4(quarters, ytd_9m, annual_facts)
+      derived = []
+      annual_facts.each do |fy|
+        ytd9 = find_prior_by_end(ytd_9m, before: fy["end"])
+        unless ytd9
+          fy_quarters = quarters.select do |q|
+            q["end"] && fy["end"] && q["end"] < fy["end"] &&
+              fy["start"] && q["start"] && q["start"] >= fy["start"]
+          end
+          fy_quarters = dedup_by_end(fy_quarters)
+          next if fy_quarters.length < 3
+
+          q1q2q3 = fy_quarters.last(3)
+          q4_val = fy["val"].to_f - q1q2q3.sum { |q| q["val"].to_f }
+          next if q4_val.negative?
+
+          derived << { "val" => q4_val, "end" => fy["end"], "fp" => "Q4" }
+          next
+        end
+
+        q4_val = fy["val"].to_f - ytd9["val"].to_f
+        next if q4_val.negative?
+
+        derived << { "val" => q4_val, "end" => fy["end"], "fp" => "Q4" }
+      end
+      derived
+    end
+
+    def find_prior_by_end(values, before:)
+      candidates = values.select { |v| v["end"] && before && v["end"] < before }
+      candidates.max_by { |v| v["end"] || "" }
+    end
+  end
+end

data/lib/edgar/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Edgar
+  VERSION = "0.1.0"
+end

data/lib/edgar/xbrl/xbrl.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Edgar
+  module XBRL
+    # Parses XBRL XML documents for financial fact extraction.
+    class XBRL
+      attr_reader :raw
+
+      def initialize(xml_content)
+        @raw = xml_content
+        @doc = parse_document(xml_content)
+      end
+
+      def context_refs
+        @doc.css("context").map do |ctx|
+          id = ctx["id"]
+          entity = ctx.at_css("entity")
+          period = ctx.at_css("period")
+          start_el = period&.at_css("startDate")
+          end_el = period&.at_css("endDate")
+          instant_el = period&.at_css("instant")
+          # Detect segment dimensions (product/service, geographic, etc.)
+          segment = entity&.at_css("segment")
+          {
+            id: id,
+            entity: entity&.text&.strip,
+            start_date: start_el&.text&.strip,
+            end_date: end_el&.text&.strip,
+            instant: instant_el&.text&.strip,
+            segmented: !segment.nil?
+          }
+        end
+      end
+
+      def facts
+        xbrl_elements = @doc.xpath("//*[local-name() != 'context' and local-name() != 'unit' and local-name() != 'schemaRef' and local-name() != 'linkbaseRef']").select do |el|
+          ns = el.namespace
+          ns&.href&.include?("xbrl")
+        end
+        xbrl_elements.map do |el|
+          {
+            name: el.name,
+            namespace: el.namespace&.href,
+            value: el.text.strip,
+            context_ref: el["contextRef"],
+            unit_ref: el["unitRef"],
+            decimals: el["decimals"],
+            signature: el["signature"]
+          }
+        end
+      end
+
+      def units
+        @doc.css("unit").map do |u|
+          { id: u["id"], measure: u.at_css("measure")&.text&.strip }
+        end
+      end
+
+      def financial_concepts
+        ns_prefixes = @doc.namespaces.select { |_, v| v&.include?("us-gaap") || v&.include?("dei") }
+        return [] if ns_prefixes.empty?
+
+        financial_ns = ns_prefixes.map { |k, _| k.sub("xmlns:", "") }
+        xpath_expr = financial_ns.map { |p| "//#{p}:*" }.join(" | ")
+        @doc.xpath(xpath_expr).filter_map do |el|
+          next unless el["contextRef"]
+
+          {
+            name: el.name,
+            value: el.text.strip,
+            context_ref: el["contextRef"],
+            unit_ref: el["unitRef"],
+            decimals: el["decimals"]
+          }
+        end
+      end
+
+      def to_s
+        "#<XBRL facts=#{facts.length}>"
+      end
+
+      private
+
+      def parse_document(content)
+        Nokogiri::XML(content) { |config| config.strict.noblanks }
+      rescue Nokogiri::XML::SyntaxError
+        Nokogiri::XML(content)
+      end
+    end
+
+    # Parses Inline XBRL (iXBRL) HTML documents with embedded financial facts.
+    class InlineXBRL < XBRL
+      def facts
+        inline_elements = @doc.css("[name]").select do |el|
+          el["name"].to_s.include?(":") && el["contextref"]
+        end
+        inline_elements.map do |el|
+          {
+            name: el["name"],
+            value: el.text.strip,
+            context_ref: el["contextref"],
+            unit_ref: el["unitref"],
+            decimals: el["decimals"],
+            format: el["format"],
+            scale: el["scale"]
+          }
+        end
+      end
+
+      def context_refs
+        @doc.css("context").map do |ctx|
+          {
+            id: ctx["id"],
+            start_date: ctx.at_css("startDate")&.text&.strip,
+            end_date: ctx.at_css("endDate")&.text&.strip,
+            instant: ctx.at_css("instant")&.text&.strip
+          }
+        end
+      end
+
+      def financial_concepts
+        facts.select { |f| f[:name]&.include?("us-gaap") || f[:name]&.include?("dei") }
+      end
+
+      private
+
+      def parse_document(content)
+        Nokogiri::HTML(content)
+      end
+    end
+  end
+end

data/lib/edgar.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "json"
+require "zlib"
+require "stringio"
+require "date"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "http_client" => "HTTPClient",
+  "xbrl" => "XBRL",
+  "ttm_calculator" => "TTMCalculator"
+)
+loader.setup
+
+# Main entry point for the Edgar library providing SEC EDGAR filing access.
+module Edgar
+  class << self
+    def http_client
+      @http_client ||= HTTPClient.new
+    end
+
+    attr_writer :http_client
+
+    def configure
+      yield(self)
+    end
+
+    def company(identifier)
+      if identifier.is_a?(Integer) || identifier.to_s.match?(/^\d+$/)
+        Company.new(cik: identifier.to_i)
+      else
+        Company.new(ticker: identifier.to_s)
+      end
+    end
+
+    def identity=(email)
+      ENV["EDGAR_IDENTITY"] = email
+      @http_client = nil
+    end
+
+    def get_filings(year, quarter)
+      Filings.from_quarter(year, quarter)
+    end
+
+    def current_filings
+      today = Date.today
+      Filings.from_quarter(today.year, ((today.month - 1) / 3) + 1)
+    end
+
+    def get_entity(cik)
+      Entity.new(cik: cik)
+    end
+
+    def find_company(name, limit: 10)
+      Company.search(name, limit: limit)
+    end
+
+    def find(identifier)
+      return nil unless identifier
+
+      str = identifier.to_s.strip
+      return Company.new(cik: str.to_i) if str.match?(/^\d{10}$/)
+      return Company.new(cik: str.to_i) if str.match?(/^\d+$/) && str.length >= 6
+      return Company.new(ticker: str) if str.match?(/^[A-Za-z]{1,5}$/)
+
+      Company.search(str, limit: 1).first
+    end
+
+    def obj(filing)
+      DataObjects.for(filing)
+    end
+
+    def reset!
+      @http_client = nil
+    end
+
+    def version
+      VERSION
+    end
+  end
+end

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: ruby-edgar
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Edgar Tools Ruby Port
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A Ruby port of the edgartools Python library for accessing and analyzing
+  SEC EDGAR filings, including company lookups, filing retrieval, and financial data
+  extraction.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/edgar.rb
+- lib/edgar/attachment.rb
+- lib/edgar/attachments.rb
+- lib/edgar/company.rb
+- lib/edgar/config.rb
+- lib/edgar/data_objects.rb
+- lib/edgar/entity.rb
+- lib/edgar/entity_data.rb
+- lib/edgar/entity_facts.rb
+- lib/edgar/filing.rb
+- lib/edgar/filing_facts.rb
+- lib/edgar/filing_header.rb
+- lib/edgar/filing_homepage.rb
+- lib/edgar/filing_index.rb
+- lib/edgar/filing_sections.rb
+- lib/edgar/filings.rb
+- lib/edgar/financials.rb
+- lib/edgar/http_client.rb
+- lib/edgar/ttm_calculator.rb
+- lib/edgar/version.rb
+- lib/edgar/xbrl/xbrl.rb
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Ruby library to access SEC EDGAR filings
+test_files: []