@aluvia-connect/agent-connect/README.md

Automatic retry and proxy fallback for Playwright powered by Aluvia

# Agent Connect

[![npm version](https://badge.fury.io/js/@aluvia-connect%2Fagent-connect.svg)](https://badge.fury.io/js/@aluvia-connect%2Fagent-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

```ts
import { chromium } from "playwright";
import { agentConnect, 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 agentConnect(page, {
  dynamicProxy: dyn,
  maxRetries: 2,
  retryOn: ["Timeout", /net::ERR/],
  onProxyLoaded: (p) => console.log("Upstream proxy loaded", p.server),
  onRetry: (a, m) => console.log(`Retry ${a}/${m}`),
}).goto("https://blocked-website.example");

console.log(await samePage.title());
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.
- The dynamic proxy closes automatically when `browser.close()` is called. You can also call `dyn.close()` manually.

You can integrate this with any proxy API or local pool, as long as it returns a `server`, `username`, and `password`.

## Aluvia Token Setup

This SDK uses an Aluvia token to fetch proxies when retries occur. You can find your token on your Aluvia account's [credentials](https://dashboard.aluvia.io/credentials) page.

Set your token key in a `.env` file:

```env
ALUVIA_TOKEN=your_aluvia_token
```

## Configuration

You can control how `agentConnect` 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_TOKEN`       | 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.                              | `2`                                     |
| `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_TOKEN=your_aluvia_token
ALUVIA_MAX_RETRIES=1
ALUVIA_BACKOFF_MS=500
ALUVIA_RETRY_ON=ECONNRESET,ETIMEDOUT,net::ERR,Timeout
```

### Options

You can also configure behavior programmatically by passing options to `agentConnect()`.

```typescript
import { agentConnect } from "@aluvia-connect/agent-connect";

const { response, page } = await agentConnect(page, {
  maxRetries: 3,
  backoffMs: 500,
  retryOn: ["ECONNRESET", /403/],
  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 `2`  | 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.                                                                          |
| `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 agentConnect(page, {
  proxyProvider: myProxyProvider,
  maxRetries: 3,
});
```

## Requirements

- Node.js >= 18
- Playwright
- Aluvia token (_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/)