feat(sdk): expose Browserbase search and fetch

[miguelg719]

Summary

• expose Browserbase Search and Fetch through the TypeScript and Python browserbase facades
• add equivalent SearchBrowserbase and FetchBrowserbase APIs to Go using the existing Browserbase HTTP transport
• normalize response models across SDKs and document usage

Testing

• pnpm --filter @browserbasehq/stagehand build
• pnpm --filter @browserbasehq/stagehand test:unit (199 passed)
• Python Ruff, ty, and pytest (460 passed, 1 skipped)
• Go package tests (passed)

---

Summary by cubic

Implements AP-2921 by exposing Browserbase Search and Fetch through the TypeScript and Python browserbase facades and Go's SearchBrowserbase/FetchBrowserbase functions, without launching a browser.

• Uses the official Browserbase SDK in TypeScript and Python and the existing HTTP transport in Go.
• Validates query limits, fetch formats, schema requirements, URLs, and required Go search-result fields.
• Normalizes result models, adds typed fetch content handling in Go, and keeps the three SDKs' APIs in sync.
• Adds README examples and tests, and improves Go extension drift checks with SHA-256 hashes and cache invalidation.

^{Written for commit 30fae44. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 30fae44

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@browserbasehq/stagehand-python	Minor
@browserbasehq/stagehand-go	Minor
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/stagehand-integrations-example-eve-facade	Patch
@browserbasehq/stagehand-integrations-example-pi-facade	Patch
@browserbasehq/stagehand-integrations-claude-agent-sdk	Patch
@browserbasehq/stagehand-integrations-example-claude-code-facade	Patch
@browserbasehq/stagehand-integrations-codex-sdk	Patch
@browserbasehq/stagehand-integrations-example-codex-facade	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 19 files

Architecture diagram

sequenceDiagram
    participant User as SDK User
    participant TS as TypeScript SDK<br/>(browserbase facade)
    participant Py as Python SDK<br/>(browserbase facade)
    participant Go as Go SDK<br/>(SearchBrowserbase/FetchBrowserbase)
    participant BB as Browserbase API

    Note over TS,Go: Search Flow

    User->>TS: browserbase.search({apiKey, query, numResults})
    TS->>TS: Validate options (zod: query min 1,<br/>numResults 1-25, strictObject)
    TS->>BB: POST /v1/search with X-BB-API-Key
    BB-->>TS: Search results (query, requestId, results[])
    TS->>TS: Parse/validate response schema
    TS-->>User: BrowserbaseSearchResult

    User->>Py: browserbase.search(api_key, query, num_results)
    Py->>Py: Validate options (pydantic: query min 1,<br/>num_results 1-25)
    Py->>BB: AsyncBrowserbase.search.web()
    BB-->>Py: Search results
    Py->>Py: Normalize publishedDate to ISO format
    Py-->>User: BrowserbaseSearchResult

    User->>Go: SearchBrowserbase(ctx, BrowserbaseSearchOptions)
    Go->>Go: Validate options (query required,<br/>numResults 1-25)
    Go->>Go: Create HTTP client with API key
    Go->>BB: POST /v1/search with X-BB-API-Key
    BB-->>Go: Search response JSON
    Go->>Go: Validate required response fields<br/>(query, requestId, results)
    Go-->>User: BrowserbaseSearchResult

    Note over TS,Go: Fetch Flow

    User->>TS: browserbase.fetch({apiKey, url, format})
    TS->>TS: Validate options (zod: url valid,<br/>format enum raw/json/markdown)
    TS->>BB: POST /v1/fetch with X-BB-API-Key
    BB-->>TS: Fetch result (id, content, contentType,<br/>encoding, headers, statusCode)
    TS->>TS: Parse/validate response schema
    TS-->>User: BrowserbaseFetchResult

    User->>Py: browserbase.fetch(api_key, url, format)
    Py->>Py: Validate options (pydantic: url valid,<br/>format enum, schema alias)
    Py->>BB: AsyncBrowserbase.fetch_api.create()
    BB-->>Py: Fetch result
    Py->>Py: Normalize response fields
    Py-->>User: BrowserbaseFetchResult

    User->>Go: FetchBrowserbase(ctx, BrowserbaseFetchOptions)
    Go->>Go: Validate options (url http/https,<br/>format enum)
    Go->>Go: Create HTTP client with API key
    Go->>BB: POST /v1/fetch with X-BB-API-Key
    BB-->>Go: Fetch response JSON
    Go->>Go: Validate required fields +<br/>decode content (string or object)
    Go-->>User: BrowserbaseFetchResult

    Note over BB: All requests require<br/>X-BB-API-Key header

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

Review completed against the latest diff

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[seanmcguire12]

can we add examples in each examples/ dir ?

[miguelg719]

Addressed the examples request in 30fae44 with separate runnable Fetch and Search examples in each SDK: packages/sdk-ts/examples/{fetch,search}.ts, packages/sdk-python/examples/{fetch,search}.py, and packages/sdk-go/examples/{fetch,search}.go. Also rebased onto current main; local TypeScript, Python, Go, formatting, lint, package-contract, and extension-drift checks pass.