FlashProxy SDK for Node.js / TypeScript

Official Node.js/TypeScript SDK for the FlashProxy Reseller API.

Installation

npm install @flashproxy/sdk

Quick Start

import { FlashProxyClient } from "@flashproxy/sdk";

const client = new FlashProxyClient("fp_live_your_api_key");

// Optionally target sandbox
const client = new FlashProxyClient("fp_test_your_api_key", {
  baseUrl: "https://rapi.flashproxy.com/sandbox/api/v1",
});

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (optional, types included)

API Reference

Balance

Get Balance

Returns your account's current balance, pre-paid allocations, and spending statistics.

const balance = await client.getBalance();

console.log(balance.balance_formatted);  // "$5,000.00"
console.log(balance.total_spent_cents);  // 150000

Get Transactions

Returns a paginated list of all balance transactions.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | page | integer | No | Page number (default: 1) | | perPage | integer | No | Items per page (default: 20, max: 100) | | type | string | No | Filter: topup, purchase, extend, refund, adjustment, all |

const result = await client.getTransactions(1, 50, "purchase");

for (const txn of result.items) {
  console.log(`${txn.type}: ${txn.amount_formatted}`);
}

Get Pricing

Returns the pricing configured for your reseller account.

const pricing = await client.getPricing();

console.log(pricing["residential-lite"].price_per_gb_cents);  // 50

Plans

List Plans

Returns a paginated list of all your proxy plans.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | page | integer | No | Page number | | perPage | integer | No | Items per page (max 100) | | status | string | No | Filter: active, expired, cancelled, all | | product | string | No | Filter by product type |

const result = await client.listPlans(1, 20, "active", "residential-lite");

for (const plan of result.items) {
  console.log(`${plan.plan_id} — ${plan.product} — ${plan.status}`);
}

Create Plan

Create a new proxy plan. Required parameters vary by product type. This deducts balance and returns a plan_id with connection credentials.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | product | string | Yes | Product type (e.g. residential-lite, residential, mobile, datacenter, etc.) | | bandwidth_gb | number | No | GB to purchase (required for bandwidth products) | | duration | string | No | Plan duration: trial, 1_day, 7_days, 14_days, 30_days, 60_days, 90_days | | billing_type | string | No | bandwidth or time (required for hybrid products) | | mbps | integer | No | Mbps for time-billed hybrid products | | bandwidth_mbps | integer | No | Bandwidth cap for unlimited_residential | | server_spec | string | No | Server spec: 8_16, 16_32, 32_64, 64_128 | | location | string | No | Location for dedicated_mobile: NL or UK | | quantity | integer | No | Number of IPs (required for dedicated_isp) | | pool | string | No | Pool name from GET /proxies/pools (required for dedicated_isp) | | end_user_reference | string | No | Your internal reference ID |

// Residential Lite — 10 GB
const plan = await client.createPlan({
  product: "residential-lite",
  bandwidth_gb: 10,
});
console.log(plan.plan_id);
console.log(plan.connection?.format);

// Datacenter — time-based, 100 Mbps, 7 days
const dc = await client.createPlan({
  product: "datacenter",
  billing_type: "time",
  duration: "7_days",
  mbps: 100,
});

// Dedicated ISP — 5 static IPs
const isp = await client.createPlan({
  product: "dedicated_isp",
  quantity: 5,
  pool: "ISP_US_SNEAKERS",
});

Get Plan

Retrieve full details for a specific plan by its ID.

const plan = await client.getPlan("3cd1f4b9-efc3-4252-b9f7-9cebc5236164");

console.log(plan.product);  // "residential-lite"
console.log(plan.status);   // "active"

Cancel Plan

Cancel an active plan immediately. No refund will be issued.

const result = await client.cancelPlan("3cd1f4b9-efc3-4252-b9f7-9cebc5236164");
console.log(result.status);  // "cancelled"

Extend Plan

Add bandwidth (GB) to bandwidth plans, or add days to time-based plans.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | add_bandwidth_gb | number | No | GB to add (for bandwidth plans) | | add_days | integer | No | Days to add (for time plans) |

// Add 5 GB to a bandwidth plan
const result = await client.extendPlan("abc-123", { add_bandwidth_gb: 5 });
console.log(result.cost_formatted);  // "$2.50"

// Add 7 days to a time plan
await client.extendPlan("abc-123", { add_days: 7 });

Upgrade Plan

Upgrade bandwidth or server spec for an unlimited_residential plan.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | bandwidth_mbps | integer | No | New Mbps: 200-1000 | | server_spec | string | No | New spec: 8_16, 16_32, 32_64, 64_128 |

const result = await client.upgradePlan("abc-123", {
  bandwidth_mbps: 1000,
  server_spec: "32_64",
});

Update Plan Password

Update the proxy authentication password for a plan.

const result = await client.updatePlanPassword("abc-123", "MyNewPass123");
console.log(result.proxy_password);

Get Plan Usage

Returns bandwidth usage for a specific plan.

const usage = await client.getPlanUsage("abc-123");
console.log(usage.usage.usage_percent);  // 25

Get Plan Proxies

Retrieve the list of static IPs for a dedicated_isp plan.

const proxies = await client.getPlanProxies("abc-123");

for (const p of proxies) {
  console.log(p.full);  // "user:[email protected]:10001"
}

Stock

Dedicated Mobile Stock

Check availability of dedicated mobile proxies by location.

const stock = await client.getDedicatedMobileStock();
console.log(stock.NL?.available);  // 19

Trial Stock

Check if trial servers are available for unlimited residential trials.

const stock = await client.getTrialStock();
if (stock.in_stock) console.log("Trial available!");

Servers

Get Server IP

Get the real IP of an unlimited_residential server. Wait 30-60 seconds after purchase.

const info = await client.getServerIp("abc-123");
console.log(info.real_ip);  // "43.153.88.155"

Get Server Stats

Returns CPU, memory, and network statistics for a dedicated server.

const stats = await client.getServerStats("abc-123");
console.log(stats.resources.cpu_percent);

Get Server Monitoring

Get detailed monitoring information for a dedicated server.

const monitoring = await client.getServerMonitoring("abc-123");

Restart Server

Restart an unlimited_residential or dedicated_mobile server. Expect 1-3 minutes downtime.

const result = await client.restartServer("abc-123");
console.log(result.message);

Rotate IP

Rotate the IP for a dedicated_mobile plan. New IP in 10-30 seconds. Min 30s between rotations.

const result = await client.rotateIp("abc-123");
console.log(result.message);

Geo Targeting

Get Countries

Get available countries for geo-targeting. Use in username: user-country-US

const countries = await client.getCountries("residential");

for (const c of countries) {
  console.log(`${c.name} (${c.iso_code})`);
}

Get States

Get states for a country. Use in username: user-country-US-state-CA

const states = await client.getStates("residential", "US");

Get Cities

Get cities for geo-targeting. Use: user-country-US-state-CA-city-losangeles

const cities = await client.getCities("residential", "US", "CA");

Get ASNs

Get available ASNs for mobile targeting. Use: user-country-US-asn-7922

const asns = await client.getAsns("US");

Usage

Usage Summary

Get aggregated usage summary across all plans.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | period | string | No | today, week, month, or all (default: month) |

const summary = await client.getUsageSummary("month");
console.log(summary.total_bytes_formatted);

Detailed Plan Usage

Get time-series usage data for a specific plan.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | granularity | string | No | hourly, daily, or weekly (default: daily) |

const usage = await client.getPlanUsageDetailed("abc-123", "hourly");

Real-time Usage

Get live bandwidth usage data across active plans.

const realtime = await client.getRealtimeUsage();

Proxies

Proxy Pool Stats

Get proxy pool statistics including total IPs and health status per product.

const stock = await client.getProxyStock();
console.log(stock.residential.total_ips);

Get ISP Pools

List available ISP and subnet pools for dedicated_isp purchases.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | type | string | No | Filter: isp or subnet | | country | string | No | Filter by country code (e.g. US) |

const pools = await client.getIspPools("isp", "US");

for (const p of pools) {
  console.log(`${p.title}: ${p.stock} available`);
}

Connection Info

Get proxy hostnames and ports for every product type.

const info = await client.getConnectionInfo();
console.log(info["residential-lite"]);

Get VPN Config

Download VPN configuration file for a plan.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | format | string | No | ovpn or wireguard (default: ovpn) |

const config = await client.getVpnConfig("abc-123", "wireguard");

Get IP Reset Link

Generate a one-time IP reset link for end-user self-service.

const result = await client.getIpResetLink("abc-123");
console.log(result.reset_link);

Sub-Users

List Sub-Users

Returns a paginated list of all sub-users.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | page | integer | No | Page number | | perPage | integer | No | Items per page | | status | string | No | Filter: active, suspended, all |

const result = await client.listSubUsers(1, 20, "active");

Create Sub-User

Create a new sub-user with optional initial balance.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | email | string | Yes | Sub-user email | | name | string | Yes | Sub-user name | | initial_balance_cents | integer | No | Starting balance in cents |

const user = await client.createSubUser({
  email: "[email protected]",
  name: "John Doe",
  initial_balance_cents: 10000,
});
console.log(user.api_key);  // "fp_sub_xxxx"

Get Sub-User

Get detailed information about a sub-user.

const user = await client.getSubUser("sub_abc123");

Update Sub-User

Update a sub-user's name, status, or add balance.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | No | New name | | status | string | No | active or suspended | | add_balance_cents | integer | No | Balance to add in cents |

const result = await client.updateSubUser("sub_abc123", {
  add_balance_cents: 5000,
});

Error Handling

All methods throw FlashProxyError on API errors:

import { FlashProxyClient, FlashProxyError } from "@flashproxy/sdk";

try {
  const plan = await client.createPlan({ product: "residential-lite", bandwidth_gb: 10 });
} catch (error) {
  if (error instanceof FlashProxyError) {
    console.error(`API Error ${error.statusCode}: ${error.message}`);
    console.error("Details:", error.details);
  }
}

Product Types

| Product | Billing | Description | |---------|---------|-------------| | residential-lite | Bandwidth (GB) | Affordable residential proxies | | residential | Bandwidth or Time | Premium residential proxies | | mobile | Bandwidth or Time | Mobile carrier proxies | | datacenter | Bandwidth or Time | Fast datacenter proxies | | shared_isp | Bandwidth | Shared ISP proxies | | ipv6-residential | Bandwidth | IPv6 residential proxies | | ipv6-datacenter | Bandwidth | IPv6 datacenter proxies | | unlimited_residential | Time + Mbps | Dedicated server with unlimited bandwidth | | dedicated_mobile | Time | Dedicated mobile proxy with IP rotation | | dedicated_isp | Static IPs | Dedicated ISP proxies (static IPs) |

Support

• Documentation: https://flashproxy.io/docs
• Email: [email protected]
• Issues: https://github.com/DevCa-IO/flashproxy_b2b_sdks/issues

License

Proprietary — see LICENSE for details.