@solarisdk/browserbase-compat 0.2.0 → 0.3.0

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],
@@ -19,7 +22,9 @@ function resolveApiKey(explicit, warn) {
     }
     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. */
+/** 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 {
@@ -31,7 +36,7 @@ export function isSolariBaseUrl(raw) {
     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")))
+    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:");
@@ -49,7 +54,7 @@ function resolveBaseUrl(explicit) {
     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).`);
+        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(/\/+$/, "");
 }
@@ -59,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 });
@@ -81,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();
@@ -153,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,
     };
@@ -199,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 {
@@ -302,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;