x3ui-api 1.0.1 → 1.0.3

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,163 @@ 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)
+- Convenient Reality inbound builder
+- 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 Reality Inbound
+
+The library provides a convenient builder pattern for creating Reality inbounds:
+
+```javascript
+async function createRealityInbound() {
+  try {
+    // Create a Reality inbound builder
+    const builder = client.createRealityBuilder({
+      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
+    const clientBuilder = 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);
+    
+    console.log('Inbound created:', result);
+    
+    // Get connection link for the client
+    const link = builder.getClientLink(0, 'your-server-ip.com');
+    console.log('Client connection link:', link);
+  } catch (error) {
+    console.error('Error creating inbound:', error.message);
+  }
+}
+```
+
+### 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
+    });
+    
+    // Delete an inbound
+    await client.deleteInbound(inboundId);
+  }
+}
+```
+
+## 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
+- `updateInbound(id, config)` - Update an existing inbound
+- `deleteInbound(id)` - Delete an inbound
+- `getNewX25519Cert()` - Generate a new X25519 certificate
+- `createRealityBuilder(options)` - Create a Reality inbound builder
+
+### RealityBuilder
+
+Builder class for creating Reality inbounds with a fluent API.
+
+#### 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.1",
+  "version": "1.0.3",
   "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/index.d.ts

@@ -201,9 +201,17 @@ export interface ClientBuilder {
     setTgId(id: string): this;
 
     /**
-     * Build client configuration
+     * Build the client configuration
      */
-    build(): Promise<ClientSettings>;
+    build(): ClientSettings;
+
+    /**
+     * Generate connection link for this client
+     * @param host Host address
+     * @param port Optional port number, defaults to parent's port
+     * @param protocol Optional protocol, defaults to parent's protocol or 'vless'
+     */
+    getLink(host: string, port?: number, protocol?: string): string;
 }
 
 export interface RealityBuilder {
@@ -257,6 +265,13 @@ export interface RealityBuilder {
      */
     addClient(options?: Partial<ClientSettings>): ClientBuilder;
     
+    /**
+     * Get connection link for a client
+     * @param clientIndex Index of the client (defaults to 0)
+     * @param host Optional host address (defaults to listenIP or 'localhost')
+     */
+    getClientLink(clientIndex?: number, host?: string): string;
+
     /**
      * Build the final inbound config
      */

package/src/index.js

@@ -72,9 +72,9 @@ module.exports = class X3UIClient {
 
     parseInbound(inbound) {
         if (this.parseJSONSettings) {
-            inbound.settings = JSON.parse(inbound.settings);
-            inbound.streamSettings = JSON.parse(inbound.streamSettings);
-            inbound.sniffing = JSON.parse(inbound.sniffing);
+            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;
@@ -196,7 +196,7 @@ class ClientBuilder {
         return this;
     }
 
-    async build() {
+    build() {
         return {
             id: this.id || crypto.randomUUID(),
             flow: this.flow,
@@ -210,6 +210,28 @@ class ClientBuilder {
             reset: this.reset
         };
     }
+
+    getLink(host, port, protocol) {
+        const id = this.id || crypto.randomUUID();
+        const settings = this.parent.streamSettings?.realitySettings;
+        if (!settings) throw new Error('Reality settings not found');
+
+        port = port || this.parent.port;
+        protocol = protocol || this.parent.protocol || 'vless';
+
+        const params = new URLSearchParams({
+            security: this.parent.streamSettings?.security || 'reality',
+            sni: settings.serverNames[0],
+            fp: settings.settings.fingerprint,
+            pbk: settings.settings.publicKey,
+            sid: settings.shortIds[0],
+            spx: settings.settings.spiderX || '/',
+            type: this.parent.streamSettings?.network || 'tcp',
+            encryption: this.parent.settings?.decryption || 'none'
+        });
+
+        return `${protocol}://${id}@${host}:${port}?${params.toString()}#${encodeURIComponent(this.email || 'default')}`;
+    }
 }
 
 class RealityBuilder {
@@ -303,10 +325,29 @@ class RealityBuilder {
         if (options.totalGB) builder.setTotalGB(options.totalGB);
         if (options.expiryTime) builder.setExpiryTime(options.expiryTime);
         if (options.tgId) builder.setTgId(options.tgId);
+        builder.parent.streamSettings = {
+            realitySettings: {
+                serverNames: this.serverNames,
+                settings: {
+                    fingerprint: this.fingerprint,
+                    publicKey: this.publicKey,
+                    spiderX: '/'
+                },
+                shortIds: this.shortIds
+            }
+        };
         this.clients.push(builder);
         return builder;
     }
 
+    getClientLink(clientIndex = 0, host) {
+        if (clientIndex < 0 || clientIndex >= this.clients.length) {
+            throw new Error('Invalid client index');
+        }
+        const client = this.clients[clientIndex];
+        return client.getLink(host || this.listenIP || 'localhost', this.port);
+    }
+
     generateRandomPort() {
         return Math.floor(Math.random() * (65535 - 1024) + 1024);
     }