@aluvia-connect/agent-connect 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aluvia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# Agent Connect
+
+[![npm version](https://badge.fury.io/js/agent-connect.svg)](https://www.npmjs.com/package/agent-connect)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)
+
+Retry failed [Playwright](https://playwright.dev) navigations automatically with proxy fallback.
+
+[Read the full documentation](https://docs.aluvia.io/docs/using-aluvia/agent-connect-sdk)
+
+## Installation
+
+```bash
+npm install @aluvia-connect/agent-connect
+```
+
+```bash
+yarn add @aluvia-connect/agent-connect
+```
+
+```bash
+pnpm add @aluvia-connect/agent-connect
+```
+
+## Quick Start
+
+```typescript
+import { chromium } from "playwright";
+import { retryWithProxy } from "@aluvia-connect/agent-connect";
+
+const browser = await chromium.launch();
+const context = await browser.newContext();
+const page = await context.newPage();
+
+const { response, page: retriedPage } = await retryWithProxy(page).goto(
+  "https://blocked-website.com"
+);
+
+console.log("Page title:", await retriedPage.title());
+await browser.close();
+```
+
+## API Key Setup
+
+This SDK uses an Aluvia API key to fetch proxies when retries occur.
+Get your key from your Aluvia account's [Dev Tools page](https://dashboard.aluvia.io/tools)
+and set it in .env:
+
+```bash
+ALUVIA_API_KEY=your_aluvia_api_key
+```
+
+## Configuration
+
+You can control how `retryWithProxy` behaves using environment variables or options passed in code.
+The environment variables set defaults globally, while the TypeScript options let you override them per call.
+
+### Environment Variables
+
+| Variable             | Description                                                                              | Default                                 |
+| -------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------- |
+| `ALUVIA_API_KEY`     | Required unless you provide a custom `proxyProvider`. Used to fetch proxies from Aluvia. | _none_                                  |
+| `ALUVIA_MAX_RETRIES` | Number of retry attempts after the first failed navigation.                              | `1`                                     |
+| `ALUVIA_BACKOFF_MS`  | Base delay (ms) between retries, grows exponentially with jitter.                        | `300`                                   |
+| `ALUVIA_RETRY_ON`    | Comma-separated list of retryable error substrings.                                      | `ECONNRESET,ETIMEDOUT,net::ERR,Timeout` |
+
+#### Example `.env`
+
+```env
+ALUVIA_API_KEY=your_aluvia_api_key
+ALUVIA_MAX_RETRIES=2
+ALUVIA_BACKOFF_MS=500
+ALUVIA_RETRY_ON=ECONNRESET,ETIMEDOUT,net::ERR,Timeout
+```
+
+### TypeScript Options
+
+You can also configure behavior programmatically by passing options to `retryWithProxy()`.
+
+```typescript
+import { retryWithProxy } from "@aluvia-connect/agent-connect";
+
+const { response, page } = await retryWithProxy(page, {
+  maxRetries: 3,
+  backoffMs: 500,
+  retryOn: ["ECONNRESET", /403/],
+  closeOldBrowser: false,
+  onRetry: (attempt, maxRetries, lastError) => {
+    console.log(
+      `Retry attempt ${attempt} of ${maxRetries} due to error:`,
+      lastError
+    );
+  },
+  onProxyLoaded: (proxy) => {
+    console.log(`Proxy loaded: ${proxy.server}`);
+  },
+});
+```
+
+#### Available Options
+
+| Option            | Type                                                                                 | Default                                  | Description                                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `maxRetries`      | `number`                                                                             | `process.env.ALUVIA_MAX_RETRIES` or `1`  | Number of retry attempts after the first failure.                                                             |
+| `backoffMs`       | `number`                                                                             | `process.env.ALUVIA_BACKOFF_MS` or `300` | Base delay (in ms) between retries, grows exponentially with jitter.                                          |
+| `retryOn`         | `(string \| RegExp)[]`                                                               | `process.env.ALUVIA_RETRY_ON`            | Error patterns considered retryable.                                                                          |
+| `closeOldBrowser` | `boolean`                                                                            | `true`                                   | Whether to close the old browser when relaunching.                                                            |
+| `proxyProvider`   | `ProxyProvider`                                                                      | Uses Aluvia SDK                          | Custom proxy provider that returns proxy credentials.                                                         |
+| `onRetry`         | `(attempt: number, maxRetries: number, lastError: unknown) => void \| Promise<void>` | `undefined`                              | Callback invoked before each retry attempt.                                                                   |
+| `onProxyLoaded`   | `(proxy: ProxySettings) => void \| Promise<void>`                                    | `undefined`                              | Callback fired after a proxy has been successfully fetched (either from the Aluvia API or a custom provider). |
+
+#### Custom Proxy Provider Example
+
+```typescript
+const myProxyProvider = {
+  async get() {
+    return {
+      server: "http://myproxy.example.com:8000",
+      username: "user123",
+      password: "secret",
+    };
+  },
+};
+
+const { response, page } = await retryWithProxy(page, {
+  proxyProvider: myProxyProvider,
+  maxRetries: 3,
+});
+```
+
+## Dynamic Proxy (No Browser Relaunch)
+
+To avoid relaunching the browser for each retry you can run a local proxy that dynamically swaps its upstream. This keeps all pages, contexts and session state intact.
+
+1. Start the dynamic proxy.
+2. Launch Playwright pointing at its local address.
+3. Pass the dynamic proxy into `retryWithProxy`.
+4. On a retryable failure the upstream proxy is fetched and swapped; navigation is re-attempted on the same page instance.
+
+```ts
+import { chromium } from "playwright";
+import { retryWithProxy, startDynamicProxy } from "@aluvia-connect/agent-connect";
+
+// Start local proxy-chain server (random free port)
+const dyn = await startDynamicProxy();
+
+// Launch browser using ONLY the local proxy initially (direct connection upstream)
+const browser = await chromium.launch({ proxy: { server: dyn.url } });
+const context = await browser.newContext();
+const page = await context.newPage();
+
+const { page: samePage } = await retryWithProxy(page, {
+  dynamicProxy: dyn,
+  maxRetries: 2,
+  retryOn: ["Timeout", /net::ERR/],
+  onProxyLoaded: (p) => console.log("Upstream proxy loaded", p.server),
+  onRetry: (a, m) => console.log(`Dynamic retry ${a}/${m}`),
+}).goto("https://blocked-website.example");
+
+console.log(await samePage.title());
+await dyn.close();
+await browser.close();
+```
+
+Notes:
+
+- The first attempt is direct (no upstream proxy). On failure we fetch a proxy and call `dynamicProxy.setUpstream()` internally.
+- Subsequent retries reuse the same browser & page; cookies and session data persist.
+- Provide your own `proxyProvider` if you do not want to use the Aluvia API.
+
+You can integrate this with any proxy API or local pool, as long as it returns a `server`, `username`, and `password`.
+
+## Requirements
+
+- Node.js >= 18
+- Playwright
+- Aluvia API key (_if not using a custom proxy provider_)
+
+## About Aluvia
+
+[Aluvia](https://www.aluvia.io/) provides real mobile proxy networks for developers and data teams, built for web automation, testing, and scraping with real device IPs.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.MD](CONTRIBUTING.MD) for guidelines.
+
+- Fork the repo and create your branch.
+- Write clear commit messages.
+- Add tests for new features.
+- Open a pull request.
+
+## Support
+
+For bugs, feature requests, or questions, please open an issue on [GitHub](https://github.com/aluvia-connect/agent-connect/issues).
+
+For commercial support or proxy questions, visit [Aluvia](https://www.aluvia.io/).
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Aluvia - [https://www.aluvia.io/](https://www.aluvia.io/)

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/src/index.js

@@ -0,0 +1,320 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AluviaError = void 0;
+exports.retryWithProxy = retryWithProxy;
+exports.startDynamicProxy = startDynamicProxy;
+const proxy_chain_1 = require("proxy-chain");
+const DEFAULT_GOTO_TIMEOUT_MS = 15000;
+const ENV_MAX_RETRIES = Math.max(0, parseInt(process.env.ALUVIA_MAX_RETRIES || "1", 10)); // prettier-ignore
+const ENV_BACKOFF_MS = Math.max(0, parseInt(process.env.ALUVIA_BACKOFF_MS || "300", 10)); // prettier-ignore
+const ENV_RETRY_ON = (process.env.ALUVIA_RETRY_ON ?? "ECONNRESET,ETIMEDOUT,net::ERR,Timeout")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+/* Pre-compile retry patterns for performance & correctness */
+const DEFAULT_RETRY_PATTERNS = ENV_RETRY_ON.map((value) => value.startsWith("/") && value.endsWith("/")
+    ? new RegExp(value.slice(1, -1))
+    : value);
+var AluviaErrorCode;
+(function (AluviaErrorCode) {
+    AluviaErrorCode["NoApiKey"] = "ALUVIA_NO_API_KEY";
+    AluviaErrorCode["NoProxy"] = "ALUVIA_NO_PROXIES";
+    AluviaErrorCode["ProxyFetchFailed"] = "ALUVIA_PROXY_FETCH_FAILED";
+    AluviaErrorCode["InsufficientBalance"] = "ALUVIA_INSUFFICIENT_BALANCE";
+    AluviaErrorCode["BalanceFetchFailed"] = "ALUVIA_BALANCE_FETCH_FAILED";
+})(AluviaErrorCode || (AluviaErrorCode = {}));
+class AluviaError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = "AluviaError";
+        this.code = code;
+    }
+}
+exports.AluviaError = AluviaError;
+let aluviaClient; // lazy-loaded Aluvia client instance
+async function getAluviaProxy() {
+    const apiKey = process.env.ALUVIA_API_KEY || "";
+    if (!apiKey) {
+        throw new AluviaError("Missing ALUVIA_API_KEY environment variable.", AluviaErrorCode.NoApiKey);
+    }
+    if (!aluviaClient) {
+        // Dynamic import to play nicely with test mocks (avoids top-level evaluation before vi.mock)
+        const mod = await Promise.resolve().then(() => __importStar(require("aluvia-ts-sdk")));
+        const AluviaCtor = mod?.default || mod;
+        aluviaClient = new AluviaCtor(apiKey);
+    }
+    const proxy = await aluviaClient.first();
+    if (!proxy) {
+        throw new AluviaError("Failed to obtain a proxy for retry attempts. Check your balance and proxy pool at https://dashboard.aluvia.io/.", AluviaErrorCode.NoProxy);
+    }
+    return {
+        server: `http://${proxy.host}:${proxy.httpPort}`,
+        username: proxy.username,
+        password: proxy.password,
+    };
+}
+async function getAluviaBalance() {
+    const apiKey = process.env.ALUVIA_API_KEY || "";
+    if (!apiKey) {
+        throw new AluviaError("Missing ALUVIA_API_KEY environment variable.", AluviaErrorCode.NoApiKey);
+    }
+    const response = await fetch("https://api.aluvia.io/account/status", {
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (!response.ok) {
+        throw new AluviaError(`Failed to fetch Aluvia account status: ${response.status} ${response.statusText}`, AluviaErrorCode.BalanceFetchFailed);
+    }
+    const data = await response.json();
+    return data.data.balance_gb;
+}
+function backoffDelay(base, attempt) {
+    // exponential + jitter
+    const jitter = Math.random() * 100;
+    return base * Math.pow(2, attempt) + jitter;
+}
+function compileRetryable(patterns = DEFAULT_RETRY_PATTERNS) {
+    return (err) => {
+        if (!err)
+            return false;
+        const msg = String(err?.message ?? err ?? "");
+        const code = String(err?.code ?? "");
+        const name = String(err?.name ?? "");
+        return patterns.some((p) => p instanceof RegExp
+            ? p.test(msg) || p.test(code) || p.test(name)
+            : msg.includes(p) || code.includes(p) || name.includes(p));
+    };
+}
+function inferBrowserTypeFromPage(page) {
+    const browser = page.context().browser();
+    const browserType = browser?.browserType?.();
+    if (!browserType) {
+        throw new Error("Cannot infer BrowserType from page");
+    }
+    return browserType;
+}
+async function inferContextDefaults(page) {
+    const context = page.context();
+    const options = context._options;
+    return options ?? {};
+}
+function inferLaunchDefaults(page) {
+    const browser = page.context().browser();
+    const options = browser._options;
+    return options ?? {};
+}
+async function relaunchWithProxy(proxy, oldPage, closeOldBrowser = true) {
+    const browserType = inferBrowserTypeFromPage(oldPage);
+    const launchDefaults = inferLaunchDefaults(oldPage);
+    const contextDefaults = await inferContextDefaults(oldPage);
+    if (closeOldBrowser) {
+        const oldBrowser = oldPage.context().browser();
+        try {
+            await oldBrowser?.close();
+        }
+        catch { }
+    }
+    const retryLaunch = {
+        ...launchDefaults,
+        proxy,
+    };
+    const browser = await browserType.launch(retryLaunch);
+    const context = await browser.newContext(contextDefaults);
+    const page = await context.newPage();
+    return { page };
+}
+const GOTO_ORIGINAL = Symbol.for("aluvia.gotoOriginal");
+function retryWithProxy(page, options) {
+    const { maxRetries = ENV_MAX_RETRIES, backoffMs = ENV_BACKOFF_MS, retryOn = DEFAULT_RETRY_PATTERNS, closeOldBrowser = true, proxyProvider, onRetry, onProxyLoaded, dynamicProxy, } = options ?? {};
+    const isRetryable = compileRetryable(retryOn);
+    /** Prefer unpatched goto to avoid recursion */
+    const getRawGoto = (p) => (p[GOTO_ORIGINAL]?.bind(p) ?? p.goto.bind(p));
+    return {
+        async goto(url, gotoOptions) {
+            const run = async () => {
+                let basePage = page;
+                let lastErr;
+                // First attempt without proxy
+                try {
+                    const response = await getRawGoto(basePage)(url, {
+                        ...(gotoOptions ?? {}),
+                        timeout: gotoOptions?.timeout ?? DEFAULT_GOTO_TIMEOUT_MS,
+                        waitUntil: gotoOptions?.waitUntil ?? "domcontentloaded",
+                    });
+                    return { response: response ?? null, page: basePage };
+                }
+                catch (err) {
+                    lastErr = err;
+                    if (!isRetryable(err)) {
+                        throw err;
+                    }
+                }
+                if (!proxyProvider) {
+                    const balance = await getAluviaBalance().catch(() => null);
+                    if (balance !== null && balance <= 0) {
+                        throw new AluviaError("Your Aluvia account has no remaining balance. Please top up at https://dashboard.aluvia.io/ to continue using proxies.", AluviaErrorCode.InsufficientBalance);
+                    }
+                }
+                const proxy = await (proxyProvider?.get() ?? getAluviaProxy()).catch((err) => {
+                    lastErr = err;
+                    return undefined;
+                });
+                if (!proxy) {
+                    throw new AluviaError("Failed to obtain a proxy for retry attempts. Check your balance and proxy pool at https://dashboard.aluvia.io/.", AluviaErrorCode.ProxyFetchFailed);
+                }
+                else {
+                    await onProxyLoaded?.(proxy);
+                }
+                // If dynamic proxy supplied, switch upstream & retry on same page without relaunch.
+                if (dynamicProxy) {
+                    await dynamicProxy.setUpstream(proxy);
+                    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+                        if (backoffMs > 0) {
+                            const delay = backoffDelay(backoffMs, attempt - 1);
+                            await new Promise((r) => setTimeout(r, delay));
+                        }
+                        await onRetry?.(attempt, maxRetries, lastErr);
+                        try {
+                            const response = await getRawGoto(basePage)(url, {
+                                ...(gotoOptions ?? {}),
+                                timeout: gotoOptions?.timeout ?? DEFAULT_GOTO_TIMEOUT_MS,
+                                waitUntil: gotoOptions?.waitUntil ?? "domcontentloaded",
+                            });
+                            return { response: response ?? null, page: basePage };
+                        }
+                        catch (err) {
+                            lastErr = err;
+                            if (!isRetryable(err))
+                                break; // stop early on non-retryable error
+                            continue; // next attempt
+                        }
+                    }
+                    if (lastErr instanceof Error)
+                        throw lastErr;
+                    throw new Error(lastErr ? String(lastErr) : "Navigation failed");
+                }
+                // Original relaunch path if no dynamic proxy provided
+                // Retries with proxy
+                for (let attempt = 1; attempt <= maxRetries; attempt++) {
+                    if (backoffMs > 0) {
+                        const delay = backoffDelay(backoffMs, attempt - 1);
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                    }
+                    await onRetry?.(attempt, maxRetries, lastErr);
+                    try {
+                        const { page: newPage } = await relaunchWithProxy(proxy, basePage, closeOldBrowser);
+                        try {
+                            const response = await getRawGoto(newPage)(url, {
+                                ...(gotoOptions ?? {}),
+                                timeout: gotoOptions?.timeout ?? DEFAULT_GOTO_TIMEOUT_MS,
+                                waitUntil: gotoOptions?.waitUntil ?? "domcontentloaded",
+                            });
+                            // non-fatal readiness gate
+                            try {
+                                await newPage.waitForFunction(() => typeof document !== "undefined" && !!document.title?.trim(), { timeout: DEFAULT_GOTO_TIMEOUT_MS });
+                            }
+                            catch { }
+                            return {
+                                response: response ?? null,
+                                page: newPage,
+                            };
+                        }
+                        catch (err) {
+                            // navigation on the new page failed — carry this page forward
+                            basePage = newPage;
+                            lastErr = err;
+                            // next loop iteration will close this browser (since we pass basePage)
+                            continue;
+                        }
+                    }
+                    catch (err) {
+                        // relaunch itself failed (no new page created)
+                        lastErr = err;
+                        continue;
+                    }
+                }
+                if (lastErr instanceof Error) {
+                    throw lastErr;
+                }
+                throw new Error(lastErr ? String(lastErr) : "Navigation failed");
+            };
+            return run();
+        },
+    };
+}
+/**
+ * Starts a local proxy-chain server which can have its upstream changed at runtime
+ * without relaunching the browser. Launch Playwright with { proxy: { server: dynamic.url } }.
+ */
+async function startDynamicProxy(port) {
+    let upstream = null;
+    const server = new proxy_chain_1.Server({
+        port: port || 0,
+        prepareRequestFunction: async () => {
+            if (!upstream)
+                return {};
+            let url = upstream.server.startsWith("http") ? upstream.server : `http://${upstream.server}`;
+            if (upstream.username && upstream.password) {
+                try {
+                    const u = new URL(url);
+                    u.username = upstream.username;
+                    u.password = upstream.password;
+                    url = u.toString();
+                }
+                catch { }
+            }
+            return { upstreamProxyUrl: url };
+        },
+    });
+    await server.listen();
+    const address = server.server.address();
+    const resolvedPort = typeof address === "object" && address ? address.port : port || 8000;
+    const url = `http://127.0.0.1:${resolvedPort}`;
+    return {
+        url,
+        async setUpstream(p) {
+            upstream = p;
+        },
+        async close() {
+            try {
+                await server.close(false);
+            }
+            catch { }
+        },
+        currentUpstream() { return upstream; },
+    };
+}

package/dist/esm/src/index.js

@@ -0,0 +1,281 @@
+import { Server as ProxyChainServer } from "proxy-chain";
+const DEFAULT_GOTO_TIMEOUT_MS = 15000;
+const ENV_MAX_RETRIES = Math.max(0, parseInt(process.env.ALUVIA_MAX_RETRIES || "1", 10)); // prettier-ignore
+const ENV_BACKOFF_MS = Math.max(0, parseInt(process.env.ALUVIA_BACKOFF_MS || "300", 10)); // prettier-ignore
+const ENV_RETRY_ON = (process.env.ALUVIA_RETRY_ON ?? "ECONNRESET,ETIMEDOUT,net::ERR,Timeout")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+/* Pre-compile retry patterns for performance & correctness */
+const DEFAULT_RETRY_PATTERNS = ENV_RETRY_ON.map((value) => value.startsWith("/") && value.endsWith("/")
+    ? new RegExp(value.slice(1, -1))
+    : value);
+var AluviaErrorCode;
+(function (AluviaErrorCode) {
+    AluviaErrorCode["NoApiKey"] = "ALUVIA_NO_API_KEY";
+    AluviaErrorCode["NoProxy"] = "ALUVIA_NO_PROXIES";
+    AluviaErrorCode["ProxyFetchFailed"] = "ALUVIA_PROXY_FETCH_FAILED";
+    AluviaErrorCode["InsufficientBalance"] = "ALUVIA_INSUFFICIENT_BALANCE";
+    AluviaErrorCode["BalanceFetchFailed"] = "ALUVIA_BALANCE_FETCH_FAILED";
+})(AluviaErrorCode || (AluviaErrorCode = {}));
+export class AluviaError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = "AluviaError";
+        this.code = code;
+    }
+}
+let aluviaClient; // lazy-loaded Aluvia client instance
+async function getAluviaProxy() {
+    const apiKey = process.env.ALUVIA_API_KEY || "";
+    if (!apiKey) {
+        throw new AluviaError("Missing ALUVIA_API_KEY environment variable.", AluviaErrorCode.NoApiKey);
+    }
+    if (!aluviaClient) {
+        // Dynamic import to play nicely with test mocks (avoids top-level evaluation before vi.mock)
+        const mod = await import("aluvia-ts-sdk");
+        const AluviaCtor = mod?.default || mod;
+        aluviaClient = new AluviaCtor(apiKey);
+    }
+    const proxy = await aluviaClient.first();
+    if (!proxy) {
+        throw new AluviaError("Failed to obtain a proxy for retry attempts. Check your balance and proxy pool at https://dashboard.aluvia.io/.", AluviaErrorCode.NoProxy);
+    }
+    return {
+        server: `http://${proxy.host}:${proxy.httpPort}`,
+        username: proxy.username,
+        password: proxy.password,
+    };
+}
+async function getAluviaBalance() {
+    const apiKey = process.env.ALUVIA_API_KEY || "";
+    if (!apiKey) {
+        throw new AluviaError("Missing ALUVIA_API_KEY environment variable.", AluviaErrorCode.NoApiKey);
+    }
+    const response = await fetch("https://api.aluvia.io/account/status", {
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (!response.ok) {
+        throw new AluviaError(`Failed to fetch Aluvia account status: ${response.status} ${response.statusText}`, AluviaErrorCode.BalanceFetchFailed);
+    }
+    const data = await response.json();
+    return data.data.balance_gb;
+}
+function backoffDelay(base, attempt) {
+    // exponential + jitter
+    const jitter = Math.random() * 100;
+    return base * Math.pow(2, attempt) + jitter;
+}
+function compileRetryable(patterns = DEFAULT_RETRY_PATTERNS) {
+    return (err) => {
+        if (!err)
+            return false;
+        const msg = String(err?.message ?? err ?? "");
+        const code = String(err?.code ?? "");
+        const name = String(err?.name ?? "");
+        return patterns.some((p) => p instanceof RegExp
+            ? p.test(msg) || p.test(code) || p.test(name)
+            : msg.includes(p) || code.includes(p) || name.includes(p));
+    };
+}
+function inferBrowserTypeFromPage(page) {
+    const browser = page.context().browser();
+    const browserType = browser?.browserType?.();
+    if (!browserType) {
+        throw new Error("Cannot infer BrowserType from page");
+    }
+    return browserType;
+}
+async function inferContextDefaults(page) {
+    const context = page.context();
+    const options = context._options;
+    return options ?? {};
+}
+function inferLaunchDefaults(page) {
+    const browser = page.context().browser();
+    const options = browser._options;
+    return options ?? {};
+}
+async function relaunchWithProxy(proxy, oldPage, closeOldBrowser = true) {
+    const browserType = inferBrowserTypeFromPage(oldPage);
+    const launchDefaults = inferLaunchDefaults(oldPage);
+    const contextDefaults = await inferContextDefaults(oldPage);
+    if (closeOldBrowser) {
+        const oldBrowser = oldPage.context().browser();
+        try {
+            await oldBrowser?.close();
+        }
+        catch { }
+    }
+    const retryLaunch = {
+        ...launchDefaults,
+        proxy,
+    };
+    const browser = await browserType.launch(retryLaunch);
+    const context = await browser.newContext(contextDefaults);
+    const page = await context.newPage();
+    return { page };
+}
+const GOTO_ORIGINAL = Symbol.for("aluvia.gotoOriginal");
+export function retryWithProxy(page, options) {
+    const { maxRetries = ENV_MAX_RETRIES, backoffMs = ENV_BACKOFF_MS, retryOn = DEFAULT_RETRY_PATTERNS, closeOldBrowser = true, proxyProvider, onRetry, onProxyLoaded, dynamicProxy, } = options ?? {};
+    const isRetryable = compileRetryable(retryOn);
+    /** Prefer unpatched goto to avoid recursion */
+    const getRawGoto = (p) => (p[GOTO_ORIGINAL]?.bind(p) ?? p.goto.bind(p));
+    return {
+        async goto(url, gotoOptions) {
+            const run = async () => {
+                let basePage = page;
+                let lastErr;
+                // First attempt without proxy
+                try {
+                    const response = await getRawGoto(basePage)(url, {
+                        ...(gotoOptions ?? {}),
+                        timeout: gotoOptions?.timeout ?? DEFAULT_GOTO_TIMEOUT_MS,
+                        waitUntil: gotoOptions?.waitUntil ?? "domcontentloaded",
+                    });
+                    return { response: response ?? null, page: basePage };
+                }
+                catch (err) {
+                    lastErr = err;
+                    if (!isRetryable(err)) {
+                        throw err;
+                    }
+                }
+                if (!proxyProvider) {
+                    const balance = await getAluviaBalance().catch(() => null);
+                    if (balance !== null && balance <= 0) {
+                        throw new AluviaError("Your Aluvia account has no remaining balance. Please top up at https://dashboard.aluvia.io/ to continue using proxies.", AluviaErrorCode.InsufficientBalance);
+                    }
+                }
+                const proxy = await (proxyProvider?.get() ?? getAluviaProxy()).catch((err) => {
+                    lastErr = err;
+                    return undefined;
+                });
+                if (!proxy) {
+                    throw new AluviaError("Failed to obtain a proxy for retry attempts. Check your balance and proxy pool at https://dashboard.aluvia.io/.", AluviaErrorCode.ProxyFetchFailed);
+                }
+                else {
+                    await onProxyLoaded?.(proxy);
+                }
+                // If dynamic proxy supplied, switch upstream & retry on same page without relaunch.
+                if (dynamicProxy) {
+                    await dynamicProxy.setUpstream(proxy);
+                    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+                        if (backoffMs > 0) {
+                            const delay = backoffDelay(backoffMs, attempt - 1);
+                            await new Promise((r) => setTimeout(r, delay));
+                        }
+                        await onRetry?.(attempt, maxRetries, lastErr);
+                        try {
+                            const response = await getRawGoto(basePage)(url, {
+                                ...(gotoOptions ?? {}),
+                                timeout: gotoOptions?.timeout ?? DEFAULT_GOTO_TIMEOUT_MS,
+                                waitUntil: gotoOptions?.waitUntil ?? "domcontentloaded",
+                            });
+                            return { response: response ?? null, page: basePage };
+                        }
+                        catch (err) {
+                            lastErr = err;
+                            if (!isRetryable(err))
+                                break; // stop early on non-retryable error
+                            continue; // next attempt
+                        }
+                    }
+                    if (lastErr instanceof Error)
+                        throw lastErr;
+                    throw new Error(lastErr ? String(lastErr) : "Navigation failed");
+                }
+                // Original relaunch path if no dynamic proxy provided
+                // Retries with proxy
+                for (let attempt = 1; attempt <= maxRetries; attempt++) {
+                    if (backoffMs > 0) {
+                        const delay = backoffDelay(backoffMs, attempt - 1);
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                    }
+                    await onRetry?.(attempt, maxRetries, lastErr);
+                    try {
+                        const { page: newPage } = await relaunchWithProxy(proxy, basePage, closeOldBrowser);
+                        try {
+                            const response = await getRawGoto(newPage)(url, {
+                                ...(gotoOptions ?? {}),
+                                timeout: gotoOptions?.timeout ?? DEFAULT_GOTO_TIMEOUT_MS,
+                                waitUntil: gotoOptions?.waitUntil ?? "domcontentloaded",
+                            });
+                            // non-fatal readiness gate
+                            try {
+                                await newPage.waitForFunction(() => typeof document !== "undefined" && !!document.title?.trim(), { timeout: DEFAULT_GOTO_TIMEOUT_MS });
+                            }
+                            catch { }
+                            return {
+                                response: response ?? null,
+                                page: newPage,
+                            };
+                        }
+                        catch (err) {
+                            // navigation on the new page failed — carry this page forward
+                            basePage = newPage;
+                            lastErr = err;
+                            // next loop iteration will close this browser (since we pass basePage)
+                            continue;
+                        }
+                    }
+                    catch (err) {
+                        // relaunch itself failed (no new page created)
+                        lastErr = err;
+                        continue;
+                    }
+                }
+                if (lastErr instanceof Error) {
+                    throw lastErr;
+                }
+                throw new Error(lastErr ? String(lastErr) : "Navigation failed");
+            };
+            return run();
+        },
+    };
+}
+/**
+ * Starts a local proxy-chain server which can have its upstream changed at runtime
+ * without relaunching the browser. Launch Playwright with { proxy: { server: dynamic.url } }.
+ */
+export async function startDynamicProxy(port) {
+    let upstream = null;
+    const server = new ProxyChainServer({
+        port: port || 0,
+        prepareRequestFunction: async () => {
+            if (!upstream)
+                return {};
+            let url = upstream.server.startsWith("http") ? upstream.server : `http://${upstream.server}`;
+            if (upstream.username && upstream.password) {
+                try {
+                    const u = new URL(url);
+                    u.username = upstream.username;
+                    u.password = upstream.password;
+                    url = u.toString();
+                }
+                catch { }
+            }
+            return { upstreamProxyUrl: url };
+        },
+    });
+    await server.listen();
+    const address = server.server.address();
+    const resolvedPort = typeof address === "object" && address ? address.port : port || 8000;
+    const url = `http://127.0.0.1:${resolvedPort}`;
+    return {
+        url,
+        async setUpstream(p) {
+            upstream = p;
+        },
+        async close() {
+            try {
+                await server.close(false);
+            }
+            catch { }
+        },
+        currentUpstream() { return upstream; },
+    };
+}

package/dist/types/src/index.d.ts

@@ -0,0 +1,159 @@
+import type { Page, Response } from "playwright";
+export type RetryPattern = string | RegExp;
+type GoToOptions = NonNullable<Parameters<Page["goto"]>[1]>;
+export interface RetryWithProxyRunner {
+    goto(url: string, options?: GoToOptions): Promise<{
+        response: Response | null;
+        page: Page;
+    }>;
+}
+export type ProxySettings = {
+    server: string;
+    username?: string;
+    password?: string;
+};
+export interface ProxyProvider {
+    get(): Promise<ProxySettings>;
+}
+declare enum AluviaErrorCode {
+    NoApiKey = "ALUVIA_NO_API_KEY",
+    NoProxy = "ALUVIA_NO_PROXIES",
+    ProxyFetchFailed = "ALUVIA_PROXY_FETCH_FAILED",
+    InsufficientBalance = "ALUVIA_INSUFFICIENT_BALANCE",
+    BalanceFetchFailed = "ALUVIA_BALANCE_FETCH_FAILED"
+}
+export declare class AluviaError extends Error {
+    code?: AluviaErrorCode;
+    constructor(message: string, code?: AluviaErrorCode);
+}
+export interface RetryWithProxyOptions {
+    /**
+     * Number of retry attempts after the first failed navigation.
+     *
+     * The first `page.goto()` is always attempted without a proxy.
+     * If it fails with a retryable error (as defined by `retryOn`),
+     * the helper will fetch a new proxy and relaunch the browser.
+     *
+     * @default process.env.ALUVIA_MAX_RETRIES || 1
+     * @example
+     * // Try up to 3 proxy relaunches after the first failure
+     * { maxRetries: 3 }
+     */
+    maxRetries?: number;
+    /**
+     * Base delay (in milliseconds) for exponential backoff between retries.
+     *
+     * Each retry waits `backoffMs * 2^attempt + random(0–100)` before continuing.
+     * Useful to avoid hammering proxy endpoints or triggering rate limits.
+     *
+     * @default process.env.ALUVIA_BACKOFF_MS || 300
+     * @example
+     * // Start with 500ms and double each time (with jitter)
+     * { backoffMs: 500 }
+     */
+    backoffMs?: number;
+    /**
+     * List of error patterns that are considered retryable.
+     *
+     * A pattern can be a string or a regular expression. When a navigation error’s
+     * message, name, or code matches any of these, the helper will trigger a retry.
+     *
+     * @default process.env.ALUVIA_RETRY_ON
+     *          or ["ECONNRESET", "ETIMEDOUT", "net::ERR", "Timeout"]
+     * @example
+     * // Retry on connection resets and 403 responses
+     * { retryOn: ["ECONNRESET", /403/] }
+     */
+    retryOn?: RetryPattern[];
+    /**
+     * Whether to close the old browser instance when relaunching with a new proxy.
+     *
+     * Set to `true` (default) to prevent multiple browsers from staying open,
+     * which is safer for most workflows. Set to `false` if you manage browser
+     * lifecycles manually or reuse a shared browser across tasks.
+     *
+     * @default true
+     * @example
+     * // Keep old browser open (you must close it yourself)
+     * { closeOldBrowser: false }
+     */
+    closeOldBrowser?: boolean;
+    /**
+     * Optional custom proxy provider used to fetch proxy credentials.
+     *
+     * By default, `retryWithProxy` automatically uses the Aluvia API
+     * via the `aluvia-ts-sdk` and reads the API key from
+     * `process.env.ALUVIA_API_KEY`.
+     *
+     * Supplying your own `proxyProvider` allows you to integrate with
+     * any proxy rotation service, database, or in-house pool instead.
+     *
+     * A proxy provider must expose a `get()` method that returns a
+     * `Promise<ProxySettings>` object with `server`, and optionally
+     * `username` and `password` fields.
+     *
+     * @default Uses the built-in Aluvia client with `process.env.ALUVIA_API_KEY`
+     * @example
+     * ```ts
+     * import { retryWithProxy } from "page-retry";
+     *
+     * // Custom proxy provider example
+     * const myProxyProvider = {
+     *   async get() {
+     *     // Pull from your own proxy pool or API
+     *     return {
+     *       server: "http://myproxy.example.com:8000",
+     *       username: "user123",
+     *       password: "secret",
+     *     };
+     *   },
+     * };
+     *
+     * const { response, page } = await retryWithProxy(page, {
+     *   proxyProvider: myProxyProvider,
+     *   maxRetries: 3,
+     * });
+     * ```
+     */
+    proxyProvider?: ProxyProvider;
+    /**
+     * Optional callback fired before each retry attempt (after backoff).
+     *
+     * @param attempt Current retry attempt number (1-based)
+     * @param maxRetries Maximum number of retries
+     * @param lastError The error that triggered the retry
+     */
+    onRetry?: (attempt: number, maxRetries: number, lastError: unknown) => void | Promise<void>;
+    /**
+     * Optional callback fired when a proxy has been successfully fetched.
+     *
+     * @param proxy The proxy settings that were fetched or provided
+     */
+    onProxyLoaded?: (proxy: ProxySettings) => void | Promise<void>;
+    /**
+     * Optional dynamic proxy. If provided, retries will switch upstream proxy
+     * via this local proxy instead of relaunching the browser.
+     *
+     * To use: const dyn = await startDynamicProxy();
+     * chromium.launch({ proxy: { server: dyn.url } })
+     * Then pass { dynamicProxy: dyn } to retryWithProxy().
+     */
+    dynamicProxy?: DynamicProxy;
+}
+export declare function retryWithProxy(page: Page, options?: RetryWithProxyOptions): RetryWithProxyRunner;
+/**
+ * Starts a local proxy-chain server which can have its upstream changed at runtime
+ * without relaunching the browser. Launch Playwright with { proxy: { server: dynamic.url } }.
+ */
+export declare function startDynamicProxy(port?: number): Promise<DynamicProxy>;
+export interface DynamicProxy {
+    /** Local proxy URL (host:port) to be used in Playwright launch options */
+    url: string;
+    /** Update upstream proxy; null disables upstream (direct connection) */
+    setUpstream(proxy: ProxySettings | null): Promise<void>;
+    /** Dispose the local proxy server */
+    close(): Promise<void>;
+    /** Returns the currently configured upstream settings (if any) */
+    currentUpstream(): ProxySettings | null;
+}
+export {};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@aluvia-connect/agent-connect",
+  "version": "1.0.0",
+  "description": "Automatic retry and proxy fallback for Playwright powered by Aluvia",
+  "homepage": "https://github.com/aluvia-connect/agent-connect#readme",
+  "bugs": {
+    "url": "https://github.com/aluvia-connect/agent-connect/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aluvia-connect/agent-connect.git"
+  },
+  "license": "MIT",
+  "author": "Aluvia",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true});require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}')\"",
+    "release:check": "npm run build && npm pack --dry-run",
+    "release:tag": "git tag v$(node -p \"require('./package.json').version\")",
+    "release:push": "git push origin main && git push origin --tags",
+    "release:version": "node -p \"require('./package.json').version\"",
+    "audit:check": "npm audit --audit-level moderate",
+    "test": "vitest run --reporter=dot",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "playwright",
+    "proxy",
+    "aluvia",
+    "retry",
+    "automation",
+    "typescript"
+  ],
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "aluvia-ts-sdk": "^2.1.2",
+    "proxy-chain": "^2.3.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "@vitest/coverage-v8": "^4.0.3",
+    "playwright": "^1.56.1",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}