ruby-edgar 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c84e8a66ea352689f9a15dbf08929fa4e9756179c39584bb4c2b2a0171273fe3
+  data.tar.gz: 8bed90b9eecebf10d7128169481bbc15b992eb809557aedccaece3dfdd6536bc
+SHA512:
+  metadata.gz: 05dc039c7a2a9be8793772ec81994ea63cf58ec9f68563e055f3fdea7636e9e4466be9af2a9bc1ec83499fc862dbf2acde7c1bc2c839eeac1ea71543bc5c8ed7
+  data.tar.gz: c5534a89eb6b87fe1a9b70bb94b6c258bb10f449442428d297df9155be3937ae270f354bf85b1e7eac89a7cefbc7819f0e4b00fbd41b6743ed469475ea6006a6

data/README.md

@@ -0,0 +1,120 @@
+# Edgar
+
+A Ruby library for accessing SEC EDGAR filings. Port of the Python [edgartools](https://github.com/dgunning/edgartools) library.
+
+## Installation
+
+```ruby
+gem "ruby-edgar", git: "https://github.com/tian-im/edgar"
+```
+
+Or build locally:
+
+```
+gem build ruby-edgar.gemspec
+gem install ruby-edgar-0.1.0.gem
+```
+
+## Usage
+
+### Company Lookup
+
+```ruby
+require "edgar"
+
+# By ticker
+aapl = Edgar.Company("AAPL")
+aapl.cik  # => 320193
+
+# By CIK
+company = Edgar::Company.new(cik: 320193)
+```
+
+### Entity Data
+
+```ruby
+data = aapl.data
+data.name          # => "Apple Inc."
+data.tickers       # => ["AAPL"]
+data.exchanges     # => ["Nasdaq"]
+data.sic           # => 3571
+data.category      # => "Large accelerated filer"
+data.business_address  # => Address
+```
+
+### Financial Facts
+
+```ruby
+facts = aapl.facts
+facts.concept_values("Revenues", limit: 1)
+facts.concept_values("NetIncomeLoss", limit: 1)
+facts.list_concepts(search: "Revenue", limit: 10)
+```
+
+### Search Filings by Quarter
+
+```ruby
+filings = Edgar::Filings.from_quarter(2024, 4)
+aapl_filings = filings.filter(cik: 320193)
+aapl_filings.latest(5).each { |f| puts "#{f.form} #{f.filing_date}" }
+```
+
+### Access a Filing
+
+```ruby
+filing = aapl_filings.first
+filing.form            # => "10-K"
+filing.filing_date     # => Date
+filing.html            # => Primary HTML document
+filing.text            # => Full submission text
+filing.header.period_of_report  # => "20240928"
+filing.header.filer_company     # => "Apple Inc."
+```
+
+### Attachments
+
+```ruby
+filing.attachments.each do |a|
+  puts "#{a.document} (#{a.document_type})"
+end
+
+filing.exhibits   # Exhibit attachments
+filing.datafiles  # XML data files
+```
+
+### Data Objects
+
+```ruby
+obj = Edgar::DataObjects.for(filing)
+# Returns TenK, TenQ, Form4, etc. based on form type
+obj.form_type
+obj.company_name
+```
+
+### XBRL
+
+```ruby
+xbrl = filing.xbrl
+xbrl.facts          # Array of fact hashes
+xbrl.context_refs   # Reporting contexts
+xbrl.financial_concepts  # US-GAAP concepts
+```
+
+## Configuration
+
+Set the `EDGAR_IDENTITY` environment variable:
+
+```
+export EDGAR_IDENTITY="Your Name your.email@example.com"
+```
+
+## Development
+
+```
+bundle install
+ruby -e 'require "bundler/setup"; require "edgar"'
+```
+
+## License
+
+MIT

data/lib/edgar/attachment.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Edgar
+  # Represents a single file attachment within an SEC filing.
+  class Attachment
+    EXHIBIT_DESCRIPTIONS = {
+      "10-K" => "Annual Report",
+      "10-Q" => "Quarterly Report",
+      "8-K" => "Current Report",
+      "EX-10" => "Material Contract",
+      "EX-21" => "Subsidiaries",
+      "EX-23" => "Consent of Expert",
+      "EX-31" => "Certification",
+      "EX-32" => "Certification"
+    }.freeze
+
+    attr_reader :sequence_number, :description, :document, :ixbrl, :path,
+                :document_type, :size, :sgml_document, :purpose, :url
+
+    def initialize(sequence_number:, description: nil, document: nil, ixbrl: false,
+                   path: nil, document_type: nil, size: nil, sgml_document: nil,
+                   purpose: nil, url: nil)
+      @sequence_number = sequence_number
+      @description = description
+      @document = document
+      @ixbrl = ixbrl
+      @path = path
+      @document_type = document_type
+      @size = size
+      @sgml_document = sgml_document
+      @purpose = purpose
+      @url = url
+    end
+
+    def display_description
+      EXHIBIT_DESCRIPTIONS[@document_type] || @description
+    end
+
+    def extension
+      return "" unless @document
+
+      File.extname(@document).downcase
+    end
+
+    def text?
+      extension == ".txt" || document_type&.include?("TEXT")
+    end
+
+    def xml?
+      [".xml", ".xsl"].include?(extension)
+    end
+
+    def html?
+      [".htm", ".html"].include?(extension)
+    end
+
+    def binary?
+      !text? && !xml? && !html?
+    end
+
+    def empty?
+      @size.nil? || @size.to_i.zero?
+    end
+
+    def to_s
+      "#<Attachment seq=#{@sequence_number} type=#{@document_type} desc='#{@description}'>"
+    end
+  end
+end

data/lib/edgar/attachments.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Edgar
+  # Enumerable collection of Attachment objects for a filing.
+  class Attachments
+    include Enumerable
+
+    attr_reader :attachments
+
+    def initialize(attachments = [])
+      @attachments = attachments
+    end
+
+    def each(&block)
+      @attachments.each(&block)
+    end
+
+    def [](index)
+      @attachments[index]
+    end
+
+    def length
+      @attachments.length
+    end
+
+    def exhibits
+      select { |a| a.purpose&.downcase&.include?("exhibit") }
+    end
+
+    def reports
+      select { |a| a.purpose&.downcase&.include?("report") }
+    end
+
+    def statements
+      select { |a| a.purpose&.downcase&.include?("statement") }
+    end
+
+    def primary_documents
+      sorted = sort_by(&:sequence_number)
+      sorted.select { |a| a.sequence_number == sorted.first&.sequence_number }
+    end
+
+    def primary_html_document
+      sorted = sort_by(&:sequence_number)
+      sorted.find(&:html?)
+    end
+
+    def primary_xml_document
+      find(&:xml?)
+    end
+
+    def xbrl_document
+      # Standard XBRL instance (EX-101.INS) or iXBRL-tagged document
+      found = find { |a| a.document_type == "EX-101.INS" || a.ixbrl }
+      return found if found
+
+      # Fallback: look for _htm.xml extracted XBRL instance (common in modern
+      # iXBRL filings where the instance is embedded in the HTML and an XML
+      # copy is provided as a datafile)
+      find { |a| a.document&.end_with?("_htm.xml") }
+    end
+
+    def datafiles
+      select(&:xml?)
+    end
+
+    def documents
+      select { |a| a.html? || a.text? }
+    end
+
+    def to_s
+      "#<Attachments count=#{@attachments.length}>"
+    end
+  end
+end

data/lib/edgar/company.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Edgar
+  # A company identified by ticker symbol, extending Entity with SEC lookup.
+  class Company < Entity
+    attr_reader :ticker
+
+    def initialize(cik: nil, ticker: nil)
+      if ticker
+        @ticker = ticker.upcase
+        cik ||= Company.lookup_cik(@ticker)
+      end
+
+      super(cik: cik)
+    end
+
+    def tickers
+      data.tickers
+    end
+
+    def primary_ticker
+      tickers.first
+    end
+
+    def exchanges
+      data.exchanges
+    end
+
+    def sic
+      data.sic
+    end
+
+    def industry
+      data.sic_description
+    end
+
+    def fiscal_year_end
+      data.fiscal_year_end
+    end
+
+    def website
+      data.website
+    end
+
+    def phone
+      data.phone
+    end
+
+    def state_of_incorporation
+      data.state_of_incorporation
+    end
+
+    def description
+      data.description
+    end
+
+    def financials
+      @financials ||= begin
+        filing = find_latest_filing_by_form("10-K") ||
+                 find_latest_filing_by_form("20-F") ||
+                 find_latest_filing_by_form("40-F")
+        if filing
+          Financials.extract(filing) || Financials.new(cik: @cik)
+        else
+          Financials.new(cik: @cik)
+        end
+      end
+    end
+
+    def facts
+      @facts ||= EntityFacts.new(cik: @cik)
+    end
+
+    def latest_tenk
+      find_latest_filing_by_form("10-K")
+    end
+
+    def latest_tenq
+      find_latest_filing_by_form("10-Q")
+    end
+
+    def annual_financials
+      filing = latest_tenk
+      return Financials.extract(filing) if filing
+
+      %w[20-F 40-F].each do |form|
+        f = find_latest_filing_by_form(form)
+        return Financials.extract(f) if f
+      end
+      nil
+    end
+
+    def quarterly_financials
+      filing = latest_tenq
+      return Financials.extract(filing) if filing
+
+      filing = find_latest_filing_by_form("6-K")
+      return Financials.extract(filing) if filing
+
+      nil
+    end
+
+    def business_category
+      sic_str = sic.to_s
+      return "Bank" if %w[6021 6022 6035 6036].include?(sic_str)
+      return "Insurance Company" if %w[6311 6321 6331].include?(sic_str)
+      return "REIT" if sic_str == "6798"
+
+      et = data.entity_type.to_s.downcase
+      return "Investment Manager" if et.include?("investment")
+      return "Operating Company" if et == "operating"
+
+      "Operating Company"
+    end
+
+    def fund?
+      ["ETF", "Mutual Fund", "Closed-End Fund"].include?(business_category)
+    end
+
+    def operating_company?
+      business_category == "Operating Company"
+    end
+
+    def financial_institution?
+      ["Bank", "Insurance Company", "Investment Manager", "BDC"].include?(business_category)
+    end
+
+    def foreign?
+      %w[Foreign Canadian].include?(filer_type)
+    end
+
+    def filer_type
+      return "Domestic" if state_of_incorporation == "CA"
+      return "Foreign" unless %w[CA DE FL IL MA MD NJ NY NV OH PA TX VA WA].include?(state_of_incorporation)
+
+      "Domestic"
+    end
+
+    def to_s
+      ticker_str = @ticker || tickers.first
+      "#<Company #{ticker_str} (#{@cik})>"
+    end
+
+    def self.lookup_cik(ticker)
+      return @ticker_cache[ticker.upcase] if @ticker_cache&.key?(ticker.upcase)
+
+      data = load_company_data
+      mapping = {}
+
+      data.each do |entry|
+        t = entry[:ticker]
+        mapping[t] = entry[:cik]
+      end
+
+      cik = mapping[ticker.upcase]
+      (@ticker_cache ||= {})[ticker.upcase] = cik if cik
+      cik
+    end
+
+    def self.search(query, limit: 10)
+      return [] if query.nil? || query.strip.empty?
+
+      data = load_company_data
+      q = query.strip.downcase
+
+      matches = data.select do |entry|
+        entry[:ticker].downcase.include?(q) ||
+          entry[:title].downcase.include?(q)
+      end
+
+      matches.first(limit)
+    end
+
+    def self.load_company_data
+      return @company_data_cache if @company_data_cache
+
+      @company_data_cache = []
+      url = Config.tickers_url
+      raw = Edgar.http_client.download_json(url)
+
+      raw.each_value do |entry|
+        @company_data_cache << {
+          cik: entry["cik_str"].to_i,
+          ticker: entry["ticker"],
+          title: entry["title"]
+        }
+      end
+
+      @company_data_cache
+    end
+
+    def self.clear_search_cache!
+      @company_data_cache = nil
+    end
+
+    private_class_method :load_company_data
+
+    private
+
+    def find_latest_filing_by_form(form)
+      recent = data.recent_filings
+      forms = recent["form"] || []
+      dates = recent["filingDate"] || []
+      accs = recent["accessionNumber"] || []
+      idx = forms.index(form)
+      return nil unless idx
+
+      Filing.new(
+        cik: @cik,
+        company: display_name,
+        form: form,
+        filing_date: dates[idx],
+        accession_number: accs[idx]
+      )
+    end
+  end
+end

data/lib/edgar/config.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Edgar
+  # SEC endpoint URLs, rate limit constants, and URL builder methods.
+  module Config
+    SEC_BASE_URL = "https://www.sec.gov"
+    SEC_DATA_URL = "https://data.sec.gov"
+    SEC_ARCHIVE_URL = "#{SEC_BASE_URL}/Archives/edgar".freeze
+
+    EDGAR_RATE_LIMIT_PER_SEC = 9
+    EDGAR_IDENTITY = ENV.fetch("EDGAR_IDENTITY", "SampleCompanyName sample.email@example.com")
+
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_CONNECT_TIMEOUT = 10
+
+    module_function
+
+    def user_agent
+      "#{EDGAR_IDENTITY} (Ruby edgar gem #{Edgar::VERSION})"
+    end
+
+    def submissions_url(cik)
+      padded = cik.to_s.rjust(10, "0")
+      "#{SEC_DATA_URL}/submissions/CIK#{padded}.json"
+    end
+
+    def company_facts_url(cik)
+      padded = cik.to_s.rjust(10, "0")
+      "#{SEC_DATA_URL}/api/xbrl/companyfacts/CIK#{padded}.json"
+    end
+
+    def full_index_url(year, quarter, type = "company")
+      "#{SEC_ARCHIVE_URL}/full-index/#{year}/QTR#{quarter}/#{type}.gz"
+    end
+
+    def daily_index_url(year, quarter, date)
+      "#{SEC_ARCHIVE_URL}/daily-index/#{year}/QTR#{quarter}/#{date}.idx"
+    end
+
+    def filing_homepage_url(cik, accession_number)
+      "#{SEC_ARCHIVE_URL}/data/#{cik}/#{accession_number}-index.html"
+    end
+
+    def filing_text_url(cik, accession_number)
+      no_dashes = accession_number.delete("-")
+      "#{SEC_ARCHIVE_URL}/data/#{cik}/#{no_dashes}/#{accession_number}.txt"
+    end
+
+    def filing_dir_url(cik, accession_number)
+      no_dashes = accession_number.delete("-")
+      "#{SEC_ARCHIVE_URL}/data/#{cik}/#{no_dashes}"
+    end
+
+    def tickers_url
+      "#{SEC_BASE_URL}/files/company_tickers.json"
+    end
+
+    def submissions_file_url(_cik, filename)
+      "#{SEC_DATA_URL}/submissions/#{filename}"
+    end
+  end
+end