@solarisdk/browser 0.2.0 → 0.4.0

package/LICENSE

@@ -1,17 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+MIT License
 
-   Copyright 2026 Solari Browser
+Copyright (c) 2026 Solari
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-       http://www.apache.org/licenses/LICENSE-2.0
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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
@@ -87,6 +102,22 @@ For staging or self-hosted gateways, pass `baseUrl` instead of `region`.
 
 ## Managed proxies
 
+Proxy bandwidth is billed per GB, and pages heavy in video and images can cost tens of megabytes
+per session. `blockHeavy` (off by default) skips them:
+
+```ts
+await solari.launch({
+    stealth: true,
+    proxy: "us",
+    blockHeavy: true, // video/audio + images over 100 KB; or { fonts: true, imageMaxBytes: 50_000 }
+});
+```
+
+Blocked requests fail inside the browser, so nothing is fetched and nothing leaves through a different
+route; the page sees an ordinary failed load and the blocked image or video does not appear. Images that
+declare no size, and requests made by service workers or cross-origin iframes, are not covered.
+Replays still play: they load media from the original site.
+
 ```ts
 await solari.launch({
     stealth: true,
@@ -122,4 +153,4 @@ try {
 
 ## License
 
-Apache-2.0
+MIT

package/dist/index.d.ts

@@ -96,6 +96,16 @@ export interface Profile {
     name: string;
     [k: string]: unknown;
 }
+/** What `blockHeavy` skips. Every field is optional. */
+export interface BlockHeavyOptions {
+    /** Block video and audio. Default true. */
+    media?: boolean;
+    /** Block web fonts. Default false (blocking fonts changes how the page renders and fingerprints). */
+    fonts?: boolean;
+    /** Block images whose declared size (Content-Length, as sent over the wire) exceeds this many bytes;
+     *  `null` keeps every image. Default 102400 (100 KB). */
+    imageMaxBytes?: number | null;
+}
 export interface CreateSessionOptions {
     /** Attach a stored browser profile (cookies + localStorage). */
     profileId?: string;
@@ -125,6 +135,15 @@ export interface CreateSessionOptions {
      *  (`sessionTimeoutMs`, else an hour, never past the plan maximum) or until
      *  it is released, so a dropped client can reconnect. */
     keepAlive?: boolean;
+    /** Skip heavy files so a proxied session does not pay proxy bandwidth for them. Off by default.
+     *
+     *    blockHeavy: true                                  // video/audio + images over 100 KB
+     *    blockHeavy: { fonts: true, imageMaxBytes: 50_000 }
+     *
+     *  Blocked requests fail inside the browser (nothing is fetched and nothing goes out directly), so the page sees an
+     *  ordinary failed load: a blocked image or video simply does not appear. Images without a declared size, and requests
+     *  made by service workers or cross-origin iframes, are not covered. The gateway rejects a malformed value with 400. */
+    blockHeavy?: boolean | BlockHeavyOptions;
     /** Free-form JSON object stored with the session (labels, job ids, ...). */
     userMetadata?: Record<string, unknown>;
 }
@@ -133,6 +152,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 +246,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());
     }
 }
@@ -308,6 +333,8 @@ class SessionsResource {
             body.timeoutSeconds = timeoutSeconds;
         if (options?.keepAlive === true)
             body.keepAlive = true;
+        if (options?.blockHeavy !== undefined && options.blockHeavy !== false)
+            body.blockHeavy = options.blockHeavy;
         if (options?.userMetadata !== undefined)
             body.userMetadata = options.userMetadata;
         // A create allocates a slot and launches a browser before it can answer,
@@ -378,13 +405,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,8 +1,8 @@
 {
   "name": "@solarisdk/browser",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Official client SDK for Solari Browser.",
-  "license": "Apache-2.0",
+  "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",