context.dev 2.9.0 → 2.11.0

data/lib/context_dev/resources/brand.rb

@@ -68,21 +68,20 @@ module ContextDev
       # Some parameter documentations has been truncated, see
       # {ContextDev::Models::BrandSearchParams} for more details.
       #
-      # Search brands by name or domain and get back up to 10 lightweight matches
-      # (domain, name, logo). Name matches rank ahead of domain matches; within each
-      # group the most popular brands come first: by Tranco rank, then market cap for
-      # brands outside the Tranco list, with text relevance breaking ties. Matching is
-      # prefix-based with no typo tolerance, so it is suited to autocomplete. Only
-      # brands already in the Context.dev index are returned — use /brand/retrieve to
-      # fetch (and index) a specific domain. Free on Pro and Scale plans; costs 1 credit
-      # per request on the Free and Starter plans.
+      # Search indexed brands by name or domain
       #
-      # @overload search(query:, tags: nil, request_options: {})
+      # @overload search(query:, autocomplete: nil, query_by: nil, tags: nil, typo_tolerance: nil, request_options: {})
       #
-      # @param query [String] Search term, matched against brand names and domains by prefix (e.g. 'nike', 'ni
+      # @param query [String] Search term, matched against the fields selected by queryBy (e.g. 'nike', 'nike.
+      #
+      # @param autocomplete [Boolean] Whether the search term matches by prefix, so partial words match as they are ty
+      #
+      # @param query_by [Array<Symbol, ContextDev::Models::BrandSearchParams::QueryBy>] Fields to match the search term against, as a comma-separated list or repeated p
       #
       # @param tags [Array<String>] Optional comma-separated caller-defined tags for tracking this request. Tags are
       #
+      # @param typo_tolerance [Integer] Maximum number of typos tolerated when matching, from 0 to 2. Defaults to 0 (no
+      #
       # @param request_options [ContextDev::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [ContextDev::Models::BrandSearchResponse]
@@ -94,7 +93,7 @@ module ContextDev
         @client.request(
           method: :get,
           path: "brand/search",
-          query: query,
+          query: query.transform_keys(query_by: "queryBy", typo_tolerance: "typoTolerance"),
           model: ContextDev::Models::BrandSearchResponse,
           options: options
         )

data/lib/context_dev/resources/news.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ContextDev
+  module Resources
+    # Search live first-party RSS and free historical news data by company identity.
+    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.
+      #
+      # @overload search(search_by:, cursor: nil, filter_by: nil, limit: nil, sort_by: nil, tags: nil, request_options: {})
+      #
+      # @param search_by [ContextDev::Models::NewsSearchParams::SearchBy] What to search for.
+      #
+      # @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 limit [Integer] Maximum results to return. Defaults to 10.
+      #
+      # @param sort_by [ContextDev::Models::NewsSearchParams::SortBy] Result ordering. Defaults to newest.
+      #
+      # @param tags [Array<String>] Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
+      #
+      # @param request_options [ContextDev::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ContextDev::Models::NewsSearchResponse]
+      #
+      # @see ContextDev::Models::NewsSearchParams
+      def search(params)
+        parsed, options = ContextDev::NewsSearchParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "news/search",
+          body: parsed,
+          model: ContextDev::Models::NewsSearchResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ContextDev::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/context_dev/resources/parse.rb

@@ -17,19 +17,19 @@ module ContextDev
       #
       # @param extension [Symbol, ContextDev::Models::ParseHandleParams::Extension] Query param: Optional file extension hint, such as pdf, docx, xlsx, pptx, html,
       #
-      # @param include_images [Boolean, Symbol, ContextDev::Models::ParseHandleParams::IncludeImages] Query param: Include image references in Markdown output
+      # @param include_images [Boolean] Query param: Include image references in Markdown output
       #
-      # @param include_links [Boolean, Symbol, ContextDev::Models::ParseHandleParams::IncludeLinks] Query param: Preserve hyperlinks in Markdown output
+      # @param include_links [Boolean] Query param: Preserve hyperlinks in Markdown output
       #
-      # @param ocr [Boolean, Symbol, ContextDev::Models::ParseHandleParams::Ocr] Query param: When true for PDF inputs, OCR the selected pages that have no usabl
+      # @param ocr [Boolean] Query param: When true for PDF inputs, OCR the selected pages that have no usabl
       #
       # @param pdf [ContextDev::Models::ParseHandleParams::Pdf] Query param: PDF page-range options as a JSON object, e.g. {"start": 2, "end": 5
       #
-      # @param shorten_base64_images [Boolean, Symbol, ContextDev::Models::ParseHandleParams::ShortenBase64Images] Query param: Shorten base64-encoded image data in the Markdown output
+      # @param shorten_base64_images [Boolean] Query param: Shorten base64-encoded image data in the Markdown output
       #
       # @param tags [Array<String>] Query param: Optional comma-separated caller-defined tags for tracking this requ
       #
-      # @param use_main_content_only [Boolean, Symbol, ContextDev::Models::ParseHandleParams::UseMainContentOnly] Query param: Extract only the main content from HTML-like inputs
+      # @param use_main_content_only [Boolean] Query param: Extract only the main content from HTML-like inputs
       #
       # @param zdr [Symbol, ContextDev::Models::ParseHandleParams::Zdr] Query param: Set to enabled to bypass shared caches and omit request and respons
       #

data/lib/context_dev/resources/utility.rb

@@ -6,16 +6,17 @@ module ContextDev
       # Some parameter documentations has been truncated, see
       # {ContextDev::Models::UtilityPrefetchParams} for more details.
       #
-      # Signal that you may fetch brand data soon to improve latency. The type field
-      # selects what to prefetch (currently only 'brand') and identifier carries exactly
-      # one lookup key: a domain, or an email whose domain is extracted and validated
-      # (free email providers and disposable email addresses are not allowed).
+      # Signal that you may fetch data soon to improve latency. The type field selects
+      # what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a
+      # styleguide extraction) and identifier carries exactly one lookup key: a domain,
+      # or an email whose domain is extracted and validated (free email providers and
+      # disposable email addresses are not allowed).
       #
       # @overload prefetch(identifier:, type:, tags: nil, timeout_ms: nil, request_options: {})
       #
-      # @param identifier [ContextDev::Models::UtilityPrefetchParams::Identifier::UtilityPrefetchDomainIdentifier, ContextDev::Models::UtilityPrefetchParams::Identifier::UtilityPrefetchEmailIdentifier] Identifier of the brand to prefetch. Provide exactly one of domain or email.
+      # @param identifier [ContextDev::Models::UtilityPrefetchParams::Identifier::UtilityPrefetchDomainIdentifier, ContextDev::Models::UtilityPrefetchParams::Identifier::UtilityPrefetchEmailIdentifier] Identifier of the target to prefetch. Provide exactly one of domain or email.
       #
-      # @param type [Symbol, ContextDev::Models::UtilityPrefetchParams::Type] What to prefetch. Currently only 'brand' is supported.
+      # @param type [Symbol, ContextDev::Models::UtilityPrefetchParams::Type] What to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the sty
       #
       # @param tags [Array<String>] Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
       #

data/lib/context_dev/resources/web.rb

@@ -176,7 +176,9 @@ module ContextDev
       #
       # Capture a screenshot of a website.
       #
-      # @overload screenshot(color_scheme: nil, country: nil, direct_url: nil, domain: nil, full_screenshot: nil, handle_cookie_popup: nil, max_age_ms: nil, page: nil, scroll_offset: nil, tags: nil, timeout_ms: nil, viewport: nil, wait_for_ms: nil, zdr: nil, request_options: {})
+      # @overload screenshot(clear_popups: nil, color_scheme: nil, country: nil, direct_url: nil, domain: nil, full_screenshot: nil, handle_cookie_popup: nil, max_age_ms: nil, page: nil, scroll_offset: nil, tags: nil, timeout_ms: nil, viewport: nil, wait_for_ms: nil, zdr: nil, request_options: {})
+      #
+      # @param clear_popups [Boolean] Optional parameter for comprehensive popup cleanup. If 'true', the browser dismi
       #
       # @param color_scheme [Symbol, ContextDev::Models::WebScreenshotParams::ColorScheme] Optional parameter to choose the site's visual theme in the screenshot. Use 'lig
       #
@@ -188,7 +190,7 @@ module ContextDev
       #
       # @param full_screenshot [Symbol, ContextDev::Models::WebScreenshotParams::FullScreenshot] Optional parameter to determine screenshot type. If 'true', takes a full page sc
       #
-      # @param handle_cookie_popup [Boolean, Symbol, ContextDev::Models::WebScreenshotParams::HandleCookiePopup] Optional parameter to control cookie/consent popup handling. If 'true', we dismi
+      # @param handle_cookie_popup [Boolean] Optional parameter to control cookie/consent popup handling. If 'true', we dismi
       #
       # @param max_age_ms [Integer, nil] Return a cached screenshot if a prior screenshot for the same parameters exists
       #
@@ -218,6 +220,7 @@ module ContextDev
           method: :get,
           path: "web/screenshot",
           query: query.transform_keys(
+            clear_popups: "clearPopups",
             color_scheme: "colorScheme",
             direct_url: "directUrl",
             full_screenshot: "fullScreenshot",
@@ -359,7 +362,7 @@ module ContextDev
       #
       # @param headers [Hash{Symbol=>String}] Optional outbound HTTP headers forwarded only to the target URL, sent as deep-ob
       #
-      # @param include_frames [Boolean, Symbol, ContextDev::Models::WebWebScrapeHTMLParams::IncludeFrames] When true, iframes are rendered inline into the returned HTML.
+      # @param include_frames [Boolean] When true, iframes are rendered inline into the returned HTML.
       #
       # @param include_selectors [Array<String>, nil] CSS selectors. When provided, only matching subtrees (and their descendants) are
       #
@@ -367,13 +370,13 @@ module ContextDev
       #
       # @param pdf [ContextDev::Models::WebWebScrapeHTMLParams::Pdf] PDF parsing controls. Use start/end to limit text extraction and embedded-image
       #
-      # @param settle_animations [Boolean, Symbol, ContextDev::Models::WebWebScrapeHTMLParams::SettleAnimations] When true, waits briefly for CSS and transition animations to settle before extr
+      # @param settle_animations [Boolean] When true, waits briefly for CSS and transition animations to settle before extr
       #
       # @param tags [Array<String>] Optional comma-separated caller-defined tags for tracking this request. Tags are
       #
       # @param timeout_ms [Integer] Optional timeout in milliseconds for the request. If the request takes longer th
       #
-      # @param use_main_content_only [Boolean, Symbol, ContextDev::Models::WebWebScrapeHTMLParams::UseMainContentOnly] When true, return only the page's main content in the HTML response, excluding h
+      # @param use_main_content_only [Boolean] When true, return only the page's main content in the HTML response, excluding h
       #
       # @param wait_for_ms [Integer, nil] Optional browser wait time in milliseconds after initial page load. Min: 0. Max:
       #
@@ -420,7 +423,7 @@ module ContextDev
       #
       # @param actions [Array<ContextDev::Models::WebWebScrapeImagesParams::Action::Wait, ContextDev::Models::WebWebScrapeImagesParams::Action::Perform>, nil] Optional browser actions executed in array order after the page loads and before
       #
-      # @param dedupe [Boolean, Symbol, ContextDev::Models::WebWebScrapeImagesParams::Dedupe] When true, visually duplicate images are removed: every image is loaded and perc
+      # @param dedupe [Boolean] When true, visually duplicate images are removed: every image is loaded and perc
       #
       # @param enrichment [ContextDev::Models::WebWebScrapeImagesParams::Enrichment, nil] Optional per-image processing, sent as deep-object query params such as enrichme
       #
@@ -476,19 +479,19 @@ module ContextDev
       #
       # ### Billing & errors
       #
-      # | HTTP status | Billed?                                   | Meaning                                                                                  |
-      # | ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------------- |
-      # | 200         | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing  |
-      # | 400         | No                                        | Invalid input, skipped PDF, or the page could not be scraped                             |
-      # | 401 / 403   | No                                        | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |
-      # | 404         | No                                        | Target page returned or fingerprinted as not found                                       |
-      # | 408         | No                                        | Request timed out                                                                        |
-      # | 413         | No                                        | Target content exceeds the maximum supported size (20 MB)                                |
-      # | 415         | No                                        | Unsupported content type                                                                 |
-      # | 429         | No                                        | Per-minute rate limit exceeded; honor Retry-After                                        |
-      # | 500         | No                                        | Internal error                                                                           |
+      # | HTTP status | Billed?                                   | Meaning                                                                                                                                                                                                                                                                                                       |
+      # | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+      # | 200         | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing                                                                                                                                                                                                                       |
+      # | 400         | No                                        | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |
+      # | 401 / 403   | No                                        | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code                                                                                                                                                                                                                      |
+      # | 404         | No                                        | Target page returned or fingerprinted as not found                                                                                                                                                                                                                                                            |
+      # | 408         | No                                        | Request timed out                                                                                                                                                                                                                                                                                             |
+      # | 413         | No                                        | Target content exceeds the maximum supported size (20 MB)                                                                                                                                                                                                                                                     |
+      # | 415         | No                                        | Unsupported content type                                                                                                                                                                                                                                                                                      |
+      # | 429         | No                                        | Per-minute rate limit exceeded; honor Retry-After                                                                                                                                                                                                                                                             |
+      # | 500         | No                                        | Internal error                                                                                                                                                                                                                                                                                                |
       #
-      # @overload web_scrape_md(url:, actions: nil, country: nil, exclude_selectors: nil, headers: nil, include_frames: nil, include_images: nil, include_links: nil, include_selectors: nil, max_age_ms: nil, pdf: nil, settle_animations: nil, shorten_base64_images: nil, tags: nil, timeout_ms: nil, use_main_content_only: nil, wait_for_ms: nil, zdr: nil, request_options: {})
+      # @overload web_scrape_md(url:, actions: nil, country: nil, exclude_selectors: nil, headers: nil, include_frames: nil, include_html: nil, include_images: nil, include_links: nil, include_selectors: nil, max_age_ms: nil, pdf: nil, settle_animations: nil, shorten_base64_images: nil, tags: nil, timeout_ms: nil, use_main_content_only: nil, wait_for_ms: nil, zdr: nil, request_options: {})
       #
       # @param url [String] Full URL to scrape into LLM usable Markdown (must include http:// or https:// pr
       #
@@ -500,11 +503,13 @@ module ContextDev
       #
       # @param headers [Hash{Symbol=>String}] Optional outbound HTTP headers forwarded only to the target URL, sent as deep-ob
       #
-      # @param include_frames [Boolean, Symbol, ContextDev::Models::WebWebScrapeMdParams::IncludeFrames] When true, the contents of iframes are rendered to Markdown.
+      # @param include_frames [Boolean] When true, the contents of iframes are rendered to Markdown.
+      #
+      # @param include_html [Boolean] When true, the response also includes an `html` field with the page HTML the Mar
       #
-      # @param include_images [Boolean, Symbol, ContextDev::Models::WebWebScrapeMdParams::IncludeImages] Include image references in Markdown output
+      # @param include_images [Boolean] Include image references in Markdown output
       #
-      # @param include_links [Boolean, Symbol, ContextDev::Models::WebWebScrapeMdParams::IncludeLinks] Preserve hyperlinks in Markdown output
+      # @param include_links [Boolean] Preserve hyperlinks in Markdown output
       #
       # @param include_selectors [Array<String>, nil] CSS selectors. When provided, only matching HTML subtrees (and their descendants
       #
@@ -512,15 +517,15 @@ module ContextDev
       #
       # @param pdf [ContextDev::Models::WebWebScrapeMdParams::Pdf] PDF parsing controls. Use start/end to limit text extraction and embedded-image
       #
-      # @param settle_animations [Boolean, Symbol, ContextDev::Models::WebWebScrapeMdParams::SettleAnimations] When true, waits briefly for CSS and transition animations to settle before conv
+      # @param settle_animations [Boolean] When true, waits briefly for CSS and transition animations to settle before conv
       #
-      # @param shorten_base64_images [Boolean, Symbol, ContextDev::Models::WebWebScrapeMdParams::ShortenBase64Images] Shorten base64-encoded image data in the Markdown output
+      # @param shorten_base64_images [Boolean] Shorten base64-encoded image data in the Markdown output
       #
       # @param tags [Array<String>] Optional comma-separated caller-defined tags for tracking this request. Tags are
       #
       # @param timeout_ms [Integer] Optional timeout in milliseconds for the request. If the request takes longer th
       #
-      # @param use_main_content_only [Boolean, Symbol, ContextDev::Models::WebWebScrapeMdParams::UseMainContentOnly] Extract only the main content of the page, excluding headers, footers, sidebars,
+      # @param use_main_content_only [Boolean] Extract only the main content of the page, excluding headers, footers, sidebars,
       #
       # @param wait_for_ms [Integer, nil] Optional browser wait time in milliseconds after initial page load before conver
       #
@@ -540,6 +545,7 @@ module ContextDev
           query: query.transform_keys(
             exclude_selectors: "excludeSelectors",
             include_frames: "includeFrames",
+            include_html: "includeHTML",
             include_images: "includeImages",
             include_links: "includeLinks",
             include_selectors: "includeSelectors",

data/lib/context_dev/version.rb

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

data/lib/context_dev.rb

@@ -107,6 +107,8 @@ require_relative "context_dev/models/monitor_run_params"
 require_relative "context_dev/models/monitor_run_response"
 require_relative "context_dev/models/monitor_update_params"
 require_relative "context_dev/models/monitor_update_response"
+require_relative "context_dev/models/news_search_params"
+require_relative "context_dev/models/news_search_response"
 require_relative "context_dev/models/page_error_count"
 require_relative "context_dev/models/parse_handle_params"
 require_relative "context_dev/models/parse_handle_response"
@@ -143,6 +145,7 @@ require_relative "context_dev/resources/batch"
 require_relative "context_dev/resources/brand"
 require_relative "context_dev/resources/industry"
 require_relative "context_dev/resources/monitors"
+require_relative "context_dev/resources/news"
 require_relative "context_dev/resources/parse"
 require_relative "context_dev/resources/people"
 require_relative "context_dev/resources/utility"

data/rbi/context_dev/client.rbi

@@ -45,6 +45,10 @@ module ContextDev
     sig { returns(ContextDev::Resources::People) }
     attr_reader :people
 
+    # Search live first-party RSS and free historical news data by company identity.
+    sig { returns(ContextDev::Resources::News) }
+    attr_reader :news
+
     # @api private
     sig { override.returns(T::Hash[String, String]) }
     private def auth_headers

data/rbi/context_dev/models/batch_get_results_response.rbi

@@ -162,7 +162,8 @@ module ContextDev
           sig { returns(String) }
           attr_accessor :url
 
-          # Raw page HTML. Present on html batches.
+          # Page HTML. Present on html batches, and on markdown batches submitted with
+          # `options.includeHTML`.
           sig { returns(T.nilable(String)) }
           attr_reader :html
 
@@ -223,7 +224,8 @@ module ContextDev
             metadata:,
             # URL as submitted, or as discovered by the crawl.
             url:,
-            # Raw page HTML. Present on html batches.
+            # Page HTML. Present on html batches, and on markdown batches submitted with
+            # `options.includeHTML`.
             html: nil,
             # Caller-supplied identifier echoed from submission.
             item_id: nil,
@@ -351,6 +353,29 @@ module ContextDev
             sig { params(favicon: String).void }
             attr_writer :favicon
 
+            # Page headings (h1–h6) in document order, extracted from the unfiltered document.
+            # Capped at the first 500 headings. Omitted when the page has none.
+            sig do
+              returns(
+                T.nilable(
+                  T::Array[
+                    ContextDev::Models::BatchGetResultsResponse::Data::Ok::Metadata::Heading
+                  ]
+                )
+              )
+            end
+            attr_reader :headings
+
+            sig do
+              params(
+                headings:
+                  T::Array[
+                    ContextDev::Models::BatchGetResultsResponse::Data::Ok::Metadata::Heading::OrHash
+                  ]
+              ).void
+            end
+            attr_writer :headings
+
             # Primary resolved preview image from Open Graph, Twitter, or image metadata.
             sig { returns(T.nilable(String)) }
             attr_reader :image
@@ -480,6 +505,10 @@ module ContextDev
                 canonical_url: String,
                 description: String,
                 favicon: String,
+                headings:
+                  T::Array[
+                    ContextDev::Models::BatchGetResultsResponse::Data::Ok::Metadata::Heading::OrHash
+                  ],
                 image: String,
                 json_ld: T::Array[T::Hash[Symbol, T.anything]],
                 keywords: T::Array[String],
@@ -519,6 +548,9 @@ module ContextDev
               description: nil,
               # Resolved favicon URL, when present.
               favicon: nil,
+              # Page headings (h1–h6) in document order, extracted from the unfiltered document.
+              # Capped at the first 500 headings. Omitted when the page has none.
+              headings: nil,
               # Primary resolved preview image from Open Graph, Twitter, or image metadata.
               image: nil,
               # JSON-LD structured data blocks parsed from the page.
@@ -562,6 +594,10 @@ module ContextDev
                   canonical_url: String,
                   description: String,
                   favicon: String,
+                  headings:
+                    T::Array[
+                      ContextDev::Models::BatchGetResultsResponse::Data::Ok::Metadata::Heading
+                    ],
                   image: String,
                   json_ld: T::Array[T::Hash[Symbol, T.anything]],
                   keywords: T::Array[String],
@@ -677,6 +713,39 @@ module ContextDev
               end
             end
 
+            class Heading < ContextDev::Internal::Type::BaseModel
+              OrHash =
+                T.type_alias do
+                  T.any(
+                    ContextDev::Models::BatchGetResultsResponse::Data::Ok::Metadata::Heading,
+                    ContextDev::Internal::AnyHash
+                  )
+                end
+
+              # Heading level, 1–6 (from h1–h6).
+              sig { returns(Integer) }
+              attr_accessor :level
+
+              # Heading text with whitespace collapsed, truncated to 1000 characters.
+              sig { returns(String) }
+              attr_accessor :text
+
+              sig do
+                params(level: Integer, text: String).returns(T.attached_class)
+              end
+              def self.new(
+                # Heading level, 1–6 (from h1–h6).
+                level:,
+                # Heading text with whitespace collapsed, truncated to 1000 characters.
+                text:
+              )
+              end
+
+              sig { override.returns({ level: Integer, text: String }) }
+              def to_hash
+              end
+            end
+
             module OpenGraph
               extend ContextDev::Internal::Type::Union