@solarisdk/browser 0.1.7 → 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;
 }
@@ -290,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.
@@ -331,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. */

package/package.json

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