proxychecker-dev 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flash AI Solutions (Jaylon Malone)
+
+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,113 @@
+# proxycheck
+
+Fast **proxy checker** for the command line. Test HTTP, HTTPS, SOCKS4, and SOCKS5 proxies for liveness, latency, anonymity, and datacenter-vs-residential type. No signup, no ads, no sketchy binary.
+
+Powered by [proxychecker.dev](https://proxychecker.dev).
+
+```bash
+npx proxychecker-dev proxies.txt
+```
+
+```
+  ALIVE  45.12.30.9:8080     http    datacenter   142ms  US  Cloudflare
+  ALIVE  98.162.25.7:31654   socks5  residential  380ms  DE  Deutsche Telekom
+  DEAD   9.9.9.9:3128        http    -            -      -   timeout
+
+  2 alive · 1 dead · avg 261ms · 1 dc · 1 res
+```
+
+## Why
+
+If you buy proxies for scraping, half the list is usually dead, slow, or a datacenter IP being sold as "residential." Checking them by hand or hacking together a `curl` loop is a waste of a morning. This does it in one command, tells you which are actually alive, how fast, and what type they really are.
+
+## Install
+
+Run it with no install:
+
+```bash
+npx proxychecker-dev proxies.txt
+```
+
+Or install globally for the short `proxycheck` command:
+
+```bash
+npm install -g proxychecker-dev
+proxycheck proxies.txt
+```
+
+Requires Node.js 18+.
+
+## Usage
+
+```bash
+# from a file (one proxy per line, # comments ignored)
+proxycheck proxies.txt
+
+# inline
+proxycheck 1.2.3.4:8080 socks5://5.6.7.8:1080
+
+# from stdin
+cat proxies.txt | proxycheck
+
+# only the live ones, as JSON, piped to jq
+proxycheck proxies.txt --alive --json | jq -r '.results[].input'
+
+# export a CSV
+proxycheck proxies.txt --csv > results.csv
+```
+
+### Accepted formats
+
+One per line. Lines starting with `#` are ignored.
+
+```
+ip:port
+ip:port:user:pass
+user:pass@ip:port
+socks5://ip:port
+```
+
+Protocols: `http`, `https`, `socks4`, `socks5`.
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-k, --key <pck_...>` | API key for 5,000 proxies/call + auto-chunking (or set `PROXYCHECK_KEY`) |
+| `-t, --timeout <ms>` | Per-proxy timeout, 3000-30000 (default 10000) |
+| `-a, --alive` | Only output proxies that are alive |
+| `--json` | Output raw JSON (pipe to `jq`) |
+| `--csv` | Output CSV |
+| `--fail-if-none` | Exit non-zero if zero proxies are alive (useful in CI) |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+## Free vs. keyed
+
+The free tier checks **50 proxies per call** with no key and no signup. That covers casual use forever.
+
+Got a big list? A key unlocks **5,000 proxies per call**, and the CLI automatically splits larger jobs into chunks and merges the results, so `proxycheck huge-list.txt --key pck_...` just works.
+
+Keys are a one-time **$5** (5,000 proxies) or **$15/mo** for ongoing bulk + API access: [proxychecker.dev/pricing](https://proxychecker.dev/pricing). Set it once:
+
+```bash
+export PROXYCHECK_KEY=pck_live_xxxxx
+proxycheck huge-list.txt
+```
+
+## What you get per proxy
+
+- **status** — alive or dead
+- **protocol** — http / https / socks4 / socks5
+- **type** — datacenter, residential, or mobile
+- **latency** — round-trip in ms
+- **country / city / ISP / ASN** — geo + network
+- **suspected_fake_residential** — flags datacenter IPs being sold as residential
+
+## API
+
+The CLI is a thin wrapper over the [proxychecker.dev API](https://proxychecker.dev/docs/api). POST a JSON array of proxies to `/api/check` with `Authorization: Bearer pck_...` and get JSON or CSV back. Use whichever you like.
+
+## License
+
+MIT © Flash AI Solutions

package/bin/proxycheck.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+// proxycheck - CLI for proxychecker.dev
+// Zero runtime dependencies. Node >=18 (uses built-in fetch + util.parseArgs).
+//
+// Free tier: 50 proxies/call, no key needed.
+// Paid tier: pass --key pck_... (or PROXYCHECK_KEY env) for 5,000/call + chunking.
+
+import { parseArgs } from "node:util";
+import { readFileSync, existsSync, statSync } from "node:fs";
+
+const API_BASE = process.env.PROXYCHECK_API || "https://proxychecker.dev";
+const FREE_CAP = 50;       // server truncates free requests above this
+const KEYED_CHUNK = 5000;  // pro tier cap; we split larger jobs into 5k calls
+
+// ---------- tiny ANSI color helpers (respect NO_COLOR + non-TTY pipes) ----------
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const green = paint(32), red = paint(31), dim = paint(90), bold = paint(1),
+      cyan = paint(36), yellow = paint(33);
+
+const HELP = `
+${bold("proxycheck")} - test proxies for liveness, speed, and type   ${dim("proxychecker.dev")}
+
+${bold("USAGE")}
+  proxycheck <file>                 check proxies from a file (one per line)
+  proxycheck <proxy> [proxy...]     check proxies passed as arguments
+  cat proxies.txt | proxycheck      check proxies from stdin
+
+${bold("OPTIONS")}
+  -k, --key <pck_...>   API key for 5,000/call + auto-chunking (or PROXYCHECK_KEY)
+  -t, --timeout <ms>    per-proxy timeout, 3000-30000 (default 10000)
+  -a, --alive           only output proxies that are alive
+      --json            output raw JSON (good for piping to jq)
+      --csv             output CSV (input,status,protocol,type,latency,country,isp)
+      --fail-if-none    exit non-zero if zero proxies are alive (for CI)
+  -h, --help            show this help
+  -v, --version         show version
+
+${bold("FORMATS ACCEPTED")}   (one per line, # comments ignored)
+  ip:port                       socks5://ip:port
+  ip:port:user:pass             user:pass@ip:port
+
+${bold("EXAMPLES")}
+  proxycheck proxies.txt
+  proxycheck 1.2.3.4:8080 socks5://5.6.7.8:1080 --alive
+  proxycheck big.txt --key pck_live_xxx --csv > results.csv
+  cat proxies.txt | proxycheck --alive --json | jq '.results[].input'
+
+Free checks 50 proxies/call. Bulk + API access from $5: ${cyan("https://proxychecker.dev/pricing")}
+`;
+
+function fail(msg, code = 1) {
+  process.stderr.write(red("error: ") + msg + "\n");
+  process.exit(code);
+}
+
+// ---------- parse args ----------
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      key:            { type: "string", short: "k" },
+      timeout:        { type: "string", short: "t" },
+      alive:          { type: "boolean", short: "a" },
+      json:           { type: "boolean" },
+      csv:            { type: "boolean" },
+      "fail-if-none": { type: "boolean" },
+      help:           { type: "boolean", short: "h" },
+      version:        { type: "boolean", short: "v" },
+    },
+  });
+} catch (e) {
+  fail(e.message + "\nRun 'proxycheck --help' for usage.");
+}
+const { values: opts, positionals } = parsed;
+
+if (opts.help) { process.stdout.write(HELP); process.exit(0); }
+if (opts.version) {
+  // read our own version without importing json (keeps it ESM-simple)
+  try {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    process.stdout.write(pkg.version + "\n");
+  } catch { process.stdout.write("unknown\n"); }
+  process.exit(0);
+}
+
+const key = opts.key || process.env.PROXYCHECK_KEY || null;
+const timeout = opts.timeout ? parseInt(opts.timeout, 10) : undefined;
+if (opts.timeout && (!Number.isFinite(timeout) || timeout < 1000)) {
+  fail("--timeout must be a number of milliseconds (>= 1000)");
+}
+
+// ---------- gather proxy list from file / args / stdin ----------
+function looksLikeProxy(s) {
+  return /[:@]/.test(s); // has a port or credentials separator
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function parseList(text) {
+  return text
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith("#"));
+}
+
+function isFile(p) {
+  try { return existsSync(p) && statSync(p).isFile(); }
+  catch { return false; }
+}
+
+async function gatherProxies() {
+  if (positionals.length) {
+    // A real file on disk wins (a Windows path like C:\list.txt also contains
+    // ':' so we can't rely on looksLikeProxy alone -- check the filesystem).
+    if (isFile(positionals[0])) {
+      return parseList(readFileSync(positionals[0], "utf8"));
+    }
+    // Otherwise treat the positionals as inline proxies.
+    if (positionals.every(looksLikeProxy)) {
+      return positionals;
+    }
+    fail(`'${positionals[0]}' is not a readable file or a valid proxy.\n` +
+         `Run 'proxycheck --help' for usage.`);
+  }
+  // Piped stdin (cat proxies.txt | proxycheck)
+  if (!process.stdin.isTTY) {
+    return parseList(await readStdin());
+  }
+  // Nothing given
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+// ---------- API call (one chunk), with a single 429 backoff/retry ----------
+// Throws on failure (caught by main). We avoid process.exit() here because a
+// hard exit while an undici keep-alive socket is still closing trips a libuv
+// assertion on Windows. Setting exitCode + draining the loop is the safe path.
+async function checkChunk(proxies, attempt = 0) {
+  const headers = { "Content-Type": "application/json" };
+  if (key) headers["Authorization"] = "Bearer " + key;
+  let res;
+  try {
+    res = await fetch(API_BASE + "/api/check", {
+      method: "POST",
+      headers,
+      body: JSON.stringify(timeout ? { proxies, timeout } : { proxies }),
+    });
+  } catch (e) {
+    throw new Error(`network error reaching ${API_BASE}: ${e.message}`);
+  }
+  if (res.status === 429 && attempt < 3) {
+    process.stderr.write(dim(`rate limited, waiting 6s...\n`));
+    await new Promise((r) => setTimeout(r, 6000));
+    return checkChunk(proxies, attempt + 1);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    let msg = `API returned ${res.status}`;
+    try { const j = JSON.parse(body); if (j.error) msg = j.error; } catch {}
+    throw new Error(msg);
+  }
+  return res.json();
+}
+
+// ---------- rendering ----------
+function statusCell(r) {
+  if (r.status === "alive") return green("ALIVE");
+  return red("DEAD ");
+}
+function pad(s, n) {
+  s = String(s ?? "");
+  return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+
+function printTable(results) {
+  const rows = opts.alive ? results.filter((r) => r.status === "alive") : results;
+  if (!rows.length) {
+    process.stdout.write(dim("no proxies to show\n"));
+    return;
+  }
+  const wInput = Math.min(Math.max(...rows.map((r) => (r.input || "").length), 5), 32);
+  for (const r of rows) {
+    const type = r.status === "alive" ? (r.type || "unknown") : "-";
+    const lat = r.latency != null ? r.latency + "ms" : "-";
+    const geo = [r.country, r.isp].filter(Boolean).join(" ");
+    const fake = r.suspected_fake_residential ? yellow("  fake-res?") : "";
+    process.stdout.write(
+      `  ${statusCell(r)}  ${pad(r.input, wInput)}  ${dim(pad(r.protocol || "-", 6))}  ` +
+      `${pad(type, 11)}  ${pad(lat, 7)}  ${dim(geo)}${fake}\n`
+    );
+  }
+}
+
+function printSummary(summary, truncated) {
+  const s = summary;
+  const parts = [
+    green(s.alive + " alive"),
+    red(s.dead + " dead"),
+    dim(`avg ${s.avg_latency_ms}ms`),
+    dim(`${s.datacenter} dc`),
+    dim(`${s.residential} res`),
+  ];
+  if (s.mobile) parts.push(dim(`${s.mobile} mobile`));
+  if (s.suspected_fake_residential) parts.push(yellow(`${s.suspected_fake_residential} fake-res`));
+  process.stdout.write("\n  " + parts.join(dim(" · ")) + "\n");
+  if (truncated) {
+    process.stdout.write(
+      "\n  " + yellow(`checked ${truncated.checked} of ${truncated.sent} (free tier cap).`) +
+      "\n  " + `Unlock ${bold("5,000/call")} with a $5 one-time key -> ${cyan("https://proxychecker.dev/pricing")}\n`
+    );
+  }
+}
+
+function toCsv(results) {
+  const cols = ["input", "status", "protocol", "type", "latency", "country", "city", "isp", "asn", "suspected_fake_residential", "reason"];
+  const esc = (v) => {
+    if (v == null) return "";
+    const str = String(v);
+    return /[",\n]/.test(str) ? '"' + str.replace(/"/g, '""') + '"' : str;
+  };
+  const lines = [cols.join(",")];
+  for (const r of results) lines.push(cols.map((c) => esc(r[c])).join(","));
+  return lines.join("\n");
+}
+
+// ---------- main ----------
+(async () => {
+  const proxies = await gatherProxies();
+  if (!proxies.length) fail("no valid proxies found in input");
+ try {
+
+  let merged = [];
+  let summaryAcc = null;
+  let truncated = null;
+
+  if (!key) {
+    // Free path: send only the first FREE_CAP (server would truncate anyway),
+    // but tell the user the true total so the upsell is honest.
+    const send = proxies.slice(0, FREE_CAP);
+    if (!opts.json && !opts.csv) {
+      process.stderr.write(dim(`proxychecker.dev · checking ${send.length} ` +
+        `${proxies.length > FREE_CAP ? `of ${proxies.length} ` : ""}proxies...\n\n`));
+    }
+    const data = await checkChunk(send);
+    merged = data.results;
+    summaryAcc = data.summary;
+    if (proxies.length > FREE_CAP) truncated = { sent: proxies.length, checked: send.length };
+  } else {
+    // Keyed path: split into 5k chunks and merge.
+    const chunks = [];
+    for (let i = 0; i < proxies.length; i += KEYED_CHUNK) chunks.push(proxies.slice(i, i + KEYED_CHUNK));
+    let done = 0;
+    for (const chunk of chunks) {
+      if (!opts.json && !opts.csv) {
+        process.stderr.write(dim(`\rproxychecker.dev · checking ${done + chunk.length}/${proxies.length}...`));
+      }
+      const data = await checkChunk(chunk);
+      merged.push(...data.results);
+      done += chunk.length;
+      if (!summaryAcc) summaryAcc = { ...data.summary };
+      else for (const k of Object.keys(data.summary)) summaryAcc[k] += data.summary[k];
+    }
+    if (summaryAcc && merged.length) {
+      const alive = merged.filter((r) => r.status === "alive");
+      summaryAcc.avg_latency_ms = alive.length
+        ? Math.round(alive.reduce((s, r) => s + (r.latency || 0), 0) / alive.length)
+        : 0;
+    }
+    if (!opts.json && !opts.csv) process.stderr.write("\n\n");
+  }
+
+  // ---------- output ----------
+  if (opts.csv) {
+    const rows = opts.alive ? merged.filter((r) => r.status === "alive") : merged;
+    process.stdout.write(toCsv(rows) + "\n");
+  } else if (opts.json) {
+    const rows = opts.alive ? merged.filter((r) => r.status === "alive") : merged;
+    process.stdout.write(JSON.stringify({ summary: summaryAcc, truncated, results: rows }, null, 2) + "\n");
+  } else {
+    printTable(merged);
+    printSummary(summaryAcc, truncated);
+  }
+
+  if (opts["fail-if-none"] && (!summaryAcc || summaryAcc.alive === 0)) process.exitCode = 2;
+ } catch (e) {
+    // Any post-network failure lands here: report and set a non-zero exit code,
+    // then let the event loop drain so we never hard-exit on a closing socket.
+    process.stderr.write(red("error: ") + e.message + "\n");
+    process.exitCode = 1;
+  }
+})();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "proxychecker-dev",
+  "version": "1.0.0",
+  "description": "Fast proxy checker CLI. Test HTTP/HTTPS/SOCKS proxies for liveness, latency, anonymity, and datacenter-vs-residential type. Free, no signup.",
+  "type": "module",
+  "bin": {
+    "proxycheck": "bin/proxycheck.js",
+    "proxychecker-dev": "bin/proxycheck.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "proxy",
+    "proxy-checker",
+    "proxy-tester",
+    "proxy-validation",
+    "socks5",
+    "socks4",
+    "http-proxy",
+    "https-proxy",
+    "scraping",
+    "web-scraping",
+    "proxies",
+    "cli",
+    "residential-proxy",
+    "datacenter-proxy"
+  ],
+  "author": "Flash AI Solutions",
+  "license": "MIT",
+  "homepage": "https://proxychecker.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iFan6oy/proxychecker-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iFan6oy/proxychecker-cli/issues"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {}
+}