3xui-api-client 3.0.1 → 3.1.0

package/index.d.ts

@@ -18,13 +18,35 @@ declare module '3xui-api-client' {
     userAgent?: string;
     token?: string;
     apiToken?: string;
+    /**
+     * Panel version detection mode.
+     * - 'auto': Automatically detect panel version (tries modern first, falls back to legacy)
+     * - 'modern': Use only modern panel endpoints (/panel/api/login)
+     * - 'legacy': Use only legacy panel endpoints (/login)
+     * @default 'auto'
+     */
+    panelVersion?: 'auto' | 'modern' | 'legacy';
+    /**
+     * Maximum number of forced re-login attempts when a 401 response is received.
+     * @default 3
+     */
+    maxLoginRetries?: number;
+    /**
+     * Delay in milliseconds to wait before each forced re-login attempt on a 401
+     * response. Helps avoid triggering fail2ban or 3x-ui login-rate limits in
+     * serverless / multi-instance environments. Set to 0 to disable.
+     * @default 500
+     */
+    loginRetryBackoff?: number;
   }
 
   export interface LoginResponse {
     success: boolean;
     fromCache?: boolean;
+    cookie?: string | null;
     headers?: any;
     data: any;
+    message?: string;
   }
 
   export interface InboundConfig {
@@ -42,6 +64,218 @@ declare module '3xui-api-client' {
     settings: string;
   }
 
+  // ===========================================
+  // MODERN API INTERFACES (3X-UI >= 2.x)
+  // ===========================================
+
+  /** Standard envelope returned by /panel/api/* (Modern API) endpoints. */
+  export interface ModernApiResponse<T = any> {
+    success: boolean;
+    msg: string;
+    obj: T;
+  }
+
+  export interface ModernClient {
+    id?: number;
+    email: string;
+    subId?: string;
+    uuid?: string;
+    password?: string;
+    flow?: string;
+    security?: string;
+    limitIp?: number;
+    /** Data limit in gigabytes (auto-converted to bytes internally) */
+    totalGB?: number;
+    expiryTime?: number;
+    enable?: boolean;
+    tgId?: number | string;
+    group?: string;
+    comment?: string;
+    reset?: number;
+    createdAt?: number;
+    updatedAt?: number;
+    [key: string]: any;
+  }
+
+  export interface ModernClientDetail {
+    client: ModernClient;
+    inboundIds: number[];
+  }
+
+  export interface ModernClientTraffic {
+    id: number;
+    inboundId: number;
+    enable: boolean;
+    email: string;
+    uuid?: string;
+    subId?: string;
+    up: number;
+    down: number;
+    expiryTime: number;
+    total: number;
+    reset: number;
+    lastOnline: number;
+  }
+
+  export interface PagedClientsResult {
+    items: Array<ModernClient & { traffic?: ModernClientTraffic }>;
+    total: number;
+    filtered: number;
+    page: number;
+    pageSize: number;
+    summary?: Record<string, any>;
+  }
+
+  export interface AddModernClientPayload {
+    inboundIds: number[];
+    client: ModernClient;
+  }
+
+  export interface BulkCreateClientEntry {
+    inboundIds: number[];
+    client: ModernClient;
+  }
+
+  export interface BulkSkipReport {
+    email: string;
+    reason: string;
+  }
+
+  export interface BulkCreateResult {
+    created: number;
+    skipped?: BulkSkipReport[];
+  }
+
+  export interface BulkAdjustPayload {
+    emails: string[];
+    /** Days to add (or subtract, if negative) to expiryTime. Clients with unlimited expiry (0) are skipped. */
+    addDays?: number;
+    /** Bytes to add (or subtract, if negative) to totalGB. Clients with unlimited traffic (0) are skipped. */
+    addBytes?: number;
+  }
+
+  export interface BulkAdjustResult {
+    adjusted: number;
+    skipped?: BulkSkipReport[];
+  }
+
+  export interface BulkDeleteResult {
+    deleted: number;
+    skipped?: BulkSkipReport[];
+  }
+
+  export interface BulkAttachDetachResult {
+    attached?: string[] | null;
+    detached?: string[] | null;
+    skipped?: string[] | null;
+    errors?: string[];
+  }
+
+  export interface BulkAffectedResult {
+    affected: number;
+  }
+
+  export interface ModernGroup {
+    name: string;
+    clientCount: number;
+    trafficUsed: number;
+  }
+
+  export interface CustomGeoResource {
+    id: number;
+    type: 'geosite' | 'geoip';
+    alias: string;
+    url: string;
+    localPath?: string;
+    lastUpdatedAt?: number;
+    lastModified?: string;
+    createdAt?: number;
+    updatedAt?: number;
+  }
+
+  export interface AddCustomGeoPayload {
+    type: 'geosite' | 'geoip';
+    alias: string;
+    url: string;
+  }
+
+  export interface AddNodePayload {
+    name: string;
+    remark?: string;
+    /** URL scheme of the node's panel, e.g. 'http' | 'https'. */
+    scheme: string;
+    address: string;
+    port: number;
+    /** Base path of the node's panel (must end with '/'), e.g. '/abc123/'. */
+    basePath: string;
+    /** Required - the API token configured on the target node's panel. */
+    apiToken: string;
+    enable?: boolean;
+    /** Required to register a node at a private/internal address (e.g. self-registration). */
+    allowPrivateAddress?: boolean;
+    /** TLS certificate verification mode for connecting to the node, e.g. 'verify' | 'skip'. */
+    tlsVerifyMode?: string;
+    /** Pinned certificate SHA-256 fingerprint, used when tlsVerifyMode requires pinning. */
+    pinnedCertSha256?: string;
+    [key: string]: any;
+  }
+
+  export interface NodeData {
+    id: number;
+    name: string;
+    remark: string;
+    scheme: string;
+    address: string;
+    port: number;
+    basePath: string;
+    apiToken: string;
+    enable: boolean;
+    allowPrivateAddress: boolean;
+    tlsVerifyMode: string;
+    pinnedCertSha256: string;
+    guid: string;
+    status: string;
+    lastHeartbeat: number;
+    latencyMs: number;
+    xrayVersion: string;
+    panelVersion: string;
+    cpuPct: number;
+    memPct: number;
+    uptimeSecs: number;
+    lastError: string;
+    xrayState: string;
+    xrayError: string;
+    configDirty: boolean;
+    configDirtyAt: number;
+    inboundCount: number;
+    clientCount: number;
+    onlineCount: number;
+    depletedCount: number;
+    createdAt: number;
+    updatedAt: number;
+    [key: string]: any;
+  }
+
+  export interface NodeHistoryPoint {
+    /** Unix timestamp in seconds */
+    t: number;
+    /** Metric value at time `t` */
+    v: number;
+  }
+
+  export interface TestNodeResult {
+    status: 'online' | 'offline' | string;
+    latencyMs: number;
+    xrayVersion: string;
+    panelVersion: string;
+    cpuPct: number;
+    memPct: number;
+    uptimeSecs: number;
+    error: string;
+    xrayState: string;
+    xrayError: string;
+  }
+
   // ===========================================
   // CREDENTIAL GENERATION INTERFACES
   // ===========================================
@@ -55,6 +289,7 @@ declare module '3xui-api-client' {
     method?: string;
     username?: string;
     limitIp?: number;
+    /** Data limit in gigabytes (auto-converted to bytes internally) */
     totalGB?: number;
     expiryTime?: number;
     enable?: boolean;
@@ -267,66 +502,66 @@ declare module '3xui-api-client' {
     // ===========================================
 
     // --- Clients ---
-    getClients(): Promise<any>;
+    getClients(): Promise<ModernApiResponse<ModernClient[]>>;
     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>;
+    }): Promise<ModernApiResponse<PagedClientsResult>>;
+    getClient(email: string): Promise<ModernApiResponse<ModernClientDetail>>;
+    getClientTraffic(email: string): Promise<ModernApiResponse<ModernClientTraffic>>;
+    getSubLinks(subId: string): Promise<ModernApiResponse<string[]>>;
+    getClientLinks(email: string): Promise<ModernApiResponse<string[]>>;
+    addModernClient(data: AddModernClientPayload): Promise<ModernApiResponse<null>>;
+    updateModernClient(email: string, data: Partial<ModernClient>): Promise<ModernApiResponse<null>>;
+    deleteModernClient(email: string): Promise<ModernApiResponse<null>>;
+    attachClientToInbounds(email: string, data: { inboundIds: number[] }): Promise<ModernApiResponse<any>>;
+    detachClientFromInbounds(email: string, data: { inboundIds: number[] }): Promise<ModernApiResponse<any>>;
+    resetAllModernClientTraffics(): Promise<ModernApiResponse<null>>;
+    deleteDepletedModernClients(): Promise<ModernApiResponse<{ deleted: number }>>;
+    bulkAdjustModernClients(data: BulkAdjustPayload): Promise<ModernApiResponse<BulkAdjustResult>>;
+    bulkDeleteModernClients(data: { emails: string[] }): Promise<ModernApiResponse<BulkDeleteResult>>;
+    bulkCreateModernClients(data: BulkCreateClientEntry[]): Promise<ModernApiResponse<BulkCreateResult>>;
+    bulkAttachModernClients(data: { emails: string[]; inboundIds: number[] }): Promise<ModernApiResponse<BulkAttachDetachResult>>;
+    bulkDetachModernClients(data: { emails: string[]; inboundIds: number[] }): Promise<ModernApiResponse<BulkAttachDetachResult>>;
+    bulkResetTrafficModernClients(data: { emails: string[] }): Promise<ModernApiResponse<BulkAffectedResult>>;
+    resetModernClientTrafficByEmail(email: string): Promise<ModernApiResponse<null>>;
+    updateModernClientTrafficByEmail(email: string, data: { up: number; down: number }): Promise<ModernApiResponse<null>>;
+    getModernClientIps(email: string): Promise<ModernApiResponse<string[] | string>>;
+    clearModernClientIps(email: string): Promise<ModernApiResponse<null>>;
+    getOnlines(): Promise<ModernApiResponse<string[]>>;
+    getModernLastOnline(): Promise<ModernApiResponse<Record<string, number>>>;
 
     // --- 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>;
+    getGroups(): Promise<ModernApiResponse<ModernGroup[]>>;
+    getGroupEmails(groupName: string): Promise<ModernApiResponse<string[]>>;
+    createGroup(data: { name: string }): Promise<ModernApiResponse<any>>;
+    renameGroup(data: { oldName: string; newName: string }): Promise<ModernApiResponse<any>>;
+    deleteGroup(data: { name: string }): Promise<ModernApiResponse<any>>;
+    bulkAddGroups(data: { emails: string[]; group: string }): Promise<ModernApiResponse<BulkAffectedResult>>;
+    bulkRemoveGroups(data: { emails: string[] }): Promise<ModernApiResponse<BulkAffectedResult>>;
 
     // --- 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>;
+    getNodes(): Promise<ModernApiResponse<NodeData[]>>;
+    getNode(id: number | string): Promise<ModernApiResponse<NodeData>>;
+    getNodeHistory(id: number | string, metric: string, bucket: number | string): Promise<ModernApiResponse<NodeHistoryPoint[]>>;
+    addNode(data: AddNodePayload): Promise<ModernApiResponse<NodeData>>;
+    updateNode(id: number | string, data: Partial<AddNodePayload>): Promise<ModernApiResponse<null>>;
+    deleteNode(id: number | string): Promise<ModernApiResponse<null>>;
+    setNodeEnable(id: number | string, enable?: boolean): Promise<ModernApiResponse<null>>;
+    testNode(data: AddNodePayload | { address: string; port: number; [key: string]: any }): Promise<ModernApiResponse<TestNodeResult>>;
+    probeNode(id: number | string): Promise<ModernApiResponse<TestNodeResult>>;
 
     // --- 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>;
+    getCustomGeos(): Promise<ModernApiResponse<CustomGeoResource[]>>;
+    getGeoAliases(): Promise<ModernApiResponse<{ geosite: string[] | null; geoip: string[] | null }>>;
+    addCustomGeo(data: AddCustomGeoPayload): Promise<ModernApiResponse<null>>;
+    updateCustomGeo(id: string | number, data: AddCustomGeoPayload): Promise<ModernApiResponse<null>>;
+    deleteCustomGeo(id: string | number): Promise<ModernApiResponse<any>>;
+    downloadCustomGeo(id: string | number): Promise<ModernApiResponse<any>>;
+    updateAllCustomGeo(): Promise<ModernApiResponse<{ succeeded: string[] | null; failed: string[] | null }>>;
 
     // ===========================================
     // Original API Methods
@@ -336,11 +571,16 @@ declare module '3xui-api-client' {
     addInbound(inboundConfig: InboundConfig): Promise<any>;
     deleteInbound(id: number): Promise<any>;
     updateInbound(id: number, inboundConfig: InboundConfig): Promise<any>;
+    importInbounds(inbounds: InboundConfig | InboundConfig[]): Promise<any[]>;
+    getLastOnline(): Promise<any>;
     addClient(clientConfig: ClientConfig): Promise<any>;
     deleteClient(inboundId: number, clientId: string): Promise<any>;
     updateClient(clientId: string, clientConfig: ClientConfig): Promise<any>;
+    /** @param trafficConfig.totalGB Data limit in gigabytes (auto-converted to bytes internally) */
+    updateClientTraffic(email: string, trafficConfig: { totalGB?: number; expiryTime?: number }): Promise<any>;
+    deleteClientByEmail(inboundId: number, email: string): Promise<any>;
     getClientTrafficsByEmail(email: string): Promise<any>;
-    getClientTrafficsById(id: number): Promise<any>;
+    getClientTrafficsById(id: string): Promise<any>;
     getClientIps(email: string): Promise<any>;
     clearClientIps(email: string): Promise<any>;
     resetClientTraffic(inboundId: number, email: string): Promise<any>;
@@ -353,6 +593,83 @@ declare module '3xui-api-client' {
 
     // Server Management
     getServerStatus(): Promise<any>;
+    /**
+     * Get CPU usage history.
+     * @param bucket - Bucket size in seconds. Must be one of: 2, 30, 60, 120, 180, 300 (default: 60)
+     */
+    getCPUHistory(bucket?: number): Promise<any>;
+    getXrayVersion(): Promise<any>;
+    getConfigJson(): Promise<any>;
+    /**
+     * Download database.
+     * @returns Raw SQLite database file content as a string (starts with "SQLite format 3 ..."), not a Buffer
+     */
+    getDb(): Promise<ModernApiResponse<string>>;
+    stopXrayService(): Promise<any>;
+    restartXrayService(): Promise<any>;
+    /**
+     * Install specific Xray version.
+     * @param version - Version to install (e.g., "1.8.0").
+     * @throws {Error} If `version` is not a non-empty string or is "latest".
+     */
+    installXray(version: string): Promise<any>;
+    getPanelLogs(count?: number): Promise<any>;
+    getXrayLogs(count?: number): Promise<any>;
+    updateGeofile(fileName?: string): Promise<any>;
+    /**
+     * Import database.
+     * @param formData - FormData containing the database file
+     */
+    importDB(formData: any): Promise<any>;
+
+    // --- Panel Settings ---
+    getAllSettings(): Promise<any>;
+    /**
+     * Update panel settings
+     * NOTE: API requires ALL settings to be sent together.
+     * This method automatically fetches current settings, merges your updates, and sends all.
+     * @param updates - Partial settings object (will be merged with current settings)
+     * Example: updateSetting({ webPort: 7070 }) - will fetch all settings, update webPort, send all
+     */
+    updateSetting(updates: Record<string, any>): Promise<any>;
+    /**
+     * Update admin username and password
+     * ⚠️ CRITICAL: This endpoint changes your login credentials.
+     * After update, internal credentials are refreshed and session re-authenticated.
+     * If re-authentication fails, old credentials are restored and error is thrown.
+     * See test/PHASE-C-CRITICAL-FINDINGS.md for security considerations.
+     */
+    updateUser(oldUsername: string, oldPassword: string, newUsername: string, newPassword: string): Promise<any>;
+    restartPanel(): Promise<any>;
+    getDefaultSettings(): Promise<any>;
+    getDefaultJsonConfig(): Promise<any>;
+
+    // --- Xray Configuration ---
+    getXrayConfig(): Promise<any>;
+    /**
+     * Update Xray configuration.
+     * @param config - Xray configuration content (JSON string or object).
+     * @throws {Error} If `config` is an invalid JSON string or not a valid object.
+     */
+    updateXrayConfig(config: string | object): Promise<any>;
+    /**
+     * Manage WARP.
+     * @param action - Action to perform (data, del, config, reg, changeIp, license, interval)
+     * @param data - Additional data for the action
+     */
+    manageWarp(action: string, data?: Record<string, any>): Promise<any>;
+    getOutboundsTraffic(): Promise<any>;
+    resetOutboundsTraffic(): Promise<any>;
+    getXrayResult(): Promise<any>;
+
+    // --- Server-side credential / certificate generators ---
+    getNewUUID(): Promise<ModernApiResponse<{ uuid: string }>>;
+    getNewX25519Cert(): Promise<ModernApiResponse<{ privateKey: string; publicKey: string; password?: string }>>;
+    getNewmldsa65(): Promise<ModernApiResponse<{ verify: string; seed: string }>>;
+    getNewmlkem768(): Promise<ModernApiResponse<{ seed: string; client: string }>>;
+    getNewVlessEnc(): Promise<ModernApiResponse<Record<string, string>>>;
+    getNewEchCert(sni?: string): Promise<ModernApiResponse<{ echServerKeys: string; echConfigList: string }>>;
+    getWebCertFiles(): Promise<ModernApiResponse<any>>;
   }
 
   // ===========================================