3xui-api-client 3.1.1 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.2.0] - 2026-08-26
+
+### Added
+- 🆕 **`testOutbound(outbound, options)`** - Test connectivity through an outbound configuration via `/panel/api/xray/testOutbound`. The endpoint reads its body as `application/x-www-form-urlencoded` rather than JSON (a JSON body always fails with `"outbound parameter is required"`, regardless of field name or nesting) - the `outbound` field must hold the JSON-stringified outbound object. Accepts an object or a pre-stringified outbound, plus optional `allOutbounds` (to resolve `sockopt.dialerProxy` dependencies between outbounds) and `mode`. `freedom`/`blackhole`-type outbounds return `success: false` with a clear `error` since there's nothing to dial through - that's expected panel behavior, not a request failure. Reverse-engineered and verified against `ghcr.io/mhsanaei/3x-ui:v3.7.0`.
+
+### Fixed
+- 🔴 **Forced re-login could fail with a masking `403`** - When `_request()` classified a response as a stale session (`401`/`404`/HTML login page) and forced a re-login via `_retryAfterRelogin`, the axios instance still carried the *previous* session's cookie as a default header. Some panels' `/csrf-token` endpoint does not reissue a `Set-Cookie` when a cookie is already attached to the request, so `_getCsrfToken()` found nothing fresh to pair with the CSRF token and returned `null`. The retried `/login` POST then went out without `X-CSRF-Token` and the panel rejected it with `403` — masking the original error (e.g. a genuine `404`) behind an unrelated "login failed" exception. `login(forceRefresh)` now clears the stale cookie/CSRF token before the handshake, so a forced re-login always starts from a clean, anonymous state. Found via local Docker testing against `ghcr.io/mhsanaei/3x-ui:v3.7.0`.
+- 🔴 **`addClientWithCredentials`/`updateClientWithCredentials` were broken on v3.x panels** - Both routed through the legacy `/panel/api/inbounds/addClient` and `/panel/api/inbounds/updateClient/:id` endpoints, which 3x-ui v3.x removed (see the Legacy API note below and `CLAUDE.md`). `addClientWithCredentials` threw an unhandled `404`; `updateClientWithCredentials` additionally called `JSON.parse()` unconditionally on `inbound.settings`, which v3.7.0+ panels return as an already-parsed object (not a JSON string), throwing `"[object Object]" is not valid JSON` before even reaching the dead route. Both now route through the Modern Client API (`addModernClient`/`/panel/api/clients/update/:email`), handle `settings` as either a string or object, and — since the Modern update endpoint replaces the whole client row rather than patching it — merge over the client's full current record (fetched via `getClient`) so untouched fields like `flow` are no longer silently cleared. The merged payload also drops the read-only numeric `id` and the `allowedIPs` field (string on read, array on write, for WireGuard peers), both of which the update endpoint rejects if round-tripped verbatim. `updateClientWithCredentials` now matches clients by UUID (`id`) or Trojan/Shadowsocks `password`, not just `id`. Found via local Docker testing against `ghcr.io/mhsanaei/3x-ui:v3.7.0`.
+- 🔴 **`importDB` always failed with `403`** - It bypassed `_request()` entirely and called `this.api.post()` directly (to dodge `_request()`'s forced `Content-Type: application/json`, which collides with a multipart boundary), so it never got the `X-CSRF-Token` header this panel requires on non-GET requests. It now routes through `_request()`, passing the `FormData`'s own multipart headers as `extraHeaders` so they override the default JSON content type while still getting CSRF attachment and session recovery. Verified end-to-end (backup via the fixed `getDb()` below, successful re-import) against `ghcr.io/mhsanaei/3x-ui:v3.7.0`.
+- 🔴 **`getDb()` silently corrupted the downloaded database** - The panel streams the raw SQLite file directly rather than wrapping it in the standard `{success, msg, obj}` envelope, and without `responseType: 'arraybuffer'`, axios's default UTF-8 text decoding is lossy for arbitrary binary content - confirmed on a live panel: a real DB download came back 10 bytes short and byte-different from the raw response, and the *pre-existing* validation logic (which assumed the envelope shape) threw `getDb: Invalid response format` on every call, meaning this method has likely never worked. It now forces `responseType: 'arraybuffer'` and decodes with latin1 (`'binary'`), which round-trips every byte value 1:1; verified byte-identical against a raw `arraybuffer` request. `_request()`/`_retryAfterRelogin()` gained an optional 5th `requestOptions` parameter to support this (and any future binary endpoint).
+- 🐛 **`package.json`'s `files` array listed two nonexistent files** (`SECURITY.md`, `USAGE_EXAMPLES.md`) - removed. Confirmed via `npm pack --dry-run` that they were never actually in the published tarball; `publint` and a strict `tsc --noEmit` type-check of `index.d.ts` are both now part of the release checklist and pass clean.
+
+### Changed
+- ⬆️ **Minimum Node.js raised from 14/16 to 18** - `package.json engines.node` was inconsistently `>=16.0.0` while `README.md` claimed `>=14.0.0`; both now say `>=18.0.0`, matching the CI test matrix (`ci.yml`/`release.yml` now both test Node 18/20/22, dropping the long-EOL Node 16). `engines.npm` raised from `>=7.0.0` to `>=9.0.0` to match.
+- ⬆️ **Dependencies updated to latest**: `axios` ^1.10.0 → ^1.20.0, `jest` ^29.7.0 → ^30.4.2, `eslint` ^9.0.0 → ^10.9.1, `@eslint/js` ^9.0.0 → ^10.9.1 (aligned with `eslint`). ESLint 10's stricter `recommended` config flagged 3 spots re-throwing an error without `{ cause }` - fixed, so the original error is now preserved for debugging instead of discarded.
+- 🗑️ Removed **`dotenv`** and **`chai`** dev dependencies - both were unused (`dotenv`: no `require` anywhere in the codebase; `chai`: no assertions written against it, tests use Jest's built-in `expect`).
+
+## [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
@@ -207,7 +233,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Planned
-- GitHub Actions CI/CD pipeline
 - Automated semantic releases
 - Enhanced unit test coverage
 - Performance benchmarking tools

package/README.md

@@ -31,13 +31,13 @@ This library is available through **[Context7 MCP](https://context7.com/iamhelit
 
 ## Features
 
-- ✅ **Dual Panel Support** - Works with both modern (React, v2.x+) and legacy (Vue, v1.x) 3x-ui panels
+- ✅ **Dual Panel Support** - Works with both modern (React, v3.x+) and legacy (Vue, v2.x) 3x-ui panels
 - ✅ **Auto-Detection** - Automatically detects panel version and uses correct endpoints
 - ✅ **API Token Authentication** - Support for API token auth (3x-ui v3.0.2+) and cookie-based login
 - ✅ **Automatic Credential Generation** - Built-in UUID, password, and key pair generators
 - ✅ **Session Management** - Automatic login, session caching, and expiry handling
 - ✅ **Security** - Input validation, secure headers, rate limiting, and error sanitization
-- ✅ **Modern API Support** - Complete modern API (v2.x+) with advanced client management
+- ✅ **Modern API Support** - Complete modern API (v3.x+) with advanced client management
 - ✅ **Legacy API Support** - Full backward compatibility with legacy API methods
 - ✅ **TypeScript Definitions** - Complete type definitions for IDE support
 - ✅ **124 API Methods** - Comprehensive coverage of all 3x-ui panel operations
@@ -90,8 +90,8 @@ const client = new ThreeXUI('https://your-3xui-server.com', 'username', 'passwor
 ```
 
 **Supported Panel Types:**
-- ✅ **Modern Panels** - React-based, v2.x+ with `/panel/api/*` endpoints
-- ✅ **Legacy Panels** - Vue-based, v1.x with `/login` endpoint
+- ✅ **Modern Panels** - React-based, v3.x+ with `/panel/api/*` endpoints
+- ✅ **Legacy Panels** - Vue-based, v2.x with `/login` endpoint
 - ✅ **Auto-Detection** - Tries modern first, falls back to legacy if needed
 - ✅ **Session Caching** - Detected version is cached for faster subsequent logins
 
@@ -99,7 +99,7 @@ See [PANEL-VERSION-SUPPORT.md](./PANEL-VERSION-SUPPORT.md) for detailed version
 
 ## API Methods
 
-### Client Management (Modern API - v2.x+)
+### Client Management (Modern API - v3.x+)
 
 #### Read Operations
 - `getClients()` - Get all clients
@@ -218,6 +218,7 @@ See [PANEL-VERSION-SUPPORT.md](./PANEL-VERSION-SUPPORT.md) for detailed version
 - `getXrayConfig()` - Get Xray configuration
 - `updateXrayConfig(config)` - Update Xray configuration
 - `manageWarp(action, data)` - Manage WARP settings
+- `testOutbound(outbound, options)` - Test connectivity through an outbound configuration
 - `getOutboundsTraffic()` - Get outbound traffic statistics
 - `resetOutboundsTraffic()` - Reset outbound traffic
 - `getXrayResult()` - Get Xray execution result
@@ -279,7 +280,7 @@ For comprehensive guides, examples, and implementation patterns, visit our **[Wi
 
 ## Requirements
 
-- Node.js >= 14.0.0
+- Node.js >= 18.0.0
 - 3x-ui panel v2.0+ (or v3.0.2+ for API token authentication)
 - API access enabled on your 3x-ui server
 

package/index.d.ts

@@ -59,6 +59,13 @@ declare module '3xui-api-client' {
     enable?: boolean;
   }
 
+  /**
+   * Raw config for `addClient`/`updateClient`. `settings` is sent to the panel exactly
+   * as given — any `totalGB` inside it must already be in BYTES (the panel's field is
+   * named totalGB but stores bytes). This is NOT auto-converted, unlike
+   * `addClientWithCredentials`/`updateClientWithCredentials`/`ModernClient.totalGB`,
+   * which accept gigabytes. See https://github.com/iamhelitha/3xui-api-client/issues/5.
+   */
   export interface ClientConfig {
     id: number;
     settings: string;
@@ -573,15 +580,29 @@ declare module '3xui-api-client' {
     updateInbound(id: number, inboundConfig: InboundConfig): Promise<any>;
     importInbounds(inbounds: InboundConfig | InboundConfig[]): Promise<any[]>;
     getLastOnline(): Promise<any>;
+    /** Raw passthrough — no unit conversion. See {@link ClientConfig}: any `totalGB` in `clientConfig.settings` must already be in bytes. */
     addClient(clientConfig: ClientConfig): Promise<any>;
     deleteClient(inboundId: number, clientId: string): Promise<any>;
+    /** Raw passthrough — no unit conversion. See {@link ClientConfig}: any `totalGB` in `clientConfig.settings` must already be in bytes. */
     updateClient(clientId: string, clientConfig: ClientConfig): Promise<any>;
-    /** @param trafficConfig.totalGB Data limit in gigabytes (auto-converted to bytes internally) */
+    /**
+     * Raw passthrough — no unit conversion.
+     * @param trafficConfig.totalGB Data limit in BYTES, not gigabytes (the panel field is named
+     *   totalGB but stores bytes). Convert yourself: `gbValue * 1024 ** 3`. For automatic
+     *   GB->bytes conversion use `updateClientWithCredentials`/`updateModernClient` instead.
+     */
     updateClientTraffic(email: string, trafficConfig: { totalGB?: number; expiryTime?: number }): Promise<any>;
     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 +616,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>;
     /**
@@ -658,6 +685,21 @@ declare module '3xui-api-client' {
      * @param data - Additional data for the action
      */
     manageWarp(action: string, data?: Record<string, any>): Promise<any>;
+    /**
+     * Test connectivity through an outbound configuration.
+     * Sent as `application/x-www-form-urlencoded`, not JSON.
+     * `freedom`/`blackhole`-type outbounds cannot be tested (nothing to
+     * dial through) - the panel returns `success: false` with a clear
+     * `error` message for those, which is expected, not a request failure.
+     * @param outbound - Outbound config object (or its JSON string)
+     * @param options.allOutbounds - Full outbounds list, to resolve `sockopt.dialerProxy`
+     *   dependencies between outbounds
+     * @param options.mode - Test mode flag (panel-defined; observed value: 'http')
+     */
+    testOutbound(
+        outbound: object | string,
+        options?: { allOutbounds?: object[]; mode?: string }
+    ): Promise<ModernApiResponse<{ tag: string; success: boolean; delay: number; error: string; mode: string }>>;
     getOutboundsTraffic(): Promise<any>;
     resetOutboundsTraffic(): Promise<any>;
     getXrayResult(): Promise<any>;

package/index.js

@@ -196,6 +196,22 @@ class ThreeXUI {
         }
 
         try {
+            // On a forced re-login (e.g. stale-session recovery in
+            // _retryAfterRelogin), the axios instance still carries the
+            // previous, now-stale session cookie as a default header. Some
+            // panels' /csrf-token endpoint does not reissue a Set-Cookie when
+            // a session cookie is already attached to the request, which
+            // makes _getCsrfToken() below return null (no fresh cookie to
+            // pair with the token) and sends /login without the
+            // X-CSRF-Token it requires - failing with a confusing 403 that
+            // masks the original error. Clear the stale cookie first so the
+            // CSRF handshake starts from a clean, anonymous state.
+            if (forceRefresh) {
+                this.cookie = null;
+                this.csrfToken = null;
+                delete this.api.defaults.headers.Cookie;
+            }
+
             const params = new URLSearchParams();
             params.append('username', this.username);
             params.append('password', this.password);
@@ -392,7 +408,15 @@ class ThreeXUI {
         return this._request('post', '/getTwoFactorEnable');
     }
 
-    async _request(method, path, data = {}, extraHeaders = {}) {
+    /**
+     * @param {string} method
+     * @param {string} path
+     * @param {*} data
+     * @param {Object} extraHeaders
+     * @param {Object} [requestOptions] - Extra axios request config to merge in verbatim
+     *   (e.g. `{ responseType: 'arraybuffer' }` for binary downloads like `getDb()`).
+     */
+    async _request(method, path, data = {}, extraHeaders = {}, requestOptions = {}) {
         // 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)) {
@@ -407,40 +431,114 @@ class ThreeXUI {
                 method,
                 url: path,
                 data,
-                headers: { ...this._buildRequestHeaders(method), ...extraHeaders }
+                headers: { ...this._buildRequestHeaders(method), ...extraHeaders },
+                ...requestOptions
             });
+
+            // 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, requestOptions);
+            }
+
             // 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.', { cause: error });
                     }
-                    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, requestOptions);
             }
             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, requestOptions = {}) {
+        // 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 },
+            ...requestOptions
+        });
+        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
@@ -596,23 +694,22 @@ class ThreeXUI {
      */
     async addClientWithCredentials(inboundId, protocol, options = {}) {
         const credentials = this.generateCredentials(protocol, options);
-        const convertedOptions = convertBandwidthFields(options);
-
-        const clientConfig = {
-            id: inboundId,
-            settings: JSON.stringify({
-                clients: [{
-                    ...credentials,
-                    enable: true,
-                    expiryTime: convertedOptions.expiryTime || 0,
-                    limitIp: convertedOptions.limitIp || 0,
-                    totalGB: convertedOptions.totalGB || 0,
-                    subId: convertedOptions.subId || this.generateUUID()
-                }]
-            })
+
+        // Routed through the Modern Client API (addModernClient), which
+        // does its own GB->bytes conversion - pass totalGB in GB here, not
+        // pre-converted, to avoid converting it twice. The legacy
+        // /panel/api/inbounds/addClient route this used to call is removed
+        // on v3.x panels (see CLAUDE.md).
+        const client = {
+            ...credentials,
+            enable: true,
+            expiryTime: options.expiryTime || 0,
+            limitIp: options.limitIp || 0,
+            totalGB: options.totalGB || 0,
+            subId: options.subId || this.generateUUID()
         };
 
-        const result = await this.addClient(clientConfig);
+        const result = await this.addModernClient({ inboundIds: [inboundId], client });
         return {
             ...result,
             credentials,
@@ -629,56 +726,65 @@ class ThreeXUI {
      */
     async updateClientWithCredentials(clientId, inboundId, options = {}) {
         try {
-            // First, get the current inbound to obtain all existing clients
+            // First, get the current inbound to locate the client by its
+            // VLESS/VMess UUID (id) or Trojan/Shadowsocks password.
             const inboundData = await this.getInbound(inboundId);
 
             if (!inboundData.success || !inboundData.obj) {
                 throw new Error(`Failed to get inbound ${inboundId} for client update`);
             }
 
-            // Parse existing settings to get all clients
-            const currentSettings = JSON.parse(inboundData.obj.settings);
+            // `settings` comes back as a JSON string on some panel versions
+            // and as an already-parsed object on others (v3.7.0+) - handle both.
+            const currentSettings = typeof inboundData.obj.settings === 'string'
+                ? JSON.parse(inboundData.obj.settings)
+                : inboundData.obj.settings;
             const existingClients = currentSettings.clients || [];
 
-            // Find the client to update
-            const clientIndex = existingClients.findIndex(client => client.id === clientId);
+            const clientIndex = existingClients.findIndex(
+                client => client.id === clientId || client.password === clientId
+            );
             if (clientIndex === -1) {
                 throw new Error(`Client with ID ${clientId} not found in inbound ${inboundId}`);
             }
+            const email = existingClients[clientIndex].email;
+            if (!email) {
+                throw new Error(`Client with ID ${clientId} has no email - cannot update via the Modern Client API`);
+            }
+
+            // The Modern Client API's update endpoint replaces the entire
+            // client row rather than patching it, so every field must be
+            // resent or it gets silently cleared (e.g. `flow`). Load the
+            // authoritative full record first.
+            const fullClient = await this.getClient(email);
+            if (!fullClient.success || !fullClient.obj || !fullClient.obj.client) {
+                throw new Error(`Failed to load full client record for ${email}`);
+            }
+            const current = fullClient.obj.client;
 
             // Convert bandwidth fields (GB to bytes)
             const convertedOptions = convertBandwidthFields(options);
 
-            // Convert user-friendly options to API format
+            // Convert user-friendly options to API format, merged over the
+            // full existing record so untouched fields are preserved as-is.
+            // `id` (the read-only numeric row id from getClient()) and
+            // `allowedIPs` (typed as a string on read but an array on
+            // write, for WireGuard peers) are dropped: resending either as
+            // read from GET fails the update endpoint's own validation.
             const processedOptions = {
-                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
-            existingClients[clientIndex] = {
-                ...existingClients[clientIndex],
-                ...processedOptions
-            };
-
-            // Prepare the complete settings with all clients
-            const updatedSettings = {
-                ...currentSettings,
-                clients: existingClients
-            };
-
-            const clientConfig = {
-                id: inboundId,
-                settings: JSON.stringify(updatedSettings)
+                ...current,
+                email: convertedOptions.email || current.email,
+                limitIp: convertedOptions.limitIp !== undefined ? convertedOptions.limitIp : current.limitIp,
+                totalGB: convertedOptions.totalGB !== undefined ? convertedOptions.totalGB : current.totalGB,
+                expiryTime: convertedOptions.expiryDays ? Date.now() + (convertedOptions.expiryDays * 24 * 60 * 60 * 1000) : current.expiryTime,
+                enable: convertedOptions.enable !== undefined ? convertedOptions.enable : current.enable,
+                flow: convertedOptions.flow || current.flow,
+                subId: convertedOptions.subId || current.subId
             };
+            delete processedOptions.id;
+            delete processedOptions.allowedIPs;
 
-            const result = await this.updateClient(clientId, clientConfig);
+            const result = await this._request('post', `/panel/api/clients/update/${encodeURIComponent(email)}`, processedOptions);
             return {
                 ...result,
                 updatedOptions: processedOptions,
@@ -1109,6 +1215,14 @@ class ThreeXUI {
     }
 
     // Clients
+    /**
+     * Add a client (raw passthrough — no unit conversion).
+     * `clientConfig.settings` is sent to the panel exactly as given, so any `totalGB`
+     * inside it must already be in BYTES (the panel stores this field in bytes despite
+     * its name). For a GB input with automatic conversion, use `addClientWithCredentials`
+     * or `addModernClient` instead. See issue #5 for background.
+     * @param {ClientConfig} clientConfig
+     */
     addClient(clientConfig) {
         // Validate client configuration for security
         const validatedConfig = InputValidator.validateClientConfig(clientConfig);
@@ -1119,6 +1233,14 @@ class ThreeXUI {
         return this._request('post', `/panel/api/inbounds/${inboundId}/delClient/${clientId}`);
     }
 
+    /**
+     * Update a client (raw passthrough — no unit conversion).
+     * Same caveat as `addClient`: any `totalGB` inside `clientConfig.settings` must
+     * already be in BYTES. Use `updateClientWithCredentials`/`updateModernClient` for
+     * automatic GB->bytes conversion.
+     * @param {string} clientId
+     * @param {ClientConfig} clientConfig
+     */
     updateClient(clientId, clientConfig) {
         // Validate client configuration for security
         const validatedConfig = InputValidator.validateClientConfig(clientConfig);
@@ -1126,9 +1248,12 @@ class ThreeXUI {
     }
 
     /**
-     * Update client traffic limit and expiry by email
+     * Update client traffic limit and expiry by email (raw passthrough — no unit conversion).
      * @param {string} email - Client email
-     * @param {Object} trafficConfig - Traffic configuration (totalGB, expiryTime)
+     * @param {Object} trafficConfig - Traffic configuration
+     * @param {number} [trafficConfig.totalGB] - Data limit in BYTES, not gigabytes (the panel
+     *   field is named totalGB but stores bytes). Convert yourself: `gbValue * 1024 ** 3`.
+     * @param {number} [trafficConfig.expiryTime]
      */
     updateClientTraffic(email, trafficConfig) {
         return this._request('post', `/panel/api/inbounds/updateClientTraffic/${email}`, trafficConfig);
@@ -1151,8 +1276,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) {
@@ -1227,11 +1388,33 @@ class ThreeXUI {
 
     /**
      * Download database
-     * @returns {Promise<string>} Raw SQLite database file content as a string (starts with "SQLite format 3 ..."), not a Buffer
+     * @returns {Promise<ModernApiResponse<string>>} `obj` is the raw SQLite database file
+     *   content as a binary-safe string (starts with "SQLite format 3 ..."), not a Buffer.
+     *   Pass it to `Buffer.from(obj, 'binary')` to get the actual file bytes back losslessly.
      */
     async getDb() {
-        const response = await this._request('get', '/panel/api/server/getDb');
-        // Add response validation
+        // The panel streams the raw SQLite file directly rather than wrapping it in
+        // the standard {success, msg, obj} envelope every other endpoint uses, and the
+        // response is arbitrary binary data - axios's default text decoding (UTF-8) is
+        // lossy for that (confirmed: a real DB download came back 10 bytes short and
+        // byte-different from the raw response). Force responseType: 'arraybuffer' to
+        // get the exact bytes, then use latin1 ('binary'), which round-trips every byte
+        // value 1:1, to produce the string this method's signature promises.
+        const response = await this._request('get', '/panel/api/server/getDb', {}, {}, { responseType: 'arraybuffer' });
+        if (Buffer.isBuffer(response) || response instanceof ArrayBuffer || ArrayBuffer.isView(response)) {
+            const buf = Buffer.from(response);
+            if (buf.length === 0) {
+                throw new Error('getDb: Response missing database content');
+            }
+            return { success: true, msg: '', obj: buf.toString('binary') };
+        }
+        if (typeof response === 'string') {
+            if (!response) {
+                throw new Error('getDb: Response missing database content');
+            }
+            return { success: true, msg: '', obj: response };
+        }
+        // Defensive fallback in case some panel fork/version does wrap it.
         if (!response || typeof response !== 'object') {
             throw new Error('getDb: Invalid response format');
         }
@@ -1308,16 +1491,19 @@ class ThreeXUI {
     }
 
     /**
-     * Import database
+     * Import database (destructive - replaces the panel's entire 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);
+    importDB(formData) {
+        // Route through _request() (not a direct api.post) so this gets the
+        // same X-CSRF-Token attachment, session recovery, and stale-session
+        // retry as every other write - without it, this always failed with
+        // a 403 on panels that require CSRF on non-GET requests. The
+        // FormData's own multipart boundary Content-Type is passed as
+        // extraHeaders so it overrides _request()'s default
+        // "Content-Type: application/json" for POST bodies.
+        const extraHeaders = typeof formData.getHeaders === 'function' ? formData.getHeaders() : {};
+        return this._request('post', '/panel/api/server/importDB', formData, extraHeaders);
     }
 
     // ===========================================
@@ -1447,7 +1633,7 @@ class ThreeXUI {
                 if (this.sessionManager) {
                     await this.sessionManager.deleteSession(this.baseURL, newUsername);
                 }
-                throw new Error(`Credential update succeeded but re-authentication failed: ${error.message}`);
+                throw new Error(`Credential update succeeded but re-authentication failed: ${error.message}`, { cause: error });
             }
         }
 
@@ -1496,7 +1682,7 @@ class ThreeXUI {
             try {
                 config = JSON.parse(config);
             } catch (error) {
-                throw new Error(`updateXrayConfig: Invalid JSON: ${error.message}`);
+                throw new Error(`updateXrayConfig: Invalid JSON: ${error.message}`, { cause: error });
             }
         }
         // Validate it's an object
@@ -1515,6 +1701,40 @@ class ThreeXUI {
         return this._request('post', `/panel/api/xray/warp/${action}`, data);
     }
 
+    /**
+     * Test connectivity through an outbound configuration.
+     *
+     * Sent as `application/x-www-form-urlencoded`, not JSON - a JSON body
+     * always fails with "outbound parameter is required" regardless of
+     * field name or nesting tried. The `outbound` field must be the
+     * JSON-stringified outbound object.
+     *
+     * `freedom`/`blackhole`-type outbounds cannot be tested (nothing to
+     * dial through) - the panel returns `success: false` with a clear
+     * `error` message for those, which is expected, not a request failure.
+     * @param {Object|string} outbound - Outbound config object (or its JSON string)
+     * @param {Object} [options]
+     * @param {Array<Object>} [options.allOutbounds] - Full outbounds list, to resolve
+     *   `sockopt.dialerProxy` dependencies between outbounds. Field name inferred from
+     *   the endpoint's own description ("optionally all outbounds") - not confirmed
+     *   against a config that actually needs it.
+     * @param {string} [options.mode] - Test mode flag (panel-defined; observed value: 'http')
+     * @returns {Promise<Object>} `{ tag, success, delay, error, mode }`
+     */
+    testOutbound(outbound, options = {}) {
+        const params = new URLSearchParams();
+        params.append('outbound', typeof outbound === 'string' ? outbound : JSON.stringify(outbound));
+        if (options.allOutbounds) {
+            params.append('outbounds', JSON.stringify(options.allOutbounds));
+        }
+        if (options.mode) {
+            params.append('mode', options.mode);
+        }
+        return this._request('post', '/panel/api/xray/testOutbound', params.toString(), {
+            'Content-Type': 'application/x-www-form-urlencoded'
+        });
+    }
+
     /**
      * Get outbound traffic statistics
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3xui-api-client",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "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",
@@ -75,8 +75,8 @@
     "url": "https://github.com/sponsors/iamhelitha"
   },
   "engines": {
-    "node": ">=16.0.0",
-    "npm": ">=7.0.0"
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
   },
   "os": [
     "linux",
@@ -89,19 +89,15 @@
     "src/",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md",
-    "SECURITY.md",
-    "USAGE_EXAMPLES.md"
+    "CHANGELOG.md"
   ],
   "dependencies": {
-    "axios": "^1.10.0"
+    "axios": "^1.20.0"
   },
   "devDependencies": {
-    "dotenv": "^16.5.0",
-    "jest": "^29.7.0",
-    "eslint": "^9.0.0",
-    "@eslint/js": "^9.0.0",
-    "chai": "^4.3.4"
+    "jest": "^30.4.2",
+    "eslint": "^10.9.1",
+    "@eslint/js": "^10.0.1"
   },
   "jest": {
     "testEnvironment": "node",