ruby-edgar 0.1.0

data/lib/edgar/data_objects.rb

@@ -0,0 +1,521 @@
+# frozen_string_literal: true
+
+module Edgar
+  # Form-type dispatching: maps filing forms to specialized data objects.
+  module DataObjects
+    # Base class for form-specific data wrappers.
+    class Base
+      attr_reader :filing
+
+      def initialize(filing)
+        @filing = filing
+      end
+
+      def form_type
+        @filing.form
+      end
+
+      def company_name
+        @filing.company
+      end
+
+      def filing_date
+        @filing.filing_date
+      end
+
+      def accession_number
+        @filing.accession_number
+      end
+
+      def to_s
+        "#<#{self.class.name.split('::').last} #{form_type} #{company_name}>"
+      end
+    end
+
+    # Wraps a 10-K annual filing with section accessors.
+    class TenK < Base
+      def items
+        @filing.sections
+      end
+
+      def business
+        items["1"]
+      end
+
+      def risk_factors
+        items["1A"]
+      end
+
+      def financial_statements
+        items["8"]
+      end
+
+      def exhibits
+        @filing.exhibits
+      end
+    end
+
+    # Wraps a 10-Q quarterly filing with section accessors.
+    class TenQ < Base
+      def items
+        @filing.sections
+      end
+
+      def financial_statements
+        items["1"]
+      end
+
+      def legal_proceedings
+        items["1"]
+      end
+    end
+
+    # Wraps a Form 4 insider trading filing.
+    class Form4 < Base
+      def transactions
+        @filing.xbrl&.financial_concepts || []
+      end
+
+      def issuer_cik
+        @filing.cik
+      end
+    end
+
+    # Wraps an 8-K current report filing.
+    class Form8K < Base
+      def items
+        @filing.sections
+      end
+
+      def exhibit_list
+        @filing.exhibits
+      end
+    end
+
+    # Wraps a Schedule 13D beneficial ownership filing.
+    class Schedule13D < Base
+      def beneficial_owner
+        @filing.header.filers.first
+      end
+    end
+
+    # Wraps a Schedule 13G beneficial ownership filing.
+    class Schedule13G < Base
+      def beneficial_owner
+        @filing.header.filers.first
+      end
+    end
+
+    # Wraps an NPORT-P portfolio holding filing.
+    class FormNport < Base
+      def report_date
+        @filing.header.period_of_report
+      end
+
+      def fund_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps a Form 13F institutional holdings filing.
+    class Form13F < Base
+      def report_date
+        @filing.header.period_of_report
+      end
+
+      def filing_manager
+        @filing.header.filer_company
+      end
+
+      def holdings
+        xml = @filing.xml
+        return [] if xml.empty?
+
+        doc = Nokogiri::XML(xml)
+        doc.remove_namespaces!
+        entries = []
+        doc.xpath("//infoTable").each do |table|
+          entry = {
+            name_of_issuer: table.at_xpath("nameOfIssuer")&.text,
+            title_of_class: table.at_xpath("titleOfClass")&.text,
+            cusip: table.at_xpath("cusip")&.text,
+            value: table.at_xpath("value")&.text&.to_i,
+            shares: table.at_xpath("shrsOrPrnAmt/shrsPrnAmt")&.text&.to_i,
+            put_call: table.at_xpath("putCall")&.text,
+            investment_discretion: table.at_xpath("investmentDiscretion")&.text,
+            voting_authority_sole: table.at_xpath("votingAuthority/sole")&.text&.to_i,
+            voting_authority_shared: table.at_xpath("votingAuthority/shared")&.text&.to_i,
+            voting_authority_none: table.at_xpath("votingAuthority/none")&.text&.to_i
+          }
+          entries << entry
+        end
+        entries
+      rescue StandardError
+        []
+      end
+    end
+
+    # Wraps a filing summary report.
+    class FilingSummary < Base
+    end
+
+    # Wraps a Form 3 initial insider ownership filing.
+    class Form3 < Base
+      def issuer_cik
+        @filing.cik
+      end
+    end
+
+    # Wraps a Form 5 annual insider ownership filing.
+    class Form5 < Base
+      def issuer_cik
+        @filing.cik
+      end
+    end
+
+    # Wraps a proxy statement (DEF 14A, etc.).
+    class ProxyStatement < Base
+      def items
+        @filing.sections
+      end
+
+      def proposals
+        items
+      end
+    end
+
+    # Wraps an S-1 IPO registration filing.
+    class S1 < Base
+      def items
+        @filing.sections
+      end
+
+      def business
+        items["1"]
+      end
+
+      def risk_factors
+        items["1A"]
+      end
+
+      def financial_statements
+        items["8"]
+      end
+    end
+
+    # Wraps a Form 20-F foreign filer annual report.
+    class Form20F < Base
+      def items
+        @filing.sections
+      end
+    end
+
+    # Wraps a Form 6-K foreign filer current report.
+    class Form6K < Base
+      def items
+        @filing.sections
+      end
+    end
+
+    # Wraps an N-CSR fund annual report.
+    class FormNCSR < Base
+    end
+
+    # Wraps a Form 144 restricted stock filing.
+    class Form144 < Base
+      def securities_sold
+        @filing.header.fields["SECURITIES SOLD"] || []
+      end
+
+      def issuer
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps a Form C crowdfunding filing.
+    class FormC < Base
+      def offering_amount
+        @filing.header.fields["TOTAL OFFERING AMOUNT"]&.first
+      end
+
+      def issuer
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps a Form D offering filing.
+    class FormD < Base
+      def offering_amount
+        @filing.header.fields["TOTAL OFFERING AMOUNT"]&.first
+      end
+
+      def issuer
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps an S-3 shelf registration filing.
+    class RegistrationS3 < Base
+      def items
+        @filing.sections
+      end
+
+      def risk_factors
+        items["1A"]
+      end
+    end
+
+    # Wraps a 424B prospectus filing.
+    class Prospectus424B < Base
+      def items
+        @filing.sections
+      end
+    end
+
+    # Wraps a SEC correspondence filing.
+    class Correspondence < Base
+      def subject
+        @filing.header.fields["SUBJECT"]&.first
+      end
+    end
+
+    # Wraps an SEC Effect filing.
+    class Effect < Base
+      def effect_type
+        @filing.header.fields["EFFECT"]&.first
+      end
+    end
+
+    # Wraps an Alternative Trading System filing.
+    class AlternativeTradingSystem < Base
+      def ats_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps a Draft Registration Statement filing.
+    class DraftRegistrationStatement < Base
+      def items
+        @filing.sections
+      end
+    end
+
+    # Wraps a 40-F Canadian MJDS annual report.
+    class FortyF < Form20F
+    end
+
+    # Wraps an F-1 foreign registration statement.
+    class RegistrationS1 < S1
+    end
+
+    # Wraps a Fund portfolio holdings report (NPORT-P).
+    class FundReport < FormNport
+    end
+
+    # Wraps a Fund shareholder report (N-CSR / N-CSRS).
+    class FundShareholderReport < FormNCSR
+    end
+
+    # Wraps a Money Market Fund report (N-MFP2 / N-MFP3).
+    class MoneyMarketFund < Base
+      def report_date
+        @filing.header.period_of_report
+      end
+
+      def fund_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps a Fund census report (N-CEN).
+    class FundCensus < Base
+      def report_date
+        @filing.header.period_of_report
+      end
+
+      def fund_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps an N-PX proxy voting record.
+    class NPX < Base
+      def report_date
+        @filing.header.period_of_report
+      end
+
+      def fund_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps a 497K summary prospectus.
+    class Prospectus497K < Base
+      def fund_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps a 24F-2NT fund fee notice.
+    class FundFeeNotice < Base
+      def fund_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps a Municipal Advisor Form (MA-I).
+    class MunicipalAdvisorForm < Base
+      def firm_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Wraps an ABS distribution report (10-D).
+    class TenD < Base
+      def items
+        @filing.sections
+      end
+
+      def distribution_data
+        @filing.attachments.select { |a| a.document_type == "EX-102" }
+      end
+    end
+
+    # Generic wrapper for XML-based SEC filings (X-17A-5, TA-1, TA-2, etc.).
+    class XmlFiling < Base
+      def xml_data
+        @filing.xml
+      end
+
+      def parsed_xml
+        return nil if xml_data.empty?
+
+        Nokogiri::XML(xml_data)
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Wraps an Alternative Trading System Cessation filing (ATS-N-C).
+    class AtsCessation < Base
+      def ats_name
+        @filing.header.filer_company
+      end
+    end
+
+    # Python-compatible alias classes
+    EightK = Form8K
+    SixK = Form6K
+    TwentyF = Form20F
+
+    FORM_MAP = {
+      "10-K" => TenK,
+      "10-K/A" => TenK,
+      "10-Q" => TenQ,
+      "10-Q/A" => TenQ,
+      "4" => Form4,
+      "4/A" => Form4,
+      "8-K" => EightK,
+      "8-K/A" => EightK,
+      "6-K" => SixK,
+      "6-K/A" => SixK,
+      "20-F" => TwentyF,
+      "20-F/A" => TwentyF,
+      "40-F" => FortyF,
+      "40-F/A" => FortyF,
+      "SC 13D" => Schedule13D,
+      "SC 13D/A" => Schedule13D,
+      "SC 13G" => Schedule13G,
+      "SC 13G/A" => Schedule13G,
+      "NPORT-P" => FundReport,
+      "NPORT-P/A" => FundReport,
+      "NPORT-EX" => FundReport,
+      "13F-HR" => Form13F,
+      "13F-HR/A" => Form13F,
+      "3" => Form3,
+      "3/A" => Form3,
+      "5" => Form5,
+      "5/A" => Form5,
+      "144" => Form144,
+      "144/A" => Form144,
+      "DEF 14A" => ProxyStatement,
+      "DEFA 14A" => ProxyStatement,
+      "DEFM 14A" => ProxyStatement,
+      "DEFC 14A" => ProxyStatement,
+      "DEFN 14A" => ProxyStatement,
+      "DFAN 14A" => ProxyStatement,
+      "DEFR 14A" => ProxyStatement,
+      "DFRN 14A" => ProxyStatement,
+      "PRE 14A" => ProxyStatement,
+      "PREC 14A" => ProxyStatement,
+      "PREN 14A" => ProxyStatement,
+      "PREM 14A" => ProxyStatement,
+      "S-1" => RegistrationS1,
+      "S-1/A" => RegistrationS1,
+      "F-1" => RegistrationS1,
+      "F-1/A" => RegistrationS1,
+      "S-3" => RegistrationS3,
+      "S-3/A" => RegistrationS3,
+      "S-3ASR" => RegistrationS3,
+      "S-3ASR/A" => RegistrationS3,
+      "S-3D" => RegistrationS3,
+      "S-3DPOS" => RegistrationS3,
+      "F-3" => RegistrationS3,
+      "F-3/A" => RegistrationS3,
+      "F-3ASR" => RegistrationS3,
+      "F-3ASR/A" => RegistrationS3,
+      "424B1" => Prospectus424B,
+      "424B2" => Prospectus424B,
+      "424B3" => Prospectus424B,
+      "424B4" => Prospectus424B,
+      "424B5" => Prospectus424B,
+      "424B7" => Prospectus424B,
+      "424B8" => Prospectus424B,
+      "497K" => Prospectus497K,
+      "N-CSR" => FundShareholderReport,
+      "N-CSRS" => FundShareholderReport,
+      "N-CEN" => FundCensus,
+      "N-MFP2" => MoneyMarketFund,
+      "N-MFP3" => MoneyMarketFund,
+      "N-PX" => NPX,
+      "10-D" => TenD,
+      "10-D/A" => TenD,
+      "24F-2NT" => FundFeeNotice,
+      "MA-I" => MunicipalAdvisorForm,
+      "MA" => XmlFiling,
+      "MA-W" => XmlFiling,
+      "C" => FormC,
+      "C/A" => FormC,
+      "C-U" => FormC,
+      "C-AR" => FormC,
+      "C-TR" => FormC,
+      "D" => FormD,
+      "D/A" => FormD,
+      "CORRESP" => Correspondence,
+      "UPLOAD" => Correspondence,
+      "EFFECT" => Effect,
+      "ATS-N" => AlternativeTradingSystem,
+      "ATS-N/A" => AlternativeTradingSystem,
+      "ATS-N-W" => AlternativeTradingSystem,
+      "DRS" => DraftRegistrationStatement,
+      "DRS/A" => DraftRegistrationStatement,
+      "X-17A-5" => XmlFiling,
+      "TA-1" => XmlFiling,
+      "TA-2" => XmlFiling,
+      "TA-W" => XmlFiling,
+      "CFPORTAL" => XmlFiling,
+      "SBSE" => XmlFiling,
+      "SBSE-A" => XmlFiling,
+      "SBSE-W" => XmlFiling,
+      "ATS-N-C" => AtsCessation
+    }.freeze
+
+    def self.for(filing)
+      form = filing.form
+      klass = FORM_MAP[form]
+      klass ||= FORM_MAP[form.sub(%r{/A$}, "")]
+      klass ||= Base
+      klass.new(filing)
+    end
+  end
+end

data/lib/edgar/entity.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Edgar
+  # Base class wrapping SEC submissions API data for a CIK entity.
+  class Entity
+    attr_reader :cik
+
+    def initialize(cik:, name: nil)
+      @cik = cik.to_i
+      @name = name
+      @entity_data = nil
+    end
+
+    def name
+      @name || data.name
+    end
+
+    def data
+      @data ||= EntityData.new(cik: @cik)
+    end
+
+    def display_name
+      data.name
+    end
+
+    def company?
+      data.company?
+    end
+
+    def individual?
+      data.individual?
+    end
+
+    def not_found?
+      data.not_found?
+    end
+
+    def mailing_address
+      data.mailing_address
+    end
+
+    def business_address
+      data.business_address
+    end
+
+    def get_filings(form: nil, year: nil, quarter: nil, accession_number: nil,
+                    filing_date: nil, date: nil,
+                    amendments: nil, date_start: nil, date_end: nil)
+      filings = if year && quarter
+                  Filings.from_quarter(year, quarter)
+                else
+                  build_filings_from_submissions
+                end
+
+      filings = filings.filter(
+        form: form,
+        filing_date: filing_date || date,
+        cik: @cik,
+        amendments: amendments,
+        date_start: date_start,
+        date_end: date_end
+      )
+
+      if accession_number
+        filing = filings.find { |f| f.accession_number == accession_number }
+        return filing ? Filings.new([filing]) : Filings.new([])
+      end
+
+      filings
+    end
+
+    def to_s
+      "#<Entity #{@cik}>"
+    end
+
+    private
+
+    def build_filings_from_submissions
+      all = data.all_filings
+      forms = all["form"] || []
+      dates = all["filingDate"] || []
+      accs = all["accessionNumber"] || []
+      companies = all["company"] || []
+
+      entries = forms.each_with_index.map do |f, i|
+        {
+          cik: @cik,
+          company: companies[i] || display_name,
+          form: f,
+          filing_date: dates[i],
+          accession_number: accs[i]
+        }
+      end
+
+      Filings.new(entries)
+    end
+  end
+end