@solarisdk/browser 0.3.0 → 0.5.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

@@ -88,6 +88,23 @@ seconds for the gateway (1001 ms is 2 s); the gateway refuses anything under 60
 zero or unset leaves the plan maximum, and a negative, `NaN`, `Infinity` or
 fractional value throws before any request. `launch()` accepts the same options.
 
+## Edit a profile
+
+`solari.profiles.edit(id)` opens the profile editor, where a person signs in once and the result is saved into the profile. It returns a handle; give its `url` to whoever should sign in, or open it yourself.
+
+```ts
+const editor = await solari.profiles.edit("prof_123", { reason: "Sign in to Acme" });
+console.log(editor.url); // open this in a browser
+
+await editor.waitForSave({ timeoutMs: 10 * 60_000 }); // the person clicks Save in the editor page
+// or drive it from code once they are done:
+await editor.saveAndClose(); // save and close the editor
+await editor.exit();         // close it WITHOUT saving
+console.log(await editor.status());
+```
+
+The link works for 30 minutes and the editor starts when the person clicks "Open editor" on the page. After that the editor stops by itself and these calls fail with a clear 404 (link expired) or 409 (editor not running). There is no save-and-keep-editing: `saveAndClose()` saves and closes.
+
 ## Regions
 
 Solari runs in `us-west` (N. California) today, with additional regions
@@ -102,6 +119,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,
@@ -137,4 +170,4 @@ try {
 
 ## License
 
-Apache-2.0
+MIT

package/dist/index.d.ts

@@ -96,6 +96,28 @@ export interface Profile {
     name: string;
     [k: string]: unknown;
 }
+/** Options for `profiles.edit()`. */
+export interface EditProfileOptions {
+    /** Shown to whoever opens the link ("Sign in once so your agent can reuse this login" by default). Max 300 chars. */
+    reason?: string;
+}
+/** Options for `ProfileEditor.waitForSave()`. */
+export interface WaitForSaveOptions {
+    /** Give up after this many ms. Default: until the link expires. */
+    timeoutMs?: number;
+    /** How often to check. Default 2000. */
+    pollMs?: number;
+}
+/** 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 +147,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>;
 }
@@ -199,6 +230,50 @@ export declare class SolariError extends Error {
     readonly code?: (SolariErrorCode | string) | undefined;
     constructor(message: string, status?: number | undefined, cause?: unknown | undefined, code?: (SolariErrorCode | string) | undefined);
 }
+/**
+ * A profile editor launched by `solari.profiles.edit(id)`. Give `url` to the person who should
+ * sign in (or open it yourself). The editor starts when the person clicks "Open editor" on that page; it is only usable
+ * while the link is valid (30 minutes from `edit()`), after which the editor stops by itself.
+ */
+export declare class ProfileEditor {
+    private readonly client;
+    readonly profileId: string;
+    /** Open this in a browser. */
+    readonly url: string;
+    readonly handoffId: string;
+    /** ISO time after which the link stops working. */
+    readonly expiresAt: string;
+    /** The profile's version when the editor was launched; a save raises it. */
+    readonly startVersion: number;
+    constructor(client: Solari, profileId: string, 
+    /** Open this in a browser. */
+    url: string, handoffId: string, 
+    /** ISO time after which the link stops working. */
+    expiresAt: string, 
+    /** The profile's version when the editor was launched; a save raises it. */
+    startVersion: number);
+    private path;
+    private headers;
+    /** The editor's state as the console reports it (`editorStatus`: launching | editing | saving | idle | error, or null before it was ever opened, meaning idle). */
+    status(): Promise<{
+        editorStatus: string;
+        version: number;
+        [k: string]: unknown;
+    }>;
+    /** Save what was signed in and close the editor. Resolves with the new profile version. */
+    saveAndClose(): Promise<{
+        version: number;
+    }>;
+    /** Close the editor WITHOUT saving; the profile keeps its previous version. */
+    exit(): Promise<void>;
+    /**
+     * Wait until the person saves in the editor page (the profile's version rises). Resolves with the
+     * new version; throws a `SolariError` with status 408 on timeout or when the link expires first.
+     */
+    waitForSave(opts?: WaitForSaveOptions): Promise<{
+        version: number;
+    }>;
+}
 declare class ProfilesResource {
     private readonly client;
     constructor(client: Solari);
@@ -206,6 +281,11 @@ declare class ProfilesResource {
         name: string;
     }): Promise<Profile>;
     list(): Promise<Profile[]>;
+    /**
+     * Open the profile editor for an existing (or newly created) profile, to sign in or fix its
+     * login. Returns a handle whose `url` is the link to the editor page; see `ProfileEditor`.
+     */
+    edit(id: string, opts?: EditProfileOptions): Promise<ProfileEditor>;
     delete(id: string): Promise<void>;
     save(id: string, storageState: StorageState): Promise<{
         version: number;
@@ -271,5 +351,7 @@ export declare class Solari {
     _unregisterSession(sessionId: string): void;
     request(method: string, path: string, body?: unknown, opts?: {
         idempotencyKey?: string;
+        headers?: Record<string, string>;
+        singleAttempt?: boolean;
     }): Promise<Response>;
 }

package/dist/index.js

@@ -221,6 +221,78 @@ function deriveCdpFromWs(wsEndpoint) {
     catch { }
     return wsEndpoint;
 }
+/**
+ * A profile editor launched by `solari.profiles.edit(id)`. Give `url` to the person who should
+ * sign in (or open it yourself). The editor starts when the person clicks "Open editor" on that page; it is only usable
+ * while the link is valid (30 minutes from `edit()`), after which the editor stops by itself.
+ */
+export class ProfileEditor {
+    client;
+    profileId;
+    url;
+    handoffId;
+    expiresAt;
+    startVersion;
+    constructor(client, profileId, 
+    /** Open this in a browser. */
+    url, handoffId, 
+    /** ISO time after which the link stops working. */
+    expiresAt, 
+    /** The profile's version when the editor was launched; a save raises it. */
+    startVersion) {
+        this.client = client;
+        this.profileId = profileId;
+        this.url = url;
+        this.handoffId = handoffId;
+        this.expiresAt = expiresAt;
+        this.startVersion = startVersion;
+    }
+    path(suffix = "") {
+        return `/profiles/${encodeURIComponent(this.profileId)}/editor${suffix}`;
+    }
+    headers(singleAttempt = false) {
+        return { headers: { "X-Handoff-Id": this.handoffId }, singleAttempt };
+    }
+    /** The editor's state as the console reports it (`editorStatus`: launching | editing | saving | idle | error, or null before it was ever opened, meaning idle). */
+    async status() {
+        const res = await this.client.request("GET", this.path(), undefined, this.headers());
+        if (!res.ok)
+            throw await apiError(`GET ${this.path()}`, res);
+        return (await res.json());
+    }
+    /** Save what was signed in and close the editor. Resolves with the new profile version. */
+    async saveAndClose() {
+        const res = await this.client.request("POST", this.path("/save"), undefined, this.headers(true));
+        if (!res.ok)
+            throw await apiError(`POST ${this.path("/save")}`, res);
+        const data = (await res.json());
+        return { version: data.version ?? this.startVersion + 1 };
+    }
+    /** Close the editor WITHOUT saving; the profile keeps its previous version. */
+    async exit() {
+        const res = await this.client.request("DELETE", this.path(), undefined, this.headers(true));
+        if (!res.ok)
+            throw await apiError(`DELETE ${this.path()}`, res);
+    }
+    /**
+     * Wait until the person saves in the editor page (the profile's version rises). Resolves with the
+     * new version; throws a `SolariError` with status 408 on timeout or when the link expires first.
+     */
+    async waitForSave(opts = {}) {
+        const pollMs = opts.pollMs ?? 2000;
+        const deadline = Math.min(Date.parse(this.expiresAt) || Number.POSITIVE_INFINITY, opts.timeoutMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + opts.timeoutMs);
+        for (;;) {
+            const p = (await this.client.profiles.list()).find((x) => x.id === this.profileId);
+            const v = typeof p?.version === "number" ? p.version : this.startVersion;
+            if (v > this.startVersion)
+                return { version: v };
+            if (Date.now() >= deadline) {
+                throw new SolariError(`Profile ${this.profileId} was not saved before the editor link expired or the wait timed out`, 408);
+            }
+            await new Promise((r) => setTimeout(r, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
+        }
+    }
+}
 class ProfilesResource {
     client;
     constructor(client) {
@@ -247,6 +319,17 @@ class ProfilesResource {
             throw await apiError("GET /profiles", res);
         return (await res.json());
     }
+    /**
+     * Open the profile editor for an existing (or newly created) profile, to sign in or fix its
+     * login. Returns a handle whose `url` is the link to the editor page; see `ProfileEditor`.
+     */
+    async edit(id, opts = {}) {
+        const res = await this.client.request("POST", `/profiles/${encodeURIComponent(id)}/login-handoff`, opts.reason === undefined ? {} : { reason: opts.reason });
+        if (!res.ok)
+            throw await apiError(`POST /profiles/${id}/login-handoff`, res);
+        const d = (await res.json());
+        return new ProfileEditor(this.client, id, d.url, d.handoffId, d.expiresAt, d.version ?? 0);
+    }
     async delete(id) {
         const res = await this.client.request("DELETE", `/profiles/${encodeURIComponent(id)}`);
         if (!res.ok && res.status !== 404)
@@ -333,6 +416,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,
@@ -638,10 +723,14 @@ export class Solari {
             ...(opts?.idempotencyKey
                 ? { "Idempotency-Key": opts.idempotencyKey }
                 : {}),
+            ...(opts?.headers ?? {}),
         };
         const payload = body === undefined ? undefined : JSON.stringify(body);
         let lastErr;
-        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+        // singleAttempt: a state-changing call that must not be replayed (the first try may have done
+        // its work; a replay would then answer 409 and hide the real result).
+        const maxAttempts = opts?.singleAttempt ? 1 : this.maxAttempts;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             const ac = new AbortController();
             const timer = setTimeout(() => ac.abort(), this.timeoutMs);
             try {
@@ -660,7 +749,7 @@ export class Solari {
                 // 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)
+                if (!retryThis || attempt === maxAttempts)
                     return res;
                 await res.text().catch(() => { });
                 lastErr = new SolariError(`Solari ${method} ${path}: ${res.status}`, res.status);
@@ -671,10 +760,10 @@ export class Solari {
                     throw e;
                 lastErr = e;
             }
-            if (attempt < this.maxAttempts) {
+            if (attempt < maxAttempts) {
                 await sleep(this.backoffMs);
             }
         }
-        throw new SolariError(`Solari ${method} ${path}: exhausted ${this.maxAttempts} attempts`, undefined, lastErr);
+        throw new SolariError(`Solari ${method} ${path}: exhausted ${maxAttempts} attempts`, undefined, lastErr);
     }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@solarisdk/browser",
-  "version": "0.3.0",
+  "version": "0.5.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",