3xui-api-client 1.0.0 → 2.1.0

package/index.d.ts

@@ -1,8 +1,28 @@
+// Type definitions for 3xui-api-client v2.0.0
+
 declare module '3xui-api-client' {
-  export interface ThreeXUIResponse<T = any> {
+  import { AxiosInstance } from 'axios';
+
+  // ===========================================
+  // CORE INTERFACES
+  // ===========================================
+
+  export interface ThreeXUIOptions {
+    sessionManager?: SessionManager | SessionConfig;
+    autoGenerateCredentials?: boolean;
+    timeout?: number;
+    maxRequestsPerMinute?: number;
+    maxLoginAttemptsPerHour?: number;
+    isDevelopment?: boolean;
+    enableCSP?: boolean;
+    userAgent?: string;
+  }
+
+  export interface LoginResponse {
     success: boolean;
-    msg: string;
-    obj: T | null;
+    fromCache?: boolean;
+    headers?: any;
+    data: any;
   }
 
   export interface InboundConfig {
@@ -11,8 +31,8 @@ declare module '3xui-api-client' {
     protocol: string;
     settings: any;
     streamSettings?: any;
-    sniffing?: any;
-    allocate?: any;
+    listen?: string;
+    enable?: boolean;
   }
 
   export interface ClientConfig {
@@ -20,90 +40,398 @@ declare module '3xui-api-client' {
     settings: string;
   }
 
-  export interface ClientData {
-    id: string;
-    email: string;
+  // ===========================================
+  // CREDENTIAL GENERATION INTERFACES
+  // ===========================================
+
+  export interface CredentialOptions {
+    email?: string;
+    passwordLength?: number;
+    level?: number;
+    alterId?: number;
+    flow?: string;
+    method?: string;
+    username?: string;
     limitIp?: number;
     totalGB?: number;
     expiryTime?: number;
     enable?: boolean;
-    tgId?: string;
     subId?: string;
+    allowedIPs?: string[];
+    keepAlive?: number;
   }
 
-  export interface InboundData {
-    id: number;
-    up: number;
-    down: number;
-    total: number;
-    remark: string;
-    enable: boolean;
-    expiryTime: number;
-    clientStats: ClientTrafficData[] | null;
-    listen: string;
-    port: number;
-    protocol: string;
-    settings: string;
-    streamSettings: string;
-    tag: string;
-    sniffing: string;
-    allocate: string;
+  export interface VLESSCredentials {
+    id: string;
+    email: string;
+    flow: string;
+    encryption: string;
   }
 
-  export interface ClientTrafficData {
-    id: number;
-    inboundId: number;
-    enable: boolean;
+  export interface VMESSCredentials {
+    id: string;
     email: string;
-    up: number;
-    down: number;
-    expiryTime: number;
-    total: number;
-    reset: number;
+    level: number;
+    alterId: number;
   }
 
-  export interface OnlineClientData {
+  export interface TrojanCredentials {
+    password: string;
     email: string;
-    ip: string;
-    connectedAt: string;
+    level: number;
   }
 
-  export interface LoginResponse {
-    success: boolean;
-    headers: any;
-    data: any;
+  export interface ShadowsocksCredentials {
+    method: string;
+    password: string;
+    email: string;
   }
 
+  export interface WireGuardCredentials {
+    privateKey: string;
+    publicKey: string;
+    allowedIPs: string[];
+    keepAlive: number;
+  }
+
+  export interface SocksCredentials {
+    user: string;
+    pass: string;
+    email: string;
+  }
+
+  export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+  }
+
+  export interface WireGuardKeys {
+    privateKey: string;
+    publicKey: string;
+    generateClientConfig: (allowedIPs?: string[]) => any;
+  }
+
+  export interface RealityKeys {
+    privateKey: string;
+    publicKey: string;
+    generateRealityConfig: (dest?: string, serverNames?: string[]) => any;
+  }
+
+  // ===========================================
+  // SESSION MANAGEMENT INTERFACES
+  // ===========================================
+
+  export interface SessionConfig {
+    sessionTTL?: number;
+    autoRefresh?: boolean;
+    refreshThreshold?: number;
+    store?: SessionStore;
+    redis?: any;
+    redisOptions?: any;
+    database?: any;
+    databaseOptions?: any;
+    customHandler?: any;
+  }
+
+  export interface SessionStore {
+    get(key: string): Promise<any>;
+    set(key: string, value: any, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    exists(key: string): Promise<boolean>;
+  }
+
+  export interface SessionManager {
+    generateSessionKey(baseURL: string, username: string): string;
+    storeSession(baseURL: string, username: string, sessionData: any): Promise<string>;
+    getSession(baseURL: string, username: string): Promise<any>;
+    hasValidSession(baseURL: string, username: string): Promise<boolean>;
+    shouldRefreshSession(session: any): boolean;
+    deleteSession(baseURL: string, username: string): Promise<void>;
+    clearAllSessions(): Promise<void>;
+    getStats(): Promise<any>;
+  }
+
+  // ===========================================
+  // WEB MIDDLEWARE INTERFACES
+  // ===========================================
+
+  export interface ExpressMiddlewareConfig {
+    baseURL: string;
+    username: string;
+    password: string;
+    sessionManager?: SessionManager;
+    sessionKey?: string;
+  }
+
+  export interface NextJSConfig {
+    baseURL: string;
+    username: string;
+    password: string;
+    sessionManager?: SessionManager;
+  }
+
+  export interface ReactHookMethods {
+    generateCredentials(protocol: string, options?: CredentialOptions): Promise<any>;
+    addClientWithCredentials(inboundId: number, protocol: string, options?: CredentialOptions): Promise<any>;
+    getInbounds(): Promise<any[]>;
+    getClientTraffic(email: string): Promise<any>;
+  }
+
+  // ===========================================
+  // PROTOCOL BUILDER INTERFACES
+  // ===========================================
+
+  export interface BuilderConfig {
+    protocol: string;
+    settings: any;
+    streamSettings?: any;
+    remark?: string;
+    port?: number;
+    listen?: string;
+    enable?: boolean;
+  }
+
+  export interface TLSOptions {
+    serverName?: string;
+    certificates?: any[];
+    certFile?: string;
+    keyFile?: string;
+  }
+
+  export interface RealityOptions {
+    keys?: RealityKeys;
+    dest?: string;
+    serverNames?: string[];
+    shortIds?: string[];
+  }
+
+  export interface WebSocketOptions {
+    path?: string;
+    headers?: Record<string, string>;
+  }
+
+  export interface HTTP2Options {
+    path?: string;
+    host?: string[];
+  }
+
+  export interface GRPCOptions {
+    serviceName?: string;
+  }
+
+  // ===========================================
+  // MAIN CLASS
+  // ===========================================
+
   export default class ThreeXUI {
-    constructor(baseURL: string, username: string, password: string);
+    constructor(baseURL: string, username: string, password: string, options?: ThreeXUIOptions);
     
     // Authentication
-    login(): Promise<LoginResponse>;
-    
-    // Inbound Management
-    getInbounds(): Promise<ThreeXUIResponse<InboundData[]>>;
-    getInbound(id: number): Promise<ThreeXUIResponse<InboundData>>;
-    addInbound(inboundConfig: InboundConfig): Promise<ThreeXUIResponse<any>>;
-    updateInbound(id: number, inboundConfig: Partial<InboundConfig>): Promise<ThreeXUIResponse<any>>;
-    deleteInbound(id: number): Promise<ThreeXUIResponse<number>>;
-    
-    // Client Management
-    addClient(clientConfig: ClientConfig): Promise<ThreeXUIResponse<null>>;
-    updateClient(clientId: string, clientConfig: ClientConfig): Promise<ThreeXUIResponse<null>>;
-    deleteClient(inboundId: number, clientId: string): Promise<ThreeXUIResponse<null>>;
-    getClientTrafficsByEmail(email: string): Promise<ThreeXUIResponse<ClientTrafficData>>;
-    getClientTrafficsById(id: string): Promise<ThreeXUIResponse<ClientTrafficData[]>>;
-    getClientIps(email: string): Promise<ThreeXUIResponse<string>>;
-    clearClientIps(email: string): Promise<ThreeXUIResponse<null>>;
-    
-    // Traffic Management
-    resetClientTraffic(inboundId: number, email: string): Promise<ThreeXUIResponse<null>>;
-    resetAllTraffics(): Promise<ThreeXUIResponse<null>>;
-    resetAllClientTraffics(inboundId: number): Promise<ThreeXUIResponse<null>>;
-    deleteDepletedClients(inboundId: number): Promise<ThreeXUIResponse<null>>;
+    login(forceRefresh?: boolean): Promise<LoginResponse>;
+    logout(): Promise<void>;
+
+    // Credential Generation Methods
+    generateCredentials(protocol: string, options?: CredentialOptions): VLESSCredentials | VMESSCredentials | TrojanCredentials | ShadowsocksCredentials | WireGuardCredentials | SocksCredentials;
+    generateUUID(secure?: boolean): string;
+    generatePassword(length?: number, options?: any): string;
+    generateBulkCredentials(protocol: string, count: number, options?: CredentialOptions): any[];
+    getShadowsocksCiphers(): string[];
+    getRecommendedShadowsocksCipher(): string;
+    generateWireGuardKeys(): WireGuardKeys;
+    generateRealityKeys(): RealityKeys;
+    generatePort(min?: number, max?: number): number;
+    validateCredentials(credentials: any, protocol: string): ValidationResult;
     
-    // System Operations
-    getOnlineClients(): Promise<ThreeXUIResponse<OnlineClientData[]>>;
-    createBackup(): Promise<ThreeXUIResponse<string>>;
+    // Security helpers
+    getSecurityStats(): any;
+    clearBlockedIPs(): void;
+    validateCredentialStrength(credential: string, type: 'password' | 'uuid' | 'port'): { isValid: boolean; issues: string[]; strength: 'weak' | 'medium' | 'strong' };
+    generateSecureToken(): string;
+    setDevelopmentMode(enabled: boolean): void;
+
+    // Enhanced Client Management
+    addClientWithCredentials(inboundId: number, protocol: string, options?: CredentialOptions): Promise<any>;
+  updateClientWithCredentials(clientId: string, inboundId: number, options?: CredentialOptions): Promise<any>;
+
+    // Session Management
+    getSessionStats(): Promise<any>;
+    clearAllSessions(): Promise<void>;
+    isSessionValid(): Promise<boolean>;
+
+    // Original API Methods
+    getInbounds(): Promise<any>;
+    getInbound(id: number): Promise<any>;
+    addInbound(inboundConfig: InboundConfig): Promise<any>;
+    deleteInbound(id: number): Promise<any>;
+    updateInbound(id: number, inboundConfig: InboundConfig): Promise<any>;
+    addClient(clientConfig: ClientConfig): Promise<any>;
+    deleteClient(inboundId: number, clientId: string): Promise<any>;
+    updateClient(clientId: string, clientConfig: ClientConfig): Promise<any>;
+    getClientTrafficsByEmail(email: string): Promise<any>;
+    getClientTrafficsById(id: number): Promise<any>;
+    getClientIps(email: string): Promise<any>;
+    clearClientIps(email: string): Promise<any>;
+    resetClientTraffic(inboundId: number, email: string): Promise<any>;
+    resetAllTraffics(): Promise<any>;
+    resetAllClientTraffics(inboundId: number): Promise<any>;
+    deleteDepletedClients(inboundId: number): Promise<any>;
+    getOnlineClients(): Promise<any>;
+    createBackup(): Promise<any>;
+
+    // Static exports
+    static CredentialGenerator: typeof CredentialGenerator;
+    static SessionManager: typeof SessionManager;
+    static createSessionManager: (options?: SessionConfig) => SessionManager;
+  }
+
+  // ===========================================
+  // CREDENTIAL GENERATOR CLASS
+  // ===========================================
+
+  export class CredentialGenerator {
+    static generateUUID(): string;
+    static generateSecureUUID(): string;
+    static generatePassword(length?: number, options?: any): string;
+    static generateShadowsocks2022PSK(method?: string): string;
+    static generateWireGuardKeys(): WireGuardKeys;
+    static generateRealityKeys(): RealityKeys;
+    static generateUsername(prefix?: string): string;
+    static getRecommendedShadowsocksCipher(): string;
+    static getShadowsocksCipherMethods(): string[];
+    static generatePort(min?: number, max?: number): number;
+    static generateRealityShortId(): string;
+    static generateForProtocol(protocol: string, options?: CredentialOptions): any;
+    static generateBulk(protocol: string, count: number, options?: CredentialOptions): any[];
+    static validateCredentials(credentials: any, protocol: string): ValidationResult;
+  }
+
+  // ===========================================
+  // SESSION MANAGEMENT CLASSES
+  // ===========================================
+
+  export class SessionStore {
+    get(key: string): Promise<any>;
+    set(key: string, value: any, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    exists(key: string): Promise<boolean>;
+  }
+
+  export class MemorySessionStore extends SessionStore {
+    constructor();
+    getStats(): any;
+  }
+
+  export class RedisSessionStore extends SessionStore {
+    constructor(redisClient: any, options?: any);
+  }
+
+  export class DatabaseSessionStore extends SessionStore {
+    constructor(database: any, options?: any);
+    cleanupExpired(): Promise<number>;
+    static getCreateTableSQL(tableName?: string): string;
+  }
+
+  export class CustomSessionHandler {
+    constructor(handlers: any);
+    validate(key: string): Promise<boolean>;
+  }
+
+  export function createSessionManager(options?: SessionConfig): SessionManager;
+  export function createMemoryStore(): MemorySessionStore;
+  export function createRedisStore(redisClient: any, options?: any): RedisSessionStore;
+  export function createDatabaseStore(database: any, options?: any): DatabaseSessionStore;
+  export function createCustomHandler(handlers: any): CustomSessionHandler;
+
+  // ===========================================
+  // WEB MIDDLEWARE EXPORTS
+  // ===========================================
+
+  export function createExpressMiddleware(config: ExpressMiddlewareConfig): any;
+  export function withThreeXUI(config: NextJSConfig, handler: any): any;
+  export function createReactHook(apiEndpoint?: string): ReactHookMethods;
+  export function createNextjsRoutes(config: NextJSConfig): any;
+
+  export const SessionConfig: {
+    memory(): SessionConfig;
+    redis(redisClient: any, options?: any): SessionConfig;
+    database(database: any, options?: any): SessionConfig;
+    custom(handlers: any): SessionConfig;
+  };
+
+  // ===========================================
+  // PROTOCOL BUILDERS
+  // ===========================================
+
+  export class BaseBuilder {
+    constructor();
+    remark(remark: string): this;
+    port(port: number): this;
+    randomPort(min?: number, max?: number): this;
+    listen(listen?: string): this;
+    enable(enabled?: boolean): this;
+    build(): BuilderConfig;
   }
-} 
+
+  export class VLESSBuilder extends BaseBuilder {
+    addClient(options?: CredentialOptions): this;
+    network(network: string): this;
+    tls(options?: TLSOptions): this;
+    reality(options?: RealityOptions): this;
+    websocket(options?: WebSocketOptions): this;
+    http2(options?: HTTP2Options): this;
+    grpc(options?: GRPCOptions): this;
+    flow(flow: string): this;
+  }
+
+  export class VMESSBuilder extends BaseBuilder {
+    addClient(options?: CredentialOptions): this;
+    network(network: string): this;
+    tls(options?: TLSOptions): this;
+    websocket(options?: WebSocketOptions): this;
+  }
+
+  export class TrojanBuilder extends BaseBuilder {
+    addClient(options?: CredentialOptions): this;
+    tls(options?: TLSOptions): this;
+    fallbacks(fallbacks: any[]): this;
+  }
+
+  export class ShadowsocksBuilder extends BaseBuilder {
+    method(method: string): this;
+    password(password?: string): this;
+    generatePassword(length?: number): this;
+    network(network: string): this;
+  }
+
+  export class WireGuardBuilder extends BaseBuilder {
+    serverKeys(keys?: WireGuardKeys): this;
+    address(addresses: string | string[]): this;
+    addPeer(options?: any): this;
+    mtu(mtu: number): this;
+  }
+
+  export class ProtocolBuilder {
+    static vless(): VLESSBuilder;
+    static vmess(): VMESSBuilder;
+    static trojan(): TrojanBuilder;
+    static shadowsocks(): ShadowsocksBuilder;
+    static wireguard(): WireGuardBuilder;
+    static templates: {
+      vlessReality(options?: any): BuilderConfig;
+      vmessWsTls(options?: any): BuilderConfig;
+      trojanTls(options?: any): BuilderConfig;
+      shadowsocks(options?: any): BuilderConfig;
+    };
+  }
+
+  // Optional: expose security helpers for advanced users
+  export const SecurityEnhancer: {
+    InputValidator: any;
+    SecureHeaders: any;
+    SecurityMonitor: any;
+    CredentialSecurity: any;
+    ErrorSecurity: any;
+  };
+}