context.dev 2.19.0 → 2.21.0

data/lib/context_dev/resources/web.rb

@@ -183,27 +183,45 @@ module ContextDev
       #
       # Reuse cached outputs independently and capture missing formats in one page
       # visit. Each cache key includes only the settings that affect that output. HTML
-      # is shared with Markdown and parsed fields. Cached outputs can come from
-      # different visits within maxAgeMs; use 0 for a fresh capture. HTML-only requests
-      # use the existing fast acquisition path. One credit per request, including cache
-      # hits, or two with browser actions; PDF OCR adds one credit per recovered page on
-      # fresh extraction. Original response bytes and screenshots are limited to 20 MiB
-      # each, screenshots to 40 megapixels, and the combined browser capture to 60 MiB.
-      #
-      # @overload scrape(formats:, url:, image_params: nil, markdown_params: nil, max_age_ms: nil, parse_params: nil, screenshot_params: nil, shared_params: nil, tags: nil, timeout_opts: nil, zdr: nil, request_options: {})
+      # 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 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: {})
       #
       # @param formats [ContextDev::Models::WebScrapeParams::Formats] Outputs to return. Enable at least one; omitted formats are false.
       #
       # @param url [String] The URL to scrape.
       #
+      # @param highlights_params [ContextDev::Models::WebScrapeParams::HighlightsParams] Highlight options. Requires formats.highlights: true.
+      #
       # @param image_params [ContextDev::Models::WebScrapeParams::ImageParams] Image options. Requires formats.images: true.
       #
+      # @param json_params [ContextDev::Models::WebScrapeParams::JsonParams] Required when formats.json is true.
+      #
       # @param markdown_params [ContextDev::Models::WebScrapeParams::MarkdownParams] Markdown options. Requires formats.markdown: true.
       #
       # @param max_age_ms [Integer] Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and update
       #
       # @param parse_params [ContextDev::Models::WebScrapeParams::ParseParams] Required when formats.parse is true.
       #
+      # @param product_params [ContextDev::Models::WebScrapeParams::ProductParams] Product options. Requires formats.product: true.
+      #
       # @param screenshot_params [ContextDev::Models::WebScrapeParams::ScreenshotParams] Screenshot options. Requires formats.screenshot: true.
       #
       # @param shared_params [ContextDev::Models::WebScrapeParams::SharedParams] Shared browser and content settings. Content filters leave screenshots and origi

data/lib/context_dev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ContextDev
-  VERSION = "2.19.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

data/rbi/context_dev/models/feedback_submit_response.rbi

@@ -0,0 +1,122 @@
+# typed: strong
+
+module ContextDev
+  module Models
+    class FeedbackSubmitResponse < ContextDev::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            ContextDev::Models::FeedbackSubmitResponse,
+            ContextDev::Internal::AnyHash
+          )
+        end
+
+      # True when feedback for this request_id was already recorded; the original
+      # feedback_id is returned.
+      sig { returns(T::Boolean) }
+      attr_accessor :already_submitted
+
+      # ID of the stored feedback.
+      sig { returns(String) }
+      attr_accessor :feedback_id
+
+      # Unique id of this API call, also sent in the X-Request-Id response header. Quote
+      # it when contacting support about a failed request.
+      sig { returns(String) }
+      attr_accessor :request_id
+
+      # Credit usage, included whenever a valid API key is provided.
+      sig do
+        returns(
+          T.nilable(ContextDev::Models::FeedbackSubmitResponse::KeyMetadata)
+        )
+      end
+      attr_reader :key_metadata
+
+      sig do
+        params(
+          key_metadata:
+            ContextDev::Models::FeedbackSubmitResponse::KeyMetadata::OrHash
+        ).void
+      end
+      attr_writer :key_metadata
+
+      sig do
+        params(
+          already_submitted: T::Boolean,
+          feedback_id: String,
+          request_id: String,
+          key_metadata:
+            ContextDev::Models::FeedbackSubmitResponse::KeyMetadata::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # True when feedback for this request_id was already recorded; the original
+        # feedback_id is returned.
+        already_submitted:,
+        # ID of the stored feedback.
+        feedback_id:,
+        # Unique id of this API call, also sent in the X-Request-Id response header. Quote
+        # it when contacting support about a failed request.
+        request_id:,
+        # Credit usage, included whenever a valid API key is provided.
+        key_metadata: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            already_submitted: T::Boolean,
+            feedback_id: String,
+            request_id: String,
+            key_metadata:
+              ContextDev::Models::FeedbackSubmitResponse::KeyMetadata
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class KeyMetadata < ContextDev::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              ContextDev::Models::FeedbackSubmitResponse::KeyMetadata,
+              ContextDev::Internal::AnyHash
+            )
+          end
+
+        # Credits used by this request.
+        sig { returns(Integer) }
+        attr_accessor :credits_consumed
+
+        # Credits remaining for your organization.
+        sig { returns(Integer) }
+        attr_accessor :credits_remaining
+
+        # Credit usage, included whenever a valid API key is provided.
+        sig do
+          params(credits_consumed: Integer, credits_remaining: Integer).returns(
+            T.attached_class
+          )
+        end
+        def self.new(
+          # Credits used by this request.
+          credits_consumed:,
+          # Credits remaining for your organization.
+          credits_remaining:
+        )
+        end
+
+        sig do
+          override.returns(
+            { credits_consumed: Integer, credits_remaining: Integer }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/context_dev/models/news_search_params.rbi

@@ -24,7 +24,9 @@ module ContextDev
       sig { returns(T.nilable(String)) }
       attr_accessor :cursor
 
-      # 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.
       sig { returns(T.nilable(ContextDev::NewsSearchParams::FilterBy)) }
       attr_reader :filter_by
 
@@ -70,7 +72,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,
@@ -812,7 +816,7 @@ module ContextDev
         end
         attr_writer :article_type
 
-        # Published-at window in epoch milliseconds.
+        # Published-at window in epoch milliseconds. from must be before or equal to to.
         sig { returns(T.nilable(ContextDev::NewsSearchParams::FilterBy::Date)) }
         attr_reader :date
 
@@ -852,7 +856,9 @@ module ContextDev
         sig { params(source_domain: T::Array[String]).void }
         attr_writer :source_domain
 
-        # 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.
         sig do
           params(
             article_language:
@@ -876,7 +882,7 @@ module ContextDev
           article_language: nil,
           # Article types to include. Up to 3.
           article_type: nil,
-          # Published-at window in epoch milliseconds.
+          # Published-at window in epoch milliseconds. from must be before or equal to to.
           date: nil,
           # Publisher countries to include, as lowercase ISO 3166-1 alpha-2 codes. Up to 3.
           source_country: nil,
@@ -1061,7 +1067,7 @@ module ContextDev
           sig { params(to: Integer).void }
           attr_writer :to
 
-          # Published-at window in epoch milliseconds.
+          # Published-at window in epoch milliseconds. from must be before or equal to to.
           sig { params(from: Integer, to: Integer).returns(T.attached_class) }
           def self.new(
             # Inclusive start of the published-at window, in epoch milliseconds.