Class: SecApi::Objects::StreamFiling

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

Overview

Note:

All instances are frozen (immutable) for thread-safety.

Immutable value object representing a real-time filing from the Stream API.

StreamFiling contains the filing metadata delivered via WebSocket when a new filing is published to the SEC EDGAR system. The structure matches the sec-api.io Stream API message format.

Examples:

Accessing filing attributes

stream.subscribe do |filing|
  puts "#{filing.ticker}: #{filing.form_type}"
  puts "Filed at: #{filing.filed_at}"
  puts "Details: #{filing.link_to_filing_details}"
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes) ⇒ StreamFiling

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Override constructor to ensure deep immutability.

API:

  • private



87
88
89
90
91
92
93
 
# File 'lib/sec_api/objects/stream_filing.rb', line 87

def initialize(attributes)
  super
  deep_freeze(entities) if entities
  deep_freeze(document_format_files) if document_format_files
  deep_freeze(data_files) if data_files
  freeze
end

Instance Attribute Details

#accession_no ⇒ String (readonly)

Returns SEC accession number (e.g., “0001193125-24-123456”).

Returns:

  • SEC accession number (e.g., “0001193125-24-123456”)



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

attribute :accession_no, Types::String

#cik ⇒ String (readonly)

Returns SEC Central Index Key.

Returns:

  • SEC Central Index Key



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

attribute :cik, Types::String

#company_name ⇒ String (readonly)

Returns Company name as registered with SEC.

Returns:

  • Company name as registered with SEC



48
 
# File 'lib/sec_api/objects/stream_filing.rb', line 48

attribute :company_name, Types::String

#data_files ⇒ Array<Hash>? (readonly)

Returns XBRL and other data files.

Returns:

  • XBRL and other data files



76
 
# File 'lib/sec_api/objects/stream_filing.rb', line 76

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

#document_format_files ⇒ Array<Hash>? (readonly)

Returns Filing document files metadata.

Returns:

  • Filing document files metadata



72
 
# File 'lib/sec_api/objects/stream_filing.rb', line 72

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

#entities ⇒ Array<Hash>? (readonly)

Returns Related entities from the filing.

Returns:

  • Related entities from the filing



68
 
# File 'lib/sec_api/objects/stream_filing.rb', line 68

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

#filed_at ⇒ String (readonly)

Returns Filing timestamp in ISO 8601 format.

Returns:

  • Filing timestamp in ISO 8601 format



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

attribute :filed_at, Types::String

#form_type ⇒ String (readonly)

Returns SEC form type (e.g., “10-K”, “8-K”, “10-Q”).

Returns:

  • SEC form type (e.g., “10-K”, “8-K”, “10-Q”)



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

attribute :form_type, Types::String

#link_to_filing_details ⇒ String (readonly)

Returns URL to filing details page on sec-api.io.

Returns:

  • URL to filing details page on sec-api.io



52
 
# File 'lib/sec_api/objects/stream_filing.rb', line 52

attribute :link_to_filing_details, Types::String

#link_to_html ⇒ String? (readonly)

Returns URL to HTML version of filing.

Returns:

  • URL to HTML version of filing



60
 
# File 'lib/sec_api/objects/stream_filing.rb', line 60

attribute? :link_to_html, Types::String.optional

#link_to_txt ⇒ String? (readonly)

Returns URL to plain text version of filing.

Returns:

  • URL to plain text version of filing



56
 
# File 'lib/sec_api/objects/stream_filing.rb', line 56

attribute? :link_to_txt, Types::String.optional

#period_of_report ⇒ String? (readonly)

Returns Reporting period date (e.g., “2024-01-15”).

Returns:

  • Reporting period date (e.g., “2024-01-15”)



64
 
# File 'lib/sec_api/objects/stream_filing.rb', line 64

attribute? :period_of_report, Types::String.optional

#received_at ⇒ Time (readonly)

Returns Timestamp when this filing was received by the client. Used for calculating delivery latency from sec-api.io to client. Defaults to Time.now when filing is created.

Returns:

  • Timestamp when this filing was received by the client. Used for calculating delivery latency from sec-api.io to client. Defaults to Time.now when filing is created.



82
 
# File 'lib/sec_api/objects/stream_filing.rb', line 82

attribute :received_at, Types::Time.default { Time.now }

#ticker ⇒ String? (readonly)

Returns Stock ticker symbol (may be nil for some filers).

Returns:

  • Stock ticker symbol (may be nil for some filers)



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

attribute? :ticker, Types::String.optional

Instance Method Details

#accession_number ⇒ String

Alias for #accession_no. Returns the SEC accession number.

Provides compatibility with Filing object API naming conventions.

Returns:

  • SEC accession number (e.g., “0001193125-24-123456”)

See Also:



126
127
128
 
# File 'lib/sec_api/objects/stream_filing.rb', line 126

def accession_number
  accession_no
end

#filing_url ⇒ String?

Alias for #url. Returns the preferred filing URL.

Returns:

  • the filing URL or nil if neither available

See Also:



115
116
117
 
# File 'lib/sec_api/objects/stream_filing.rb', line 115

def filing_url
  url
end

#html_url ⇒ String?

Alias for #link_to_html. Returns URL to HTML version of filing.

Returns:

  • URL to HTML version of filing

See Also:



135
136
137
 
# File 'lib/sec_api/objects/stream_filing.rb', line 135

def html_url
  link_to_html
end

#latency_ms ⇒ Integer?

Calculate delivery latency in milliseconds.

Measures time between when the filing was published to sec-api.io (filed_at) and when it was received by the client (received_at).

Examples:

filing.latency_ms #=> 1523

Returns:

  • Latency in milliseconds, or nil if timestamps unavailable



157
158
159
160
161
162
163
164
 
# File 'lib/sec_api/objects/stream_filing.rb', line 157

def latency_ms
  return nil unless filed_at && received_at

  filed_time = Time.parse(filed_at)
  ((received_at - filed_time) * 1000).round
rescue ArgumentError
  nil  # Invalid date string
end

#latency_seconds ⇒ Float?

Calculate delivery latency in seconds.

Examples:

filing.latency_seconds #=> 1.523

Returns:

  • Latency in seconds, or nil if timestamps unavailable



172
173
174
175
 
# File 'lib/sec_api/objects/stream_filing.rb', line 172

def latency_seconds
  ms = latency_ms
  ms ? ms / 1000.0 : nil
end

#txt_url ⇒ String?

Alias for #link_to_txt. Returns URL to plain text version of filing.

Returns:

  • URL to plain text version of filing

See Also:



144
145
146
 
# File 'lib/sec_api/objects/stream_filing.rb', line 144

def txt_url
  link_to_txt
end

#url ⇒ String?

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

This convenience method provides a single access point for the filing document URL, preferring the HTML version when available.

Examples:

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

Returns:

  • the filing URL or nil if neither available



104
105
106
107
108
 
# File 'lib/sec_api/objects/stream_filing.rb', line 104

def url
  return link_to_html unless link_to_html.nil? || link_to_html.empty?
  return link_to_txt unless link_to_txt.nil? || link_to_txt.empty?
  nil
end

#within_latency_threshold?(seconds = 120) ⇒ Boolean

Check if filing was delivered within the specified latency threshold.

The default threshold of 120 seconds (2 minutes) corresponds to NFR1.

Examples:

filing.within_latency_threshold?      #=> true (if < 2 minutes)
filing.within_latency_threshold?(60)  #=> false (if > 1 minute)

Parameters:

  • (defaults to: 120)

    Maximum acceptable latency in seconds (default: 120)

Returns:

  • true if latency is within threshold, false otherwise



187
188
189
190
191
 
# File 'lib/sec_api/objects/stream_filing.rb', line 187

def within_latency_threshold?(seconds = 120)
  latency = latency_seconds
  return false if latency.nil?
  latency <= seconds
end