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

The SDK is installed directly from its GitHub repository (it is not published to the npm registry):

npm install ProxyHatCom/node-sdk

Or with yarn:

yarn add ProxyHatCom/node-sdk

The installed package name is proxyhat, so imports and require() calls use that name.

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.traffic.total_bytes} bytes`);

// List sub-users
const subUsers = await client.subUsers.list();
for (const su of subUsers) {
  console.log(`${su.username} — ${su.used_traffic} 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: 1000000000, // 1 GB
});
console.log(`Created: ${subUser.username}`);

Update a Sub-User

await client.subUsers.update(subUser.id, {
  trafficLimit: 2000000000, // 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();