### Install 3x-ui SDK

Source: https://github.com/mehdikhody/3x-ui-js/blob/master/README.md

Install the 3x-ui SDK using npm. This is the first step to integrate the SDK into your Node.js project.

```bash
npm install 3x-ui
```

--------------------------------

### Initialization - new XuiApi(uri)

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Constructs an SDK instance by parsing a connection URI. Allows configuration of debug logging and response caching TTL. Includes an example of checking panel health.

```APIDOC
## Initialization — `new XuiApi(uri)`

Constructs an SDK instance by parsing a connection URI that embeds credentials, host, port, and optional base path. All subsequent calls are made against this panel. Set `debug = true` for verbose logging and configure `stdTTL` (seconds) to control how long responses are cached before a fresh API call is made.

```typescript
import { XuiApi } from "3x-ui";

// URI format: http(s)://username:password@host:port/optional-base-path
const api = new XuiApi("http://admin:securepassword@192.168.1.100:2053/mybasepath");

api.debug = true;   // Enable detailed Winston logging (default: false)
api.stdTTL = 30;    // Cache responses for 30 seconds (default: 10)

// Verify panel connectivity — returns true if the panel is reachable and authenticated
const healthy = await api.checkHealth();
console.log("Panel healthy:", healthy); // Panel healthy: true
```
```

--------------------------------

### Get Online Clients

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Returns an array of email addresses for clients that are currently online. Results are cached within the TTL window. Returns an empty array if no clients are online.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const onlineEmails = await api.getOnlineClients();
console.log("Online clients:", onlineEmails.length);
console.log(onlineEmails.map(email => ` - ${email}`).join("\n"));
// Online clients: 2
//  - alice@example.com
//  - charlie@example.com
```

--------------------------------

### Get Client Protocol Options

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Retrieve detailed protocol-level options for a specific client, such as VMess, VLess, Trojan, or Shadowsocks. Useful for inspecting or modifying protocol-specific fields like `flow`, `tgId`, or `subId`. Requires the client's identifier.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const options = await api.getClientOptions("alice@example.com");
if (options && "id" in options) {
    // VMess or VLess client
    console.log("UUID:", options.id);
    console.log("IP limit:", options.limitIp);
    console.log("Total GB:", options.totalGB / 1073741824, "GB");
    console.log("Telegram ID:", options.tgId ?? "not set");
}
```

--------------------------------

### Get All Inbounds

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Retrieves the full list of all inbounds configured on the panel. Results are cached for efficiency. Each inbound object contains its Xray protocol settings, stream settings, port, enable state, traffic statistics, and client information.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const inbounds = await api.getInbounds();
for (const inbound of inbounds) {
    console.log(`[${inbound.id}] ${inbound.remark} — ${inbound.protocol} :${inbound.port}`);
    console.log(`  ↑ ${inbound.up} bytes  ↓ ${inbound.down} bytes  enabled: ${inbound.enable}`);
    console.log(`  Clients: ${inbound.clientStats.length}`);
}
// [1] My VMess — vmess :10001
//   ↑ 104857600 bytes  ↓ 2097152 bytes  enabled: true
//   Clients: 3
```

--------------------------------

### Get Client Associated IP Addresses

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Retrieve a list of IP addresses currently or recently associated with a client. The client can be identified by email or UUID/password. Returns an empty array if no IPs are recorded.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const ips = await api.getClientIps("alice@example.com");
if (ips.length === 0) {
    console.log("No IP records for this client.");
} else {
    console.log("Active IPs:", ips);
    // Active IPs: ["203.0.113.10", "198.51.100.45"]
}
```

--------------------------------

### Get Single Inbound by ID

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Fetches a specific inbound by its numeric ID. The result is cached after the first fetch. Returns the `Inbound` object or `null` if not found. Useful for retrieving details of a single inbound without loading the entire list.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const inbound = await api.getInbound(1);
if (!inbound) {
    console.error("Inbound not found");
    process.exit(1);
}

console.log("Remark:", inbound.remark);
console.log("Protocol:", inbound.protocol);
console.log("Port:", inbound.port);
console.log("Expiry:", inbound.expiryTime === 0 ? "Never" : new Date(inbound.expiryTime));
```

--------------------------------

### Import and Initialize 3x-ui SDK

Source: https://github.com/mehdikhody/3x-ui-js/blob/master/README.md

Import the XuiApi class from the '3x-ui' package and initialize it with the URL of your 3x-ui panel. Debug mode and cache TTL can also be configured during initialization.

```javascript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://username:password@localhost:2053");
api.debug = true; // Enables debug mode - defualt is false
api.stdTTL = 60; // Cache time in seconds - default is 10s
```

--------------------------------

### Initialize XuiApi Instance

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Constructs an SDK instance using a connection URI that includes credentials, host, port, and an optional base path. Enable debug logging and configure the cache TTL as needed. This snippet also demonstrates checking panel connectivity.

```typescript
import { XuiApi } from "3x-ui";

// URI format: http(s)://username:password@host:port/optional-base-path
const api = new XuiApi("http://admin:securepassword@192.168.1.100:2053/mybasepath");

api.debug = true;   // Enable detailed Winston logging (default: false)
api.stdTTL = 30;    // Cache responses for 30 seconds (default: 10)

// Verify panel connectivity — returns true if the panel is reachable and authenticated
const healthy = await api.checkHealth();
console.log("Panel healthy:", healthy); // Panel healthy: true
```

--------------------------------

### Fetch 3x-ui Data

Source: https://github.com/mehdikhody/3x-ui-js/blob/master/README.md

Utilize the initialized SDK to fetch various data points from the 3x-ui panel, such as inbounds, client statistics, and online clients.

```javascript
const inbounds = await api.getInbounds();
const clientStat = await api.getClient("email or clientId");
const clientOptions = await api.getClientOptions("email or clientId");
const onlines = await api.getOnlineClients();
```

--------------------------------

### sendBackup()

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Triggers the 3x-ui panel to send a database backup file to the configured Telegram bot. Returns `true` on success. Requires the panel's Telegram bot integration to be configured beforehand.

```APIDOC
## `sendBackup()`

### Description
Triggers the 3x-ui panel to send a database backup file to the configured Telegram bot. Returns `true` on success. Requires the panel's Telegram bot integration to be configured beforehand.

### Method
`sendBackup()`

### Returns
- `boolean`: `true` on success.
```

--------------------------------

### Create a new inbound with Xray configuration

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Use this to create a new inbound on the panel. Ensure all required fields in `InboundOptions` are provided. Returns the new `Inbound` object or `null` on failure.

```typescript
import { XuiApi } from "3x-ui";
import { randomUUID } from "crypto";

const api = new XuiApi("http://admin:pass@localhost:2053");

const newInbound = await api.addInbound({
    enable: true,
    remark: "Production VMess",
    listen: "0.0.0.0",
    port: 10010,
    protocol: "vmess",
    expiryTime: 0, // 0 = never expires
    settings: {
        decryption: "none",
        fallbacks: [],
        clients: [
            {
                id: randomUUID(),
                email: "alice@example.com",
                enable: true,
                expiryTime: 0,
                limitIp: 2,
                totalGB: 50 * 1073741824, // 50 GB in bytes
            },
        ],
    },
    streamSettings: {
        network: "ws",
        security: "tls",
        wsSettings: { path: "/ws" },
    },
    sniffing: {
        enabled: true,
        destOverride: ["http", "tls"],
    },
});

console.log("Created inbound ID:", newInbound?.id);
// Created inbound ID: 5
```

--------------------------------

### addInbound

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Creates a new inbound on the panel with the provided Xray configuration. Requires InboundOptions including protocol, settings, streamSettings, sniffing, enable, remark, listen, port, and expiryTime. Returns the newly created Inbound object or null on failure.

```APIDOC
## `addInbound(options: InboundOptions)`

Creates a new inbound on the panel with the provided Xray configuration. `InboundOptions` includes required fields: `protocol`, `settings`, `streamSettings`, `sniffing`, `enable`, `remark`, `listen`, `port`, and `expiryTime`. Returns the newly created `Inbound` object or `null` on failure.

```typescript
import { XuiApi } from "3x-ui";
import { randomUUID } from "crypto";

const api = new XuiApi("http://admin:pass@localhost:2053");

const newInbound = await api.addInbound({
    enable: true,
    remark: "Production VMess",
    listen: "0.0.0.0",
    port: 10010,
    protocol: "vmess",
    expiryTime: 0, // 0 = never expires
    settings: {
        decryption: "none",
        fallbacks: [],
        clients: [
            {
                id: randomUUID(),
                email: "alice@example.com",
                enable: true,
                expiryTime: 0,
                limitIp: 2,
                totalGB: 50 * 1073741824, // 50 GB in bytes
            },
        ],
    },
    streamSettings: {
        network: "ws",
        security: "tls",
        wsSettings: { path: "/ws" },
    },
    sniffing: {
        enabled: true,
        destOverride: ["http", "tls"],
    },
});

console.log("Created inbound ID:", newInbound?.id);
// Created inbound ID: 5
```
```

--------------------------------

### Configure Proxy Agent

Source: https://github.com/mehdikhody/3x-ui-js/blob/master/README.md

Specify proxy settings for the SDK's communication with the panel using environment variables like HTTP_PROXY and HTTPS_PROXY. Refer to the proxy-agent documentation for detailed configuration.

```env
HTTP_PROXY="http://proxy-server-over-tcp.com:3128"
HTTPS_PROXY="https://proxy-server-over-tls.com:3129"
```

--------------------------------

### Send Database Backup

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Triggers the 3x-ui panel to send a database backup file to the configured Telegram bot. Requires the panel's Telegram bot integration to be configured beforehand.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const sent = await api.sendBackup();
console.log("Backup dispatched via Telegram:", sent); // Backup dispatched via Telegram: true
```

--------------------------------

### getInbounds()

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Returns the full list of all inbounds configured on the panel. Results are cached. Each `Inbound` object includes its Xray protocol settings, stream settings, sniffing config, port, enable state, traffic stats, and an array of `clientStats`.

```APIDOC
## `getInbounds()`

Returns the full list of all inbounds configured on the panel. Results are cached; subsequent calls within the TTL window are served instantly from memory. Each `Inbound` object includes its Xray protocol settings, stream settings, sniffing config, port, enable state, traffic stats, and an array of `clientStats`.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const inbounds = await api.getInbounds();
for (const inbound of inbounds) {
    console.log(`[${inbound.id}] ${inbound.remark} — ${inbound.protocol} :${inbound.port}`);
    console.log(`  ↑ ${inbound.up} bytes  ↓ ${inbound.down} bytes  enabled: ${inbound.enable}`);
    console.log(`  Clients: ${inbound.clientStats.length}`);
}
// [1] My VMess — vmess :10001
//   ↑ 104857600 bytes  ↓ 2097152 bytes  enabled: true
//   Clients: 3
```
```

--------------------------------

### Clients API

Source: https://github.com/mehdikhody/3x-ui-js/blob/master/README.md

Functions for managing clients within the 3x-ui panel.

```APIDOC
## getClient(clientId: string)

### Description
Returns a client with the given `email` or `clientId`.

### Method
GET

### Endpoint
/clients/{clientId}

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The email or client ID of the client to retrieve.

### Response
#### Success Response (200)
- **client** (object) - The client object.
```

```APIDOC
## getClientIps(clientId: string)

### Description
Returns all client's IPs with the given `email` or `clientId`.

### Method
GET

### Endpoint
/clients/{clientId}/ips

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The email or client ID of the client.

### Response
#### Success Response (200)
- **ips** (array) - An array of client IP addresses.
```

```APIDOC
## getClientOptions(clientId: string)

### Description
Returns all client's options with the given `email` or `clientId`.

### Method
GET

### Endpoint
/clients/{clientId}/options

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The email or client ID of the client.

### Response
#### Success Response (200)
- **options** (object) - The client options.
```

```APIDOC
## addClient(inboundId: number, options: ClientOptions)

### Description
Adds a new client with the given options.

### Method
POST

### Endpoint
/inbounds/{inboundId}/clients

### Parameters
#### Path Parameters
- **inboundId** (number) - Required - The ID of the inbound to add the client to.

### Request Body
- **options** (ClientOptions) - Required - The options for the new client.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## updateClient(clientId: string, options: Partial<ClientOptions>)

### Description
Updates a client with the given `email` or `clientId`.

### Method
PUT

### Endpoint
/clients/{clientId}

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The email or client ID of the client to update.

### Request Body
- **options** (Partial<ClientOptions>) - Required - The partial options to update the client with.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## resetClientIps(clientId: string)

### Description
Resets all client's IPs with the given `email` or `clientId`.

### Method
POST

### Endpoint
/clients/{clientId}/reset/ips

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The email or client ID of the client.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## resetClientStat(clientId: string)

### Description
Resets a client's stat with the given `email` or `clientId`.

### Method
POST

### Endpoint
/clients/{clientId}/reset/stat

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The email or client ID of the client.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## deleteClient(clientId: string)

### Description
Deletes a client with the given `email` or `clientId`.

### Method
DELETE

### Endpoint
/clients/{clientId}

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The email or client ID of the client to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## deleteDepletedClients()

### Description
Deletes all clients that have depleted their traffic.

### Method
DELETE

### Endpoint
/clients/depleted

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## deleteInboundDepletedClients(inboundId: number)

### Description
Deletes all clients of an inbound that have depleted their traffic.

### Method
DELETE

### Endpoint
/inbounds/{inboundId}/clients/depleted

### Parameters
#### Path Parameters
- **inboundId** (number) - Required - The ID of the inbound whose depleted clients should be deleted.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## getOnlineClients()

### Description
Returns all online clients.

### Method
GET

### Endpoint
/clients/online

### Response
#### Success Response (200)
- **clients** (array) - An array of online client objects.
```

--------------------------------

### getClientOptions

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Retrieves the full protocol-level options for a specified client. This is useful for accessing or modifying protocol-specific fields like 'flow', 'tgId', or 'subId'.

```APIDOC
## getClientOptions(clientId: string)

### Description
Returns the full protocol-level options for a client (e.g. `ClientVmessOptions`, `ClientVlessOptions`, `ClientTrojanOptions`, or `ClientShadowsocksOptions`). This is distinct from `getClient`, which returns traffic stats. Useful when you need to read or update protocol-specific fields such as `flow`, `tgId`, or `subId`.

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The unique identifier for the client (e.g., email or UUID).

### Response
#### Success Response (200)
- **ClientOptions** - An object containing the client's protocol-level options.

### Request Example
```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const options = await api.getClientOptions("alice@example.com");
if (options && "id" in options) {
    // VMess or VLess client
    console.log("UUID:", options.id);
    console.log("IP limit:", options.limitIp);
    console.log("Total GB:", options.totalGB / 1073741824, "GB");
    console.log("Telegram ID:", options.tgId ?? "not set");
}
```
```

--------------------------------

### getClient

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Looks up a client by email or UUID/password (depending on protocol: id for VMess/VLess, password for Trojan/Shadowsocks). Returns a Client stat object containing traffic usage, expiry, and enable status, or null if not found. Falls back to scanning all inbounds when direct lookup returns nothing.

```APIDOC
## `getClient(clientId: string)`

Looks up a client by **email** or **UUID/password** (depending on protocol: `id` for VMess/VLess, `password` for Trojan/Shadowsocks). Returns a `Client` stat object containing traffic usage, expiry, and enable status, or `null` if not found. Falls back to scanning all inbounds when direct lookup returns nothing.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

// Lookup by email
const byEmail = await api.getClient("alice@example.com");
if (byEmail) {
    console.log("Email:", byEmail.email);
    console.log("Inbound ID:", byEmail.inboundId);
    console.log("Upload:", byEmail.up, "bytes");
    console.log("Download:", byEmail.down, "bytes");
    console.log("Enabled:", byEmail.enable);
    console.log("Expires:", byEmail.expiryTime === 0 ? "Never" : new Date(byEmail.expiryTime));
}

// Lookup by UUID (VMess/VLess)
const byUUID = await api.getClient("550e8400-e29b-41d4-a716-446655440000");
console.log("Found by UUID:", byUUID?.email);
```
```

--------------------------------

### Update Existing Client

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Modify an existing client's settings by providing partial updates. The client can be identified by email or UUID/password. The SDK fetches the current state, merges changes, and saves them. Returns the updated client statistics or null if not found.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

// Extend expiry and increase data cap — identify by email
const updated = await api.updateClient("bob@example.com", {
    expiryTime: Date.now() + 60 * 24 * 60 * 60 * 1000, // +60 days
    totalGB: 50 * 1073741824,
    tgId: 111222333,
});

console.log("Updated client:", updated?.email);

// Or identify by UUID
await api.updateClient("550e8400-e29b-41d4-a716-446655440000", {
    enable: false, // disable the client
});
```

--------------------------------

### addClient

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Adds a new client to an existing inbound connection. Supports various client types like VMess, VLess, Trojan, and Shadowsocks, with specific options for each.

```APIDOC
## addClient(inboundId: number, options: ClientOptions)

### Description
Adds a new client to an existing inbound. `ClientOptions` is a union type — pass `ClientVmessOptions` (with `id` UUID) for VMess/VLess inbounds, `ClientTrojanOptions` (with `password`) for Trojan, or `ClientShadowsocksOptions` for Shadowsocks. Returns the created `Client` stat object or `null` on failure.

### Parameters
#### Path Parameters
- **inboundId** (number) - Required - The ID of the inbound connection to which the client will be added.
- **options** (ClientOptions) - Required - The configuration options for the new client. This can be `ClientVmessOptions`, `ClientVlessOptions`, `ClientTrojanOptions`, or `ClientShadowsocksOptions`.

### Request Body
- **options.id** (string) - Required for VMess/VLess - The UUID for the client.
- **options.password** (string) - Required for Trojan - The password for the client.
- **options.email** (string) - Optional - The email address of the client.
- **options.enable** (boolean) - Optional - Whether the client is enabled.
- **options.expiryTime** (number) - Optional - The expiration timestamp for the client.
- **options.limitIp** (number) - Optional - The maximum number of IP addresses allowed for the client.
- **options.totalGB** (number) - Optional - The total data limit in bytes for the client.
- **options.flow** (string) - Optional - The flow type for VMess/VLess clients.
- **options.tgId** (number) - Optional - The Telegram ID associated with the client.

### Response
#### Success Response (200)
- **Client** - The created client stat object.
#### Failure Response (null)
- **null** - Returned if the client could not be added.

### Request Example
```typescript
import { XuiApi } from "3x-ui";
import { randomUUID } from "crypto";

const api = new XuiApi("http://admin:pass@localhost:2053");

// Add a VLess client to inbound ID 1
const client = await api.addClient(1, {
    id: randomUUID(),
    email: "bob@example.com",
    enable: true,
    expiryTime: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days from now
    limitIp: 3,
    totalGB: 20 * 1073741824, // 20 GB
    flow: "xtls-rprx-vision",
    tgId: 987654321,
});

console.log("New client email:", client?.email);   // New client email: bob@example.com
console.log("New client inbound:", client?.inboundId); // New client inbound: 1
```
```

--------------------------------

### updateClient

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Updates an existing client's configuration using partial option overrides. The client can be identified by email or UUID/password.

```APIDOC
## updateClient(clientId: string, options: Partial<ClientOptions>)

### Description
Updates a client identified by email or UUID/password with partial option overrides. The SDK fetches the current client state, merges the provided fields, and posts the update. Returns the updated `Client` stat or `null` if the client is not found.

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The identifier for the client (email or UUID/password).
- **options** (Partial<ClientOptions>) - Required - An object containing the fields to update. Only provided fields will be changed.

### Request Body
- **options.expiryTime** (number) - Optional - New expiration timestamp.
- **options.totalGB** (number) - Optional - New total data limit in bytes.
- **options.tgId** (number) - Optional - New Telegram ID.
- **options.enable** (boolean) - Optional - New enable status.

### Response
#### Success Response (200)
- **Client** - The updated client stat object.
#### Not Found Response (null)
- **null** - Returned if the client with the specified `clientId` is not found.

### Request Example
```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

// Extend expiry and increase data cap — identify by email
const updated = await api.updateClient("bob@example.com", {
    expiryTime: Date.now() + 60 * 24 * 60 * 60 * 1000, // +60 days
    totalGB: 50 * 1073741824,
    tgId: 111222333,
});

console.log("Updated client:", updated?.email);

// Or identify by UUID
await api.updateClient("550e8400-e29b-41d4-a716-446655440000", {
    enable: false, // disable the client
});
```
```

--------------------------------

### Look up a client by email or UUID/password

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Retrieves a client's statistics, expiry, and status using their email or protocol-specific identifier (UUID for VMess/VLess, password for Trojan/Shadowsocks). Returns a `Client` stat object or `null` if not found. Scans all inbounds if direct lookup fails.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

// Lookup by email
const byEmail = await api.getClient("alice@example.com");
if (byEmail) {
    console.log("Email:", byEmail.email);
    console.log("Inbound ID:", byEmail.inboundId);
    console.log("Upload:", byEmail.up, "bytes");
    console.log("Download:", byEmail.down, "bytes");
    console.log("Enabled:", byEmail.enable);
    console.log("Expires:", byEmail.expiryTime === 0 ? "Never" : new Date(byEmail.expiryTime));
}

// Lookup by UUID (VMess/VLess)
const byUUID = await api.getClient("550e8400-e29b-41d4-a716-446655440000");
console.log("Found by UUID:", byUUID?.email);
```

--------------------------------

### Add New Client to Inbound

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Add a new client to an existing inbound connection. Supports various client types by passing appropriate `ClientOptions` (e.g., `ClientVmessOptions`, `ClientTrojanOptions`). Returns the created client's statistics or null if creation fails. Requires inbound ID and client configuration.

```typescript
import { XuiApi } from "3x-ui";
import { randomUUID } from "crypto";

const api = new XuiApi("http://admin:pass@localhost:2053");

// Add a VLess client to inbound ID 1
const client = await api.addClient(1, {
    id: randomUUID(),
    email: "bob@example.com",
    enable: true,
    expiryTime: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days from now
    limitIp: 3,
    totalGB: 20 * 1073741824, // 20 GB
    flow: "xtls-rprx-vision",
    tgId: 987654321,
});

console.log("New client email:", client?.email);   // New client email: bob@example.com
console.log("New client inbound:", client?.inboundId); // New client inbound: 1
```

--------------------------------

### Other Functions

Source: https://github.com/mehdikhody/3x-ui-js/blob/master/README.md

Miscellaneous functions available in the SDK.

```APIDOC
## sendBackup()

### Description
Sends a backup file via the Telegram bot.

### Method
POST

### Endpoint
/backup

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

--------------------------------

### deleteDepletedClients()

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Removes all clients across all inbounds whose traffic allowance has been fully consumed. Returns `true` on success. Ideal for automated housekeeping in subscription-based proxy services.

```APIDOC
## `deleteDepletedClients()`

### Description
Removes all clients across all inbounds whose traffic allowance has been fully consumed. Returns `true` on success. Ideal for automated housekeeping in subscription-based proxy services.

### Method
`deleteDepletedClients()`

### Returns
- `boolean`: `true` on success.
```

--------------------------------

### Reset traffic statistics for all inbounds

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Resets upload and download counters for all inbounds simultaneously. Returns `true` on success. Useful for monthly traffic resets.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const result = await api.resetInboundsStat();
console.log("All inbound stats reset:", result); // All inbound stats reset: true
```

--------------------------------

### getClientIps

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Retrieves a list of IP addresses currently or recently associated with a specific client. The client can be identified by email or UUID/password.

```APIDOC
## getClientIps(clientId: string)

### Description
Returns the list of IP addresses currently or recently associated with a client. Accepts email or UUID/password. Returns an empty array if there are no recorded IPs.

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The identifier for the client (email or UUID/password).

### Response
#### Success Response (200)
- **string[]** - An array of IP addresses associated with the client. Returns an empty array if none are found.

### Request Example
```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const ips = await api.getClientIps("alice@example.com");
if (ips.length === 0) {
    console.log("No IP records for this client.");
} else {
    console.log("Active IPs:", ips);
    // Active IPs: ["203.0.113.10", "198.51.100.45"]
}
```
```

--------------------------------

### resetInboundsStat

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Resets traffic statistics (upload/download counters) for all inbounds at once. Returns true on success. Useful for monthly traffic resets or billing cycles.

```APIDOC
## `resetInboundsStat()`

Resets traffic statistics (upload/download counters) for **all** inbounds at once. Returns `true` on success. Useful for monthly traffic resets or billing cycles.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const result = await api.resetInboundsStat();
console.log("All inbound stats reset:", result); // All inbound stats reset: true
```
```

--------------------------------

### getOnlineClients()

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Returns an array of email addresses for clients that are currently online (actively tunneling traffic). Results are cached within the TTL window. Returns an empty array if no clients are online.

```APIDOC
## `getOnlineClients()`

### Description
Returns an array of email addresses for clients that are currently online (actively tunneling traffic). Results are cached within the TTL window. Returns an empty array if no clients are online.

### Method
`getOnlineClients()`

### Returns
- `string[]`: An array of email addresses of online clients, or an empty array if none are online.
```

--------------------------------

### Inbounds API

Source: https://github.com/mehdikhody/3x-ui-js/blob/master/README.md

Functions for managing inbounds within the 3x-ui panel.

```APIDOC
## getInbounds()

### Description
Returns an array of all inbounds.

### Method
GET

### Endpoint
/inbounds

### Response
#### Success Response (200)
- **inbounds** (array) - An array of inbound objects.
```

```APIDOC
## getInbound(id: number)

### Description
Returns the inbound with the specified ID.

### Method
GET

### Endpoint
/inbounds/{id}

### Parameters
#### Path Parameters
- **id** (number) - Required - The ID of the inbound to retrieve.

### Response
#### Success Response (200)
- **inbound** (object) - The inbound object with the specified ID.
```

```APIDOC
## addInbound(options: InboundOptions)

### Description
Adds a new inbound with the provided options.

### Method
POST

### Endpoint
/inbounds

### Request Body
- **options** (InboundOptions) - Required - The options for the new inbound.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## updateInbound(id: number, options: Partial<InboundOptions>)

### Description
Updates the inbound with the specified ID using the provided options.

### Method
PUT

### Endpoint
/inbounds/{id}

### Parameters
#### Path Parameters
- **id** (number) - Required - The ID of the inbound to update.

### Request Body
- **options** (Partial<InboundOptions>) - Required - The partial options to update the inbound with.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## resetInboundsStat()

### Description
Resets statistics for all inbounds.

### Method
POST

### Endpoint
/inbounds/reset/all

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## resetInboundStat(id: number)

### Description
Resets statistics for the inbound with the specified ID.

### Method
POST

### Endpoint
/inbounds/reset/{id}

### Parameters
#### Path Parameters
- **id** (number) - Required - The ID of the inbound to reset statistics for.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

```APIDOC
## deleteInbound(id: number)

### Description
Deletes the inbound with the specified ID.

### Method
DELETE

### Endpoint
/inbounds/{id}

### Parameters
#### Path Parameters
- **id** (number) - Required - The ID of the inbound to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

--------------------------------

### resetClientIps

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Clears all stored IP address records for a given client. This is useful for allowing a client to reconnect from a new location when IP-lock is enforced.

```APIDOC
## resetClientIps(clientId: string)

### Description
Clears all stored IP records for a client. Returns `true` on success. Useful for allowing a client to reconnect from a new location when IP-lock is enforced.

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The identifier for the client (email or UUID/password).

### Response
#### Success Response (true)
- **true** - Indicates that the IP records were successfully cleared.

### Request Example
```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const cleared = await api.resetClientIps("alice@example.com");
console.log("IPs cleared:", cleared); // IPs cleared: true
```
```

--------------------------------

### Reset Client Traffic Statistics

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Reset the upload and download traffic counters for a single client, identified by email or UUID/password. Returns `true` on success. Commonly used when renewing subscription periods or for troubleshooting.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const reset = await api.resetClientStat("alice@example.com");
console.log("Traffic reset:", reset); // Traffic reset: true

const refreshed = await api.getClient("alice@example.com");
console.log("Upload after reset:", refreshed?.up);   // 0
console.log("Download after reset:", refreshed?.down); // 0
```

--------------------------------

### Update an existing inbound configuration

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Merges partial `InboundOptions` onto an existing inbound. Only specified fields are changed, preserving others. Returns the updated `Inbound` or `null` if not found.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

// Disable the inbound and rename it
const updated = await api.updateInbound(5, {
    enable: false,
    remark: "Production VMess (Disabled)",
});

if (updated) {
    console.log("Updated remark:", updated.remark);
    console.log("Enabled:", updated.enable);
}
// Updated remark: Production VMess (Disabled)
// Enabled: false
```

--------------------------------

### flushCache()

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Immediately invalidates all cached inbound and client data. This is useful after external modifications to the panel state or to force a fresh read.

```APIDOC
## `flushCache()`

Immediately invalidates all cached inbound and client data. Call this after any external modification to the panel state not done through this SDK instance, or to force a fresh read on the next API call.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const inboundsBefore = await api.getInbounds(); // fetched from API, result cached
const inboundsFromCache = await api.getInbounds(); // served from cache

api.flushCache(); // invalidate everything

const inboundsAfterFlush = await api.getInbounds(); // fetched fresh from API
console.log("Total inbounds:", inboundsAfterFlush.length);
```
```

--------------------------------

### resetClientStat

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Resets the upload and download traffic counters for a specific client. The client can be identified by email or UUID/password.

```APIDOC
## resetClientStat(clientId: string)

### Description
Resets the upload/download traffic counter for a single client, identified by email or UUID/password. Returns `true` on success. Often used when renewing a subscription period.

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The identifier for the client (email or UUID/password).

### Response
#### Success Response (true)
- **true** - Indicates that the traffic counters were successfully reset.

### Request Example
```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const reset = await api.resetClientStat("alice@example.com");
console.log("Traffic reset:", reset); // Traffic reset: true

const refreshed = await api.getClient("alice@example.com");
console.log("Upload after reset:", refreshed?.up);   // 0
console.log("Download after reset:", refreshed?.down); // 0
```
```

--------------------------------

### Delete All Depleted Clients

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Removes all clients across all inbounds whose traffic allowance has been fully consumed. Ideal for automated housekeeping in subscription-based proxy services.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const result = await api.deleteDepletedClients();
console.log("Depleted clients cleaned up:", result); // Depleted clients cleaned up: true
```

--------------------------------

### updateInbound

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Merges partial InboundOptions onto an existing inbound and persists the change. Only the supplied fields are changed; all other existing settings are preserved. Flushes the cache and returns the updated Inbound or null if not found.

```APIDOC
## `updateInbound(id: number, options: Partial<InboundOptions>)`

Merges partial `InboundOptions` onto an existing inbound and persists the change. Only the supplied fields are changed; all other existing settings are preserved. Flushes the cache and returns the updated `Inbound` or `null` if not found.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

// Disable the inbound and rename it
const updated = await api.updateInbound(5, {
    enable: false,
    remark: "Production VMess (Disabled)",
});

if (updated) {
    console.log("Updated remark:", updated.remark);
    console.log("Enabled:", updated.enable);
}
// Updated remark: Production VMess (Disabled)
// Enabled: false
```
```

--------------------------------

### deleteInbound

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Permanently removes an inbound and all its associated clients from the panel. Returns true on success and false on failure. The cache is flushed automatically after deletion.

```APIDOC
## `deleteInbound(id: number)`

Permanently removes an inbound and all its associated clients from the panel. Returns `true` on success and `false` on failure. The cache is flushed automatically after deletion.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const deleted = await api.deleteInbound(5);
console.log("Deleted:", deleted); // Deleted: true

// Verify it is gone
const check = await api.getInbound(5);
console.log("Still exists:", check !== null); // Still exists: false
```
```

--------------------------------

### getInbound(id: number)

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Fetches a single inbound by its numeric ID. Returns the `Inbound` object (cached after first fetch) or `null` if not found. Useful when only a specific inbound's details are needed.

```APIDOC
## `getInbound(id: number)`

Fetches a single inbound by its numeric ID. Returns the `Inbound` object (cached after first fetch) or `null` if not found. Useful when only a specific inbound's details are needed without loading the full list.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const inbound = await api.getInbound(1);
if (!inbound) {
    console.error("Inbound not found");
    process.exit(1);
}

console.log("Remark:", inbound.remark);
console.log("Protocol:", inbound.protocol);
console.log("Port:", inbound.port);
console.log("Expiry:", inbound.expiryTime === 0 ? "Never" : new Date(inbound.expiryTime));
```
```

--------------------------------

### Reset Client IP Records

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Clear all stored IP address records for a specific client, identified by email or UUID/password. Returns `true` on success. This is useful for enforcing IP-lock policies and allowing reconnections from new locations.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const cleared = await api.resetClientIps("alice@example.com");
console.log("IPs cleared:", cleared); // IPs cleared: true
```

--------------------------------

### Reset traffic statistics for a single inbound

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Resets traffic statistics for all clients of a specific inbound, identified by its ID. Returns `true` on success.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const result = await api.resetInboundStat(1);
console.log("Inbound 1 stat reset:", result); // Inbound 1 stat reset: true
```

--------------------------------

### Delete Depleted Clients for a Specific Inbound

Source: https://context7.com/mehdikhody/3x-ui-js/llms.txt

Removes all traffic-depleted clients from a specific inbound only. Returns `true` on success.

```typescript
import { XuiApi } from "3x-ui";

const api = new XuiApi("http://admin:pass@localhost:2053");

const result = await api.deleteInboundDepletedClients(1);
console.log("Inbound 1 depleted clients removed:", result);
```