context.dev 2.20.0 → 2.21.0

data/rbi/context_dev/models/web_scrape_response.rbi

@@ -35,9 +35,9 @@ module ContextDev
       end
       attr_writer :cache_metadata
 
-      # Plain-text passages relevant to highlightsParams.query, in page order, each
-      # prefixed with its section heading in square brackets. Empty when the page has no
-      # text.
+      # Relevant Markdown excerpts for your question or topic, in page order. Headings
+      # in square brackets supply necessary context; ellipses mark omitted portions.
+      # Empty when the page has no text.
       sig { returns(ContextDev::Models::WebScrapeResponse::Highlights) }
       attr_reader :highlights
 
@@ -68,10 +68,7 @@ module ContextDev
       end
       attr_writer :images
 
-      # Page data extracted into jsonParams.schema, after shared content filters. Values
-      # are grounded in the page; optional fields the page does not state are omitted,
-      # or null when their type allows null. An empty object when the filters leave no
-      # text.
+      # Page data extracted using your schema.
       sig { returns(ContextDev::Models::WebScrapeResponse::Json) }
       attr_reader :json
 
@@ -113,7 +110,7 @@ module ContextDev
       end
       attr_writer :parsed
 
-      # Product detail page classification and the extracted product.
+      # Product details found on the page.
       sig { returns(ContextDev::Models::WebScrapeResponse::Product) }
       attr_reader :product
 
@@ -144,10 +141,11 @@ module ContextDev
       sig { returns(String) }
       attr_accessor :url
 
-      # Present when return-partial captures a page that is still loading, returns
-      # images before image processing finishes, or cuts product AI extraction short.
-      # Also present if the optional product AI fallback fails. Partial responses are
-      # not cached.
+      # Present when at least one requested output succeeds while another fails, or when
+      # successful outputs come from a page that is still loading or images returned
+      # before processing finished. Absent when every requested output fails. Check each
+      # output's success field for its result. Valid captured pieces may be cached
+      # independently; failed retrievals and incomplete captures are not cached.
       sig do
         returns(
           T.nilable(
@@ -209,18 +207,15 @@ module ContextDev
         # cache-controlled fetch contributing to the output was a hit; age_ms is the
         # oldest contributing hit.
         cache_metadata:,
-        # Plain-text passages relevant to highlightsParams.query, in page order, each
-        # prefixed with its section heading in square brackets. Empty when the page has no
-        # text.
+        # Relevant Markdown excerpts for your question or topic, in page order. Headings
+        # in square brackets supply necessary context; ellipses mark omitted portions.
+        # Empty when the page has no text.
         highlights:,
         # Rendered HTML after content filters.
         html:,
         # Images after content filters. Empty when none are found.
         images:,
-        # Page data extracted into jsonParams.schema, after shared content filters. Values
-        # are grounded in the page; optional fields the page does not state are omitted,
-        # or null when their type allows null. An empty object when the filters leave no
-        # text.
+        # Page data extracted using your schema.
         json:,
         # Markdown after content filters.
         markdown:,
@@ -228,7 +223,7 @@ module ContextDev
         metadata:,
         # Fields produced by parseParams.rules, after shared content filters.
         parsed:,
-        # Product detail page classification and the extracted product.
+        # Product details found on the page.
         product:,
         # Unique id of this API call, also sent in the X-Request-Id response header. Quote
         # it when contacting support about a failed request.
@@ -237,10 +232,11 @@ module ContextDev
         screenshot:,
         # Final URL after redirects and browser actions.
         url:,
-        # Present when return-partial captures a page that is still loading, returns
-        # images before image processing finishes, or cuts product AI extraction short.
-        # Also present if the optional product AI fallback fails. Partial responses are
-        # not cached.
+        # Present when at least one requested output succeeds while another fails, or when
+        # successful outputs come from a page that is still loading or images returned
+        # before processing finished. Absent when every requested output fails. Check each
+        # output's success field for its result. Valid captured pieces may be cached
+        # independently; failed retrievals and incomplete captures are not cached.
         is_partial: nil,
         # Credit usage, included whenever a valid API key is provided.
         key_metadata: nil
@@ -300,6 +296,10 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
         # Original HTTP response body. Waiting, actions, and content filters never change
         # it.
         sig do
@@ -308,10 +308,16 @@ module ContextDev
               T.nilable(
                 ContextDev::Models::WebScrapeResponse::Bytes::Data::OrHash
               ),
-            requested: T::Boolean
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
           ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
@@ -319,7 +325,8 @@ module ContextDev
             {
               data:
                 T.nilable(ContextDev::Models::WebScrapeResponse::Bytes::Data),
-              requested: T::Boolean
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
             }
           )
         end
@@ -472,21 +479,35 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
-        # Plain-text passages relevant to highlightsParams.query, in page order, each
-        # prefixed with its section heading in square brackets. Empty when the page has no
-        # text.
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
+        # Relevant Markdown excerpts for your question or topic, in page order. Headings
+        # in square brackets supply necessary context; ellipses mark omitted portions.
+        # Empty when the page has no text.
         sig do
           params(
             data: T.nilable(T::Array[String]),
-            requested: T::Boolean
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
           ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
           override.returns(
-            { data: T.nilable(T::Array[String]), requested: T::Boolean }
+            {
+              data: T.nilable(T::Array[String]),
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
+            }
           )
         end
         def to_hash
@@ -508,17 +529,34 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
         # Rendered HTML after content filters.
         sig do
-          params(data: T.nilable(String), requested: T::Boolean).returns(
-            T.attached_class
-          )
+          params(
+            data: T.nilable(String),
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
+          ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
-          override.returns({ data: T.nilable(String), requested: T::Boolean })
+          override.returns(
+            {
+              data: T.nilable(String),
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
+            }
+          )
         end
         def to_hash
         end
@@ -545,6 +583,10 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
         # Images after content filters. Empty when none are found.
         sig do
           params(
@@ -554,10 +596,16 @@ module ContextDev
                   ContextDev::Models::WebScrapeResponse::Images::Data::OrHash
                 ]
               ),
-            requested: T::Boolean
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
           ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
@@ -567,7 +615,8 @@ module ContextDev
                 T.nilable(
                   T::Array[ContextDev::Models::WebScrapeResponse::Images::Data]
                 ),
-              requested: T::Boolean
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
             }
           )
         end
@@ -750,24 +799,32 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
-        # Page data extracted into jsonParams.schema, after shared content filters. Values
-        # are grounded in the page; optional fields the page does not state are omitted,
-        # or null when their type allows null. An empty object when the filters leave no
-        # text.
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
+        # Page data extracted using your schema.
         sig do
           params(
             data: T.nilable(T::Hash[Symbol, T.anything]),
-            requested: T::Boolean
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
           ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
           override.returns(
             {
               data: T.nilable(T::Hash[Symbol, T.anything]),
-              requested: T::Boolean
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
             }
           )
         end
@@ -790,17 +847,34 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
         # Markdown after content filters.
         sig do
-          params(data: T.nilable(String), requested: T::Boolean).returns(
-            T.attached_class
-          )
+          params(
+            data: T.nilable(String),
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
+          ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
-          override.returns({ data: T.nilable(String), requested: T::Boolean })
+          override.returns(
+            {
+              data: T.nilable(String),
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
+            }
+          )
         end
         def to_hash
         end
@@ -1324,21 +1398,32 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
         # Fields produced by parseParams.rules, after shared content filters.
         sig do
           params(
             data: T.nilable(T::Hash[Symbol, T.anything]),
-            requested: T::Boolean
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
           ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
           override.returns(
             {
               data: T.nilable(T::Hash[Symbol, T.anything]),
-              requested: T::Boolean
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
             }
           )
         end
@@ -1375,17 +1460,27 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
-        # Product detail page classification and the extracted product.
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
+        # Product details found on the page.
         sig do
           params(
             data:
               T.nilable(
                 ContextDev::Models::WebScrapeResponse::Product::Data::OrHash
               ),
-            requested: T::Boolean
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
           ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
@@ -1393,7 +1488,8 @@ module ContextDev
             {
               data:
                 T.nilable(ContextDev::Models::WebScrapeResponse::Product::Data),
-              requested: T::Boolean
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
             }
           )
         end
@@ -1784,26 +1880,44 @@ module ContextDev
         sig { returns(T::Boolean) }
         attr_accessor :requested
 
+        # True when retrieved, false when retrieval failed, and null when not requested.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_accessor :success
+
         # An image data URL. Use directly as an image src.
         sig do
-          params(data: T.nilable(String), requested: T::Boolean).returns(
-            T.attached_class
-          )
+          params(
+            data: T.nilable(String),
+            requested: T::Boolean,
+            success: T.nilable(T::Boolean)
+          ).returns(T.attached_class)
         end
-        def self.new(data:, requested:)
+        def self.new(
+          data:,
+          requested:,
+          # True when retrieved, false when retrieval failed, and null when not requested.
+          success:
+        )
         end
 
         sig do
-          override.returns({ data: T.nilable(String), requested: T::Boolean })
+          override.returns(
+            {
+              data: T.nilable(String),
+              requested: T::Boolean,
+              success: T.nilable(T::Boolean)
+            }
+          )
         end
         def to_hash
         end
       end
 
-      # Present when return-partial captures a page that is still loading, returns
-      # images before image processing finishes, or cuts product AI extraction short.
-      # Also present if the optional product AI fallback fails. Partial responses are
-      # not cached.
+      # Present when at least one requested output succeeds while another fails, or when
+      # successful outputs come from a page that is still loading or images returned
+      # before processing finished. Absent when every requested output fails. Check each
+      # output's success field for its result. Valid captured pieces may be cached
+      # independently; failed retrievals and incomplete captures are not cached.
       module IsPartial
         extend ContextDev::Internal::Type::Enum
 

data/rbi/context_dev/models.rbi

@@ -21,6 +21,8 @@ module ContextDev
 
   Failure = ContextDev::Models::Failure
 
+  FeedbackSubmitParams = ContextDev::Models::FeedbackSubmitParams
+
   IndustryRetrieveNaicsParams = ContextDev::Models::IndustryRetrieveNaicsParams
 
   IndustryRetrieveSicParams = ContextDev::Models::IndustryRetrieveSicParams

data/rbi/context_dev/resources/feedback.rbi

@@ -0,0 +1,42 @@
+# typed: strong
+
+module ContextDev
+  module Resources
+    # Report bugs, docs mismatches, and friction with any Context.dev API. Submissions
+    # cost no credits and use a separate rate limit.
+    class Feedback
+      # Report a problem with a Context.dev API call, docs page, SDK, or CLI. Include
+      # request_id, url, or both.
+      sig do
+        params(
+          category: ContextDev::FeedbackSubmitParams::Category::OrSymbol,
+          note: String,
+          request_id: String,
+          tags: T::Array[String],
+          url: String,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::FeedbackSubmitResponse)
+      end
+      def submit(
+        # Kind of issue.
+        category:,
+        # What went wrong and what you expected instead.
+        note:,
+        # The request_id of the API call the feedback is about, from its response body or
+        # X-Request-Id header.
+        request_id: nil,
+        # Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
+        tags: nil,
+        # The page the feedback is about, such as one page of a crawl or a docs page.
+        url: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: ContextDev::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/context_dev/resources/news.rbi

@@ -6,9 +6,10 @@ module ContextDev
     class News
       # Searches live and historical company news for one company, identified in
       # searchBy by name, domain, ticker (optionally disambiguated by exchange), or
-      # ISIN. Results can be filtered by publisher domain, publisher country, article
-      # language, article type, and published-at date, and include stable story IDs,
-      # source metadata, verified entity relevance, and cursor pagination.
+      # ISIN. Results can be filtered by one of publisher domain, publisher country,
+      # article language, or article type, optionally combined with a published-at date
+      # range, and include stable story IDs, source metadata, verified entity relevance,
+      # and cursor pagination.
       sig do
         params(
           search_by: ContextDev::NewsSearchParams::SearchBy::OrHash,
@@ -25,7 +26,9 @@ module ContextDev
         search_by:,
         # Opaque next_cursor from the previous response, or null for the first page.
         cursor: nil,
-        # Optional result filters.
+        # Optional result filters. Use at most one of sourceDomain, sourceCountry,
+        # articleLanguage, or articleType. A date range may accompany that category;
+        # date.from must not exceed date.to.
         filter_by: nil,
         # Maximum results to return. Defaults to 10.
         limit: nil,

data/rbi/context_dev/resources/web.rbi

@@ -204,15 +204,21 @@ module ContextDev
       # is shared with Markdown, parsed fields, product data, highlights, and JSON
       # extraction. Cached outputs can come from different visits within maxAgeMs; use 0
       # for a fresh capture. HTML-only requests use the existing fast acquisition path.
-      # Highlights return the plain-text passages most relevant to
-      # highlightsParams.query. One credit per request, including cache hits and missing
-      # pages, or two with browser actions; highlights add 3 credits when passages are
-      # returned; JSON extraction adds four credits and runs an LLM over the page
-      # Markdown on every request that has text to extract; PDF OCR adds one credit per
-      # recovered page on fresh extraction; the product output adds one credit, plus six
-      # more when the specialized model is used. Original response bytes and screenshots
-      # are limited to 20 MiB each, screenshots to 40 megapixels, and the combined
-      # browser capture to 60 MiB.
+      # Highlights return Markdown excerpts most relevant to highlightsParams.query.
+      # Requests with at least one successful output cost one base credit, including
+      # cache hits, or two with browser actions. All-failed responses are unbilled
+      # except missing pages, which retain the base price and the one-credit product
+      # charge when product was requested. Highlights add 3 credits when passages are
+      # returned. JSON extraction runs an LLM over nonempty page Markdown and adds four
+      # credits only when its result is returned successfully. PDF OCR adds one credit
+      # per recovered page on fresh extraction. Product adds one credit when its
+      # successful result is returned, plus six if that result used the specialized
+      # model. Original response bytes and screenshots are limited to 20 MiB each,
+      # screenshots to 40 megapixels, and the combined response to 60 MiB. An oversized
+      # output has success: false and data: null. If the combined response exceeds its
+      # limit, the largest outputs are marked failed until the remaining outputs fit.
+      # Valid captured pieces may still be cached when omitted to meet the response size
+      # limit.
       sig do
         params(
           formats: ContextDev::WebScrapeParams::Formats::OrHash,
@@ -264,16 +270,19 @@ module ContextDev
         # Labels for tracking request usage. Not retained when zdr is enabled.
         tags: nil,
         # Total deadline, including navigation, actions, waiting, and all outputs.
-        # Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture
-        # the current page state and return captured images if image processing cannot
-        # finish before the deadline; these responses set isPartial and are not cached.
-        # Every requested format must still be available. Fixed waits must fit before a
-        # response reserve of up to 5000 milliseconds (at most one quarter of the timeout)
-        # when using return-partial.
+        # Defaults to 60000 milliseconds with behavior fail. Individual outputs have
+        # internal deadlines that reserve time to return completed outputs; timed-out
+        # outputs have success: false and data: null under either behavior. The overall
+        # request deadline remains enforced: fail returns an error if that deadline is
+        # reached. Use return-partial to allow the current page state and available
+        # outputs when the page is still loading. Partial responses set isPartial. Failed
+        # retrievals and incomplete captures are not cached; valid captured pieces may be
+        # cached independently. Fixed waits must fit before a response reserve of up to
+        # 5000 milliseconds (at most one quarter of the timeout) when using
+        # return-partial.
         timeout_opts: nil,
         # Zero data retention. Bypasses caches and uploads; excludes request/response
-        # content and tags from logs. Must be enabled for your organization. Not available
-        # with the highlights output.
+        # content and tags from logs. Must be enabled for your organization.
         zdr: nil,
         request_options: {}
       )

data/sig/context_dev/client.rbs

@@ -32,6 +32,8 @@ module ContextDev
 
     attr_reader logs: ContextDev::Resources::Logs
 
+    attr_reader feedback: ContextDev::Resources::Feedback
+
     private def auth_headers: -> ::Hash[String, String]
 
     def initialize: (