{"_id":"11dice","_rev":"2-cdf85831e984335c1f4d38b4fb89ca93","name":"11dice","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"11dice","version":"0.1.0","keywords":["proxy","proxies","fetch","rotate","rotation","free-proxy","proxy-pool","load-test","scraping","rate-limit","undici"],"license":"MIT","_id":"11dice@0.1.0","maintainers":[{"name":"moji2002","email":"moji2002@gmail.com"}],"dist":{"shasum":"860b7ec85a66207adf85478d57d58f9199e2380e","tarball":"https://registry.npmjs.org/11dice/-/11dice-0.1.0.tgz","fileCount":9,"integrity":"sha512-6u2DT6ZN8/fSRZWxGu86VZH/9jUhVW2kYzm4Nh0P4jOiQHPkXqXuqborvSVtaFyZjneufl+UCCANbaL/ab1s4g==","signatures":[{"sig":"MEYCIQDPgl1OC8KvgBPRW+NZo1NQm2m+oKUXuj3qa6SJ2l3TrAIhAOP1uZHzt5M1SiztdihRdh7IBPBTZlYfK3udQoqnDVwD","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":254495},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.18.0"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"9d01f4b2932c9d9f76f3b26733a257dd97d2a944","scripts":{"test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"moji2002","email":"moji2002@gmail.com"},"_npmVersion":"11.16.0","description":"fetch with automatic rotating free proxies. Scrapes public proxy lists, validates them, and routes every request through a random working proxy. Proper defaults, works out of the box.","directories":{},"sideEffects":false,"_nodeVersion":"20.19.4","dependencies":{"undici":"^7.29.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^3.2.7","typescript":"^5.9.3","@types/node":"^22.20.1"},"_npmOperationalInternal":{"tmp":"tmp/11dice_0.1.0_1788803167178_0.04069203727678827","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"11dice","version":"0.2.0","description":"fetch with automatic rotating free proxies. Scrapes public proxy lists, validates them, and routes every request through a random working proxy. Proper defaults, works out of the box.","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"sideEffects":false,"engines":{"node":">=20.18.0"},"scripts":{"build":"tsup","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"keywords":["proxy","proxies","fetch","rotate","rotation","free-proxy","proxy-pool","load-test","scraping","rate-limit","undici"],"license":"MIT","dependencies":{"undici":"^7.29.1"},"devDependencies":{"@types/node":"^22.20.1","tsup":"^8.5.1","typescript":"^5.9.3","vitest":"^3.2.7"},"gitHead":"3078e8ef667576cd32217f21faf79a178663d6d2","_id":"11dice@0.2.0","_nodeVersion":"20.19.4","_npmVersion":"11.16.0","dist":{"integrity":"sha512-68qKNWXcTQDf3ds3Hq/OhhyG9cpag6u14+9zhKnX6vakztytDgQY/bJT7Oz62lE6p2nInny3aZ86aahiPm4VlQ==","shasum":"67e680a61cefaaad51aeec4b10059da0d8c260e9","tarball":"https://registry.npmjs.org/11dice/-/11dice-0.2.0.tgz","fileCount":9,"unpackedSize":255043,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDqHe8g/5GY+4O2EQUB66ZaXcnHlHnsSAhsm8SYpCFkQgIgeXDFaYnW2qKUYk5WhGBIEaP+2sWlEVmrmked91zBkDY="}]},"_npmUser":{"name":"moji2002","email":"moji2002@gmail.com"},"directories":{},"maintainers":[{"name":"moji2002","email":"moji2002@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/11dice_0.2.0_1788803254199_0.7335689169298343"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T17:46:06.795Z","modified":"2026-09-07T17:47:34.525Z","0.1.0":"2026-09-07T17:46:07.309Z","0.2.0":"2026-09-07T17:47:34.329Z"},"license":"MIT","keywords":["proxy","proxies","fetch","rotate","rotation","free-proxy","proxy-pool","load-test","scraping","rate-limit","undici"],"description":"fetch with automatic rotating free proxies. Scrapes public proxy lists, validates them, and routes every request through a random working proxy. Proper defaults, works out of the box.","maintainers":[{"name":"moji2002","email":"moji2002@gmail.com"}],"readme":"# 11dice\n\nA fetch-like HTTP client for Node.js that scrapes free proxies, validates them,\nand rotates through a fresh proxy on every request — so you can hammer your own\nservers or APIs without tripping IP-based rate limits.\n\n```ts\nimport { ElevenDice } from '11dice'\n\nconst client = new ElevenDice({ rotation: 'random' })\nconst res = await client.fetch('https://api.example.com/health')\nconsole.log(res.proxy.url) // the proxy that actually served the request\n```\n\n## Features\n\n- **Auto-scraping** — pulls free proxies from trusted CDN sources (jsDelivr/API\n  endpoints) on startup and refreshes them every 15 minutes by default. Add your\n  own sources or seed a list directly via `proxyList`.\n- **Auto-validation** — every scraped proxy is probed for liveness before it\n  enters the pool, so you rarely ask a dead proxy to do work.\n- **Rotation** — `random` (default), `round-robin`, or `sticky` (reuse one proxy\n  for N requests to keep sessions).\n- **Retries** — transparently retries `429` / `5xx` and network failures through\n  a *different* proxy.\n- **Realistic User-Agent** — a random real browser UA is attached by default;\n  your own explicit `user-agent` header always wins.\n- **HTTP, HTTPS & SOCKS5** — powered by undici's `ProxyAgent`.\n- **TypeScript** — full type definitions, ESM + CJS.\n\n## Install\n\n```sh\nnpm install 11dice\n```\n\nRequires Node.js `>=20.18.0`.\n\n## Quick start\n\n```ts\nimport { ElevenDice } from '11dice'\n\nconst client = new ElevenDice({\n  rotation: 'round-robin',\n  retries: 3,              // extra proxies tried after the first failure\n  retryStatuses: [429, 500, 502, 503, 504],\n})\n\nconst res = await client.fetch('https://httpbin.org/headers', {\n  headers: { 'x-anything': 'yes' },\n})\n\nconsole.log(res.status)      // 200\nconsole.log(res.proxy?.host) // the IP that served you\nconsole.log(res.elapsedMs)   // total time including retries\nawait client.close()         // stop the refresh timer\n```\n\n## Options\n\nAll fields are optional; defaults are safe for most users.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `protocols` | `['http', 'https', 'socks5']` | Proxy protocols to keep in the pool. |\n| `sources` | built-in list | Custom `url` (and optional `protocol` hint) sources. `[]` disables scraping. |\n| `proxyList` | `[]` | Seed proxies directly: `'host:port'`, `'scheme://host:port'`, or full `ProxyInfo` objects. |\n| `maxProxies` | `200` | Cap on pooled proxies. |\n| `minProxies` | `10` | Minimum alive proxies before the pool is \"ready\" for a request. |\n| `validationTarget` | `https://example.com` | URL used to probe liveness. |\n| `validationTimeoutMs` | `8000` | Per-probe timeout. |\n| `validationConcurrency` | `50` | Probes run in parallel. |\n| `validateOnRefresh` | `true` | Probe sources after scraping. |\n| `requestTimeoutMs` | `15000` | Per-attempt timeout. |\n| `refreshIntervalMs` | `900000` (15 min) | Re-scrape cadence. |\n| `autoRefresh` | `true` | Scrape on startup and on the interval. |\n| `retries` | `3` | Extra attempts through different proxies after a failure. |\n| `retryStatuses` | `[429, 500, 502, 503, 504]` | Status codes that trigger a retry. |\n| `rotation` | `'random'` | `'random'`, `'round-robin'`, or `'sticky'`. |\n| `stickyRequests` | `5` | Requests per proxy in `'sticky'` mode. |\n| `userAgents` | `true` | `true` = built-in UA pool, `string[]` = your UAs, `false` = never send the header. |\n| `maxConcurrent` | `Infinity` | Cap on concurrent requests. |\n| `fallbackDirect` | `false` | Send directly (no proxy) when the pool is empty. |\n| `strictProxies` | `true` | Throw `NoProxiesAvailableError` instead of going direct when the pool stays empty. |\n| `log` | `false` | Log refresh/validation activity to stderr. |\n\n### Per-request options\n\n`fetch` accepts everything undici's `fetch` does, plus:\n\n- `timeoutMs` — override `requestTimeoutMs` for this call.\n- `proxy` — force one specific proxy for this call, skipping rotation.\n- `rotation` — override the pool strategy for this call.\n\n## The returned response\n\n`client.fetch` returns a standard `Response` (use `.json()`, `.text()`, etc.)\nwith these extras:\n\n- `res.proxy` — the `ProxyInfo` that served the request, or `null` for direct.\n- `res.attempts` — every proxy tried, in order.\n- `res.elapsedMs` — total wall-clock time including retries.\n\n## Errors\n\n```ts\nimport { NoProxiesAvailableError, AllRetriesFailedError } from '11dice'\n```\n\n- `NoProxiesAvailableError` — the pool is empty after a refresh and no fallback\n  applies.\n- `AllRetriesFailedError` — every attempt (through different proxies) failed;\n  `.cause` holds the final underlying error.\n- `InvalidProxyError`, `UnsupportedProtocolError` — bad `proxyList` entries.\n\n## Disclaimer\n\n**Use at your own risk, and only against servers you control or have explicit\npermission to load-test.**\n\n- Free proxies are unreliable, slow, and commonly operated by strangers. They\n  can read, log, drop, or tamper with every byte you send through them.\n  **Never** route credentials, tokens, or any sensitive or personally\n  identifiable data through this client.\n- A proxy can MITM your traffic, return forged responses, or black-hole\n  requests. Treat all proxied responses as untrusted input.\n- Do **not** use this to hammer websites, APIs, or services you do not own or\n  that do not authorize load testing — that is abuse and may be illegal.\n- Free proxy lists churn constantly; expect intermittent failures and flaky\n  results. This package is a convenience wrapper over data you did not author.\n\nBy using `11dice` you accept full responsibility for the traffic you send and\nthe targets you send it to.\n\n## License\n\nMIT","readmeFilename":"README.md"}