@solarisdk/browserbase-compat 0.2.0 → 0.3.0

package/dist/mapping.d.ts

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

package/dist/mapping.js

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

package/dist/options.d.ts

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

package/dist/options.js

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

package/dist/types.d.ts

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

package/dist/unsupported.d.ts

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

package/dist/unsupported.js

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

package/package.json

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