Node.js SDK

The official ProxyHat Node.js SDK provides a modern, async/await interface for the ProxyHat API with full TypeScript support.

View on GitHub

Requirements

Node.js 18 or later

Installation

npm install proxyhat

Or with yarn:

yarn add proxyhat

Quick Start

const { ProxyHat } = require("proxyhat");

const client = new ProxyHat({ apiKey: "YOUR_API_KEY" });

// Get account info
const user = await client.auth.user();
console.log(`Email: ${user.email}`);
console.log(`Traffic balance: ${user.trafficBalance} bytes`);

// List sub-users
const subUsers = await client.subUsers.list();
for (const su of subUsers) {
  console.log(`${su.username} — ${su.trafficUsed} bytes used`);
}

ES Modules

import { ProxyHat } from "proxyhat";

const client = new ProxyHat({ apiKey: "YOUR_API_KEY" });

Sub-User Management

Create a Sub-User

const subUser = await client.subUsers.create({
  username: "user1",
  password: "securePass123",
  trafficLimit: 1073741824, // 1 GB
});
console.log(`Created: ${subUser.username}`);

Update a Sub-User

await client.subUsers.update(subUser.id, {
  trafficLimit: 2147483648, // 2 GB
});

Delete a Sub-User

await client.subUsers.delete(subUser.id);

Locations

// List available countries
const countries = await client.locations.countries();
for (const country of countries) {
  console.log(`${country.name}: ${country.proxyCount} proxies`);
}

// List cities in a country
const cities = await client.locations.cities({ countryCode: "US" });
for (const city of cities) {
  console.log(`${city.name}, ${city.region}`);
}

Proxy Presets

// Create a preset
const preset = await client.proxyPresets.create({
  name: "US Residential",
  countryCode: "US",
  connectionType: "residential",
});

// List presets
const presets = await client.proxyPresets.list();
for (const p of presets) {
  console.log(`${p.name}: ${p.countryCode}`);
}

Analytics

// Get traffic usage chart
const chart = await client.analytics.trafficChart({ period: "7d" });
for (const point of chart) {
  console.log(`${point.date}: ${point.bytesUsed} bytes`);
}

Error Handling

const { ProxyHatError, AuthenticationError, RateLimitError } = require("proxyhat");

try {
  const user = await client.auth.user();
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof ProxyHatError) {
    console.error(`API error: ${err.message}`);
  }
}

TypeScript

The SDK ships with built-in TypeScript declarations. All methods and response types are fully typed:

import { ProxyHat, SubUser, Country } from "proxyhat";

const client = new ProxyHat({ apiKey: "YOUR_API_KEY" });

const subUsers: SubUser[] = await client.subUsers.list();
const countries: Country[] = await client.locations.countries();