npm package: @mobileproxy/sdk
Description: Official Node.js SDK for MobileProxy.Space API — private mobile proxies on real GSM devices
Author: MobileProxy.Space
Latest version: 1.0.0

# MobileProxy.Space Node.js SDK

[![CI](https://github.com/mobileproxy/node-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/mobileproxy/node-sdk/actions/workflows/ci.yml)

Official Node.js SDK for the [MobileProxy.Space](https://mobileproxy.space) API — private mobile proxies on real GSM devices across 52 countries.

## Features

- **Full API coverage** — all endpoints wrapped in async methods with JSDoc
- **TypeScript declarations** included (`index.d.ts`)
- **Zero dependencies** — uses native `fetch` (Node.js 18+)
- **CJS + ESM** — works with `require()` and `import`
- **Typed errors** — `ApiError`, `AuthenticationError`, `RateLimitError`
- **IP rotation** — dedicated `changeIp()` with no rate limit

## Installation

```bash
npm install @mobileproxy/sdk
```

## Quick Start

```js
const MobileProxyClient = require('@mobileproxy/sdk');

const client = new MobileProxyClient('YOUR_API_TOKEN');

// Check balance
const balance = await client.getBalance();
console.log(balance);

// List active proxies
const proxies = await client.getMyProxy();

// Get current IP
const ip = await client.getProxyIp(12345);

// Rotate IP (no rate limit)
await client.changeIp('your_proxy_key');
```

### ESM

```js
import MobileProxyClient from '@mobileproxy/sdk';

const client = new MobileProxyClient('YOUR_API_TOKEN');
const balance = await client.getBalance();
```

## API Methods

### Proxy Information

| Method | Description |
|--------|-------------|
| `getProxyIp(proxyId, options?)` | Get current IP address of a proxy |
| `getMyProxy(proxyId?)` | List active proxies (all or specific) |
| `getIpStats()` | IP address statistics by GEO |

### Proxy Management

| Method | Description |
|--------|-------------|
| `changeProxyCredentials(proxyId, login, password)` | Change proxy login/password |
| `rebootProxy(proxyId)` | Restart the modem |
| `editProxy(proxyId, options?)` | Update proxy settings |
| `changeIp(proxyKey, options?)` | Rotate IP (no rate limit) |

### Equipment & GEO

| Method | Description |
|--------|-------------|
| `changeEquipment(proxyId, options?)` | Switch modem/SIM/operator/city |
| `getAvailableEquipment(proxyId, options?)` | List available equipment by GEO |
| `getGeoList(proxyId, geoId)` | Available GEOs for a proxy |
| `getOperators(geoId)` | Operators for a GEO |
| `getCountries(onlyAvailable?)` | List of countries |
| `getCities()` | List of cities |

### Blacklist

| Method | Description |
|--------|-------------|
| `getBlackList(proxyId)` | Get equipment/operator blacklist |
| `addOperatorToBlackList(proxyId, operatorId)` | Block an operator |
| `removeOperatorFromBlackList(proxyId, operatorId)` | Unblock an operator |
| `removeFromBlackList(proxyId, blackListId, eid)` | Remove equipment from blacklist |

### Purchasing & Billing

| Method | Description |
|--------|-------------|
| `buyProxy(options)` | Purchase a proxy |
| `refundProxy(proxyId)` | Request a refund |
| `getBalance()` | Account balance |
| `getPrices(countryId)` | Prices for a country |
| `getTestProxy(geoId, operator)` | Get a free 2-hour trial proxy |

### Utilities

| Method | Description |
|--------|-------------|
| `checkEquipmentAvailability(eid)` | Check if equipment is available |
| `viewUrlFromDifferentIps(url, countryId)` | Anti-cloaking: view URL from another country |
| `getTaskResult(taskId)` | Get async task result |

## Error Handling

```js
const { ApiError, AuthenticationError, RateLimitError } = require('@mobileproxy/sdk');

try {
  await client.getBalance();
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid API token
  } else if (err instanceof RateLimitError) {
    // Too many requests — back off and retry
  } else if (err instanceof ApiError) {
    console.error(err.message, err.httpCode, err.responseBody);
  }
}
```

## Configuration

```js
const client = new MobileProxyClient('YOUR_API_TOKEN', {
  timeout: 120000,  // request timeout in ms
  baseUrl: 'https://mobileproxy.space/api.html', // default
});
```

## Rate Limits

API requests are limited to **3 × (number of active proxies)** per second. For example, 10 proxies = 30 req/s. The `changeIp()` method uses a separate endpoint with **no rate limit**.

## Requirements

- Node.js 18 or higher (uses native `fetch`)

## Links

- [API Documentation](https://mobileproxy.space/en/user.html?api)
- [Dashboard](https://mobileproxy.space/en/user.html)
- [Website](https://mobileproxy.space)
- [PHP SDK](https://github.com/mobileproxy/php-sdk)
- [Chrome Extension](https://chromewebstore.google.com/detail/mobile-proxy-manager/lhbdhjhflkejgkkhlgacbaogbaaollac)

## License

MIT — see [LICENSE](LICENSE).