@solarisdk/browser 0.1.6 → 0.2.0

package/README.md

@@ -3,6 +3,9 @@
 Official client SDK for [Solari Browser](https://getsolari.com) — managed,
 stealth-hardened browsers as an API.
 
+Feature coverage across all five languages is on the
+[SDK feature matrix](https://docs.getsolari.com/sdk-capabilities).
+
 ## Install
 
 ```bash
@@ -55,6 +58,21 @@ const session = await solari.sessions.create();
 const browser = await chromium.connectOverCDP(session.cdpEndpoint);
 ```
 
+### Timeout, keep-alive and metadata
+
+```ts
+const session = await solari.sessions.create({
+    sessionTimeoutMs: 600_000, // end earlier than the plan maximum, in ms (at least 60 000)
+    keepAlive: true,           // hold the session if the client drops, until its deadline or release
+    userMetadata: { job: "nightly-42" }, // stored with the session
+});
+```
+
+Every duration option is in milliseconds. `sessionTimeoutMs` is rounded up to whole
+seconds for the gateway (1001 ms is 2 s); the gateway refuses anything under 60 s;
+zero or unset leaves the plan maximum, and a negative, `NaN`, `Infinity` or
+fractional value throws before any request. `launch()` accepts the same options.
+
 ## Regions
 
 Solari runs in `us-west` (N. California) today, with additional regions

package/dist/index.d.ts

@@ -88,6 +88,8 @@ export interface Session {
     /** Present only when a managed proxy was requested. Confirmation only
      *  (country/tier/timezone) — egress is applied server-side. */
     proxy?: ResolvedProxyConfig;
+    /** Echo of the `userMetadata` sent at create; absent when none was sent. */
+    userMetadata?: Record<string, unknown>;
 }
 export interface Profile {
     id: string;
@@ -114,6 +116,17 @@ export interface CreateSessionOptions {
      *    proxy: "off"
      */
     proxy?: string | ProxyRequest | "off" | "smart";
+    /** End the session earlier than the plan maximum, in milliseconds. The gateway
+     *  counts whole seconds, so the value is rounded up (1001 ms is 2 s), and it
+     *  refuses anything under 60 s (400). Zero/undefined leaves the plan maximum;
+     *  a negative, NaN, Infinity or non-integer value throws. */
+    sessionTimeoutMs?: number;
+    /** Hold the session after the client disconnects, until its deadline
+     *  (`sessionTimeoutMs`, else an hour, never past the plan maximum) or until
+     *  it is released, so a dropped client can reconnect. */
+    keepAlive?: boolean;
+    /** Free-form JSON object stored with the session (labels, job ids, ...). */
+    userMetadata?: Record<string, unknown>;
 }
 export interface ReplayUrl {
     url: string;

package/dist/index.js

@@ -60,6 +60,19 @@ const DEFAULT_TIMEOUT_MS = 90_000;
 // transient, and a client's correctness must not depend on which gateway
 // build it reaches. Inert today, and deliberately so — do not delete it as
 // dead code.
+/**
+ * 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.
+ */
+function sessionTimeoutSeconds(ms) {
+    if (ms === undefined || ms === 0)
+        return undefined;
+    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);
+}
 function isRetryableStatus(status) {
     return status === 502 || status === 503 || status === 504 || status === 507;
 }
@@ -109,15 +122,19 @@ async function responseSaysRetryable(res) {
         return false;
     }
 }
-// A few 503s are answers, not outages: retrying cannot change them, and swallowing the body would hide the
-// code from the caller. `ProxyTierUnavailable` (explicitly requested proxy tier not servable) is one.
+// Some 5xx are answers, not outages: retrying cannot change them, and swallowing the body would hide the
+// code from the caller. The gateway says so itself with `retryable: false` (502 `PoolResponseUnparseable`:
+// the session may already exist, so a retry creates a second one; 503 `EgressBlockPeekUnsupportedOnFlavor`).
+// `ProxyTierUnavailable` (explicitly requested proxy tier not servable) is also terminal, whatever its flag.
 const TERMINAL_503_CODES = new Set(["ProxyTierUnavailable"]);
-async function responseIsTerminal503(res) {
-    if (res.status !== 503)
-        return false;
+async function responseIsTerminal(res) {
     try {
         const body = (await res.clone().json());
-        return typeof body?.code === "string" && TERMINAL_503_CODES.has(body.code);
+        if (body?.retryable === false)
+            return true;
+        return (res.status === 503 &&
+            typeof body?.code === "string" &&
+            TERMINAL_503_CODES.has(body.code));
     }
     catch {
         return false;
@@ -286,6 +303,13 @@ class SessionsResource {
             body.captcha = true;
         if (options?.proxy !== undefined)
             body.proxy = options.proxy;
+        const timeoutSeconds = sessionTimeoutSeconds(options?.sessionTimeoutMs);
+        if (timeoutSeconds !== undefined)
+            body.timeoutSeconds = timeoutSeconds;
+        if (options?.keepAlive === true)
+            body.keepAlive = true;
+        if (options?.userMetadata !== undefined)
+            body.userMetadata = options.userMetadata;
         // A create allocates a slot and launches a browser before it can answer,
         // so a response lost after that point makes a retry a SECOND session.
         // The key lets the gateway answer the retry from the first result.
@@ -327,6 +351,9 @@ class SessionsResource {
         if (data.proxy) {
             session.proxy = data.proxy;
         }
+        if (data.userMetadata) {
+            session.userMetadata = data.userMetadata;
+        }
         return session;
     }
     /** Fire-and-forget release. Use `releaseAndWait` for confirmation. */
@@ -575,10 +602,13 @@ export class Solari {
                 clearTimeout(timer);
                 if (res.ok)
                     return res;
-                const retryThis = (isRetryableStatus(res.status) && !(await responseIsTerminal503(res))) ||
+                const retryThis = (isRetryableStatus(res.status) && !(await responseIsTerminal(res))) ||
                     (isSafeToReplay(method, opts?.idempotencyKey) &&
                         (await responseSaysRetryable(res)));
-                if (!retryThis)
+                // Out of attempts: hand the last response back so the caller maps its
+                // status and `code` like any other error, instead of a status-less
+                // "exhausted" error that hides why the gateway refused.
+                if (!retryThis || attempt === this.maxAttempts)
                     return res;
                 await res.text().catch(() => { });
                 lastErr = new SolariError(`Solari ${method} ${path}: ${res.status}`, res.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/browser",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Official client SDK for Solari Browser.",
   "license": "Apache-2.0",
   "type": "module",