Class: SecApi::Objects::Filing

Inherits:
Dry::Struct
  • Object
show all
Defined in:
lib/sec_api/objects/filing.rb

Overview

Represents an SEC filing with complete metadata.

Filing objects are immutable (frozen) and thread-safe for concurrent access. All date strings are automatically coerced to Ruby Date objects via Dry::Types.

Examples:

Accessing filing metadata

filing = client.query.where(ticker: "AAPL").first
filing.ticker         #=> "AAPL"
filing.form_type      #=> "10-K"
filing.accession_no   #=> "0000320193-24-000001"
filing.filed_at       #=> #<Date: 2024-01-15>
filing.filing_url     #=> "https://sec.gov/..."

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes) ⇒ Filing

Override constructor to ensure immutability



116
117
118
119
 
# File 'lib/sec_api/objects/filing.rb', line 116

def initialize(attributes)
  super
  freeze
end

Instance Attribute Details

#accession_number ⇒ String (readonly)

Returns SEC accession number (e.g., “0000320193-24-000001”).

Returns:

  • (String) —

    SEC accession number (e.g., “0000320193-24-000001”)



101
 
# File 'lib/sec_api/objects/filing.rb', line 101

attribute :accession_number, Types::String

#cik ⇒ String (readonly)

Returns SEC Central Index Key (e.g., “320193”).

Returns:

  • (String) —

    SEC Central Index Key (e.g., “320193”)



32
 
# File 'lib/sec_api/objects/filing.rb', line 32

attribute :cik, Types::String

#company_name ⇒ String (readonly)

Returns company name (e.g., “Apple Inc”).

Returns:

  • (String) —

    company name (e.g., “Apple Inc”)



40
 
# File 'lib/sec_api/objects/filing.rb', line 40

attribute :company_name, Types::String

#company_name_long ⇒ String (readonly)

Returns full company name (e.g., “Apple Inc.”).

Returns:

  • (String) —

    full company name (e.g., “Apple Inc.”)



44
 
# File 'lib/sec_api/objects/filing.rb', line 44

attribute :company_name_long, Types::String

#data_files ⇒ Array<DataFile> (readonly)

Returns associated data files.

Returns:

  • (Array<DataFile>) —

    associated data files



97
 
# File 'lib/sec_api/objects/filing.rb', line 97

attribute :data_files, Types::Array.of(DataFile)

#description ⇒ String? (readonly)

Returns optional filing description.

Returns:

  • (String, nil) —

    optional filing description



105
 
# File 'lib/sec_api/objects/filing.rb', line 105

attribute? :description, Types::String.optional

#documents ⇒ Array<DocumentFormatFile> (readonly)

Returns document format files.

Returns:



93
 
# File 'lib/sec_api/objects/filing.rb', line 93

attribute :documents, Types::Array.of(DocumentFormatFile)

#effectiveness_date ⇒ String? (readonly)

Returns effectiveness date for registration statements.

Returns:

  • (String, nil) —

    effectiveness date for registration statements



113
 
# File 'lib/sec_api/objects/filing.rb', line 113

attribute? :effectiveness_date, Types::String.optional

#entities ⇒ Array<Entity> (readonly)

Returns associated entities.

Returns:

  • (Array<Entity>) —

    associated entities



89
 
# File 'lib/sec_api/objects/filing.rb', line 89

attribute :entities, Types::Array.of(Entity)

#filed_at ⇒ Date (readonly)

Returns filing date (automatically coerced from string via Dry::Types).

Returns:

  • (Date) —

    filing date (automatically coerced from string via Dry::Types)



69
 
# File 'lib/sec_api/objects/filing.rb', line 69

attribute :filed_at, Types::JSON::Date

#filing_details_url ⇒ String (readonly)

Returns URL to filing details page.

Returns:

  • (String) —

    URL to filing details page



85
 
# File 'lib/sec_api/objects/filing.rb', line 85

attribute :filing_details_url, Types::String

#form_type ⇒ String (readonly)

Note:

Filing objects handle all form types uniformly - no special handling for international forms. The same structure applies to domestic and foreign filings.

Returns SEC form type. Includes both domestic forms (10-K, 10-Q, 8-K, etc.) and international forms (20-F, 40-F, 6-K for foreign private issuers).

Examples:

Domestic filing

filing.form_type  #=> "10-K"

Foreign private issuer annual report

filing.form_type  #=> "20-F"

Canadian issuer annual report (MJDS)

filing.form_type  #=> "40-F"

Foreign current report

filing.form_type  #=> "6-K"

Returns:

  • (String) —

    SEC form type. Includes both domestic forms (10-K, 10-Q, 8-K, etc.) and international forms (20-F, 40-F, 6-K for foreign private issuers).

See Also:



61
 
# File 'lib/sec_api/objects/filing.rb', line 61

attribute :form_type, Types::String

#html_url ⇒ String (readonly)

Returns URL to HTML filing.

Returns:

  • (String) —

    URL to HTML filing



77
 
# File 'lib/sec_api/objects/filing.rb', line 77

attribute :html_url, Types::String

#id ⇒ String (readonly)

Returns unique filing identifier.

Returns:

  • (String) —

    unique filing identifier



28
 
# File 'lib/sec_api/objects/filing.rb', line 28

attribute :id, Types::String

#period_of_report ⇒ String? (readonly)

Returns reporting period end date (may be nil for some filing types).

Returns:

  • (String, nil) —

    reporting period end date (may be nil for some filing types)



65
 
# File 'lib/sec_api/objects/filing.rb', line 65

attribute? :period_of_report, Types::String.optional

#series_and_classes_contracts_information ⇒ Array<Hash>? (readonly)

Returns series and classes/contracts info (mutual funds, ETFs).

Returns:

  • (Array<Hash>, nil) —

    series and classes/contracts info (mutual funds, ETFs)



109
 
# File 'lib/sec_api/objects/filing.rb', line 109

attribute? :series_and_classes_contracts_information, Types::Array.of(Types::Hash).optional

#ticker ⇒ String (readonly)

Returns company stock ticker symbol (e.g., “AAPL”).

Returns:

  • (String) —

    company stock ticker symbol (e.g., “AAPL”)



36
 
# File 'lib/sec_api/objects/filing.rb', line 36

attribute :ticker, Types::String

#txt_url ⇒ String (readonly)

Returns URL to plain text filing.

Returns:

  • (String) —

    URL to plain text filing



73
 
# File 'lib/sec_api/objects/filing.rb', line 73

attribute :txt_url, Types::String

#xbrl_url ⇒ String (readonly)

Returns URL to XBRL filing.

Returns:

  • (String) —

    URL to XBRL filing



81
 
# File 'lib/sec_api/objects/filing.rb', line 81

attribute :xbrl_url, Types::String

Class Method Details

.from_api(data) ⇒ Filing

Creates a Filing from API response data.

Normalizes camelCase keys from the API to snake_case and recursively builds nested Entity, DocumentFormatFile, and DataFile objects.

Examples:

data = { id: "abc123", ticker: "AAPL", formType: "10-K", ... }
filing = Filing.from_api(data)
filing.form_type  # => "10-K"

Parameters:

  • data (Hash) —

    API response hash with filing data

Returns:

  • (Filing) —

    Immutable filing object



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/sec_api/objects/filing.rb', line 163

def self.from_api(data)
  data[:company_name] = data.delete(:companyName) if data.key?(:companyName)
  data[:company_name_long] = data.delete(:companyNameLong) if data.key?(:companyNameLong)
  data[:form_type] = data.delete(:formType) if data.key?(:formType)
  data[:period_of_report] = data.delete(:periodOfReport) if data.key?(:periodOfReport)
  data[:filed_at] = data.delete(:filedAt) if data.key?(:filedAt)
  data[:txt_url] = data.delete(:linkToTxt) if data.key?(:linkToTxt)
  data[:html_url] = data.delete(:linkToHtml) if data.key?(:linkToHtml)
  data[:xbrl_url] = data.delete(:linkToXbrl) if data.key?(:linkToXbrl)
  data[:filing_details_url] = data.delete(:linkToFilingDetails) if data.key?(:linkToFilingDetails)
  data[:documents] = data.delete(:documentFormatFiles) if data.key?(:documentFormatFiles)
  data[:data_files] = data.delete(:dataFiles) if data.key?(:dataFiles)
  data[:accession_number] = data.delete(:accessionNo) if data.key?(:accessionNo)
  data[:series_and_classes_contracts_information] = data.delete(:seriesAndClassesContractsInformation) if data.key?(:seriesAndClassesContractsInformation)
  data[:effectiveness_date] = data.delete(:effectivenessDate) if data.key?(:effectivenessDate)

  entities = data[:entities].map do |entity|
    Entity.from_api(entity)
  end

  documents = data[:documents].map do |document|
    DocumentFormatFile.from_api(document)
  end

  data_files = data[:data_files].map do |data_file|
    DataFile.from_api(data_file)
  end
  data[:entities] = entities
  data[:documents] = documents
  data[:data_files] = data_files
  new(data)
end

Instance Method Details

#accession_no ⇒ String

Alias for #accession_number.

Examples:

filing.accession_no #=> "0000320193-24-000001"

Returns:

  • (String) —

    SEC accession number



137
138
139
 
# File 'lib/sec_api/objects/filing.rb', line 137

def accession_no
  accession_number
end

#filing_url ⇒ String?

Alias for #url. Returns the preferred filing URL.

Examples:

filing.filing_url #=> "https://sec.gov/Archives/..."

Returns:

  • (String, nil) —

    the filing URL or nil if neither available



146
147
148
 
# File 'lib/sec_api/objects/filing.rb', line 146

def filing_url
  url
end

#url ⇒ String?

Returns the preferred filing URL (HTML if available, otherwise TXT).

Examples:

filing.url #=> "https://sec.gov/Archives/..."

Returns:

  • (String, nil) —

    the filing URL or nil if neither available



126
127
128
129
130
 
# File 'lib/sec_api/objects/filing.rb', line 126

def url
  return html_url unless html_url.nil? || html_url.empty?
  return txt_url unless txt_url.nil? || txt_url.empty?
  nil
end