@solarisdk/browserbase-compat 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 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

@@ -0,0 +1,65 @@
+# Browserbase compatibility — what works, what differs, what raises
+
+`@solarisdk/browserbase-compat` gives Solari Browser the shape of the Browserbase SDK, so code written against
+`new Browserbase({ apiKey })` runs against Solari with the import and the key changed. This page is the full list.
+
+```ts
+import Browserbase from "@solarisdk/browserbase-compat";
+import { chromium } from "playwright-core";
+
+const bb = new Browserbase({ apiKey: process.env.SOLARI_API_KEY }); // slr_… key
+const session = await bb.sessions.create({ browserSettings: { recordSession: true } });
+const browser = await chromium.connectOverCDP(session.connectUrl);  // Puppeteer: puppeteer.connect({ browserWSEndpoint: session.connectUrl })
+// … drive the page …
+await browser.close();
+await bb.sessions.update(session.id, { status: "REQUEST_RELEASE" });
+```
+
+`connectUrl` is a raw CDP websocket URL, so any CDP client works and **nothing needs a pinned Playwright version**.
+Keep it private: the session id inside it is the credential.
+
+## Keys and endpoint
+| | |
+|---|---|
+| 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 `getsolari.com` (or a subdomain) or loopback, 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
+| 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.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. |
+| `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.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 (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
+const ctx = await bb.contexts.create({ name: "shop-login" });
+const s = await bb.sessions.create({ browserSettings: { context: { id: ctx.id, persist: true } } });
+const browser = await chromium.connectOverCDP(s.connectUrl);
+// First run: log in, then release; the context is saved when you release through this client.
+await bb.sessions.update(s.id, { status: "REQUEST_RELEASE" });
+
+// Later: the saved login comes back as `storageState`. Create your browser context with it:
+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: 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @solarisdk/browserbase-compat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Browserbase-shaped SDK for [Solari Browser](https://getsolari.com): change the import and the key, keep your code.
+
+```bash
+npm install @solarisdk/browserbase-compat
+```
+
+```ts
+import Browserbase from "@solarisdk/browserbase-compat";
+import { chromium } from "playwright-core";
+
+const bb = new Browserbase({ apiKey: process.env.SOLARI_API_KEY }); // slr_… key
+const session = await bb.sessions.create();
+const browser = await chromium.connectOverCDP(session.connectUrl);
+const page = browser.contexts()[0].pages()[0] ?? (await browser.contexts()[0].newPage());
+await page.goto("https://example.com");
+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
+and every difference. Requires Node 20+. No Playwright version pin is needed: `connectUrl` is a plain CDP endpoint.
+
+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

@@ -0,0 +1,95 @@
+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 {
+    /** Solari API key (`slr_...`). Falls back to SOLARI_API_KEY, then BROWSERBASE_API_KEY. A key that does not start with `slr_` is never used or sent. */
+    apiKey?: string;
+    /** Gateway base URL. Default https://api.getsolari.com (env SOLARI_BASE_URL). */
+    baseURL?: string;
+    /** Throw SolariCompatUnsupported instead of warning when an ignorable setting (timeout, keepAlive, ...) is passed. */
+    strict?: boolean;
+    /** Called for each soft difference; default console.warn. */
+    onWarning?: (message: string) => void;
+    maxRetries?: number;
+    /** Per-request timeout in ms. */
+    timeout?: number;
+    /** Test hook. */
+    fetch?: typeof fetch;
+}
+/** Whether a base URL may receive a Solari key: https on getsolari.com or a subdomain, 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 apiKey: string;
+    readonly baseURL: string;
+    /** @internal */ readonly strict: boolean;
+    /** @internal */ readonly warn: (m: string) => void;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    /** 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>;
+    /** @internal */
+    request(method: string, path: string, body?: unknown, opts?: {
+        idempotencyKey?: string;
+    }): Promise<Response>;
+    /** @internal */
+    json<T>(method: string, path: string, body?: unknown, opts?: {
+        idempotencyKey?: string;
+    }): 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;
+    constructor(c: Browserbase);
+    create(params?: SessionCreateParams): Promise<SessionCreateResponse>;
+    retrieve(id: string): Promise<SessionRetrieveResponse>;
+    list(query?: {
+        status?: SessionStatus;
+        q?: string;
+    }): Promise<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>;
+    /** Live-view links. Both URLs are the same view-only share link; `pages` is empty. */
+    debug(id: string, query?: {
+        expiresIn?: number;
+    }): Promise<SessionLiveURLs>;
+}
+declare class Recording {
+    private readonly c;
+    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[]>;
+}
+declare class Contexts {
+    private readonly c;
+    constructor(c: Browserbase);
+    /** A Context is a Solari profile (cookies + localStorage). */
+    create(params?: {
+        projectId?: string;
+        name?: string;
+    }): Promise<ContextCreateResponse>;
+    retrieve(id: string): Promise<Context>;
+    update(): never;
+    delete(id: string): Promise<void>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,323 @@
+import { gunzipSync } from "node:zlib";
+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)
+function resolveApiKey(explicit, warn) {
+    const sources = [
+        ["apiKey", explicit],
+        ["SOLARI_API_KEY", process.env.SOLARI_API_KEY],
+        ["BROWSERBASE_API_KEY", process.env.BROWSERBASE_API_KEY],
+    ];
+    for (const [name, v] of sources) {
+        if (!v)
+            continue;
+        if (v.startsWith("slr_"))
+            return v;
+        // Never echo any part of the value: it is probably a Browserbase secret.
+        warn(`${name} does not look like a Solari key (expected the slr_ prefix); ignoring it. It was not sent anywhere.`);
+    }
+    throw new BrowserbaseError("No Solari API key: pass apiKey or set SOLARI_API_KEY (keys start with slr_)");
+}
+/** Whether a base URL may receive a Solari key: https on getsolari.com or a subdomain, 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:" && (host === "getsolari.com" || host.endsWith(".getsolari.com")))
+        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 does not point at Solari (getsolari.com or loopback).`);
+    }
+    return given.replace(/\/+$/, "");
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export class Browserbase {
+    sessions;
+    contexts;
+    extensions;
+    projects;
+    agents;
+    fetchAPI;
+    search;
+    apiKey;
+    baseURL;
+    /** @internal */ strict;
+    /** @internal */ warn;
+    fetchImpl;
+    maxRetries;
+    timeoutMs;
+    /** session id -> profile to save on release (browserSettings.context.persist). In-process only. */
+    /** @internal */ persist = new Map();
+    constructor(opts = {}) {
+        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 = resolveBaseUrl(opts.baseURL);
+        this.strict = opts.strict === true;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.timeoutMs = opts.timeout ?? 60_000;
+        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) {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 15_000);
+        try {
+            return await this.fetchImpl(url, { signal: ac.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** @internal */
+    async request(method, path, body, opts) {
+        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;
+        let lastErr;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+            try {
+                const res = await this.fetchImpl(`${this.baseURL}${path}`, {
+                    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)
+                    return res;
+                await res.text().catch(() => { });
+            }
+            catch (e) {
+                clearTimeout(timer);
+                if (!replaySafe || attempt === this.maxRetries)
+                    throw connectionErrorFor(e);
+                lastErr = e;
+            }
+            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);
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!res.ok) {
+            const o = (parsed ?? {});
+            throw apiErrorFor(res.status, `Solari ${method} ${path}: ${res.status} ${o.error ?? text.slice(0, 200)}`, o.code, parsed);
+        }
+        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 unsupported(feature, hint) {
+    return new UnsupportedImpl(feature, hint);
+}
+function newKey() {
+    return globalThis.crypto?.randomUUID?.() ?? `bbc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+function toSession(row, extra = {}) {
+    const created = row.createdAt ?? new Date().toISOString();
+    const status = extra.status ?? mapStatus(row.status);
+    return {
+        id: row.id,
+        createdAt: created,
+        updatedAt: created,
+        projectId: "",
+        startedAt: created,
+        ...(status === "COMPLETED" || status === "TIMED_OUT" ? { endedAt: new Date().toISOString() } : {}),
+        expiresAt: row.expiresAt ?? created,
+        status,
+        proxyBytes: 0,
+        keepAlive: extra.keepAlive ?? false,
+        ...(row.userMetadata ? { userMetadata: row.userMetadata } : {}),
+        ...(extra.contextId ? { contextId: extra.contextId } : {}),
+        region: REGION,
+    };
+}
+function withConnect(s, cdp) {
+    return { ...s, connectUrl: cdp, seleniumRemoteUrl: "", signingKey: "" };
+}
+class Sessions {
+    c;
+    recording;
+    replays;
+    logs;
+    downloads;
+    uploads;
+    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");
+            }
+            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 ?? "");
+    }
+    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;
+    }
+    /** `{ 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" });
+    }
+    /** 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: [] };
+    }
+}
+class Recording {
+    c;
+    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));
+    }
+}
+class Contexts {
+    c;
+    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 };
+    }
+    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 } : {}) };
+    }
+    update() {
+        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)}`);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,54 @@
+/** Base class for everything this package throws. */
+export declare class BrowserbaseError extends Error {
+    constructor(message: string);
+}
+/** The gateway answered with a non-2xx status. `code` is Solari's machine-readable error code when present. */
+export declare class APIError extends BrowserbaseError {
+    readonly status: number;
+    readonly code: string | undefined;
+    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;
+    readonly hint: string | undefined;
+    constructor(feature: string, hint?: string);
+}

package/dist/errors.js

@@ -0,0 +1,89 @@
+/** Base class for everything this package throws. */
+export class BrowserbaseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** The gateway answered with a non-2xx status. `code` is Solari's machine-readable error code when present. */
+export class APIError extends BrowserbaseError {
+    status;
+    code;
+    body;
+    constructor(status, message, code, body) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        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;
+    hint;
+    constructor(feature, hint) {
+        super(`Not supported by Solari Browser: ${feature}${hint ? ` — ${hint}` : ""}`);
+        this.feature = feature;
+        this.hint = hint;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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 { mapCreateParams, mapStatus } from "./mapping.js";
+export type * from "./types.js";
+export default Browserbase;

package/dist/index.js

@@ -0,0 +1,5 @@
+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 { mapCreateParams, mapStatus } from "./mapping.js";
+export default Browserbase;

package/dist/mapping.d.ts

@@ -0,0 +1,17 @@
+import type { SessionCreateParams, SessionStatus } from "./types.js";
+export interface MappedCreate {
+    /** Body for POST /sessions on the Solari gateway. */
+    body: Record<string, unknown>;
+    /** Context to save back to when the session is released (browserSettings.context.persist). */
+    persistProfileId?: string;
+    /** Soft differences the caller should know about (also emitted via the warn callback). */
+    warnings: string[];
+}
+/**
+ * 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
+ * what the page sees) are returned as warnings, or thrown when `strict` is set.
+ */
+export declare function mapCreateParams(params: SessionCreateParams | undefined, strict: boolean): MappedCreate;
+/** Solari session state -> Browserbase status. */
+export declare function mapStatus(s: string | undefined): SessionStatus;

package/dist/mapping.js

@@ -0,0 +1,115 @@
+import { SolariCompatUnsupported } from "./errors.js";
+const SOLARI_REGION_ALIASES = new Set(["us-west-2"]);
+function proxyBody(proxies, caCerts) {
+    if (caCerts && caCerts.length > 0) {
+        throw new SolariCompatUnsupported("proxySettings.caCertificates", "custom CA certificates are not supported");
+    }
+    if (proxies === undefined || proxies === false)
+        return undefined;
+    if (proxies === true)
+        return { country: "us" };
+    if (!Array.isArray(proxies) || proxies.length === 0)
+        return undefined;
+    if (proxies.length > 1) {
+        throw new SolariCompatUnsupported("multiple proxies / domain routing rules", "pass at most one managed proxy; per-domain routing is not supported");
+    }
+    const p = proxies[0];
+    if (p.domainPattern !== undefined && p.domainPattern !== "") {
+        throw new SolariCompatUnsupported("proxies[].domainPattern", "per-domain proxy routing is not supported");
+    }
+    if (p.type === "external") {
+        throw new SolariCompatUnsupported("external proxy", "bring-your-own proxy servers are not supported; use a managed proxy");
+    }
+    if (p.type === "none")
+        return undefined; // no proxy, same as not asking for one
+    if (p.type !== "browserbase") {
+        throw new SolariCompatUnsupported(`proxy type ${JSON.stringify(p.type)}`);
+    }
+    const g = p.geolocation;
+    if (!g)
+        return { country: "us" };
+    const out = { country: g.country.toLowerCase() };
+    if (g.state)
+        out.state = g.state.toLowerCase();
+    if (g.city)
+        out.city = g.city;
+    return out;
+}
+/**
+ * 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
+ * what the page sees) are returned as warnings, or thrown when `strict` is set.
+ */
+export function mapCreateParams(params, strict) {
+    const p = params ?? {};
+    const bs = p.browserSettings ?? {};
+    const warnings = [];
+    const soft = (feature, why) => {
+        if (strict)
+            throw new SolariCompatUnsupported(feature, why);
+        warnings.push(`${feature}: ${why}`);
+    };
+    // ── hard gaps ────────────────────────────────────────────────────────────────
+    if (p.extensionId || bs.extensionId)
+        throw new SolariCompatUnsupported("extensions", "browser extensions cannot be loaded");
+    if (bs.ignoreCertificateErrors === true)
+        throw new SolariCompatUnsupported("browserSettings.ignoreCertificateErrors");
+    if (bs.captchaImageSelector || bs.captchaInputSelector)
+        throw new SolariCompatUnsupported("custom CAPTCHA selectors");
+    if (bs.os === "mobile" || bs.os === "tablet")
+        throw new SolariCompatUnsupported(`browserSettings.os=${bs.os}`, "only desktop browsers");
+    if (p.region !== undefined && !SOLARI_REGION_ALIASES.has(p.region) && p.region !== "us-west") {
+        throw new SolariCompatUnsupported(`region ${p.region}`, "Solari Browser runs in one region (us-west)");
+    }
+    // ── soft gaps ────────────────────────────────────────────────────────────────
+    if (bs.viewport !== undefined)
+        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)
+        soft("browserSettings.logSession", "session command logs are not available");
+    if (bs.os === "windows" || bs.os === "mac" || bs.os === "linux")
+        soft("browserSettings.os", "the operating system profile cannot be chosen");
+    // ── mapping ──────────────────────────────────────────────────────────────────
+    const proxy = proxyBody(p.proxies, p.proxySettings?.caCertificates);
+    const allowedDomains = bs.allowedDomains && bs.allowedDomains.length > 0 ? bs.allowedDomains : undefined;
+    const captcha = bs.solveCaptchas === true;
+    const stealth = bs.verified === true || bs.advancedStealth === true || captcha || proxy !== undefined || allowedDomains !== undefined;
+    const body = {};
+    if (stealth)
+        body.stealth = true;
+    if (captcha)
+        body.captcha = true;
+    if (bs.recordSession === true)
+        body.recording = true;
+    if (proxy !== undefined)
+        body.proxy = proxy;
+    if (allowedDomains)
+        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 } : {}),
+        warnings,
+    };
+}
+/** Solari session state -> Browserbase status. */
+export function mapStatus(s) {
+    switch (s) {
+        case "active":
+            return "RUNNING";
+        case "released":
+            return "COMPLETED";
+        case "expired":
+            return "TIMED_OUT";
+        default:
+            return "ERROR";
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+/** Browserbase-shaped types (the subset this package supports). */
+export type SessionStatus = "PENDING" | "RUNNING" | "ERROR" | "TIMED_OUT" | "COMPLETED";
+export interface ProxyGeolocation {
+    country: string;
+    state?: string;
+    city?: string;
+}
+export interface BrowserbaseProxyConfig {
+    type: "browserbase";
+    geolocation?: ProxyGeolocation;
+    domainPattern?: string;
+}
+export interface ExternalProxyConfig {
+    type: "external";
+    server: string;
+    username?: string;
+    password?: string;
+    domainPattern?: string;
+}
+export interface NoneProxyConfig {
+    type: "none";
+    domainPattern?: string;
+}
+export type ProxyConfig = BrowserbaseProxyConfig | ExternalProxyConfig | NoneProxyConfig;
+export interface BrowserSettings {
+    context?: {
+        id: string;
+        persist?: boolean;
+    };
+    extensionId?: string;
+    viewport?: {
+        width?: number;
+        height?: number;
+    };
+    blockAds?: boolean;
+    solveCaptchas?: boolean;
+    recordSession?: boolean;
+    logSession?: boolean;
+    advancedStealth?: boolean;
+    verified?: boolean;
+    captchaImageSelector?: string;
+    captchaInputSelector?: string;
+    os?: "windows" | "mac" | "linux" | "mobile" | "tablet";
+    allowedDomains?: string[];
+    ignoreCertificateErrors?: boolean;
+}
+export interface SessionCreateParams {
+    projectId?: string;
+    extensionId?: string;
+    browserSettings?: BrowserSettings;
+    timeout?: number;
+    keepAlive?: boolean;
+    proxies?: boolean | ProxyConfig[];
+    proxySettings?: {
+        caCertificates?: string[];
+    };
+    region?: string;
+    userMetadata?: Record<string, unknown>;
+}
+export interface Session {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    projectId: string;
+    startedAt: string;
+    endedAt?: string;
+    expiresAt: string;
+    status: SessionStatus;
+    proxyBytes: number;
+    keepAlive: boolean;
+    contextId?: string;
+    region: string;
+    userMetadata?: Record<string, unknown>;
+}
+export interface SessionCreateResponse extends Session {
+    /** CDP websocket URL: `chromium.connectOverCDP(connectUrl)` / `puppeteer.connect({browserWSEndpoint})`. */
+    connectUrl: string;
+    /** Always empty: Solari Browser has no WebDriver endpoint. */
+    seleniumRemoteUrl: string;
+    /** Always empty: nothing to sign, the session id in the URL is the credential. */
+    signingKey: string;
+    /**
+     * Solari extension. For a session created with `browserSettings.context`, the saved cookies and localStorage.
+     * Solari applies a saved context only to a browser context created with it, so create yours with
+     * `browser.newContext({ storageState: session.storageState })`. Absent when no context was requested.
+     */
+    storageState?: StorageState | null;
+}
+export interface StorageState {
+    cookies?: Array<Record<string, unknown>>;
+    origins?: Array<Record<string, unknown>>;
+}
+export type SessionRetrieveResponse = SessionCreateResponse;
+export interface SessionLiveURLs {
+    debuggerFullscreenUrl: string;
+    debuggerUrl: string;
+    wsUrl: string;
+    pages: Array<{
+        id: string;
+        url: string;
+        title: string;
+        faviconUrl: string;
+        debuggerUrl: string;
+        debuggerFullscreenUrl: string;
+    }>;
+}
+export interface Context {
+    id: string;
+    name?: string;
+    createdAt?: string;
+}
+export interface ContextCreateResponse {
+    id: string;
+    /** Empty: Solari profiles are stored server-side, no client-side encryption material. */
+    publicKey: string;
+    cipherAlgorithm: string;
+    initializationVectorSize: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@solarisdk/browserbase-compat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Drop-in Browserbase-style SDK surface for Solari Browser: sessions, connectUrl (CDP), contexts, live view, replay events.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "COMPAT.md", "CHANGELOG.md", "LICENSE", "NOTICE"],
+  "keywords": ["browserbase", "solari", "browser", "playwright", "puppeteer", "cdp", "compat"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "node ../../scripts/typecheck-guard.mjs 2 -- tsc --noEmit",
+    "test": "tsc && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}