3xui-api-client 3.1.1 → 3.1.2

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.1.2] - 2026-06-30
+
+### Fixed
+- 🔴 **Session recovery for non-401 stale sessions** ([#10](https://github.com/iamhelitha/3xui-api-client/issues/10)) - Automatic re-login is no longer keyed strictly to HTTP `401`. Some 3x-ui forks reject a stale cookie session with `404` (the auth-gated route falls through to a generic not-found handler when not logged in) or by returning an HTML login page with `200`. The client now treats all three as a lost session and performs one bounded, backed-off forced re-login + retry — reusing the existing `maxLoginRetries` / `loginRetryBackoff` budget. Token auth is unchanged: a `401` still throws a clear "token invalid" error and a `404` surfaces unchanged as a genuine missing resource.
+- 🐛 **`getClientIps(email)` now returns a real array** ([#12](https://github.com/iamhelitha/3xui-api-client/issues/12)) - The legacy panel returns `obj` as a JSON-encoded string (e.g. `'["1.2.3.4"]'`) rather than an actual array. The client now parses it internally so `obj` is always a `string[]` (empty array when the panel has no IP record), matching every other list-returning endpoint. The TypeScript signature is now `Promise<ModernApiResponse<string[]>>`.
+
+### Changed
+- 📖 **`getCPUHistory(bucket)` documentation/types corrected** ([#11](https://github.com/iamhelitha/3xui-api-client/issues/11)) - The previously documented `{ history: [{ timestamp, usage }] }` shape was assumed and never verified. The endpoint actually returns the standard `{ success, msg, obj }` envelope where `obj` is an array of exactly 60 `{ cpu: number; t: number }` points (`cpu` is a plain percentage number, `t` is epoch **seconds**; total span is `60 * bucket` seconds). The TypeScript signature is now `Promise<ModernApiResponse<Array<{ cpu: number; t: number }>>>`. No runtime change — the method already returned the real envelope.
+
 ## [3.1.1] - 2026-06-18
 
 ### Changed

package/index.d.ts

@@ -581,7 +581,14 @@ declare module '3xui-api-client' {
     deleteClientByEmail(inboundId: number, email: string): Promise<any>;
     getClientTrafficsByEmail(email: string): Promise<any>;
     getClientTrafficsById(id: string): Promise<any>;
-    getClientIps(email: string): Promise<any>;
+    /**
+     * Get the list of IP addresses recorded for a client.
+     *
+     * The legacy panel returns `obj` as a JSON-encoded string; this client
+     * parses it internally so `obj` is always a real `string[]` (empty when
+     * the panel has no IP record for the client).
+     */
+    getClientIps(email: string): Promise<ModernApiResponse<string[]>>;
     clearClientIps(email: string): Promise<any>;
     resetClientTraffic(inboundId: number, email: string): Promise<any>;
     resetAllTraffics(): Promise<any>;
@@ -595,9 +602,15 @@ declare module '3xui-api-client' {
     getServerStatus(): Promise<any>;
     /**
      * Get CPU usage history.
+     *
+     * Returns the standard `{ success, msg, obj }` envelope. `obj` is an array
+     * of exactly 60 points, each `{ cpu, t }` where `cpu` is the usage
+     * percentage (a plain number, no trailing `%`) and `t` is the epoch time in
+     * seconds. The total span covered is `60 * bucket` seconds.
+     *
      * @param bucket - Bucket size in seconds. Must be one of: 2, 30, 60, 120, 180, 300 (default: 60)
      */
-    getCPUHistory(bucket?: number): Promise<any>;
+    getCPUHistory(bucket?: number): Promise<ModernApiResponse<Array<{ cpu: number; t: number }>>>;
     getXrayVersion(): Promise<any>;
     getConfigJson(): Promise<any>;
     /**

package/index.js

@@ -409,38 +409,110 @@ class ThreeXUI {
                 data,
                 headers: { ...this._buildRequestHeaders(method), ...extraHeaders }
             });
+
+            // Some panels answer a stale/expired session with HTTP 200 plus an
+            // HTML login page (a redirect-then-200) instead of an explicit
+            // 401/404. For cookie auth, treat that HTML body where JSON was
+            // expected as a lost session and recover transparently.
+            if (!this.token && this._looksLikeLoginPage(response.data)) {
+                return await this._retryAfterRelogin(method, path, data, extraHeaders);
+            }
+
             // Reset retry counter on successful request
             this.loginRetryCount = 0;
             return response.data;
         } catch (error) {
-            if (error.response && error.response.status === 401) {
+            if (this._isStaleSessionError(error)) {
                 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));
+                    // Token auth: a 401 means the token itself is invalid, so
+                    // retrying will not help. A 404 is a genuine missing
+                    // resource (the token never goes "stale"), so surface it
+                    // unchanged.
+                    if (error.response && error.response.status === 401) {
+                        throw new Error('API Token is invalid or expired. Please check your credentials.');
                     }
-                    await this._ensureAuthenticated(true); // Force refresh
-                    const response = await this.api.request({
-                        method,
-                        url: path,
-                        data,
-                        headers: { ...this._buildRequestHeaders(method), ...extraHeaders }
-                    });
-                    return response.data;
-                } else {
-                    throw new Error('Maximum login retry attempts exceeded. Check your credentials.');
+                    throw error;
                 }
+                // Cookie session may have expired. Different 3x-ui versions/forks
+                // are inconsistent about the signal (401, 404, or an HTML login
+                // page), so we recover the same way for each: one bounded,
+                // backed-off forced re-login + retry.
+                return await this._retryAfterRelogin(method, path, data, extraHeaders);
             }
             throw error;
         }
     }
 
+    /**
+     * Decide whether an error from an authenticated request indicates a lost
+     * cookie session that warrants a forced re-login. Different 3x-ui forks
+     * reject a stale session with 401, with 404 (the auth-gated route falls
+     * through to a generic not-found handler when not logged in), or by
+     * returning an HTML login page where JSON was expected.
+     *
+     * @param {*} error - Error thrown by the axios request
+     * @returns {boolean} True if the error looks like a session failure
+     */
+    _isStaleSessionError(error) {
+        if (!error || !error.response) {
+            return false;
+        }
+        const status = error.response.status;
+        if (status === 401 || status === 404) {
+            return true;
+        }
+        return this._looksLikeLoginPage(error.response.data);
+    }
+
+    /**
+     * Heuristic for a panel returning its HTML login page in place of the
+     * expected JSON envelope. Every authenticated endpoint here returns JSON
+     * (or, for getDb, a "SQLite format 3" string), so an HTML document body is
+     * itself the anomaly that signals a redirect to the login screen.
+     *
+     * @param {*} data - Response body
+     * @returns {boolean} True if the body looks like an HTML login page
+     */
+    _looksLikeLoginPage(data) {
+        if (typeof data !== 'string') {
+            return false;
+        }
+        const trimmed = data.trim().toLowerCase();
+        return trimmed.startsWith('<!doctype html') || trimmed.startsWith('<html');
+    }
+
+    /**
+     * Force a fresh login and retry the original request once, honoring the
+     * shared retry budget and backoff. Used for cookie-auth session recovery
+     * regardless of whether the panel signalled with 401, 404, or a login-page
+     * body, so consumers never have to reimplement session recovery themselves.
+     *
+     * @param {string} method - HTTP method
+     * @param {string} path - Request path
+     * @param {Object} data - Request body
+     * @param {Object} extraHeaders - Additional headers to merge
+     * @returns {Promise<*>} The retried response data
+     */
+    async _retryAfterRelogin(method, path, data, extraHeaders) {
+        // Bound the recovery to a single retry budget to avoid login storms
+        // (e.g. tripping fail2ban) when many instances race to re-authenticate.
+        if (this.loginRetryCount >= this.maxLoginRetries) {
+            throw new Error('Maximum login retry attempts exceeded. Check your credentials.');
+        }
+        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,
+            headers: { ...this._buildRequestHeaders(method), ...extraHeaders }
+        });
+        this.loginRetryCount = 0;
+        return response.data;
+    }
+
     /**
      * Build per-request headers, including the JSON content type for POST
      * bodies and (on cookie-authenticated sessions against newer
@@ -1151,8 +1223,44 @@ class ThreeXUI {
         return this._request('get', `/panel/api/inbounds/getClientTrafficsById/${id}`);
     }
 
-    getClientIps(email) {
-        return this._request('post', `/panel/api/inbounds/clientIps/${email}`);
+    /**
+     * Get the list of IP addresses recorded for a client.
+     *
+     * The legacy panel returns `obj` as a JSON-encoded string (e.g.
+     * `'["1.2.3.4"]'`) rather than an actual array, unlike every other
+     * list-returning endpoint. We parse it internally so callers get
+     * `obj: string[]` directly. If the panel reports "No IP Record" (or any
+     * non-array/unparseable value), `obj` is normalized to an empty array.
+     *
+     * @param {string} email - Client email
+     * @returns {Promise<{success: boolean, msg: string, obj: string[]}>}
+     */
+    async getClientIps(email) {
+        const response = await this._request('post', `/panel/api/inbounds/clientIps/${email}`);
+        return { ...response, obj: this._parseClientIps(response && response.obj) };
+    }
+
+    /**
+     * Normalize the `obj` field returned by clientIps into a real array of IP
+     * strings. The panel may return a JSON-encoded array string, an already
+     * parsed array, or a placeholder message like "No IP Record".
+     *
+     * @param {*} obj - Raw `obj` value from the clientIps response
+     * @returns {string[]} Parsed list of IP addresses (empty when none)
+     */
+    _parseClientIps(obj) {
+        if (Array.isArray(obj)) {
+            return obj;
+        }
+        if (typeof obj === 'string') {
+            try {
+                const parsed = JSON.parse(obj);
+                return Array.isArray(parsed) ? parsed : [];
+            } catch {
+                return [];
+            }
+        }
+        return [];
     }
 
     clearClientIps(email) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3xui-api-client",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "Node.js API client for the 3x-ui panel (VLESS, VMess, Trojan, Shadowsocks, WireGuard, Reality) with automatic session management, credential generation, and full REST API coverage",
   "main": "index.js",
   "types": "index.d.ts",