@solarisdk/browser 0.5.0 → 0.5.2

package/README.md

@@ -29,7 +29,7 @@ console.log(await page.title());
 await browser.close();
 ```
 
-Or with explicit resource management (Node 22+):
+Or with explicit resource management (compiled TypeScript 5.2+, or uncompiled on Node 24+; Node 22 rejects the syntax):
 
 ```ts
 await using browser = await solari.launch({ stealth: true });

package/dist/browser-session.d.ts

@@ -54,6 +54,6 @@ export declare class BrowserSession {
     newPage(): Promise<Page>;
     /** Close the browser and release the session. Idempotent. */
     close(): Promise<void>;
-    /** Supports `await using browser = await solari.launch()` (Node 22+). */
+    /** Supports `await using browser = await solari.launch()` (compiled TypeScript 5.2+, or uncompiled on Node 24+). */
     [Symbol.asyncDispose](): Promise<void>;
 }

package/dist/browser-session.js

@@ -101,7 +101,7 @@ export class BrowserSession {
         if (browserErr)
             throw browserErr;
     }
-    /** Supports `await using browser = await solari.launch()` (Node 22+). */
+    /** Supports `await using browser = await solari.launch()` (compiled TypeScript 5.2+, or uncompiled on Node 24+). */
     async [Symbol.asyncDispose]() {
         await this.close();
     }

package/dist/index.d.ts

@@ -230,6 +230,18 @@ export declare class SolariError extends Error {
     readonly code?: (SolariErrorCode | string) | undefined;
     constructor(message: string, status?: number | undefined, cause?: unknown | undefined, code?: (SolariErrorCode | string) | undefined);
 }
+/**
+ * `text` with each of `secrets` (the session's ws / cdp endpoints) replaced by its redacted form, then any other
+ * URL-looking token cut to `scheme://host/…`: the Playwright driver prints the URL it dialled ("Call log: <ws
+ * connecting> ws://…/ws/<id>"), and that URL carries the session's credential.
+ */
+declare function scrubUrls(text: string, secrets?: string[]): string;
+/** @internal Exposed for tests only. */
+export declare const __testing: {
+    scrubUrls: typeof scrubUrls;
+    redactSessionPath: typeof redactSessionPath;
+};
+declare function redactSessionPath(text: string): string;
 /**
  * A profile editor launched by `solari.profiles.edit(id)`. Give `url` to the person who should
  * sign in (or open it yourself). The editor starts when the person clicks "Open editor" on that page; it is only usable
@@ -341,7 +353,7 @@ export declare class Solari {
      *   await page.goto("https://example.com");
      *   await browser.close();
      *
-     * Or with explicit resource management (Node 22+):
+     * Or with explicit resource management (compiled TypeScript 5.2+, or uncompiled on Node 24+):
      *
      *   await using browser = await solari.launch({ stealth: true });
      */

package/dist/index.js

@@ -69,6 +69,51 @@ export class SolariError extends Error {
  * `code`. Every REST call uses this so a caller can branch on `e.code` no matter
  * which endpoint failed.
  */
+/**
+ * `text` with the session id in every `/sessions/<id>` cut to its first 8 characters. The session id is
+ * the credential inside the ws/cdp URLs, so it must not appear in error messages or logs.
+ */
+/** Field names of a gateway response, never its values (they hold the session id and the ws / cdp URLs). */
+function responseFields(data) {
+    return data && typeof data === "object" ? Object.keys(data).join(", ") || "none" : typeof data;
+}
+function redactUrl(url) {
+    try {
+        const u = new URL(url);
+        return `${u.protocol}//${u.host}/\u2026`;
+    }
+    catch {
+        return "<url>";
+    }
+}
+/**
+ * `text` with each of `secrets` (the session's ws / cdp endpoints) replaced by its redacted form, then any other
+ * URL-looking token cut to `scheme://host/…`: the Playwright driver prints the URL it dialled ("Call log: <ws
+ * connecting> ws://…/ws/<id>"), and that URL carries the session's credential.
+ */
+function scrubUrls(text, secrets = []) {
+    let out = text;
+    for (const s of secrets)
+        if (s)
+            out = out.split(s).join(redactUrl(s));
+    return out.replace(/[a-z][a-z0-9+.-]*:\/\/[^\s"'<>)\],]+/gi, (m) => redactUrl(m));
+}
+/** @internal Exposed for tests only. */
+export const __testing = { scrubUrls, redactSessionPath };
+/** The error to surface from launch(): a foreign error (patchright's connect failure) gets its message scrubbed and its
+ *  cause dropped, since both print the endpoint; SolariErrors only get a scrub of their message. */
+function scrubbedLaunchError(err, secrets) {
+    if (err instanceof SolariError) {
+        err.message = scrubUrls(err.message, secrets);
+        return err;
+    }
+    if (err instanceof Error)
+        return new SolariError(scrubUrls(err.message, secrets));
+    return err;
+}
+function redactSessionPath(text) {
+    return text.replace(/(\/sessions\/)([^/?#\s]+)/g, (_m, prefix, id) => `${prefix}${id.length > 8 ? `${id.slice(0, 8)}\u2026` : id}`);
+}
 async function apiError(what, res) {
     const body = await res.text().catch(() => "");
     let code;
@@ -78,7 +123,7 @@ async function apiError(what, res) {
             code = parsed.code;
     }
     catch { }
-    return new SolariError(`Solari ${what} failed: ${res.status} ${body}`, res.status, undefined, code);
+    return new SolariError(`Solari ${redactSessionPath(what)} failed: ${res.status} ${body}`, res.status, undefined, code);
 }
 const REGION_URLS = {
     "us-west": "https://api.getsolari.com",
@@ -96,7 +141,8 @@ const DEFAULT_TIMEOUT_MS = 90_000;
 /**
  * The gateway's `timeoutSeconds` for a `sessionTimeoutMs`: rounded UP to whole
  * seconds (1001 -> 2). Zero/undefined means "omit". Throws for a negative, NaN,
- * Infinity or non-integer value. Not clamped: the gateway still answers 400 under 60 s.
+ * Infinity or non-integer value, and for one whose seconds do not fit the wire
+ * field (int32), as the Go and Rust SDKs do. Not clamped: the gateway still answers 400 under 60 s.
  */
 function sessionTimeoutSeconds(ms) {
     if (ms === undefined || ms === 0)
@@ -104,7 +150,11 @@ function sessionTimeoutSeconds(ms) {
     if (typeof ms !== "number" || !Number.isInteger(ms) || ms < 0) {
         throw new SolariError(`Solari: sessionTimeoutMs must be a non-negative integer number of milliseconds, got ${String(ms)}`);
     }
-    return Math.ceil(ms / 1000);
+    const seconds = Math.ceil(ms / 1000);
+    if (seconds > 2_147_483_647) {
+        throw new SolariError(`Solari: sessionTimeoutMs is too large, got ${String(ms)}`);
+    }
+    return seconds;
 }
 function isRetryableStatus(status) {
     return status === 502 || status === 503 || status === 504 || status === 507;
@@ -437,7 +487,7 @@ class SessionsResource {
         }
         const data = (await res.json());
         if (!data.sessionId || !data.wsEndpoint) {
-            throw new SolariError(`Solari: unexpected session response: ${JSON.stringify(data)}`);
+            throw new SolariError(`Solari: unexpected session response (fields: ${responseFields(data)})`);
         }
         const cdpUpstream = data.cdpEndpoint ?? deriveCdpFromWs(data.wsEndpoint);
         const localWsEndpoint = await this.client._wrapSessionEndpoint(data.sessionId, data.wsEndpoint, "ws");
@@ -472,12 +522,12 @@ class SessionsResource {
         void this.client.request("DELETE", `/sessions/${encodeURIComponent(id)}`).then(async (res) => {
             const rejection = await releaseRejection(res);
             if (rejection) {
-                console.warn(`[Solari] DELETE /sessions/${id} returned ${res.status}: ` +
+                console.warn(`[Solari] ${redactSessionPath(`DELETE /sessions/${id}`)} returned ${res.status}: ` +
                     `${rejection.body} — session was NOT released; its pool ` +
                     `slot stays held until the server-side grace timer reaps it`);
             }
         }, (err) => {
-            console.warn(`[Solari] DELETE /sessions/${id} failed (fire-and-forget):`, err);
+            console.warn(`[Solari] ${redactSessionPath(`DELETE /sessions/${id}`)} failed (fire-and-forget):`, err);
         });
     }
     async releaseAndWait(id) {
@@ -485,7 +535,7 @@ class SessionsResource {
         const res = await this.client.request("DELETE", `/sessions/${encodeURIComponent(id)}`);
         const rejection = await releaseRejection(res);
         if (rejection) {
-            throw new SolariError(`Solari DELETE /sessions/${id} failed: ${res.status} ${rejection.body}`, res.status, undefined, rejection.code);
+            throw new SolariError(`Solari ${redactSessionPath(`DELETE /sessions/${id}`)} failed: ${res.status} ${rejection.body}`, res.status, undefined, rejection.code);
         }
     }
     /** The gateway's current view of one session (`GET /sessions/:id`). */
@@ -524,7 +574,7 @@ class SessionsResource {
             throw await apiError(`GET /sessions/${id}/replay-url`, res);
         const data = (await res.json());
         if (!data.url) {
-            throw new SolariError(`Solari: unexpected replay-url response: ${JSON.stringify(data)}`);
+            throw new SolariError(`Solari: unexpected replay-url response (fields: ${responseFields(data)})`);
         }
         return {
             url: data.url,
@@ -582,7 +632,7 @@ export class Solari {
      *   await page.goto("https://example.com");
      *   await browser.close();
      *
-     * Or with explicit resource management (Node 22+):
+     * Or with explicit resource management (compiled TypeScript 5.2+, or uncompiled on Node 24+):
      *
      *   await using browser = await solari.launch({ stealth: true });
      */
@@ -662,7 +712,7 @@ export class Solari {
                     await sleep(100 * attempt);
                     continue;
                 }
-                throw err;
+                throw scrubbedLaunchError(err, [session.wsEndpoint, session.cdpEndpoint]);
             }
         }
         throw lastErr ?? new SolariError("Solari.launch: exhausted attempts");
@@ -704,7 +754,7 @@ export class Solari {
             upstream = new URL(upstreamEndpoint);
         }
         catch (e) {
-            throw new SolariError(`Solari: invalid upstream ${kind}Endpoint: ${upstreamEndpoint}`, undefined, e);
+            throw new SolariError(`Solari: invalid upstream ${kind}Endpoint: ${redactUrl(upstreamEndpoint)}`, undefined, e);
         }
         await this.localProxy.start();
         this.localProxy.register(sessionId, upstream, kind);
@@ -752,7 +802,7 @@ export class Solari {
                 if (!retryThis || attempt === maxAttempts)
                     return res;
                 await res.text().catch(() => { });
-                lastErr = new SolariError(`Solari ${method} ${path}: ${res.status}`, res.status);
+                lastErr = new SolariError(`Solari ${method} ${redactSessionPath(path)}: ${res.status}`, res.status);
             }
             catch (e) {
                 clearTimeout(timer);
@@ -764,6 +814,6 @@ export class Solari {
                 await sleep(this.backoffMs);
             }
         }
-        throw new SolariError(`Solari ${method} ${path}: exhausted ${maxAttempts} attempts`, undefined, lastErr);
+        throw new SolariError(`Solari ${method} ${redactSessionPath(path)}: exhausted ${maxAttempts} attempts`, undefined, lastErr);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/browser",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Official client SDK for Solari Browser.",
   "license": "MIT",
   "type": "module",