x3ui-api 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 # x3ui-api
 
-A Node.js client for interacting with the x3ui panel API.
+A Node.js client for interacting with the x3ui panel API. This library provides a simple interface to manage X-UI inbounds, clients, and system statistics.
 
 ## Installation
 
@@ -8,6 +8,311 @@ A Node.js client for interacting with the x3ui panel API.
 npm install x3ui-api
 ```
 
+## Features
+
+- Authentication with x3ui panel
+- Get system statistics (CPU, memory, network, etc.)
+- Manage inbounds (list, add, update, delete)
+- Protocol-specific builders with fluent API:
+  - VLESS with Reality support
+  - VMess with HTTP Upgrade support
+- Client management with fluent API
+- TypeScript support
+
+## Usage
+
+### Basic Usage
+
+```javascript
+const X3UIClient = require('x3ui-api');
+
+// Initialize client
+const client = new X3UIClient({
+  baseURL: 'http://your-x3ui-panel.com:54321',
+  parseJSONSettings: true // Default: true - automatically parse JSON settings
+});
+
+// Login to panel
+async function main() {
+  try {
+    const loginResult = await client.login('admin', 'password');
+    console.log('Login successful:', loginResult.success);
+    
+    // Get system stats
+    const stats = await client.getSystemStats();
+    console.log('CPU Usage:', stats.cpu + '%');
+    console.log('Memory:', Math.round(stats.mem.current / stats.mem.total * 100) + '%');
+    
+    // List all inbounds
+    const inbounds = await client.getInbounds();
+    console.log('Inbounds:', inbounds.length);
+    
+    // First inbound details
+    if (inbounds.length > 0) {
+      console.log('First inbound:', inbounds[0].remark);
+      console.log('Protocol:', inbounds[0].protocol);
+      console.log('Port:', inbounds[0].port);
+    }
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+main();
+```
+
+### Creating a VMess Inbound
+
+The library provides a convenient builder pattern for creating VMess inbounds with HTTP Upgrade:
+
+```javascript
+const X3UIClient = require('x3ui-api');
+const vmess = require('x3ui-api/src/protocols/vmess');
+
+const client = new X3UIClient({
+  baseURL: 'http://your-x3ui-panel.com:54321'
+});
+
+async function createVmessInbound() {
+  try {
+    await client.login('admin', 'password');
+    
+    // Create a VMess inbound builder
+    let builder = new vmess.VmessBuilder(client)
+      .setRemark('My VMess Inbound')
+      .setPort(8443) // Optional, will auto-generate if not provided
+      .setHttpUpgradeHost('your-domain.com');
+    
+    // Add a client
+    builder.addClient()
+      .setEmail('user@example.com')
+      .setTotalGB(100) // 100 GB traffic limit
+      .setExpiryTime(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days
+    
+    // Build and add the inbound
+    const inbound = await builder.build();
+    const createdInbound = await client.addInbound(inbound);
+    
+    // Update the builder with the server-returned inbound to get all metrics and IDs
+    builder = new vmess.VmessBuilder(client, createdInbound);
+    
+    console.log('Inbound created:', createdInbound);
+    
+    // Get connection link for the client (now with accurate server-assigned values)
+    const link = builder.getClientLink(0, 'your-server-ip.com');
+    console.log('Client connection link:', link);
+  } catch (error) {
+    console.error('Error creating inbound:', error.message);
+  }
+}
+
+createVmessInbound();
+```
+
+### Creating a VLESS Reality Inbound
+
+The library provides a convenient builder pattern for creating Reality inbounds:
+
+```javascript
+const X3UIClient = require('x3ui-api');
+const vless = require('x3ui-api/src/protocols/vless');
+
+const client = new X3UIClient({
+  baseURL: 'http://your-x3ui-panel.com:54321'
+});
+
+async function createRealityInbound() {
+  try {
+    await client.login('admin', 'password');
+    
+    // Create a Reality inbound builder
+    let builder = new vless.RealityBuilder(client, {
+      remark: 'My Reality Inbound',
+      port: 8443 // Optional, will auto-generate if not provided
+    });
+    
+    // Configure Reality settings
+    builder
+      .setDest('yahoo.com:443')
+      .setServerNames(['yahoo.com', 'www.yahoo.com'])
+      .setFingerprint('chrome');
+    
+    // Add a client
+    builder.addClient()
+      .setEmail('user@example.com')
+      .setTotalGB(100) // 100 GB traffic limit
+      .setExpiryTime(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days
+    
+    // Build and add the inbound
+    const inbound = await builder.build();
+    const createdInbound = await client.addInbound(inbound);
+    
+    // Update the builder with the server-returned inbound to get all metrics and IDs
+    builder = new vless.RealityBuilder(client, createdInbound);
+    
+    console.log('Inbound created:', createdInbound);
+    
+    // Get connection link for the client (now with accurate server-assigned values)
+    const link = builder.getClientLink(0, 'your-server-ip.com');
+    console.log('Client connection link:', link);
+  } catch (error) {
+    console.error('Error creating inbound:', error.message);
+  }
+}
+```
+
+### Real-World Example
+
+Here's a complete example showing how to create a VMess inbound and get the client link:
+
+```javascript
+const X3UIClient = require('x3ui-api');
+const vmess = require('x3ui-api/src/protocols/vmess');
+
+const client = new X3UIClient({
+    baseURL: 'https://your-panel-url.com/path/',
+});
+
+(async () => {
+    await client.login('username', 'password');
+
+    // Create VMess builder with HTTP Upgrade
+    let vmessBuilder = new vmess.VmessBuilder(client)
+        .setRemark("My VMess Inbound")
+        .setHttpUpgradeHost("your-domain.com");
+
+    // Add the inbound to the server
+    const vmessInbound = await client.addInbound(await vmessBuilder.build());
+    
+    // Create a new builder with the server-returned inbound to get accurate client links
+    vmessBuilder = new vmess.VmessBuilder(client, vmessInbound);
+    
+    // Generate and output the client connection link
+    console.log(vmessBuilder.getClientLink(0, "your-domain.com"));
+})();
+```
+
+### Managing Existing Inbounds
+
+```javascript
+async function manageInbounds() {
+  try {
+    // Get all inbounds
+    const inbounds = await client.getInbounds();
+    
+    if (inbounds.length > 0) {
+      // Get the first inbound
+      const inbound = inbounds[0];
+      const inboundId = inbound.id;
+      
+      // IMPORTANT: When updating an inbound, always start with the complete inbound object
+      // to avoid losing data, then modify only what you need to change
+      
+      // Example 1: Update the remark and enable status
+      inbound.remark = 'Updated Inbound Name';
+      inbound.enable = true;
+      
+      // Send the complete updated inbound back to the server
+      await client.updateInbound(inboundId, inbound);
+      
+      // Example 2: Add a new client to an existing inbound
+      if (inbound.protocol === 'vmess') {
+        // Create a builder with the existing inbound
+        const builder = new vmess.VmessBuilder(client, inbound);
+        
+        // Add a new client
+        builder.addClient()
+          .setEmail('newuser@example.com')
+          .setTotalGB(50);
+        
+        // Build the updated inbound and send it to the server
+        const updatedInbound = await builder.build();
+        await client.updateInbound(inboundId, updatedInbound);
+        
+        // Get the link for the new client
+        const link = builder.getClientLink(builder.clients.length - 1, 'your-server-ip.com');
+        console.log('New client link:', link);
+      }
+      
+      // Example 3: Delete an inbound
+      await client.deleteInbound(inboundId);
+    }
+  } catch (error) {
+    console.error('Error managing inbounds:', error.message);
+  }
+}
+```
+
+## API Reference
+
+### X3UIClient
+
+#### Constructor
+
+```javascript
+new X3UIClient({
+  baseURL: string,       // Required: URL to your x3ui panel
+  token?: string,        // Optional: Authentication token (if already logged in)
+  parseJSONSettings?: boolean // Optional: Auto-parse JSON settings (default: true)
+})
+```
+
+#### Methods
+
+- `login(username: string, password: string)` - Authenticate with the panel
+- `getSystemStats()` - Get system statistics
+- `getInbounds()` - Get all configured inbounds
+- `addInbound(config)` - Add a new inbound and returns the created inbound with server-assigned values
+- `updateInbound(id, config)` - Update an existing inbound with the complete inbound configuration
+- `deleteInbound(id)` - Delete an inbound
+- `getNewX25519Cert()` - Generate a new X25519 certificate
+
+### Protocol Builders
+
+The library provides protocol-specific builders for creating different types of inbounds:
+
+#### VMess Builder
+
+```javascript
+const vmess = require('x3ui-api/src/protocols/vmess');
+const builder = new vmess.VmessBuilder(client, options);
+```
+
+Methods:
+- `setPort(port)` - Set the port for the inbound
+- `setRemark(remark)` - Set the name/remark for the inbound
+- `setNetwork(network)` - Set the network type (default: 'httpupgrade')
+- `setSecurity(security)` - Set the security type (default: 'none')
+- `setHttpUpgradePath(path)` - Set the HTTP upgrade path
+- `setHttpUpgradeHost(host)` - Set the HTTP upgrade host
+- `setSniffing(enabled, destOverride, metadataOnly, routeOnly)` - Configure sniffing
+- `setListenIP(ip)` - Set listen IP address
+- `setExpiryTime(timestamp)` - Set inbound expiry time
+- `addClient(options)` - Add a new client to the inbound
+- `getClientLink(clientIndex, host, port)` - Get connection link for a client
+- `build()` - Build the final inbound config
+
+#### VLESS Reality Builder
+
+```javascript
+const vless = require('x3ui-api/src/protocols/vless');
+const builder = new vless.RealityBuilder(client, options);
+```
+
+Methods:
+- `setPort(port)` - Set the port for the inbound
+- `setRemark(remark)` - Set the name/remark for the inbound
+- `setDest(dest)` - Set the destination address (e.g., "yahoo.com:443")
+- `setServerNames(names)` - Set server names for SNI
+- `setKeyPair(privateKey, publicKey)` - Set Reality keypair
+- `setShortIds(ids)` - Set short IDs for Reality
+- `setFingerprint(fingerprint)` - Set browser fingerprint
+- `setListenIP(ip)` - Set listen IP address
+- `setExpiryTime(timestamp)` - Set inbound expiry time
+- `addClient(options)` - Add a new client to the inbound
+- `getClientLink(clientIndex, host)` - Get connection link for a client
+- `build()` - Build the final inbound config
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x3ui-api",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "API client for x3ui panel",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -11,7 +11,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.6.5",
+    "axios": "^1.8.2",
     "form-data": "^4.0.0"
   },
   "devDependencies": {

package/src/core/ClientBuilder.d.ts

@@ -0,0 +1,37 @@
+import {ClientSettings, InboundConfig} from "../index";
+import InboundBuilder from "./IndoundBuilder";
+
+export default class ClientBuilder {
+    
+    constructor(parent: InboundBuilder | InboundConfig);
+    
+    /**
+     * Set client UUID. If not provided, will be auto-generated
+     */
+    setId(id: string): this;
+
+    /**
+     * Set client email
+     */
+    setEmail(email: string): this;
+
+    /**
+     * Set total traffic limit in GB
+     */
+    setTotalGB(gb: number): this;
+
+    /**
+     * Set expiry time in unix timestamp
+     */
+    setExpiryTime(timestamp: number): this;
+
+    /**
+     * Set Telegram ID
+     */
+    setTgId(id: string): this;
+
+    /**
+     * Build the client configuration
+     */
+    build(): ClientSettings;
+}

package/src/core/ClientBuilder.js

@@ -0,0 +1,57 @@
+const crypto = require("crypto");
+
+module.exports = class ClientBuilder {
+    constructor(parent) {
+        this.parent = parent;
+        this.id = '';
+        this.flow = '';
+        this.email = '';
+        this.limitIp = 0;
+        this.totalGB = 0;
+        this.expiryTime = 0;
+        this.enable = true;
+        this.tgId = '';
+        this.subId = '';
+        this.reset = 0;
+    }
+
+    setId(id) {
+        this.id = id;
+        return this;
+    }
+
+    setEmail(email) {
+        this.email = email;
+        return this;
+    }
+
+    setTotalGB(gb) {
+        this.totalGB = gb;
+        return this;
+    }
+
+    setExpiryTime(timestamp) {
+        this.expiryTime = timestamp;
+        return this;
+    }
+
+    setTgId(id) {
+        this.tgId = id;
+        return this;
+    }
+
+    build() {
+        return {
+            id: this.id || crypto.randomUUID(),
+            flow: this.flow,
+            email: this.email || Math.random().toString(36).substring(2, 10),
+            limitIp: this.limitIp,
+            totalGB: this.totalGB,
+            expiryTime: this.expiryTime,
+            enable: this.enable,
+            tgId: this.tgId,
+            subId: this.subId || Math.random().toString(36).substring(2, 18),
+            reset: this.reset
+        };
+    }
+}

package/src/core/IndoundBuilder.d.ts

@@ -0,0 +1 @@
+export default class InboundBuilder {}

package/src/core/X3UIClient.d.ts

@@ -0,0 +1,31 @@
+import {AxiosInstance} from "axios";
+import {
+    InboundConfig,
+    LoginResponse,
+    SystemStats,
+    X3UIConfig
+} from "../index";
+
+export default class X3UIClient {
+    private client: AxiosInstance;
+
+    constructor(config: X3UIConfig);
+
+    login(username: string, password: string): Promise<LoginResponse>;
+
+    getSystemStats(): Promise<SystemStats>;
+
+    getInbounds(): Promise<InboundConfig[]>;
+
+    addInbound(config: Omit<InboundConfig, 'id'>): Promise<InboundConfig>;
+
+    updateInbound(id: number, config: Partial<InboundConfig>): Promise<void>;
+
+    deleteInbound(id: number): Promise<void>;
+
+    getInboundTraffic(id: number): Promise<{ up: number; down: number }>;
+
+    resetInboundTraffic(id: number): Promise<void>;
+
+    getNewX25519Cert(): Promise<{ privateKey: string; publicKey: string }>;
+}

package/src/core/X3UIClient.js

@@ -0,0 +1,147 @@
+const axios = require("axios");
+
+module.exports = class X3UIClient {
+    constructor(config) {
+        this.parseJSONSettings = config.parseJSONSettings || true;
+        this.client = axios.create({
+            baseURL: config.baseURL,
+            headers: config.token ? {
+                'Cookie': `lang=en-US; 3x-ui=${config.token}`,
+            } : {
+                'Cookie': 'lang=en-US'
+            }
+        });
+    }
+
+    /**
+     * Login to the x3ui panel
+     * @param {string} username Panel username
+     * @param {string} password Panel password
+     * @returns {Promise<{success: boolean, msg: string, obj: any}>} Login response with success status and token
+     */
+    async login(username, password) {
+        const formData = new URLSearchParams();
+        formData.append('username', username);
+        formData.append('password', password);
+
+        const response = await this.client.post('/login', formData, {
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            }
+        });
+
+        if (response.data.success) {
+            this.client.defaults.headers.Cookie = `lang=en-US; ${response.headers.get("set-cookie")[0].split(";")[0]}`;
+        }
+
+        return response.data;
+    }
+
+    async getSystemStats() {
+        const response = await this.client.post('/server/status');
+        return response.data.obj;
+    }
+
+    /**
+     * Get all inbounds
+     * @returns {Promise<Array<{
+     *   id?: number,
+     *   up: number,
+     *   down: number,
+     *   total: number,
+     *   remark: string,
+     *   enable: boolean,
+     *   expiryTime: number | null,
+     *   listen: string,
+     *   port: number,
+     *   protocol: string,
+     *   settings: any,
+     *   streamSettings: any,
+     *   sniffing: any
+     * }>>}
+     */
+    async getInbounds() {
+        const response = await this.client.get('/panel/api/inbounds/list');
+        let inbounds = response.data.obj;
+        if (this.parseJSONSettings) {
+            inbounds = inbounds.map(inbound => this.parseInbound(inbound));
+        }
+        return inbounds;
+    }
+
+    parseInbound(inbound) {
+        if (this.parseJSONSettings) {
+            inbound.settings = inbound.settings && inbound.settings.length > 0 ? JSON.parse(inbound.settings) : {};
+            inbound.streamSettings = inbound.streamSettings && inbound.streamSettings.length > 0 ? JSON.parse(inbound.streamSettings) : {};
+            inbound.sniffing = inbound.sniffing && inbound.sniffing.length > 0 ? JSON.parse(inbound.sniffing) : {};
+            inbound.allocate = inbound.allocate && inbound.allocate.length > 0 ? JSON.parse(inbound.allocate) : {};
+        }
+        return inbound;
+    }
+
+    stringifyInbound(inbound) {
+        inbound.settings = JSON.stringify(inbound.settings);
+        inbound.streamSettings = JSON.stringify(inbound.streamSettings);
+        inbound.sniffing = JSON.stringify(inbound.sniffing);
+        inbound.allocate = JSON.stringify(inbound.allocate);
+        return inbound;
+    }
+
+    /**
+     * Add new inbound
+     * @param {Object} config Inbound configuration
+     * @param {number} config.up Upload traffic in bytes
+     * @param {number} config.down Download traffic in bytes
+     * @param {number} config.total Total traffic limit in bytes
+     * @param {string} config.remark Inbound remark/name
+     * @param {boolean} config.enable Enable status
+     * @param {number|null} config.expiryTime Expiry timestamp
+     * @param {string} config.listen Listen address
+     * @param {number} config.port Port number
+     * @param {string} config.protocol Protocol type
+     * @param {Object} config.settings Protocol settings
+     * @param {Object} config.streamSettings Stream settings
+     * @param {Object} config.sniffing Sniffing settings
+     * @param {Object} config.allocate Allocation settings
+     * @returns {Promise<void>}
+     */
+    async addInbound(config) {
+        config = this.stringifyInbound(config);
+        const response = await this.client.post('/panel/api/inbounds/add', config);
+        if(!response.data.success)
+            throw new Error(response.data.msg);
+        return this.parseInbound(response.data.obj);
+    }
+
+    /**
+     * Update existing inbound
+     * @param {number} id Inbound ID
+     * @param {Object} config Partial inbound configuration
+     * @returns {Promise<void>}
+     */
+    async updateInbound(id, config) {
+        config = this.stringifyInbound(config);
+        const response = await this.client.post(`/panel/api/inbounds/update/${id}`, config);
+        if(!response.data.success)
+            throw new Error(response.data.msg);
+        return this.parseInbound(response.data.obj);
+    }
+
+    /**
+     * Delete inbound
+     * @param {number} id Inbound ID
+     * @returns {Promise<void>}
+     */
+    async deleteInbound(id) {
+        await this.client.post(`/panel/api/inbounds/del/${id}`);
+    }
+
+    /**
+     * Get new X25519 certificate
+     * @returns {Promise<{privateKey: string, publicKey: string}>} New X25519 key pair
+     */
+    async getNewX25519Cert() {
+        const response = await this.client.post('/server/getNewX25519Cert');
+        return response.data.obj;
+    }
+}