@solarisdk/browser 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -131,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;
@@ -150,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);
@@ -165,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>;
     /**
@@ -189,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

@@ -54,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;
@@ -186,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) {
@@ -203,7 +272,10 @@ class SessionsResource {
             body.captcha = 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;
@@ -296,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");
@@ -318,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.
@@ -443,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;
@@ -471,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.4",
+  "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": {