3xui-api-client 2.0.0 → 2.1.1

package/index.d.ts

@@ -11,6 +11,11 @@ declare module '3xui-api-client' {
     sessionManager?: SessionManager | SessionConfig;
     autoGenerateCredentials?: boolean;
     timeout?: number;
+    maxRequestsPerMinute?: number;
+    maxLoginAttemptsPerHour?: number;
+    isDevelopment?: boolean;
+    enableCSP?: boolean;
+    userAgent?: string;
   }
 
   export interface LoginResponse {
@@ -237,9 +242,17 @@ declare module '3xui-api-client' {
     generateRealityKeys(): RealityKeys;
     generatePort(min?: number, max?: number): number;
     validateCredentials(credentials: any, protocol: string): ValidationResult;
+    
+    // Security helpers
+    getSecurityStats(): any;
+    clearBlockedIPs(): void;
+    validateCredentialStrength(credential: string, type: 'password' | 'uuid' | 'port'): { isValid: boolean; issues: string[]; strength: 'weak' | 'medium' | 'strong' };
+    generateSecureToken(): string;
+    setDevelopmentMode(enabled: boolean): void;
 
     // Enhanced Client Management
     addClientWithCredentials(inboundId: number, protocol: string, options?: CredentialOptions): Promise<any>;
+  updateClientWithCredentials(clientId: string, inboundId: number, options?: CredentialOptions): Promise<any>;
 
     // Session Management
     getSessionStats(): Promise<any>;
@@ -265,11 +278,10 @@ declare module '3xui-api-client' {
     deleteDepletedClients(inboundId: number): Promise<any>;
     getOnlineClients(): Promise<any>;
     createBackup(): Promise<any>;
+    backupToTgBot(): Promise<any>;
 
-    // Static exports
-    static CredentialGenerator: typeof CredentialGenerator;
-    static SessionManager: typeof SessionManager;
-    static createSessionManager: (options?: SessionConfig) => SessionManager;
+    // Server Management
+    getServerStatus(): Promise<any>;
   }
 
   // ===========================================
@@ -284,7 +296,6 @@ declare module '3xui-api-client' {
     static generateWireGuardKeys(): WireGuardKeys;
     static generateRealityKeys(): RealityKeys;
     static generateUsername(prefix?: string): string;
-    static generateEmail(domain?: string): string;
     static getRecommendedShadowsocksCipher(): string;
     static getShadowsocksCipherMethods(): string[];
     static generatePort(min?: number, max?: number): number;
@@ -413,4 +424,13 @@ declare module '3xui-api-client' {
       shadowsocks(options?: any): BuilderConfig;
     };
   }
-} 
+
+  // Optional: expose security helpers for advanced users
+  export const SecurityEnhancer: {
+    InputValidator: any;
+    SecureHeaders: any;
+    SecurityMonitor: any;
+    CredentialSecurity: any;
+    ErrorSecurity: any;
+  };
+}

package/index.js

@@ -45,6 +45,14 @@ class ThreeXUI {
 
         // Apply security validations
         this.baseURL = InputValidator.validateURL(baseURL);
+
+        // Warning for common configuration error
+        if (this.baseURL.endsWith('/panel') || this.baseURL.endsWith('/panel/')) {
+            console.warn('WARNING: baseURL should NOT end with "/panel". The library appends this automatically. Please remove it from your configuration.');
+            // Auto-fix for better user experience
+            this.baseURL = this.baseURL.replace(/\/panel\/?$/, '');
+        }
+
         this.username = InputValidator.validateUsername(username);
         this.password = InputValidator.validatePassword(password);
         this.cookie = null;
@@ -174,6 +182,7 @@ class ThreeXUI {
                 return {
                     success: true,
                     fromCache: false,
+                    cookie: this.cookie, // Explicitly return the cookie
                     headers: response.headers,
                     data: response.data
                 };
@@ -206,6 +215,12 @@ class ThreeXUI {
      * Logout and clear session
      */
     async logout() {
+        try {
+            await this._request('get', '/logout');
+        } catch {
+            // Ignore server-side logout errors, proceed to clear local session
+        }
+
         this.cookie = null;
         delete this.api.defaults.headers.Cookie;
 
@@ -214,6 +229,14 @@ class ThreeXUI {
         }
     }
 
+    /**
+     * Check if Two-Factor Authentication is enabled
+     * @returns {Promise<Object>} 2FA status
+     */
+    getTwoFactorEnable() {
+        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)) {
@@ -436,7 +459,8 @@ class ThreeXUI {
             const processedOptions = {
                 email: options.email || existingClients[clientIndex].email,
                 limitIp: options.limitIp !== undefined ? options.limitIp : existingClients[clientIndex].limitIp,
-                totalGB: options.totalGB ? options.totalGB * 1024 * 1024 * 1024 : existingClients[clientIndex].totalGB,
+                // 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,
@@ -466,7 +490,7 @@ class ThreeXUI {
                 ...result,
                 updatedOptions: processedOptions,
                 conversions: {
-                    totalGB: options.totalGB ? `${options.totalGB}GB → ${processedOptions.totalGB} bytes` : 'unchanged',
+                    totalGB: options.totalGB !== undefined ? `${options.totalGB}GB` : 'unchanged',
                     expiryDays: options.expiryDays ? `${options.expiryDays} days → ${new Date(processedOptions.expiryTime).toISOString()}` : 'unchanged'
                 }
             };
@@ -544,6 +568,21 @@ class ThreeXUI {
         return this._request('post', `/panel/api/inbounds/update/${id}`, validatedConfig);
     }
 
+    /**
+     * Import inbounds
+     * @param {Array} inbounds - Array of inbound configurations
+     */
+    importInbounds(inbounds) {
+        return this._request('post', '/panel/api/inbounds/import', { inbounds });
+    }
+
+    /**
+     * Get last online time for clients
+     */
+    getLastOnline() {
+        return this._request('post', '/panel/api/inbounds/lastOnline');
+    }
+
     // Clients
     addClient(clientConfig) {
         // Validate client configuration for security
@@ -561,6 +600,24 @@ class ThreeXUI {
         return this._request('post', `/panel/api/inbounds/updateClient/${clientId}`, validatedConfig);
     }
 
+    /**
+     * Update client traffic limit and expiry by email
+     * @param {string} email - Client email
+     * @param {Object} trafficConfig - Traffic configuration (totalGB, expiryTime)
+     */
+    updateClientTraffic(email, trafficConfig) {
+        return this._request('post', `/panel/api/inbounds/updateClientTraffic/${email}`, trafficConfig);
+    }
+
+    /**
+     * Delete client by email
+     * @param {number} inboundId - Inbound ID
+     * @param {string} email - Client email
+     */
+    deleteClientByEmail(inboundId, email) {
+        return this._request('post', `/panel/api/inbounds/${inboundId}/delClientByEmail/${email}`);
+    }
+
     getClientTrafficsByEmail(email) {
         return this._request('get', `/panel/api/inbounds/getClientTraffics/${email}`);
     }
@@ -603,6 +660,248 @@ class ThreeXUI {
         return this._request('get', '/panel/api/inbounds/createbackup');
     }
 
+    /**
+     * Trigger sending a backup to Telegram bot admins
+     */
+    backupToTgBot() {
+        return this._request('post', '/panel/api/backuptotgbot');
+    }
+
+    // ===========================================
+    // SERVER MANAGEMENT
+    // ===========================================
+
+    /**
+     * Get server status (CPU, RAM, etc.)
+     */
+    getServerStatus() {
+        return this._request('get', '/panel/api/server/status');
+    }
+
+    /**
+     * Get CPU usage history
+     * @param {string} bucket - Time bucket (e.g., 'min', 'hour')
+     */
+    getCPUHistory(bucket = 'min') {
+        return this._request('get', `/panel/api/server/cpuHistory/${bucket}`);
+    }
+
+    /**
+     * Get current Xray version
+     */
+    getXrayVersion() {
+        return this._request('get', '/panel/api/server/getXrayVersion');
+    }
+
+    /**
+     * Get Xray config as JSON
+     */
+    getConfigJson() {
+        return this._request('get', '/panel/api/server/getConfigJson');
+    }
+
+    /**
+     * Download database
+     */
+    getDb() {
+        return this._request('get', '/panel/api/server/getDb');
+    }
+
+    /**
+     * Stop Xray core service
+     */
+    stopXrayService() {
+        return this._request('post', '/panel/api/server/stopXrayService');
+    }
+
+    /**
+     * Restart Xray core service
+     */
+    restartXrayService() {
+        return this._request('post', '/panel/api/server/restartXrayService');
+    }
+
+    /**
+     * Install specific Xray version
+     * @param {string} version - Version to install
+     */
+    installXray(version) {
+        return this._request('post', `/panel/api/server/installXray/${version}`);
+    }
+
+    /**
+     * Get panel logs
+     * @param {number} count - Number of logs to retrieve
+     */
+    getPanelLogs(count = 100) {
+        return this._request('post', `/panel/api/server/logs/${count}`);
+    }
+
+    /**
+     * Get Xray logs
+     * @param {number} count - Number of logs to retrieve
+     */
+    getXrayLogs(count = 100) {
+        return this._request('post', `/panel/api/server/xraylogs/${count}`);
+    }
+
+    /**
+     * Update GeoIP/GeoSite files
+     * @param {string} [fileName] - Specific file to update (optional)
+     */
+    updateGeofile(fileName) {
+        const url = fileName
+            ? `/panel/api/server/updateGeofile/${fileName}`
+            : '/panel/api/server/updateGeofile';
+        return this._request('post', url);
+    }
+
+    /**
+     * Import database
+     * @param {FormData} formData - FormData containing the database file
+     */
+    async importDB(formData) {
+        // Ensure authenticated before direct API call
+        if (!this.cookie) {
+            await this._ensureAuthenticated();
+        }
+        // Use direct api call to handle multipart/form-data correctly
+        return this.api.post('/panel/api/server/importDB', formData);
+    }
+
+    // ===========================================
+    // SERVER-SIDE GENERATORS
+    // ===========================================
+
+    getNewUUID() {
+        return this._request('get', '/panel/api/server/getNewUUID');
+    }
+
+    getNewX25519Cert() {
+        return this._request('get', '/panel/api/server/getNewX25519Cert');
+    }
+
+    getNewmldsa65() {
+        return this._request('get', '/panel/api/server/getNewmldsa65');
+    }
+
+    getNewmlkem768() {
+        return this._request('get', '/panel/api/server/getNewmlkem768');
+    }
+
+    getNewVlessEnc() {
+        return this._request('get', '/panel/api/server/getNewVlessEnc');
+    }
+
+    getNewEchCert() {
+        return this._request('post', '/panel/api/server/getNewEchCert');
+    }
+
+    // ===========================================
+    // PANEL SETTINGS
+    // ===========================================
+
+    /**
+     * Get all panel settings
+     */
+    getAllSettings() {
+        return this._request('post', '/panel/setting/all');
+    }
+
+    /**
+     * Update panel settings
+     * @param {Object} settings - Settings to update
+     */
+    updateSetting(settings) {
+        return this._request('post', '/panel/setting/update', settings);
+    }
+
+    /**
+     * Update admin username and password
+     * @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', {
+            oldUsername,
+            oldPassword,
+            newUsername,
+            newPassword
+        });
+    }
+
+    /**
+     * Restart the panel
+     */
+    restartPanel() {
+        return this._request('post', '/panel/setting/restartPanel');
+    }
+
+    /**
+     * Get default settings
+     */
+    getDefaultSettings() {
+        return this._request('post', '/panel/setting/defaultSettings');
+    }
+
+    /**
+     * Get default Xray JSON config
+     */
+    getDefaultJsonConfig() {
+        return this._request('get', '/panel/setting/getDefaultJsonConfig');
+    }
+
+    // ===========================================
+    // XRAY CONFIGURATION
+    // ===========================================
+
+    /**
+     * Get Xray configuration
+     */
+    getXrayConfig() {
+        return this._request('post', '/panel/xray/');
+    }
+
+    /**
+     * Update Xray configuration
+     * @param {string} config - Xray configuration content
+     */
+    updateXrayConfig(config) {
+        return this._request('post', '/panel/xray/update', { content: config });
+    }
+
+    /**
+     * Manage WARP
+     * @param {string} action - Action to perform (data, del, config, reg, license)
+     * @param {Object} [data] - Additional data for the action
+     */
+    manageWarp(action, data = {}) {
+        return this._request('post', `/panel/xray/warp/${action}`, data);
+    }
+
+    /**
+     * Get outbound traffic statistics
+     */
+    getOutboundsTraffic() {
+        return this._request('get', '/panel/xray/getOutboundsTraffic');
+    }
+
+    /**
+     * Reset outbound traffic statistics
+     */
+    resetOutboundsTraffic() {
+        return this._request('post', '/panel/xray/resetOutboundsTraffic');
+    }
+
+    /**
+     * Get Xray execution result
+     */
+    getXrayResult() {
+        return this._request('get', '/panel/xray/getXrayResult');
+    }
+
     // Security Methods
 
     /**
@@ -652,4 +951,63 @@ ThreeXUI.CredentialGenerator = CredentialGenerator;
 ThreeXUI.SessionManager = SessionManager;
 ThreeXUI.createSessionManager = createSessionManager;
 
-module.exports = ThreeXUI;
+module.exports = ThreeXUI;
+
+// Define lazy getters to avoid circular dependencies
+Object.defineProperties(module.exports, {
+    // Web middleware helpers
+    createExpressMiddleware: {
+        enumerable: true,
+        get: () => require('./src/middleware/WebMiddleware').createExpressMiddleware
+    },
+    withThreeXUI: {
+        enumerable: true,
+        get: () => require('./src/middleware/WebMiddleware').withThreeXUI
+    },
+    createReactHook: {
+        enumerable: true,
+        get: () => require('./src/middleware/WebMiddleware').createReactHook
+    },
+    createNextjsRoutes: {
+        enumerable: true,
+        get: () => require('./src/middleware/WebMiddleware').createNextjsRoutes
+    },
+    SessionConfig: {
+        enumerable: true,
+        get: () => require('./src/middleware/WebMiddleware').SessionConfig
+    },
+    // Protocol builders
+    ProtocolBuilder: {
+        enumerable: true,
+        get: () => require('./src/builders/ProtocolBuilders').ProtocolBuilder
+    },
+    VLESSBuilder: {
+        enumerable: true,
+        get: () => require('./src/builders/ProtocolBuilders').VLESSBuilder
+    },
+    VMESSBuilder: {
+        enumerable: true,
+        get: () => require('./src/builders/ProtocolBuilders').VMESSBuilder
+    },
+    TrojanBuilder: {
+        enumerable: true,
+        get: () => require('./src/builders/ProtocolBuilders').TrojanBuilder
+    },
+    ShadowsocksBuilder: {
+        enumerable: true,
+        get: () => require('./src/builders/ProtocolBuilders').ShadowsocksBuilder
+    },
+    WireGuardBuilder: {
+        enumerable: true,
+        get: () => require('./src/builders/ProtocolBuilders').WireGuardBuilder
+    },
+    BaseBuilder: {
+        enumerable: true,
+        get: () => require('./src/builders/ProtocolBuilders').BaseBuilder
+    },
+    // Security helpers
+    SecurityEnhancer: {
+        enumerable: true,
+        get: () => require('./src/security/SecurityEnhancer')
+    }
+});

package/index.mjs

@@ -1,5 +1,5 @@
-import { createRequire } from 'module';
-const require = createRequire(import.meta.url);
-const ThreeXUI = require('./index.js');
-
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const ThreeXUI = require('./index.js');
+
 export default ThreeXUI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3xui-api-client",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "A Node.js client library for 3x-ui panel API with built-in credential generation, session management, and web integration support",
   "main": "index.js",
   "types": "index.d.ts",