@solarisdk/browser 0.2.0 → 0.3.0

package/README.md

@@ -58,6 +58,21 @@ 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

package/dist/index.d.ts

@@ -133,6 +133,42 @@ export interface ReplayUrl {
     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. */
@@ -191,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",
 };
@@ -210,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,
@@ -279,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());
     }
 }
@@ -378,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.2.0",
+  "version": "0.3.0",
   "description": "Official client SDK for Solari Browser.",
   "license": "Apache-2.0",
   "type": "module",