context.dev 1.35.0 → 2.0.0

data/rbi/context_dev/resources/monitors.rbi

@@ -0,0 +1,286 @@
+# typed: strong
+
+module ContextDev
+  module Resources
+    # Monitor pages, sitemaps, and extracted website data for exact or semantic
+    # changes. The change.detected webhook payload is documented by the
+    # MonitorsChangeDetectedWebhookPayload schema.
+    class Monitors
+      # Creates a monitor. The request body is a union of the supported target/change
+      # detection combinations. The monitor runs immediately after creation to create
+      # its initial baseline.
+      sig do
+        params(
+          change_detection:
+            T.any(
+              ContextDev::MonitorCreateParams::ChangeDetection::Exact::OrHash,
+              ContextDev::MonitorCreateParams::ChangeDetection::Semantic::OrHash
+            ),
+          name: String,
+          schedule: ContextDev::MonitorCreateParams::Schedule::OrHash,
+          target:
+            T.any(
+              ContextDev::MonitorCreateParams::Target::Page::OrHash,
+              ContextDev::MonitorCreateParams::Target::Sitemap::OrHash,
+              ContextDev::MonitorCreateParams::Target::Extract::OrHash
+            ),
+          mode: ContextDev::MonitorCreateParams::Mode::OrSymbol,
+          tags: T::Array[String],
+          webhook: T.nilable(ContextDev::MonitorCreateParams::Webhook::OrHash),
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorCreateResponse)
+      end
+      def create(
+        # Discriminated union describing how changes are detected.
+        change_detection:,
+        name:,
+        # Run the monitor on a fixed interval defined by a frequency and a unit, e.g.
+        # every 6 hours or every 2 days. The total interval (frequency × unit) must be
+        # between 10 minutes and 1 year.
+        schedule:,
+        # Discriminated union describing what the monitor watches.
+        target:,
+        # Top-level monitor category. Always `web` today; the concrete behavior is
+        # described by `target` and `change_detection`.
+        mode: nil,
+        # User-defined tags for grouping and filtering monitors and their changes.
+        tags: nil,
+        webhook: nil,
+        request_options: {}
+      )
+      end
+
+      # Get a monitor
+      sig do
+        params(
+          monitor_id: String,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorRetrieveResponse)
+      end
+      def retrieve(monitor_id, request_options: {})
+      end
+
+      # Updates a monitor. If `target` or `change_detection` changes, the monitor
+      # creates a new baseline. Unsupported target/change detection combinations are
+      # rejected.
+      sig do
+        params(
+          monitor_id: String,
+          change_detection:
+            T.any(
+              ContextDev::MonitorUpdateParams::ChangeDetection::Exact::OrHash,
+              ContextDev::MonitorUpdateParams::ChangeDetection::Semantic::OrHash
+            ),
+          name: String,
+          schedule: ContextDev::MonitorUpdateParams::Schedule::OrHash,
+          status: ContextDev::MonitorUpdateParams::Status::OrSymbol,
+          tags: T::Array[String],
+          target:
+            T.any(
+              ContextDev::MonitorUpdateParams::Target::Page::OrHash,
+              ContextDev::MonitorUpdateParams::Target::Sitemap::OrHash,
+              ContextDev::MonitorUpdateParams::Target::Extract::OrHash
+            ),
+          webhook: T.nilable(ContextDev::MonitorUpdateParams::Webhook::OrHash),
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorUpdateResponse)
+      end
+      def update(
+        monitor_id,
+        # Discriminated union describing how changes are detected.
+        change_detection: nil,
+        name: nil,
+        # Run the monitor on a fixed interval defined by a frequency and a unit, e.g.
+        # every 6 hours or every 2 days. The total interval (frequency × unit) must be
+        # between 10 minutes and 1 year.
+        schedule: nil,
+        status: nil,
+        # User-defined tags for grouping and filtering monitors and their changes.
+        tags: nil,
+        # Discriminated union describing what the monitor watches.
+        target: nil,
+        # Set to null to remove the webhook.
+        webhook: nil,
+        request_options: {}
+      )
+      end
+
+      # Lists monitors for the authenticated organization. Supports free-text search
+      # (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus
+      # status/type/tag filters. Results are paginated via the opaque `cursor`.
+      sig do
+        params(
+          change_detection_type:
+            ContextDev::MonitorListParams::ChangeDetectionType::OrSymbol,
+          cursor: String,
+          limit: Integer,
+          q: String,
+          search_by:
+            T::Array[ContextDev::MonitorListParams::SearchBy::OrSymbol],
+          search_type: ContextDev::MonitorListParams::SearchType::OrSymbol,
+          status: ContextDev::MonitorListParams::Status::OrSymbol,
+          tag: String,
+          tags: T::Array[String],
+          target_type: ContextDev::MonitorListParams::TargetType::OrSymbol,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorListResponse)
+      end
+      def list(
+        change_detection_type: nil,
+        cursor: nil,
+        limit: nil,
+        # Free-text search term, matched against the fields named in `search_by`.
+        q: nil,
+        # Comma-separated fields to search with `q`. Defaults to all of them. Note `query`
+        # only exists on semantic monitors.
+        search_by: nil,
+        # `prefix` for as-you-type prefix matching (default), `exact` for full-token
+        # matching.
+        search_type: nil,
+        # Monitor lifecycle status. `failed` means the most recent run failed (see the
+        # monitor's `last_error`); failed monitors keep running on schedule and flip back
+        # to `active` on the next successful run. Monitors are auto-`paused` after
+        # repeated consecutive failures or insufficient-credit skips; resume by PATCHing
+        # status to `active`.
+        status: nil,
+        # Filter to items that have this tag.
+        tag: nil,
+        # Comma-separated list of tags to filter by (matches monitors having any of them).
+        tags: nil,
+        target_type: nil,
+        request_options: {}
+      )
+      end
+
+      # Delete a monitor
+      sig do
+        params(
+          monitor_id: String,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorDeleteResponse)
+      end
+      def delete(monitor_id, request_options: {})
+      end
+
+      # Returns an account-wide feed of detected changes across monitors.
+      sig do
+        params(
+          change_detection_type:
+            ContextDev::MonitorListAccountChangesParams::ChangeDetectionType::OrSymbol,
+          cursor: String,
+          limit: Integer,
+          monitor_id: String,
+          since: Time,
+          tag: String,
+          target_type:
+            ContextDev::MonitorListAccountChangesParams::TargetType::OrSymbol,
+          until_: Time,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorListAccountChangesResponse)
+      end
+      def list_account_changes(
+        change_detection_type: nil,
+        cursor: nil,
+        limit: nil,
+        monitor_id: nil,
+        since: nil,
+        # Filter to items that have this tag.
+        tag: nil,
+        target_type: nil,
+        until_: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns an account-wide feed of monitor runs across all monitors.
+      sig do
+        params(
+          cursor: String,
+          limit: Integer,
+          status: ContextDev::MonitorListAccountRunsParams::Status::OrSymbol,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorListAccountRunsResponse)
+      end
+      def list_account_runs(
+        cursor: nil,
+        limit: nil,
+        # Lifecycle status of a run. `skipped` runs never executed — see `skip_reason`
+        # (insufficient credits, monitor paused, or superseded by a concurrent run).
+        status: nil,
+        request_options: {}
+      )
+      end
+
+      # List changes for a monitor
+      sig do
+        params(
+          monitor_id: String,
+          cursor: String,
+          limit: Integer,
+          since: Time,
+          tag: String,
+          until_: Time,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorListChangesResponse)
+      end
+      def list_changes(
+        monitor_id,
+        cursor: nil,
+        limit: nil,
+        since: nil,
+        # Filter to items that have this tag.
+        tag: nil,
+        until_: nil,
+        request_options: {}
+      )
+      end
+
+      # List monitor runs
+      sig do
+        params(
+          monitor_id: String,
+          cursor: String,
+          limit: Integer,
+          status: ContextDev::MonitorListRunsParams::Status::OrSymbol,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorListRunsResponse)
+      end
+      def list_runs(
+        monitor_id,
+        cursor: nil,
+        limit: nil,
+        # Lifecycle status of a run. `skipped` runs never executed — see `skip_reason`
+        # (insufficient credits, monitor paused, or superseded by a concurrent run).
+        status: nil,
+        request_options: {}
+      )
+      end
+
+      # Get a change
+      sig do
+        params(
+          change_id: String,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorRetrieveChangeResponse)
+      end
+      def retrieve_change(change_id, request_options: {})
+      end
+
+      # Triggers an immediate run of the monitor outside its normal schedule. The run is
+      # queued and processed asynchronously.
+      sig do
+        params(
+          monitor_id: String,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::MonitorRunResponse)
+      end
+      def run(monitor_id, 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/utility.rbi

@@ -3,42 +3,27 @@
 module ContextDev
   module Resources
     class Utility
-      # Signal that you may fetch brand data for a particular domain soon to improve
-      # latency.
+      # 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).
       sig do
         params(
-          domain: String,
+          identifier:
+            T.any(
+              ContextDev::UtilityPrefetchParams::Identifier::UtilityPrefetchDomainIdentifier::OrHash,
+              ContextDev::UtilityPrefetchParams::Identifier::UtilityPrefetchEmailIdentifier::OrHash
+            ),
+          type: ContextDev::UtilityPrefetchParams::Type::OrSymbol,
           timeout_ms: Integer,
           request_options: ContextDev::RequestOptions::OrHash
         ).returns(ContextDev::Models::UtilityPrefetchResponse)
       end
       def prefetch(
-        # Domain name to prefetch brand data for
-        domain:,
-        # Optional timeout in milliseconds for the request. If the request takes longer
-        # than this value, it will be aborted with a 408 status code. Maximum allowed
-        # value is 300000ms (5 minutes).
-        timeout_ms: nil,
-        request_options: {}
-      )
-      end
-
-      # Signal that you may fetch brand data for a particular domain soon to improve
-      # latency. This endpoint accepts an email address, extracts the domain from it,
-      # validates that it's not a disposable or free email provider, and queues the
-      # domain for prefetching.
-      sig do
-        params(
-          email: String,
-          timeout_ms: Integer,
-          request_options: ContextDev::RequestOptions::OrHash
-        ).returns(ContextDev::Models::UtilityPrefetchByEmailResponse)
-      end
-      def prefetch_by_email(
-        # Email address to prefetch brand data for. The domain will be extracted from the
-        # email. Free email providers (gmail.com, yahoo.com, etc.) and disposable email
-        # addresses are not allowed.
-        email:,
+        # Identifier of the brand to prefetch. Provide exactly one of domain or email.
+        identifier:,
+        # What to prefetch. Currently only 'brand' is supported.
+        type:,
         # Optional timeout in milliseconds for the request. If the request takes longer
         # than this value, it will be aborted with a 408 status code. Maximum allowed
         # value is 300000ms (5 minutes).

data/rbi/context_dev/resources/web.rbi

@@ -129,6 +129,8 @@ module ContextDev
       # typography, spacing, shadows, and UI components.
       sig do
         params(
+          color_scheme:
+            ContextDev::WebExtractStyleguideParams::ColorScheme::OrSymbol,
           direct_url: String,
           domain: String,
           max_age_ms: Integer,
@@ -137,6 +139,9 @@ module ContextDev
         ).returns(ContextDev::Models::WebExtractStyleguideResponse)
       end
       def extract_styleguide(
+        # Optional browser color scheme to emulate for websites that respond to
+        # prefers-color-scheme. This value is part of the styleguide cache key.
+        color_scheme: nil,
         # A specific URL to fetch the styleguide from directly, bypassing domain
         # resolution (e.g., 'https://example.com/design-system'). When provided, the
         # styleguide is extracted from this exact URL. You must provide either 'domain' or
@@ -162,6 +167,8 @@ module ContextDev
       # Capture a screenshot of a website.
       sig do
         params(
+          color_scheme: ContextDev::WebScreenshotParams::ColorScheme::OrSymbol,
+          country: ContextDev::WebScreenshotParams::Country::OrSymbol,
           direct_url: String,
           domain: String,
           full_screenshot:
@@ -178,6 +185,12 @@ module ContextDev
         ).returns(ContextDev::Models::WebScreenshotResponse)
       end
       def screenshot(
+        # Optional parameter to choose the site's visual theme in the screenshot. Use
+        # 'light' or 'dark' when the site offers both appearances.
+        color_scheme: nil,
+        # Two-letter ISO 3166-1 alpha-2 country code for the website request location.
+        # When provided, Context.dev fetches the target page from that country.
+        country: nil,
         # A specific URL to screenshot directly, bypassing domain resolution (e.g.,
         # 'https://example.com/pricing'). When provided, the screenshot is taken of this
         # exact URL. You must provide either 'domain' or 'directUrl', but not both.
@@ -229,19 +242,25 @@ module ContextDev
       sig do
         params(
           query: String,
+          country: ContextDev::WebSearchParams::Country::OrSymbol,
           exclude_domains: T::Array[String],
           freshness: ContextDev::WebSearchParams::Freshness::OrSymbol,
           include_domains: T::Array[String],
           markdown_options:
             ContextDev::WebSearchParams::MarkdownOptions::OrHash,
+          num_results: Integer,
           query_fanout: T::Boolean,
           timeout_ms: Integer,
           request_options: ContextDev::RequestOptions::OrHash
         ).returns(ContextDev::Models::WebSearchResponse)
       end
       def search(
-        # Natural-language search query.
+        # Search query. Accepts natural language as well as Google-style search operators
+        # such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`.
         query:,
+        # Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific
+        # country (maps to Google's `gl` parameter). Example: "us", "gb", "de".
+        country: nil,
         # Blocklist — drop results from these domains. Example: ["pinterest.com",
         # "reddit.com"].
         exclude_domains: nil,
@@ -252,6 +271,8 @@ module ContextDev
         include_domains: nil,
         # Inline Markdown scraping for each result. Set `enabled: true` to activate.
         markdown_options: nil,
+        # Number of results to request and return (10–100). Defaults to 10.
+        num_results: nil,
         # Expand the query into multiple parallel variants for broader recall.
         query_fanout: nil,
         # Optional timeout in milliseconds for the request. If the request takes longer
@@ -267,6 +288,7 @@ module ContextDev
       sig do
         params(
           url: String,
+          country: ContextDev::WebWebCrawlMdParams::Country::OrSymbol,
           exclude_selectors: T::Array[String],
           follow_subdomains: T::Boolean,
           include_frames: T::Boolean,
@@ -277,6 +299,7 @@ module ContextDev
           max_depth: Integer,
           max_pages: Integer,
           pdf: ContextDev::WebWebCrawlMdParams::Pdf::OrHash,
+          settle_animations: T::Boolean,
           shorten_base64_images: T::Boolean,
           stop_after_ms: Integer,
           timeout_ms: Integer,
@@ -289,6 +312,10 @@ module ContextDev
       def web_crawl_md(
         # The starting URL for the crawl (must include http:// or https:// protocol)
         url:,
+        # Two-letter ISO 3166-1 alpha-2 country code identifying a supported Context.dev
+        # residential proxy exit location. Must be one of Context.dev's supported
+        # countries. When provided, Context.dev fetches the target page from that country.
+        country: nil,
         # CSS selectors to remove before each crawled page is converted to Markdown.
         # Applied after includeSelectors. Exclusion takes precedence: an element matching
         # both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]".
@@ -320,6 +347,10 @@ module ContextDev
         # PDF parsing controls. Use start/end to limit text extraction and OCR to an
         # inclusive 1-based page range.
         pdf: nil,
+        # When true, waits briefly for CSS and transition animations to settle before
+        # extracting each crawled page. Defaults to false. This adds a bit of latency in
+        # exchange for more stable output on animated pages.
+        settle_animations: nil,
         # Truncate base64-encoded image data in the Markdown output
         shorten_base64_images: nil,
         # Soft time budget for the crawl in milliseconds. After each scrape, the crawler
@@ -347,12 +378,14 @@ module ContextDev
       sig do
         params(
           url: String,
+          country: ContextDev::WebWebScrapeHTMLParams::Country::OrSymbol,
           exclude_selectors: T::Array[String],
           headers: T::Hash[Symbol, String],
           include_frames: T::Boolean,
           include_selectors: T::Array[String],
           max_age_ms: Integer,
           pdf: ContextDev::WebWebScrapeHTMLParams::Pdf::OrHash,
+          settle_animations: T::Boolean,
           timeout_ms: Integer,
           use_main_content_only: T::Boolean,
           wait_for_ms: Integer,
@@ -362,6 +395,9 @@ module ContextDev
       def web_scrape_html(
         # Full URL to scrape (must include http:// or https:// protocol)
         url:,
+        # Two-letter ISO 3166-1 alpha-2 country code for the website request location.
+        # When provided, Context.dev fetches the target page from that country.
+        country: nil,
         # CSS selectors to remove from the result. Applied after includeSelectors.
         # Exclusion takes precedence: an element matching both is removed. Examples:
         # "nav", "footer", ".ad-banner", "[aria-hidden=true]".
@@ -383,6 +419,10 @@ module ContextDev
         # PDF parsing controls. Use start/end to limit text extraction and OCR to an
         # inclusive 1-based page range.
         pdf: nil,
+        # When true, waits briefly for CSS and transition animations to settle before
+        # extracting HTML. Defaults to false. This adds a bit of latency in exchange for
+        # more stable output on animated pages.
+        settle_animations: nil,
         # Optional timeout in milliseconds for the request. If the request takes longer
         # than this value, it will be aborted with a 408 status code. Maximum allowed
         # value is 300000ms (5 minutes).
@@ -404,6 +444,7 @@ module ContextDev
       sig do
         params(
           url: String,
+          dedupe: T::Boolean,
           enrichment: ContextDev::WebWebScrapeImagesParams::Enrichment::OrHash,
           headers: T::Hash[Symbol, String],
           max_age_ms: Integer,
@@ -415,6 +456,11 @@ module ContextDev
       def web_scrape_images(
         # Page URL to inspect. Must include http:// or https://.
         url:,
+        # When true, visually duplicate images are removed: every image is loaded and
+        # perceptually hashed, and only the highest-resolution copy of each duplicate
+        # group is kept. Images that cannot be downloaded or hashed are kept. Default:
+        # false.
+        dedupe: nil,
         # Optional per-image processing, sent as deep-object query params such as
         # enrichment[resolution]=true.
         enrichment: nil,
@@ -440,6 +486,7 @@ module ContextDev
       sig do
         params(
           url: String,
+          country: ContextDev::WebWebScrapeMdParams::Country::OrSymbol,
           exclude_selectors: T::Array[String],
           headers: T::Hash[Symbol, String],
           include_frames: T::Boolean,
@@ -448,6 +495,7 @@ module ContextDev
           include_selectors: T::Array[String],
           max_age_ms: Integer,
           pdf: ContextDev::WebWebScrapeMdParams::Pdf::OrHash,
+          settle_animations: T::Boolean,
           shorten_base64_images: T::Boolean,
           timeout_ms: Integer,
           use_main_content_only: T::Boolean,
@@ -459,6 +507,9 @@ module ContextDev
         # Full URL to scrape into LLM usable Markdown (must include http:// or https://
         # protocol)
         url:,
+        # Two-letter ISO 3166-1 alpha-2 country code for the website request location.
+        # When provided, Context.dev fetches the target page from that country.
+        country: nil,
         # CSS selectors to remove before conversion to Markdown. Applied after
         # includeSelectors. Exclusion takes precedence: an element matching both is
         # removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]".
@@ -484,6 +535,10 @@ module ContextDev
         # PDF parsing controls. Use start/end to limit text extraction and OCR to an
         # inclusive 1-based page range.
         pdf: nil,
+        # When true, waits briefly for CSS and transition animations to settle before
+        # converting to Markdown. Defaults to false. This adds a bit of latency in
+        # exchange for more stable output on animated pages.
+        settle_animations: nil,
         # Shorten base64-encoded image data in the Markdown output
         shorten_base64_images: nil,
         # Optional timeout in milliseconds for the request. If the request takes longer

data/sig/context_dev/client.rbs

@@ -20,6 +20,8 @@ module ContextDev
 
     attr_reader utility: ContextDev::Resources::Utility
 
+    attr_reader monitors: ContextDev::Resources::Monitors
+
     private def auth_headers: -> ::Hash[String, String]
 
     def initialize: (