3xui-api-client 2.1.1 → 3.0.1

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.1] - 2026-06-07
+
+### Fixed
+- Re-release as 3.0.1 — version 3.0.0 was previously published and unpublished, making it permanently blocked on npm.
+
+## [3.0.0] - 2026-06-07
+
+### Added
+- 🔑 **API Token Authentication** — Pass `token` or `apiToken` in options to authenticate via Bearer token instead of cookie-based login. Resolves compatibility with 3x-ui v3.0.2+ where the legacy login mechanism changed. ([#1](https://github.com/iamhelitha/3xui-api-client/issues/1))
+- 🆕 **Object-style constructor** — `new ThreeXUI(url, { username, password, token })` as an alternative to the positional `(url, user, pass)` signature.
+- 📡 **48 new Modern API routes** (3x-ui v2.x/v3.x endpoints):
+  - **Clients** (25 routes): `getClients`, `getPagedClients`, `getClient`, `getClientTraffic`, `getSubLinks`, `getClientLinks`, `addModernClient`, `updateModernClient`, `deleteModernClient`, `attachClientToInbounds`, `detachClientFromInbounds`, `resetAllModernClientTraffics`, `deleteDepletedModernClients`, bulk operations (`bulkAdjust`, `bulkDel`, `bulkCreate`, `bulkAttach`, `bulkDetach`, `bulkResetTraffic`), `resetModernClientTrafficByEmail`, `updateModernClientTrafficByEmail`, `getModernClientIps`, `clearModernClientIps`, `getOnlines`, `getModernLastOnline`
+  - **Client Groups** (7 routes): `getGroups`, `getGroupEmails`, `createGroup`, `renameGroup`, `deleteGroup`, `bulkAddGroups`, `bulkRemoveGroups`
+  - **Nodes** (9 routes): `getNodes`, `getNode`, `getNodeHistory`, `addNode`, `updateNode`, `deleteNode`, `setNodeEnable`, `testNode`, `probeNode`
+  - **Custom Geo** (7 routes): `getCustomGeos`, `getGeoAliases`, `addCustomGeo`, `updateCustomGeo`, `deleteCustomGeo`, `downloadCustomGeo`, `updateAllCustomGeo`
+
+### Changed
+- Constructor signature extended to accept an options object as the second argument (fully backward compatible — existing `(url, user, pass)` usage is unchanged).
+- `_request()` and `login()` skip cookie-based auth flow when a token is configured.
+- `isSessionValid()` returns `true` immediately when token auth is active.
+
+### Fixed
+- ESLint errors (trailing whitespace, missing curly braces) introduced in new route additions.
+- Indentation inconsistency in TypeScript declarations (`updateClientWithCredentials`).
+
+### Backward Compatibility
+- All existing `(url, username, password)` constructor calls continue to work without any changes.
+- All 55 original API routes are unchanged.
+- Verified against older 3x-ui servers — cookie-based login, session management, and all core routes function identically.
+
 ## [2.1.1] - 2025-11-30
 
 ### Fixed

package/index.d.ts

@@ -16,6 +16,8 @@ declare module '3xui-api-client' {
     isDevelopment?: boolean;
     enableCSP?: boolean;
     userAgent?: string;
+    token?: string;
+    apiToken?: string;
   }
 
   export interface LoginResponse {
@@ -226,6 +228,7 @@ declare module '3xui-api-client' {
 
   export default class ThreeXUI {
     constructor(baseURL: string, username: string, password: string, options?: ThreeXUIOptions);
+    constructor(baseURL: string, options: ThreeXUIOptions);
     
     // Authentication
     login(forceRefresh?: boolean): Promise<LoginResponse>;
@@ -252,14 +255,82 @@ declare module '3xui-api-client' {
 
     // Enhanced Client Management
     addClientWithCredentials(inboundId: number, protocol: string, options?: CredentialOptions): Promise<any>;
-  updateClientWithCredentials(clientId: string, inboundId: number, options?: CredentialOptions): Promise<any>;
+    updateClientWithCredentials(clientId: string, inboundId: number, options?: CredentialOptions): Promise<any>;
 
     // Session Management
     getSessionStats(): Promise<any>;
     clearAllSessions(): Promise<void>;
     isSessionValid(): Promise<boolean>;
 
+    // ===========================================
+    // Modern API Methods (3X-UI >= 2.x)
+    // ===========================================
+
+    // --- Clients ---
+    getClients(): Promise<any>;
+    getPagedClients(params?: {
+        page?: number;
+        size?: number;
+        sort?: string;
+        order?: 'asc' | 'desc';
+        email?: string;
+    }): Promise<any>;
+    getClient(email: string): Promise<any>;
+    getClientTraffic(email: string): Promise<any>;
+    getSubLinks(subId: string): Promise<any>;
+    getClientLinks(email: string): Promise<any>;
+    addModernClient(data: any): Promise<any>;
+    updateModernClient(email: string, data: any): Promise<any>;
+    deleteModernClient(email: string): Promise<any>;
+    attachClientToInbounds(email: string, data: any): Promise<any>;
+    detachClientFromInbounds(email: string, data: any): Promise<any>;
+    resetAllModernClientTraffics(): Promise<any>;
+    deleteDepletedModernClients(): Promise<any>;
+    bulkAdjustModernClients(data: any): Promise<any>;
+    bulkDeleteModernClients(data: any): Promise<any>;
+    bulkCreateModernClients(data: any): Promise<any>;
+    bulkAttachModernClients(data: any): Promise<any>;
+    bulkDetachModernClients(data: any): Promise<any>;
+    bulkResetTrafficModernClients(data: any): Promise<any>;
+    resetModernClientTrafficByEmail(email: string): Promise<any>;
+    updateModernClientTrafficByEmail(email: string, data: any): Promise<any>;
+    getModernClientIps(email: string): Promise<any>;
+    clearModernClientIps(email: string): Promise<any>;
+    getOnlines(): Promise<any>;
+    getModernLastOnline(): Promise<any>;
+
+    // --- Client Groups ---
+    getGroups(): Promise<any>;
+    getGroupEmails(groupName: string): Promise<any>;
+    createGroup(data: any): Promise<any>;
+    renameGroup(data: any): Promise<any>;
+    deleteGroup(data: any): Promise<any>;
+    bulkAddGroups(data: any): Promise<any>;
+    bulkRemoveGroups(data: any): Promise<any>;
+
+    // --- Nodes ---
+    getNodes(): Promise<any>;
+    getNode(id: number | string): Promise<any>;
+    getNodeHistory(id: number | string, metric: string, bucket: string): Promise<any>;
+    addNode(data: any): Promise<any>;
+    updateNode(id: number | string, data: any): Promise<any>;
+    deleteNode(id: number | string): Promise<any>;
+    setNodeEnable(id: number | string): Promise<any>;
+    testNode(data: any): Promise<any>;
+    probeNode(id: number | string): Promise<any>;
+
+    // --- Custom Geo ---
+    getCustomGeos(): Promise<any>;
+    getGeoAliases(): Promise<any>;
+    addCustomGeo(data: any): Promise<any>;
+    updateCustomGeo(id: string | number, data: any): Promise<any>;
+    deleteCustomGeo(id: string | number): Promise<any>;
+    downloadCustomGeo(id: string | number): Promise<any>;
+    updateAllCustomGeo(): Promise<any>;
+
+    // ===========================================
     // Original API Methods
+    // ===========================================
     getInbounds(): Promise<any>;
     getInbound(id: number): Promise<any>;
     addInbound(inboundConfig: InboundConfig): Promise<any>;

package/index.js

@@ -32,16 +32,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,8 +47,32 @@ 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.options = options;
         this.loginMutex = false; // Add mutex to prevent concurrent logins
@@ -81,15 +99,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 +144,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')) {
@@ -238,11 +270,13 @@ class ThreeXUI {
     }
 
     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();
+        // 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 {
@@ -257,6 +291,9 @@ class ThreeXUI {
             return response.data;
         } catch (error) {
             if (error.response && error.response.status === 401) {
+                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
                 if (this.loginRetryCount < this.maxLoginRetries) {
                     await this._ensureAuthenticated(true); // Force refresh
@@ -533,12 +570,322 @@ 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) {
+        return this._request('post', '/panel/api/clients/add', data);
+    }
+
+    /**
+     * 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) {
+        return this._request('post', `/panel/api/clients/update/${encodeURIComponent(email)}`, data);
+    }
+
+    /**
+     * 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)}`);
+    }
+
+    setNodeEnable(id) {
+        return this._request('post', `/panel/api/nodes/setEnable/${encodeURIComponent(id)}`);
+    }
+
+    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)
     // ===========================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3xui-api-client",
-  "version": "2.1.1",
+  "version": "3.0.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",