Polish SDK repositories

Author: lr2bmail

.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm test

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+coverage/

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+Thanks for helping improve the Proxy11 Node.js client.
+
+## Local Setup
+
+```bash
+npm test
+```
+
+Keep changes small and focused. If you add or change behavior, add a test for it.

README.md

@@ -1,6 +1,12 @@
 # proxy11
 
-Lightweight Node.js client for the [Proxy11](https://proxy11.com) proxy API.
+[![npm](https://img.shields.io/npm/v/proxy11.svg)](https://www.npmjs.com/package/proxy11)
+[![Node](https://img.shields.io/node/v/proxy11.svg)](package.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Official Node.js client for the [Proxy11](https://proxy11.com) proxy API.
+
+Use it to fetch fresh proxy lists, filter by country or anonymity type, rotate through proxies, and export simple `ip:port` files.
 
 ## Install
 
@@ -14,41 +20,40 @@ npm install proxy11
 const { ProxyClient } = require("proxy11");
 
 const client = new ProxyClient("YOUR_API_KEY");
+
+const proxies = await client.get({ limit: 50, country: "us" });
+const proxy = await client.random({ proxyType: "anonymous" });
+const proxyList = await client.asList({ limit: 100 });
 ```
 
-`Proxy11Error`, `APIError`, and `NoProxiesError` are exported if you want to catch client-specific errors.
+## Examples
 
-## Get Proxies
+### Get Proxies
 
 ```js
-const proxies = await client.get();
-
-const usProxies = await client.get({
+const proxies = await client.get({
   limit: 50,
   country: "us",
   proxyType: "anonymous",
   speed: 1.0,
 });
 ```
 
-## Get `ip:port` List
+### Get `ip:port` List
 
 ```js
 const proxies = await client.asList({ limit: 50 });
 // ["103.152.112.166:8080", "45.77.56.114:4145"]
 ```
 
-## Random Proxy
+### Random Proxy
 
 ```js
 const proxy = await client.random({ country: "us" });
-// "103.152.112.166:8080"
-
 const proxyDetails = await client.randomProxy();
-// { ip: "103.152.112.166", port: "8080", country: "Indonesia", ... }
 ```
 
-## Save to File
+### Save to File
 
 ```js
 const count = await client.save("proxies.txt", { country: "us" });
@@ -57,8 +62,6 @@ console.log(`saved ${count} proxies`);
 
 ## Rotator
 
-Cycle through proxies with optional auto-refresh and dead-proxy removal.
-
 ```js
 const rotator = await client.rotator({
   country: "us",
@@ -73,26 +76,55 @@ for (let i = 0; i < 100; i += 1) {
   // if proxy fails:
   // rotator.markDead(proxy);
 }
+```
+
+## Error Handling
 
-console.log(`${rotator.remaining} proxies left in pool`);
+```js
+const { APIError, NoProxiesError, ProxyClient } = require("proxy11");
+
+const client = new ProxyClient("YOUR_API_KEY");
+
+try {
+  const proxy = await client.random({ country: "us" });
+  console.log(proxy);
+} catch (error) {
+  if (error instanceof NoProxiesError) {
+    console.log("No proxies matched the filters");
+  } else if (error instanceof APIError) {
+    console.log(`Proxy11 API error: ${error.message}`);
+  } else {
+    throw error;
+  }
+}
 ```
 
-## Parameters
+## API
+
+| Method | Description |
+|--------|-------------|
+| `get(filters)` | Return proxy rows as objects |
+| `asList(filters)` | Return proxies as `ip:port` strings |
+| `random(filters)` | Return one random `ip:port` proxy |
+| `randomProxy(filters)` | Return one random proxy object |
+| `save(path, filters)` | Save `ip:port` proxies to a file |
+| `rotator(filters)` | Create an async proxy rotator |
 
-| Parameter   | Type   | Description                                      |
-|-------------|--------|--------------------------------------------------|
-| `limit`     | number | Max proxies to return (free: 50, ultimate: 5000) |
-| `country`   | string | Filter by country name or code                   |
-| `port`      | number | Filter by port number                            |
-| `speed`     | number | Max response time in seconds                     |
-| `proxyType` | string | `anonymous` or `transparent`                     |
+## Filters
 
-## API Key
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | number | Max proxies to return, capped by your plan |
+| `country` | string | Country name or two-letter country code |
+| `port` | number | Proxy port |
+| `speed` | number | Max response time in seconds |
+| `proxyType` | string | `anonymous` or `transparent` |
 
-Get a free API key at [proxy11.com](https://proxy11.com/newaccount).
+## Links
 
-- **Free plan**: 50 proxies per request
-- **Ultimate plan**: 5,000 proxies per request, from $12
+- Website: [proxy11.com](https://proxy11.com)
+- API docs: [proxy11.com/apidoc](https://proxy11.com/apidoc)
+- SDK page: [proxy11.com/sdk](https://proxy11.com/sdk)
 
 ## License
 

SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+If you find a security issue in this client or in the Proxy11 API, please do not open a public issue.
+
+Email: info@proxy11.com
+
+Include enough detail to reproduce the issue. We will review and respond as quickly as possible.

examples/basic.js

@@ -0,0 +1,12 @@
+const { ProxyClient } = require("../src");
+
+async function main() {
+  const client = new ProxyClient("YOUR_API_KEY");
+  const proxies = await client.get({ limit: 10, country: "us" });
+  console.log(proxies);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

examples/rotator.js

@@ -0,0 +1,19 @@
+const { ProxyClient } = require("../src");
+
+async function main() {
+  const client = new ProxyClient("YOUR_API_KEY");
+  const rotator = await client.rotator({
+    country: "us",
+    proxyType: "anonymous",
+    autoRefresh: true,
+  });
+
+  for (let i = 0; i < 10; i += 1) {
+    console.log(await rotator.next());
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

examples/save.js

@@ -0,0 +1,12 @@
+const { ProxyClient } = require("../src");
+
+async function main() {
+  const client = new ProxyClient("YOUR_API_KEY");
+  const count = await client.save("proxies.txt", { limit: 100, country: "us" });
+  console.log(`saved ${count} proxies`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});