@solarisdk/browser 0.1.3 → 0.1.5

package/dist/browser-session.d.ts

@@ -5,8 +5,14 @@ export declare class BrowserSession {
     private readonly client;
     readonly session: Session;
     private readonly browser;
+    /** The session's primary context — seeded with the attached profile's
+     *  storageState when there is one. See {@link context}. */
+    private readonly primaryContext?;
     private closed;
-    constructor(client: Solari, session: Session, browser: Browser);
+    constructor(client: Solari, session: Session, browser: Browser, 
+    /** The session's primary context — seeded with the attached profile's
+     *  storageState when there is one. See {@link context}. */
+    primaryContext?: BrowserContext | undefined);
     /** Session id. */
     get id(): string;
     /** Plan-tier deadline (ISO 8601 UTC); session auto-releases at this point. */
@@ -23,11 +29,28 @@ export declare class BrowserSession {
     isConnected(): boolean;
     /** Browser version string (e.g. `"Chromium/130.0.6723.31"`). */
     version(): string;
-    /** All open contexts. Sessions ship with a default context at `contexts()[0]`. */
+    /**
+     * The session's primary context — the one carrying the attached profile's
+     * cookies and localStorage. Use this (or {@link newPage}) rather than
+     * `contexts()[0]`, which is not guaranteed to be the seeded one.
+     */
+    get context(): BrowserContext | undefined;
+    /**
+     * All open contexts, straight from the browser.
+     *
+     * NOTE: this is NOT guaranteed to be non-empty, and `contexts()[0]` is NOT
+     * guaranteed to be the profile-seeded context — the pool only pre-creates an
+     * eager context when a proxy was requested. Prefer {@link context}.
+     */
     contexts(): BrowserContext[];
-    /** Open a fresh browser context. Most callers want `contexts()[0]` instead. */
+    /** Open an ADDITIONAL, empty browser context. This does NOT carry the
+     *  attached profile — use {@link context} for that. */
     newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
-    /** Open a fresh page in a new context. */
+    /**
+     * Open a page in the session's primary context, so an attached profile's
+     * cookies/localStorage are actually present. Falls back to a browser-level
+     * page only when there is no primary context.
+     */
     newPage(): Promise<Page>;
     /** Close the browser and release the session. Idempotent. */
     close(): Promise<void>;

package/dist/browser-session.js

@@ -2,11 +2,16 @@ export class BrowserSession {
     client;
     session;
     browser;
+    primaryContext;
     closed = false;
-    constructor(client, session, browser) {
+    constructor(client, session, browser, 
+    /** The session's primary context — seeded with the attached profile's
+     *  storageState when there is one. See {@link context}. */
+    primaryContext) {
         this.client = client;
         this.session = session;
         this.browser = browser;
+        this.primaryContext = primaryContext;
     }
     /** Session id. */
     get id() {
@@ -40,16 +45,37 @@ export class BrowserSession {
     version() {
         return this.browser.version();
     }
-    /** All open contexts. Sessions ship with a default context at `contexts()[0]`. */
+    /**
+     * The session's primary context — the one carrying the attached profile's
+     * cookies and localStorage. Use this (or {@link newPage}) rather than
+     * `contexts()[0]`, which is not guaranteed to be the seeded one.
+     */
+    get context() {
+        return this.primaryContext;
+    }
+    /**
+     * All open contexts, straight from the browser.
+     *
+     * NOTE: this is NOT guaranteed to be non-empty, and `contexts()[0]` is NOT
+     * guaranteed to be the profile-seeded context — the pool only pre-creates an
+     * eager context when a proxy was requested. Prefer {@link context}.
+     */
     contexts() {
         return this.browser.contexts();
     }
-    /** Open a fresh browser context. Most callers want `contexts()[0]` instead. */
+    /** Open an ADDITIONAL, empty browser context. This does NOT carry the
+     *  attached profile — use {@link context} for that. */
     async newContext(options) {
         return this.browser.newContext(options);
     }
-    /** Open a fresh page in a new context. */
+    /**
+     * Open a page in the session's primary context, so an attached profile's
+     * cookies/localStorage are actually present. Falls back to a browser-level
+     * page only when there is no primary context.
+     */
     async newPage() {
+        if (this.primaryContext)
+            return this.primaryContext.newPage();
         return this.browser.newPage();
     }
     /** Close the browser and release the session. Idempotent. */

package/dist/index.d.ts

@@ -103,11 +103,6 @@ export interface CreateSessionOptions {
     stealth?: boolean;
     /** Enable managed captcha solving. Requires `stealth: true`. */
     captcha?: boolean;
-    /** Opt in to Cloudflare Web Bot Auth — sign every outbound HTTP
-     *  request with an Ed25519 key registered to our verified bot
-     *  directory. Independent of `stealth`. Silently inert if the
-     *  acquired slot has no signing key configured. */
-    webBotAuth?: boolean;
     /** Request managed proxy egress. Requires `stealth: true`.
      *
      *    proxy: "us"
@@ -136,6 +131,17 @@ export interface LaunchOptions extends CreateSessionOptions {
     probeTimeoutMs?: number;
 }
 export type SolariErrorCode = "FeatureRequiresPlan" | "ConcurrencyLimitExceeded" | "PlanLimitExceeded" | "BrowserUnhealthy" | "InvalidSessionId";
+/** Supported egress countries and residential-proxy status, from
+ *  {@link Solari.proxy}.countries() (`GET /proxy/countries`). */
+export interface ProxyCountries {
+    /** Whether RESIDENTIAL managed-proxy credentials are configured on the
+     *  gateway. Reflects only the residential tier — the static/mobile tiers
+     *  have separate credentials this flag does not report, so `true` is not a
+     *  guarantee that `tier: "mobile"` will resolve. */
+    enabled: boolean;
+    /** Supported ISO-3166-1 alpha-2 egress countries (lowercase, sorted). */
+    countries: string[];
+}
 export declare class SolariError extends Error {
     readonly status?: number | undefined;
     readonly cause?: unknown | undefined;
@@ -155,6 +161,14 @@ declare class ProfilesResource {
         sizeBytes: number;
     }>;
 }
+declare class ProxyResource {
+    private readonly client;
+    constructor(client: Solari);
+    /** `GET /proxy/countries` — the egress countries this gateway supports and
+     *  whether residential proxy credentials are configured. Matches the Go/Rust
+     *  `proxy.countries()` and C++ `proxyCountries()`. */
+    countries(): Promise<ProxyCountries>;
+}
 declare class SessionsResource {
     private readonly client;
     constructor(client: Solari);
@@ -170,12 +184,13 @@ declare class SessionsResource {
 export declare class Solari {
     readonly sessions: SessionsResource;
     readonly profiles: ProfilesResource;
+    readonly proxy: ProxyResource;
     private readonly apiKey;
     private readonly baseUrl;
     private readonly maxAttempts;
     private readonly backoffMs;
     private readonly timeoutMs;
-    private readonly proxy;
+    private readonly localProxy;
     constructor(opts: SolariOptions);
     close(): Promise<void>;
     /**
@@ -194,5 +209,7 @@ export declare class Solari {
     private _probeBrowserHealth;
     _wrapSessionEndpoint(sessionId: string, upstreamEndpoint: string, kind?: ProxyKind): Promise<string>;
     _unregisterSession(sessionId: string): void;
-    request(method: string, path: string, body?: unknown): Promise<Response>;
+    request(method: string, path: string, body?: unknown, opts?: {
+        idempotencyKey?: string;
+    }): Promise<Response>;
 }

package/dist/index.js

@@ -2,6 +2,39 @@ import { chromium } from "patchright-core";
 import { LocalProxy } from "./local-proxy.js";
 import { BrowserSession } from "./browser-session.js";
 export { BrowserSession } from "./browser-session.js";
+/**
+ * Narrow a {@link StorageState} to the shape `newContext({storageState})` wants.
+ *
+ * Our StorageState is deliberately permissive — every field optional, plus an
+ * index signature — because it doubles as the INPUT to `profiles.save()`, where
+ * callers hand-build partial objects. Playwright's parameter type requires the
+ * cookie fields to be present, so passing ours straight through is a TS2322 and
+ * callers were resorting to `as any`.
+ *
+ * Rather than tighten the public type (which would break anyone constructing a
+ * partial state to save), fill the defaults at this one seam. Values that are
+ * actually present always win; the defaults only cover fields the gateway
+ * omitted, and they match Playwright's own defaults for a host-only cookie.
+ */
+function toPlaywrightStorageState(state) {
+    return {
+        cookies: (state.cookies ?? []).map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain ?? "",
+            path: c.path ?? "/",
+            // -1 is Playwright's "session cookie" sentinel.
+            expires: c.expires ?? -1,
+            httpOnly: c.httpOnly ?? false,
+            secure: c.secure ?? false,
+            sameSite: c.sameSite ?? "Lax",
+        })),
+        origins: (state.origins ?? []).map((o) => ({
+            origin: o.origin,
+            localStorage: o.localStorage ?? [],
+        })),
+    };
+}
 export class SolariError extends Error {
     status;
     cause;
@@ -21,8 +54,60 @@ const DEFAULT_REGION = "us-west";
 const DEFAULT_MAX_ATTEMPTS = 2;
 const DEFAULT_BACKOFF_MS = 500;
 const DEFAULT_TIMEOUT_MS = 90_000;
+// 507 is in the list although THIS gateway does not emit one (censused
+// 2026-09-22: browser emits 501/502/503 only). It is here so the client is
+// right on its own terms: the desktop gateway's InsufficientCapacity 507 is
+// transient, and a client's correctness must not depend on which gateway
+// build it reaches. Inert today, and deliberately so — do not delete it as
+// dead code.
 function isRetryableStatus(status) {
-    return status === 502 || status === 503 || status === 504;
+    return status === 502 || status === 503 || status === 504 || status === 507;
+}
+// Methods that are safe to send twice. The gateway issues no Idempotency-Key
+// for the browser API, so the `retryable` hint is honoured ONLY here: a
+// re-sent POST /sessions could leave a second live session behind.
+function isIdempotentMethod(method) {
+    const m = method.toUpperCase();
+    return m === "GET" || m === "HEAD" || m === "DELETE" || m === "PUT";
+}
+// Is THIS REQUEST safe to send again? Deliberately a per-request question, not
+// a per-method one. A POST is not idempotent by verb, but a POST carrying an
+// Idempotency-Key is safe to replay because the server answers the second copy
+// from the first one's result instead of creating twice.
+//
+// This is what the old comment here was waiting for. It read: "The browser API
+// issues no Idempotency-Key, so the `retryable` hint is honoured ONLY for
+// idempotent methods: a re-sent POST /sessions could leave a second live
+// session behind." That reason is being removed, not worked around.
+function isSafeToReplay(method, idempotencyKey) {
+    return isIdempotentMethod(method) || idempotencyKey !== undefined;
+}
+// A key must identify the CALL, not the attempt: minted once by the caller and
+// reused by every retry of that call. Minting per attempt would make each retry
+// a fresh create and defeat the whole mechanism.
+function newIdempotencyKey() {
+    const c = typeof globalThis.crypto !== "undefined" ? globalThis.crypto : undefined;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    // Pre-19 Node / older browsers: not a v4 UUID, just unique enough to key on.
+    return `slr-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 14)}`;
+}
+// The gateway can mark a response retryable on a status that is NOT in the
+// 5xx allowlist — today `404 ReplayPending`, where the recording upload is
+// still in flight. Honour that hint rather than flattening it into a
+// terminal error.
+//
+// The body is read from a CLONE: the caller still owns the original and
+// parses `code` out of it, and a Response body can only be consumed once.
+async function responseSaysRetryable(res) {
+    try {
+        const body = (await res.clone().json());
+        return body?.retryable === true;
+    }
+    catch {
+        // Non-JSON or already-consumed body: no hint, not retryable.
+        return false;
+    }
 }
 function isRetryableError(_err) {
     return true;
@@ -153,6 +238,23 @@ async function releaseRejection(res) {
         return null;
     return { body, code };
 }
+class ProxyResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** `GET /proxy/countries` — the egress countries this gateway supports and
+     *  whether residential proxy credentials are configured. Matches the Go/Rust
+     *  `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);
+        }
+        return (await res.json());
+    }
+}
 class SessionsResource {
     client;
     constructor(client) {
@@ -168,11 +270,12 @@ class SessionsResource {
             body.stealth = true;
         if (options?.captcha === true)
             body.captcha = true;
-        if (options?.webBotAuth === true)
-            body.webBotAuth = true;
         if (options?.proxy !== undefined)
             body.proxy = options.proxy;
-        const res = await this.client.request("POST", "/sessions", Object.keys(body).length ? body : undefined);
+        // A create allocates a slot and launches a browser before it can answer,
+        // so a response lost after that point makes a retry a SECOND session.
+        // The key lets the gateway answer the retry from the first result.
+        const res = await this.client.request("POST", "/sessions", Object.keys(body).length ? body : undefined, { idempotencyKey: newIdempotencyKey() });
         if (!res.ok) {
             const text = await res.text().catch(() => "");
             let code;
@@ -265,12 +368,13 @@ class SessionsResource {
 export class Solari {
     sessions;
     profiles;
+    proxy;
     apiKey;
     baseUrl;
     maxAttempts;
     backoffMs;
     timeoutMs;
-    proxy = new LocalProxy();
+    localProxy = new LocalProxy();
     constructor(opts) {
         if (!opts.apiKey) {
             throw new SolariError("Solari: apiKey is required");
@@ -287,9 +391,10 @@ export class Solari {
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.sessions = new SessionsResource(this);
         this.profiles = new ProfilesResource(this);
+        this.proxy = new ProxyResource(this);
     }
     async close() {
-        await this.proxy.stop();
+        await this.localProxy.stop();
     }
     /**
      * Create a session and return a connected browser.
@@ -322,7 +427,32 @@ export class Solari {
                 if (probeEnabled) {
                     await this._probeBrowserHealth(browser, probeTimeoutMs);
                 }
-                return new BrowserSession(this, session, browser);
+                // Materialise ONE primary context for the session.
+                //
+                // The gateway already fetches an attached profile's cookies +
+                // origins into session.storageState (and its own comment says it
+                // does so "so the SDK skips the newContext({storageState}) seed")
+                // — but the SDK never performed that seed, so every run wrote a
+                // new profile version and read none back. Seed it here.
+                //
+                // Also makes a context reliably available: the pool only
+                // pre-creates one when a proxy was requested, so on a plain
+                // launch() browser.contexts() was empty and contexts()[0]
+                // undefined — which the SDK's own docs pointed callers at.
+                const ctxOptions = {};
+                const tz = session.proxy?.timezoneId;
+                if (tz)
+                    ctxOptions.timezoneId = tz;
+                if (session.storageState) {
+                    ctxOptions.storageState = toPlaywrightStorageState(session.storageState);
+                }
+                const primary = 
+                // Reuse the pool's eager context only when we have nothing
+                // to seed — storageState can only be applied at creation.
+                !ctxOptions.storageState && browser.contexts().length > 0
+                    ? browser.contexts()[0]
+                    : await browser.newContext(ctxOptions);
+                return new BrowserSession(this, session, browser, primary);
             }
             catch (err) {
                 if (browser) {
@@ -387,18 +517,23 @@ export class Solari {
         catch (e) {
             throw new SolariError(`Solari: invalid upstream ${kind}Endpoint: ${upstreamEndpoint}`, undefined, e);
         }
-        await this.proxy.start();
-        this.proxy.register(sessionId, upstream, kind);
-        return this.proxy.getLocalEndpoint(sessionId, kind);
+        await this.localProxy.start();
+        this.localProxy.register(sessionId, upstream, kind);
+        return this.localProxy.getLocalEndpoint(sessionId, kind);
     }
     _unregisterSession(sessionId) {
-        this.proxy.unregister(sessionId);
+        this.localProxy.unregister(sessionId);
     }
-    async request(method, path, body) {
+    async request(method, path, body, opts) {
         const url = `${this.baseUrl}${path}`;
+        // Built ONCE, outside the retry loop, so every attempt of this call
+        // carries the same key. See newIdempotencyKey.
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
+            ...(opts?.idempotencyKey
+                ? { "Idempotency-Key": opts.idempotencyKey }
+                : {}),
         };
         const payload = body === undefined ? undefined : JSON.stringify(body);
         let lastErr;
@@ -415,7 +550,10 @@ export class Solari {
                 clearTimeout(timer);
                 if (res.ok)
                     return res;
-                if (!isRetryableStatus(res.status))
+                const retryThis = isRetryableStatus(res.status) ||
+                    (isSafeToReplay(method, opts?.idempotencyKey) &&
+                        (await responseSaysRetryable(res)));
+                if (!retryThis)
                     return res;
                 await res.text().catch(() => { });
                 lastErr = new SolariError(`Solari ${method} ${path}: ${res.status}`, res.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/browser",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Official client SDK for Solari Browser.",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,6 +36,8 @@
   },
   "scripts": {
     "build": "tsc",
+    "typecheck": "node ../scripts/typecheck-guard.mjs 2 -- tsc --noEmit",
+    "test": "tsc && node --test test/*.test.mjs",
     "prepublishOnly": "node ../scripts/check-sdk-version-pin.mjs && tsc"
   },
   "dependencies": {