@solarisdk/browserbase-compat 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0
+- **Every Browserbase resource and method now exists.** `secrets`, `webhooks`, `navigationPolicies`, `certificates`, `functions.secrets`, `sessions.recording.downloads` and the rest were `undefined` on the client, so calling them failed with "not a function". They now throw `SolariCompatUnsupported` naming the method (for example `secrets.create`), as do `.asResponse()` / `.withResponse()` and the raw `client.get` / `post` / `request` calls. The ones that map to Solari (sessions, contexts, live view, recording) work as before.
+- **`keepAlive` is reported correctly.** `sessions.retrieve` and `sessions.list` said `keepAlive: false` for every session. A session created with `keepAlive: true` now reports `true`. The gateway does not return it, so the package stores it in one reserved user metadata key, `solari_compat_keep_alive`, and hides that key from the `userMetadata` you get back. That key is reserved, and `keepAlive: true` with 50 metadata keys of your own now throws. A session created some other way, or by an older version, still reports `false`.
+- **Behaviour change: the session timeout is `api_timeout`, as in Browserbase's SDK.** `api_timeout` is sent to Solari as the session length. A lone `sessions.create({ timeout: 300 })` used to set the session length; Browserbase's SDK treats it as the request timeout (milliseconds), and so does this package now. `timeout` next to other params (`create({ timeout: 300, keepAlive: true })`) is still read as the session length, and giving it together with a different `api_timeout` throws. Change `timeout` to `api_timeout`.
+- **Options are no longer dropped.** The client takes `defaultHeaders` and `defaultQuery`. Every method takes Browserbase's second argument: `timeout`, `maxRetries`, `headers`, `query`, `signal` (an aborted request throws `APIUserAbortError`), and on create calls `body` and `idempotencyKey`. `httpAgent`, per-call `method` / `path` / `stream` and a header that sets `Authorization` throw.
+- **Unknown keys throw instead of vanishing.** An unknown option on the client, an unknown key in the `sessions.create` params, in `context`, `viewport`, a proxy entry, its `geolocation` or `proxySettings`, in the query of `list` / `update` / `debug`, and `browserSettings.riskPolicyId` all throw `SolariCompatUnsupported`. **If a call now throws for such a key, it never had any effect: remove it or fix the spelling.**
+- **`projectId` now warns once** (it was ignored silently). Solari keys belong to an organisation, so it selects nothing; `strict: true` throws instead.
+- **`sessions.list` returns every session.** It stopped after the gateway's first page of 100; it now follows the pages to the end.
+- **Wrong values removed.** `endedAt` was the time of your call for every finished session; it is now the expiry time for a timed-out session and absent for a released one (the gateway does not say when). `contexts.retrieve` of a missing context throws `NotFoundError`. `Context` gains `projectId` and `updatedAt`, and `ContextCreateResponse` gains `uploadUrl` (empty; see COMPAT.md).
+- The replay and saved-context downloads go through the `fetch` you gave the client, and never carry your key or default headers.
+
 ## 0.2.1
 - **Security: the base URL check accepts only the Solari API hosts.** It used to accept any `*.getsolari.com` host, including sandbox preview hosts (`<label>-<port>.preview.getsolari.com`) that serve customer code, so a `baseURL` / `SOLARI_BASE_URL` pointed there would send your `slr_` key to code running in a sandbox. Now only the Solari API hosts and loopback are accepted.
 

package/COMPAT.md

@@ -23,13 +23,15 @@ Keep it private: the session id inside it is the credential.
 |---|---|
 | Key | `apiKey` option, else `SOLARI_API_KEY`, else `BROWSERBASE_API_KEY`. **A key that does not start with `slr_` is never used or sent** (it is probably a Browserbase secret): it is skipped with a warning that does not print it, and if no `slr_` key remains the constructor throws. |
 | Endpoint | `baseURL` option or `SOLARI_BASE_URL`; default `https://api.getsolari.com`. Must be `https` on a Solari API host or loopback (preview and other `*.getsolari.com` hosts are refused: they serve customer code), otherwise the constructor throws `BrowserbaseError` ("Refusing to send a Solari API key to …"): the key is never sent to another host. |
-| `projectId` | Accepted and ignored: Solari keys belong to an organisation, there are no projects. |
+| `projectId` | Accepted, ignored, and **warned about once per client** (`strict: true` throws instead): Solari keys belong to an organisation, there are no projects. |
+| Client options | `apiKey`, `baseURL`, `maxRetries` (default 2) and `timeout` (ms, default 60000) apply to every request. `defaultHeaders` and `defaultQuery` are added to every Solari request (never to presigned storage downloads); a `null` header value removes a header, and `Authorization` cannot be set. `fetch` replaces the global fetch (use it for a proxy or your own dispatcher). `maxRetries` and `timeout` read back. **`httpAgent` and any option this client does not have throw `SolariCompatUnsupported`** (they are never dropped). |
+| Per-call options | Every method takes Browserbase's second argument: `timeout` (ms), `maxRetries`, `headers`, `query` and `signal` apply to every request the call makes (an aborted `signal` throws `APIUserAbortError`). `body` (extra JSON fields) and `idempotencyKey` apply to the create calls only (`sessions.create`, `contexts.create`); on any other call they throw. `method`, `path`, `stream`, `httpAgent`, `defaultBaseURL` and `__binary*` throw. `Authorization` cannot be set in `headers`. |
 
 ## Works
 | Browserbase | Here |
 |---|---|
 | `sessions.create` | `POST /sessions`; returns `connectUrl` (CDP), `id`, `status: "RUNNING"`, `expiresAt`, `region`, `keepAlive`, `contextId`. A create is retried safely (idempotency key). |
-| `sessions.retrieve`, `sessions.list({ status })` | Solari `active/released/expired/unknown` map to `RUNNING/COMPLETED/TIMED_OUT/ERROR`. `proxyBytes` is `0`, `startedAt` is the create time. |
+| `sessions.retrieve`, `sessions.list({ status, q })` | Solari `active/released/expired/unknown` map to `RUNNING/COMPLETED/TIMED_OUT/ERROR`. `list` returns **every** matching session: it follows the gateway's pages to the end (it stops with a `BrowserbaseError` after 1000 pages, or if the gateway repeats a page cursor). See [Reported as unknown](#reported-as-unknown-or-empty) for the fields Solari does not have. |
 | `sessions.update(id, { status: "REQUEST_RELEASE" })` | Releases the session. |
 | `proxies: true`, `proxies: [{ type: "browserbase", geolocation }]` | A managed proxy; `geolocation.country/state/city` map across (a proxy needs the stealth browser, so `stealth` is switched on for you). `{ type: "none" }` means no proxy. |
 | `browserSettings.verified`, `advancedStealth` | Solari's stealth browser. |
@@ -43,9 +45,25 @@ Keep it private: the session id inside it is the credential.
 - **Recording is a DOM-event log, not video.** `sessions.recording.retrieve(id)` returns rrweb events once the replay has been uploaded (a few seconds after release; until then it throws `APIError` with `code: "ReplayPending"`). There is no HLS playlist and no MP4.
 - **Contexts store cookies and localStorage only** (Playwright `storageState`), not IndexedDB, service workers or autofill data.
 - **No choice of operating system or viewport at create time (known gap).** A `viewport` setting is accepted with a one-line warning and has no effect; set the viewport from your automation client (`page.setViewportSize`). `strict: true` makes it throw instead.
-- **`timeout`, `keepAlive` and `userMetadata` work as in Browserbase.** `timeout` (seconds, at least 60) ends the session at that time, capped at your plan's maximum session length. `keepAlive: true` keeps the session after your client disconnects, until its `timeout` (default 1 hour), the plan maximum, or `sessions.update(..., REQUEST_RELEASE)`. `userMetadata` (up to 50 keys, 8 KB) is stored, returned by `retrieve`/`list`, and filterable with `sessions.list({ q: "user_metadata['key']:'value'" })` (conditions joined with `AND`).
+- **`api_timeout`, `keepAlive` and `userMetadata` work as in Browserbase.** `api_timeout` (seconds, at least 60; Browserbase's name for the session timeout) ends the session at that time, capped at your plan's maximum session length. `keepAlive: true` keeps the session after your client disconnects, until its `api_timeout` (default 1 hour), the plan maximum, or `sessions.update(..., REQUEST_RELEASE)`. `userMetadata` (up to 50 keys, 8 KB) is stored, returned by `retrieve`/`list`, and filterable with `sessions.list({ q: "user_metadata['key']:'value'" })` (conditions joined with `AND`).
+- **The session timeout is `api_timeout`; `timeout` is the request timeout.** As in Browserbase's SDK, a lone `sessions.create({ timeout: 5000 })` is the *options* argument (a request timeout in ms), not a session setting. The older spelling `timeout` (seconds) is still read as the session timeout when it sits next to other params (`create({ timeout: 300, keepAlive: true })`); passing it together with a different `api_timeout` throws. Use `api_timeout`.
+- **`keepAlive` is remembered in the session's user metadata.** The Solari gateway does not return `keepAlive` when you retrieve or list a session. With `keepAlive: true`, `sessions.create` therefore also stores one reserved user metadata key, `solari_compat_keep_alive`, and `retrieve` / `list` read it back (and remove it from the `userMetadata` you see). Consequences: the key is reserved (using it yourself throws), `keepAlive: true` leaves room for 49 of your own metadata keys (50 throws), and **a session that was not created through this package (version 0.3.0 or later) reports `keepAlive: false` even if it was created with keep-alive**, because the gateway does not say.
 - **`viewport`, `blockAds: true`, `logSession: true`, `os`** are accepted with a one-line warning and have no effect. Pass `strict: true` to make them throw instead.
 
+## Reported as unknown or empty
+Solari has no equivalent for these fields of Browserbase's objects, so they carry a fixed value instead of a made-up one:
+
+| Field | Value |
+|---|---|
+| `Session.projectId`, `Context.projectId` | `""` (no projects) |
+| `Session.updatedAt`, `Session.startedAt` | the create time |
+| `Session.proxyBytes` | `0` |
+| `Session.region` | `us-west-2` (Solari's single region) |
+| `Session.endedAt` | the expiry time for a `TIMED_OUT` session; absent for a released one (the gateway does not say when), except in the answer to your own `sessions.update(..., REQUEST_RELEASE)`, where it is the time of that call |
+| `Context.updatedAt` | the profile's last update when the gateway reports one, else its creation time |
+| `ContextCreateResponse.publicKey`, `cipherAlgorithm`, `initializationVectorSize`, `uploadUrl` | `""` / `0` (Solari profiles are stored server-side, nothing is uploaded) |
+| `SessionCreateResponse.seleniumRemoteUrl`, `signingKey` | `""` |
+
 ## Contexts
 ```ts
 const ctx = await bb.contexts.create({ name: "shop-login" });
@@ -62,4 +80,11 @@ const page = await (await b2.newContext({ storageState: s2.storageState })).newP
 Two differences from Browserbase: a saved context's **cookies** are also present in the default browser context (`browser.contexts()[0]`), but localStorage is applied only to a browser context created *with* the state (use `newContext({ storageState })` to get both), and `persist: true` saves when you release **through the same client object** (it is remembered in memory).
 
 ## Raises `SolariCompatUnsupported`
-Extensions (`extensionId`), the Selenium endpoint (`seleniumRemoteUrl` is always empty), downloads (`sessions.downloads`) and uploads (`sessions.uploads`) APIs, video replays (`sessions.replays`), session logs (`sessions.logs`), external/bring-your-own proxies, per-domain proxy rules (`domainPattern`), custom CA certificates, `ignoreCertificateErrors: true`, custom captcha selectors, `os: "mobile" | "tablet"`, a `region` other than `us-west-2` (or `us-west`), `contexts.update`, and the separate `projects`, `extensions`, `agents`, `fetchAPI` and `search` resources.
+Every resource and method of Browserbase's Node SDK exists on the client; these throw, naming the method (for example `secrets.create`), and send nothing:
+
+- **Resources Solari has no equivalent of:** `extensions` (and `extensionId`), `projects` (`retrieve`, `list`, `usage`), `agents` and `agents.runs`, `fetchAPI`, `search`, `secrets` (`create`, `retrieve`, `update`, `list`, `delete`, `getPublicKey`), `webhooks` (`create`, `retrieve`, `update`, `list`, `delete`, `rotateSecret`), `navigationPolicies`, `certificates`, `functions.secrets` (`list`, `attach`, `detach`).
+- **Session sub-resources:** `sessions.downloads.list`, `sessions.uploads.create`, `sessions.logs.list`, `sessions.replays` (`retrieve`, `retrievePage`), `sessions.recording.downloads` (`create`, `list`). Recordings are DOM events: use `sessions.recording.retrieve`.
+- **`contexts.update`.**
+- **Raw responses and raw requests:** `.asResponse()` and `.withResponse()` on a returned promise; `client.get/post/put/patch/delete/getAPIList/request` (Browserbase API paths that Solari does not serve).
+- **Settings:** the Selenium endpoint (`seleniumRemoteUrl` is always empty), external/bring-your-own proxies, per-domain proxy rules (`domainPattern`), custom CA certificates, `ignoreCertificateErrors: true`, custom captcha selectors, `riskPolicyId`, `os: "mobile" | "tablet"`, a `region` other than `us-west-2` (or `us-west`).
+- **Any key Solari cannot map is refused, never dropped:** an unknown key in the `sessions.create` params, in `browserSettings`, in `context` (only `id`, `persist`), `viewport` (`width`, `height`), a `proxies` entry, its `geolocation` (`country`, `state`, `city`) or `proxySettings` (`caCertificates`); an unknown key in the query of `sessions.list` (`status`, `q`), `sessions.update` (`status`, `projectId`), `sessions.debug` (`expiresIn`) or `contexts.create` (`name`, `projectId`); an unknown client or per-call option.

package/README.md

@@ -19,8 +19,9 @@ await browser.close();
 await bb.sessions.update(session.id, { status: "REQUEST_RELEASE" });
 ```
 
-Sessions, contexts, live view and recording are supported; extensions, downloads/uploads APIs, video replays,
-bring-your-own proxies and Selenium raise `SolariCompatUnsupported`. See [docs.getsolari.com/browserbase](https://docs.getsolari.com/browserbase) (and `COMPAT.md` in this package) for the full list
+Sessions, contexts, live view and recording are supported. Every other Browserbase resource and method exists but throws
+`SolariCompatUnsupported` naming it (extensions, secrets, webhooks, projects, downloads/uploads APIs, video replays,
+bring-your-own proxies, Selenium, ...). See [docs.getsolari.com/browserbase](https://docs.getsolari.com/browserbase) (and `COMPAT.md` in this package) for the full list
 and every difference. Requires Node 20+. No Playwright version pin is needed: `connectUrl` is a plain CDP endpoint.
 
 Licence: MIT. See `NOTICE`.

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import type { Call, CompatPromise, RequestOptions } from "./options.js";
 import type { Context, ContextCreateResponse, Session, SessionCreateParams, SessionCreateResponse, SessionLiveURLs, SessionRetrieveResponse, SessionStatus } from "./types.js";
 export declare const DEFAULT_BASE_URL = "https://api.getsolari.com";
 export interface BrowserbaseOptions {
@@ -9,76 +10,107 @@ export interface BrowserbaseOptions {
     strict?: boolean;
     /** Called for each soft difference; default console.warn. */
     onWarning?: (message: string) => void;
+    /** Retries for a request that failed with a connection error or 502/503/504 (GET, DELETE and creates only). Default 2. */
     maxRetries?: number;
-    /** Per-request timeout in ms. */
+    /** Per-request timeout in ms. Default 60000. */
     timeout?: number;
-    /** Test hook. */
+    /** A fetch to use instead of the global one (for a proxy, a custom dispatcher, or a test). */
     fetch?: typeof fetch;
+    /** Headers sent on every request. A `null` or `undefined` value removes a header. `Authorization` cannot be set. */
+    defaultHeaders?: Record<string, string | null | undefined>;
+    /** Query parameters sent on every request. */
+    defaultQuery?: Record<string, string | undefined>;
+    /** Not supported: raises. Pass `fetch` with your own dispatcher instead. */
+    httpAgent?: unknown;
 }
 /** Whether a base URL may receive a Solari key: https on a Solari API host, or loopback. */
 export declare function isSolariBaseUrl(raw: string): boolean;
 export declare class Browserbase {
     readonly sessions: Sessions;
     readonly contexts: Contexts;
-    readonly extensions: UnsupportedResource;
-    readonly projects: UnsupportedResource;
-    readonly agents: UnsupportedResource;
-    readonly fetchAPI: UnsupportedResource;
-    readonly search: UnsupportedResource;
+    readonly extensions: import("./unsupported.js").UnsupportedMethods<"create" | "retrieve" | "delete">;
+    readonly projects: import("./unsupported.js").UnsupportedMethods<"retrieve" | "list" | "usage">;
+    readonly agents: {
+        runs: import("./unsupported.js").UnsupportedMethods<"create" | "retrieve" | "list" | "listMessages">;
+        create: (...args: unknown[]) => never;
+        retrieve: (...args: unknown[]) => never;
+        delete: (...args: unknown[]) => never;
+        list: (...args: unknown[]) => never;
+        update: (...args: unknown[]) => never;
+    };
+    readonly fetchAPI: import("./unsupported.js").UnsupportedMethods<"create">;
+    readonly search: import("./unsupported.js").UnsupportedMethods<"web">;
+    readonly certificates: import("./unsupported.js").UnsupportedMethods<"create" | "retrieve" | "delete" | "list">;
+    readonly secrets: import("./unsupported.js").UnsupportedMethods<"create" | "retrieve" | "delete" | "list" | "update" | "getPublicKey">;
+    readonly functions: {
+        secrets: import("./unsupported.js").UnsupportedMethods<"list" | "attach" | "detach">;
+    };
+    readonly webhooks: import("./unsupported.js").UnsupportedMethods<"create" | "retrieve" | "delete" | "list" | "update" | "rotateSecret">;
+    readonly navigationPolicies: import("./unsupported.js").UnsupportedMethods<"create" | "retrieve" | "delete" | "list" | "update">;
     readonly apiKey: string;
     readonly baseURL: string;
+    /** Retries for a failed request (client default; a call can override it). */
+    readonly maxRetries: number;
+    /** Request timeout in ms (client default; a call can override it). */
+    readonly timeout: number;
     /** @internal */ readonly strict: boolean;
     /** @internal */ readonly warn: (m: string) => void;
     private readonly fetchImpl;
-    private readonly maxRetries;
-    private readonly timeoutMs;
+    private readonly defaultHeaders;
+    private readonly defaultQuery;
+    private projectIdWarned;
     /** session id -> profile to save on release (browserSettings.context.persist). In-process only. */
     /** @internal */ readonly persist: Map<string, string>;
     constructor(opts?: BrowserbaseOptions);
-    /** @internal  GET a presigned URL (no Solari auth header). */
-    fetchPublic(url: string): Promise<Response>;
+    get(..._a: unknown[]): never;
+    post(..._a: unknown[]): never;
+    put(..._a: unknown[]): never;
+    patch(..._a: unknown[]): never;
+    delete(..._a: unknown[]): never;
+    getAPIList(..._a: unknown[]): never;
+    request(..._a: unknown[]): never;
+    /** @internal  `projectId` has nothing to select on Solari: say so once per client (or refuse under `strict`). */
+    noteProjectId(where: string): void;
+    /** @internal  GET a presigned URL (no Solari auth header, no default headers). */
+    fetchPublic(url: string, call?: Call, defaultTimeoutMs?: number): Promise<Response>;
     /** @internal */
-    request(method: string, path: string, body?: unknown, opts?: {
-        idempotencyKey?: string;
-    }): Promise<Response>;
+    send(method: string, path: string, body?: unknown, call?: Call): Promise<Response>;
     /** @internal */
-    json<T>(method: string, path: string, body?: unknown, opts?: {
-        idempotencyKey?: string;
-    }): Promise<T>;
+    json<T>(method: string, path: string, body?: unknown, call?: Call): Promise<T>;
 }
-/** A resource whose every method throws SolariCompatUnsupported. */
-export type UnsupportedResource = {
-    [method: string]: (...args: unknown[]) => never;
-};
 declare class Sessions {
     private readonly c;
     readonly recording: Recording;
-    readonly replays: UnsupportedResource;
-    readonly logs: UnsupportedResource;
-    readonly downloads: UnsupportedResource;
-    readonly uploads: UnsupportedResource;
+    readonly replays: import("./unsupported.js").UnsupportedMethods<"retrieve" | "retrievePage">;
+    readonly logs: import("./unsupported.js").UnsupportedMethods<"list">;
+    readonly downloads: import("./unsupported.js").UnsupportedMethods<"list">;
+    readonly uploads: import("./unsupported.js").UnsupportedMethods<"create">;
     constructor(c: Browserbase);
-    create(params?: SessionCreateParams): Promise<SessionCreateResponse>;
-    retrieve(id: string): Promise<SessionRetrieveResponse>;
+    create(params?: SessionCreateParams, options?: RequestOptions): CompatPromise<SessionCreateResponse>;
+    create(options?: RequestOptions): CompatPromise<SessionCreateResponse>;
+    retrieve(id: string, options?: RequestOptions): CompatPromise<SessionRetrieveResponse>;
     list(query?: {
         status?: SessionStatus;
         q?: string;
-    }): Promise<Session[]>;
+    }, options?: RequestOptions): CompatPromise<Session[]>;
+    list(options?: RequestOptions): CompatPromise<Session[]>;
     /** `{ status: "REQUEST_RELEASE" }` releases the session (saving the context first when it was created with persist: true). */
     update(id: string, params: {
         status: "REQUEST_RELEASE";
         projectId?: string;
-    }): Promise<Session>;
+    }, options?: RequestOptions): CompatPromise<Session>;
     /** Live-view links. Both URLs are the same view-only share link; `pages` is empty. */
     debug(id: string, query?: {
         expiresIn?: number;
-    }): Promise<SessionLiveURLs>;
+    }, options?: RequestOptions): CompatPromise<SessionLiveURLs>;
+    debug(id: string, options?: RequestOptions): CompatPromise<SessionLiveURLs>;
 }
 declare class Recording {
     private readonly c;
+    readonly downloads: import("./unsupported.js").UnsupportedMethods<"create" | "list">;
     constructor(c: Browserbase);
     /** The session's DOM recording as an array of rrweb events. Needs `browserSettings: { recordSession: true }`; available a few seconds after release. */
-    retrieve(id: string): Promise<unknown[]>;
+    retrieve(id: string, options?: RequestOptions): CompatPromise<unknown[]>;
 }
 declare class Contexts {
     private readonly c;
@@ -87,9 +119,10 @@ declare class Contexts {
     create(params?: {
         projectId?: string;
         name?: string;
-    }): Promise<ContextCreateResponse>;
-    retrieve(id: string): Promise<Context>;
-    update(): never;
-    delete(id: string): Promise<void>;
+    }, options?: RequestOptions): CompatPromise<ContextCreateResponse>;
+    create(options?: RequestOptions): CompatPromise<ContextCreateResponse>;
+    retrieve(id: string, options?: RequestOptions): CompatPromise<Context>;
+    update(..._a: unknown[]): never;
+    delete(id: string, options?: RequestOptions): CompatPromise<void>;
 }
 export {};

package/dist/client.js

@@ -1,8 +1,11 @@
 import { gunzipSync } from "node:zlib";
-import { APIError, BrowserbaseError, SolariCompatUnsupported, apiErrorFor, connectionErrorFor } from "./errors.js";
-import { mapCreateParams, mapStatus } from "./mapping.js";
+import { APIError, APIUserAbortError, BrowserbaseError, NotFoundError, SolariCompatUnsupported, apiErrorFor, connectionErrorFor } from "./errors.js";
+import { KEEP_ALIVE_KEY, mapCreateParams, mapStatus } from "./mapping.js";
+import { assertHeaders, compat, followUp, resolveOptions, setHeader, splitArgs } from "./options.js";
+import { unsupportedMethods } from "./unsupported.js";
 export const DEFAULT_BASE_URL = "https://api.getsolari.com";
 const REGION = "us-west-2"; // reported for Browserbase-shaped objects; Solari's single region (us-west)
+const CLIENT_OPTION_KEYS = new Set(["apiKey", "baseURL", "strict", "onWarning", "maxRetries", "timeout", "fetch", "defaultHeaders", "defaultQuery", "httpAgent"]);
 function resolveApiKey(explicit, warn) {
     const sources = [
         ["apiKey", explicit],
@@ -61,21 +64,51 @@ function sleep(ms) {
 export class Browserbase {
     sessions;
     contexts;
-    extensions;
-    projects;
-    agents;
-    fetchAPI;
-    search;
+    extensions = unsupportedMethods("extensions", "browser extensions cannot be loaded", ["create", "retrieve", "delete"]);
+    projects = unsupportedMethods("projects", "Solari keys are organisation-scoped; there are no projects", ["retrieve", "list", "usage"]);
+    agents = {
+        ...unsupportedMethods("agents", "Browserbase Agents is a separate product", ["create", "retrieve", "update", "list", "delete"]),
+        runs: unsupportedMethods("agents.runs", "Browserbase Agents is a separate product", ["create", "retrieve", "list", "listMessages"]),
+    };
+    fetchAPI = unsupportedMethods("fetchAPI", "Browserbase Fetch is a separate product", ["create"]);
+    search = unsupportedMethods("search", "Browserbase Search is a separate product", ["web"]);
+    certificates = unsupportedMethods("certificates", "custom CA certificates are not supported", ["create", "retrieve", "list", "delete"]);
+    secrets = unsupportedMethods("secrets", "Solari has no secret store for Browserbase Functions", ["create", "retrieve", "update", "list", "delete", "getPublicKey"]);
+    functions = {
+        secrets: unsupportedMethods("functions.secrets", "Browserbase Functions is a separate product", ["list", "attach", "detach"]),
+    };
+    webhooks = unsupportedMethods("webhooks", "Solari does not offer webhooks", ["create", "retrieve", "update", "list", "delete", "rotateSecret"]);
+    navigationPolicies = unsupportedMethods("navigationPolicies", "Solari has no stored navigation policies; pass browserSettings.allowedDomains for an egress allowlist", ["create", "retrieve", "update", "list", "delete"]);
     apiKey;
     baseURL;
+    /** Retries for a failed request (client default; a call can override it). */
+    maxRetries;
+    /** Request timeout in ms (client default; a call can override it). */
+    timeout;
     /** @internal */ strict;
     /** @internal */ warn;
     fetchImpl;
-    maxRetries;
-    timeoutMs;
+    defaultHeaders;
+    defaultQuery;
+    projectIdWarned = false;
     /** session id -> profile to save on release (browserSettings.context.persist). In-process only. */
     /** @internal */ persist = new Map();
     constructor(opts = {}) {
+        for (const k of Object.keys(opts)) {
+            if (opts[k] === undefined)
+                continue;
+            if (k === "httpAgent")
+                throw new SolariCompatUnsupported("client option httpAgent", "pass fetch with your own dispatcher instead");
+            if (!CLIENT_OPTION_KEYS.has(k))
+                throw new SolariCompatUnsupported(`client option ${k}`, "not an option of this client");
+        }
+        if (opts.maxRetries !== undefined && !(Number.isInteger(opts.maxRetries) && opts.maxRetries >= 0)) {
+            throw new BrowserbaseError("maxRetries must be a non-negative integer");
+        }
+        if (opts.timeout !== undefined && !(typeof opts.timeout === "number" && opts.timeout > 0)) {
+            throw new BrowserbaseError("timeout must be a positive number of milliseconds");
+        }
+        assertHeaders(opts.defaultHeaders, "client option defaultHeaders");
         this.warn = opts.onWarning ?? ((m) => console.warn(`[solari-browserbase-compat] ${m}`));
         // Non-enumerable so console.log(client) / JSON.stringify(client) never print the key.
         Object.defineProperty(this, "apiKey", { value: resolveApiKey(opts.apiKey, this.warn), enumerable: false });
@@ -83,61 +116,106 @@ export class Browserbase {
         this.strict = opts.strict === true;
         this.fetchImpl = opts.fetch ?? fetch;
         this.maxRetries = opts.maxRetries ?? 2;
-        this.timeoutMs = opts.timeout ?? 60_000;
+        this.timeout = opts.timeout ?? 60_000;
+        this.defaultHeaders = { ...(opts.defaultHeaders ?? {}) };
+        this.defaultQuery = { ...(opts.defaultQuery ?? {}) };
         this.sessions = new Sessions(this);
         this.contexts = new Contexts(this);
-        this.extensions = unsupported("extensions", "browser extensions cannot be loaded");
-        this.projects = unsupported("projects", "Solari keys are organisation-scoped; there are no projects");
-        this.agents = unsupported("agents", "Browserbase Agents is a separate product");
-        this.fetchAPI = unsupported("fetchAPI", "Browserbase Fetch is a separate product");
-        this.search = unsupported("search", "Browserbase Search is a separate product");
     }
-    /** @internal  GET a presigned URL (no Solari auth header). */
-    async fetchPublic(url) {
+    // Browserbase's raw HTTP escape hatches address Browserbase's own API paths, which Solari does not serve.
+    get(..._a) { throw rawUnsupported("get"); }
+    post(..._a) { throw rawUnsupported("post"); }
+    put(..._a) { throw rawUnsupported("put"); }
+    patch(..._a) { throw rawUnsupported("patch"); }
+    delete(..._a) { throw rawUnsupported("delete"); }
+    getAPIList(..._a) { throw rawUnsupported("getAPIList"); }
+    request(..._a) { throw rawUnsupported("request"); }
+    /** @internal  `projectId` has nothing to select on Solari: say so once per client (or refuse under `strict`). */
+    noteProjectId(where) {
+        if (this.strict)
+            throw new SolariCompatUnsupported(`${where} projectId`, "Solari keys belong to an organisation; there are no projects");
+        if (this.projectIdWarned)
+            return;
+        this.projectIdWarned = true;
+        this.warn("projectId is ignored: Solari keys belong to an organisation; there are no projects.");
+    }
+    /** @internal  GET a presigned URL (no Solari auth header, no default headers). */
+    async fetchPublic(url, call = {}, defaultTimeoutMs = 15_000) {
         const ac = new AbortController();
-        const timer = setTimeout(() => ac.abort(), 15_000);
+        const detach = linkSignal(ac, call.signal);
+        const timer = setTimeout(() => ac.abort(), call.timeout ?? defaultTimeoutMs);
         try {
             return await this.fetchImpl(url, { signal: ac.signal });
         }
+        catch (e) {
+            if (call.signal?.aborted)
+                throw new APIUserAbortError();
+            throw connectionErrorFor(e);
+        }
         finally {
             clearTimeout(timer);
+            detach();
         }
     }
     /** @internal */
-    async request(method, path, body, opts) {
+    async send(method, path, body, call = {}) {
         const headers = { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" };
-        if (opts?.idempotencyKey)
-            headers["Idempotency-Key"] = opts.idempotencyKey;
-        const replaySafe = method === "GET" || method === "DELETE" || opts?.idempotencyKey !== undefined;
+        for (const [k, v] of Object.entries(this.defaultHeaders))
+            setHeader(headers, k, v);
+        for (const [k, v] of Object.entries(call.headers ?? {}))
+            setHeader(headers, k, v);
+        if (call.idempotencyKey)
+            headers["Idempotency-Key"] = call.idempotencyKey;
+        // Extra query parameters are appended (percent-encoded) rather than re-serialising the path's own query.
+        const extra = [...Object.entries(this.defaultQuery), ...Object.entries(call.query ?? {})]
+            .filter(([, v]) => v !== undefined && v !== null)
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+        const url = `${this.baseURL}${path}${extra.length > 0 ? (path.includes("?") ? "&" : "?") + extra.join("&") : ""}`;
+        if (call.body !== undefined) {
+            if (method === "GET")
+                throw new SolariCompatUnsupported("request option body", "a GET has no body");
+            body = { ...(body ?? {}), ...call.body };
+        }
+        const maxRetries = call.maxRetries ?? this.maxRetries;
+        const timeoutMs = call.timeout ?? this.timeout;
+        const replaySafe = method === "GET" || method === "DELETE" || call.idempotencyKey !== undefined;
         let lastErr;
-        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            if (call.signal?.aborted)
+                throw new APIUserAbortError();
             const ac = new AbortController();
-            const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+            const detach = linkSignal(ac, call.signal);
+            const timer = setTimeout(() => ac.abort(), timeoutMs);
             try {
-                const res = await this.fetchImpl(`${this.baseURL}${path}`, {
+                const res = await this.fetchImpl(url, {
                     method,
                     headers,
                     body: body === undefined ? undefined : JSON.stringify(body),
                     signal: ac.signal,
                 });
                 clearTimeout(timer);
-                if (res.ok || !replaySafe || ![502, 503, 504].includes(res.status) || attempt === this.maxRetries)
+                if (res.ok || !replaySafe || ![502, 503, 504].includes(res.status) || attempt === maxRetries)
                     return res;
                 await res.text().catch(() => { });
             }
             catch (e) {
                 clearTimeout(timer);
-                if (!replaySafe || attempt === this.maxRetries)
+                if (call.signal?.aborted)
+                    throw new APIUserAbortError();
+                if (!replaySafe || attempt === maxRetries)
                     throw connectionErrorFor(e);
                 lastErr = e;
             }
+            finally {
+                detach();
+            }
             await sleep(300 * (attempt + 1));
         }
         throw connectionErrorFor(lastErr ?? new Error("request failed"));
     }
     /** @internal */
-    async json(method, path, body, opts) {
-        const res = await this.request(method, path, body, opts);
+    async json(method, path, body, call = {}) {
+        const res = await this.send(method, path, body, call);
         if (res.status === 204)
             return undefined;
         const text = await res.text();
@@ -155,45 +233,51 @@ export class Browserbase {
         return parsed;
     }
 }
-class UnsupportedImpl {
-    feature;
-    hint;
-    constructor(feature, hint) {
-        this.feature = feature;
-        this.hint = hint;
-        // Every method on this object throws; a Proxy keeps the surface open-ended (create/list/retrieve/...).
-        return new Proxy(this, {
-            get: (target, prop) => {
-                if (typeof prop === "symbol" || prop === "then" || prop in target)
-                    return Reflect.get(target, prop);
-                return () => {
-                    throw new SolariCompatUnsupported(`${target.feature}.${prop}`, target.hint);
-                };
-            },
-        });
-    }
+function rawUnsupported(method) {
+    return new SolariCompatUnsupported(`client.${method}()`, "Browserbase's raw HTTP methods address its own API paths, which Solari does not serve");
 }
-function unsupported(feature, hint) {
-    return new UnsupportedImpl(feature, hint);
+/** Abort `ac` when the caller's signal aborts. Returns the function that detaches the listener. */
+function linkSignal(ac, signal) {
+    if (!signal)
+        return () => { };
+    if (signal.aborted) {
+        ac.abort();
+        return () => { };
+    }
+    const on = () => ac.abort();
+    signal.addEventListener("abort", on, { once: true });
+    return () => signal.removeEventListener("abort", on);
 }
 function newKey() {
     return globalThis.crypto?.randomUUID?.() ?? `bbc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
 }
+/** The keepAlive flag and the user's own metadata, from what the gateway stored (see KEEP_ALIVE_KEY). */
+function splitMetadata(md) {
+    if (!md || typeof md !== "object")
+        return { keepAlive: false };
+    const { [KEEP_ALIVE_KEY]: marker, ...rest } = md;
+    return { keepAlive: marker === true, ...(Object.keys(rest).length > 0 ? { userMetadata: rest } : {}) };
+}
 function toSession(row, extra = {}) {
     const created = row.createdAt ?? new Date().toISOString();
     const status = extra.status ?? mapStatus(row.status);
+    const expiresAt = row.expiresAt ?? created;
+    const meta = splitMetadata(row.userMetadata);
+    // Only report an end time we know: the release call knows it (now); a timed-out session ended at its deadline; the
+    // gateway does not record when a released session ended, so that is left out rather than invented.
+    const endedAt = extra.endedAt ?? (status === "TIMED_OUT" && row.expiresAt ? row.expiresAt : undefined);
     return {
         id: row.id,
         createdAt: created,
         updatedAt: created,
         projectId: "",
         startedAt: created,
-        ...(status === "COMPLETED" || status === "TIMED_OUT" ? { endedAt: new Date().toISOString() } : {}),
-        expiresAt: row.expiresAt ?? created,
+        ...(endedAt ? { endedAt } : {}),
+        expiresAt,
         status,
         proxyBytes: 0,
-        keepAlive: extra.keepAlive ?? false,
-        ...(row.userMetadata ? { userMetadata: row.userMetadata } : {}),
+        keepAlive: extra.keepAlive ?? meta.keepAlive,
+        ...(meta.userMetadata ? { userMetadata: meta.userMetadata } : {}),
         ...(extra.contextId ? { contextId: extra.contextId } : {}),
         region: REGION,
     };
@@ -201,102 +285,151 @@ function toSession(row, extra = {}) {
 function withConnect(s, cdp) {
     return { ...s, connectUrl: cdp, seleniumRemoteUrl: "", signingKey: "" };
 }
+function onlyParams(obj, known, feature) {
+    for (const k of Object.keys(obj ?? {})) {
+        if (!known.includes(k))
+            throw new SolariCompatUnsupported(`${feature}.${k}`, "this parameter is not supported");
+    }
+}
+const MAX_LIST_PAGES = 1000;
 class Sessions {
     c;
     recording;
-    replays;
-    logs;
-    downloads;
-    uploads;
+    replays = unsupportedMethods("sessions.replays", "Solari records DOM events, not video; use sessions.recording.retrieve", ["retrieve", "retrievePage"]);
+    logs = unsupportedMethods("sessions.logs", "session command logs are not available", ["list"]);
+    downloads = unsupportedMethods("sessions.downloads", "file downloads cannot be retrieved through the API", ["list"]);
+    uploads = unsupportedMethods("sessions.uploads", "use your automation client's setInputFiles", ["create"]);
     constructor(c) {
         this.c = c;
         this.recording = new Recording(c);
-        this.replays = unsupported("sessions.replays", "Solari records DOM events, not video; use sessions.recording.retrieve");
-        this.logs = unsupported("sessions.logs", "session command logs are not available");
-        this.downloads = unsupported("sessions.downloads", "file downloads cannot be retrieved through the API");
-        this.uploads = unsupported("sessions.uploads", "use your automation client's setInputFiles");
     }
-    async create(params) {
-        const mapped = mapCreateParams(params, this.c.strict);
-        for (const w of mapped.warnings)
-            this.c.warn(w);
-        const data = await this.c.json("POST", "/sessions", Object.keys(mapped.body).length ? mapped.body : undefined, { idempotencyKey: newKey() });
-        if (!data?.sessionId || !data.cdpEndpoint) {
-            throw new BrowserbaseError(`Solari returned an unexpected session response: ${JSON.stringify(data)}`);
-        }
-        if (mapped.persistProfileId)
-            this.c.persist.set(data.sessionId, mapped.persistProfileId);
-        const ctx = params?.browserSettings?.context?.id;
-        const s = toSession({
-            id: data.sessionId,
-            status: "active",
-            createdAt: new Date().toISOString(),
-            ...(data.expiresAt ? { expiresAt: data.expiresAt } : {}),
-            ...(data.userMetadata ? { userMetadata: data.userMetadata } : {}),
-        }, { keepAlive: params?.keepAlive === true, ...(ctx ? { contextId: ctx } : {}), status: "RUNNING" });
-        const out = withConnect(s, data.cdpEndpoint);
-        if (ctx) {
-            let state = data.storageState ?? null;
-            if (!state && data.storageStateUrl?.url) {
-                const r = await this.c.fetchPublic(data.storageStateUrl.url).catch(() => undefined);
-                if (r?.ok)
-                    state = (await r.json().catch(() => null));
-                else
-                    this.c.warn("could not download the saved context; the session starts without it");
+    create(first, second) {
+        return compat(async () => {
+            const [params, options] = splitArgs(first, second);
+            const call = resolveOptions(options, { body: true, idempotencyKey: true }, "sessions.create");
+            const mapped = mapCreateParams(params, this.c.strict);
+            if (params?.projectId !== undefined)
+                this.c.noteProjectId("sessions.create");
+            for (const w of mapped.warnings)
+                this.c.warn(w);
+            const data = await this.c.json("POST", "/sessions", Object.keys(mapped.body).length ? mapped.body : undefined, { ...call, idempotencyKey: call.idempotencyKey ?? newKey() });
+            if (!data?.sessionId || !data.cdpEndpoint) {
+                throw new BrowserbaseError(`Solari returned an unexpected session response: ${JSON.stringify(data)}`);
             }
-            out.storageState = state;
-        }
-        return out;
+            if (mapped.persistProfileId)
+                this.c.persist.set(data.sessionId, mapped.persistProfileId);
+            const ctx = params?.browserSettings?.context?.id;
+            const s = toSession({
+                id: data.sessionId,
+                status: "active",
+                createdAt: new Date().toISOString(),
+                ...(data.expiresAt ? { expiresAt: data.expiresAt } : {}),
+                ...(data.userMetadata ? { userMetadata: data.userMetadata } : {}),
+            }, { keepAlive: params?.keepAlive === true, ...(ctx ? { contextId: ctx } : {}), status: "RUNNING" });
+            const out = withConnect(s, data.cdpEndpoint);
+            if (ctx) {
+                let state = data.storageState ?? null;
+                if (!state && data.storageStateUrl?.url) {
+                    const r = await this.c.fetchPublic(data.storageStateUrl.url, followUp(call)).catch(() => undefined);
+                    if (r?.ok)
+                        state = (await r.json().catch(() => null));
+                    else
+                        this.c.warn("could not download the saved context; the session starts without it");
+                }
+                out.storageState = state;
+            }
+            return out;
+        });
     }
-    async retrieve(id) {
-        const row = await this.c.json("GET", `/sessions/${encodeURIComponent(id)}`);
-        return withConnect(toSession({ ...row, id: row.id ?? id }), row.cdpEndpoint ?? "");
+    retrieve(id, options) {
+        return compat(async () => {
+            const call = resolveOptions(options, {}, "sessions.retrieve");
+            const row = await this.c.json("GET", `/sessions/${encodeURIComponent(id)}`, undefined, call);
+            return withConnect(toSession({ ...row, id: row.id ?? id }), row.cdpEndpoint ?? "");
+        });
     }
-    async list(query) {
-        const data = await this.c.json("GET", query?.q ? `/sessions?q=${encodeURIComponent(query.q)}` : "/sessions");
-        const all = (data?.sessions ?? []).map((r) => toSession(r));
-        return query?.status ? all.filter((s) => s.status === query.status) : all;
+    list(first, second) {
+        return compat(async () => {
+            const [query, options] = splitArgs(first, second);
+            onlyParams(query, ["status", "q"], "sessions.list");
+            const call = resolveOptions(options, {}, "sessions.list");
+            // The gateway answers in pages (100 by default); Browserbase's list is the whole list, so follow the cursor.
+            const rows = [];
+            let cursor;
+            for (let page = 0;; page++) {
+                if (page >= MAX_LIST_PAGES)
+                    throw new BrowserbaseError(`sessions.list: more than ${MAX_LIST_PAGES} pages; narrow it with q`);
+                const qs = [];
+                if (query?.q)
+                    qs.push(`q=${encodeURIComponent(query.q)}`);
+                if (cursor)
+                    qs.push(`cursor=${encodeURIComponent(cursor)}`);
+                const data = await this.c.json("GET", qs.length > 0 ? `/sessions?${qs.join("&")}` : "/sessions", undefined, call);
+                rows.push(...(data?.sessions ?? []));
+                if (!data?.nextCursor)
+                    break;
+                if (data.nextCursor === cursor)
+                    throw new BrowserbaseError("sessions.list: the gateway's cursor did not advance");
+                cursor = data.nextCursor;
+            }
+            const all = rows.map((r) => toSession(r));
+            return query?.status ? all.filter((s) => s.status === query.status) : all;
+        });
     }
     /** `{ status: "REQUEST_RELEASE" }` releases the session (saving the context first when it was created with persist: true). */
-    async update(id, params) {
-        if (params?.status !== "REQUEST_RELEASE")
-            throw new SolariCompatUnsupported(`sessions.update status ${String(params?.status)}`, "only REQUEST_RELEASE exists");
-        const profileId = this.c.persist.get(id);
-        if (profileId) {
-            await this.c.json("POST", `/sessions/${encodeURIComponent(id)}/save-profile`, { profileId });
-            this.c.persist.delete(id);
-        }
-        await this.c.json("DELETE", `/sessions/${encodeURIComponent(id)}`);
-        return toSession({ id, status: "released" }, { status: "COMPLETED" });
+    update(id, params, options) {
+        return compat(async () => {
+            onlyParams(params, ["status", "projectId"], "sessions.update");
+            const call = resolveOptions(options, {}, "sessions.update");
+            if (params?.status !== "REQUEST_RELEASE")
+                throw new SolariCompatUnsupported(`sessions.update status ${String(params?.status)}`, "only REQUEST_RELEASE exists");
+            if (params.projectId !== undefined)
+                this.c.noteProjectId("sessions.update");
+            const profileId = this.c.persist.get(id);
+            if (profileId) {
+                await this.c.json("POST", `/sessions/${encodeURIComponent(id)}/save-profile`, { profileId }, call);
+                this.c.persist.delete(id);
+            }
+            await this.c.json("DELETE", `/sessions/${encodeURIComponent(id)}`, undefined, call);
+            return toSession({ id, status: "released" }, { status: "COMPLETED", endedAt: new Date().toISOString() });
+        });
     }
-    /** Live-view links. Both URLs are the same view-only share link; `pages` is empty. */
-    async debug(id, query) {
-        const share = await this.c.json("POST", `/sessions/${encodeURIComponent(id)}/shares`, query?.expiresIn !== undefined ? { ttlSeconds: query.expiresIn } : {});
-        const row = await this.c.json("GET", `/sessions/${encodeURIComponent(id)}`);
-        return { debuggerFullscreenUrl: share.url, debuggerUrl: share.url, wsUrl: row.cdpEndpoint ?? "", pages: [] };
+    debug(id, first, second) {
+        return compat(async () => {
+            const [query, options] = splitArgs(first, second);
+            onlyParams(query, ["expiresIn"], "sessions.debug");
+            const call = resolveOptions(options, {}, "sessions.debug");
+            const share = await this.c.json("POST", `/sessions/${encodeURIComponent(id)}/shares`, query?.expiresIn !== undefined ? { ttlSeconds: query.expiresIn } : {}, call);
+            const row = await this.c.json("GET", `/sessions/${encodeURIComponent(id)}`, undefined, call);
+            return { debuggerFullscreenUrl: share.url, debuggerUrl: share.url, wsUrl: row.cdpEndpoint ?? "", pages: [] };
+        });
     }
 }
 class Recording {
     c;
+    downloads = unsupportedMethods("sessions.recording.downloads", "Solari records DOM events, not video; use sessions.recording.retrieve", ["create", "list"]);
     constructor(c) {
         this.c = c;
     }
     /** The session's DOM recording as an array of rrweb events. Needs `browserSettings: { recordSession: true }`; available a few seconds after release. */
-    async retrieve(id) {
-        const meta = await this.c.json("GET", `/sessions/${encodeURIComponent(id)}/replay-url`);
-        if (!meta?.url)
-            throw new BrowserbaseError("Solari returned no replay URL");
-        const r = await fetch(meta.url);
-        if (!r.ok)
-            throw new APIError(r.status, `replay download failed: ${r.status}`);
-        let buf = Buffer.from(await r.arrayBuffer());
-        if (buf.length > 2 && buf[0] === 0x1f && buf[1] === 0x8b)
-            buf = gunzipSync(buf);
-        return buf
-            .toString("utf8")
-            .split("\n")
-            .filter((l) => l.trim() !== "")
-            .map((l) => JSON.parse(l));
+    retrieve(id, options) {
+        return compat(async () => {
+            const call = resolveOptions(options, {}, "sessions.recording.retrieve");
+            const meta = await this.c.json("GET", `/sessions/${encodeURIComponent(id)}/replay-url`, undefined, call);
+            if (!meta?.url)
+                throw new BrowserbaseError("Solari returned no replay URL");
+            const r = await this.c.fetchPublic(meta.url, followUp(call), 60_000);
+            if (!r.ok)
+                throw new APIError(r.status, `replay download failed: ${r.status}`);
+            let buf = Buffer.from(await r.arrayBuffer());
+            if (buf.length > 2 && buf[0] === 0x1f && buf[1] === 0x8b)
+                buf = gunzipSync(buf);
+            return buf
+                .toString("utf8")
+                .split("\n")
+                .filter((l) => l.trim() !== "")
+                .map((l) => JSON.parse(l));
+        });
     }
 }
 class Contexts {
@@ -304,22 +437,35 @@ class Contexts {
     constructor(c) {
         this.c = c;
     }
-    /** A Context is a Solari profile (cookies + localStorage). */
-    async create(params) {
-        const p = await this.c.json("POST", "/profiles", { name: params?.name ?? `context-${newKey().slice(0, 8)}` });
-        return { id: p.id, publicKey: "", cipherAlgorithm: "", initializationVectorSize: 0 };
+    create(first, second) {
+        return compat(async () => {
+            const [params, options] = splitArgs(first, second);
+            onlyParams(params, ["projectId", "name"], "contexts.create");
+            const call = resolveOptions(options, { body: true, idempotencyKey: true }, "contexts.create");
+            if (params?.projectId !== undefined)
+                this.c.noteProjectId("contexts.create");
+            const p = await this.c.json("POST", "/profiles", { name: params?.name ?? `context-${newKey().slice(0, 8)}` }, call);
+            return { id: p.id, publicKey: "", cipherAlgorithm: "", initializationVectorSize: 0, uploadUrl: "" };
+        });
     }
-    async retrieve(id) {
-        const list = await this.c.json("GET", "/profiles");
-        const p = (list ?? []).find((x) => x.id === id);
-        if (!p)
-            throw new APIError(404, `context ${id} not found`, "NotFound");
-        return { id: p.id, ...(p.name ? { name: p.name } : {}), ...(p.createdAt ? { createdAt: p.createdAt } : {}) };
+    retrieve(id, options) {
+        return compat(async () => {
+            const call = resolveOptions(options, {}, "contexts.retrieve");
+            const list = await this.c.json("GET", "/profiles", undefined, call);
+            const p = (list ?? []).find((x) => x.id === id);
+            if (!p)
+                throw new NotFoundError(404, `context ${id} not found`, "NotFound");
+            const createdAt = p.createdAt ?? "";
+            return { id: p.id, ...(p.name ? { name: p.name } : {}), createdAt, updatedAt: p.updatedAt ?? createdAt, projectId: "" };
+        });
     }
-    update() {
+    update(..._a) {
         throw new SolariCompatUnsupported("contexts.update", "contexts are saved when a persist:true session is released");
     }
-    async delete(id) {
-        await this.c.json("DELETE", `/profiles/${encodeURIComponent(id)}`);
+    delete(id, options) {
+        return compat(async () => {
+            const call = resolveOptions(options, {}, "contexts.delete");
+            await this.c.json("DELETE", `/profiles/${encodeURIComponent(id)}`, undefined, call);
+        });
     }
 }

package/dist/errors.d.ts

@@ -42,6 +42,10 @@ export declare class APIConnectionError extends BrowserbaseError {
 export declare class APIConnectionTimeoutError extends APIConnectionError {
     constructor(message?: string, cause?: unknown);
 }
+/** The caller aborted the request (the `signal` passed in the request options). Same name as Browserbase's SDK. */
+export declare class APIUserAbortError extends BrowserbaseError {
+    constructor(message?: string);
+}
 /** The APIError subclass for an HTTP status, as Browserbase's SDK raises them. */
 export declare function apiErrorFor(status: number, message: string, code?: string, body?: unknown): APIError;
 /** A fetch failure as a Browserbase-style connection error (abort/timeout vs. everything else). */

package/dist/errors.js

@@ -55,6 +55,12 @@ export class APIConnectionTimeoutError extends APIConnectionError {
         super(message, cause);
     }
 }
+/** The caller aborted the request (the `signal` passed in the request options). Same name as Browserbase's SDK. */
+export class APIUserAbortError extends BrowserbaseError {
+    constructor(message = "Request was aborted.") {
+        super(message);
+    }
+}
 /** The APIError subclass for an HTTP status, as Browserbase's SDK raises them. */
 export function apiErrorFor(status, message, code, body) {
     const C = status === 400 ? BadRequestError

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 import { Browserbase } from "./client.js";
 export { Browserbase, DEFAULT_BASE_URL } from "./client.js";
-export type { BrowserbaseOptions, UnsupportedResource } from "./client.js";
-export { APIConnectionError, APIConnectionTimeoutError, APIError, AuthenticationError, BadRequestError, BrowserbaseError, ConflictError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, SolariCompatUnsupported, UnprocessableEntityError, } from "./errors.js";
+export type { BrowserbaseOptions } from "./client.js";
+export type { UnsupportedResource } from "./unsupported.js";
+export type { RequestOptions } from "./options.js";
+export { CompatPromise } from "./options.js";
+export { APIConnectionError, APIConnectionTimeoutError, APIError, APIUserAbortError, AuthenticationError, BadRequestError, BrowserbaseError, ConflictError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, SolariCompatUnsupported, UnprocessableEntityError, } from "./errors.js";
 export { mapCreateParams, mapStatus } from "./mapping.js";
 export type * from "./types.js";
 export default Browserbase;

package/dist/index.js

@@ -1,5 +1,6 @@
 import { Browserbase } from "./client.js";
 export { Browserbase, DEFAULT_BASE_URL } from "./client.js";
-export { APIConnectionError, APIConnectionTimeoutError, APIError, AuthenticationError, BadRequestError, BrowserbaseError, ConflictError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, SolariCompatUnsupported, UnprocessableEntityError, } from "./errors.js";
+export { CompatPromise } from "./options.js";
+export { APIConnectionError, APIConnectionTimeoutError, APIError, APIUserAbortError, AuthenticationError, BadRequestError, BrowserbaseError, ConflictError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, SolariCompatUnsupported, UnprocessableEntityError, } from "./errors.js";
 export { mapCreateParams, mapStatus } from "./mapping.js";
 export default Browserbase;

package/dist/mapping.d.ts

@@ -7,6 +7,11 @@ export interface MappedCreate {
     /** Soft differences the caller should know about (also emitted via the warn callback). */
     warnings: string[];
 }
+/**
+ * The gateway does not return a session's keepAlive flag, so a keepAlive create also stores this reserved key in the session's
+ * user metadata, and `retrieve` / `list` read the flag back from it (and hide the key). The gateway allows 50 metadata keys.
+ */
+export declare const KEEP_ALIVE_KEY = "solari_compat_keep_alive";
 /**
  * Translate Browserbase `sessions.create` params into a Solari `POST /sessions` body.
  * Hard gaps throw SolariCompatUnsupported. Soft gaps (a setting we cannot honour but whose absence does not change

package/dist/mapping.js

@@ -1,5 +1,29 @@
 import { SolariCompatUnsupported } from "./errors.js";
 const SOLARI_REGION_ALIASES = new Set(["us-west-2"]);
+/**
+ * The gateway does not return a session's keepAlive flag, so a keepAlive create also stores this reserved key in the session's
+ * user metadata, and `retrieve` / `list` read the flag back from it (and hide the key). The gateway allows 50 metadata keys.
+ */
+export const KEEP_ALIVE_KEY = "solari_compat_keep_alive";
+const METADATA_MAX_KEYS = 50;
+const PARAM_KEYS = new Set(["browserSettings", "extensionId", "keepAlive", "projectId", "proxies", "proxySettings", "region", "api_timeout", "timeout", "userMetadata"]);
+const SETTING_KEYS = new Set([
+    "advancedStealth", "allowedDomains", "blockAds", "captchaImageSelector", "captchaInputSelector", "context", "extensionId",
+    "ignoreCertificateErrors", "logSession", "os", "recordSession", "riskPolicyId", "solveCaptchas", "verified", "viewport",
+]);
+/** Raise for any key outside `known`: a dropped key is a silent failure (and for `allowedDomains`-like keys it would fail open). */
+function onlyKeys(obj, known, where) {
+    if (obj === undefined || obj === null || typeof obj !== "object" || Array.isArray(obj))
+        return;
+    for (const k of Object.keys(obj)) {
+        if (!known.has(k))
+            throw new SolariCompatUnsupported(`${where}.${k}`, "this setting is not supported");
+    }
+}
+const CONTEXT_KEYS = new Set(["id", "persist"]);
+const VIEWPORT_KEYS = new Set(["width", "height"]);
+const PROXY_KEYS = new Set(["type", "domainPattern", "geolocation", "server", "username", "password"]);
+const GEO_KEYS = new Set(["country", "state", "city"]);
 function proxyBody(proxies, caCerts) {
     if (caCerts && caCerts.length > 0) {
         throw new SolariCompatUnsupported("proxySettings.caCertificates", "custom CA certificates are not supported");
@@ -14,6 +38,8 @@ function proxyBody(proxies, caCerts) {
         throw new SolariCompatUnsupported("multiple proxies / domain routing rules", "pass at most one managed proxy; per-domain routing is not supported");
     }
     const p = proxies[0];
+    onlyKeys(p, PROXY_KEYS, "proxies[]");
+    onlyKeys(p.geolocation, GEO_KEYS, "proxies[].geolocation");
     if (p.domainPattern !== undefined && p.domainPattern !== "") {
         throw new SolariCompatUnsupported("proxies[].domainPattern", "per-domain proxy routing is not supported");
     }
@@ -42,7 +68,12 @@ function proxyBody(proxies, caCerts) {
  */
 export function mapCreateParams(params, strict) {
     const p = params ?? {};
+    onlyKeys(p, PARAM_KEYS, "sessions.create");
     const bs = p.browserSettings ?? {};
+    onlyKeys(bs, SETTING_KEYS, "browserSettings");
+    onlyKeys(bs.context, CONTEXT_KEYS, "browserSettings.context");
+    onlyKeys(bs.viewport, VIEWPORT_KEYS, "browserSettings.viewport");
+    onlyKeys(p.proxySettings, new Set(["caCertificates"]), "proxySettings");
     const warnings = [];
     const soft = (feature, why) => {
         if (strict)
@@ -50,6 +81,8 @@ export function mapCreateParams(params, strict) {
         warnings.push(`${feature}: ${why}`);
     };
     // ── hard gaps ────────────────────────────────────────────────────────────────
+    if (bs.riskPolicyId !== undefined)
+        throw new SolariCompatUnsupported("browserSettings.riskPolicyId", "risk policies are a Browserbase feature with no Solari equivalent");
     if (p.extensionId || bs.extensionId)
         throw new SolariCompatUnsupported("extensions", "browser extensions cannot be loaded");
     if (bs.ignoreCertificateErrors === true)
@@ -88,12 +121,31 @@ export function mapCreateParams(params, strict) {
         body.allowedDomains = allowedDomains;
     if (bs.context?.id)
         body.profileId = bs.context.id;
-    if (p.timeout !== undefined)
-        body.timeoutSeconds = p.timeout; // the gateway validates (>= 60) and clamps to the plan maximum
+    // Browserbase's name for the session timeout is `api_timeout`; `timeout` next to other params is the older spelling.
+    if (p.api_timeout !== undefined && p.timeout !== undefined && p.api_timeout !== p.timeout) {
+        throw new SolariCompatUnsupported("sessions.create timeout", "api_timeout and timeout are both the session timeout and differ; pass api_timeout only");
+    }
+    const sessionTimeout = p.api_timeout ?? p.timeout;
+    if (sessionTimeout !== undefined)
+        body.timeoutSeconds = sessionTimeout; // the gateway validates (>= 60) and clamps to the plan maximum
     if (p.keepAlive === true)
         body.keepAlive = true;
-    if (p.userMetadata !== undefined)
-        body.userMetadata = p.userMetadata;
+    const um = p.userMetadata;
+    if (um !== undefined && (um === null || typeof um !== "object" || Array.isArray(um))) {
+        throw new SolariCompatUnsupported("userMetadata", "expected an object of key/value pairs");
+    }
+    if (um !== undefined && KEEP_ALIVE_KEY in um) {
+        throw new SolariCompatUnsupported(`userMetadata.${KEEP_ALIVE_KEY}`, "this key is reserved: it records keepAlive so retrieve and list can report it");
+    }
+    if (p.keepAlive === true) {
+        if (um !== undefined && Object.keys(um).length >= METADATA_MAX_KEYS) {
+            throw new SolariCompatUnsupported(`keepAlive with ${Object.keys(um).length} userMetadata keys`, `one of the ${METADATA_MAX_KEYS} metadata keys is reserved for keepAlive; pass at most ${METADATA_MAX_KEYS - 1}`);
+        }
+        body.userMetadata = { ...(um ?? {}), [KEEP_ALIVE_KEY]: true };
+    }
+    else if (um !== undefined) {
+        body.userMetadata = um;
+    }
     return {
         body,
         ...(bs.context?.id && bs.context.persist === true ? { persistProfileId: bs.context.id } : {}),

package/dist/options.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Per-call options, as in Browserbase's SDK. `query`, `headers`, `timeout`, `maxRetries` and `signal` apply to every request a
+ * call makes; `body` and `idempotencyKey` only to calls that create something (`sessions.create`, `contexts.create`).
+ * The rest (`method`, `path`, `stream`, `httpAgent`, `defaultBaseURL`, `__binary*`) raise `SolariCompatUnsupported`.
+ */
+export interface RequestOptions {
+    query?: Record<string, unknown> | undefined;
+    body?: Record<string, unknown> | null | undefined;
+    headers?: Record<string, string | null | undefined> | undefined;
+    /** Retries for this call (overrides the client's). */
+    maxRetries?: number;
+    /** Request timeout in milliseconds (overrides the client's). Not the session timeout: that is `api_timeout` on `sessions.create`. */
+    timeout?: number;
+    signal?: AbortSignal | undefined | null;
+    /** Only on create calls. */
+    idempotencyKey?: string;
+    /** Not supported: raises. */
+    method?: string;
+    path?: string;
+    defaultBaseURL?: string | undefined;
+    stream?: boolean | undefined;
+    httpAgent?: unknown;
+    __binaryRequest?: boolean | undefined;
+    __binaryResponse?: boolean | undefined;
+}
+/** Browserbase's heuristic: a non-empty object whose keys are all request options is the options argument, not the params. */
+export declare function isRequestOptions(o: unknown): o is RequestOptions;
+/** `fn(params?, options?)` and `fn(options?)`: which is which. */
+export declare function splitArgs<P>(first: P | RequestOptions | undefined, second: RequestOptions | undefined): [P | undefined, RequestOptions | undefined];
+/** What a call hands to the HTTP layer. */
+export interface Call {
+    headers?: Record<string, string | null | undefined>;
+    query?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    timeout?: number;
+    maxRetries?: number;
+    signal?: AbortSignal | null;
+    idempotencyKey?: string;
+}
+/** Validate a call's options. Nothing is dropped: an option that cannot be honoured raises. */
+export declare function resolveOptions(options: RequestOptions | undefined, allow: {
+    body?: boolean;
+    idempotencyKey?: boolean;
+}, feature: string): Call;
+/** A call's options for the follow-up requests of a multi-request call: no body, no idempotency key. */
+export declare function followUp(call: Call): Call;
+/** Headers the caller may not set: the key is the client's, not a header to override. */
+export declare function assertHeaders(h: Record<string, string | null | undefined> | undefined, where: string): void;
+export declare function setHeader(target: Record<string, string>, name: string, value: string | null | undefined): void;
+/**
+ * What every method returns. Awaits like a Promise; `asResponse()` and `withResponse()` (Browserbase's APIPromise extras)
+ * raise `SolariCompatUnsupported`, because a call here can be several HTTP requests with no single response.
+ */
+export declare class CompatPromise<T> extends Promise<T> {
+    static get [Symbol.species](): PromiseConstructor;
+    asResponse(): never;
+    withResponse(): never;
+}
+export declare function compat<T>(fn: () => Promise<T>): CompatPromise<T>;

package/dist/options.js

@@ -0,0 +1,112 @@
+import { SolariCompatUnsupported } from "./errors.js";
+const REQUEST_OPTION_KEYS = new Set([
+    "method", "path", "query", "body", "headers", "defaultBaseURL", "maxRetries", "stream", "timeout", "httpAgent", "signal",
+    "idempotencyKey", "__binaryRequest", "__binaryResponse",
+]);
+const REFUSED = {
+    method: "the HTTP method is fixed by the call",
+    path: "the path is fixed by the call",
+    defaultBaseURL: "set baseURL on the client",
+    stream: "responses are not streamed",
+    httpAgent: "pass a fetch with your own dispatcher to the client instead",
+    __binaryRequest: "binary requests are not used",
+    __binaryResponse: "binary responses are not used",
+};
+/** Browserbase's heuristic: a non-empty object whose keys are all request options is the options argument, not the params. */
+export function isRequestOptions(o) {
+    if (!o || typeof o !== "object" || Array.isArray(o))
+        return false;
+    const keys = Object.keys(o);
+    return keys.length > 0 && keys.every((k) => REQUEST_OPTION_KEYS.has(k));
+}
+/** `fn(params?, options?)` and `fn(options?)`: which is which. */
+export function splitArgs(first, second) {
+    if (second === undefined && isRequestOptions(first))
+        return [undefined, first];
+    return [first, second];
+}
+/** Validate a call's options. Nothing is dropped: an option that cannot be honoured raises. */
+export function resolveOptions(options, allow, feature) {
+    if (options === undefined || options === null)
+        return {};
+    if (typeof options !== "object" || Array.isArray(options))
+        throw new SolariCompatUnsupported(`${feature}: request options`, "expected an object");
+    for (const k of Object.keys(options)) {
+        if (options[k] === undefined)
+            continue;
+        if (k in REFUSED)
+            throw new SolariCompatUnsupported(`${feature}: request option ${k}`, REFUSED[k]);
+        if (!REQUEST_OPTION_KEYS.has(k))
+            throw new SolariCompatUnsupported(`${feature}: request option ${k}`, "not a request option");
+    }
+    if (options.body !== undefined && options.body !== null && !allow.body) {
+        throw new SolariCompatUnsupported(`${feature}: request option body`, "this call takes no extra body fields");
+    }
+    if (options.idempotencyKey !== undefined && !allow.idempotencyKey) {
+        throw new SolariCompatUnsupported(`${feature}: request option idempotencyKey`, "only create calls take an idempotency key");
+    }
+    if (options.body !== undefined && options.body !== null && (typeof options.body !== "object" || Array.isArray(options.body))) {
+        throw new SolariCompatUnsupported(`${feature}: request option body`, "expected an object");
+    }
+    if (options.timeout !== undefined && !(typeof options.timeout === "number" && options.timeout > 0)) {
+        throw new SolariCompatUnsupported(`${feature}: request option timeout`, "expected a positive number of milliseconds");
+    }
+    if (options.maxRetries !== undefined && !(Number.isInteger(options.maxRetries) && options.maxRetries >= 0)) {
+        throw new SolariCompatUnsupported(`${feature}: request option maxRetries`, "expected a non-negative integer");
+    }
+    assertHeaders(options.headers, `${feature}: request option headers`);
+    return {
+        ...(options.headers ? { headers: options.headers } : {}),
+        ...(options.query ? { query: options.query } : {}),
+        ...(options.body ? { body: options.body } : {}),
+        ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+        ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
+    };
+}
+/** A call's options for the follow-up requests of a multi-request call: no body, no idempotency key. */
+export function followUp(call) {
+    const { body: _b, idempotencyKey: _i, ...rest } = call;
+    return rest;
+}
+const RESERVED_HEADERS = new Set(["authorization", "idempotency-key"]);
+/** Headers the caller may not set: the key is the client's, not a header to override. */
+export function assertHeaders(h, where) {
+    if (h === undefined)
+        return;
+    if (h === null || typeof h !== "object" || Array.isArray(h))
+        throw new SolariCompatUnsupported(where, "expected an object");
+    for (const k of Object.keys(h)) {
+        if (RESERVED_HEADERS.has(k.toLowerCase()))
+            throw new SolariCompatUnsupported(where, `${k} cannot be set: the client sets it`);
+    }
+}
+export function setHeader(target, name, value) {
+    const lower = name.toLowerCase();
+    for (const k of Object.keys(target))
+        if (k.toLowerCase() === lower)
+            delete target[k];
+    if (value !== null && value !== undefined)
+        target[name] = value;
+}
+/**
+ * What every method returns. Awaits like a Promise; `asResponse()` and `withResponse()` (Browserbase's APIPromise extras)
+ * raise `SolariCompatUnsupported`, because a call here can be several HTTP requests with no single response.
+ */
+export class CompatPromise extends Promise {
+    static get [Symbol.species]() {
+        return Promise;
+    }
+    asResponse() {
+        throw new SolariCompatUnsupported("asResponse()", "a call can make several requests; there is no single Response");
+    }
+    withResponse() {
+        throw new SolariCompatUnsupported("withResponse()", "a call can make several requests; there is no single Response");
+    }
+}
+export function compat(fn) {
+    return new CompatPromise((resolve, reject) => {
+        fn().then(resolve, reject);
+    });
+}

package/dist/types.d.ts

@@ -40,6 +40,8 @@ export interface BrowserSettings {
     verified?: boolean;
     captchaImageSelector?: string;
     captchaInputSelector?: string;
+    /** Not supported: raises. */
+    riskPolicyId?: string;
     os?: "windows" | "mac" | "linux" | "mobile" | "tablet";
     allowedDomains?: string[];
     ignoreCertificateErrors?: boolean;
@@ -48,6 +50,9 @@ export interface SessionCreateParams {
     projectId?: string;
     extensionId?: string;
     browserSettings?: BrowserSettings;
+    /** The session timeout in seconds (Browserbase's name for it). */
+    api_timeout?: number;
+    /** @deprecated The older spelling of `api_timeout`, read only when passed next to other params. A lone `{ timeout }` is the request timeout, as in Browserbase's SDK. */
     timeout?: number;
     keepAlive?: boolean;
     proxies?: boolean | ProxyConfig[];
@@ -107,7 +112,11 @@ export interface SessionLiveURLs {
 export interface Context {
     id: string;
     name?: string;
-    createdAt?: string;
+    createdAt: string;
+    /** Solari does not track when a profile was last saved: the same as `createdAt`. */
+    updatedAt: string;
+    /** Always empty: Solari keys belong to an organisation, there are no projects. */
+    projectId: string;
 }
 export interface ContextCreateResponse {
     id: string;
@@ -115,4 +124,6 @@ export interface ContextCreateResponse {
     publicKey: string;
     cipherAlgorithm: string;
     initializationVectorSize: number;
+    /** Empty: contexts are saved by releasing a `persist: true` session, not by uploading. */
+    uploadUrl: string;
 }

package/dist/unsupported.d.ts

@@ -0,0 +1,9 @@
+/** A resource whose methods all throw SolariCompatUnsupported (kept for the public type; see `unsupportedMethods`). */
+export type UnsupportedResource = {
+    [method: string]: (...args: unknown[]) => never;
+};
+/** A resource with exactly these methods, each of which throws SolariCompatUnsupported naming `<feature>.<method>`. */
+export type UnsupportedMethods<K extends string> = {
+    [P in K]: (...args: unknown[]) => never;
+};
+export declare function unsupportedMethods<const K extends string>(feature: string, hint: string, methods: readonly K[]): UnsupportedMethods<K>;

package/dist/unsupported.js

@@ -0,0 +1,10 @@
+import { SolariCompatUnsupported } from "./errors.js";
+export function unsupportedMethods(feature, hint, methods) {
+    const out = {};
+    for (const m of methods) {
+        out[m] = () => {
+            throw new SolariCompatUnsupported(`${feature}.${m}`, hint);
+        };
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/browserbase-compat",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Drop-in Browserbase-style SDK surface for Solari Browser: sessions, connectUrl (CDP), contexts, live view, replay events.",
   "license": "MIT",
   "type": "module",