context.dev 2.11.0 → 2.12.0

data/rbi/context_dev/models/web_extract_params.rbi

@@ -11,9 +11,11 @@ module ContextDev
           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.
+      # JSON Schema for the returned data object. Image fields such as `image_urls` or
+      # `product_photos` automatically make page image references available to
+      # extraction, so product data and photos can be returned in one call. 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
 
@@ -22,6 +24,39 @@ module ContextDev
       sig { returns(String) }
       attr_accessor :url
 
+      # Optional browser actions executed in order on the requested page after it loads,
+      # before links are discovered or additional pages are crawled. Requires a paid
+      # plan. When actions are provided and stopAfterMs is omitted, the crawl budget
+      # defaults to 110000 ms.
+      sig do
+        returns(
+          T.nilable(
+            T::Array[
+              T.any(
+                ContextDev::WebExtractParams::Action::Wait,
+                ContextDev::WebExtractParams::Action::Perform,
+                ContextDev::WebExtractParams::Action::Scroll
+              )
+            ]
+          )
+        )
+      end
+      attr_reader :actions
+
+      sig do
+        params(
+          actions:
+            T::Array[
+              T.any(
+                ContextDev::WebExtractParams::Action::Wait::OrHash,
+                ContextDev::WebExtractParams::Action::Perform::OrHash,
+                ContextDev::WebExtractParams::Action::Scroll::OrHash
+              )
+            ]
+        ).void
+      end
+      attr_writer :actions
+
       # When true, 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 (default), the model may make reasonable inferences and derivations from
@@ -95,7 +130,8 @@ module ContextDev
       attr_writer :settle_animations
 
       # Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000
-      # (110s). Default: 80000 (80s).
+      # (110s). Defaults to 80000 (80s), or 110000 (110s) when browser actions are
+      # provided.
       sig { returns(T.nilable(Integer)) }
       attr_reader :stop_after_ms
 
@@ -130,6 +166,14 @@ module ContextDev
         params(
           schema: T::Hash[Symbol, T.anything],
           url: String,
+          actions:
+            T::Array[
+              T.any(
+                ContextDev::WebExtractParams::Action::Wait::OrHash,
+                ContextDev::WebExtractParams::Action::Perform::OrHash,
+                ContextDev::WebExtractParams::Action::Scroll::OrHash
+              )
+            ],
           fact_check: T::Boolean,
           follow_subdomains: T::Boolean,
           include_frames: T::Boolean,
@@ -147,13 +191,20 @@ module ContextDev
         ).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.
+        # JSON Schema for the returned data object. Image fields such as `image_urls` or
+        # `product_photos` automatically make page image references available to
+        # extraction, so product data and photos can be returned in one call. 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:,
+        # Optional browser actions executed in order on the requested page after it loads,
+        # before links are discovered or additional pages are crawled. Requires a paid
+        # plan. When actions are provided and stopAfterMs is omitted, the crawl budget
+        # defaults to 110000 ms.
+        actions: nil,
         # When true, 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 (default), the model may make reasonable inferences and derivations from
@@ -182,7 +233,8 @@ module ContextDev
         # exchange for more stable output on animated pages.
         settle_animations: nil,
         # Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000
-        # (110s). Default: 80000 (80s).
+        # (110s). Defaults to 80000 (80s), or 110000 (110s) when browser actions are
+        # provided.
         stop_after_ms: nil,
         # Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
         tags: nil,
@@ -202,6 +254,14 @@ module ContextDev
           {
             schema: T::Hash[Symbol, T.anything],
             url: String,
+            actions:
+              T::Array[
+                T.any(
+                  ContextDev::WebExtractParams::Action::Wait,
+                  ContextDev::WebExtractParams::Action::Perform,
+                  ContextDev::WebExtractParams::Action::Scroll
+                )
+              ],
             fact_check: T::Boolean,
             follow_subdomains: T::Boolean,
             include_frames: T::Boolean,
@@ -222,6 +282,291 @@ module ContextDev
       def to_hash
       end
 
+      # Browser action discriminated by `do`. Each variant exposes only its applicable
+      # fields.
+      module Action
+        extend ContextDev::Internal::Type::Union
+
+        Variants =
+          T.type_alias do
+            T.any(
+              ContextDev::WebExtractParams::Action::Wait,
+              ContextDev::WebExtractParams::Action::Perform,
+              ContextDev::WebExtractParams::Action::Scroll
+            )
+          end
+
+        class Wait < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::WebExtractParams::Action::Wait,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          sig { returns(Symbol) }
+          attr_accessor :do_
+
+          sig { returns(Integer) }
+          attr_accessor :time_ms
+
+          # Pause for a fixed number of milliseconds before continuing to the next action.
+          sig do
+            params(time_ms: Integer, do_: Symbol).returns(T.attached_class)
+          end
+          def self.new(time_ms:, do_: :wait)
+          end
+
+          sig { override.returns({ do_: Symbol, time_ms: Integer }) }
+          def to_hash
+          end
+        end
+
+        class Perform < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::WebExtractParams::Action::Perform,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          sig { returns(String) }
+          attr_accessor :action
+
+          sig { returns(Symbol) }
+          attr_accessor :do_
+
+          # Resolve and perform one natural-language browser action.
+          sig { params(action: String, do_: Symbol).returns(T.attached_class) }
+          def self.new(action:, do_: :perform)
+          end
+
+          sig { override.returns({ action: String, do_: Symbol }) }
+          def to_hash
+          end
+        end
+
+        class Scroll < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::WebExtractParams::Action::Scroll,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          sig { returns(Symbol) }
+          attr_accessor :do_
+
+          # Pixels per scroll, one visible viewport, or the current scroll boundary.
+          # Defaults to viewport.
+          sig do
+            returns(
+              T.nilable(
+                T.any(
+                  Integer,
+                  ContextDev::WebExtractParams::Action::Scroll::Amount::OrSymbol
+                )
+              )
+            )
+          end
+          attr_reader :amount
+
+          sig do
+            params(
+              amount:
+                T.any(
+                  Integer,
+                  ContextDev::WebExtractParams::Action::Scroll::Amount::OrSymbol
+                )
+            ).void
+          end
+          attr_writer :amount
+
+          # CSS selector for the first matching scroll container. Defaults to the page.
+          sig { returns(T.nilable(String)) }
+          attr_reader :container
+
+          sig { params(container: String).void }
+          attr_writer :container
+
+          # Direction to scroll. Defaults to down.
+          sig do
+            returns(
+              T.nilable(
+                ContextDev::WebExtractParams::Action::Scroll::Direction::OrSymbol
+              )
+            )
+          end
+          attr_reader :direction
+
+          sig do
+            params(
+              direction:
+                ContextDev::WebExtractParams::Action::Scroll::Direction::OrSymbol
+            ).void
+          end
+          attr_writer :direction
+
+          # Maximum scroll iterations. Stops early when scrolling and scrollable extent stop
+          # changing. Defaults to 1.
+          sig { returns(T.nilable(Integer)) }
+          attr_reader :max_scrolls
+
+          sig { params(max_scrolls: Integer).void }
+          attr_writer :max_scrolls
+
+          # Scroll the page or a selected scrollable container, waiting adaptively for
+          # content and dimensions to settle after each iteration.
+          sig do
+            params(
+              amount:
+                T.any(
+                  Integer,
+                  ContextDev::WebExtractParams::Action::Scroll::Amount::OrSymbol
+                ),
+              container: String,
+              direction:
+                ContextDev::WebExtractParams::Action::Scroll::Direction::OrSymbol,
+              max_scrolls: Integer,
+              do_: Symbol
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Pixels per scroll, one visible viewport, or the current scroll boundary.
+            # Defaults to viewport.
+            amount: nil,
+            # CSS selector for the first matching scroll container. Defaults to the page.
+            container: nil,
+            # Direction to scroll. Defaults to down.
+            direction: nil,
+            # Maximum scroll iterations. Stops early when scrolling and scrollable extent stop
+            # changing. Defaults to 1.
+            max_scrolls: nil,
+            do_: :scroll
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                do_: Symbol,
+                amount:
+                  T.any(
+                    Integer,
+                    ContextDev::WebExtractParams::Action::Scroll::Amount::OrSymbol
+                  ),
+                container: String,
+                direction:
+                  ContextDev::WebExtractParams::Action::Scroll::Direction::OrSymbol,
+                max_scrolls: Integer
+              }
+            )
+          end
+          def to_hash
+          end
+
+          # Pixels per scroll, one visible viewport, or the current scroll boundary.
+          # Defaults to viewport.
+          module Amount
+            extend ContextDev::Internal::Type::Union
+
+            Variants =
+              T.type_alias do
+                T.any(
+                  Integer,
+                  ContextDev::WebExtractParams::Action::Scroll::Amount::TaggedSymbol
+                )
+              end
+
+            sig do
+              override.returns(
+                T::Array[
+                  ContextDev::WebExtractParams::Action::Scroll::Amount::Variants
+                ]
+              )
+            end
+            def self.variants
+            end
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  ContextDev::WebExtractParams::Action::Scroll::Amount
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            VIEWPORT =
+              T.let(
+                :viewport,
+                ContextDev::WebExtractParams::Action::Scroll::Amount::TaggedSymbol
+              )
+            MAX =
+              T.let(
+                :max,
+                ContextDev::WebExtractParams::Action::Scroll::Amount::TaggedSymbol
+              )
+          end
+
+          # Direction to scroll. Defaults to down.
+          module Direction
+            extend ContextDev::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  ContextDev::WebExtractParams::Action::Scroll::Direction
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            UP =
+              T.let(
+                :up,
+                ContextDev::WebExtractParams::Action::Scroll::Direction::TaggedSymbol
+              )
+            DOWN =
+              T.let(
+                :down,
+                ContextDev::WebExtractParams::Action::Scroll::Direction::TaggedSymbol
+              )
+            LEFT =
+              T.let(
+                :left,
+                ContextDev::WebExtractParams::Action::Scroll::Direction::TaggedSymbol
+              )
+            RIGHT =
+              T.let(
+                :right,
+                ContextDev::WebExtractParams::Action::Scroll::Direction::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  ContextDev::WebExtractParams::Action::Scroll::Direction::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+        end
+
+        sig do
+          override.returns(
+            T::Array[ContextDev::WebExtractParams::Action::Variants]
+          )
+        end
+        def self.variants
+        end
+      end
+
       class Pdf < ContextDev::Internal::Type::BaseModel
         OrHash =
           T.type_alias do

data/rbi/context_dev/models/web_extract_response.rbi

@@ -123,6 +123,28 @@ module ContextDev
         sig { returns(Integer) }
         attr_accessor :num_urls
 
+        # One verified outcome per requested browser action, in request order.
+        sig do
+          returns(
+            T.nilable(
+              T::Array[
+                ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied
+              ]
+            )
+          )
+        end
+        attr_reader :actions_applied
+
+        sig do
+          params(
+            actions_applied:
+              T::Array[
+                ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::OrHash
+              ]
+          ).void
+        end
+        attr_writer :actions_applied
+
         sig do
           params(
             max_crawl_depth: Integer,
@@ -130,7 +152,11 @@ module ContextDev
             num_failed: Integer,
             num_skipped: Integer,
             num_succeeded: Integer,
-            num_urls: Integer
+            num_urls: Integer,
+            actions_applied:
+              T::Array[
+                ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::OrHash
+              ]
           ).returns(T.attached_class)
         end
         def self.new(
@@ -141,7 +167,9 @@ module ContextDev
           num_failed:,
           num_skipped:,
           num_succeeded:,
-          num_urls:
+          num_urls:,
+          # One verified outcome per requested browser action, in request order.
+          actions_applied: nil
         )
         end
 
@@ -153,12 +181,153 @@ module ContextDev
               num_failed: Integer,
               num_skipped: Integer,
               num_succeeded: Integer,
-              num_urls: Integer
+              num_urls: Integer,
+              actions_applied:
+                T::Array[
+                  ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied
+                ]
             }
           )
         end
         def to_hash
         end
+
+        class ActionsApplied < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          sig { returns(String) }
+          attr_accessor :instruction
+
+          # Applied means the requested page state was visibly verified. Failed means it was
+          # not verified. Skipped means it was not attempted.
+          sig do
+            returns(
+              ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::Status::TaggedSymbol
+            )
+          end
+          attr_accessor :status
+
+          # Visible page evidence used to verify an applied action.
+          sig { returns(T.nilable(String)) }
+          attr_reader :completion_evidence
+
+          sig { params(completion_evidence: String).void }
+          attr_writer :completion_evidence
+
+          sig { returns(T.nilable(Float)) }
+          attr_reader :duration_ms
+
+          sig { params(duration_ms: Float).void }
+          attr_writer :duration_ms
+
+          sig { returns(T.nilable(String)) }
+          attr_reader :error
+
+          sig { params(error: String).void }
+          attr_writer :error
+
+          sig { returns(T.nilable(String)) }
+          attr_reader :method_
+
+          sig { params(method_: String).void }
+          attr_writer :method_
+
+          sig { returns(T.nilable(String)) }
+          attr_reader :target_description
+
+          sig { params(target_description: String).void }
+          attr_writer :target_description
+
+          sig do
+            params(
+              instruction: String,
+              status:
+                ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::Status::OrSymbol,
+              completion_evidence: String,
+              duration_ms: Float,
+              error: String,
+              method_: String,
+              target_description: String
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            instruction:,
+            # Applied means the requested page state was visibly verified. Failed means it was
+            # not verified. Skipped means it was not attempted.
+            status:,
+            # Visible page evidence used to verify an applied action.
+            completion_evidence: nil,
+            duration_ms: nil,
+            error: nil,
+            method_: nil,
+            target_description: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                instruction: String,
+                status:
+                  ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::Status::TaggedSymbol,
+                completion_evidence: String,
+                duration_ms: Float,
+                error: String,
+                method_: String,
+                target_description: String
+              }
+            )
+          end
+          def to_hash
+          end
+
+          # Applied means the requested page state was visibly verified. Failed means it was
+          # not verified. Skipped means it was not attempted.
+          module Status
+            extend ContextDev::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::Status
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            APPLIED =
+              T.let(
+                :applied,
+                ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::Status::TaggedSymbol
+              )
+            FAILED =
+              T.let(
+                :failed,
+                ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::Status::TaggedSymbol
+              )
+            SKIPPED =
+              T.let(
+                :skipped,
+                ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::Status::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  ContextDev::Models::WebExtractResponse::Metadata::ActionsApplied::Status::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+        end
       end
 
       class KeyMetadata < ContextDev::Internal::Type::BaseModel

data/rbi/context_dev/models/web_web_crawl_md_params.rbi

@@ -150,7 +150,9 @@ module ContextDev
       sig { params(timeout_ms: Integer).void }
       attr_writer :timeout_ms
 
-      # Regex pattern. Only URLs matching this pattern will be followed and scraped.
+      # Regex pattern. Only URLs matching this pattern will be followed and scraped. An
+      # automatic prefix scope in the form ^<starting URL> follows a redirect of the
+      # starting page.
       sig { returns(T.nilable(String)) }
       attr_reader :url_regex
 
@@ -165,8 +167,8 @@ module ContextDev
       sig { params(use_main_content_only: T::Boolean).void }
       attr_writer :use_main_content_only
 
-      # Optional browser wait time in milliseconds after initial page load for each
-      # crawled page. Min: 0. Max: 30000 (30 seconds).
+      # Browser wait time in milliseconds after initial page load for each crawled page.
+      # Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds).
       sig { returns(T.nilable(Integer)) }
       attr_reader :wait_for_ms
 
@@ -263,13 +265,15 @@ module ContextDev
         # than this value, it will be aborted with a 408 status code. Maximum allowed
         # value is 300000ms (5 minutes).
         timeout_ms: nil,
-        # Regex pattern. Only URLs matching this pattern will be followed and scraped.
+        # Regex pattern. Only URLs matching this pattern will be followed and scraped. An
+        # automatic prefix scope in the form ^<starting URL> follows a redirect of the
+        # starting page.
         url_regex: nil,
         # Extract only the main content, stripping headers, footers, sidebars, and
         # navigation
         use_main_content_only: nil,
-        # Optional browser wait time in milliseconds after initial page load for each
-        # crawled page. Min: 0. Max: 30000 (30 seconds).
+        # Browser wait time in milliseconds after initial page load for each crawled page.
+        # Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds).
         wait_for_ms: nil,
         # Set to enabled to bypass shared caches and omit request and response content
         # from retained usage logs. Requires zero data retention to be enabled for your