@solarisdk/browser 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Solari Browser
+
+   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
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   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.

package/README.md

@@ -0,0 +1,107 @@
+# @solarisdk/browser
+
+Official client SDK for [Solari Browser](https://solaribrowser.com) — managed,
+stealth-hardened browsers as an API.
+
+## Install
+
+```bash
+npm install @solarisdk/browser
+```
+
+## Quickstart
+
+```ts
+import { Solari } from "@solarisdk/browser";
+
+const solari = new Solari({
+    apiKey: process.env.SOLARI_API_KEY!,
+    // region: "us-west",  // default — additional regions coming soon
+});
+
+const browser = await solari.launch({ stealth: true });
+const page = await browser.newPage();
+await page.goto("https://example.com");
+console.log(await page.title());
+await browser.close();
+```
+
+Or with explicit resource management (Node 22+):
+
+```ts
+await using browser = await solari.launch({ stealth: true });
+const page = await browser.newPage();
+await page.goto("https://example.com");
+```
+
+## Sessions
+
+Drive a session yourself instead of using `launch()`:
+
+```ts
+const session = await solari.sessions.create({ stealth: true });
+// connect via Playwright wire protocol
+import { chromium } from "patchright-core";
+const browser = await chromium.connect(session.wsEndpoint);
+// ...
+await browser.close();
+await solari.sessions.releaseAndWait(session.id);
+```
+
+Or via raw CDP (Puppeteer, browser-use, playwright-core):
+
+```ts
+const session = await solari.sessions.create();
+const browser = await chromium.connectOverCDP(session.cdpEndpoint);
+```
+
+## Regions
+
+Solari runs in `us-west` (N. California) today, with additional regions
+coming soon. Sessions, replays, and profile storage are colocated with
+the region you pick.
+
+```ts
+const solari = new Solari({ apiKey, region: "us-west" });
+```
+
+For staging or self-hosted gateways, pass `baseUrl` instead of `region`.
+
+## Managed proxies
+
+```ts
+await solari.launch({
+    stealth: true,
+    proxy: { country: "us", tier: "mobile" },
+});
+```
+
+For targets whose stealth posture is unknown a priori, `proxy: "smart"`
+runs an escalation ladder (rotating residential → direct → mobile → fresh
+residential → residential GB) and swaps the egress in-place when a block
+page is detected mid-session — no client-side retry required.
+
+```ts
+await solari.launch({ stealth: true, proxy: "smart" });
+```
+
+See the [Solari docs](https://docs.solaribrowser.com) for the full proxy,
+stealth, captcha, and profile reference.
+
+## Errors
+
+```ts
+import { SolariError } from "@solarisdk/browser";
+
+try {
+    await solari.sessions.create({ stealth: true });
+} catch (err) {
+    if (err instanceof SolariError && err.code === "FeatureRequiresPlan") {
+        // ...
+    }
+}
+```
+
+## License
+
+Apache-2.0

package/dist/browser-session.d.ts

@@ -0,0 +1,36 @@
+import type { Browser, BrowserContext, BrowserContextOptions, Page } from "patchright-core";
+import type { Solari } from "./index.js";
+import type { Session } from "./index.js";
+export declare class BrowserSession {
+    private readonly client;
+    readonly session: Session;
+    private readonly browser;
+    private closed;
+    constructor(client: Solari, session: Session, browser: Browser);
+    /** Session id. */
+    get id(): string;
+    /** Plan-tier deadline (ISO 8601 UTC); session auto-releases at this point. */
+    get expiresAt(): string;
+    /** Resolved proxy credentials, when a proxy was requested. */
+    get proxy(): Session["proxy"];
+    /** Playwright wire-protocol endpoint (loopback-wrapped). */
+    get wsEndpoint(): string;
+    /** Raw CDP endpoint (loopback-wrapped). */
+    get cdpEndpoint(): string;
+    /** Underlying Browser. Use for advanced APIs not surfaced on this wrapper. */
+    get raw(): Browser;
+    /** `true` while the underlying browser connection is alive. */
+    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]`. */
+    contexts(): BrowserContext[];
+    /** Open a fresh browser context. Most callers want `contexts()[0]` instead. */
+    newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
+    /** Open a fresh page in a new context. */
+    newPage(): Promise<Page>;
+    /** Close the browser and release the session. Idempotent. */
+    close(): Promise<void>;
+    /** Supports `await using browser = await solari.launch()` (Node 22+). */
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/browser-session.js

@@ -0,0 +1,82 @@
+export class BrowserSession {
+    client;
+    session;
+    browser;
+    closed = false;
+    constructor(client, session, browser) {
+        this.client = client;
+        this.session = session;
+        this.browser = browser;
+    }
+    /** Session id. */
+    get id() {
+        return this.session.id;
+    }
+    /** Plan-tier deadline (ISO 8601 UTC); session auto-releases at this point. */
+    get expiresAt() {
+        return this.session.expiresAt;
+    }
+    /** Resolved proxy credentials, when a proxy was requested. */
+    get proxy() {
+        return this.session.proxy;
+    }
+    /** Playwright wire-protocol endpoint (loopback-wrapped). */
+    get wsEndpoint() {
+        return this.session.wsEndpoint;
+    }
+    /** Raw CDP endpoint (loopback-wrapped). */
+    get cdpEndpoint() {
+        return this.session.cdpEndpoint;
+    }
+    /** Underlying Browser. Use for advanced APIs not surfaced on this wrapper. */
+    get raw() {
+        return this.browser;
+    }
+    /** `true` while the underlying browser connection is alive. */
+    isConnected() {
+        return !this.closed && this.browser.isConnected();
+    }
+    /** Browser version string (e.g. `"Chromium/130.0.6723.31"`). */
+    version() {
+        return this.browser.version();
+    }
+    /** All open contexts. Sessions ship with a default context at `contexts()[0]`. */
+    contexts() {
+        return this.browser.contexts();
+    }
+    /** Open a fresh browser context. Most callers want `contexts()[0]` instead. */
+    async newContext(options) {
+        return this.browser.newContext(options);
+    }
+    /** Open a fresh page in a new context. */
+    async newPage() {
+        return this.browser.newPage();
+    }
+    /** Close the browser and release the session. Idempotent. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        let browserErr;
+        try {
+            await this.browser.close();
+        }
+        catch (e) {
+            browserErr = e;
+        }
+        try {
+            await this.client.sessions.releaseAndWait(this.session.id);
+        }
+        catch (releaseErr) {
+            if (browserErr)
+                throw browserErr;
+            throw releaseErr;
+        }
+        if (browserErr)
+            throw browserErr;
+    }
+    /** Supports `await using browser = await solari.launch()` (Node 22+). */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+import { type ProxyKind } from "./local-proxy.js";
+import { BrowserSession } from "./browser-session.js";
+export { BrowserSession } from "./browser-session.js";
+/** Supported Solari regions. More coming soon. */
+export type SolariRegion = "us-west";
+export interface SolariOptions {
+    apiKey: string;
+    /** Region to route sessions through. Defaults to `"us-west"`.
+     *  Additional regions (e.g. `us-east`) are coming soon. */
+    region?: SolariRegion;
+    /** Override the resolved region URL. Useful for staging / self-hosted
+     *  gateways. When set, `region` is ignored. */
+    baseUrl?: string;
+    maxAttempts?: number;
+    backoffMs?: number;
+    timeoutMs?: number;
+}
+export interface StorageState {
+    cookies?: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+        path?: string;
+        expires?: number;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: "Strict" | "Lax" | "None";
+    }>;
+    origins?: Array<{
+        origin: string;
+        localStorage?: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+    [k: string]: unknown;
+}
+/** Managed proxy egress request. */
+export interface ProxyRequest {
+    /** ISO-3166-1 alpha-2, lowercase. Defaults to "us". */
+    country?: string;
+    /** Proxy tier: `"residential"` (default, rotating), `"static"` (fixed ISP IP),
+     *  or `"mobile"` (carrier IPs). */
+    tier?: "residential" | "static" | "mobile";
+    /** @deprecated Use `tier: "static"`. */
+    static?: boolean;
+    /** Pin egress to a specific ASN (e.g. "20057" for AT&T Mobility). */
+    asn?: string;
+    /** Sticky-session id (alnum + dash, ≤32 chars). Pins egress IP for
+     *  `sessionDuration` minutes. */
+    session?: string;
+    /** Sticky lifetime in minutes (1–30, default 10). Only with `session`. */
+    sessionDuration?: number;
+    /** US-only geo narrowing (e.g. "california"). */
+    state?: string;
+    /** US-only city pin (e.g. "los_angeles"). */
+    city?: string;
+}
+/** Resolved proxy credentials returned on the session response. */
+export interface ResolvedProxyConfig {
+    server: string;
+    username: string;
+    password: string;
+    timezoneId: string;
+    country: string;
+    tier?: "residential" | "static" | "mobile";
+}
+export interface Session {
+    id: string;
+    /** Playwright wire-protocol endpoint for `chromium.connect()`. */
+    wsEndpoint: string;
+    /** Raw CDP endpoint for `chromium.connectOverCDP()` or Puppeteer. */
+    cdpEndpoint: string;
+    /** Plan-tier deadline (ISO 8601 UTC); session auto-releases at this point. */
+    expiresAt: string;
+    /** `undefined` = no profile attached; `null` = profile exists but empty. */
+    storageState?: StorageState | null;
+    /** Present only when a managed proxy was requested. */
+    proxy?: ResolvedProxyConfig;
+}
+export interface Profile {
+    id: string;
+    name: string;
+    [k: string]: unknown;
+}
+export interface CreateSessionOptions {
+    /** Attach a stored browser profile (cookies + localStorage). */
+    profileId?: string;
+    /** Enable session recording. Off by default. */
+    recording?: boolean;
+    /** Enable the runtime stealth shim. Off by default. */
+    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"
+     *    proxy: { country: "gb" }
+     *    proxy: { country: "us", tier: "static" }
+     *    proxy: { country: "us", tier: "mobile" }
+     *    proxy: { country: "us", session: "warm-1" }
+     *    proxy: "smart"
+     *    proxy: "off"
+     */
+    proxy?: string | ProxyRequest | "off" | "smart";
+}
+export interface ReplayUrl {
+    url: string;
+    expiresInSeconds: number;
+    contentEncoding: string;
+}
+/** Options for `Solari.launch()`. Strict superset of `CreateSessionOptions`. */
+export interface LaunchOptions extends CreateSessionOptions {
+    /** Additional re-launch attempts after the first failure. Default 0. */
+    retries?: number;
+    /** Probe the connected browser before returning. Defaults to `true` when
+     *  `retries > 0`, `false` otherwise. */
+    probe?: boolean;
+    /** Hard upper bound on the post-connect probe in ms. Default 2000. */
+    probeTimeoutMs?: number;
+}
+export type SolariErrorCode = "FeatureRequiresPlan" | "ConcurrencyLimitExceeded" | "PlanLimitExceeded" | "BrowserUnhealthy";
+export declare class SolariError extends Error {
+    readonly status?: number | undefined;
+    readonly cause?: unknown | undefined;
+    readonly code?: (SolariErrorCode | string) | undefined;
+    constructor(message: string, status?: number | undefined, cause?: unknown | undefined, code?: (SolariErrorCode | string) | undefined);
+}
+declare class ProfilesResource {
+    private readonly client;
+    constructor(client: Solari);
+    create(opts: {
+        name: string;
+    }): Promise<Profile>;
+    list(): Promise<Profile[]>;
+    delete(id: string): Promise<void>;
+    save(id: string, storageState: StorageState): Promise<{
+        version: number;
+        sizeBytes: number;
+    }>;
+}
+declare class SessionsResource {
+    private readonly client;
+    constructor(client: Solari);
+    create(options?: CreateSessionOptions): Promise<Session>;
+    /** Fire-and-forget release. Use `releaseAndWait` for confirmation. */
+    release(id: string): void;
+    releaseAndWait(id: string): Promise<void>;
+    /** Presigned URL for the session's replay. Available ~1-3s after `releaseAndWait`. */
+    getReplayUrl(id: string): Promise<ReplayUrl>;
+    /** Download the replay as NDJSON bytes. */
+    downloadReplay(id: string): Promise<Uint8Array>;
+}
+export declare class Solari {
+    readonly sessions: SessionsResource;
+    readonly profiles: ProfilesResource;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxAttempts;
+    private readonly backoffMs;
+    private readonly timeoutMs;
+    private readonly proxy;
+    constructor(opts: SolariOptions);
+    close(): Promise<void>;
+    /**
+     * Create a session and return a connected browser.
+     *
+     *   const browser = await solari.launch({ stealth: true });
+     *   const page = await browser.newPage();
+     *   await page.goto("https://example.com");
+     *   await browser.close();
+     *
+     * Or with explicit resource management (Node 22+):
+     *
+     *   await using browser = await solari.launch({ stealth: true });
+     */
+    launch(options?: LaunchOptions): Promise<BrowserSession>;
+    private _probeBrowserHealth;
+    _wrapSessionEndpoint(sessionId: string, upstreamEndpoint: string, kind?: ProxyKind): Promise<string>;
+    _unregisterSession(sessionId: string): void;
+    request(method: string, path: string, body?: unknown): Promise<Response>;
+}

package/dist/index.js

@@ -0,0 +1,401 @@
+import { chromium } from "patchright-core";
+import { LocalProxy } from "./local-proxy.js";
+import { BrowserSession } from "./browser-session.js";
+export { BrowserSession } from "./browser-session.js";
+export class SolariError extends Error {
+    status;
+    cause;
+    code;
+    constructor(message, status, cause, code) {
+        super(message);
+        this.status = status;
+        this.cause = cause;
+        this.code = code;
+        this.name = "SolariError";
+    }
+}
+const REGION_URLS = {
+    "us-west": "https://api.solaribrowser.com",
+};
+const DEFAULT_REGION = "us-west";
+const DEFAULT_MAX_ATTEMPTS = 2;
+const DEFAULT_BACKOFF_MS = 500;
+const DEFAULT_TIMEOUT_MS = 90_000;
+function isRetryableStatus(status) {
+    return status === 502 || status === 503 || status === 504;
+}
+function isRetryableError(_err) {
+    return true;
+}
+function isLikelyTransientConnect(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (!message)
+        return false;
+    return /ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|socket hang up|WebSocket|connect|handshake|Browser closed|Target page, context or browser has been closed/i
+        .test(message);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function fetchPresignedStorageState(url) {
+    if (!url)
+        return null;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "GET",
+            signal: AbortSignal.timeout(8_000),
+        });
+    }
+    catch (err) {
+        throw new SolariError(`Solari: failed to fetch storageState: ${err instanceof Error ? err.message : String(err)}`, undefined, err);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new SolariError(`Solari: storageState fetch returned ${res.status}: ${body.slice(0, 256)}`, res.status);
+    }
+    try {
+        return (await res.json());
+    }
+    catch (err) {
+        throw new SolariError(`Solari: storageState response was not valid JSON: ${err instanceof Error ? err.message : String(err)}`, undefined, err);
+    }
+}
+function deriveCdpFromWs(wsEndpoint) {
+    try {
+        const u = new URL(wsEndpoint);
+        if (u.pathname.startsWith("/ws/")) {
+            u.pathname = "/cdp/" + u.pathname.slice("/ws/".length);
+            return u.toString();
+        }
+    }
+    catch { }
+    return wsEndpoint;
+}
+class ProfilesResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async create(opts) {
+        const res = await this.client.request("POST", "/profiles", { name: opts.name });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            let code;
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed.code === "string")
+                    code = parsed.code;
+            }
+            catch { }
+            throw new SolariError(`Solari POST /profiles failed: ${res.status} ${text}`, res.status, undefined, code);
+        }
+        return (await res.json());
+    }
+    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);
+        }
+        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);
+        }
+    }
+    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);
+        }
+        const data = (await res.json());
+        return {
+            version: data.version ?? 0,
+            sizeBytes: data.sizeBytes ?? 0,
+        };
+    }
+}
+class SessionsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async create(options) {
+        const body = {};
+        if (options?.profileId)
+            body.profileId = options.profileId;
+        if (options?.recording)
+            body.recording = true;
+        if (options?.stealth === true)
+            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);
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            let code;
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed?.code === "string")
+                    code = parsed.code;
+            }
+            catch { }
+            throw new SolariError(`Solari POST /sessions failed: ${res.status} ${text}`, res.status, undefined, code);
+        }
+        const data = (await res.json());
+        if (!data.sessionId || !data.wsEndpoint) {
+            throw new SolariError(`Solari: unexpected session response: ${JSON.stringify(data)}`);
+        }
+        const cdpUpstream = data.cdpEndpoint ?? deriveCdpFromWs(data.wsEndpoint);
+        const localWsEndpoint = await this.client._wrapSessionEndpoint(data.sessionId, data.wsEndpoint, "ws");
+        const localCdpEndpoint = await this.client._wrapSessionEndpoint(data.sessionId, cdpUpstream, "cdp");
+        const expiresAt = data.expiresAt
+            ?? new Date(Date.now() + 60 * 60_000).toISOString();
+        const session = {
+            id: data.sessionId,
+            wsEndpoint: localWsEndpoint,
+            cdpEndpoint: localCdpEndpoint,
+            expiresAt,
+        };
+        if (options?.profileId !== undefined) {
+            if (data.storageStateUrl !== undefined) {
+                session.storageState = await fetchPresignedStorageState(data.storageStateUrl.url);
+            }
+            else {
+                session.storageState = data.storageState ?? null;
+            }
+        }
+        if (data.proxy) {
+            session.proxy = data.proxy;
+        }
+        return session;
+    }
+    /** Fire-and-forget release. Use `releaseAndWait` for confirmation. */
+    release(id) {
+        this.client._unregisterSession(id);
+        void this.client.request("DELETE", `/sessions/${encodeURIComponent(id)}`).then((res) => {
+            if (!res.ok && res.status !== 404) {
+                res.text().catch(() => "").then((body) => {
+                    console.warn(`[Solari] DELETE /sessions/${id} returned ${res.status}: ${body}`);
+                });
+            }
+        }, (err) => {
+            console.warn(`[Solari] DELETE /sessions/${id} failed (fire-and-forget):`, err);
+        });
+    }
+    async releaseAndWait(id) {
+        this.client._unregisterSession(id);
+        const res = await this.client.request("DELETE", `/sessions/${encodeURIComponent(id)}`);
+        if (!res.ok && res.status !== 404) {
+            const body = await res.text().catch(() => "");
+            throw new SolariError(`Solari DELETE /sessions/${id} failed: ${res.status} ${body}`, res.status);
+        }
+    }
+    /** 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);
+        }
+        const data = (await res.json());
+        if (!data.url) {
+            throw new SolariError(`Solari: unexpected replay-url response: ${JSON.stringify(data)}`);
+        }
+        return {
+            url: data.url,
+            expiresInSeconds: data.expiresInSeconds ?? 0,
+            contentEncoding: data.contentEncoding ?? "gzip",
+        };
+    }
+    /** Download the replay as NDJSON bytes. */
+    async downloadReplay(id) {
+        const { url } = await this.getReplayUrl(id);
+        const res = await fetch(url);
+        if (!res.ok) {
+            throw new SolariError(`Solari: replay download failed: ${res.status} ${res.statusText}`, res.status);
+        }
+        const buf = await res.arrayBuffer();
+        return new Uint8Array(buf);
+    }
+}
+export class Solari {
+    sessions;
+    profiles;
+    apiKey;
+    baseUrl;
+    maxAttempts;
+    backoffMs;
+    timeoutMs;
+    proxy = new LocalProxy();
+    constructor(opts) {
+        if (!opts.apiKey) {
+            throw new SolariError("Solari: apiKey is required");
+        }
+        this.apiKey = opts.apiKey;
+        const region = opts.region ?? DEFAULT_REGION;
+        const regionUrl = REGION_URLS[region];
+        if (!regionUrl) {
+            throw new SolariError(`Solari: unsupported region "${region}". Supported: ${Object.keys(REGION_URLS).join(", ")}.`);
+        }
+        this.baseUrl = (opts.baseUrl ?? regionUrl).replace(/\/$/, "");
+        this.maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.backoffMs = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.sessions = new SessionsResource(this);
+        this.profiles = new ProfilesResource(this);
+    }
+    async close() {
+        await this.proxy.stop();
+    }
+    /**
+     * Create a session and return a connected browser.
+     *
+     *   const browser = await solari.launch({ stealth: true });
+     *   const page = await browser.newPage();
+     *   await page.goto("https://example.com");
+     *   await browser.close();
+     *
+     * Or with explicit resource management (Node 22+):
+     *
+     *   await using browser = await solari.launch({ stealth: true });
+     */
+    async launch(options) {
+        const retries = Math.max(0, options?.retries ?? 0);
+        const probeEnabled = options?.probe ?? retries > 0;
+        const probeTimeoutMs = Math.max(1, options?.probeTimeoutMs ?? 2_000);
+        const totalAttempts = retries + 1;
+        let sessionOpts;
+        if (options) {
+            const { retries: _r, probe: _p, probeTimeoutMs: _t, ...rest } = options;
+            sessionOpts = rest;
+        }
+        let lastErr;
+        for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+            const session = await this.sessions.create(sessionOpts);
+            let browser;
+            try {
+                browser = await chromium.connect(session.wsEndpoint);
+                if (probeEnabled) {
+                    await this._probeBrowserHealth(browser, probeTimeoutMs);
+                }
+                return new BrowserSession(this, session, browser);
+            }
+            catch (err) {
+                if (browser) {
+                    try {
+                        await browser.close();
+                    }
+                    catch { }
+                }
+                try {
+                    this.sessions.release(session.id);
+                }
+                catch { }
+                lastErr = err;
+                const isHealth = err instanceof SolariError && err.code === "BrowserUnhealthy";
+                const transientConnect = !isHealth && isLikelyTransientConnect(err);
+                const retryable = isHealth || transientConnect;
+                if (attempt < totalAttempts && retryable) {
+                    await sleep(100 * attempt);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw lastErr ?? new SolariError("Solari.launch: exhausted attempts");
+    }
+    async _probeBrowserHealth(browser, timeoutMs) {
+        let timer;
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new SolariError(`Solari: browser health probe timed out after ${timeoutMs}ms`, undefined, undefined, "BrowserUnhealthy"));
+            }, timeoutMs);
+        });
+        const probe = async () => {
+            const ctx = await browser.newContext();
+            try {
+                const page = await ctx.newPage();
+                await page.evaluate("1");
+            }
+            finally {
+                await ctx.close().catch(() => { });
+            }
+        };
+        try {
+            await Promise.race([probe(), timeoutPromise]);
+        }
+        catch (err) {
+            if (err instanceof SolariError && err.code === "BrowserUnhealthy") {
+                throw err;
+            }
+            throw new SolariError(`Solari: browser health probe failed: ${err instanceof Error ? err.message : String(err)}`, undefined, err, "BrowserUnhealthy");
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async _wrapSessionEndpoint(sessionId, upstreamEndpoint, kind = "ws") {
+        let upstream;
+        try {
+            upstream = new URL(upstreamEndpoint);
+        }
+        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);
+    }
+    _unregisterSession(sessionId) {
+        this.proxy.unregister(sessionId);
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+        };
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        let lastErr;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+            try {
+                const res = await fetch(url, {
+                    method,
+                    headers,
+                    body: payload,
+                    signal: ac.signal,
+                });
+                clearTimeout(timer);
+                if (res.ok)
+                    return res;
+                if (!isRetryableStatus(res.status))
+                    return res;
+                await res.text().catch(() => { });
+                lastErr = new SolariError(`Solari ${method} ${path}: ${res.status}`, res.status);
+            }
+            catch (e) {
+                clearTimeout(timer);
+                if (!isRetryableError(e))
+                    throw e;
+                lastErr = e;
+            }
+            if (attempt < this.maxAttempts) {
+                await sleep(this.backoffMs);
+            }
+        }
+        throw new SolariError(`Solari ${method} ${path}: exhausted ${this.maxAttempts} attempts`, undefined, lastErr);
+    }
+}

package/dist/local-proxy.d.ts

@@ -0,0 +1,14 @@
+export type ProxyKind = "ws" | "cdp";
+export declare class LocalProxy {
+    private server;
+    private localPort;
+    private starting;
+    private readonly sessions;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    register(sessionId: string, upstream: URL, kind?: ProxyKind): void;
+    unregister(sessionId: string): void;
+    getLocalEndpoint(sessionId: string, kind?: ProxyKind): string;
+    private handleUpgrade;
+    private connectAndPipe;
+}

package/dist/local-proxy.js

@@ -0,0 +1,173 @@
+import http from "node:http";
+import net from "node:net";
+import tls from "node:tls";
+const MAX_UPSTREAM_ATTEMPTS = 3;
+const UPSTREAM_BACKOFF_MS = 50;
+const UPSTREAM_CONNECT_TIMEOUT_MS = 2_000;
+export class LocalProxy {
+    server = null;
+    localPort = null;
+    starting = null;
+    sessions = new Map();
+    async start() {
+        if (this.server)
+            return;
+        if (this.starting)
+            return this.starting;
+        this.starting = new Promise((resolve, reject) => {
+            const server = http.createServer();
+            server.on("upgrade", (req, clientSocket, head) => {
+                this.handleUpgrade(req, clientSocket, head);
+            });
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", () => {
+                const addr = server.address();
+                this.server = server;
+                this.localPort = addr.port;
+                server.off("error", reject);
+                server.on("error", (err) => {
+                    console.error("[solari-sdk:local-proxy] server error:", err);
+                });
+                resolve();
+            });
+        });
+        return this.starting;
+    }
+    async stop() {
+        if (!this.server)
+            return;
+        const server = this.server;
+        this.server = null;
+        this.localPort = null;
+        this.sessions.clear();
+        await new Promise((r) => server.close(() => r()));
+    }
+    register(sessionId, upstream, kind = "ws") {
+        this.sessions.set(`${kind}:${sessionId}`, upstream);
+    }
+    unregister(sessionId) {
+        this.sessions.delete(`ws:${sessionId}`);
+        this.sessions.delete(`cdp:${sessionId}`);
+    }
+    getLocalEndpoint(sessionId, kind = "ws") {
+        if (!this.localPort)
+            throw new Error("LocalProxy not started");
+        return `ws://127.0.0.1:${this.localPort}/${kind}/${encodeURIComponent(sessionId)}`;
+    }
+    handleUpgrade(req, clientSocket, head) {
+        const denyClient = (status, reason) => {
+            try {
+                clientSocket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\n\r\n`);
+            }
+            catch { }
+            clientSocket.destroy();
+        };
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        const match = url.pathname.match(/^\/(ws|cdp)\/([^/]+)$/);
+        if (!match)
+            return denyClient(404, "Not Found");
+        const kind = match[1];
+        const sessionId = decodeURIComponent(match[2]);
+        const upstream = this.sessions.get(`${kind}:${sessionId}`);
+        if (!upstream)
+            return denyClient(404, "Session Not Found");
+        clientSocket.pause();
+        void this.connectAndPipe(req, clientSocket, head, upstream, sessionId).catch((err) => {
+            console.error(`[solari-sdk:local-proxy] upstream failed for ${sessionId.slice(0, 8)}:`, err?.message ?? err);
+            denyClient(502, "Bad Gateway");
+        });
+    }
+    async connectAndPipe(req, clientSocket, head, upstream, sessionId) {
+        const upstreamHost = upstream.hostname;
+        const upstreamPort = Number(upstream.port || (upstream.protocol === "wss:" ? 443 : 80));
+        const useTls = upstream.protocol === "wss:";
+        let upstreamSocket = null;
+        let lastErr;
+        for (let attempt = 1; attempt <= MAX_UPSTREAM_ATTEMPTS; attempt++) {
+            try {
+                upstreamSocket = await tcpConnect(upstreamHost, upstreamPort, UPSTREAM_CONNECT_TIMEOUT_MS, useTls);
+                if (attempt > 1) {
+                    console.error(`[solari-sdk:local-proxy] upstream recovered for ${sessionId.slice(0, 8)} on attempt ${attempt}`);
+                }
+                break;
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt < MAX_UPSTREAM_ATTEMPTS) {
+                    await sleep(UPSTREAM_BACKOFF_MS);
+                }
+            }
+        }
+        if (!upstreamSocket) {
+            throw lastErr ?? new Error("upstream connect: exhausted retries");
+        }
+        try {
+            upstreamSocket.setNoDelay(true);
+        }
+        catch { }
+        try {
+            clientSocket.setNoDelay(true);
+        }
+        catch { }
+        const upstreamPath = (upstream.pathname || "/") + (upstream.search || "");
+        const headerLines = [`GET ${upstreamPath} HTTP/1.1`];
+        headerLines.push(`Host: ${upstreamHost}:${upstreamPort}`);
+        for (const [k, v] of Object.entries(req.headers)) {
+            if (v === undefined)
+                continue;
+            if (k.toLowerCase() === "host")
+                continue;
+            if (Array.isArray(v)) {
+                for (const vv of v)
+                    headerLines.push(`${k}: ${vv}`);
+            }
+            else {
+                headerLines.push(`${k}: ${v}`);
+            }
+        }
+        headerLines.push("", "");
+        upstreamSocket.write(headerLines.join("\r\n"));
+        if (head && head.length)
+            upstreamSocket.write(head);
+        const cleanup = () => {
+            try {
+                upstreamSocket.destroy();
+            }
+            catch { }
+            try {
+                clientSocket.destroy();
+            }
+            catch { }
+        };
+        upstreamSocket.once("error", cleanup);
+        clientSocket.once("error", cleanup);
+        upstreamSocket.once("close", () => clientSocket.destroy());
+        clientSocket.once("close", () => upstreamSocket.destroy());
+        upstreamSocket.pipe(clientSocket);
+        clientSocket.pipe(upstreamSocket);
+        clientSocket.resume();
+    }
+}
+function tcpConnect(host, port, timeoutMs, useTls = false) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const done = (err, socket) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err || !socket)
+                reject(err ?? new Error("no socket"));
+            else
+                resolve(socket);
+        };
+        const socket = useTls
+            ? tls.connect({ host, port, servername: host }, () => done(null, socket))
+            : net.connect(port, host, () => done(null, socket));
+        const timer = setTimeout(() => { socket.destroy(); done(new Error(`connect timeout ${timeoutMs}ms to ${host}:${port}`)); }, timeoutMs);
+        socket.once("error", (err) => { done(err); });
+    });
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@solarisdk/browser",
+  "version": "0.1.0",
+  "description": "Official client SDK for Solari Browser.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "browser",
+    "automation",
+    "playwright",
+    "chromium",
+    "cdp",
+    "headless",
+    "stealth",
+    "scraping",
+    "solari"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "node ../scripts/check-sdk-version-pin.mjs && tsc"
+  },
+  "dependencies": {
+    "patchright-core": "1.59.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}