Node.js & TypeScript proxy 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. Ships types; works in ESM and CommonJS.
Install
Add proxy-builder-sdk to your project.
npm install proxy-builder-sdknpm install aethyn-proxySame package, re-exported for backward compatibility. import { AethynClient } from "aethyn-proxy" still works.
The SDK picks the correct port from your tier and protocol automatically.
| Tier | HTTP | SOCKS5 |
|---|---|---|
| Premium | 2099 | 1099 |
| Elite | 5499 | 3499 |
White-label? Pass host: "gate.example.com" to the client constructor.
Usage
Copy-paste examples for common patterns.
import { AethynClient } from "proxy-builder-sdk";
const client = new AethynClient({ username: "aethyn-XXXXX", password: "PASSWORD" });
// or set AETHYN_USERNAME / AETHYN_PASSWORD
const p = client.proxy({ country: "us" });
// rotating residential exit in the US
const res = await fetch("https://api.ipify.org?format=json", {
// node fetch via undici ProxyAgent, got { proxy: p.url }, axios, etc.
});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).
const p = client.session({ country: "us", city: "chicago", isp: "comcast", session: "run1", ttl: 30, tier: "elite" });
// city, state, isp, and zip are Elite-only — SDK throws a clear error if you pass them on Premiumimport got from "got";
const p = client.proxy({ country: "gb" });
await got("https://example.com", { proxy: p.url });import { chromium } from "playwright";
const p = client.session({ country: "fr", session: "s1", ttl: 15, tier: "elite" });
const browser = await chromium.launch({ proxy: p.forPlaywright() });const p = client.proxy({ country: "jp", protocol: "socks5" });
// socks5://...@proxy.aethyn.io:1099const 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-...:PASSWORD@proxy.aethyn.io:2099"
p.proxies; // { http, https }
p.forPlaywright(); // { server, username, password }
String(p); // password-redacted, safe to logOther 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 and 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.
- Set AETHYN_USERNAME and AETHYN_PASSWORD env vars instead of hardcoding credentials.
- String(p) is safe to log — the password is redacted.
- Self-hosting or white-labeling? Pass host: "gate.example.com" to the client constructor.
FAQ
Do I need the SDK to use Aethyn?
What's the difference between proxy-builder-sdk and aethyn-proxy?
Which port does the SDK pick?
Can I use city or ISP targeting on Premium?
What is the ttl range for sticky sessions?
Does it support other proxy providers?
Docs, integrations & blog
License: MIT