@solarisdk/browser 0.1.7 → 0.3.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,36 @@ const session = await solari.sessions.create();
 const browser = await chromium.connectOverCDP(session.cdpEndpoint);
 ```
 
+### Get and list sessions
+
+```ts
+const view = await solari.sessions.get(session.id); // status, kind, userMetadata, endpoints while active
+let page = await solari.sessions.list({ limit: 50, metadata: { job: "nightly-42" } });
+// page.sessions, page.nextCursor (absent on the last page)
+```
+
+`list` never returns the websocket endpoints (they are bearer capabilities): call `get`
+for a single session's. Pass `page.nextCursor` as `cursor` for the next page.
+
+Every REST error carries the gateway's `code` when it sends one, so you can branch on
+it whichever call failed: `e.code === "ReplayPending"` (a replay still uploading; wait and
+call again), `"SessionNotFound"`, `"InvalidSessionId"`, `"PlanLimitExceeded"` and so on.
+
+### 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,12 +116,59 @@ 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;
     expiresInSeconds: number;
     contentEncoding: string;
 }
+/** `GET /sessions/:id`. Fields the gateway adds later are kept (index signature). */
+export interface SessionView {
+    id: string;
+    status: string;
+    kind?: string | null;
+    org?: string;
+    createdAt?: string | null;
+    expiresAt?: string | null;
+    userMetadata?: Record<string, unknown>;
+    /** Present while the session is active. */
+    wsEndpoint?: string;
+    cdpEndpoint?: string;
+    [k: string]: unknown;
+}
+/** One row of `sessions.list()`. Never carries the websocket endpoints. */
+export interface SessionSummary {
+    id: string;
+    status: string;
+    kind?: string | null;
+    createdAt?: string | null;
+    expiresAt?: string | null;
+    userMetadata?: Record<string, unknown>;
+}
+export interface SessionList {
+    sessions: SessionSummary[];
+    /** Absent on the last page; pass it as `ListSessionsOptions.cursor`. */
+    nextCursor?: string;
+}
+export interface ListSessionsOptions {
+    /** Page size; unset uses the gateway default. */
+    limit?: number;
+    /** Continue from a previous page's `nextCursor`. */
+    cursor?: string;
+    /** Keep sessions whose `userMetadata` has all these string values. */
+    metadata?: Record<string, string>;
+}
 /** Options for `Solari.launch()`. Strict superset of `CreateSessionOptions`. */
 export interface LaunchOptions extends CreateSessionOptions {
     /** Additional re-launch attempts after the first failure. Default 0. */
@@ -178,6 +227,15 @@ declare class SessionsResource {
     /** Fire-and-forget release. Use `releaseAndWait` for confirmation. */
     release(id: string): void;
     releaseAndWait(id: string): Promise<void>;
+    /** The gateway's current view of one session (`GET /sessions/:id`). */
+    get(id: string): Promise<SessionView>;
+    /**
+     * One page of the organisation's sessions (`GET /sessions`). Rows never carry the
+     * websocket endpoints (they are bearer capabilities): call `get(id)` for those.
+     * `metadata` keeps sessions whose `userMetadata` has all these string values
+     * (at most 10 pairs; keys and values cannot contain a single quote).
+     */
+    list(options?: ListSessionsOptions): Promise<SessionList>;
     /** Presigned URL for the session's replay. Available ~1-3s after `releaseAndWait`. */
     getReplayUrl(id: string): Promise<ReplayUrl>;
     /** Download the replay as NDJSON bytes. */

package/dist/index.js

@@ -35,6 +35,21 @@ function toPlaywrightStorageState(state) {
         })),
     };
 }
+/** The gateway's list filter grammar, in key order; throws for a pair it cannot express. */
+function metadataFilter(m) {
+    const keys = Object.keys(m).sort();
+    if (keys.length > 10)
+        throw new SolariError("Solari: at most 10 metadata filter pairs");
+    return keys
+        .map((k) => {
+        const v = m[k];
+        if (k.length < 1 || k.length > 128 || k.includes("'") || v.includes("'")) {
+            throw new SolariError(`Solari: metadata filter key ${JSON.stringify(k)} or its value cannot be expressed (1-128 characters, no single quote)`);
+        }
+        return `user_metadata['${k}']:'${v}'`;
+    })
+        .join(" AND ");
+}
 export class SolariError extends Error {
     status;
     cause;
@@ -47,6 +62,24 @@ export class SolariError extends Error {
         this.name = "SolariError";
     }
 }
+/**
+ * Build the error for a non-ok API response: the status, the body text in the
+ * message, and the gateway's `code` (for example `ReplayPending`,
+ * `SessionNotFound`, `InvalidSessionId`) when the body is JSON with a string
+ * `code`. Every REST call uses this so a caller can branch on `e.code` no matter
+ * which endpoint failed.
+ */
+async function apiError(what, res) {
+    const body = await res.text().catch(() => "");
+    let code;
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed?.code === "string")
+            code = parsed.code;
+    }
+    catch { }
+    return new SolariError(`Solari ${what} failed: ${res.status} ${body}`, res.status, undefined, code);
+}
 const REGION_URLS = {
     "us-west": "https://api.getsolari.com",
 };
@@ -60,6 +93,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;
 }
@@ -197,25 +243,19 @@ class ProfilesResource {
     }
     async list() {
         const res = await this.client.request("GET", "/profiles");
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            throw new SolariError(`Solari GET /profiles failed: ${res.status} ${body}`, res.status);
-        }
+        if (!res.ok)
+            throw await apiError("GET /profiles", res);
         return (await res.json());
     }
     async delete(id) {
         const res = await this.client.request("DELETE", `/profiles/${encodeURIComponent(id)}`);
-        if (!res.ok && res.status !== 404) {
-            const body = await res.text().catch(() => "");
-            throw new SolariError(`Solari DELETE /profiles/${id} failed: ${res.status} ${body}`, res.status);
-        }
+        if (!res.ok && res.status !== 404)
+            throw await apiError(`DELETE /profiles/${id}`, res);
     }
     async save(id, storageState) {
         const res = await this.client.request("POST", `/profiles/${encodeURIComponent(id)}/save`, { storageState });
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            throw new SolariError(`Solari POST /profiles/${id}/save failed: ${res.status} ${body}`, res.status);
-        }
+        if (!res.ok)
+            throw await apiError(`POST /profiles/${id}/save`, res);
         const data = (await res.json());
         return {
             version: data.version ?? 0,
@@ -266,10 +306,8 @@ class ProxyResource {
      *  `proxy.countries()` and C++ `proxyCountries()`. */
     async countries() {
         const res = await this.client.request("GET", "/proxy/countries");
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            throw new SolariError(`Solari GET /proxy/countries failed: ${res.status} ${body}`, res.status);
-        }
+        if (!res.ok)
+            throw await apiError("GET /proxy/countries", res);
         return (await res.json());
     }
 }
@@ -290,6 +328,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 +376,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. */
@@ -355,13 +403,40 @@ class SessionsResource {
             throw new SolariError(`Solari DELETE /sessions/${id} failed: ${res.status} ${rejection.body}`, res.status, undefined, rejection.code);
         }
     }
+    /** The gateway's current view of one session (`GET /sessions/:id`). */
+    async get(id) {
+        const res = await this.client.request("GET", `/sessions/${encodeURIComponent(id)}`);
+        if (!res.ok)
+            throw await apiError(`GET /sessions/${id}`, res);
+        return (await res.json());
+    }
+    /**
+     * One page of the organisation's sessions (`GET /sessions`). Rows never carry the
+     * websocket endpoints (they are bearer capabilities): call `get(id)` for those.
+     * `metadata` keeps sessions whose `userMetadata` has all these string values
+     * (at most 10 pairs; keys and values cannot contain a single quote).
+     */
+    async list(options) {
+        const params = new URLSearchParams();
+        if (options?.limit !== undefined && options.limit > 0)
+            params.set("limit", String(options.limit));
+        if (options?.cursor)
+            params.set("cursor", options.cursor);
+        if (options?.metadata && Object.keys(options.metadata).length > 0) {
+            params.set("q", metadataFilter(options.metadata));
+        }
+        const qs = params.toString();
+        const res = await this.client.request("GET", `/sessions${qs ? `?${qs}` : ""}`);
+        if (!res.ok)
+            throw await apiError("GET /sessions", res);
+        const data = (await res.json());
+        return { sessions: data.sessions ?? [], ...(data.nextCursor ? { nextCursor: data.nextCursor } : {}) };
+    }
     /** Presigned URL for the session's replay. Available ~1-3s after `releaseAndWait`. */
     async getReplayUrl(id) {
         const res = await this.client.request("GET", `/sessions/${encodeURIComponent(id)}/replay-url`);
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            throw new SolariError(`Solari GET /sessions/${id}/replay-url failed: ${res.status} ${body}`, res.status);
-        }
+        if (!res.ok)
+            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)}`);

package/package.json

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