stagehand 0.0.4 → 3.5.2

data/rbi/stagehand/resources/sessions.rbi

@@ -0,0 +1,421 @@
+# typed: strong
+
+module Stagehand
+  module Resources
+    class Sessions
+      # See {Stagehand::Resources::Sessions#act_streaming} for streaming counterpart.
+      #
+      # Executes a browser action using natural language instructions or a predefined
+      # Action object.
+      sig do
+        params(
+          id: String,
+          input: T.any(String, Stagehand::Action::OrHash),
+          frame_id: T.nilable(String),
+          options: Stagehand::SessionActParams::Options::OrHash,
+          x_stream_response:
+            Stagehand::SessionActParams::XStreamResponse::OrSymbol,
+          stream_response: T.noreturn,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Models::SessionActResponse)
+      end
+      def act(
+        # Path param: Unique session identifier
+        id,
+        # Body param: Natural language instruction or Action object
+        input:,
+        # Body param: Target frame ID for the action
+        frame_id: nil,
+        # Body param
+        options: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        # There is no need to provide `stream_response:`. Instead, use `#act_streaming` or
+        # `#act` for streaming and non-streaming use cases, respectively.
+        stream_response: false,
+        request_options: {}
+      )
+      end
+
+      # See {Stagehand::Resources::Sessions#act} for non-streaming counterpart.
+      #
+      # Executes a browser action using natural language instructions or a predefined
+      # Action object.
+      sig do
+        params(
+          id: String,
+          input: T.any(String, Stagehand::Action::OrHash),
+          frame_id: T.nilable(String),
+          options: Stagehand::SessionActParams::Options::OrHash,
+          x_stream_response:
+            Stagehand::SessionActParams::XStreamResponse::OrSymbol,
+          stream_response: T.noreturn,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Internal::Stream[Stagehand::StreamEvent])
+      end
+      def act_streaming(
+        # Path param: Unique session identifier
+        id,
+        # Body param: Natural language instruction or Action object
+        input:,
+        # Body param: Target frame ID for the action
+        frame_id: nil,
+        # Body param
+        options: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        # There is no need to provide `stream_response:`. Instead, use `#act_streaming` or
+        # `#act` for streaming and non-streaming use cases, respectively.
+        stream_response: true,
+        request_options: {}
+      )
+      end
+
+      # Terminates the browser session and releases all associated resources.
+      sig do
+        params(
+          id: String,
+          x_stream_response:
+            Stagehand::SessionEndParams::XStreamResponse::OrSymbol,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Models::SessionEndResponse)
+      end
+      def end_(
+        # Unique session identifier
+        id,
+        # Whether to stream the response via SSE
+        x_stream_response: nil,
+        request_options: {}
+      )
+      end
+
+      # See {Stagehand::Resources::Sessions#execute_streaming} for streaming
+      # counterpart.
+      #
+      # Runs an autonomous AI agent that can perform complex multi-step browser tasks.
+      sig do
+        params(
+          id: String,
+          agent_config: Stagehand::SessionExecuteParams::AgentConfig::OrHash,
+          execute_options:
+            Stagehand::SessionExecuteParams::ExecuteOptions::OrHash,
+          frame_id: T.nilable(String),
+          should_cache: T::Boolean,
+          x_stream_response:
+            Stagehand::SessionExecuteParams::XStreamResponse::OrSymbol,
+          stream_response: T.noreturn,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Models::SessionExecuteResponse)
+      end
+      def execute(
+        # Path param: Unique session identifier
+        id,
+        # Body param
+        agent_config:,
+        # Body param
+        execute_options:,
+        # Body param: Target frame ID for the agent
+        frame_id: nil,
+        # Body param: If true, the server captures a cache entry and returns it to the
+        # client
+        should_cache: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        # There is no need to provide `stream_response:`. Instead, use
+        # `#execute_streaming` or `#execute` for streaming and non-streaming use cases,
+        # respectively.
+        stream_response: false,
+        request_options: {}
+      )
+      end
+
+      # See {Stagehand::Resources::Sessions#execute} for non-streaming counterpart.
+      #
+      # Runs an autonomous AI agent that can perform complex multi-step browser tasks.
+      sig do
+        params(
+          id: String,
+          agent_config: Stagehand::SessionExecuteParams::AgentConfig::OrHash,
+          execute_options:
+            Stagehand::SessionExecuteParams::ExecuteOptions::OrHash,
+          frame_id: T.nilable(String),
+          should_cache: T::Boolean,
+          x_stream_response:
+            Stagehand::SessionExecuteParams::XStreamResponse::OrSymbol,
+          stream_response: T.noreturn,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Internal::Stream[Stagehand::StreamEvent])
+      end
+      def execute_streaming(
+        # Path param: Unique session identifier
+        id,
+        # Body param
+        agent_config:,
+        # Body param
+        execute_options:,
+        # Body param: Target frame ID for the agent
+        frame_id: nil,
+        # Body param: If true, the server captures a cache entry and returns it to the
+        # client
+        should_cache: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        # There is no need to provide `stream_response:`. Instead, use
+        # `#execute_streaming` or `#execute` for streaming and non-streaming use cases,
+        # respectively.
+        stream_response: true,
+        request_options: {}
+      )
+      end
+
+      # See {Stagehand::Resources::Sessions#extract_streaming} for streaming
+      # counterpart.
+      #
+      # Extracts structured data from the current page using AI-powered analysis.
+      sig do
+        params(
+          id: String,
+          frame_id: T.nilable(String),
+          instruction: String,
+          options: Stagehand::SessionExtractParams::Options::OrHash,
+          schema: T::Hash[Symbol, T.anything],
+          x_stream_response:
+            Stagehand::SessionExtractParams::XStreamResponse::OrSymbol,
+          stream_response: T.noreturn,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Models::SessionExtractResponse)
+      end
+      def extract(
+        # Path param: Unique session identifier
+        id,
+        # Body param: Target frame ID for the extraction
+        frame_id: nil,
+        # Body param: Natural language instruction for what to extract
+        instruction: nil,
+        # Body param
+        options: nil,
+        # Body param: JSON Schema defining the structure of data to extract
+        schema: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        # There is no need to provide `stream_response:`. Instead, use
+        # `#extract_streaming` or `#extract` for streaming and non-streaming use cases,
+        # respectively.
+        stream_response: false,
+        request_options: {}
+      )
+      end
+
+      # See {Stagehand::Resources::Sessions#extract} for non-streaming counterpart.
+      #
+      # Extracts structured data from the current page using AI-powered analysis.
+      sig do
+        params(
+          id: String,
+          frame_id: T.nilable(String),
+          instruction: String,
+          options: Stagehand::SessionExtractParams::Options::OrHash,
+          schema: T::Hash[Symbol, T.anything],
+          x_stream_response:
+            Stagehand::SessionExtractParams::XStreamResponse::OrSymbol,
+          stream_response: T.noreturn,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Internal::Stream[Stagehand::StreamEvent])
+      end
+      def extract_streaming(
+        # Path param: Unique session identifier
+        id,
+        # Body param: Target frame ID for the extraction
+        frame_id: nil,
+        # Body param: Natural language instruction for what to extract
+        instruction: nil,
+        # Body param
+        options: nil,
+        # Body param: JSON Schema defining the structure of data to extract
+        schema: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        # There is no need to provide `stream_response:`. Instead, use
+        # `#extract_streaming` or `#extract` for streaming and non-streaming use cases,
+        # respectively.
+        stream_response: true,
+        request_options: {}
+      )
+      end
+
+      # Navigates the browser to the specified URL.
+      sig do
+        params(
+          id: String,
+          url: String,
+          frame_id: T.nilable(String),
+          options: Stagehand::SessionNavigateParams::Options::OrHash,
+          stream_response: T::Boolean,
+          x_stream_response:
+            Stagehand::SessionNavigateParams::XStreamResponse::OrSymbol,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Models::SessionNavigateResponse)
+      end
+      def navigate(
+        # Path param: Unique session identifier
+        id,
+        # Body param: URL to navigate to
+        url:,
+        # Body param: Target frame ID for the navigation
+        frame_id: nil,
+        # Body param
+        options: nil,
+        # Body param: Whether to stream the response via SSE
+        stream_response: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        request_options: {}
+      )
+      end
+
+      # See {Stagehand::Resources::Sessions#observe_streaming} for streaming
+      # counterpart.
+      #
+      # Identifies and returns available actions on the current page that match the
+      # given instruction.
+      sig do
+        params(
+          id: String,
+          frame_id: T.nilable(String),
+          instruction: String,
+          options: Stagehand::SessionObserveParams::Options::OrHash,
+          x_stream_response:
+            Stagehand::SessionObserveParams::XStreamResponse::OrSymbol,
+          stream_response: T.noreturn,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Models::SessionObserveResponse)
+      end
+      def observe(
+        # Path param: Unique session identifier
+        id,
+        # Body param: Target frame ID for the observation
+        frame_id: nil,
+        # Body param: Natural language instruction for what actions to find
+        instruction: nil,
+        # Body param
+        options: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        # There is no need to provide `stream_response:`. Instead, use
+        # `#observe_streaming` or `#observe` for streaming and non-streaming use cases,
+        # respectively.
+        stream_response: false,
+        request_options: {}
+      )
+      end
+
+      # See {Stagehand::Resources::Sessions#observe} for non-streaming counterpart.
+      #
+      # Identifies and returns available actions on the current page that match the
+      # given instruction.
+      sig do
+        params(
+          id: String,
+          frame_id: T.nilable(String),
+          instruction: String,
+          options: Stagehand::SessionObserveParams::Options::OrHash,
+          x_stream_response:
+            Stagehand::SessionObserveParams::XStreamResponse::OrSymbol,
+          stream_response: T.noreturn,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Internal::Stream[Stagehand::StreamEvent])
+      end
+      def observe_streaming(
+        # Path param: Unique session identifier
+        id,
+        # Body param: Target frame ID for the observation
+        frame_id: nil,
+        # Body param: Natural language instruction for what actions to find
+        instruction: nil,
+        # Body param
+        options: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        # There is no need to provide `stream_response:`. Instead, use
+        # `#observe_streaming` or `#observe` for streaming and non-streaming use cases,
+        # respectively.
+        stream_response: true,
+        request_options: {}
+      )
+      end
+
+      # Retrieves replay metrics for a session.
+      sig do
+        params(
+          id: String,
+          x_stream_response:
+            Stagehand::SessionReplayParams::XStreamResponse::OrSymbol,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Models::SessionReplayResponse)
+      end
+      def replay(
+        # Unique session identifier
+        id,
+        # Whether to stream the response via SSE
+        x_stream_response: nil,
+        request_options: {}
+      )
+      end
+
+      # Creates a new browser session with the specified configuration. Returns a
+      # session ID used for all subsequent operations.
+      sig do
+        params(
+          model_name: String,
+          act_timeout_ms: Float,
+          browser: Stagehand::SessionStartParams::Browser::OrHash,
+          browserbase_session_create_params:
+            Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::OrHash,
+          browserbase_session_id: String,
+          dom_settle_timeout_ms: Float,
+          experimental: T::Boolean,
+          self_heal: T::Boolean,
+          system_prompt: String,
+          verbose: Stagehand::SessionStartParams::Verbose::OrFloat,
+          wait_for_captcha_solves: T::Boolean,
+          x_stream_response:
+            Stagehand::SessionStartParams::XStreamResponse::OrSymbol,
+          request_options: Stagehand::RequestOptions::OrHash
+        ).returns(Stagehand::Models::SessionStartResponse)
+      end
+      def start(
+        # Body param: Model name to use for AI operations
+        model_name:,
+        # Body param: Timeout in ms for act operations (deprecated, v2 only)
+        act_timeout_ms: nil,
+        # Body param
+        browser: nil,
+        # Body param
+        browserbase_session_create_params: nil,
+        # Body param: Existing Browserbase session ID to resume
+        browserbase_session_id: nil,
+        # Body param: Timeout in ms to wait for DOM to settle
+        dom_settle_timeout_ms: nil,
+        # Body param
+        experimental: nil,
+        # Body param: Enable self-healing for failed actions
+        self_heal: nil,
+        # Body param: Custom system prompt for AI operations
+        system_prompt: nil,
+        # Body param: Logging verbosity level (0=quiet, 1=normal, 2=debug)
+        verbose: nil,
+        # Body param: Wait for captcha solves (deprecated, v2 only)
+        wait_for_captcha_solves: nil,
+        # Header param: Whether to stream the response via SSE
+        x_stream_response: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Stagehand::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/stagehand/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module Stagehand
+  VERSION = T.let(T.unsafe(nil), String)
+end

data/sig/stagehand/client.rbs

@@ -0,0 +1,41 @@
+module Stagehand
+  class Client < Stagehand::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    attr_reader browserbase_api_key: String
+
+    attr_reader browserbase_project_id: String
+
+    attr_reader model_api_key: String
+
+    attr_reader sessions: Stagehand::Resources::Sessions
+
+    private def auth_headers: -> ::Hash[String, String]
+
+    private def bb_api_key_auth: -> ::Hash[String, String]
+
+    private def bb_project_id_auth: -> ::Hash[String, String]
+
+    private def llm_model_api_key_auth: -> ::Hash[String, String]
+
+    def initialize: (
+      ?browserbase_api_key: String?,
+      ?browserbase_project_id: String?,
+      ?model_api_key: String?,
+      ?server: String,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+
+    def close: -> void
+  end
+end

data/sig/stagehand/errors.rbs

@@ -0,0 +1,117 @@
+module Stagehand
+  module Errors
+    class Error < StandardError
+      attr_accessor cause: StandardError?
+    end
+
+    class ConversionError < Stagehand::Errors::Error
+      def cause: -> StandardError?
+
+      def initialize: (
+        on: Class,
+        method: Symbol,
+        target: top,
+        value: top,
+        ?cause: StandardError?
+      ) -> void
+    end
+
+    class APIError < Stagehand::Errors::Error
+      attr_accessor url: URI::Generic
+
+      attr_accessor status: Integer?
+
+      attr_accessor headers: ::Hash[String, String]?
+
+      attr_accessor body: top?
+
+      def initialize: (
+        url: URI::Generic,
+        ?status: Integer?,
+        ?headers: ::Hash[String, String]?,
+        ?body: Object?,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIConnectionError < Stagehand::Errors::APIError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APITimeoutError < Stagehand::Errors::APIConnectionError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIStatusError < Stagehand::Errors::APIError
+      def self.for: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> instance
+
+      def initialize: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class BadRequestError < Stagehand::Errors::APIStatusError
+      HTTP_STATUS: 400
+    end
+
+    class AuthenticationError < Stagehand::Errors::APIStatusError
+      HTTP_STATUS: 401
+    end
+
+    class PermissionDeniedError < Stagehand::Errors::APIStatusError
+      HTTP_STATUS: 403
+    end
+
+    class NotFoundError < Stagehand::Errors::APIStatusError
+      HTTP_STATUS: 404
+    end
+
+    class ConflictError < Stagehand::Errors::APIStatusError
+      HTTP_STATUS: 409
+    end
+
+    class UnprocessableEntityError < Stagehand::Errors::APIStatusError
+      HTTP_STATUS: 422
+    end
+
+    class RateLimitError < Stagehand::Errors::APIStatusError
+      HTTP_STATUS: 429
+    end
+
+    class InternalServerError < Stagehand::Errors::APIStatusError
+      HTTP_STATUS: Range[Integer]
+    end
+  end
+end

data/sig/stagehand/file_part.rbs

@@ -0,0 +1,21 @@
+module Stagehand
+  class FilePart
+    attr_reader content: Pathname | StringIO | IO | String
+
+    attr_reader content_type: String?
+
+    attr_reader filename: String?
+
+    private def read: -> String
+
+    def to_json: (*top a) -> String
+
+    def to_yaml: (*top a) -> String
+
+    def initialize: (
+      Pathname | StringIO | IO | String content,
+      ?filename: (Pathname | String)?,
+      ?content_type: String?
+    ) -> void
+  end
+end

data/sig/stagehand/internal/stream.rbs

@@ -0,0 +1,9 @@
+module Stagehand
+  module Internal
+    class Stream[Elem]
+      include Stagehand::Internal::Type::BaseStream[Stagehand::Internal::Util::server_sent_event, Elem]
+
+      private def iterator: -> Enumerable[Elem]
+    end
+  end
+end