context.dev 1.23.0 → 1.25.0

data/rbi/context_dev/models/web_extract_params.rbi

@@ -0,0 +1,232 @@
+# typed: strong
+
+module ContextDev
+  module Models
+    class WebExtractParams < ContextDev::Internal::Type::BaseModel
+      extend ContextDev::Internal::Type::RequestParameters::Converter
+      include ContextDev::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(ContextDev::WebExtractParams, ContextDev::Internal::AnyHash)
+        end
+
+      # JSON Schema for the returned data object. TypeScript Zod users can pass a JSON
+      # Schema generated from a Zod object; Python users can pass the equivalent JSON
+      # Schema object.
+      sig { returns(T::Hash[Symbol, T.anything]) }
+      attr_accessor :schema
+
+      # The starting website URL to crawl and extract from. Must include http:// or
+      # https://.
+      sig { returns(String) }
+      attr_accessor :url
+
+      # When true (default), every returned value must be grounded in facts stated on
+      # the page; fields that cannot be supported by the page are returned as
+      # null/empty. When false, the model may make reasonable inferences and derivations
+      # from the page content (e.g. ideal customer, competitor analysis,
+      # recommendations) while keeping verifiable specifics (names, quotes, URLs, dates,
+      # metrics) faithful to the source.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :fact_check
+
+      sig { params(fact_check: T::Boolean).void }
+      attr_writer :fact_check
+
+      # When true, follow links on subdomains of the starting URL's domain.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :follow_subdomains
+
+      sig { params(follow_subdomains: T::Boolean).void }
+      attr_writer :follow_subdomains
+
+      # When true, iframe contents are included in Markdown before extraction.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :include_frames
+
+      sig { params(include_frames: T::Boolean).void }
+      attr_writer :include_frames
+
+      # Optional extraction guidance, such as which facts to prioritize or how to
+      # interpret fields in the schema.
+      sig { returns(T.nilable(String)) }
+      attr_reader :instructions
+
+      sig { params(instructions: String).void }
+      attr_writer :instructions
+
+      # Return cached scrape results if a prior scrape for the same parameters is
+      # younger than this many milliseconds.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :max_age_ms
+
+      sig { params(max_age_ms: Integer).void }
+      attr_writer :max_age_ms
+
+      sig { returns(T.nilable(ContextDev::WebExtractParams::Pdf)) }
+      attr_reader :pdf
+
+      sig { params(pdf: ContextDev::WebExtractParams::Pdf::OrHash).void }
+      attr_writer :pdf
+
+      # Soft time budget for the crawl in milliseconds.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :stop_after_ms
+
+      sig { params(stop_after_ms: Integer).void }
+      attr_writer :stop_after_ms
+
+      # 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).
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :timeout_ms
+
+      sig { params(timeout_ms: Integer).void }
+      attr_writer :timeout_ms
+
+      # Optional browser wait time in milliseconds after initial page load for each
+      # crawled page.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :wait_for_ms
+
+      sig { params(wait_for_ms: Integer).void }
+      attr_writer :wait_for_ms
+
+      sig do
+        params(
+          schema: T::Hash[Symbol, T.anything],
+          url: String,
+          fact_check: T::Boolean,
+          follow_subdomains: T::Boolean,
+          include_frames: T::Boolean,
+          instructions: String,
+          max_age_ms: Integer,
+          pdf: ContextDev::WebExtractParams::Pdf::OrHash,
+          stop_after_ms: Integer,
+          timeout_ms: Integer,
+          wait_for_ms: Integer,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # JSON Schema for the returned data object. TypeScript Zod users can pass a JSON
+        # Schema generated from a Zod object; Python users can pass the equivalent JSON
+        # Schema object.
+        schema:,
+        # The starting website URL to crawl and extract from. Must include http:// or
+        # https://.
+        url:,
+        # When true (default), every returned value must be grounded in facts stated on
+        # the page; fields that cannot be supported by the page are returned as
+        # null/empty. When false, the model may make reasonable inferences and derivations
+        # from the page content (e.g. ideal customer, competitor analysis,
+        # recommendations) while keeping verifiable specifics (names, quotes, URLs, dates,
+        # metrics) faithful to the source.
+        fact_check: nil,
+        # When true, follow links on subdomains of the starting URL's domain.
+        follow_subdomains: nil,
+        # When true, iframe contents are included in Markdown before extraction.
+        include_frames: nil,
+        # Optional extraction guidance, such as which facts to prioritize or how to
+        # interpret fields in the schema.
+        instructions: nil,
+        # Return cached scrape results if a prior scrape for the same parameters is
+        # younger than this many milliseconds.
+        max_age_ms: nil,
+        pdf: nil,
+        # Soft time budget for the crawl in milliseconds.
+        stop_after_ms: 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).
+        timeout_ms: nil,
+        # Optional browser wait time in milliseconds after initial page load for each
+        # crawled page.
+        wait_for_ms: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            schema: T::Hash[Symbol, T.anything],
+            url: String,
+            fact_check: T::Boolean,
+            follow_subdomains: T::Boolean,
+            include_frames: T::Boolean,
+            instructions: String,
+            max_age_ms: Integer,
+            pdf: ContextDev::WebExtractParams::Pdf,
+            stop_after_ms: Integer,
+            timeout_ms: Integer,
+            wait_for_ms: Integer,
+            request_options: ContextDev::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Pdf < ContextDev::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              ContextDev::WebExtractParams::Pdf,
+              ContextDev::Internal::AnyHash
+            )
+          end
+
+        # Last 1-based PDF page to parse. Must be greater than or equal to start when both
+        # are provided.
+        sig { returns(T.nilable(Integer)) }
+        attr_reader :end_
+
+        sig { params(end_: Integer).void }
+        attr_writer :end_
+
+        # When true, PDF pages are fetched and parsed. When false, PDF pages are skipped.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :should_parse
+
+        sig { params(should_parse: T::Boolean).void }
+        attr_writer :should_parse
+
+        # First 1-based PDF page to parse.
+        sig { returns(T.nilable(Integer)) }
+        attr_reader :start
+
+        sig { params(start: Integer).void }
+        attr_writer :start
+
+        sig do
+          params(
+            end_: Integer,
+            should_parse: T::Boolean,
+            start: Integer
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Last 1-based PDF page to parse. Must be greater than or equal to start when both
+          # are provided.
+          end_: nil,
+          # When true, PDF pages are fetched and parsed. When false, PDF pages are skipped.
+          should_parse: nil,
+          # First 1-based PDF page to parse.
+          start: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            { end_: Integer, should_parse: T::Boolean, start: Integer }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/context_dev/models/web_extract_response.rbi

@@ -0,0 +1,134 @@
+# typed: strong
+
+module ContextDev
+  module Models
+    class WebExtractResponse < ContextDev::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            ContextDev::Models::WebExtractResponse,
+            ContextDev::Internal::AnyHash
+          )
+        end
+
+      # Extracted data matching the request schema
+      sig { returns(T::Hash[Symbol, T.anything]) }
+      attr_accessor :data
+
+      sig { returns(ContextDev::Models::WebExtractResponse::Metadata) }
+      attr_reader :metadata
+
+      sig do
+        params(
+          metadata: ContextDev::Models::WebExtractResponse::Metadata::OrHash
+        ).void
+      end
+      attr_writer :metadata
+
+      # Status of the response, e.g., 'ok'
+      sig { returns(String) }
+      attr_accessor :status
+
+      # The starting URL that was analyzed
+      sig { returns(String) }
+      attr_accessor :url
+
+      # List of URLs whose Markdown was used for extraction
+      sig { returns(T::Array[String]) }
+      attr_accessor :urls_analyzed
+
+      sig do
+        params(
+          data: T::Hash[Symbol, T.anything],
+          metadata: ContextDev::Models::WebExtractResponse::Metadata::OrHash,
+          status: String,
+          url: String,
+          urls_analyzed: T::Array[String]
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Extracted data matching the request schema
+        data:,
+        metadata:,
+        # Status of the response, e.g., 'ok'
+        status:,
+        # The starting URL that was analyzed
+        url:,
+        # List of URLs whose Markdown was used for extraction
+        urls_analyzed:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            data: T::Hash[Symbol, T.anything],
+            metadata: ContextDev::Models::WebExtractResponse::Metadata,
+            status: String,
+            url: String,
+            urls_analyzed: T::Array[String]
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Metadata < ContextDev::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              ContextDev::Models::WebExtractResponse::Metadata,
+              ContextDev::Internal::AnyHash
+            )
+          end
+
+        sig { returns(Integer) }
+        attr_accessor :max_crawl_depth
+
+        sig { returns(Integer) }
+        attr_accessor :num_failed
+
+        sig { returns(Integer) }
+        attr_accessor :num_skipped
+
+        sig { returns(Integer) }
+        attr_accessor :num_succeeded
+
+        sig { returns(Integer) }
+        attr_accessor :num_urls
+
+        sig do
+          params(
+            max_crawl_depth: Integer,
+            num_failed: Integer,
+            num_skipped: Integer,
+            num_succeeded: Integer,
+            num_urls: Integer
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          max_crawl_depth:,
+          num_failed:,
+          num_skipped:,
+          num_succeeded:,
+          num_urls:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              max_crawl_depth: Integer,
+              num_failed: Integer,
+              num_skipped: Integer,
+              num_succeeded: Integer,
+              num_urls: Integer
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/context_dev/models/web_extract_styleguide_params.rbi

@@ -33,6 +33,16 @@ module ContextDev
       sig { params(domain: String).void }
       attr_writer :domain
 
+      # Maximum age in milliseconds for cached data before the API performs a hard
+      # refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms)
+      # are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1
+      # year.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :max_age_ms
+
+      sig { params(max_age_ms: Integer).void }
+      attr_writer :max_age_ms
+
       # 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).
@@ -46,6 +56,7 @@ module ContextDev
         params(
           direct_url: String,
           domain: String,
+          max_age_ms: Integer,
           timeout_ms: Integer,
           request_options: ContextDev::RequestOptions::OrHash
         ).returns(T.attached_class)
@@ -60,6 +71,11 @@ module ContextDev
         # domain will be automatically normalized and validated. You must provide either
         # 'domain' or 'directUrl', but not both.
         domain: nil,
+        # Maximum age in milliseconds for cached data before the API performs a hard
+        # refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms)
+        # are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1
+        # year.
+        max_age_ms: 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).
@@ -73,6 +89,7 @@ module ContextDev
           {
             direct_url: String,
             domain: String,
+            max_age_ms: Integer,
             timeout_ms: Integer,
             request_options: ContextDev::RequestOptions
           }

data/rbi/context_dev/models.rbi

@@ -34,6 +34,8 @@ module ContextDev
 
   WebExtractFontsParams = ContextDev::Models::WebExtractFontsParams
 
+  WebExtractParams = ContextDev::Models::WebExtractParams
+
   WebExtractStyleguideParams = ContextDev::Models::WebExtractStyleguideParams
 
   WebScreenshotParams = ContextDev::Models::WebScreenshotParams

data/rbi/context_dev/resources/web.rbi

@@ -3,12 +3,72 @@
 module ContextDev
   module Resources
     class Web
+      # Crawl a website, convert pages to Markdown using the scrape cache, and extract
+      # structured data into the provided JSON Schema. The schema must describe the
+      # response data object. This endpoint does not accept targeted page-type
+      # selection.
+      sig do
+        params(
+          schema: T::Hash[Symbol, T.anything],
+          url: String,
+          fact_check: T::Boolean,
+          follow_subdomains: T::Boolean,
+          include_frames: T::Boolean,
+          instructions: String,
+          max_age_ms: Integer,
+          pdf: ContextDev::WebExtractParams::Pdf::OrHash,
+          stop_after_ms: Integer,
+          timeout_ms: Integer,
+          wait_for_ms: Integer,
+          request_options: ContextDev::RequestOptions::OrHash
+        ).returns(ContextDev::Models::WebExtractResponse)
+      end
+      def extract(
+        # JSON Schema for the returned data object. TypeScript Zod users can pass a JSON
+        # Schema generated from a Zod object; Python users can pass the equivalent JSON
+        # Schema object.
+        schema:,
+        # The starting website URL to crawl and extract from. Must include http:// or
+        # https://.
+        url:,
+        # When true (default), every returned value must be grounded in facts stated on
+        # the page; fields that cannot be supported by the page are returned as
+        # null/empty. When false, the model may make reasonable inferences and derivations
+        # from the page content (e.g. ideal customer, competitor analysis,
+        # recommendations) while keeping verifiable specifics (names, quotes, URLs, dates,
+        # metrics) faithful to the source.
+        fact_check: nil,
+        # When true, follow links on subdomains of the starting URL's domain.
+        follow_subdomains: nil,
+        # When true, iframe contents are included in Markdown before extraction.
+        include_frames: nil,
+        # Optional extraction guidance, such as which facts to prioritize or how to
+        # interpret fields in the schema.
+        instructions: nil,
+        # Return cached scrape results if a prior scrape for the same parameters is
+        # younger than this many milliseconds.
+        max_age_ms: nil,
+        pdf: nil,
+        # Soft time budget for the crawl in milliseconds.
+        stop_after_ms: 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).
+        timeout_ms: nil,
+        # Optional browser wait time in milliseconds after initial page load for each
+        # crawled page.
+        wait_for_ms: nil,
+        request_options: {}
+      )
+      end
+
       # Scrape font information from a website including font families, usage
       # statistics, fallbacks, and element/word counts.
       sig do
         params(
           direct_url: String,
           domain: String,
+          max_age_ms: Integer,
           timeout_ms: Integer,
           request_options: ContextDev::RequestOptions::OrHash
         ).returns(ContextDev::Models::WebExtractFontsResponse)
@@ -22,6 +82,11 @@ module ContextDev
         # domain will be automatically normalized and validated. You must provide either
         # 'domain' or 'directUrl', but not both.
         domain: nil,
+        # Maximum age in milliseconds for cached data before the API performs a hard
+        # refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms)
+        # are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1
+        # year.
+        max_age_ms: 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).
@@ -36,6 +101,7 @@ module ContextDev
         params(
           direct_url: String,
           domain: String,
+          max_age_ms: Integer,
           timeout_ms: Integer,
           request_options: ContextDev::RequestOptions::OrHash
         ).returns(ContextDev::Models::WebExtractStyleguideResponse)
@@ -50,6 +116,11 @@ module ContextDev
         # domain will be automatically normalized and validated. You must provide either
         # 'domain' or 'directUrl', but not both.
         domain: nil,
+        # Maximum age in milliseconds for cached data before the API performs a hard
+        # refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms)
+        # are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1
+        # year.
+        max_age_ms: 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).

data/sig/context_dev/models/web_extract_fonts_params.rbs

@@ -1,7 +1,12 @@
 module ContextDev
   module Models
     type web_extract_fonts_params =
-      { direct_url: String, domain: String, timeout_ms: Integer }
+      {
+        direct_url: String,
+        domain: String,
+        max_age_ms: Integer,
+        timeout_ms: Integer
+      }
       & ContextDev::Internal::Type::request_parameters
 
     class WebExtractFontsParams < ContextDev::Internal::Type::BaseModel
@@ -16,6 +21,10 @@ module ContextDev
 
       def domain=: (String) -> String
 
+      attr_reader max_age_ms: Integer?
+
+      def max_age_ms=: (Integer) -> Integer
+
       attr_reader timeout_ms: Integer?
 
       def timeout_ms=: (Integer) -> Integer
@@ -23,6 +32,7 @@ module ContextDev
       def initialize: (
         ?direct_url: String,
         ?domain: String,
+        ?max_age_ms: Integer,
         ?timeout_ms: Integer,
         ?request_options: ContextDev::request_opts
       ) -> void
@@ -30,6 +40,7 @@ module ContextDev
       def to_hash: -> {
         direct_url: String,
         domain: String,
+        max_age_ms: Integer,
         timeout_ms: Integer,
         request_options: ContextDev::RequestOptions
       }

data/sig/context_dev/models/web_extract_params.rbs

@@ -0,0 +1,120 @@
+module ContextDev
+  module Models
+    type web_extract_params =
+      {
+        schema: ::Hash[Symbol, top],
+        url: String,
+        fact_check: bool,
+        follow_subdomains: bool,
+        include_frames: bool,
+        instructions: String,
+        max_age_ms: Integer,
+        pdf: ContextDev::WebExtractParams::Pdf,
+        stop_after_ms: Integer,
+        timeout_ms: Integer,
+        wait_for_ms: Integer
+      }
+      & ContextDev::Internal::Type::request_parameters
+
+    class WebExtractParams < ContextDev::Internal::Type::BaseModel
+      extend ContextDev::Internal::Type::RequestParameters::Converter
+      include ContextDev::Internal::Type::RequestParameters
+
+      attr_accessor schema: ::Hash[Symbol, top]
+
+      attr_accessor url: String
+
+      attr_reader fact_check: bool?
+
+      def fact_check=: (bool) -> bool
+
+      attr_reader follow_subdomains: bool?
+
+      def follow_subdomains=: (bool) -> bool
+
+      attr_reader include_frames: bool?
+
+      def include_frames=: (bool) -> bool
+
+      attr_reader instructions: String?
+
+      def instructions=: (String) -> String
+
+      attr_reader max_age_ms: Integer?
+
+      def max_age_ms=: (Integer) -> Integer
+
+      attr_reader pdf: ContextDev::WebExtractParams::Pdf?
+
+      def pdf=: (
+        ContextDev::WebExtractParams::Pdf
+      ) -> ContextDev::WebExtractParams::Pdf
+
+      attr_reader stop_after_ms: Integer?
+
+      def stop_after_ms=: (Integer) -> Integer
+
+      attr_reader timeout_ms: Integer?
+
+      def timeout_ms=: (Integer) -> Integer
+
+      attr_reader wait_for_ms: Integer?
+
+      def wait_for_ms=: (Integer) -> Integer
+
+      def initialize: (
+        schema: ::Hash[Symbol, top],
+        url: String,
+        ?fact_check: bool,
+        ?follow_subdomains: bool,
+        ?include_frames: bool,
+        ?instructions: String,
+        ?max_age_ms: Integer,
+        ?pdf: ContextDev::WebExtractParams::Pdf,
+        ?stop_after_ms: Integer,
+        ?timeout_ms: Integer,
+        ?wait_for_ms: Integer,
+        ?request_options: ContextDev::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        schema: ::Hash[Symbol, top],
+        url: String,
+        fact_check: bool,
+        follow_subdomains: bool,
+        include_frames: bool,
+        instructions: String,
+        max_age_ms: Integer,
+        pdf: ContextDev::WebExtractParams::Pdf,
+        stop_after_ms: Integer,
+        timeout_ms: Integer,
+        wait_for_ms: Integer,
+        request_options: ContextDev::RequestOptions
+      }
+
+      type pdf = { end_: Integer, should_parse: bool, start: Integer }
+
+      class Pdf < ContextDev::Internal::Type::BaseModel
+        attr_reader end_: Integer?
+
+        def end_=: (Integer) -> Integer
+
+        attr_reader should_parse: bool?
+
+        def should_parse=: (bool) -> bool
+
+        attr_reader start: Integer?
+
+        def start=: (Integer) -> Integer
+
+        def initialize: (
+          ?end_: Integer,
+          ?should_parse: bool,
+          ?start: Integer
+        ) -> void
+
+        def to_hash: -> { end_: Integer, should_parse: bool, start: Integer }
+      end
+    end
+  end
+end