{"_id":"@aluvia-connect/agent-connect","_rev":"7-391ad50756a3a909f7e8f71a3364ff1b","name":"@aluvia-connect/agent-connect","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@aluvia-connect/agent-connect","version":"1.0.0","keywords":["playwright","proxy","aluvia","retry","automation","typescript"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia-connect/agent-connect@1.0.0","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://github.com/aluvia-connect/agent-connect#readme","bugs":{"url":"https://github.com/aluvia-connect/agent-connect/issues"},"dist":{"shasum":"5703bf887f3ae305adaa239a7a4f59bf458c9363","tarball":"https://registry.npmjs.org/@aluvia-connect/agent-connect/-/agent-connect-1.0.0.tgz","fileCount":7,"integrity":"sha512-kO6O8a2iYXOOh39s0RO+o5S/53jABFv7ev+9zxtIGKfgfpCNJ7ITZUbiTB0IYUV1KhTE4uZ62JjoxaSS6LYg2w==","signatures":[{"sig":"MEQCICdgMwq+RPQSxhbNwWCoivGswLqb6s6KzQnmQuC/2MZ7AiAy2c/UO+r7187a+9beDt9R4PSKX+ETRbNdGE6r78hVjg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44162},"main":"./dist/cjs/index.js","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"gitHead":"cfa0a2d7d95dd1921b4b27e6083c8c2f9cb02952","scripts":{"test":"vitest run --reporter=dot","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\\\"}')\"","clean":"rimraf dist","test:watch":"vitest","audit:check":"npm audit --audit-level moderate","release:tag":"git tag v$(node -p \"require('./package.json').version\")","release:push":"git push origin main && git push origin --tags","release:check":"npm run build && npm pack --dry-run","release:version":"node -p \"require('./package.json').version\""},"_npmUser":{"name":"denniskrol","email":"dennis@xtrella.com"},"repository":{"url":"git+https://github.com/aluvia-connect/agent-connect.git","type":"git"},"_npmVersion":"11.6.2","description":"Automatic retry and proxy fallback for Playwright powered by Aluvia","directories":{},"sideEffects":false,"_nodeVersion":"22.19.0","dependencies":{"proxy-chain":"^2.3.0","aluvia-ts-sdk":"^2.1.2"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"^4.0.3","playwright":"^1.56.1","typescript":"^5.9.3","@types/node":"^24.9.1","@vitest/coverage-v8":"^4.0.3"},"peerDependencies":{"playwright":">=1.40.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-connect_1.0.0_1762497437460_0.2139027294747089","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"1.0.2":{"name":"@aluvia-connect/agent-connect","version":"1.0.2","keywords":["playwright","proxy","aluvia","retry","automation","typescript"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia-connect/agent-connect@1.0.2","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://github.com/aluvia-connect/agent-connect#readme","bugs":{"url":"https://github.com/aluvia-connect/agent-connect/issues"},"dist":{"shasum":"a7fbfe31fb30f33efec4699d640cdf7f1330d964","tarball":"https://registry.npmjs.org/@aluvia-connect/agent-connect/-/agent-connect-1.0.2.tgz","fileCount":7,"integrity":"sha512-8TB2sEfVq/UXePVRT7BltQt/PxK6hV2y+gJMXVzIJ2euLDdAERGyctP4tE+2Fz6hSVO5xjxiR+cXVqR2SycWRQ==","signatures":[{"sig":"MEUCIQCufYeco0X9bCnJyaPniC/PBvk0L4GswDKNDSMyYYGHOwIgcyNSCbLz+57AVg022t/dqf+D66j8+MKDtwchwv5VlOI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44195},"main":"./dist/cjs/index.js","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"gitHead":"2ea63a8a79db2ecad3a15c0679e19d0d790ba5c6","scripts":{"test":"vitest run --reporter=dot","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\\\"}')\"","clean":"rimraf dist","test:watch":"vitest","audit:check":"npm audit --audit-level moderate","release:tag":"git tag v$(node -p \"require('./package.json').version\")","release:push":"git push origin main && git push origin --tags","release:check":"npm run build && npm pack --dry-run","release:version":"node -p \"require('./package.json').version\""},"_npmUser":{"name":"denniskrol","email":"dennis@xtrella.com"},"repository":{"url":"git+https://github.com/aluvia-connect/agent-connect.git","type":"git"},"_npmVersion":"11.6.2","description":"Automatic retry and proxy fallback for Playwright powered by Aluvia","directories":{},"sideEffects":false,"_nodeVersion":"22.19.0","dependencies":{"proxy-chain":"^2.3.0","aluvia-ts-sdk":"^2.1.2"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"^4.0.3","playwright":"^1.56.1","typescript":"^5.9.3","@types/node":"^24.9.1","@vitest/coverage-v8":"^4.0.3"},"peerDependencies":{"playwright":">=1.40.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-connect_1.0.2_1762752904869_0.1762832947725299","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"1.0.3":{"name":"@aluvia-connect/agent-connect","version":"1.0.3","keywords":["playwright","proxy","aluvia","retry","automation","typescript"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia-connect/agent-connect@1.0.3","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://github.com/aluvia-connect/agent-connect#readme","bugs":{"url":"https://github.com/aluvia-connect/agent-connect/issues"},"dist":{"shasum":"490effe6bebced70680a629f2af4cef869b69ce2","tarball":"https://registry.npmjs.org/@aluvia-connect/agent-connect/-/agent-connect-1.0.3.tgz","fileCount":7,"integrity":"sha512-5xxZLzBRaI5DvCTTM5L8Ma1jau2rhDA++CXw0pV/JCxL4jPuB5GoUbgQyx/ATWzKYpzQfqGfRowtF11zPJLIIA==","signatures":[{"sig":"MEQCIEJYQ6mcPl8CaH4uonVepOYK9BviFQIZwSUB0njwLxA8AiA+roW9ASJLCInQDipuNGXrvbFEztyUq3240ugg9FavXg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aluvia-connect%2fagent-connect@1.0.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":44195},"main":"./dist/cjs/index.js","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"gitHead":"c921530ea6fc1d7e397b60a1de031485142bb2ee","scripts":{"test":"vitest run --reporter=dot","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\\\"}')\"","clean":"rimraf dist","test:watch":"vitest","audit:check":"npm audit --audit-level moderate","release:tag":"git tag v$(node -p \"require('./package.json').version\")","release:push":"git push origin main && git push origin --tags","release:check":"npm run build && npm pack --dry-run","release:version":"node -p \"require('./package.json').version\""},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c69135dc-beea-4eac-be0c-60f1f61e7a56"}},"repository":{"url":"git+https://github.com/aluvia-connect/agent-connect.git","type":"git"},"_npmVersion":"11.6.2","description":"Automatic retry and proxy fallback for Playwright powered by Aluvia","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","dependencies":{"proxy-chain":"^2.3.0","aluvia-ts-sdk":"^2.1.2"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"^4.0.3","playwright":"^1.56.1","typescript":"^5.9.3","@types/node":"^24.9.1","@vitest/coverage-v8":"^4.0.3"},"peerDependencies":{"playwright":">=1.40.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-connect_1.0.3_1762753425713_0.5663000776524032","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"1.0.4":{"name":"@aluvia-connect/agent-connect","version":"1.0.4","keywords":["playwright","proxy","aluvia","retry","automation","typescript"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia-connect/agent-connect@1.0.4","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://github.com/aluvia-connect/agent-connect#readme","bugs":{"url":"https://github.com/aluvia-connect/agent-connect/issues"},"dist":{"shasum":"e65c9b9b4fab3f6aa393a4834397cb0371b76252","tarball":"https://registry.npmjs.org/@aluvia-connect/agent-connect/-/agent-connect-1.0.4.tgz","fileCount":7,"integrity":"sha512-fBTIjIKBo5T/nG/JpuLorS3X+XcqeIDkZM9+V/kcMUxYLnZlHinRxeaEACOkkOaDk2vchiqzVO1e1UzzAhzngw==","signatures":[{"sig":"MEUCIA+84f5AQEVKPn6c/EZ7YQC/YkGMLs6Nj4I7VE59c2D7AiEAtm8NxqNg/Yxr8lcPpu1iCdDmh2Sh7k969wdQBnaN1xo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aluvia-connect%2fagent-connect@1.0.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":44219},"main":"./dist/cjs/src/index.js","type":"module","types":"./dist/types/src/index.d.ts","module":"./dist/esm/src/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/src/index.d.ts","import":"./dist/esm/src/index.js","require":"./dist/cjs/src/index.js"},"./package.json":"./package.json"},"gitHead":"5623479d7900477cb76702e696b57c853dd27f84","scripts":{"test":"vitest run --reporter=dot","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\\\"}')\"","clean":"rimraf dist","test:watch":"vitest","audit:check":"npm audit --audit-level moderate","release:tag":"git tag v$(node -p \"require('./package.json').version\")","release:push":"git push origin main && git push origin --tags","release:check":"npm run build && npm pack --dry-run","release:version":"node -p \"require('./package.json').version\""},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c69135dc-beea-4eac-be0c-60f1f61e7a56"}},"repository":{"url":"git+https://github.com/aluvia-connect/agent-connect.git","type":"git"},"_npmVersion":"11.6.2","description":"Automatic retry and proxy fallback for Playwright powered by Aluvia","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","dependencies":{"proxy-chain":"^2.3.0","aluvia-ts-sdk":"^2.1.2"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"^4.0.3","playwright":"^1.56.1","typescript":"^5.9.3","@types/node":"^24.9.1","@vitest/coverage-v8":"^4.0.3"},"peerDependencies":{"playwright":">=1.40.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-connect_1.0.4_1762760083682_0.1641856116438949","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"1.1.0":{"name":"@aluvia-connect/agent-connect","version":"1.1.0","keywords":["playwright","proxy","aluvia","retry","automation","typescript"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia-connect/agent-connect@1.1.0","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://github.com/aluvia-connect/agent-connect#readme","bugs":{"url":"https://github.com/aluvia-connect/agent-connect/issues"},"dist":{"shasum":"4f65765ff5d60100a3a18cfaad558e4d95ac4419","tarball":"https://registry.npmjs.org/@aluvia-connect/agent-connect/-/agent-connect-1.1.0.tgz","fileCount":7,"integrity":"sha512-wvu9PJTg7EEsROpUJaexYGd3pizDxKOn/7eTmXff467EaAr1nQB2ORsxk343yoVFUoqEN9sgOyzaAtkyg35cMQ==","signatures":[{"sig":"MEYCIQCjTa8n2p4SoXVpmtbXyJw3rbcZTWNIINrZ1qZaVb51ewIhAOVYXJbotWYsurH6joZIL6AU/qiZKLH+ta1uhUBpyIAX","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aluvia-connect%2fagent-connect@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":36977},"main":"./dist/cjs/src/index.js","type":"module","types":"./dist/types/src/index.d.ts","module":"./dist/esm/src/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/src/index.d.ts","import":"./dist/esm/src/index.js","require":"./dist/cjs/src/index.js"},"./package.json":"./package.json"},"gitHead":"60e2f02496bb2a477525d6035f998bc45a4213cd","scripts":{"test":"vitest run --reporter=dot","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\\\"}')\"","clean":"rimraf dist","test:watch":"vitest","audit:check":"npm audit --audit-level moderate","release:tag":"git tag v$(node -p \"require('./package.json').version\")","release:push":"git push origin main && git push origin --tags","release:check":"npm run build && npm pack --dry-run","release:version":"node -p \"require('./package.json').version\""},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c69135dc-beea-4eac-be0c-60f1f61e7a56"}},"repository":{"url":"git+https://github.com/aluvia-connect/agent-connect.git","type":"git"},"_npmVersion":"11.6.2","description":"Automatic retry and proxy fallback for Playwright powered by Aluvia","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","dependencies":{"proxy-chain":"^2.3.0","aluvia-ts-sdk":"^2.1.2"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"^4.0.3","playwright":"^1.56.1","typescript":"^5.9.3","@types/node":"^24.9.1","@vitest/coverage-v8":"^4.0.3"},"peerDependencies":{"playwright":">=1.40.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-connect_1.1.0_1762918921015_0.15639037708838588","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"1.2.0":{"name":"@aluvia-connect/agent-connect","version":"1.2.0","keywords":["playwright","proxy","aluvia","retry","automation","typescript"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia-connect/agent-connect@1.2.0","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://github.com/aluvia-connect/agent-connect#readme","bugs":{"url":"https://github.com/aluvia-connect/agent-connect/issues"},"dist":{"shasum":"10355dd1fb983b87e864e0362a42f62f92b9f194","tarball":"https://registry.npmjs.org/@aluvia-connect/agent-connect/-/agent-connect-1.2.0.tgz","fileCount":7,"integrity":"sha512-opt6yVJNKJSgdl5jWJ6iNFfl/flLpXNjZrYn5jg5S74iA318F8X8gcvLu0vrQKXA7sfXwRJwpsxoqBRpkq3Yug==","signatures":[{"sig":"MEUCIQDbdjBok++xkrjSaEtSqLeNLVzQF/KrcjYpEWs+eDUlvgIgSiNKFYKHSjgIC+9CpXwT2GPgAAUboUdwh5t/PysiQtQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aluvia-connect%2fagent-connect@1.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":36985},"main":"./dist/cjs/src/index.js","type":"module","types":"./dist/types/src/index.d.ts","module":"./dist/esm/src/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/src/index.d.ts","import":"./dist/esm/src/index.js","require":"./dist/cjs/src/index.js"},"./package.json":"./package.json"},"gitHead":"25ef97a90dcef4693f890b77447ea9091de4a8f4","scripts":{"test":"vitest run --reporter=dot","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\\\"}')\"","clean":"rimraf dist","test:watch":"vitest","audit:check":"npm audit --audit-level moderate","release:tag":"git tag v$(node -p \"require('./package.json').version\")","release:push":"git push origin main && git push origin --tags","release:check":"npm run build && npm pack --dry-run","release:version":"node -p \"require('./package.json').version\""},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c69135dc-beea-4eac-be0c-60f1f61e7a56"}},"repository":{"url":"git+https://github.com/aluvia-connect/agent-connect.git","type":"git"},"_npmVersion":"11.6.3","description":"Automatic retry and proxy fallback for Playwright powered by Aluvia","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","dependencies":{"proxy-chain":"^2.3.0","aluvia-ts-sdk":"^2.1.2"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"^4.0.3","playwright":"^1.56.1","typescript":"^5.9.3","@types/node":"^24.9.1","@vitest/coverage-v8":"^4.0.3"},"peerDependencies":{"playwright":">=1.40.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-connect_1.2.0_1763631589930_0.5593593976570534","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2025-11-07T06:37:17.312Z","modified":"2026-02-23T02:22:51.389Z","1.0.0":"2025-11-07T06:37:17.667Z","1.0.2":"2025-11-10T05:35:05.079Z","1.0.3":"2025-11-10T05:43:45.935Z","1.0.4":"2025-11-10T07:34:43.874Z","1.1.0":"2025-11-12T03:42:01.210Z","1.2.0":"2025-11-20T09:39:50.108Z"},"bugs":{"url":"https://github.com/aluvia-connect/agent-connect/issues"},"author":{"name":"Aluvia"},"license":"MIT","homepage":"https://github.com/aluvia-connect/agent-connect#readme","keywords":["playwright","proxy","aluvia","retry","automation","typescript"],"repository":{"url":"git+https://github.com/aluvia-connect/agent-connect.git","type":"git"},"description":"Automatic retry and proxy fallback for Playwright powered by Aluvia","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"readme":"# Agent Connect\n\n[![npm version](https://badge.fury.io/js/@aluvia-connect%2Fagent-connect.svg)](https://badge.fury.io/js/@aluvia-connect%2Fagent-connect)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)\n\nRetry failed [Playwright](https://playwright.dev) navigations automatically with proxy fallback.\n\n[Read the full documentation](https://docs.aluvia.io/docs/using-aluvia/agent-connect-sdk)\n\n## Installation\n\n```bash\nnpm install @aluvia-connect/agent-connect\n```\n\n```bash\nyarn add @aluvia-connect/agent-connect\n```\n\n```bash\npnpm add @aluvia-connect/agent-connect\n```\n\n## Quick Start\n\n```ts\nimport { chromium } from \"playwright\";\nimport { agentConnect, startDynamicProxy } from \"@aluvia-connect/agent-connect\";\n\n// Start local proxy-chain server (random free port)\nconst dyn = await startDynamicProxy();\n\n// Launch browser using ONLY the local proxy initially (direct connection upstream)\nconst browser = await chromium.launch({ proxy: { server: dyn.url } });\nconst context = await browser.newContext();\nconst page = await context.newPage();\n\nconst { page: samePage } = await agentConnect(page, {\n  dynamicProxy: dyn,\n  maxRetries: 2,\n  retryOn: [\"Timeout\", /net::ERR/],\n  onProxyLoaded: (p) => console.log(\"Upstream proxy loaded\", p.server),\n  onRetry: (a, m) => console.log(`Retry ${a}/${m}`),\n}).goto(\"https://blocked-website.example\");\n\nconsole.log(await samePage.title());\nawait browser.close();\n```\n\nNotes:\n\n- The first attempt is direct (no upstream proxy). On failure, we fetch a proxy and call `dynamicProxy.setUpstream()` internally.\n- Subsequent retries reuse the same browser & page; cookies and session data persist.\n- Provide your own `proxyProvider` if you do not want to use the Aluvia API.\n- The dynamic proxy closes automatically when `browser.close()` is called. You can also call `dyn.close()` manually.\n\nYou can integrate this with any proxy API or local pool, as long as it returns a `server`, `username`, and `password`.\n\n## Aluvia Token Setup\n\nThis 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.\n\nSet your token key in a `.env` file:\n\n```env\nALUVIA_TOKEN=your_aluvia_token\n```\n\n## Configuration\n\nYou can control how `agentConnect` behaves using environment variables or options passed in code.\nThe environment variables set defaults globally, while the TypeScript options let you override them per call.\n\n### Environment Variables\n\n| Variable             | Description                                                                              | Default                                 |\n|----------------------| ---------------------------------------------------------------------------------------- |-----------------------------------------|\n| `ALUVIA_TOKEN`       | Required unless you provide a custom `proxyProvider`. Used to fetch proxies from Aluvia. | _none_                                  |\n| `ALUVIA_MAX_RETRIES` | Number of retry attempts after the first failed navigation.                              | `2`                                     |\n| `ALUVIA_BACKOFF_MS`  | Base delay (ms) between retries, grows exponentially with jitter.                        | `300`                                   |\n| `ALUVIA_RETRY_ON`    | Comma-separated list of retryable error substrings.                                      | `ECONNRESET,ETIMEDOUT,net::ERR,Timeout` |\n\n#### Example `.env`\n\n```env\nALUVIA_TOKEN=your_aluvia_token\nALUVIA_MAX_RETRIES=1\nALUVIA_BACKOFF_MS=500\nALUVIA_RETRY_ON=ECONNRESET,ETIMEDOUT,net::ERR,Timeout\n```\n\n### Options\n\nYou can also configure behavior programmatically by passing options to `agentConnect()`.\n\n```typescript\nimport { agentConnect } from \"@aluvia-connect/agent-connect\";\n\nconst { response, page } = await agentConnect(page, {\n  maxRetries: 3,\n  backoffMs: 500,\n  retryOn: [\"ECONNRESET\", /403/],\n  onRetry: (attempt, maxRetries, lastError) => {\n    console.log(\n      `Retry attempt ${attempt} of ${maxRetries} due to error:`,\n      lastError\n    );\n  },\n  onProxyLoaded: (proxy) => {\n    console.log(`Proxy loaded: ${proxy.server}`);\n  },\n});\n```\n\n#### Available Options\n\n| Option            | Type                                                                                 | Default                                  | Description                                                                                                   |\n| ----------------- | ------------------------------------------------------------------------------------ |------------------------------------------| ------------------------------------------------------------------------------------------------------------- |\n| `maxRetries`      | `number`                                                                             | `process.env.ALUVIA_MAX_RETRIES` or `2`  | Number of retry attempts after the first failure.                                                             |\n| `backoffMs`       | `number`                                                                             | `process.env.ALUVIA_BACKOFF_MS` or `300` | Base delay (in ms) between retries, grows exponentially with jitter.                                          |\n| `retryOn`         | `(string \\| RegExp)[]`                                                               | `process.env.ALUVIA_RETRY_ON`            | Error patterns considered retryable.                                                                          |\n| `proxyProvider`   | `ProxyProvider`                                                                      | Uses Aluvia SDK                          | Custom proxy provider that returns proxy credentials.                                                         |\n| `onRetry`         | `(attempt: number, maxRetries: number, lastError: unknown) => void \\| Promise<void>` | `undefined`                              | Callback invoked before each retry attempt.                                                                   |\n| `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). |\n\n#### Custom Proxy Provider Example\n\n```typescript\nconst myProxyProvider = {\n  async get() {\n    return {\n      server: \"http://myproxy.example.com:8000\",\n      username: \"user123\",\n      password: \"secret\",\n    };\n  },\n};\n\nconst { response, page } = await agentConnect(page, {\n  proxyProvider: myProxyProvider,\n  maxRetries: 3,\n});\n```\n\n## Requirements\n\n- Node.js >= 18\n- Playwright\n- Aluvia token (_if not using a custom proxy provider_)\n\n## About Aluvia\n\n[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.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.MD](CONTRIBUTING.MD) for guidelines.\n\n- Fork the repo and create your branch.\n- Write clear commit messages.\n- Add tests for new features.\n- Open a pull request.\n\n## Support\n\nFor bugs, feature requests, or questions, please open an issue on [GitHub](https://github.com/aluvia-connect/agent-connect/issues).\n\nFor commercial support or proxy questions, visit [Aluvia](https://www.aluvia.io/).\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\nAluvia - [https://www.aluvia.io/](https://www.aluvia.io/)\n","readmeFilename":"README.md"}