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.



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:

  • (String) —

    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:

  • (String) —

    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:

  • (String) —

    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:

  • (Array<Hash>, nil) —

    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:

  • (Array<Hash>, nil) —

    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:

  • (Array<Hash>, nil) —

    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:

  • (String) —

    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:

  • (String) —

    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:

  • (String) —

    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:

  • (String, nil) —

    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:

  • (String, nil) —

    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:

  • (String, nil) —

    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:

  • (Time) —

    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:

  • (String, nil) —

    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:

  • (String) —

    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:

  • (String, nil) —

    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:

  • (String, nil) —

    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:

  • (Integer, nil) —

    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:

  • (Float, nil) —

    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:

  • (String, nil) —

    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:

  • (String, nil) —

    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:

  • seconds (Numeric) (defaults to: 120) —

    Maximum acceptable latency in seconds (default: 120)

Returns:

  • (Boolean) —

    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