@solarisdk/browser 0.4.0 → 0.5.1

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

package/dist/index.d.ts

@@ -96,6 +96,18 @@ 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. */
@@ -218,6 +230,62 @@ export declare class SolariError extends Error {
     readonly code?: (SolariErrorCode | string) | undefined;
     constructor(message: string, status?: number | undefined, cause?: unknown | undefined, code?: (SolariErrorCode | string) | undefined);
 }
+/**
+ * `text` with each of `secrets` (the session's ws / cdp endpoints) replaced by its redacted form, then any other
+ * URL-looking token cut to `scheme://host/…`: the Playwright driver prints the URL it dialled ("Call log: <ws
+ * connecting> ws://…/ws/<id>"), and that URL carries the session's credential.
+ */
+declare function scrubUrls(text: string, secrets?: string[]): string;
+/** @internal Exposed for tests only. */
+export declare const __testing: {
+    scrubUrls: typeof scrubUrls;
+    redactSessionPath: typeof redactSessionPath;
+};
+declare function redactSessionPath(text: string): string;
+/**
+ * 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);
@@ -225,6 +293,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;
@@ -290,5 +363,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

@@ -69,6 +69,51 @@ export class SolariError extends Error {
  * `code`. Every REST call uses this so a caller can branch on `e.code` no matter
  * which endpoint failed.
  */
+/**
+ * `text` with the session id in every `/sessions/<id>` cut to its first 8 characters. The session id is
+ * the credential inside the ws/cdp URLs, so it must not appear in error messages or logs.
+ */
+/** Field names of a gateway response, never its values (they hold the session id and the ws / cdp URLs). */
+function responseFields(data) {
+    return data && typeof data === "object" ? Object.keys(data).join(", ") || "none" : typeof data;
+}
+function redactUrl(url) {
+    try {
+        const u = new URL(url);
+        return `${u.protocol}//${u.host}/\u2026`;
+    }
+    catch {
+        return "<url>";
+    }
+}
+/**
+ * `text` with each of `secrets` (the session's ws / cdp endpoints) replaced by its redacted form, then any other
+ * URL-looking token cut to `scheme://host/…`: the Playwright driver prints the URL it dialled ("Call log: <ws
+ * connecting> ws://…/ws/<id>"), and that URL carries the session's credential.
+ */
+function scrubUrls(text, secrets = []) {
+    let out = text;
+    for (const s of secrets)
+        if (s)
+            out = out.split(s).join(redactUrl(s));
+    return out.replace(/[a-z][a-z0-9+.-]*:\/\/[^\s"'<>)\],]+/gi, (m) => redactUrl(m));
+}
+/** @internal Exposed for tests only. */
+export const __testing = { scrubUrls, redactSessionPath };
+/** The error to surface from launch(): a foreign error (patchright's connect failure) gets its message scrubbed and its
+ *  cause dropped, since both print the endpoint; SolariErrors only get a scrub of their message. */
+function scrubbedLaunchError(err, secrets) {
+    if (err instanceof SolariError) {
+        err.message = scrubUrls(err.message, secrets);
+        return err;
+    }
+    if (err instanceof Error)
+        return new SolariError(scrubUrls(err.message, secrets));
+    return err;
+}
+function redactSessionPath(text) {
+    return text.replace(/(\/sessions\/)([^/?#\s]+)/g, (_m, prefix, id) => `${prefix}${id.length > 8 ? `${id.slice(0, 8)}\u2026` : id}`);
+}
 async function apiError(what, res) {
     const body = await res.text().catch(() => "");
     let code;
@@ -78,7 +123,7 @@ async function apiError(what, res) {
             code = parsed.code;
     }
     catch { }
-    return new SolariError(`Solari ${what} failed: ${res.status} ${body}`, res.status, undefined, code);
+    return new SolariError(`Solari ${redactSessionPath(what)} failed: ${res.status} ${body}`, res.status, undefined, code);
 }
 const REGION_URLS = {
     "us-west": "https://api.getsolari.com",
@@ -221,6 +266,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 +364,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)
@@ -354,7 +482,7 @@ class SessionsResource {
         }
         const data = (await res.json());
         if (!data.sessionId || !data.wsEndpoint) {
-            throw new SolariError(`Solari: unexpected session response: ${JSON.stringify(data)}`);
+            throw new SolariError(`Solari: unexpected session response (fields: ${responseFields(data)})`);
         }
         const cdpUpstream = data.cdpEndpoint ?? deriveCdpFromWs(data.wsEndpoint);
         const localWsEndpoint = await this.client._wrapSessionEndpoint(data.sessionId, data.wsEndpoint, "ws");
@@ -389,12 +517,12 @@ class SessionsResource {
         void this.client.request("DELETE", `/sessions/${encodeURIComponent(id)}`).then(async (res) => {
             const rejection = await releaseRejection(res);
             if (rejection) {
-                console.warn(`[Solari] DELETE /sessions/${id} returned ${res.status}: ` +
+                console.warn(`[Solari] ${redactSessionPath(`DELETE /sessions/${id}`)} returned ${res.status}: ` +
                     `${rejection.body} — session was NOT released; its pool ` +
                     `slot stays held until the server-side grace timer reaps it`);
             }
         }, (err) => {
-            console.warn(`[Solari] DELETE /sessions/${id} failed (fire-and-forget):`, err);
+            console.warn(`[Solari] ${redactSessionPath(`DELETE /sessions/${id}`)} failed (fire-and-forget):`, err);
         });
     }
     async releaseAndWait(id) {
@@ -402,7 +530,7 @@ class SessionsResource {
         const res = await this.client.request("DELETE", `/sessions/${encodeURIComponent(id)}`);
         const rejection = await releaseRejection(res);
         if (rejection) {
-            throw new SolariError(`Solari DELETE /sessions/${id} failed: ${res.status} ${rejection.body}`, res.status, undefined, rejection.code);
+            throw new SolariError(`Solari ${redactSessionPath(`DELETE /sessions/${id}`)} failed: ${res.status} ${rejection.body}`, res.status, undefined, rejection.code);
         }
     }
     /** The gateway's current view of one session (`GET /sessions/:id`). */
@@ -441,7 +569,7 @@ class SessionsResource {
             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)}`);
+            throw new SolariError(`Solari: unexpected replay-url response (fields: ${responseFields(data)})`);
         }
         return {
             url: data.url,
@@ -579,7 +707,7 @@ export class Solari {
                     await sleep(100 * attempt);
                     continue;
                 }
-                throw err;
+                throw scrubbedLaunchError(err, [session.wsEndpoint, session.cdpEndpoint]);
             }
         }
         throw lastErr ?? new SolariError("Solari.launch: exhausted attempts");
@@ -621,7 +749,7 @@ export class Solari {
             upstream = new URL(upstreamEndpoint);
         }
         catch (e) {
-            throw new SolariError(`Solari: invalid upstream ${kind}Endpoint: ${upstreamEndpoint}`, undefined, e);
+            throw new SolariError(`Solari: invalid upstream ${kind}Endpoint: ${redactUrl(upstreamEndpoint)}`, undefined, e);
         }
         await this.localProxy.start();
         this.localProxy.register(sessionId, upstream, kind);
@@ -640,10 +768,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 {
@@ -662,10 +794,10 @@ 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);
+                lastErr = new SolariError(`Solari ${method} ${redactSessionPath(path)}: ${res.status}`, res.status);
             }
             catch (e) {
                 clearTimeout(timer);
@@ -673,10 +805,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} ${redactSessionPath(path)}: exhausted ${maxAttempts} attempts`, undefined, lastErr);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/browser",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Official client SDK for Solari Browser.",
   "license": "MIT",
   "type": "module",