feat(sdk): add Browserbase clientOptions to launch and connect
Merged
MI
9d ago+551+551+012345678901234567890123456789-101-101-012345678901234567890123456789
why
Sibling to #2933. That PR lets callers inject a Browserbase SDK instance. This PR takes the alternative approach: Stagehand keeps building the Browserbase client, and callers pass the client's HTTP settings instead.
- One
apiKeyauthenticates both Browserbase and the Stagehand runtime. An injected client could carry a different key. - Stagehand controls the SDK version and how the client is built. A hand-made or mismatched-version instance can't break calls like
extensions.deletethat depend on SDK-specific options. - Python can offer the same option, which #3119 does. The shared fields (
timeout,max_retries,default_headers,default_query) exist in both SDKs.
The options are nested under clientOptions rather than flattened, because browserbase.launch() passes unknown keys through to SessionCreateParams, which already has a timeout field (the session timeout in seconds).
what changed
clientOptions?: BrowserbaseClientOptionsonbrowserbase.launch()andbrowserbase.connect(). The type isPick<ClientOptions, "timeout" | "maxRetries" | "defaultHeaders" | "defaultQuery" | "fetch">, validated by a strict schema.apiKeyandbaseURLare rejected inside it.BrowserbaseClientOptionsis exported.- In the cross-language parity test,
BrowserbaseConnectOptions.client_optionsis temporarily exempt for Python, until the stacked #3119 removes the exemption, and pending for Go. Go talks to Browserbase over its ownnet/httpclient rather than the official SDK. - Adds docs (
configuration/browser.mdx, TypeScript only for now) and a minor changeset for@browserbasehq/stagehand.
test plan
-
tsc --noEmit, oxfmt, oxlint; sdk-ts unit tests andrules/ast-grepparity tests (31 files, 407 tests) - One test builds a real
@browserbasehq/sdkclient with a spyfetchand checks that the request URL,defaultQuery,defaultHeadersand API key are applied - Published-tarball consumer type fixture uses
BrowserbaseClientOptions - No live Browserbase session was launched