x3ui-api 1.0.3 → 1.0.4

package/README.md

@@ -13,7 +13,9 @@ npm install x3ui-api
 - Authentication with x3ui panel
 - Get system statistics (CPU, memory, network, etc.)
 - Manage inbounds (list, add, update, delete)
-- Convenient Reality inbound builder
+- Protocol-specific builders with fluent API:
+  - VLESS with Reality support
+  - VMess with HTTP Upgrade support
 - Client management with fluent API
 - TypeScript support
 
@@ -59,15 +61,72 @@ async function main() {
 main();
 ```
 
-### Creating a Reality Inbound
+### 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
-    const builder = client.createRealityBuilder({
+    let builder = new vless.RealityBuilder(client, {
       remark: 'My Reality Inbound',
       port: 8443 // Optional, will auto-generate if not provided
     });
@@ -79,18 +138,21 @@ async function createRealityInbound() {
       .setFingerprint('chrome');
     
     // Add a client
-    const clientBuilder = builder.addClient()
+    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 result = await client.addInbound(inbound);
+    const createdInbound = await client.addInbound(inbound);
     
-    console.log('Inbound created:', result);
+    // Update the builder with the server-returned inbound to get all metrics and IDs
+    builder = new vless.RealityBuilder(client, createdInbound);
     
-    // Get connection link for the client
+    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) {
@@ -99,24 +161,84 @@ async function createRealityInbound() {
 }
 ```
 
+### 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() {
-  // Get all inbounds
-  const inbounds = await client.getInbounds();
-  
-  if (inbounds.length > 0) {
-    const inboundId = inbounds[0].id;
-    
-    // Update an inbound
-    await client.updateInbound(inboundId, {
-      remark: 'Updated Inbound Name',
-      enable: true
-    });
+  try {
+    // Get all inbounds
+    const inbounds = await client.getInbounds();
     
-    // Delete an inbound
-    await client.deleteInbound(inboundId);
+    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);
   }
 }
 ```
@@ -140,18 +262,44 @@ new X3UIClient({
 - `login(username: string, password: string)` - Authenticate with the panel
 - `getSystemStats()` - Get system statistics
 - `getInbounds()` - Get all configured inbounds
-- `addInbound(config)` - Add a new inbound
-- `updateInbound(id, config)` - Update an existing inbound
+- `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
-- `createRealityBuilder(options)` - Create a Reality inbound builder
 
-### RealityBuilder
+### Protocol Builders
 
-Builder class for creating Reality inbounds with a fluent API.
+The library provides protocol-specific builders for creating different types of inbounds:
 
-#### Methods
+#### 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")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x3ui-api",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "API client for x3ui panel",
   "main": "src/index.js",
   "types": "src/index.d.ts",

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;
+    }
+}