context.dev 2.21.0 → 2.22.0

data/rbi/context_dev/models/web_search_params.rbi

@@ -26,8 +26,8 @@ module ContextDev
       end
       attr_writer :country
 
-      # Blocklist — drop results from these domains. Example: ["pinterest.com",
-      # "reddit.com"].
+      # Blocklist — drop results from these domains. Up to 100 domains. Example:
+      # ["pinterest.com", "reddit.com"].
       sig { returns(T.nilable(T::Array[String])) }
       attr_reader :exclude_domains
 
@@ -45,8 +45,21 @@ module ContextDev
       end
       attr_writer :freshness
 
-      # Allowlist — only return results from these domains. Example: ["arxiv.org",
-      # "github.com"].
+      # Passages from each result page that are relevant to the query. Pages are read
+      # with the `markdownOptions` settings.
+      sig { returns(T.nilable(ContextDev::WebSearchParams::HighlightsOptions)) }
+      attr_reader :highlights_options
+
+      sig do
+        params(
+          highlights_options:
+            ContextDev::WebSearchParams::HighlightsOptions::OrHash
+        ).void
+      end
+      attr_writer :highlights_options
+
+      # Allowlist — only return results from these domains. Up to 100 domains. Example:
+      # ["arxiv.org", "github.com"].
       sig { returns(T.nilable(T::Array[String])) }
       attr_reader :include_domains
 
@@ -71,23 +84,21 @@ module ContextDev
       sig { params(num_results: Integer).void }
       attr_writer :num_results
 
-      # Expand the query into multiple parallel variants for broader recall.
+      # Currently has no effect.
       sig { returns(T.nilable(T::Boolean)) }
       attr_reader :query_fanout
 
       sig { params(query_fanout: T::Boolean).void }
       attr_writer :query_fanout
 
-      # Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
+      # Labels for filtering usage in the dashboard.
       sig { returns(T.nilable(T::Array[String])) }
       attr_reader :tags
 
       sig { params(tags: T::Array[String]).void }
       attr_writer :tags
 
-      # Optional request deadline and behavior on timeout. For GET requests, use
-      # timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded
-      # timeoutOpts object.
+      # Request deadline and what to return when it passes.
       sig { returns(T.nilable(ContextDev::WebSearchParams::TimeoutOpts)) }
       attr_reader :timeout_opts
 
@@ -98,11 +109,8 @@ module ContextDev
       end
       attr_writer :timeout_opts
 
-      # Set to enabled to bypass shared caches and omit request and response content
-      # from retained usage logs. Asset uploads are skipped, so hosted image URLs are
-      # omitted. Requires zero data retention to be enabled for your organization
-      # (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED.
-      # Successful ZDR responses include X-Context-ZDR: true.
+      # `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
+      # your organization has ZDR.
       sig { returns(T.nilable(ContextDev::WebSearchParams::Zdr::OrSymbol)) }
       attr_reader :zdr
 
@@ -115,6 +123,8 @@ module ContextDev
           country: ContextDev::WebSearchParams::Country::OrSymbol,
           exclude_domains: T::Array[String],
           freshness: ContextDev::WebSearchParams::Freshness::OrSymbol,
+          highlights_options:
+            ContextDev::WebSearchParams::HighlightsOptions::OrHash,
           include_domains: T::Array[String],
           markdown_options:
             ContextDev::WebSearchParams::MarkdownOptions::OrHash,
@@ -133,31 +143,29 @@ module ContextDev
         # Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific
         # country (maps to Google's `gl` parameter). Example: "us", "gb", "de".
         country: nil,
-        # Blocklist — drop results from these domains. Example: ["pinterest.com",
-        # "reddit.com"].
+        # Blocklist — drop results from these domains. Up to 100 domains. Example:
+        # ["pinterest.com", "reddit.com"].
         exclude_domains: nil,
         # Restrict results to content published within this window.
         freshness: nil,
-        # Allowlist — only return results from these domains. Example: ["arxiv.org",
-        # "github.com"].
+        # Passages from each result page that are relevant to the query. Pages are read
+        # with the `markdownOptions` settings.
+        highlights_options: nil,
+        # Allowlist — only return results from these domains. Up to 100 domains. Example:
+        # ["arxiv.org", "github.com"].
         include_domains: nil,
         # Inline Markdown scraping for each result. Set `enabled: true` to activate.
         markdown_options: nil,
         # Number of results to request and return (10–100). Defaults to 10.
         num_results: nil,
-        # Expand the query into multiple parallel variants for broader recall.
+        # Currently has no effect.
         query_fanout: nil,
-        # Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
+        # Labels for filtering usage in the dashboard.
         tags: nil,
-        # Optional request deadline and behavior on timeout. For GET requests, use
-        # timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded
-        # timeoutOpts object.
+        # Request deadline and what to return when it passes.
         timeout_opts: nil,
-        # Set to enabled to bypass shared caches and omit request and response content
-        # from retained usage logs. Asset uploads are skipped, so hosted image URLs are
-        # omitted. Requires zero data retention to be enabled for your organization
-        # (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED.
-        # Successful ZDR responses include X-Context-ZDR: true.
+        # `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
+        # your organization has ZDR.
         zdr: nil,
         request_options: {}
       )
@@ -170,6 +178,7 @@ module ContextDev
             country: ContextDev::WebSearchParams::Country::OrSymbol,
             exclude_domains: T::Array[String],
             freshness: ContextDev::WebSearchParams::Freshness::OrSymbol,
+            highlights_options: ContextDev::WebSearchParams::HighlightsOptions,
             include_domains: T::Array[String],
             markdown_options: ContextDev::WebSearchParams::MarkdownOptions,
             num_results: Integer,
@@ -480,6 +489,51 @@ module ContextDev
         end
       end
 
+      class HighlightsOptions < ContextDev::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              ContextDev::WebSearchParams::HighlightsOptions,
+              ContextDev::Internal::AnyHash
+            )
+          end
+
+        # Return relevant passages for each result. Adds 1 credit per 10 results.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :enabled
+
+        sig { params(enabled: T::Boolean).void }
+        attr_writer :enabled
+
+        # Maximum combined length of passages per result.
+        sig { returns(T.nilable(Integer)) }
+        attr_reader :max_characters
+
+        sig { params(max_characters: Integer).void }
+        attr_writer :max_characters
+
+        # Passages from each result page that are relevant to the query. Pages are read
+        # with the `markdownOptions` settings.
+        sig do
+          params(enabled: T::Boolean, max_characters: Integer).returns(
+            T.attached_class
+          )
+        end
+        def self.new(
+          # Return relevant passages for each result. Adds 1 credit per 10 results.
+          enabled: nil,
+          # Maximum combined length of passages per result.
+          max_characters: nil
+        )
+        end
+
+        sig do
+          override.returns({ enabled: T::Boolean, max_characters: Integer })
+        end
+        def to_hash
+        end
+      end
+
       class MarkdownOptions < ContextDev::Internal::Type::BaseModel
         OrHash =
           T.type_alias do
@@ -489,7 +543,7 @@ module ContextDev
             )
           end
 
-        # Scrape each result to Markdown. Off by default to keep search cheap and fast.
+        # Scrape each result to Markdown. Adds 1 credit per 10 results.
         sig { returns(T.nilable(T::Boolean)) }
         attr_reader :enabled
 
@@ -517,8 +571,10 @@ module ContextDev
         sig { params(include_links: T::Boolean).void }
         attr_writer :include_links
 
-        # Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max
-        # 30 days. Set to 0 to force a fresh scrape.
+        # Maximum cache age in milliseconds for result page content. Defaults to 180 days
+        # (15552000000 ms) when Markdown is requested, or 365 days (31536000000 ms) when
+        # only highlights are requested. Explicit values override either default. Maximum:
+        # 365 days. Set to 0 to force a fresh scrape.
         sig { returns(T.nilable(Integer)) }
         attr_reader :max_age_ms
 
@@ -545,9 +601,7 @@ module ContextDev
         sig { params(shorten_base64_images: T::Boolean).void }
         attr_writer :shorten_base64_images
 
-        # Optional request deadline and behavior on timeout. For GET requests, use
-        # timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded
-        # timeoutOpts object.
+        # Request deadline and what to return when it passes.
         sig do
           returns(
             T.nilable(ContextDev::WebSearchParams::MarkdownOptions::TimeoutOpts)
@@ -595,7 +649,7 @@ module ContextDev
           ).returns(T.attached_class)
         end
         def self.new(
-          # Scrape each result to Markdown. Off by default to keep search cheap and fast.
+          # Scrape each result to Markdown. Adds 1 credit per 10 results.
           enabled: nil,
           # Render iframe contents into the Markdown.
           include_frames: nil,
@@ -603,16 +657,16 @@ module ContextDev
           include_images: nil,
           # Keep hyperlinks in the Markdown.
           include_links: nil,
-          # Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max
-          # 30 days. Set to 0 to force a fresh scrape.
+          # Maximum cache age in milliseconds for result page content. Defaults to 180 days
+          # (15552000000 ms) when Markdown is requested, or 365 days (31536000000 ms) when
+          # only highlights are requested. Explicit values override either default. Maximum:
+          # 365 days. Set to 0 to force a fresh scrape.
           max_age_ms: nil,
           # PDF handling. Use start/end to bound text extraction and OCR to a page range.
           pdf: nil,
           # Truncate inline base64 image payloads to keep responses small.
           shorten_base64_images: nil,
-          # Optional request deadline and behavior on timeout. For GET requests, use
-          # timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded
-          # timeoutOpts object.
+          # Request deadline and what to return when it passes.
           timeout_opts: nil,
           # Strip nav, header, footer, and sidebar — keep only the primary article content.
           use_main_content_only: nil,
@@ -710,15 +764,12 @@ module ContextDev
               )
             end
 
-          # Request deadline in milliseconds. Maximum: 300000 (5 minutes).
+          # Deadline in milliseconds.
           sig { returns(Integer) }
           attr_accessor :milliseconds
 
-          # What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging
-          # credits. "return-partial" returns usable results collected so far; if none are
-          # available, the request still fails without charging credits. Partial results are
-          # not cached as complete results. "return-partial" requires milliseconds of at
-          # least 5000.
+          # "fail" returns 408 at the deadline. "return-partial" returns available results;
+          # inspect the response’s partial flag. "return-partial" requires at least 5000 ms.
           sig do
             returns(
               T.nilable(
@@ -736,9 +787,7 @@ module ContextDev
           end
           attr_writer :behavior
 
-          # Optional request deadline and behavior on timeout. For GET requests, use
-          # timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded
-          # timeoutOpts object.
+          # Request deadline and what to return when it passes.
           sig do
             params(
               milliseconds: Integer,
@@ -747,13 +796,10 @@ module ContextDev
             ).returns(T.attached_class)
           end
           def self.new(
-            # Request deadline in milliseconds. Maximum: 300000 (5 minutes).
+            # Deadline in milliseconds.
             milliseconds:,
-            # What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging
-            # credits. "return-partial" returns usable results collected so far; if none are
-            # available, the request still fails without charging credits. Partial results are
-            # not cached as complete results. "return-partial" requires milliseconds of at
-            # least 5000.
+            # "fail" returns 408 at the deadline. "return-partial" returns available results;
+            # inspect the response’s partial flag. "return-partial" requires at least 5000 ms.
             behavior: nil
           )
           end
@@ -770,11 +816,8 @@ module ContextDev
           def to_hash
           end
 
-          # What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging
-          # credits. "return-partial" returns usable results collected so far; if none are
-          # available, the request still fails without charging credits. Partial results are
-          # not cached as complete results. "return-partial" requires milliseconds of at
-          # least 5000.
+          # "fail" returns 408 at the deadline. "return-partial" returns available results;
+          # inspect the response’s partial flag. "return-partial" requires at least 5000 ms.
           module Behavior
             extend ContextDev::Internal::Type::Enum
 
@@ -820,14 +863,12 @@ module ContextDev
             )
           end
 
-        # Request deadline in milliseconds. Maximum: 300000 (5 minutes).
+        # Deadline in milliseconds.
         sig { returns(Integer) }
         attr_accessor :milliseconds
 
-        # What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging
-        # credits. "return-partial" returns usable results collected so far; if none are
-        # available, the request still fails without charging credits. Partial results are
-        # not cached as complete results.
+        # "fail" returns 408 at the deadline. "return-partial" returns available results;
+        # inspect the response’s partial flag.
         sig do
           returns(
             T.nilable(
@@ -845,9 +886,7 @@ module ContextDev
         end
         attr_writer :behavior
 
-        # Optional request deadline and behavior on timeout. For GET requests, use
-        # timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded
-        # timeoutOpts object.
+        # Request deadline and what to return when it passes.
         sig do
           params(
             milliseconds: Integer,
@@ -856,12 +895,10 @@ module ContextDev
           ).returns(T.attached_class)
         end
         def self.new(
-          # Request deadline in milliseconds. Maximum: 300000 (5 minutes).
+          # Deadline in milliseconds.
           milliseconds:,
-          # What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging
-          # credits. "return-partial" returns usable results collected so far; if none are
-          # available, the request still fails without charging credits. Partial results are
-          # not cached as complete results.
+          # "fail" returns 408 at the deadline. "return-partial" returns available results;
+          # inspect the response’s partial flag.
           behavior: nil
         )
         end
@@ -878,10 +915,8 @@ module ContextDev
         def to_hash
         end
 
-        # What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging
-        # credits. "return-partial" returns usable results collected so far; if none are
-        # available, the request still fails without charging credits. Partial results are
-        # not cached as complete results.
+        # "fail" returns 408 at the deadline. "return-partial" returns available results;
+        # inspect the response’s partial flag.
         module Behavior
           extend ContextDev::Internal::Type::Enum
 
@@ -914,11 +949,8 @@ module ContextDev
         end
       end
 
-      # Set to enabled to bypass shared caches and omit request and response content
-      # from retained usage logs. Asset uploads are skipped, so hosted image URLs are
-      # omitted. Requires zero data retention to be enabled for your organization
-      # (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED.
-      # Successful ZDR responses include X-Context-ZDR: true.
+      # `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
+      # your organization has ZDR.
       module Zdr
         extend ContextDev::Internal::Type::Enum
 

data/rbi/context_dev/models/web_search_response.rbi

@@ -11,9 +11,7 @@ module ContextDev
           )
         end
 
-      # Cache outcome for this response. Composite responses are hits only when every
-      # cache-controlled fetch contributing to the output was a hit; age_ms is the
-      # oldest contributing hit.
+      # Whether this response came from cache.
       sig { returns(ContextDev::Models::WebSearchResponse::CacheMetadata) }
       attr_reader :cache_metadata
 
@@ -29,15 +27,15 @@ module ContextDev
       sig { returns(String) }
       attr_accessor :query
 
-      # Unique id of this API call, also sent in the X-Request-Id response header. Quote
-      # it when contacting support about a failed request.
+      # Unique ID of this request, also in `X-Request-Id`. Include it when contacting
+      # support.
       sig { returns(String) }
       attr_accessor :request_id
 
       sig { returns(T::Array[ContextDev::Models::WebSearchResponse::Result]) }
       attr_accessor :results
 
-      # Credit usage, included whenever a valid API key is provided.
+      # Credits this request used and your remaining balance.
       sig do
         returns(T.nilable(ContextDev::Models::WebSearchResponse::KeyMetadata))
       end
@@ -74,17 +72,15 @@ module ContextDev
         ).returns(T.attached_class)
       end
       def self.new(
-        # Cache outcome for this response. Composite responses are hits only when every
-        # cache-controlled fetch contributing to the output was a hit; age_ms is the
-        # oldest contributing hit.
+        # Whether this response came from cache.
         cache_metadata:,
         # Echo of the original query (useful when fanout was enabled).
         query:,
-        # Unique id of this API call, also sent in the X-Request-Id response header. Quote
-        # it when contacting support about a failed request.
+        # Unique ID of this request, also in `X-Request-Id`. Include it when contacting
+        # support.
         request_id:,
         results:,
-        # Credit usage, included whenever a valid API key is provided.
+        # Credits this request used and your remaining balance.
         key_metadata: nil,
         # True when timeoutOpts.behavior=return-partial returned the usable results
         # collected before the deadline. Partial collections are not cached as complete
@@ -131,9 +127,7 @@ module ContextDev
         end
         attr_accessor :status
 
-        # Cache outcome for this response. Composite responses are hits only when every
-        # cache-controlled fetch contributing to the output was a hit; age_ms is the
-        # oldest contributing hit.
+        # Whether this response came from cache.
         sig do
           params(
             age_ms: Integer,
@@ -218,6 +212,20 @@ module ContextDev
         sig { returns(String) }
         attr_accessor :description
 
+        # Highlights status and passages for this result.
+        sig do
+          returns(ContextDev::Models::WebSearchResponse::Result::Highlights)
+        end
+        attr_reader :highlights
+
+        sig do
+          params(
+            highlights:
+              ContextDev::Models::WebSearchResponse::Result::Highlights::OrHash
+          ).void
+        end
+        attr_writer :highlights
+
         # Markdown scrape status and content for this result.
         sig { returns(ContextDev::Models::WebSearchResponse::Result::Markdown) }
         attr_reader :markdown
@@ -249,6 +257,8 @@ module ContextDev
         sig do
           params(
             description: String,
+            highlights:
+              ContextDev::Models::WebSearchResponse::Result::Highlights::OrHash,
             markdown:
               ContextDev::Models::WebSearchResponse::Result::Markdown::OrHash,
             relevance:
@@ -261,6 +271,8 @@ module ContextDev
           # Snippet excerpt from the page. Empty string when the search provider does not
           # supply a snippet.
           description:,
+          # Highlights status and passages for this result.
+          highlights:,
           # Markdown scrape status and content for this result.
           markdown:,
           # Relevance to the original query.
@@ -276,6 +288,8 @@ module ContextDev
           override.returns(
             {
               description: String,
+              highlights:
+                ContextDev::Models::WebSearchResponse::Result::Highlights,
               markdown: ContextDev::Models::WebSearchResponse::Result::Markdown,
               relevance:
                 ContextDev::Models::WebSearchResponse::Result::Relevance::TaggedSymbol,
@@ -287,6 +301,113 @@ module ContextDev
         def to_hash
         end
 
+        class Highlights < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::Models::WebSearchResponse::Result::Highlights,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          # Per-result highlights outcome. Inspect this before reading `highlights`.
+          sig do
+            returns(
+              ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol
+            )
+          end
+          attr_accessor :code
+
+          # Passages relevant to the query, in page order. Null unless
+          # highlightsOptions.enabled is true and the page was read.
+          sig { returns(T.nilable(T::Array[String])) }
+          attr_accessor :highlights
+
+          # Highlights status and passages for this result.
+          sig do
+            params(
+              code:
+                ContextDev::Models::WebSearchResponse::Result::Highlights::Code::OrSymbol,
+              highlights: T.nilable(T::Array[String])
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Per-result highlights outcome. Inspect this before reading `highlights`.
+            code:,
+            # Passages relevant to the query, in page order. Null unless
+            # highlightsOptions.enabled is true and the page was read.
+            highlights:
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                code:
+                  ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol,
+                highlights: T.nilable(T::Array[String])
+              }
+            )
+          end
+          def to_hash
+          end
+
+          # Per-result highlights outcome. Inspect this before reading `highlights`.
+          module Code
+            extend ContextDev::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  ContextDev::Models::WebSearchResponse::Result::Highlights::Code
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            SUCCESS =
+              T.let(
+                :SUCCESS,
+                ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol
+              )
+            NOT_REQUESTED =
+              T.let(
+                :NOT_REQUESTED,
+                ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol
+              )
+            TIMEOUT =
+              T.let(
+                :TIMEOUT,
+                ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol
+              )
+            CONTENT_TOO_LARGE =
+              T.let(
+                :CONTENT_TOO_LARGE,
+                ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol
+              )
+            WEBSITE_ACCESS_ERROR =
+              T.let(
+                :WEBSITE_ACCESS_ERROR,
+                ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol
+              )
+            ERROR =
+              T.let(
+                :ERROR,
+                ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  ContextDev::Models::WebSearchResponse::Result::Highlights::Code::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+        end
+
         class Markdown < ContextDev::Internal::Type::BaseModel
           OrHash =
             T.type_alias do
@@ -309,11 +430,8 @@ module ContextDev
           sig { returns(T.nilable(String)) }
           attr_accessor :markdown
 
-          # How complete the returned content is. `loaded` means the page finished the waits
-          # the request asked for. `still-loading` only occurs with
-          # timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was
-          # reached first, so the content reflects the DOM at that moment and late-rendering
-          # parts may be missing. Partial results are billed at the base request cost.
+          # `loaded`, or `still-loading` when capture ended before the page finished
+          # loading.
           sig do
             returns(
               T.nilable(
@@ -347,11 +465,8 @@ module ContextDev
             # GFM Markdown of the page. Null unless markdownOptions.enabled is true and
             # scraping succeeded.
             markdown:,
-            # How complete the returned content is. `loaded` means the page finished the waits
-            # the request asked for. `still-loading` only occurs with
-            # timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was
-            # reached first, so the content reflects the DOM at that moment and late-rendering
-            # parts may be missing. Partial results are billed at the base request cost.
+            # `loaded`, or `still-loading` when capture ended before the page finished
+            # loading.
             final_dom_state: nil
           )
           end
@@ -425,11 +540,8 @@ module ContextDev
             end
           end
 
-          # How complete the returned content is. `loaded` means the page finished the waits
-          # the request asked for. `still-loading` only occurs with
-          # timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was
-          # reached first, so the content reflects the DOM at that moment and late-rendering
-          # parts may be missing. Partial results are billed at the base request cost.
+          # `loaded`, or `still-loading` when capture ended before the page finished
+          # loading.
           module FinalDomState
             extend ContextDev::Internal::Type::Enum
 
@@ -515,7 +627,7 @@ module ContextDev
             )
           end
 
-        # Credits used by this request.
+        # Credits charged for this request.
         sig { returns(Integer) }
         attr_accessor :credits_consumed
 
@@ -523,14 +635,14 @@ module ContextDev
         sig { returns(Integer) }
         attr_accessor :credits_remaining
 
-        # Credit usage, included whenever a valid API key is provided.
+        # Credits this request used and your remaining balance.
         sig do
           params(credits_consumed: Integer, credits_remaining: Integer).returns(
             T.attached_class
           )
         end
         def self.new(
-          # Credits used by this request.
+          # Credits charged for this request.
           credits_consumed:,
           # Credits remaining for your organization.
           credits_remaining: