@solarisdk/browser 0.1.5 → 0.1.7

package/dist/captcha.d.ts

@@ -0,0 +1,66 @@
+export interface CaptchaFailure {
+    code: string;
+    message: string;
+    retryable: boolean;
+    nextAction: "retry_fresh_challenge" | "manual" | "stop";
+    vendorErrorCode?: string;
+}
+export interface CaptchaStatus {
+    id: string;
+    provider: string;
+    vendor: string;
+    url: string;
+    stage: "detected" | "solving" | "vendor_solved" | "applied" | "failed" | "cancelled";
+    startedAt: number;
+    updatedAt: number;
+    durationMs: number;
+    websiteVerification: "unknown" | "accepted" | "rejected" | "timed_out";
+    verificationSource?: "client";
+    error?: CaptchaFailure;
+}
+export declare class CaptchaError extends Error {
+    readonly failure: CaptchaFailure;
+    readonly status?: CaptchaStatus | undefined;
+    constructor(failure: CaptchaFailure, status?: CaptchaStatus | undefined);
+}
+interface CaptchaTransport {
+    send(method: string, params?: Record<string, unknown>): Promise<any>;
+    on(event: string, listener: (status: CaptchaStatus) => void): unknown;
+    off(event: string, listener: (status: CaptchaStatus) => void): unknown;
+}
+/** Session outcome polling or an existing raw-CDP transport. No token is exposed. */
+export declare class CaptchaObserver {
+    private readonly transport;
+    private readonly disconnect;
+    private readonly history;
+    private readonly listeners;
+    private closed;
+    private readonly waits;
+    private readonly receive;
+    private constructor();
+    /** Poll over the public session API, without creating another browser
+     * connection. Works for both Playwright wire and raw-CDP task clients. */
+    static forSession(client: {
+        request(method: string, path: string, body?: unknown): Promise<Response>;
+    }, sessionId: string): Promise<CaptchaObserver>;
+    /** Also accepts an existing raw-CDP transport; useful for other agents. */
+    static attach(transport: CaptchaTransport, disconnect?: () => Promise<void>): Promise<CaptchaObserver>;
+    onStatus(listener: (status: CaptchaStatus) => void): () => void;
+    statuses(): Promise<CaptchaStatus[]>;
+    reportVerification(attemptId: string, accepted: boolean): Promise<boolean>;
+    /** Resolves only after the caller's website-specific verifier returns true.
+     * Await this before resuming the agent. Manual recovery runs at most once
+     * per attempt and shares the same deadline; it never refreshes/re-bills
+     * automatically. A rejected/expired token requires a fresh challenge. */
+    waitForVerification(options: {
+        verify: () => Promise<boolean>;
+        /** Scope multi-widget/tab sessions to the challenge being verified. */
+        attemptId?: string;
+        provider?: string;
+        timeoutMs?: number;
+        onManualRequired?: (status: CaptchaStatus, signal: AbortSignal) => Promise<void>;
+        signal?: AbortSignal;
+    }): Promise<CaptchaStatus>;
+    close(): Promise<void>;
+}
+export {};

package/dist/captcha.js

@@ -0,0 +1,229 @@
+export class CaptchaError extends Error {
+    failure;
+    status;
+    constructor(failure, status) {
+        super(`${failure.code}: ${failure.message}`);
+        this.failure = failure;
+        this.status = status;
+        this.name = "CaptchaError";
+    }
+}
+function timeoutFailure() {
+    return new CaptchaError({ code: "TIMEOUT", message: "CAPTCHA verification did not finish before the deadline",
+        retryable: false, nextAction: "manual" });
+}
+/** Session outcome polling or an existing raw-CDP transport. No token is exposed. */
+export class CaptchaObserver {
+    transport;
+    disconnect;
+    history = new Map();
+    listeners = new Set();
+    closed = false;
+    waits = new Set();
+    receive = (status) => {
+        if (this.closed)
+            return;
+        const previous = this.history.get(status.id);
+        if (previous) {
+            if (status.updatedAt < previous.updatedAt)
+                return;
+            // A delayed HTTP snapshot may arrive after a terminal CDP event.
+            // The server never reopens an attempt after application/failure.
+            const terminal = ["applied", "failed", "cancelled"].includes(previous.stage);
+            if (terminal && status.stage !== previous.stage)
+                return;
+            const rank = { detected: 0, solving: 1, vendor_solved: 2, applied: 3, failed: 3, cancelled: 3 };
+            if (status.updatedAt === previous.updatedAt && rank[status.stage] < rank[previous.stage])
+                return;
+            if (previous.verificationSource === "client" && previous.websiteVerification !== "unknown" &&
+                (status.websiteVerification === "unknown" || previous.websiteVerification !== "timed_out" && status.websiteVerification !== previous.websiteVerification))
+                return;
+            if (JSON.stringify(previous) === JSON.stringify(status))
+                return;
+        }
+        this.history.set(status.id, structuredClone(status));
+        if (this.history.size > 64)
+            this.history.delete(this.history.keys().next().value);
+        for (const listener of this.listeners) {
+            try {
+                listener(structuredClone(status));
+            }
+            catch { }
+        }
+    };
+    constructor(transport, disconnect) {
+        this.transport = transport;
+        this.disconnect = disconnect;
+    }
+    /** Poll over the public session API, without creating another browser
+     * connection. Works for both Playwright wire and raw-CDP task clients. */
+    static async forSession(client, sessionId) {
+        const prefix = `/sessions/${encodeURIComponent(sessionId)}/captcha`;
+        const transport = {
+            on() { }, off() { },
+            async send(method, params) {
+                if (method === "Solari.enableCaptchaEvents")
+                    return {};
+                const response = await client.request(method === "Solari.getCaptchaStatus" ? "GET" : "POST", prefix + (method === "Solari.getCaptchaStatus" ? "" : "/verification"), params);
+                if (!response.ok)
+                    throw new CaptchaError({ code: "STATUS_UNAVAILABLE",
+                        message: `CAPTCHA status HTTP ${response.status}`, retryable: response.status >= 500, nextAction: "stop" });
+                return response.json();
+            },
+        };
+        const observer = await CaptchaObserver.attach(transport);
+        await observer.statuses();
+        return observer;
+    }
+    /** Also accepts an existing raw-CDP transport; useful for other agents. */
+    static async attach(transport, disconnect = async () => { }) {
+        const observer = new CaptchaObserver(transport, disconnect);
+        transport.on("Solari.captchaStatusChanged", observer.receive);
+        try {
+            await transport.send("Solari.enableCaptchaEvents", { includeStatus: true });
+        }
+        catch (error) {
+            transport.off("Solari.captchaStatusChanged", observer.receive);
+            throw error;
+        }
+        return observer;
+    }
+    onStatus(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    async statuses() {
+        if (this.closed)
+            throw new Error("CAPTCHA observer is closed");
+        const result = await this.transport.send("Solari.getCaptchaStatus");
+        for (const status of result.attempts ?? [])
+            this.receive(status);
+        return [...this.history.values()].sort((a, b) => a.startedAt - b.startedAt).map(status => structuredClone(status));
+    }
+    async reportVerification(attemptId, accepted) {
+        if (this.closed)
+            throw new Error("CAPTCHA observer is closed");
+        const result = await this.transport.send("Solari.reportCaptchaVerification", { attemptId, accepted });
+        return result.recorded === true;
+    }
+    /** Resolves only after the caller's website-specific verifier returns true.
+     * Await this before resuming the agent. Manual recovery runs at most once
+     * per attempt and shares the same deadline; it never refreshes/re-bills
+     * automatically. A rejected/expired token requires a fresh challenge. */
+    async waitForVerification(options) {
+        const timeoutMs = options.timeoutMs ?? 300_000;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new Error("timeoutMs must be positive");
+        const controller = new AbortController();
+        this.waits.add(controller);
+        const deadline = Date.now() + timeoutMs;
+        const timer = setTimeout(() => controller.abort(timeoutFailure()), timeoutMs);
+        const abort = () => controller.abort(options.signal?.reason ?? new Error("CAPTCHA wait aborted"));
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        const manual = new Set();
+        let lastAttempt;
+        // Start lazily: a cancelled deadline must not initiate another request,
+        // verifier, manual callback or an unobserved rejected promise.
+        const bounded = (operation) => new Promise((resolve, reject) => {
+            if (controller.signal.aborted) {
+                reject(controller.signal.reason);
+                return;
+            }
+            const fail = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", fail, { once: true });
+            try {
+                operation().then(resolve, reject).finally(() => controller.signal.removeEventListener("abort", fail));
+            }
+            catch (error) {
+                controller.signal.removeEventListener("abort", fail);
+                reject(error);
+            }
+        });
+        const selected = (statuses) => statuses.filter(status => (!options.attemptId || status.id === options.attemptId) &&
+            (!options.provider || status.provider === options.provider));
+        const active = (statuses) => statuses.some(status => ["detected", "solving", "vendor_solved"].includes(status.stage));
+        const latestOf = (statuses) => statuses.filter(status => status.stage !== "cancelled").at(-1);
+        const stillCurrent = (statuses, id) => !active(statuses) && latestOf(statuses)?.id === id && latestOf(statuses)?.websiteVerification !== "rejected";
+        const pollDelay = () => bounded(() => new Promise(resolve => setTimeout(resolve, 250)));
+        try {
+            while (Date.now() < deadline) {
+                if (this.closed)
+                    throw new Error("CAPTCHA observer is closed");
+                const statuses = selected(await bounded(() => this.statuses()));
+                const latest = latestOf(statuses);
+                lastAttempt = latest;
+                if (!active(statuses) && latest) {
+                    if (latest.websiteVerification === "rejected")
+                        throw new CaptchaError({
+                            code: "WEBSITE_REJECTED", message: "The website rejected CAPTCHA verification",
+                            retryable: true, nextAction: "retry_fresh_challenge",
+                        }, latest);
+                    if (await bounded(() => options.verify())) {
+                        // The verifier and the report are asynchronous. A new
+                        // challenge may have started during either operation.
+                        const beforeReport = selected(await bounded(() => this.statuses()));
+                        lastAttempt = latestOf(beforeReport);
+                        if (!stillCurrent(beforeReport, latest.id)) {
+                            await pollDelay();
+                            continue;
+                        }
+                        const result = await bounded(() => this.transport.send("Solari.reportCaptchaVerification", { attemptId: latest.id, accepted: true }));
+                        if (!result.recorded)
+                            throw new Error("CAPTCHA verification could not be recorded for this attempt");
+                        const afterReport = selected(await bounded(() => this.statuses()));
+                        lastAttempt = latestOf(afterReport);
+                        if (!stillCurrent(afterReport, latest.id)) {
+                            await pollDelay();
+                            continue;
+                        }
+                        return { ...latestOf(afterReport), websiteVerification: "accepted", verificationSource: "client" };
+                    }
+                    if (latest.stage === "failed") {
+                        if (!options.onManualRequired || latest.error?.nextAction === "stop")
+                            throw new CaptchaError(latest.error ?? { code: "UNKNOWN", message: "CAPTCHA solving failed", retryable: false, nextAction: "manual" }, latest);
+                        if (!manual.has(latest.id)) {
+                            const beforeHandoff = selected(await bounded(() => this.statuses()));
+                            lastAttempt = latestOf(beforeHandoff);
+                            if (!stillCurrent(beforeHandoff, latest.id)) {
+                                await pollDelay();
+                                continue;
+                            }
+                            manual.add(latest.id);
+                            await bounded(() => options.onManualRequired(latest, controller.signal));
+                        }
+                    }
+                }
+                await pollDelay();
+            }
+            throw timeoutFailure();
+        }
+        catch (error) {
+            if (error instanceof CaptchaError && error.failure.code === "TIMEOUT" && lastAttempt?.stage === "applied") {
+                let reportTimer;
+                await Promise.race([
+                    this.transport.send("Solari.reportCaptchaVerification", { attemptId: lastAttempt.id, outcome: "timed_out" }).catch(() => { }),
+                    new Promise(resolve => { reportTimer = setTimeout(resolve, 1_000); }),
+                ]).finally(() => clearTimeout(reportTimer));
+            }
+            throw error;
+        }
+        finally {
+            this.waits.delete(controller);
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.listeners.clear();
+        for (const wait of this.waits)
+            wait.abort(new Error("CAPTCHA observer is closed"));
+        this.waits.clear();
+        this.transport.off("Solari.captchaStatusChanged", this.receive);
+        await this.disconnect();
+    }
+}

package/dist/index.d.ts

@@ -130,7 +130,9 @@ export interface LaunchOptions extends CreateSessionOptions {
     /** Hard upper bound on the post-connect probe in ms. Default 2000. */
     probeTimeoutMs?: number;
 }
-export type SolariErrorCode = "FeatureRequiresPlan" | "ConcurrencyLimitExceeded" | "PlanLimitExceeded" | "BrowserUnhealthy" | "InvalidSessionId";
+export type SolariErrorCode = "FeatureRequiresPlan" | "ConcurrencyLimitExceeded" | "PlanLimitExceeded" | "BrowserUnhealthy" | "InvalidSessionId"
+/** A proxy tier you explicitly requested cannot be served right now (503). No session was created. */
+ | "ProxyTierUnavailable";
 /** Supported egress countries and residential-proxy status, from
  *  {@link Solari.proxy}.countries() (`GET /proxy/countries`). */
 export interface ProxyCountries {

package/dist/index.js

@@ -109,6 +109,24 @@ async function responseSaysRetryable(res) {
         return false;
     }
 }
+// Some 5xx are answers, not outages: retrying cannot change them, and swallowing the body would hide the
+// code from the caller. The gateway says so itself with `retryable: false` (502 `PoolResponseUnparseable`:
+// the session may already exist, so a retry creates a second one; 503 `EgressBlockPeekUnsupportedOnFlavor`).
+// `ProxyTierUnavailable` (explicitly requested proxy tier not servable) is also terminal, whatever its flag.
+const TERMINAL_503_CODES = new Set(["ProxyTierUnavailable"]);
+async function responseIsTerminal(res) {
+    try {
+        const body = (await res.clone().json());
+        if (body?.retryable === false)
+            return true;
+        return (res.status === 503 &&
+            typeof body?.code === "string" &&
+            TERMINAL_503_CODES.has(body.code));
+    }
+    catch {
+        return false;
+    }
+}
 function isRetryableError(_err) {
     return true;
 }
@@ -439,6 +457,17 @@ export class Solari {
                 // 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.
+                //
+                // DELIBERATE DOUBLE-SEED (audit-profiles-not-applied): the pool
+                // now ALSO seeds browser.contexts()[0] server-side whenever
+                // storageStateUrl is present, so a published build of this SDK
+                // talking to a fixed gateway seeds the same profile twice (one
+                // extra GCS fetch, harmless). DO NOT remove this seed on the
+                // assumption the server already did it — this SDK version may
+                // be talking to an OLDER gateway that doesn't carry the
+                // server-side fix, and the server has no way to tell the SDK
+                // whether it already seeded. Version skew means the SDK must
+                // assume the server did nothing.
                 const ctxOptions = {};
                 const tz = session.proxy?.timezoneId;
                 if (tz)
@@ -550,10 +579,13 @@ export class Solari {
                 clearTimeout(timer);
                 if (res.ok)
                     return res;
-                const retryThis = isRetryableStatus(res.status) ||
+                const retryThis = (isRetryableStatus(res.status) && !(await responseIsTerminal(res))) ||
                     (isSafeToReplay(method, opts?.idempotencyKey) &&
                         (await responseSaysRetryable(res)));
-                if (!retryThis)
+                // 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)
                     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.5",
+  "version": "0.1.7",
   "description": "Official client SDK for Solari Browser.",
   "license": "Apache-2.0",
   "type": "module",