Skip to content

CLAUDE.md

Latest commit

 

History

History
77 lines (60 loc) · 4.72 KB

CLAUDE.md

File metadata and controls

77 lines (60 loc) · 4.72 KB
Raw

Browser Use SDK

Official TypeScript and Python SDKs for the Browser Use cloud API. Published as browser-use-sdk on npm and PyPI.

Project Layout

browser-use-node/src/          # TypeScript SDK
  index.ts                     # default = v2
  v3.ts                        # subpath = v3
  v4.ts                        # subpath = v4
  core/                        # shared http + errors
  generated/v{2,3,4}/types.ts  # openapi-typescript output
  v2/                          # client + resource files + helpers
  v3/                          # client + sessions + helpers
  v4/                          # client + resource files + polling helpers

browser-use-python/src/browser_use_sdk/   # Python SDK
  __init__.py                  # default = v2
  _core/                       # shared http + errors
  generated/v{2,3,4}/models.py # datamodel-codegen output
  v2/                          # client + resource files + helpers
  v3/                          # client + sessions + helpers
  v4/                          # client + resource files + polling helpers

snapshots/v{2,3,4}.json        # last-generated OpenAPI specs
Taskfile.yml                   # mechanical commands
RUNBOOK.md                     # /sdk pipeline guide + learnings
.env                           # CLOUD_REPO_PATH, BACKEND_URL, BROWSER_USE_API_KEY

API Versions

  • v2 (default) — stable, full API surface. import { BrowserUse } from "browser-use-sdk" / from browser_use_sdk import BrowserUse
  • v3 — subpath import. import { BrowserUse } from "browser-use-sdk/v3" / from browser_use_sdk.v3 import BrowserUse
  • v4 — current API, subpath import. import { BrowserUse } from "browser-use-sdk/v4" / from browser_use_sdk.v4 import BrowserUse

SDK Updates

Run /sdk to update both SDKs from the OpenAPI specs. See RUNBOOK.md for the pipeline phases and accumulated learnings.

Commands

task gen:types       # generate TS + Python types from OpenAPI
task check           # type-check both SDKs
task build           # compile both SDKs
task test            # spec-driven vibe tests (no backend)
task test:live       # live integration tests (needs backend)
task snapshot:save   # save current specs as snapshots
task version:bump    # bump package versions
task publish         # npm + pypi publish

Design Principles

  1. 1:1 with OpenAPI. Every endpoint maps to an SDK method.
  2. Types are generated. openapi-typescript + datamodel-codegen. Deterministic.
  3. Helpers are minimal. complete() and stream() are ~20 lines each.
  4. Python returns Pydantic models. Full type safety, not dicts.
  5. Everything is regeneratable. Generate, audit, fix, ship.

SDK Rules (both TS and Python)

  • Every method with a request body MUST accept **extra (Python) or spread extra fields (TS) for forward-compatibility. No exceptions.
  • Both SDKs must stay in sync. Same retry logic, same polling defaults (2s interval, 300s timeout), same terminal statuses, same backoff cap (10s). When changing behavior in one SDK, change both.
  • Retry HTTP 429 for all methods, and 502/503/504 for GET only. Honor integer-second Retry-After within the existing ten-second delay cap; surface longer waits and use normal backoff for other formats. Keep the retry count and up to 250ms jitter; timeout remains per attempt. Do not retry other 5xx.
  • Transport retries: GET only. Retry network failures (refused/reset connections, DNS, connect timeout, a body cut off mid-read). Never retry other methods (a write may have reached the server), x402 or a custom fetch (may pay per request), read timeouts (they multiply the caller's timeout), TLS certificate failures or client-side errors. Never follow redirects.
  • Every public method needs a docstring (Python) or JSDoc (TS). One-liner, imperative style.
  • Re-export all user-facing types from top-level __init__.py / index.ts. Users should never need to import from generated/ directly.
  • Busy 503 exception. request_idempotent / requestIdempotent retry a 503 carrying Retry-After (capped at 10s). Use them only for idempotent calls the server marks busy, such as run cancel and session delete.

Python SDK Rules

  • Never use Dict[str, Any] for typed params. If the OpenAPI spec defines a schema, use the generated Pydantic model (e.g. SessionSettings, CustomProxy). Only use Dict[str, Any] when the spec literally says object with no further schema.
  • Use X | None, not Optional[X]. Modern Python union syntax everywhere — hand-written code and generated code (via --use-union-operator flag).
  • No Optional, Dict, List, Union imports from typing in hand-written code. Use built-in dict, list, X | Y syntax (with from __future__ import annotations).