3xui-api-client 2.1.1 → 3.1.0

package/index.js

@@ -8,6 +8,7 @@ const {
     CredentialSecurity,
     ErrorSecurity
 } = require('./src/security/SecurityEnhancer');
+const { convertBandwidthFields } = require('./src/utils/ByteConversion');
 
 /**
  * 3X-UI API Client Library
@@ -32,16 +33,10 @@ class ThreeXUI {
      * @param {number} options.timeout - Request timeout in milliseconds (default: 30000)
      * @throws {Error} If baseURL, username, or password is missing
      */
-    constructor(baseURL, username, password, options = {}) {
+    constructor(baseURL, usernameOrOptions, password, options = {}) {
         if (!baseURL) {
             throw new Error('baseURL is required');
         }
-        if (!username) {
-            throw new Error('username is required');
-        }
-        if (!password) {
-            throw new Error('password is required');
-        }
 
         // Apply security validations
         this.baseURL = InputValidator.validateURL(baseURL);
@@ -53,13 +48,46 @@ class ThreeXUI {
             this.baseURL = this.baseURL.replace(/\/panel\/?$/, '');
         }
 
-        this.username = InputValidator.validateUsername(username);
-        this.password = InputValidator.validatePassword(password);
+        // Object containing configs as 2nd parameter
+        if (typeof usernameOrOptions === 'object' && usernameOrOptions !== null) {
+            options = usernameOrOptions;
+            this.username = options.username;
+            this.password = options.password;
+        } else {
+            this.username = usernameOrOptions;
+            this.password = password;
+        }
+
+        this.token = options.token || options.apiToken || null;
+
+        if (this.token) {
+            this.username = this.username || 'token-auth'; // prevent missing args error
+            this.password = this.password || 'token-auth';
+        } else {
+            if (!this.username) {
+                throw new Error('username is required');
+            }
+            if (!this.password) {
+                throw new Error('password is required');
+            }
+            this.username = InputValidator.validateUsername(this.username);
+            this.password = InputValidator.validatePassword(this.password);
+        }
+
         this.cookie = null;
+        this.csrfToken = null;
         this.options = options;
         this.loginMutex = false; // Add mutex to prevent concurrent logins
         this.loginRetryCount = 0; // Add retry counter
         this.maxLoginRetries = 3; // Maximum login attempts
+        // Delay (ms) between forced re-login attempts on 401.
+        // Helps avoid tripping fail2ban or 3x-ui login-rate limits,
+        // especially in serverless environments where many cold-start
+        // instances may race to re-authenticate simultaneously.
+        this.loginRetryBackoff = options.loginRetryBackoff !== undefined
+            ? options.loginRetryBackoff
+            : 500;
+        this.panelType = options.panelType || 'auto'; // 'modern', 'legacy', or 'auto' for detection
 
         // Initialize security monitoring
         this.securityMonitor = new SecurityMonitor({
@@ -81,15 +109,21 @@ class ThreeXUI {
         }
 
         // Create axios instance with security best practices
+        const secureHeaders = SecureHeaders.getSecureHeaders({
+            userAgent: options.userAgent || '3xui-api-client/2.0.0 (Security-Enhanced)',
+            enableCSP: options.enableCSP || false
+        });
+
+        if (this.token) {
+            secureHeaders['Authorization'] = `Bearer ${this.token}`;
+        }
+
         this.api = axios.create({
             baseURL: this.baseURL,
             timeout: options.timeout || 30000, // 30 second timeout
             maxRedirects: 5,
             validateStatus: (status) => status >= 200 && status < 300,
-            headers: SecureHeaders.getSecureHeaders({
-                userAgent: options.userAgent || '3xui-api-client/2.0.0 (Security-Enhanced)',
-                enableCSP: options.enableCSP || false
-            })
+            headers: secureHeaders
         });
 
         // Add request interceptor for security headers
@@ -120,6 +154,14 @@ class ThreeXUI {
      * @returns {Object} Login response
      */
     async login(forceRefresh = false) {
+        // If API token is configured, skip cookie auth
+        if (this.token) {
+            return {
+                success: true,
+                message: 'Authenticated successfully using API Token'
+            };
+        }
+
         // Check rate limiting first
         const identifier = CredentialSecurity.hashForLogging(this.username);
         if (!this.securityMonitor.checkRateLimit(identifier, 'login')) {
@@ -136,6 +178,13 @@ class ThreeXUI {
             if (existingSession && existingSession.cookie) {
                 this.cookie = existingSession.cookie;
                 this.api.defaults.headers.Cookie = this.cookie;
+                if (existingSession.csrfToken) {
+                    this.csrfToken = existingSession.csrfToken;
+                }
+                // Restore panel type from session if auto-detection was used
+                if (existingSession.panelType && this.panelType === 'auto') {
+                    this.panelType = existingSession.panelType;
+                }
                 // Reset retry count on successful session restore
                 this.loginRetryCount = 0;
                 return {
@@ -151,11 +200,66 @@ class ThreeXUI {
             params.append('username', this.username);
             params.append('password', this.password);
 
-            const response = await this.api.post('/login', params, {
-                headers: {
-                    'Content-Type': 'application/x-www-form-urlencoded'
+            const loginHeaders = {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            };
+
+            // Newer (React-based) 3x-ui panels require a CSRF token + session
+            // cookie obtained from /csrf-token before /login will accept
+            // credentials. Older (Vue-based) panels don't expose this
+            // endpoint (404), in which case we fall back to the classic
+            // direct login below.
+            const csrfInfo = await this._getCsrfToken();
+            if (csrfInfo) {
+                loginHeaders['X-CSRF-Token'] = csrfInfo.token;
+                loginHeaders['Cookie'] = csrfInfo.cookie;
+            }
+
+            // Try modern endpoint first (/panel/api/login), then fall back to legacy endpoint (/login)
+            // This supports both newer (React-based) and older (Vue-based) 3x-ui panels
+            let response;
+            let lastError;
+            let detectedPanelType = this.panelType;
+
+            // Determine which endpoint to try based on panelType setting
+            const tryModernFirst = this.panelType !== 'legacy';
+            const tryLegacyFallback = this.panelType !== 'modern';
+
+            if (tryModernFirst) {
+                // Try modern endpoint first (/panel/api/login)
+                try {
+                    response = await this.api.post('/panel/api/login', params, {
+                        headers: loginHeaders
+                    });
+                    if (this.panelType === 'auto') {
+                        detectedPanelType = 'modern';
+                    }
+                } catch (modernError) {
+                    lastError = modernError;
+                    // If modern endpoint fails and fallback is enabled, try legacy endpoint
+                    if (tryLegacyFallback) {
+                        try {
+                            response = await this.api.post('/login', params, {
+                                headers: loginHeaders
+                            });
+                            if (this.panelType === 'auto') {
+                                detectedPanelType = 'legacy';
+                            }
+                        } catch {
+                            // Both endpoints failed, throw the last error
+                            throw lastError;
+                        }
+                    } else {
+                        throw modernError;
+                    }
                 }
-            });
+            } else {
+                // Try legacy endpoint first (/login) if explicitly set
+                response = await this.api.post('/login', params, {
+                    headers: loginHeaders
+                });
+                detectedPanelType = 'legacy';
+            }
 
             if (response.data.success) {
                 const cookies = response.headers['set-cookie'];
@@ -163,11 +267,24 @@ class ThreeXUI {
                     this.cookie = cookies[0].split(';')[0];
                     this.api.defaults.headers.Cookie = this.cookie;
 
+                    // On newer panels, every non-safe request (POST/PUT/DELETE)
+                    // also requires this CSRF token, not just /login.
+                    if (csrfInfo) {
+                        this.csrfToken = csrfInfo.token;
+                    }
+
+                    // Update panel type after successful detection
+                    if (this.panelType === 'auto') {
+                        this.panelType = detectedPanelType;
+                    }
+
                     // Store session if session manager is available
                     if (this.sessionManager) {
                         try {
                             await this.sessionManager.storeSession(this.baseURL, this.username, {
                                 cookie: this.cookie,
+                                csrfToken: this.csrfToken,
+                                panelType: detectedPanelType, // Store detected panel type for future use
                                 loginTime: new Date().toISOString()
                             });
                         } catch (sessionError) {
@@ -211,6 +328,43 @@ class ThreeXUI {
         }
     }
 
+    /**
+     * Detect newer (React-based) 3x-ui panels and obtain the CSRF token +
+     * session cookie required by their /login endpoint.
+     *
+     * Older (Vue-based) panels don't expose /csrf-token and respond with a
+     * 404, in which case this returns null so login() falls back to the
+     * classic direct login flow.
+     *
+     * @returns {Promise<{token: string, cookie: string} | null>}
+     */
+    async _getCsrfToken() {
+        try {
+            const response = await this.api.get('/csrf-token', {
+                headers: { 'X-Requested-With': 'XMLHttpRequest' },
+                validateStatus: (status) => status === 200 || status === 404
+            });
+
+            if (response.status !== 200 || !response.data || !response.data.success || !response.data.obj) {
+                return null;
+            }
+
+            const cookies = response.headers['set-cookie'];
+            if (!cookies || cookies.length === 0) {
+                return null;
+            }
+
+            return {
+                token: response.data.obj,
+                cookie: cookies[0].split(';')[0]
+            };
+        } catch {
+            // /csrf-token unreachable or errored - treat as an old panel
+            // and let login() proceed with the classic flow.
+            return null;
+        }
+    }
+
     /**
      * Logout and clear session
      */
@@ -222,6 +376,7 @@ class ThreeXUI {
         }
 
         this.cookie = null;
+        this.csrfToken = null;
         delete this.api.defaults.headers.Cookie;
 
         if (this.sessionManager) {
@@ -237,12 +392,14 @@ class ThreeXUI {
         return this._request('post', '/getTwoFactorEnable');
     }
 
-    async _request(method, path, data = {}) {
-        // Check session validity first with mutex protection
-        if (!this.loginMutex && this.sessionManager && !await this.sessionManager.hasValidSession(this.baseURL, this.username)) {
-            await this._ensureAuthenticated();
-        } else if (!this.loginMutex && !this.cookie) {
-            await this._ensureAuthenticated();
+    async _request(method, path, data = {}, extraHeaders = {}) {
+        // Check session validity first with mutex protection if token is not provided
+        if (!this.token) {
+            if (!this.loginMutex && this.sessionManager && !await this.sessionManager.hasValidSession(this.baseURL, this.username)) {
+                await this._ensureAuthenticated();
+            } else if (!this.loginMutex && !this.cookie) {
+                await this._ensureAuthenticated();
+            }
         }
 
         try {
@@ -250,21 +407,30 @@ class ThreeXUI {
                 method,
                 url: path,
                 data,
-                ...(method.toLowerCase() === 'post' ? { headers: { 'Content-Type': 'application/json' } } : {})
+                headers: { ...this._buildRequestHeaders(method), ...extraHeaders }
             });
             // Reset retry counter on successful request
             this.loginRetryCount = 0;
             return response.data;
         } catch (error) {
             if (error.response && error.response.status === 401) {
-                // Cookie might have expired, try to login again with retry limit
+                if (this.token) {
+                    throw new Error('API Token is invalid or expired. Please check your credentials.');
+                }
+                // Cookie might have expired, try to login again with retry limit.
+                // A configurable backoff delay is applied before each re-login to
+                // avoid burning through the retry budget or tripping login-rate limits
+                // (e.g. fail2ban) when many instances race to re-authenticate.
                 if (this.loginRetryCount < this.maxLoginRetries) {
+                    if (this.loginRetryBackoff > 0) {
+                        await new Promise(resolve => setTimeout(resolve, this.loginRetryBackoff));
+                    }
                     await this._ensureAuthenticated(true); // Force refresh
                     const response = await this.api.request({
                         method,
                         url: path,
                         data,
-                        ...(method.toLowerCase() === 'post' ? { headers: { 'Content-Type': 'application/json' } } : {})
+                        headers: { ...this._buildRequestHeaders(method), ...extraHeaders }
                     });
                     return response.data;
                 } else {
@@ -275,6 +441,30 @@ class ThreeXUI {
         }
     }
 
+    /**
+     * Build per-request headers, including the JSON content type for POST
+     * bodies and (on cookie-authenticated sessions against newer
+     * React-based panels) the X-CSRF-Token header required for non-safe
+     * HTTP methods.
+     *
+     * @param {string} method - HTTP method for the request
+     * @returns {Object} Headers to merge into the request
+     */
+    _buildRequestHeaders(method) {
+        const headers = {};
+
+        if (method.toLowerCase() === 'post') {
+            headers['Content-Type'] = 'application/json';
+        }
+
+        const isSafeMethod = ['get', 'head', 'options'].includes(method.toLowerCase());
+        if (!isSafeMethod && !this.token && this.csrfToken) {
+            headers['X-CSRF-Token'] = this.csrfToken;
+        }
+
+        return headers;
+    }
+
     /**
      * Ensure authentication with mutex protection
      * @param {boolean} forceRefresh - Force a new login
@@ -406,6 +596,7 @@ class ThreeXUI {
      */
     async addClientWithCredentials(inboundId, protocol, options = {}) {
         const credentials = this.generateCredentials(protocol, options);
+        const convertedOptions = convertBandwidthFields(options);
 
         const clientConfig = {
             id: inboundId,
@@ -413,10 +604,10 @@ class ThreeXUI {
                 clients: [{
                     ...credentials,
                     enable: true,
-                    expiryTime: options.expiryTime || 0,
-                    limitIp: options.limitIp || 0,
-                    totalGB: options.totalGB || 0,
-                    subId: options.subId || this.generateUUID()
+                    expiryTime: convertedOptions.expiryTime || 0,
+                    limitIp: convertedOptions.limitIp || 0,
+                    totalGB: convertedOptions.totalGB || 0,
+                    subId: convertedOptions.subId || this.generateUUID()
                 }]
             })
         };
@@ -455,17 +646,19 @@ class ThreeXUI {
                 throw new Error(`Client with ID ${clientId} not found in inbound ${inboundId}`);
             }
 
+            // Convert bandwidth fields (GB to bytes)
+            const convertedOptions = convertBandwidthFields(options);
+
             // Convert user-friendly options to API format
             const processedOptions = {
-                email: options.email || existingClients[clientIndex].email,
-                limitIp: options.limitIp !== undefined ? options.limitIp : existingClients[clientIndex].limitIp,
-                // totalGB is specified in gigabytes in 3x-ui config; do not convert to bytes
-                totalGB: options.totalGB !== undefined ? options.totalGB : existingClients[clientIndex].totalGB,
-                expiryTime: options.expiryDays ? Date.now() + (options.expiryDays * 24 * 60 * 60 * 1000) : existingClients[clientIndex].expiryTime,
-                enable: options.enable !== undefined ? options.enable : existingClients[clientIndex].enable,
-                flow: options.flow || existingClients[clientIndex].flow,
-                encryption: options.encryption || existingClients[clientIndex].encryption || 'none',
-                subId: options.subId || existingClients[clientIndex].subId
+                email: convertedOptions.email || existingClients[clientIndex].email,
+                limitIp: convertedOptions.limitIp !== undefined ? convertedOptions.limitIp : existingClients[clientIndex].limitIp,
+                totalGB: convertedOptions.totalGB !== undefined ? convertedOptions.totalGB : existingClients[clientIndex].totalGB,
+                expiryTime: convertedOptions.expiryDays ? Date.now() + (convertedOptions.expiryDays * 24 * 60 * 60 * 1000) : existingClients[clientIndex].expiryTime,
+                enable: convertedOptions.enable !== undefined ? convertedOptions.enable : existingClients[clientIndex].enable,
+                flow: convertedOptions.flow || existingClients[clientIndex].flow,
+                encryption: convertedOptions.encryption || existingClients[clientIndex].encryption || 'none',
+                subId: convertedOptions.subId || existingClients[clientIndex].subId
             };
 
             // Update the specific client while preserving others
@@ -490,8 +683,8 @@ class ThreeXUI {
                 ...result,
                 updatedOptions: processedOptions,
                 conversions: {
-                    totalGB: options.totalGB !== undefined ? `${options.totalGB}GB` : 'unchanged',
-                    expiryDays: options.expiryDays ? `${options.expiryDays} days → ${new Date(processedOptions.expiryTime).toISOString()}` : 'unchanged'
+                    totalGB: convertedOptions.totalGB !== undefined ? `${options.totalGB} GB → ${convertedOptions.totalGB} bytes` : 'unchanged',
+                    expiryDays: convertedOptions.expiryDays ? `${convertedOptions.expiryDays} days → ${new Date(processedOptions.expiryTime).toISOString()}` : 'unchanged'
                 }
             };
         } catch (error) {
@@ -533,12 +726,334 @@ class ThreeXUI {
      * @returns {boolean} Session validity
      */
     async isSessionValid() {
+        if (this.token) {
+            return true;
+        }
         if (this.sessionManager) {
             return await this.sessionManager.hasValidSession(this.baseURL, this.username);
         }
         return !!this.cookie;
     }
 
+    // ===========================================
+    // MODERN API METHODS (3X-UI >= 2.x)
+    // ===========================================
+
+    // --- Clients ---
+
+    /**
+     * Get list of all clients
+     * @returns {Promise<Object>} Formatted list of all clients
+     */
+    getClients() {
+        return this._request('get', '/panel/api/clients/list');
+    }
+
+    /**
+     * Get paginated list of clients
+     * @param {Object} params - Pagination parameters
+     * @param {number} params.page - Page number (default: 1)
+     * @param {number} params.size - Items per page (default: 10)
+     * @param {string} params.sort - Sort field (e.g., 'email', 'expireTime')
+     * @param {string} params.order - Sort order ('asc' or 'desc')
+     * @param {string} params.email - Filter by email
+     * @returns {Promise<Object>} Paginated clients
+     */
+    getPagedClients(params = {}) {
+        const queryParams = new URLSearchParams();
+        if (params.page !== undefined) {
+            queryParams.append('page', params.page);
+        }
+        if (params.size !== undefined) {
+            queryParams.append('size', params.size);
+        }
+        if (params.sort !== undefined) {
+            queryParams.append('sort', params.sort);
+        }
+        if (params.order !== undefined) {
+            queryParams.append('order', params.order);
+        }
+        if (params.email !== undefined) {
+            queryParams.append('email', params.email);
+        }
+
+        const queryString = queryParams.toString();
+        const url = queryString ? `/panel/api/clients/list/paged?${queryString}` : '/panel/api/clients/list/paged';
+
+        return this._request('get', url);
+    }
+
+    /**
+     * Get client by email
+     * @param {string} email - Exact client email address
+     * @returns {Promise<Object>} Client metadata
+     */
+    getClient(email) {
+        return this._request('get', `/panel/api/clients/get/${encodeURIComponent(email)}`);
+    }
+
+    /**
+     * Get client traffic by email
+     * @param {string} email - Exact client email
+     * @returns {Promise<Object>} Client traffic details
+     */
+    getClientTraffic(email) {
+        return this._request('get', `/panel/api/clients/traffic/${encodeURIComponent(email)}`);
+    }
+
+    /**
+     * Get subscription links for a client by subscription ID
+     * @param {string} subId - Subscription ID (UUID)
+     * @returns {Promise<Object>} Subscription details and links
+     */
+    getSubLinks(subId) {
+        return this._request('get', `/panel/api/clients/subLinks/${encodeURIComponent(subId)}`);
+    }
+
+    /**
+     * Get generic client links by email
+     * @param {string} email - Exact client email
+     * @returns {Promise<Object>} Link strings
+     */
+    getClientLinks(email) {
+        return this._request('get', `/panel/api/clients/links/${encodeURIComponent(email)}`);
+    }
+
+    /**
+     * Add a new client via Modern API
+     * @param {Object} data - Client payload
+     * @returns {Promise<Object>} Addition response
+     */
+    addModernClient(data) {
+        const convertedData = {
+            ...data,
+            client: data.client ? convertBandwidthFields(data.client) : undefined
+        };
+        return this._request('post', '/panel/api/clients/add', convertedData);
+    }
+
+    /**
+     * Update client by email via Modern API
+     * @param {string} email - Exact client email
+     * @param {Object} data - Update payload
+     * @returns {Promise<Object>} Update response
+     */
+    updateModernClient(email, data) {
+        const convertedData = convertBandwidthFields(data);
+        return this._request('post', `/panel/api/clients/update/${encodeURIComponent(email)}`, convertedData);
+    }
+
+    /**
+     * Delete client by email via Modern API
+     * @param {string} email - Exact client email
+     * @returns {Promise<Object>} Delete response
+     */
+    deleteModernClient(email) {
+        return this._request('post', `/panel/api/clients/del/${encodeURIComponent(email)}`);
+    }
+
+    attachClientToInbounds(email, data) {
+        return this._request('post', `/panel/api/clients/${encodeURIComponent(email)}/attach`, data);
+    }
+
+    detachClientFromInbounds(email, data) {
+        return this._request('post', `/panel/api/clients/${encodeURIComponent(email)}/detach`, data);
+    }
+
+    resetAllModernClientTraffics() {
+        return this._request('post', '/panel/api/clients/resetAllTraffics');
+    }
+
+    deleteDepletedModernClients() {
+        return this._request('post', '/panel/api/clients/delDepleted');
+    }
+
+    bulkAdjustModernClients(data) {
+        return this._request('post', '/panel/api/clients/bulkAdjust', data);
+    }
+
+    bulkDeleteModernClients(data) {
+        return this._request('post', '/panel/api/clients/bulkDel', data);
+    }
+
+    bulkCreateModernClients(data) {
+        return this._request('post', '/panel/api/clients/bulkCreate', data);
+    }
+
+    bulkAttachModernClients(data) {
+        return this._request('post', '/panel/api/clients/bulkAttach', data);
+    }
+
+    bulkDetachModernClients(data) {
+        return this._request('post', '/panel/api/clients/bulkDetach', data);
+    }
+
+    bulkResetTrafficModernClients(data) {
+        return this._request('post', '/panel/api/clients/bulkResetTraffic', data);
+    }
+
+    resetModernClientTrafficByEmail(email) {
+        return this._request('post', `/panel/api/clients/resetTraffic/${encodeURIComponent(email)}`);
+    }
+
+    updateModernClientTrafficByEmail(email, data) {
+        return this._request('post', `/panel/api/clients/updateTraffic/${encodeURIComponent(email)}`, data);
+    }
+
+    getModernClientIps(email) {
+        return this._request('post', `/panel/api/clients/ips/${encodeURIComponent(email)}`);
+    }
+
+    clearModernClientIps(email) {
+        return this._request('post', `/panel/api/clients/clearIps/${encodeURIComponent(email)}`);
+    }
+
+    getOnlines() {
+        return this._request('post', '/panel/api/clients/onlines');
+    }
+
+    getModernLastOnline() {
+        return this._request('post', '/panel/api/clients/lastOnline');
+    }
+
+    // --- Client Groups ---
+
+    /**
+     * Get list of all client groups
+     * @returns {Promise<Object>} List of client groups
+     */
+    getGroups() {
+        return this._request('get', '/panel/api/clients/groups');
+    }
+
+    /**
+     * Get list of emails belonging to a specific group
+     * @param {string} groupName - The name of the group
+     * @returns {Promise<Object>} List of emails in the group
+     */
+    getGroupEmails(groupName) {
+        return this._request('get', `/panel/api/clients/groups/${encodeURIComponent(groupName)}/emails`);
+    }
+
+    createGroup(data) {
+        return this._request('post', '/panel/api/clients/groups/create', data);
+    }
+
+    renameGroup(data) {
+        return this._request('post', '/panel/api/clients/groups/rename', data);
+    }
+
+    deleteGroup(data) {
+        return this._request('post', '/panel/api/clients/groups/delete', data);
+    }
+
+    bulkAddGroups(data) {
+        return this._request('post', '/panel/api/clients/groups/bulkAdd', data);
+    }
+
+    bulkRemoveGroups(data) {
+        return this._request('post', '/panel/api/clients/groups/bulkRemove', data);
+    }
+
+    // --- Nodes ---
+
+    /**
+     * Get list of all nodes
+     * @returns {Promise<Object>} List of nodes
+     */
+    getNodes() {
+        return this._request('get', '/panel/api/nodes/list');
+    }
+
+    /**
+     * Get specific node by ID
+     * @param {number|string} id - Node ID
+     * @returns {Promise<Object>} Node details
+     */
+    getNode(id) {
+        return this._request('get', `/panel/api/nodes/get/${encodeURIComponent(id)}`);
+    }
+
+    /**
+     * Get history metrics for a node
+     * @param {number|string} id - Node ID
+     * @param {string} metric - Metric name (e.g., 'cpu', 'memory')
+     * @param {string} bucket - Time bucket size
+     * @returns {Promise<Object>} Node history data
+     */
+    getNodeHistory(id, metric, bucket) {
+        return this._request('get', `/panel/api/nodes/history/${encodeURIComponent(id)}/${encodeURIComponent(metric)}/${encodeURIComponent(bucket)}`);
+    }
+
+    addNode(data) {
+        return this._request('post', '/panel/api/nodes/add', data);
+    }
+
+    updateNode(id, data) {
+        return this._request('post', `/panel/api/nodes/update/${encodeURIComponent(id)}`, data);
+    }
+
+    deleteNode(id) {
+        return this._request('post', `/panel/api/nodes/del/${encodeURIComponent(id)}`);
+    }
+
+    /**
+     * Enable or disable a node.
+     * @param {number|string} id - Node ID
+     * @param {boolean} [enable] - Desired enabled state. If omitted, the panel toggles the current state.
+     * @returns {Promise<Object>} Result of the operation
+     */
+    setNodeEnable(id, enable) {
+        const data = typeof enable === 'boolean' ? { enable } : {};
+        return this._request('post', `/panel/api/nodes/setEnable/${encodeURIComponent(id)}`, data);
+    }
+
+    testNode(data) {
+        return this._request('post', '/panel/api/nodes/test', data);
+    }
+
+    probeNode(id) {
+        return this._request('post', `/panel/api/nodes/probe/${encodeURIComponent(id)}`);
+    }
+
+    // --- Custom Geo ---
+
+    /**
+     * Get list of custom geo sites/ips
+     * @returns {Promise<Object>} List of custom geos
+     */
+    getCustomGeos() {
+        return this._request('get', '/panel/api/custom-geo/list');
+    }
+
+    /**
+     * Get aliases for custom geos
+     * @returns {Promise<Object>} Custom geo aliases
+     */
+    getGeoAliases() {
+        return this._request('get', '/panel/api/custom-geo/aliases');
+    }
+
+    addCustomGeo(data) {
+        return this._request('post', '/panel/api/custom-geo/add', data);
+    }
+
+    updateCustomGeo(id, data) {
+        return this._request('post', `/panel/api/custom-geo/update/${encodeURIComponent(id)}`, data);
+    }
+
+    deleteCustomGeo(id) {
+        return this._request('post', `/panel/api/custom-geo/delete/${encodeURIComponent(id)}`);
+    }
+
+    downloadCustomGeo(id) {
+        return this._request('post', `/panel/api/custom-geo/download/${encodeURIComponent(id)}`);
+    }
+
+    updateAllCustomGeo() {
+        return this._request('post', '/panel/api/custom-geo/update-all');
+    }
+
     // ===========================================
     // ORIGINAL API METHODS (UNCHANGED)
     // ===========================================
@@ -569,11 +1084,21 @@ class ThreeXUI {
     }
 
     /**
-     * Import inbounds
-     * @param {Array} inbounds - Array of inbound configurations
+     * Import one or more inbounds. The panel endpoint only accepts a single
+     * inbound per request (as a form-encoded `data` field containing the
+     * inbound JSON), so each inbound is sent as a separate request.
+     * @param {Object|Object[]} inbounds - Inbound configuration, or array of configurations
+     * @returns {Promise<Object[]>} One response object per imported inbound
      */
     importInbounds(inbounds) {
-        return this._request('post', '/panel/api/inbounds/import', { inbounds });
+        const list = Array.isArray(inbounds) ? inbounds : [inbounds];
+        return Promise.all(list.map((inboundConfig) => {
+            const validatedConfig = InputValidator.validateInboundConfig(inboundConfig);
+            const body = new URLSearchParams({ data: JSON.stringify(validatedConfig) }).toString();
+            return this._request('post', '/panel/api/inbounds/import', body, {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            });
+        }));
     }
 
     /**
@@ -680,10 +1205,10 @@ class ThreeXUI {
 
     /**
      * Get CPU usage history
-     * @param {string} bucket - Time bucket (e.g., 'min', 'hour')
+     * @param {number} bucket - Bucket size in seconds. Must be one of: 2, 30, 60, 120, 180, 300
      */
-    getCPUHistory(bucket = 'min') {
-        return this._request('get', `/panel/api/server/cpuHistory/${bucket}`);
+    getCPUHistory(bucket = 60) {
+        return this._request('get', `/panel/api/server/cpuHistory/${encodeURIComponent(bucket)}`);
     }
 
     /**
@@ -702,9 +1227,24 @@ class ThreeXUI {
 
     /**
      * Download database
+     * @returns {Promise<string>} Raw SQLite database file content as a string (starts with "SQLite format 3 ..."), not a Buffer
      */
-    getDb() {
-        return this._request('get', '/panel/api/server/getDb');
+    async getDb() {
+        const response = await this._request('get', '/panel/api/server/getDb');
+        // Add response validation
+        if (!response || typeof response !== 'object') {
+            throw new Error('getDb: Invalid response format');
+        }
+        if (response.success === false) {
+            throw new Error(`getDb failed: ${response.msg || 'Unknown error'}`);
+        }
+        if (!response.obj) {
+            throw new Error('getDb: Response missing database content');
+        }
+        if (typeof response.obj !== 'string') {
+            throw new Error(`getDb: Expected string content, got ${typeof response.obj}`);
+        }
+        return response;
     }
 
     /**
@@ -723,9 +1263,20 @@ class ThreeXUI {
 
     /**
      * Install specific Xray version
-     * @param {string} version - Version to install
+     * @param {string} version - Version to install (e.g., "1.8.0")
      */
     installXray(version) {
+        // Validate version parameter
+        if (!version || typeof version !== 'string') {
+            throw new Error('installXray: version must be a non-empty string');
+        }
+        if (version.toLowerCase() === 'latest') {
+            throw new Error(
+                'installXray: "latest" is not a valid version. ' +
+                'Use client.getXrayVersion() to get available versions, ' +
+                'then pass a specific version like "1.8.0"'
+            );
+        }
         return this._request('post', `/panel/api/server/installXray/${version}`);
     }
 
@@ -793,8 +1344,25 @@ class ThreeXUI {
         return this._request('get', '/panel/api/server/getNewVlessEnc');
     }
 
-    getNewEchCert() {
-        return this._request('post', '/panel/api/server/getNewEchCert');
+    /**
+     * Generate a new ECH (Encrypted Client Hello) certificate.
+     * @param {string} [sni] - Optional SNI to embed in the generated certificate.
+     *   Sent as `application/x-www-form-urlencoded` since the panel reads it via `c.PostForm`.
+     * @returns {Promise<Object>} Generated ECH certificate data
+     */
+    getNewEchCert(sni) {
+        const body = sni ? new URLSearchParams({ sni }).toString() : '';
+        return this._request('post', '/panel/api/server/getNewEchCert', body, {
+            'Content-Type': 'application/x-www-form-urlencoded'
+        });
+    }
+
+    /**
+     * Get the panel's configured web certificate/key file paths.
+     * @returns {Promise<Object>} Web certificate file info
+     */
+    getWebCertFiles() {
+        return this._request('get', '/panel/api/server/getWebCertFiles');
     }
 
     // ===========================================
@@ -805,52 +1373,106 @@ class ThreeXUI {
      * Get all panel settings
      */
     getAllSettings() {
-        return this._request('post', '/panel/setting/all');
+        return this._request('post', '/panel/api/setting/all');
     }
 
     /**
      * Update panel settings
-     * @param {Object} settings - Settings to update
+     * NOTE: The API requires ALL settings to be sent together, not just the changed ones.
+     * This method automatically fetches current settings, applies your changes, and sends all.
+     * @param {Object} updates - Settings to update (partial object, will be merged with current)
+     * @returns {Promise} Response from /panel/api/setting/update
      */
-    updateSetting(settings) {
-        return this._request('post', '/panel/setting/update', settings);
+    async updateSetting(updates) {
+        if (!updates || typeof updates !== 'object') {
+            throw new Error('updates must be an object');
+        }
+
+        // Fetch current settings
+        const currentResponse = await this.getAllSettings();
+        if (!currentResponse.success || !currentResponse.obj) {
+            throw new Error('Failed to fetch current settings for merge');
+        }
+
+        // Merge updates with current settings (updates override current)
+        const mergedSettings = {
+            ...currentResponse.obj,
+            ...updates
+        };
+
+        // Send all settings together
+        return this._request('post', '/panel/api/setting/update', mergedSettings);
     }
 
     /**
      * Update admin username and password
+     * ⚠️ CRITICAL: This endpoint changes your login credentials.
+     * After a successful update, the internal client credentials are refreshed
+     * and the session is re-authenticated with new credentials.
      * @param {string} oldUsername - Current username
      * @param {string} oldPassword - Current password
      * @param {string} newUsername - New username
      * @param {string} newPassword - New password
      */
-    updateUser(oldUsername, oldPassword, newUsername, newPassword) {
-        return this._request('post', '/panel/setting/updateUser', {
+    async updateUser(oldUsername, oldPassword, newUsername, newPassword) {
+        const response = await this._request('post', '/panel/api/setting/updateUser', {
             oldUsername,
             oldPassword,
             newUsername,
             newPassword
         });
+
+        if (response && response.success) {
+            // Update internal credentials to match new credentials
+            const oldUsername_ = this.username;
+            this.username = newUsername;
+            this.password = newPassword;
+
+            // Clear old session from session manager
+            if (this.sessionManager) {
+                try {
+                    await this.sessionManager.deleteSession(this.baseURL, oldUsername_);
+                } catch (error) {
+                    console.warn('[3xui-api-client] Could not delete old session:', error.message);
+                }
+            }
+
+            // Re-authenticate with new credentials to ensure session is valid
+            try {
+                await this.login(true); // Force refresh with new credentials
+            } catch (error) {
+                // If login fails after credential change, restore old credentials and re-throw
+                this.username = oldUsername;
+                this.password = oldPassword;
+                if (this.sessionManager) {
+                    await this.sessionManager.deleteSession(this.baseURL, newUsername);
+                }
+                throw new Error(`Credential update succeeded but re-authentication failed: ${error.message}`);
+            }
+        }
+
+        return response;
     }
 
     /**
      * Restart the panel
      */
     restartPanel() {
-        return this._request('post', '/panel/setting/restartPanel');
+        return this._request('post', '/panel/api/setting/restartPanel');
     }
 
     /**
      * Get default settings
      */
     getDefaultSettings() {
-        return this._request('post', '/panel/setting/defaultSettings');
+        return this._request('post', '/panel/api/setting/defaultSettings');
     }
 
     /**
      * Get default Xray JSON config
      */
     getDefaultJsonConfig() {
-        return this._request('get', '/panel/setting/getDefaultJsonConfig');
+        return this._request('get', '/panel/api/setting/getDefaultJsonConfig');
     }
 
     // ===========================================
@@ -861,45 +1483,57 @@ class ThreeXUI {
      * Get Xray configuration
      */
     getXrayConfig() {
-        return this._request('post', '/panel/xray/');
+        return this._request('post', '/panel/api/xray/');
     }
 
     /**
      * Update Xray configuration
-     * @param {string} config - Xray configuration content
+     * @param {string|object} config - Xray configuration content (JSON string or object)
      */
     updateXrayConfig(config) {
-        return this._request('post', '/panel/xray/update', { content: config });
+        // Parse JSON string to object before sending
+        if (typeof config === 'string') {
+            try {
+                config = JSON.parse(config);
+            } catch (error) {
+                throw new Error(`updateXrayConfig: Invalid JSON: ${error.message}`);
+            }
+        }
+        // Validate it's an object
+        if (!config || typeof config !== 'object') {
+            throw new Error('updateXrayConfig: config must be a valid JSON object or string');
+        }
+        return this._request('post', '/panel/api/xray/update', { content: JSON.stringify(config) });
     }
 
     /**
      * Manage WARP
-     * @param {string} action - Action to perform (data, del, config, reg, license)
+     * @param {string} action - Action to perform (data, del, config, reg, changeIp, license, interval)
      * @param {Object} [data] - Additional data for the action
      */
     manageWarp(action, data = {}) {
-        return this._request('post', `/panel/xray/warp/${action}`, data);
+        return this._request('post', `/panel/api/xray/warp/${action}`, data);
     }
 
     /**
      * Get outbound traffic statistics
      */
     getOutboundsTraffic() {
-        return this._request('get', '/panel/xray/getOutboundsTraffic');
+        return this._request('get', '/panel/api/xray/getOutboundsTraffic');
     }
 
     /**
      * Reset outbound traffic statistics
      */
     resetOutboundsTraffic() {
-        return this._request('post', '/panel/xray/resetOutboundsTraffic');
+        return this._request('post', '/panel/api/xray/resetOutboundsTraffic');
     }
 
     /**
      * Get Xray execution result
      */
     getXrayResult() {
-        return this._request('get', '/panel/xray/getXrayResult');
+        return this._request('get', '/panel/api/xray/getXrayResult');
     }
 
     // Security Methods