3xui-api-client 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,104 @@ 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).
 
+## [2.1.0] - 2025-08-30
+
+### Added
+- 🔥 **Firestore Session Store Support** - Custom session handler for Firebase Firestore integration
+- 📝 **Enhanced Wiki Documentation** - Comprehensive guides with real-world examples and integration patterns
+- 🔍 **Client Identifier Clarification** - Clear documentation that 'email' field is an identifier, not a real email address
+
+### Enhanced
+- 📚 **Authentication Guide** - Added detailed session/cookie flow documentation and Firestore integration example
+- 👥 **Client Management Guide** - Clarified email field semantics and added identifier generation examples  
+- 🛠️ **Inbound Management Guide** - Added protocol-specific authentication method explanations
+- 🏠 **Home Documentation** - Improved navigation and cross-references between guides
+
+### Documentation
+- **Session Management**: Added comprehensive Firestore adapter example with cleanup patterns
+- **API Flow Clarification**: Documented that all API calls automatically include stored session cookies
+- **Client Identifiers**: Clarified that 'email' fields use random strings (e.g., '5yhuih4hg93') for privacy
+- **Integration Examples**: Enhanced web integration patterns for Express.js and Next.js
+- **Security Best Practices**: Consolidated security guidance in Authentication Guide
+
+### Removed
+- Removed any references to email generation functionality for clarity
+- Cleaned up duplicate content across wiki files
+
+### Fixed
+- Corrected misconceptions about email field usage in 3x-ui
+- Improved consistency across documentation
+
+## [2.0.0] - 2025-06-25
+
+### Added
+- 🎯 **Built-in Credential Generation System** - Automatic generation of random passwords, UUIDs, and client identifiers
+- 🔧 **Advanced Session Management** - Intelligent session caching, automatic renewal, and multi-server support
+- 🌐 **Web Integration Support** - Express.js and Next.js middleware for seamless web app integration
+- 🛡️ **Enhanced Security Framework** - Input validation, security monitoring, and secure headers management
+- 📦 **Modular Architecture** - New `src/` directory structure with specialized modules:
+  - `CredentialGenerator.js` - Random credential generation utilities
+  - `SessionManager.js` - Advanced session handling and caching
+  - `WebMiddleware.js` - Express/Next.js integration helpers
+  - `ProtocolBuilders.js` - Automated inbound configuration builders
+  - `SecurityEnhancer.js` - Security validation and monitoring
+
+### Enhanced
+- 🔐 **Improved Authentication** - More robust session handling with automatic recovery
+- 📊 **Better Error Handling** - Enhanced error messages and recovery mechanisms
+- 🎨 **Developer Experience** - Improved TypeScript definitions and code documentation
+- 🧪 **Testing Framework** - Updated test suite with better coverage and reliability
+- 📝 **Documentation** - Comprehensive wiki updates with practical examples
+
+### New Features
+- **Credential Generation**:
+  - Random password generation with customizable complexity
+  - UUID v4 generation for unique client identifiers
+  - Secure random string generation for API keys
+  - Email-like identifier generation for client management
+
+- **Session Management**:
+  - Intelligent session caching with TTL support
+  - Multi-server session handling
+  - Automatic session renewal and cleanup
+  - Database-ready session storage format
+
+- **Web Integration**:
+  - Express.js middleware for route protection
+  - Next.js API route helpers
+  - Automatic cookie management
+  - Request/response transformation utilities
+
+- **Protocol Builders**:
+  - Automated VLESS configuration generation
+  - VMess protocol setup helpers
+  - Trojan and Shadowsocks builders
+  - Reality and WireGuard configuration support
+
+### Changed
+- **Breaking Change**: Enhanced API structure with new module organization
+- **Package Structure**: Moved from monolithic to modular architecture
+- **Dependencies**: Updated to latest stable versions
+- **Configuration**: Improved configuration options and defaults
+
+### Security
+- Enhanced input validation and sanitization
+- Improved session security with automatic cleanup
+- Better error handling to prevent information leakage
+- Security monitoring and alerting capabilities
+
+### Developer Experience
+- Better TypeScript support with comprehensive type definitions
+- Improved documentation with real-world examples
+- Enhanced testing framework with automated validation
+- ESLint configuration for code quality
+
+### Performance
+- Optimized session management with intelligent caching
+- Reduced API call overhead through better request batching
+- Improved memory usage with automatic cleanup
+- Faster authentication flow with session reuse
+
 ## [1.0.0] - 2025-06-20
 
 ### Added
@@ -43,6 +141,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Planned
 - GitHub Actions CI/CD pipeline
 - Automated semantic releases
-- Unit test coverage with Jest
-- ESLint configuration
-- Contribution guidelines 
+- Enhanced unit test coverage
+- Performance benchmarking tools
+- Advanced monitoring and analytics 

package/README.md

@@ -20,6 +20,12 @@ A Node.js client library for 3x-ui panel API that provides easy-to-use methods f
 npm install 3xui-api-client
 ```
 
+## Context7 MCP Integration
+
+This library can be implemented with the help of [Context7 MCP](https://context7.com/iamhelitha/3xui-api-client). Use the package name `3xui-api-client` to get context and documentation through Context7's Model Context Protocol integration.
+
+Learn more about [Context7 MCP](https://context7.com) for enhanced development experience.
+
 ## Quick Start
 
 ```javascript
@@ -153,7 +159,7 @@ const clientConfig = {
   settings: JSON.stringify({
     clients: [{
       id: "client-uuid-here",
-      email: "user@example.com",
+      email: "user23c5n7",
       limitIp: 0,
       totalGB: 0,
       expiryTime: 0,
@@ -184,7 +190,7 @@ const result = await client.deleteClient(inboundId, clientUUID);
 
 #### Get Client Traffic by Email
 ```javascript
-const traffic = await client.getClientTrafficsByEmail("user@example.com");
+const traffic = await client.getClientTrafficsByEmail("user23c5n7");
 console.log('Client traffic:', traffic);
 ```
 
@@ -197,17 +203,17 @@ console.log('Client traffic:', traffic);
 #### Manage Client IPs
 ```javascript
 // Get client IPs
-const ips = await client.getClientIps("user@example.com");
+const ips = await client.getClientIps("user23c5n7");
 
 // Clear client IPs
-const result = await client.clearClientIps("user@example.com");
+const result = await client.clearClientIps("user23c5n7");
 ```
 
 ### Traffic Management (✅ Tested & Working)
 
 #### Reset Individual Client Traffic
 ```javascript
-const result = await client.resetClientTraffic(inboundId, "user@example.com");
+const result = await client.resetClientTraffic(inboundId, "user23c5n7");
 ```
 
 #### Reset All Traffic (Global)
@@ -239,151 +245,16 @@ const result = await client.createBackup();
 console.log('Backup created:', result);
 ```
 
-## Use Cases
-
-### VPN Service Provider
-```javascript
-const ThreeXUI = require('3xui-api-client');
-
-class VPNServiceManager {
-  constructor() {
-    this.client = new ThreeXUI(process.env.XUI_URL, process.env.XUI_USER, process.env.XUI_PASS);
-  }
-
-  // Create new customer account
-  async createCustomerAccount(email, dataLimitGB = 50) {
-    // 1. Get available inbound
-    const inbounds = await this.client.getInbounds();
-    const activeInbound = inbounds.obj.find(i => i.enable);
-
-    // 2. Add client to inbound
-    const clientConfig = {
-      id: activeInbound.id,
-      settings: JSON.stringify({
-        clients: [{
-          id: this.generateUUID(),
-          email: email,
-          limitIp: 2,
-          totalGB: dataLimitGB,
-          expiryTime: Date.now() + (30 * 24 * 60 * 60 * 1000), // 30 days
-          enable: true
-        }]
-      })
-    };
-
-    return await this.client.addClient(clientConfig);
-  }
-
-  // Monthly billing cycle
-  async processBillingCycle() {
-    const inbounds = await this.client.getInbounds();
-    
-    for (const inbound of inbounds.obj) {
-      if (inbound.clientStats) {
-        for (const client of inbound.clientStats) {
-          // Reset traffic for active subscriptions
-          await this.client.resetClientTraffic(inbound.id, client.email);
-        }
-      }
-    }
-  }
-
-  // Monitor usage and send alerts
-  async monitorUsage() {
-    const onlineClients = await this.client.getOnlineClients();
-    
-    for (const client of onlineClients.obj || []) {
-      const traffic = await this.client.getClientTrafficsByEmail(client.email);
-      
-      if (traffic.obj && traffic.obj.total > (40 * 1024 * 1024 * 1024)) { // 40GB
-        console.log(`⚠️ Client ${client.email} approaching data limit`);
-        // Send notification to customer
-      }
-    }
-  }
-}
-```
-
-### Server Administration
-```javascript
-class ServerAdmin {
-  constructor() {
-    this.client = new ThreeXUI(process.env.XUI_URL, process.env.XUI_USER, process.env.XUI_PASS);
-  }
-
-  // Daily maintenance
-  async dailyMaintenance() {
-    // 1. Create backup
-    await this.client.createBackup();
-    
-    // 2. Clean up depleted clients
-    const inbounds = await this.client.getInbounds();
-    for (const inbound of inbounds.obj) {
-      await this.client.deleteDepletedClients(inbound.id);
-    }
-    
-    // 3. Generate usage report
-    const report = await this.generateUsageReport();
-    console.log('Daily Report:', report);
-  }
-
-  // Setup new VPN server
-  async setupNewServer(port, protocol = 'vless') {
-    const serverConfig = {
-      remark: `VPN-Server-${port}`,
-      port: port,
-      protocol: protocol,
-      settings: {
-        clients: [],
-        decryption: "none",
-        fallbacks: []
-      },
-      streamSettings: {
-        network: "tcp",
-        security: "reality",
-        realitySettings: {
-          dest: "google.com:443",
-          serverNames: ["google.com"]
-        }
-      }
-    };
-
-    return await this.client.addInbound(serverConfig);
-  }
-}
-```
-
-### Real-Time Monitoring Dashboard
-```javascript
-class MonitoringDashboard {
-  constructor() {
-    this.client = new ThreeXUI(process.env.XUI_URL, process.env.XUI_USER, process.env.XUI_PASS);
-  }
+## Documentation
 
-  async getDashboardData() {
-    const [inbounds, onlineClients] = await Promise.all([
-      this.client.getInbounds(),
-      this.client.getOnlineClients()
-    ]);
-
-    return {
-      totalInbounds: inbounds.obj.length,
-      activeInbounds: inbounds.obj.filter(i => i.enable).length,
-      totalClients: inbounds.obj.reduce((sum, i) => sum + (i.clientStats?.length || 0), 0),
-      onlineClients: onlineClients.obj?.length || 0,
-      totalTraffic: inbounds.obj.reduce((sum, i) => sum + i.total, 0)
-    };
-  }
+For comprehensive guides, examples, and implementation patterns, visit our [Wiki](https://github.com/iamhelitha/3xui-api-client/wiki):
 
-  // WebSocket endpoint for real-time updates
-  async startRealTimeUpdates(ws) {
-    setInterval(async () => {
-      const data = await this.getDashboardData();
-      ws.send(JSON.stringify(data));
-    }, 30000); // Update every 30 seconds
-  }
-}
-```
+- 📚 [**Use Cases & Examples**](https://github.com/iamhelitha/3xui-api-client/wiki/Use-Cases) - VPN service provider, server administration, monitoring dashboards
+- 🔐 [**Authentication Guide**](https://github.com/iamhelitha/3xui-api-client/wiki/Authentication-Guide) - Secure login and session management  
+- 🌐 [**Inbound Management**](https://github.com/iamhelitha/3xui-api-client/wiki/Inbound-Management) - Server configuration and setup
+- 👥 [**Client Management**](https://github.com/iamhelitha/3xui-api-client/wiki/Client-Management) - User account operations
+- 📊 [**Traffic Management**](https://github.com/iamhelitha/3xui-api-client/wiki/Traffic-Management) - Usage monitoring and billing
+- ⚙️ [**System Operations**](https://github.com/iamhelitha/3xui-api-client/wiki/System-Operations) - Backup and maintenance
 
 ## Error Handling
 
@@ -425,9 +296,7 @@ npm run test:login
 npm test
 ```
 
-## Documentation
 
-For detailed guides and examples, visit our [Wiki](https://github.com/iamhelitha/3xui-api-client/wiki).
 
 ## License