Skip to main content
Stagehand driver session, types, and generated Stagehand classes. Entrypoint source: sdk/src/stagehand.ts
import { ... } from '@bctrl/sdk/stagehand';

Export Index

ExportKindSourceNotes
RemoteStagehandContextclasssdk/src/drivers/stagehand/generated/context.tsRemoteStagehandContext - Remote Puppeteer Context API over RPC.
RemoteStagehandLocatorclasssdk/src/drivers/stagehand/generated/locator.tsRemoteStagehandLocator - Remote Puppeteer Locator API over RPC.
RemoteStagehandPageclasssdk/src/drivers/stagehand/generated/page.tsRemoteStagehandPage - Remote Puppeteer Page API over RPC.
RemoteStagehandResponseclasssdk/src/drivers/stagehand/generated/response.tsRemoteStagehandResponse - Remote Puppeteer Response API over RPC.
StagehandClickOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandDragAndDropOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandFileInputtypepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandFilePayloadinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandGotoOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandHeaderEntryinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandHighlightOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandHoverOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandInitScriptSourcetypepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandLoadStatetypepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandLocatorClickOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandLocatorTypeOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandReloadOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandScreenshotClipinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandScreenshotOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandSecurityDetailsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandSendClickEventOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandServerAddrinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandSessionclasssdk/src/drivers/stagehand/session.ts-
StagehandSnapshotOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandSnapshotResultinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandTypeOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandViewportOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandViewportSizeinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandWaitForSelectorOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source

Classes

RemoteStagehandContext

Source: sdk/src/drivers/stagehand/generated/context.ts
class RemoteStagehandContext
RemoteStagehandContext - Remote Puppeteer Context API over RPC.

Constructor

new (id: string, sendRpc: SimpleRpcSender, createPage: (id: string) => RemoteStagehandPage)

Properties

NameTypeNotes
idstringreadonly

Methods

activePage
Get the currently active page.
activePage(): Promise<RemoteStagehandPage | undefined>
addInitScript
Inject JavaScript that runs before any page scripts on every navigation.
addInitScript<Arg = unknown>(script: string | { path?: string; content?: string } | ((arg: Arg) => unknown), arg?: Arg): Promise<void>
close
Close the browser context and all associated pages.
close(): Promise<void>
markClosed
Mark this context as closed (internal use).
markClosed(): void
newPage
Create a new page (tab) in the browser.
newPage(url?: string): Promise<RemoteStagehandPage>
pages
Get all open pages in the browser context.
pages(): Promise<RemoteStagehandPage[]>
setActivePage
Set a specific page as the active page.
setActivePage(pageId: string): Promise<void>

RemoteStagehandLocator

Source: sdk/src/drivers/stagehand/generated/locator.ts
class RemoteStagehandLocator
RemoteStagehandLocator - Remote Puppeteer Locator API over RPC.

Constructor

new (selector: string, sendRpc: SimpleRpcSender)

Properties

NameTypeNotes
selectorstringreadonly

Methods

backendNodeId
Get the DOM backend node ID for the element.
backendNodeId(): Promise<number>
centroid
Get the center coordinates of the element.
centroid(): Promise<{ x: number; y: number }>
click
Click the element at its visual center.
click(options?: StagehandLocatorClickOptions): Promise<void>
clone
Clones the locator.
clone(): RemoteStagehandLocator
count
Return the number of elements matching this locator.
count(): Promise<number>
fill
Fill an input, textarea, or contenteditable element.
fill(value: string): Promise<void>
first
Return a locator for the first matching element.
first(): RemoteStagehandLocator
highlight
Visually highlight the element with an overlay.
highlight(options?: StagehandHighlightOptions): Promise<void>
hover
Move the mouse cursor to the element’s center without clicking.
hover(): Promise<void>
innerHtml
Get the element’s inner HTML.
innerHtml(): Promise<string>
innerText
Get the element’s visible text (layout-aware).
innerText(): Promise<string>
inputValue
Get the current value of an input element.
inputValue(): Promise<string>
isChecked
Check if a checkbox or radio button is checked.
isChecked(): Promise<boolean>
isVisible
Check if the element is visible.
isVisible(): Promise<boolean>
nth
Return a locator for the nth matching element.
nth(index: number): RemoteStagehandLocator
scrollTo
Scroll the element to a specific position.
scrollTo(percent: number | string): Promise<void>
selectOption
Select one or more options in a <select> element.
selectOption(values: string | string[]): Promise<string[]>
sendClickEvent
Dispatch a DOM click event directly on the element.
sendClickEvent(options?: StagehandSendClickEventOptions): Promise<void>
setInputFiles
Set files on an <input type=“file”> element.
setInputFiles(files: StagehandFileInput): Promise<void>
textContent
Get the element’s text content (raw).
textContent(): Promise<string>
type
Type text into the element with optional delay between keystrokes.
type(text: string, options?: StagehandLocatorTypeOptions): Promise<void>

RemoteStagehandPage

Source: sdk/src/drivers/stagehand/generated/page.ts
class RemoteStagehandPage
RemoteStagehandPage - Remote Puppeteer Page API over RPC.

Constructor

new (id: string, sendRpc: SimpleRpcSender, createLocator: (selector: string) => RemoteStagehandLocator, createDeepLocator: (selector: string) => RemoteStagehandLocator, createResponse: (data: unknown) => RemoteStagehandResponse)

Properties

NameTypeNotes
idstringreadonly

Methods

addInitScript
Add an initialization script that runs before page scripts.
addInitScript<Arg = unknown>(script: string | { path?: string; content?: string } | ((arg: Arg) => unknown), arg?: Arg): Promise<void>
click
Click at the specified coordinates.
click(x: number, y: number, options?: StagehandClickOptions): Promise<string | void>
deepLocator
Create a deep locator that can traverse iframes and shadow roots.
deepLocator(selector: string): RemoteStagehandLocator
dragAndDrop
Drag from one point to another.
dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options?: StagehandDragAndDropOptions): Promise<[string, string] | void>
evaluate
Execute JavaScript code within the page context.
evaluate<R, Arg = unknown>(pageFunction: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>
goBack
Navigate to the previous page in history.
goBack(options?: StagehandGotoOptions): Promise<RemoteStagehandResponse | null>
goForward
Navigate to the next page in history.
goForward(options?: StagehandGotoOptions): Promise<RemoteStagehandResponse | null>
goto
Navigate the page to a URL.
goto(url: string, options?: StagehandGotoOptions): Promise<RemoteStagehandResponse | null>
hover
Hover at the specified coordinates.
hover(x: number, y: number, options?: StagehandHoverOptions): Promise<string | void>
locator
Create a locator for an element using a CSS or XPath selector.
locator(selector: string): RemoteStagehandLocator
off
Remove an event listener.
off(event: string, handler: Function): this
on
Register an event listener.
on(event: string, handler: Function): this
once
Register a one-time event listener.
once(event: string, handler: Function): this
reload
Reload the current page.
reload(options?: StagehandReloadOptions): Promise<RemoteStagehandResponse | null>
screenshot
Capture a screenshot of the page.
screenshot(options?: StagehandScreenshotOptions): Promise<Buffer>
scroll
Scroll at the specified position by the given delta.
scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>
setViewportSize
Set the viewport size of the page.
setViewportSize(width: number, height: number, options?: StagehandViewportOptions): Promise<void>
snapshot
Get a snapshot of the page DOM.
snapshot(options?: StagehandSnapshotOptions): Promise<StagehandSnapshotResult>
title
Get the title of the page.
title(): Promise<string>
type
Type text into the currently focused element.
type(text: string, options?: StagehandTypeOptions): Promise<void>
url
Get the current URL of the page.
url(): string
waitForLoadState
Wait for the page to reach a specific load state.
waitForLoadState(state?: StagehandLoadState, options?: { timeout?: number }): Promise<void>
waitForSelector
Wait for an element matching the selector to appear.
waitForSelector(selector: string, options?: StagehandWaitForSelectorOptions): Promise<void>

RemoteStagehandResponse

Source: sdk/src/drivers/stagehand/generated/response.ts
class RemoteStagehandResponse
RemoteStagehandResponse - Remote Puppeteer Response API over RPC.

Constructor

new (sendRpc: SimpleRpcSender, data: StagehandResponseData)

Methods

allHeaders
Get all response headers including those not exposed by the standard API.
allHeaders(): Promise<Record<string, string>>
body
Get the response body as a Buffer.
body(): Promise<Buffer>
finished
Wait for the response to finish and get any error message.
finished(): Promise<string | null>
frame
Get the frame that initiated this response (synchronous version). Note: Not fully supported in remote SDK.
frame(): unknown
fromServiceWorker
Check if the response was served from a service worker.
fromServiceWorker(): boolean
headers
Get all response headers as an object.
headers(): Record<string, string>
headersArray
Get all response headers as an array of { name, value } objects.
headersArray(): Promise<StagehandHeaderEntry[]>
headerValue
Get the value of a specific header.
headerValue(name: string): Promise<string | null>
headerValues
Get all values of a specific header (for headers with multiple values).
headerValues(name: string): Promise<string[]>
json
Get the response body parsed as JSON.
json(): Promise<unknown>
ok
Check if the response status is in the 200-299 range.
ok(): boolean
securityDetails
Get the security details of the response (for HTTPS).
securityDetails(): Promise<StagehandSecurityDetails | null>
serverAddr
Get the server address (IP and port) that served the response.
serverAddr(): Promise<StagehandServerAddr | null>
status
Get the HTTP status code of the response.
status(): number
statusText
Get the HTTP status text of the response.
statusText(): string
text
Get the response body as text.
text(): Promise<string>
url
Get the URL of the response.
url(): string

StagehandSession

Source: sdk/src/drivers/stagehand/session.ts
class StagehandSession extends BaseSession<RemoteStagehandPage, StagehandScriptPage>

Constructor

new (sessionId: string, hostId: string, baseUrl: string, options?: { apiKey?: string; defaultContextId?: string; defaultPageId?: string; storage?: string })

Properties

NameTypeNotes
pageRemoteStagehandPagegetter • Get the default/active page.

External Re-exports

ExportKindSourceNotes
StagehandClickOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandDragAndDropOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandFileInputtypepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandFilePayloadinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandGotoOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandHeaderEntryinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandHighlightOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandHoverOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandInitScriptSourcetypepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandLoadStatetypepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandLocatorClickOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandLocatorTypeOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandReloadOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandScreenshotClipinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandScreenshotOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandSecurityDetailsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandSendClickEventOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandServerAddrinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandSnapshotOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandSnapshotResultinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandTypeOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandViewportOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandViewportSizeinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source
StagehandWaitForSelectorOptionsinterfacepackages/schemas/src/drivers/stagehand/types.tsRe-exported from non-SDK source