@solarisdk/browserbase-compat 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 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.
+
+## 0.2.0
+- `timeout`, `keepAlive` and `userMetadata` are sent to Solari (they were warned about and ignored in 0.1.0). `userMetadata` comes back on `create`, `retrieve` and `list`, and `sessions.list({ q })` filters on it.
+- **A base URL that does not point at Solari is now refused.** `baseURL` and `SOLARI_BASE_URL` must be `https` on `getsolari.com` (or a subdomain) or a loopback address; anything else throws `BrowserbaseError` ("Refusing to send a Solari API key to …"). In 0.1.0 such a URL was used as given, which could send your `slr_` key to another host.
+- Errors use Browserbase's class names: `NotFoundError`, `RateLimitError`, `BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `ConflictError`, `UnprocessableEntityError`, `InternalServerError` (all `APIError` subclasses), `APIConnectionError` and `APIConnectionTimeoutError`. Network failures used to surface as the raw `fetch` error.
+- A saved context's cookies are also present in the browser's default context (`browser.contexts()[0]`).
+- `viewport` at create remains a documented gap (warns; `strict` throws).
+- Added `NOTICE`; README links to docs.getsolari.com.
+
+## 0.1.0
+- First release.

package/COMPAT.md

@@ -22,7 +22,7 @@ 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`. |
+| 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. |
 
 ## Works
@@ -35,16 +35,16 @@ Keep it private: the session id inside it is the credential.
 | `browserSettings.verified`, `advancedStealth` | Solari's stealth browser. |
 | `browserSettings.solveCaptchas: true` | Solari captcha solving (stealth browser, plan-gated). **Off unless you pass `true`**: Browserbase turns it on by default. |
 | `browserSettings.recordSession: true` | Session recording. **Off unless you pass `true`**: Browserbase records by default. Read it back with `sessions.recording.retrieve(id)` (rrweb events). |
-| `browserSettings.allowedDomains` | Egress allowlist (enterprise plan, stealth browser); a plan error comes back as an `APIError` with `code: "FeatureRequiresPlan"`. |
+| `browserSettings.allowedDomains` | Egress allowlist (Team or Enterprise plan, stealth browser); a plan error comes back as an `APIError` with `code: "FeatureRequiresPlan"`. |
 | `browserSettings.context: { id, persist }`, `contexts.create/retrieve/delete` | A Context is a Solari **profile**. See [Contexts](#contexts). |
 | `sessions.debug(id, { expiresIn })` | A view-only live-view link (`debuggerUrl` and `debuggerFullscreenUrl` are the same link; `pages` is empty; `wsUrl` is the CDP URL). |
 
 ## Differs (documented, not errors)
 - **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.** Set the viewport from your automation client.
-- **`keepAlive`**: a disconnected session is released about 45 s after its socket closes (reconnect with the same `connectUrl` inside that window). Sessions end at your plan's maximum session length.
-- **`timeout`, `userMetadata`, `keepAlive: true`, `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.
+- **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`).
+- **`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.
 
 ## Contexts
 ```ts
@@ -59,7 +59,7 @@ const s2 = await bb.sessions.create({ browserSettings: { context: { id: ctx.id }
 const b2 = await chromium.connectOverCDP(s2.connectUrl);
 const page = await (await b2.newContext({ storageState: s2.storageState })).newPage();
 ```
-Two differences from Browserbase: Solari applies a saved context only to a browser context created *with* it (use `newContext({ storageState })`, not `browser.contexts()[0]`), and `persist: true` saves when you release **through the same client object** (it is remembered in memory).
+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`), `sessions.list({ q })` (metadata queries), `contexts.update`, and the separate `projects`, `extensions`, `agents`, `fetchAPI` and `search` resources.
+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.

package/NOTICE

@@ -0,0 +1,10 @@
+Solari Browserbase compatibility SDK
+Copyright (c) 2026 Solari. Licensed under the MIT License (see LICENSE).
+
+This package implements a client whose method names and parameters follow the
+publicly documented Browserbase SDK, so that code written for that SDK can run
+against Solari Browser. It contains no Browserbase source code.
+
+It is not affiliated with, endorsed by, or sponsored by Browserbase, Inc.
+"Browserbase" is a trademark of its owner and is used only to describe API
+compatibility.

package/README.md

@@ -20,7 +20,9 @@ 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 [COMPAT.md](./COMPAT.md) for the full list
+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
 and every difference. Requires Node 20+. No Playwright version pin is needed: `connectUrl` is a plain CDP endpoint.
 
-Licence: MIT.
+Licence: MIT. See `NOTICE`.
+
+This is an independent project. It is not affiliated with, endorsed by, or sponsored by Browserbase, Inc. "Browserbase" is a trademark of its owner and is used here only to describe API compatibility.

package/dist/client.d.ts

@@ -15,6 +15,8 @@ export interface BrowserbaseOptions {
     /** Test hook. */
     fetch?: typeof fetch;
 }
+/** 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;

package/dist/client.js

@@ -1,5 +1,5 @@
 import { gunzipSync } from "node:zlib";
-import { APIError, BrowserbaseError, SolariCompatUnsupported } from "./errors.js";
+import { APIError, BrowserbaseError, SolariCompatUnsupported, apiErrorFor, connectionErrorFor } from "./errors.js";
 import { mapCreateParams, mapStatus } from "./mapping.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)
@@ -19,6 +19,42 @@ function resolveApiKey(explicit, warn) {
     }
     throw new BrowserbaseError("No Solari API key: pass apiKey or set SOLARI_API_KEY (keys start with slr_)");
 }
+/** The only Solari hosts that may receive a key (the API gateways). Not every *.getsolari.com host: preview hosts (<label>-<port>.preview.getsolari.com) serve customer code. */
+const SOLARI_API_HOST = /^api(-sta(-gcp)?)?\.getsolari\.com$/;
+/** Whether a base URL may receive a Solari key: https on a Solari API host, or loopback. */
+export function isSolariBaseUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (u.username || u.password)
+        return false; // never a URL with credentials in it
+    const host = u.hostname.toLowerCase().replace(/\.$/, "");
+    if (u.protocol === "https:" && SOLARI_API_HOST.test(host))
+        return true;
+    const loopback = host === "localhost" || host === "[::1]" || /^127(\.\d{1,3}){3}$/.test(host);
+    return loopback && (u.protocol === "http:" || u.protocol === "https:");
+}
+function describeHost(raw) {
+    try {
+        return new URL(raw).hostname || "unparsable URL";
+    }
+    catch {
+        return "unparsable URL";
+    }
+}
+function resolveBaseUrl(explicit) {
+    const given = explicit || process.env.SOLARI_BASE_URL;
+    if (!given)
+        return DEFAULT_BASE_URL;
+    if (!isSolariBaseUrl(given)) {
+        throw new BrowserbaseError(`Refusing to send a Solari API key to ${describeHost(given)}: it is not a Solari API host or loopback.`);
+    }
+    return given.replace(/\/+$/, "");
+}
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
@@ -43,7 +79,7 @@ export class Browserbase {
         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 });
-        this.baseURL = (opts.baseURL ?? process.env.SOLARI_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.baseURL = resolveBaseUrl(opts.baseURL);
         this.strict = opts.strict === true;
         this.fetchImpl = opts.fetch ?? fetch;
         this.maxRetries = opts.maxRetries ?? 2;
@@ -92,12 +128,12 @@ export class Browserbase {
             catch (e) {
                 clearTimeout(timer);
                 if (!replaySafe || attempt === this.maxRetries)
-                    throw e;
+                    throw connectionErrorFor(e);
                 lastErr = e;
             }
             await sleep(300 * (attempt + 1));
         }
-        throw lastErr instanceof Error ? lastErr : new BrowserbaseError("request failed");
+        throw connectionErrorFor(lastErr ?? new Error("request failed"));
     }
     /** @internal */
     async json(method, path, body, opts) {
@@ -114,7 +150,7 @@ export class Browserbase {
         }
         if (!res.ok) {
             const o = (parsed ?? {});
-            throw new APIError(res.status, `Solari ${method} ${path}: ${res.status} ${o.error ?? text.slice(0, 200)}`, o.code, parsed);
+            throw apiErrorFor(res.status, `Solari ${method} ${path}: ${res.status} ${o.error ?? text.slice(0, 200)}`, o.code, parsed);
         }
         return parsed;
     }
@@ -157,6 +193,7 @@ function toSession(row, extra = {}) {
         status,
         proxyBytes: 0,
         keepAlive: extra.keepAlive ?? false,
+        ...(row.userMetadata ? { userMetadata: row.userMetadata } : {}),
         ...(extra.contextId ? { contextId: extra.contextId } : {}),
         region: REGION,
     };
@@ -190,7 +227,13 @@ class Sessions {
         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 } : {}) }, { keepAlive: params?.keepAlive === true, ...(ctx ? { contextId: ctx } : {}), status: "RUNNING" });
+        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;
@@ -210,9 +253,7 @@ class Sessions {
         return withConnect(toSession({ ...row, id: row.id ?? id }), row.cdpEndpoint ?? "");
     }
     async list(query) {
-        if (query?.q)
-            throw new SolariCompatUnsupported("sessions.list q (userMetadata query)", "metadata is not stored");
-        const data = await this.c.json("GET", "/sessions");
+        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;
     }

package/dist/errors.d.ts

@@ -9,6 +9,43 @@ export declare class APIError extends BrowserbaseError {
     readonly body: unknown;
     constructor(status: number, message: string, code?: string, body?: unknown);
 }
+/** 400 */
+export declare class BadRequestError extends APIError {
+}
+/** 401 */
+export declare class AuthenticationError extends APIError {
+}
+/** 403 */
+export declare class PermissionDeniedError extends APIError {
+}
+/** 404 */
+export declare class NotFoundError extends APIError {
+}
+/** 409 */
+export declare class ConflictError extends APIError {
+}
+/** 422 */
+export declare class UnprocessableEntityError extends APIError {
+}
+/** 429 */
+export declare class RateLimitError extends APIError {
+}
+/** 5xx */
+export declare class InternalServerError extends APIError {
+}
+/** The request never produced an HTTP response (DNS, refused, reset, ...). Same name as Browserbase's SDK. */
+export declare class APIConnectionError extends BrowserbaseError {
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/** The request timed out. */
+export declare class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message?: string, cause?: unknown);
+}
+/** 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). */
+export declare function connectionErrorFor(e: unknown): BrowserbaseError;
 /** A Browserbase feature Solari Browser does not offer (see COMPAT.md). Never silently ignored when it would change results. */
 export declare class SolariCompatUnsupported extends BrowserbaseError {
     readonly feature: string;

package/dist/errors.js

@@ -17,6 +17,66 @@ export class APIError extends BrowserbaseError {
         this.body = body;
     }
 }
+/** 400 */
+export class BadRequestError extends APIError {
+}
+/** 401 */
+export class AuthenticationError extends APIError {
+}
+/** 403 */
+export class PermissionDeniedError extends APIError {
+}
+/** 404 */
+export class NotFoundError extends APIError {
+}
+/** 409 */
+export class ConflictError extends APIError {
+}
+/** 422 */
+export class UnprocessableEntityError extends APIError {
+}
+/** 429 */
+export class RateLimitError extends APIError {
+}
+/** 5xx */
+export class InternalServerError extends APIError {
+}
+/** The request never produced an HTTP response (DNS, refused, reset, ...). Same name as Browserbase's SDK. */
+export class APIConnectionError extends BrowserbaseError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
+}
+/** The request timed out. */
+export class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message = "Request timed out.", cause) {
+        super(message, cause);
+    }
+}
+/** 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
+        : status === 401 ? AuthenticationError
+            : status === 403 ? PermissionDeniedError
+                : status === 404 ? NotFoundError
+                    : status === 409 ? ConflictError
+                        : status === 422 ? UnprocessableEntityError
+                            : status === 429 ? RateLimitError
+                                : status >= 500 ? InternalServerError
+                                    : APIError;
+    return new C(status, message, code, body);
+}
+/** A fetch failure as a Browserbase-style connection error (abort/timeout vs. everything else). */
+export function connectionErrorFor(e) {
+    if (e instanceof BrowserbaseError)
+        return e;
+    const name = e?.name;
+    if (name === "AbortError" || name === "TimeoutError")
+        return new APIConnectionTimeoutError("Request timed out.", e);
+    return new APIConnectionError(`Connection error: ${e?.message ?? "request failed"}`, e);
+}
 /** A Browserbase feature Solari Browser does not offer (see COMPAT.md). Never silently ignored when it would change results. */
 export class SolariCompatUnsupported extends BrowserbaseError {
     feature;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Browserbase } from "./client.js";
 export { Browserbase, DEFAULT_BASE_URL } from "./client.js";
 export type { BrowserbaseOptions, UnsupportedResource } from "./client.js";
-export { APIError, BrowserbaseError, SolariCompatUnsupported } from "./errors.js";
+export { APIConnectionError, APIConnectionTimeoutError, APIError, 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,5 @@
 import { Browserbase } from "./client.js";
 export { Browserbase, DEFAULT_BASE_URL } from "./client.js";
-export { APIError, BrowserbaseError, SolariCompatUnsupported } from "./errors.js";
+export { APIConnectionError, APIConnectionTimeoutError, APIError, 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.js

@@ -62,14 +62,8 @@ export function mapCreateParams(params, strict) {
         throw new SolariCompatUnsupported(`region ${p.region}`, "Solari Browser runs in one region (us-west)");
     }
     // ── soft gaps ────────────────────────────────────────────────────────────────
-    if (p.timeout !== undefined)
-        soft("timeout", "sessions end at your plan's maximum session length, not at this value; call sessions.update to release earlier");
-    if (p.keepAlive === true)
-        soft("keepAlive", "a disconnected session is released about 45 s after the socket closes; reconnect inside that window or hold the connection");
-    if (p.userMetadata !== undefined)
-        soft("userMetadata", "metadata is not stored or queryable");
     if (bs.viewport !== undefined)
-        soft("browserSettings.viewport", "set the viewport from your automation client (page.setViewportSize)");
+        soft("browserSettings.viewport", "known gap: the viewport cannot be set at create; call page.setViewportSize() from your automation client");
     if (bs.blockAds === true)
         soft("browserSettings.blockAds", "ad blocking is not available");
     if (bs.logSession === true)
@@ -94,6 +88,12 @@ 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
+    if (p.keepAlive === true)
+        body.keepAlive = true;
+    if (p.userMetadata !== undefined)
+        body.userMetadata = p.userMetadata;
     return {
         body,
         ...(bs.context?.id && bs.context.persist === true ? { persistProfileId: bs.context.id } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/browserbase-compat",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Drop-in Browserbase-style SDK surface for Solari Browser: sessions, connectUrl (CDP), contexts, live view, replay events.",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,7 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "README.md", "COMPAT.md", "LICENSE"],
+  "files": ["dist", "README.md", "COMPAT.md", "CHANGELOG.md", "LICENSE", "NOTICE"],
   "keywords": ["browserbase", "solari", "browser", "playwright", "puppeteer", "cdp", "compat"],
   "engines": { "node": ">=20" },
   "publishConfig": { "access": "public" },