feat(sdk): add Browserbase clientOptions to launch and connect

Merged
MI
9d ago
+551-101

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 apiKey authenticates 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.delete that 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?: BrowserbaseClientOptions on browserbase.launch() and browserbase.connect(). The type is Pick<ClientOptions, "timeout" | "maxRetries" | "defaultHeaders" | "defaultQuery" | "fetch">, validated by a strict schema. apiKey and baseURL are rejected inside it. BrowserbaseClientOptions is exported.
  • In the cross-language parity test, BrowserbaseConnectOptions.client_options is temporarily exempt for Python, until the stacked #3119 removes the exemption, and pending for Go. Go talks to Browserbase over its own net/http client 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 and rules/ast-grep parity tests (31 files, 407 tests)
  • One test builds a real @browserbasehq/sdk client with a spy fetch and checks that the request URL, defaultQuery, defaultHeaders and API key are applied
  • Published-tarball consumer type fixture uses BrowserbaseClientOptions
  • No live Browserbase session was launched