@solarisdk/browser 0.4.0 → 0.5.0

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,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);
@@ -225,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;
@@ -290,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)
@@ -640,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 {
@@ -662,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);
@@ -673,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,6 +1,6 @@
 {
   "name": "@solarisdk/browser",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Official client SDK for Solari Browser.",
   "license": "MIT",
   "type": "module",