NestProxy SDK

TypeScript SDK cho NestProxy Residential Proxy API.

Cài đặt

npm install @nestproxy/sdk

Sử dụng

import { NestProxySDK } from '@nestproxy/sdk';

const sdk = new NestProxySDK({
    apiKey: 'your-api-key-here', // Bắt buộc cho các hàm quản lý Key/User
    // baseUrl: 'https://nestproxy.com/',
});

// Hoặc khởi tạo không cần apiKey nếu chỉ dùng public endpoints
const publicSdk = new NestProxySDK();

// ── Provinces ──
const provinces = await sdk.getProvinces();
const filtered = await sdk.getProvinces('Hà Nội');

// ── Pricing ──
const pricing = await sdk.getPricing();

// ── Proxy Operations ──
const newIP = await sdk.getNewIP('your-proxy-key');
const newIPByProvince = await sdk.getNewIP('your-proxy-key', 1); // Hà Nội
const currentIP = await sdk.getCurrentIP('your-proxy-key');
const removed = await sdk.removeOldIP('your-proxy-key');

// ── Key Management ──
const keys = await sdk.getKeyList();
const detail = await sdk.getKeyDetail('proxy-key-uuid');
const newKeys = await sdk.buyKey({ keyType: 'NORMAL', quantity: 2, duration: 30 });
const renewed = await sdk.renewKey({ proxyKey: 'proxy-key-uuid', duration: 7 });
const deleted = await sdk.removeKey('proxy-key-uuid');

// ── User ──
const user = await sdk.getCurrentUser();

// ── History ──
const ipHistory = await sdk.getIpHistory();
const transactions = await sdk.getTransactions();
const buyOnly = await sdk.getTransactions('BUY');

Error Handling

import { NestProxySDK, NestProxyError } from '@nestproxy/sdk';

try {
    const proxy = await sdk.getNewIP('invalid-key');
} catch (err) {
    if (err instanceof NestProxyError) {
        console.error(err.statusCode); // 404
        console.error(err.message);    // 'Proxy key không hợp lệ'
    }
}

API Reference

| Method | Auth | Return Type | |--------|------|-------------| | getProvinces(search?) | Public | Province[] | | getPricing(domain?) | Public | PricingTier[] | | getNewIP(proxyKey, provinceId?) | Public | ProxyInfo | | getCurrentIP(proxyKey) | Public | ProxyInfo | | removeOldIP(proxyKey) | Public | RemoveIPResponse | | getKeyDetail(proxyKey) | Public | KeyDetail | | getKeyList() | 🔑 API Key | KeyDetail[] | | buyKey(params) | 🔑 API Key | KeyDetail[] | | renewKey(params) | 🔑 API Key | KeyDetail | | removeKey(proxyKey) | 🔑 API Key | RemoveKeyResponse | | getCurrentUser() | 🔑 API Key | UserInfo | | getIpHistory() | 🔑 API Key | IpHistoryEntry[] | | getTransactions(type?) | 🔑 API Key | Transaction[] |

Types

// ── Config ──
interface NestProxyConfig {
    apiKey?: string;    // optional for public endpoints
    baseUrl?: string;   // default: 'https://nestproxy.com/'
    timeout?: number;   // default: 30000ms
}

// ── Province ──
interface Province {
    id: number;
    name: string;       // "Thành phố Hà Nội"
    level: string;      // "Thành phố Trung ương" | "Tỉnh"
}

// ── Proxy ──
interface ProxyInfo {
    proxy: string;          // "103.1.1.2:8080"
    vip: boolean;
    canChangeAt: string;    // ISO timestamp
}

interface CurrentProxyInfo {
    proxy: string | null;
    vip?: boolean;
    message?: string;
    canChangeAt?: string | null;
}

// ── Key ──
type KeyType = 'NORMAL' | 'VIP' | 'VIP_1H';

interface KeyDetail {
    id: number;
    proxyKey: string;       // UUID
    keyType?: KeyType;
    isActive: boolean;
    expiredAt?: string;     // ISO date
    createdAt?: string;
}

interface BuyKeyParams {
    keyType: KeyType;
    quantity?: number;      // default: 1
    duration?: number;      // ngày, default: 1
}

interface RenewKeyParams {
    proxyKey: string;
    duration?: number;      // ngày, default: 1
}

// ── User ──
interface UserInfo {
    id: number;
    userName: string;
    email?: string;
    showName?: string;
    balance: number | string;
    role: string;
    apiKey?: string;
    phoneNumber?: string;
    avatar?: string;          // URL avatar
    createdAt?: string;       // ISO date
    paymentCode?: string;     // Mã nạp tiền
}

// ── History ──
interface IpHistoryEntry {
    id: number;
    proxyKey: string;
    ip: string;
    port: number;
    provinceId?: number;
    createdAt: string;
}

type TransactionType = 'BUY' | 'RENEW' | 'deposit';

interface Transaction {
    id: number;
    amount: number | string;
    quantity?: number;
    keyType?: string;
    status: string;
    description?: string;
    duration?: number;
    transactionType: TransactionType;
    createdAt: string;
}

// ── Pricing ──
interface PricingTier {
    id: number;
    keyType: string;
    duration: number;
    price: number | string;
}

// ── Responses ──
interface RemoveIPResponse   { message: string; success: boolean; released: number; }
interface RemoveKeyResponse  { message: string; success: boolean; }
interface RedeemGiftCodeResponse { success: boolean; amount: string; message: string; }

// ── Error ──
class NestProxyError extends Error {
    statusCode: number;
    error?: string;
}