proxy-builder-sdk

A tiny, dependency-free Node/TypeScript SDK for aethyn.io residential proxies. Build correct proxy URLs with country / city / sticky-session / lifetime targeting and hand them straight to got, axios, fetch, Playwright, or Puppeteer — without hand-assembling fragile username strings.

npm install proxy-builder-sdk

import { AethynClient } from "proxy-builder-sdk";

const client = new AethynClient({ username: "aethyn-XXXXX", password: "secret" });
// or set AETHYN_USERNAME / AETHYN_PASSWORD

// rotating residential exit in the US
const p = client.proxy({ country: "us" });

const res = await fetch("https://api.ipify.org?format=json", {
  // node fetch via undici ProxyAgent, got { proxy: p.url }, axios, etc.
});

No hand-built aethyn-XXXXX-country-us-session-...-lifetime-... strings, no off-by-one dashes, no guessing the port. Ships types; works in ESM and CommonJS.

Why

Aethyn encodes targeting inside the proxy username — country, city, ISP, a sticky-session id, and a lifetime. It's powerful but easy to get subtly wrong (a stray - in a session id silently corrupts the whole thing, and city/ISP only work on the Elite tier). This SDK gives you a typed, validated API and keeps the wire format an internal detail, so if Aethyn ever changes the username scheme, you just upgrade the package — your code doesn't move.

Usage

Sticky sessions

Hold the same exit IP for a multi-step flow (login → cart → checkout):

const p = client.session({ country: "de", session: "cart42", ttl: 10 }); // same IP for 10 min
// p.username -> "aethyn-XXXXX-country-de-session-cart42-lifetime-10"

ttl is minutes (1–1440). Omit session for per-request rotation (the default).

City / ISP targeting (Elite tier)

const p = client.session({ country: "us", city: "chicago", isp: "comcast", session: "run1", ttl: 30, tier: "elite" });

city, state, isp, and zip are Elite-only — the SDK throws a clear error if you pass them on Premium.

got / axios

import got from "got";
const p = client.proxy({ country: "gb" });
await got("https://example.com", { proxy: p.url });

Playwright / Puppeteer

import { chromium } from "playwright";
const p = client.session({ country: "fr", session: "s1", ttl: 15, tier: "elite" });
const browser = await chromium.launch({ proxy: p.forPlaywright() });

SOCKS5

const p = client.proxy({ country: "jp", protocol: "socks5" }); // socks5://...@proxy.aethyn.io:1099

What you get back

const p = client.session({ country: "us", session: "run1", ttl: 10 });
p.username;         // "aethyn-XXXXX-country-us-session-run1-lifetime-10"
p.host; p.port;     // "proxy.aethyn.io", 2099
p.url;              // "http://aethyn-XXXXX-...:secret@proxy.aethyn.io:2099"
p.proxies;          // { http, https }
p.forPlaywright();  // { server, username, password }
String(p);          // password-redacted, safe to log

Ports are picked for you: Premium 2099 (HTTP) / 1099 (SOCKS5), Elite 5499 (HTTP) / 3499 (SOCKS5). Self-hosting or white-labeling? Pass new AethynClient({ ..., host: "gate.example.com" }).

Other providers

Aethyn is the default, but the same clean API drives other big residential providers too — use ProxyClient with a provider:

import { ProxyClient } from "proxy-builder-sdk";

// Oxylabs — the SDK emits customer-...-cc-us-sessid-run1-sesstime-10
const p = new ProxyClient({ username: "customer-me", password: "pw", provider: "oxylabs" })
  .session({ country: "us", session: "run1", ttl: 10 });

provider	gateway	notes
aethyn (default)	proxy.aethyn.io	Premium/Elite tiers, city/ISP/state/zip
brightdata	brd.superproxy.io	pass brd-customer-<id>-zone-<zone> as the username
oxylabs	pr.oxylabs.io	cc/sessid/sesstime; state as us_california
smartproxy / decodo	gate.decodo.com	sessionduration (minutes)
iproyal	geo.iproyal.com	targeting goes in the password
soax	proxy.soax.com	⚠️ community-verified; lifetime in seconds
netnut	gw.netnut.net	country + sticky session only

Every non-Aethyn dialect was verified against the provider's official docs (each provider file records the source URL + a confidence level). soax is medium confidence — sanity-check it against SOAX's current docs before you lean on it. Each provider maps the same semantic call (country, city, state, session, ttl) to its own username/password format and throws a clear error for anything it can't express.

Adding another proxy provider

Contributions of new providers are welcome. Most providers are a ~12-line dialect config — drop a file in src/providers/, register it, add one import line to src/providers/index.ts, and open a PR:

import { DialectProvider } from "./dialect";
import { registerProvider } from "./base";

registerProvider(new DialectProvider({
  name: "myprovider", display: "My Provider",
  host: "gateway.myprovider.com", httpPort: 8000, socks5Port: null,
  authIn: "username", delim: "-",
  keys: { country: "cc", session: "sess", ttl: "ttl" }, // our param -> their keyword
  order: ["country", "session", "ttl"],
  source: "https://docs.myprovider.com/...", confidence: "high",
}));

For anything that doesn't fit the dialect model, implement the one-method Provider interface directly. See CONTRIBUTING.md for the full walkthrough and PR checklist.

Links

• aethyn.io — residential proxies (Aethyn is the default provider)
• Docs: https://www.aethyn.io/docs
• Python version: proxy-builder-sdk on PyPI

License

MIT