sec_api 1.0.0

data/lib/sec_api/errors/error.rb

@@ -0,0 +1,75 @@
+module SecApi
+  # Error Taxonomy (Architecture ADR-2: Error Handling Strategy)
+  #
+  # SecApi uses a type-based retry taxonomy to distinguish retryable from non-retryable failures:
+  #
+  #   SecApi::Error (base)
+  #   ├── TransientError (retryable) - Network issues, server errors, rate limits
+  #   │   ├── NetworkError    - Timeouts, connection failures, SSL errors
+  #   │   ├── ServerError     - HTTP 5xx responses
+  #   │   └── RateLimitError  - HTTP 429 responses
+  #   └── PermanentError (fail-fast) - Client errors that require code/config changes
+  #       ├── AuthenticationError - HTTP 401, 403
+  #       ├── NotFoundError       - HTTP 404
+  #       └── ValidationError     - HTTP 400, 422, XBRL validation
+  #
+  # Design rationale: The retry middleware checks `error.is_a?(TransientError)` to determine
+  # retry eligibility. This enables automatic recovery for temporary issues (NFR5: 95%+ recovery)
+  # while failing fast on permanent errors to avoid wasting resources.
+  #
+  # Base error class for all sec_api errors.
+  #
+  # All errors include a request_id for correlation with logs and
+  # instrumentation callbacks. When request_id is present, error messages
+  # are automatically prefixed with `[request_id]` for easy log correlation.
+  #
+  # @example Accessing request_id from error
+  #   begin
+  #     client.query.ticker("AAPL").search
+  #   rescue SecApi::Error => e
+  #     logger.error("Request failed", request_id: e.request_id, error: e.message)
+  #     Bugsnag.notify(e, request_id: e.request_id)
+  #   end
+  #
+  # @example Error message format with request_id
+  #   # When request_id is present:
+  #   # => "[abc123-def456] Rate limit exceeded (429 Too Many Requests)."
+  #   #
+  #   # When request_id is nil or empty:
+  #   # => "Rate limit exceeded (429 Too Many Requests)."
+  #
+  # @example Correlating with distributed tracing
+  #   begin
+  #     client.query.ticker("AAPL").search
+  #   rescue SecApi::Error => e
+  #     # The request_id matches the trace ID from your APM system
+  #     # if you configured external request_id via custom middleware
+  #     Datadog.tracer.active_span&.set_tag('sec_api.request_id', e.request_id)
+  #   end
+  #
+  class Error < StandardError
+    # The unique request correlation ID for this error.
+    # @return [String, nil] UUID request ID, or nil if not available
+    attr_reader :request_id
+
+    # Creates a new error with optional request correlation ID.
+    #
+    # @param message [String] Error message
+    # @param request_id [String, nil] Request correlation ID for tracing
+    def initialize(message = nil, request_id: nil)
+      @request_id = request_id
+      super(build_message(message))
+    end
+
+    private
+
+    # Builds the error message, optionally prefixing with request_id.
+    #
+    # @param message [String, nil] Original error message
+    # @return [String, nil] Formatted message with request_id prefix if present
+    def build_message(message)
+      return message if @request_id.nil? || @request_id.to_s.empty?
+      "[#{@request_id}] #{message}"
+    end
+  end
+end

data/lib/sec_api/errors/network_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Raised when network connectivity issues occur (timeouts, connection failures).
+  #
+  # Why TransientError? Network issues are inherently temporary - a brief blip,
+  # overloaded router, or momentary DNS failure. The request is valid; the network
+  # path is temporarily broken. High probability of success on retry.
+  #
+  # Wrapped Faraday exceptions: TimeoutError, ConnectionFailed, SSLError.
+  #
+  # This is a transient error - the retry middleware will automatically
+  # retry the request. Network errors represent temporary connectivity issues
+  # that may resolve on subsequent attempts.
+  #
+  # @example Handling network errors
+  #   begin
+  #     client.query.ticker("AAPL").search
+  #   rescue SecApi::NetworkError => e
+  #     # Retries exhausted - persistent connectivity issue
+  #     logger.error("Network error: #{e.message}")
+  #     check_network_status
+  #   end
+  class NetworkError < TransientError
+  end
+end

data/lib/sec_api/errors/not_found_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Raised when a requested resource is not found (404 Not Found).
+  #
+  # Why PermanentError? The resource genuinely doesn't exist - invalid ticker,
+  # nonexistent CIK, or filing not in database. Retrying won't create it.
+  # User needs to fix their query parameters or check that the resource exists.
+  #
+  # This is a permanent error - the requested ticker, CIK, or filing does not exist.
+  # Retrying won't help; the query parameters need to be corrected.
+  #
+  # @example Handling not found errors
+  #   begin
+  #     client.query.ticker("INVALID").search
+  #   rescue SecApi::NotFoundError => e
+  #     # Correct the ticker symbol or filing identifier
+  #     logger.warn("Resource not found: #{e.message}")
+  #     prompt_user_for_valid_ticker
+  #   end
+  class NotFoundError < PermanentError
+  end
+end

data/lib/sec_api/errors/pagination_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Raised when a pagination operation cannot be completed.
+  #
+  # This error is raised when attempting to fetch the next page of results
+  # when no more pages are available. It inherits from PermanentError because
+  # retrying the operation will not resolve the issue.
+  #
+  # @example Handling pagination end
+  #   begin
+  #     next_page = filings.fetch_next_page
+  #   rescue SecApi::PaginationError => e
+  #     puts "No more pages available"
+  #   end
+  #
+  # @example Checking before fetching
+  #   if filings.has_more?
+  #     next_page = filings.fetch_next_page
+  #   else
+  #     puts "Already on the last page"
+  #   end
+  #
+  # @see SecApi::Collections::Filings#fetch_next_page
+  # @see SecApi::Collections::Filings#has_more?
+  class PaginationError < PermanentError
+  end
+end

data/lib/sec_api/errors/permanent_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Base class for all non-retryable (permanent) errors.
+  #
+  # Design rationale: PermanentError signals the retry middleware to fail immediately
+  # without retrying. Retrying a 401 (bad API key) or 404 (nonexistent resource) wastes
+  # resources and delays the inevitable failure. Fail fast with a clear message instead.
+  #
+  # These errors require human intervention - code changes, configuration fixes,
+  # or different input parameters. The same request will always fail.
+  #
+  # Permanent errors represent failures that won't be resolved by retrying,
+  # such as authentication failures, validation errors, or resource not found.
+  # These errors require code or configuration changes to resolve.
+  #
+  # @example Catching all permanent errors
+  #   begin
+  #     client.query.ticker("INVALID").search
+  #   rescue SecApi::PermanentError => e
+  #     # No retry will help - requires action
+  #     logger.error("Permanent failure: #{e.message}")
+  #     notify_developer(e)
+  #   end
+  #
+  # @see TransientError for retryable errors
+  class PermanentError < Error
+  end
+end

data/lib/sec_api/errors/rate_limit_error.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Raised when sec-api.io rate limit is exceeded (429 Too Many Requests).
+  #
+  # Why TransientError? Rate limits reset after a time window (typically 60s).
+  # The request is valid - we just hit a temporary capacity limit. Worth waiting
+  # and retrying automatically rather than failing to the user. (FR5.4: auto-resume)
+  #
+  # This is a transient error - the retry middleware will automatically
+  # retry the request after waiting for the rate limit to reset.
+  #
+  # The error includes retry context when available from response headers:
+  # - {#retry_after}: Duration to wait (from Retry-After header)
+  # - {#reset_at}: Timestamp when rate limit resets (from X-RateLimit-Reset header)
+  #
+  # @example Handling rate limits
+  #   begin
+  #     client.query.ticker("AAPL").search
+  #   rescue SecApi::RateLimitError => e
+  #     # Retries exhausted - rate limit hit repeatedly
+  #     logger.warn("Rate limit exceeded: #{e.message}")
+  #     if e.retry_after
+  #       logger.info("Server suggests waiting #{e.retry_after} seconds")
+  #     end
+  #     notify_ops_team(e)
+  #   end
+  #
+  # @example Checking reset time
+  #   rescue SecApi::RateLimitError => e
+  #     if e.reset_at
+  #       wait_time = e.reset_at - Time.now
+  #       sleep(wait_time) if wait_time.positive?
+  #     end
+  #
+  class RateLimitError < TransientError
+    # Duration in seconds to wait before retrying (from Retry-After header).
+    # @return [Integer, nil] Seconds to wait, or nil if header was not present
+    attr_reader :retry_after
+
+    # Timestamp when the rate limit window resets (from X-RateLimit-Reset header).
+    # @return [Time, nil] Reset time, or nil if header was not present
+    attr_reader :reset_at
+
+    # Creates a new RateLimitError with optional retry context.
+    #
+    # @param message [String] Error message describing the rate limit
+    # @param retry_after [Integer, nil] Seconds to wait (from Retry-After header)
+    # @param reset_at [Time, nil] Timestamp when rate limit resets (from X-RateLimit-Reset header)
+    # @param request_id [String, nil] Request correlation ID for tracing
+    def initialize(message, retry_after: nil, reset_at: nil, request_id: nil)
+      super(message, request_id: request_id)
+      @retry_after = retry_after
+      @reset_at = reset_at
+    end
+  end
+end

data/lib/sec_api/errors/reconnection_error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Raised when WebSocket reconnection fails after maximum attempts.
+  #
+  # This is a TransientError (the underlying cause was likely temporary)
+  # but after exhausting retries, we give up and surface to the caller.
+  #
+  # @example Handling reconnection failure
+  #   begin
+  #     client.stream.subscribe { |f| process(f) }
+  #   rescue SecApi::ReconnectionError => e
+  #     logger.error("Stream failed permanently", attempts: e.attempts)
+  #     # Fallback to polling via Query API
+  #   end
+  #
+  class ReconnectionError < NetworkError
+    # @return [Integer] Number of reconnection attempts made
+    attr_reader :attempts
+
+    # @return [Float] Total downtime in seconds
+    attr_reader :downtime_seconds
+
+    # @param message [String] Error message
+    # @param attempts [Integer] Number of reconnection attempts made
+    # @param downtime_seconds [Float] Total downtime in seconds
+    # @param request_id [String, nil] Request correlation ID (optional, WebSocket context may not have one)
+    def initialize(message:, attempts:, downtime_seconds:, request_id: nil)
+      @attempts = attempts
+      @downtime_seconds = downtime_seconds
+      super(message, request_id: request_id)
+    end
+  end
+end

data/lib/sec_api/errors/server_error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Raised when sec-api.io returns a server error (5xx status code).
+  #
+  # Why TransientError? Server errors (500, 502, 503, 504) typically indicate
+  # temporary infrastructure issues - service restart, brief overload, upstream
+  # timeout. The request is valid; the server is temporarily unhealthy. Worth
+  # retrying with exponential backoff.
+  #
+  # This is a transient error - the retry middleware will automatically
+  # retry the request. Server errors typically indicate temporary issues
+  # with the sec-api.io infrastructure.
+  #
+  # @example Handling server errors
+  #   begin
+  #     client.query.ticker("AAPL").search
+  #   rescue SecApi::ServerError => e
+  #     # Retries exhausted - persistent server issue
+  #     logger.error("Server error: #{e.message}")
+  #     alert_on_call_team(e)
+  #   end
+  class ServerError < TransientError
+  end
+end

data/lib/sec_api/errors/transient_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Base class for all retryable (transient) errors.
+  #
+  # Design rationale: TransientError signals the retry middleware that this failure is worth
+  # retrying because the underlying issue may resolve (network blip, brief overload, rate limit
+  # window reset). This supports NFR5 (95%+ automatic recovery from transient failures).
+  #
+  # Retry behavior: The retry middleware uses `error.is_a?(TransientError)` to decide
+  # retry eligibility. Subclasses inherit retry eligibility automatically.
+  #
+  # Transient errors represent temporary failures that may succeed if retried,
+  # such as network timeouts, rate limiting, or temporary server issues.
+  # The retry middleware automatically retries operations that raise TransientError.
+  #
+  # @example Catching all transient errors
+  #   begin
+  #     client.query.ticker("AAPL").search
+  #   rescue SecApi::TransientError => e
+  #     # Auto-retry already attempted (5 times by default)
+  #     logger.error("Operation failed after retries: #{e.message}")
+  #   end
+  #
+  # @see PermanentError for non-retryable errors
+  class TransientError < Error
+  end
+end

data/lib/sec_api/errors/validation_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Raised when request validation fails (400, 422) or XBRL data integrity issues are detected.
+  #
+  # Why PermanentError? The client sent invalid data - malformed query, invalid
+  # parameters, bad date format. This is a programming error or bad input that
+  # won't fix itself. Also raised for XBRL data that fails heuristic validation.
+  #
+  # This is a permanent error - indicates malformed or incomplete filing data.
+  # Retrying won't help; the filing data itself has issues that require investigation.
+  #
+  # @example Handling validation errors
+  #   begin
+  #     xbrl_data = client.xbrl_to_json(accession_no: "0001234567-21-000001")
+  #   rescue SecApi::ValidationError => e
+  #     # Report data quality issue
+  #     logger.error("XBRL validation failed: #{e.message}")
+  #     report_data_quality_issue(e)
+  #   end
+  class ValidationError < PermanentError
+  end
+end

data/lib/sec_api/extractor.rb

@@ -0,0 +1,122 @@
+module SecApi
+  # Extractor proxy for document extraction endpoints
+  #
+  # All extractor methods return immutable ExtractedData objects (not raw hashes).
+  # This ensures thread safety and a consistent API surface.
+  #
+  # @example Extract text from filing
+  #   extracted = client.extractor.extract(filing_url)
+  #   extracted.text              # => "Full extracted text..."
+  #   extracted.sections          # => { risk_factors: "...", financials: "..." }
+  #   extracted.metadata          # => { source_url: "...", form_type: "10-K" }
+  #
+  # @example Extract specific sections
+  #   extracted = client.extractor.extract(filing_url, sections: [:risk_factors, :mda])
+  #   extracted.risk_factors      # => "Risk factor content..."
+  #   extracted.mda               # => "MD&A content..."
+  class Extractor
+    # Maps Ruby symbols to SEC item identifiers for 10-K filings
+    # @api private
+    SECTION_MAP = {
+      risk_factors: "1A",
+      business: "1",
+      mda: "7",
+      financials: "8",
+      legal_proceedings: "3",
+      properties: "2",
+      market_risk: "7A"
+    }.freeze
+
+    # Creates a new Extractor proxy instance.
+    #
+    # Extractor instances are obtained via {Client#extractor} and cached
+    # for reuse. Direct instantiation is not recommended.
+    #
+    # @param client [SecApi::Client] The parent client for API access
+    # @return [SecApi::Extractor] A new extractor proxy instance
+    # @api private
+    def initialize(client)
+      @_client = client
+    end
+
+    # Extract text and sections from SEC filing
+    #
+    # @param filing [String, Filing] The filing URL string or Filing object
+    # @param sections [Array<Symbol>, nil] Specific sections to extract (e.g., [:risk_factors, :mda])
+    #   When nil or omitted, extracts the full filing text.
+    #   Supported sections: :risk_factors, :business, :mda, :financials, :legal_proceedings, :properties, :market_risk
+    # @param options [Hash] Additional extraction options passed to the API
+    # @return [ExtractedData] Immutable extracted data object
+    # @raise [AuthenticationError] when API key is invalid
+    # @raise [NotFoundError] when filing URL is not found
+    # @raise [NetworkError] when connection fails
+    # @note When extracting multiple sections, one API call is made per section.
+    #   This may impact latency and API usage costs for large section lists.
+    #
+    # @example Extract full filing
+    #   extracted = client.extractor.extract(filing_url)
+    #   extracted.text  # => "Full filing text..."
+    #
+    # @example Extract specific section (dynamic accessor)
+    #   extracted = client.extractor.extract(filing_url, sections: [:risk_factors])
+    #   extracted.risk_factors  # => "Risk factors content..."
+    #
+    # @example Extract multiple sections (dynamic accessors)
+    #   extracted = client.extractor.extract(filing_url, sections: [:risk_factors, :mda])
+    #   extracted.risk_factors  # => "Risk factors..."
+    #   extracted.mda           # => "MD&A analysis..."
+    def extract(filing, sections: nil, **options)
+      url = filing.is_a?(String) ? filing : filing.url
+
+      if sections.nil? || sections.empty?
+        # Default behavior - extract full filing
+        response = @_client.connection.post("/extractor", {url: url}.merge(options))
+        ExtractedData.from_api(response.body)
+      else
+        # Extract specified sections
+        section_contents = extract_sections(url, Array(sections), options)
+        ExtractedData.from_api({sections: section_contents})
+      end
+    end
+
+    private
+
+    # Extract multiple sections by making individual API calls
+    #
+    # @param url [String] The filing URL
+    # @param sections [Array<Symbol>] List of sections to extract
+    # @param options [Hash] Additional options
+    # @return [Hash{Symbol => String}] Hash of section names to content
+    def extract_sections(url, sections, options)
+      sections.each_with_object({}) do |section, hash|
+        item_id = SECTION_MAP[section.to_sym] || section.to_s
+        response = @_client.connection.post("/extractor", {
+          url: url,
+          item: item_id
+        }.merge(options))
+
+        # API returns sections hash or text directly
+        content = extract_section_content(response.body, section)
+        hash[section.to_sym] = content if content
+      end
+    end
+
+    # Extract section content from API response
+    #
+    # @param body [Hash, String] The API response body
+    # @param section [Symbol] The requested section name
+    # @return [String, nil] The section content
+    def extract_section_content(body, section)
+      return body if body.is_a?(String)
+      return nil unless body.is_a?(Hash)
+
+      # Try sections hash first, then fall back to text
+      sections = body[:sections] || body["sections"]
+      if sections
+        sections[section.to_sym] || sections[section.to_s]
+      else
+        body[:text] || body["text"]
+      end
+    end
+  end
+end