context.dev 2.20.0 → 2.21.0

data/lib/context_dev/models/web_scrape_response.rb

@@ -20,9 +20,9 @@ module ContextDev
       required :cache_metadata, -> { ContextDev::Models::WebScrapeResponse::CacheMetadata }
 
       # @!attribute highlights
-      #   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.
       #
       #   @return [ContextDev::Models::WebScrapeResponse::Highlights]
       required :highlights, -> { ContextDev::Models::WebScrapeResponse::Highlights }
@@ -40,10 +40,7 @@ module ContextDev
       required :images, -> { ContextDev::Models::WebScrapeResponse::Images }
 
       # @!attribute json
-      #   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.
       #
       #   @return [ContextDev::Models::WebScrapeResponse::Json]
       required :json, -> { ContextDev::Models::WebScrapeResponse::Json }
@@ -67,7 +64,7 @@ module ContextDev
       required :parsed, -> { ContextDev::Models::WebScrapeResponse::Parsed }
 
       # @!attribute product
-      #   Product detail page classification and the extracted product.
+      #   Product details found on the page.
       #
       #   @return [ContextDev::Models::WebScrapeResponse::Product]
       required :product, -> { ContextDev::Models::WebScrapeResponse::Product }
@@ -92,10 +89,11 @@ module ContextDev
       required :url, String
 
       # @!attribute is_partial
-      #   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.
       #
       #   @return [Boolean, ContextDev::Models::WebScrapeResponse::IsPartial, nil]
       optional :is_partial, enum: -> { ContextDev::Models::WebScrapeResponse::IsPartial }, api_name: :isPartial
@@ -114,13 +112,13 @@ module ContextDev
       #
       #   @param cache_metadata [ContextDev::Models::WebScrapeResponse::CacheMetadata] Cache outcome for this response. Composite responses are hits only when every ca
       #
-      #   @param highlights [ContextDev::Models::WebScrapeResponse::Highlights] Plain-text passages relevant to highlightsParams.query, in page order, each pref
+      #   @param highlights [ContextDev::Models::WebScrapeResponse::Highlights] Relevant Markdown excerpts for your question or topic, in page order. Headings i
       #
       #   @param html [ContextDev::Models::WebScrapeResponse::HTML] Rendered HTML after content filters.
       #
       #   @param images [ContextDev::Models::WebScrapeResponse::Images] Images after content filters. Empty when none are found.
       #
-      #   @param json [ContextDev::Models::WebScrapeResponse::Json] Page data extracted into jsonParams.schema, after shared content filters. Values
+      #   @param json [ContextDev::Models::WebScrapeResponse::Json] Page data extracted using your schema.
       #
       #   @param markdown [ContextDev::Models::WebScrapeResponse::Markdown] Markdown after content filters.
       #
@@ -128,7 +126,7 @@ module ContextDev
       #
       #   @param parsed [ContextDev::Models::WebScrapeResponse::Parsed] Fields produced by parseParams.rules, after shared content filters.
       #
-      #   @param product [ContextDev::Models::WebScrapeResponse::Product] Product detail page classification and the extracted product.
+      #   @param product [ContextDev::Models::WebScrapeResponse::Product] Product details found on the page.
       #
       #   @param request_id [String] Unique id of this API call, also sent in the X-Request-Id response header. Quote
       #
@@ -136,7 +134,7 @@ module ContextDev
       #
       #   @param url [String] Final URL after redirects and browser actions.
       #
-      #   @param is_partial [Boolean, ContextDev::Models::WebScrapeResponse::IsPartial] Present when return-partial captures a page that is still loading, returns image
+      #   @param is_partial [Boolean, ContextDev::Models::WebScrapeResponse::IsPartial] Present when at least one requested output succeeds while another fails, or when
       #
       #   @param key_metadata [ContextDev::Models::WebScrapeResponse::KeyMetadata] Credit usage, included whenever a valid API key is provided.
 
@@ -152,12 +150,21 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, requested:)
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, success:)
         #   Original HTTP response body. Waiting, actions, and content filters never change
         #   it.
         #
         #   @param data [ContextDev::Models::WebScrapeResponse::Bytes::Data, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
 
         # @see ContextDev::Models::WebScrapeResponse::Bytes#data
         class Data < ContextDev::Internal::Type::BaseModel
@@ -238,13 +245,22 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, 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.
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, 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.
         #
         #   @param data [Array<String>, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
       end
 
       # @see ContextDev::Models::WebScrapeResponse#html
@@ -259,11 +275,20 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, requested:)
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, success:)
         #   Rendered HTML after content filters.
         #
         #   @param data [String, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
       end
 
       # @see ContextDev::Models::WebScrapeResponse#images
@@ -280,11 +305,20 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, requested:)
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, success:)
         #   Images after content filters. Empty when none are found.
         #
         #   @param data [Array<ContextDev::Models::WebScrapeResponse::Images::Data>, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
 
         class Data < ContextDev::Internal::Type::BaseModel
           # @!attribute alt
@@ -368,14 +402,20 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, 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.
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, success:)
+        #   Page data extracted using your schema.
         #
         #   @param data [Hash{Symbol=>Object}, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
       end
 
       # @see ContextDev::Models::WebScrapeResponse#markdown
@@ -390,11 +430,20 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, requested:)
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, success:)
         #   Markdown after content filters.
         #
         #   @param data [String, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
       end
 
       # @see ContextDev::Models::WebScrapeResponse#metadata
@@ -668,11 +717,20 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, requested:)
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, success:)
         #   Fields produced by parseParams.rules, after shared content filters.
         #
         #   @param data [Hash{Symbol=>Object}, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
       end
 
       # @see ContextDev::Models::WebScrapeResponse#product
@@ -687,11 +745,20 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, requested:)
-        #   Product detail page classification and the extracted product.
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, success:)
+        #   Product details found on the page.
         #
         #   @param data [ContextDev::Models::WebScrapeResponse::Product::Data, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
 
         # @see ContextDev::Models::WebScrapeResponse::Product#data
         class Data < ContextDev::Internal::Type::BaseModel
@@ -926,17 +993,27 @@ module ContextDev
         #   @return [Boolean]
         required :requested, ContextDev::Internal::Type::Boolean
 
-        # @!method initialize(data:, requested:)
+        # @!attribute success
+        #   True when retrieved, false when retrieval failed, and null when not requested.
+        #
+        #   @return [Boolean, nil]
+        required :success, ContextDev::Internal::Type::Boolean, nil?: true
+
+        # @!method initialize(data:, requested:, success:)
         #   An image data URL. Use directly as an image src.
         #
         #   @param data [String, nil]
+        #
         #   @param requested [Boolean]
+        #
+        #   @param success [Boolean, nil] True when retrieved, false when retrieval failed, and null when not requested.
       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.
       #
       # @see ContextDev::Models::WebScrapeResponse#is_partial
       module IsPartial

data/lib/context_dev/models.rb

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

data/lib/context_dev/resources/feedback.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+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
+      # Some parameter documentations has been truncated, see
+      # {ContextDev::Models::FeedbackSubmitParams} for more details.
+      #
+      # Report a problem with a Context.dev API call, docs page, SDK, or CLI. Include
+      # request_id, url, or both.
+      #
+      # @overload submit(category:, note:, request_id: nil, tags: nil, url: nil, request_options: {})
+      #
+      # @param category [Symbol, ContextDev::Models::FeedbackSubmitParams::Category] Kind of issue.
+      #
+      # @param note [String] What went wrong and what you expected instead.
+      #
+      # @param request_id [String] The request_id of the API call the feedback is about, from its response body or
+      #
+      # @param tags [Array<String>] Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
+      #
+      # @param url [String] The page the feedback is about, such as one page of a crawl or a docs page.
+      #
+      # @param request_options [ContextDev::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ContextDev::Models::FeedbackSubmitResponse]
+      #
+      # @see ContextDev::Models::FeedbackSubmitParams
+      def submit(params)
+        parsed, options = ContextDev::FeedbackSubmitParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "feedback",
+          body: parsed,
+          model: ContextDev::Models::FeedbackSubmitResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ContextDev::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/context_dev/resources/news.rb

@@ -4,11 +4,15 @@ module ContextDev
   module Resources
     # Search live first-party RSS and free historical news data by company identity.
     class News
+      # Some parameter documentations has been truncated, see
+      # {ContextDev::Models::NewsSearchParams} for more details.
+      #
       # 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.
       #
       # @overload search(search_by:, cursor: nil, filter_by: nil, limit: nil, sort_by: nil, tags: nil, request_options: {})
       #
@@ -16,7 +20,7 @@ module ContextDev
       #
       # @param cursor [String, nil] Opaque next_cursor from the previous response, or null for the first page.
       #
-      # @param filter_by [ContextDev::Models::NewsSearchParams::FilterBy] Optional result filters.
+      # @param filter_by [ContextDev::Models::NewsSearchParams::FilterBy] Optional result filters. Use at most one of sourceDomain, sourceCountry, article
       #
       # @param limit [Integer] Maximum results to return. Defaults to 10.
       #

data/lib/context_dev/resources/web.rb

@@ -186,15 +186,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.
       #
       # @overload scrape(formats:, url:, highlights_params: nil, image_params: nil, json_params: nil, markdown_params: nil, max_age_ms: nil, parse_params: nil, product_params: nil, screenshot_params: nil, shared_params: nil, tags: nil, timeout_opts: nil, zdr: nil, request_options: {})
       #

data/lib/context_dev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ContextDev
-  VERSION = "2.20.0"
+  VERSION = "2.21.0"
 end

data/lib/context_dev.rb

@@ -71,6 +71,8 @@ require_relative "context_dev/models/brand_search_params"
 require_relative "context_dev/models/brand_search_response"
 require_relative "context_dev/models/crawl_controls"
 require_relative "context_dev/models/failure"
+require_relative "context_dev/models/feedback_submit_params"
+require_relative "context_dev/models/feedback_submit_response"
 require_relative "context_dev/models/industry_retrieve_naics_params"
 require_relative "context_dev/models/industry_retrieve_naics_response"
 require_relative "context_dev/models/industry_retrieve_sic_params"
@@ -150,6 +152,7 @@ require_relative "context_dev/models/web_web_crawl_md_response"
 require_relative "context_dev/models"
 require_relative "context_dev/resources/batch"
 require_relative "context_dev/resources/brand"
+require_relative "context_dev/resources/feedback"
 require_relative "context_dev/resources/industry"
 require_relative "context_dev/resources/logs"
 require_relative "context_dev/resources/monitors"

data/rbi/context_dev/client.rbi

@@ -54,6 +54,11 @@ module ContextDev
     sig { returns(ContextDev::Resources::Logs) }
     attr_reader :logs
 
+    # Report bugs, docs mismatches, and friction with any Context.dev API. Submissions
+    # cost no credits and use a separate rate limit.
+    sig { returns(ContextDev::Resources::Feedback) }
+    attr_reader :feedback
+
     # @api private
     sig { override.returns(T::Hash[String, String]) }
     private def auth_headers

data/rbi/context_dev/models/feedback_submit_params.rbi

@@ -0,0 +1,133 @@
+# typed: strong
+
+module ContextDev
+  module Models
+    class FeedbackSubmitParams < ContextDev::Internal::Type::BaseModel
+      extend ContextDev::Internal::Type::RequestParameters::Converter
+      include ContextDev::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(ContextDev::FeedbackSubmitParams, ContextDev::Internal::AnyHash)
+        end
+
+      # Kind of issue.
+      sig { returns(ContextDev::FeedbackSubmitParams::Category::OrSymbol) }
+      attr_accessor :category
+
+      # What went wrong and what you expected instead.
+      sig { returns(String) }
+      attr_accessor :note
+
+      # The request_id of the API call the feedback is about, from its response body or
+      # X-Request-Id header.
+      sig { returns(T.nilable(String)) }
+      attr_reader :request_id
+
+      sig { params(request_id: String).void }
+      attr_writer :request_id
+
+      # Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :tags
+
+      sig { params(tags: T::Array[String]).void }
+      attr_writer :tags
+
+      # The page the feedback is about, such as one page of a crawl or a docs page.
+      sig { returns(T.nilable(String)) }
+      attr_reader :url
+
+      sig { params(url: String).void }
+      attr_writer :url
+
+      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(T.attached_class)
+      end
+      def self.new(
+        # 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
+
+      sig do
+        override.returns(
+          {
+            category: ContextDev::FeedbackSubmitParams::Category::OrSymbol,
+            note: String,
+            request_id: String,
+            tags: T::Array[String],
+            url: String,
+            request_options: ContextDev::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # Kind of issue.
+      module Category
+        extend ContextDev::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, ContextDev::FeedbackSubmitParams::Category)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        BUG =
+          T.let(:bug, ContextDev::FeedbackSubmitParams::Category::TaggedSymbol)
+        DOCS_MISMATCH =
+          T.let(
+            :docs_mismatch,
+            ContextDev::FeedbackSubmitParams::Category::TaggedSymbol
+          )
+        FRICTION =
+          T.let(
+            :friction,
+            ContextDev::FeedbackSubmitParams::Category::TaggedSymbol
+          )
+        FEATURE_GAP =
+          T.let(
+            :feature_gap,
+            ContextDev::FeedbackSubmitParams::Category::TaggedSymbol
+          )
+        QUALITY_DEGRADATION =
+          T.let(
+            :quality_degradation,
+            ContextDev::FeedbackSubmitParams::Category::TaggedSymbol
+          )
+        OTHER =
+          T.let(
+            :other,
+            ContextDev::FeedbackSubmitParams::Category::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[ContextDev::FeedbackSubmitParams::Category::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end