JSPM

3xui-api-client

2.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4
  • Score
    100M100P100Q37509F
  • License MIT

A Node.js client library for 3x-ui panel API with built-in credential generation, session management, and web integration support

Package Exports

  • 3xui-api-client

Readme

3xui-api-client

A Node.js client library for 3x-ui panel API that provides easy-to-use methods for managing your 3x-ui server.

npm version License: MIT

Features

  • ✅ Authentication - Secure login with automatic session management
  • ✅ Inbound Management - Get, add, update, and delete inbounds
  • ✅ Client Management - Add, update, delete clients and monitor traffic
  • ✅ Traffic Management - Monitor, reset, and manage traffic limits
  • ✅ System Operations - Backup creation and online client monitoring
  • ✅ Complete API Coverage - All 19 API routes fully tested and working

Installation

npm install 3xui-api-client

Context7 MCP Integration

This library can be implemented with the help of Context7 MCP. Use the package name 3xui-api-client to get context and documentation through Context7's Model Context Protocol integration.

Learn more about Context7 MCP for enhanced development experience.

Quick Start

const ThreeXUI = require('3xui-api-client');

const client = new ThreeXUI('https://your-3xui-server.com', 'username', 'password');

// Get all inbounds
client.getInbounds()
  .then(inbounds => {
    console.log('Inbounds:', inbounds);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Authentication & Security

Automatic Login

The client automatically handles authentication. When you make your first API call, it will:

  1. Login with your credentials
  2. Store the session cookie
  3. Use the cookie for subsequent requests
  4. Automatically re-login if the session expires

For production applications, store the session cookie securely on your server:

const ThreeXUI = require('3xui-api-client');

class SecureThreeXUIManager {
  constructor(baseURL, username, password) {
    this.client = new ThreeXUI(baseURL, username, password);
    this.sessionCookie = null;
  }

  async ensureAuthenticated() {
    if (!this.sessionCookie) {
      const loginResult = await this.client.login();
      this.sessionCookie = this.client.cookie;
      
      // Store in secure session storage (Redis, database, etc.)
      await this.storeSessionSecurely(this.sessionCookie);
    } else {
      // Restore from secure storage
      this.client.cookie = this.sessionCookie;
      this.client.api.defaults.headers.Cookie = this.sessionCookie;
    }
  }

  async storeSessionSecurely(cookie) {
    // Example: Store in Redis with expiration
    // await redis.setex('3xui_session', 3600, cookie);
    
    // Example: Store in database
    // await db.sessions.upsert({ service: '3xui', cookie, expires_at: new Date(Date.now() + 3600000) });
  }

  async getInbounds() {
    await this.ensureAuthenticated();
    return this.client.getInbounds();
  }
}

API Reference

Constructor

new ThreeXUI(baseURL, username, password)
  • baseURL (string): Your 3x-ui server URL (e.g., 'https://your-server.com')
  • username (string): Admin username
  • password (string): Admin password

Inbound Management (✅ Tested & Working)

Get All Inbounds

const inbounds = await client.getInbounds();
console.log(inbounds);

Get Specific Inbound

const inbound = await client.getInbound(inboundId);
console.log(inbound);

Add New Inbound

const inboundConfig = {
  remark: "My VPN Server",
  port: 443,
  protocol: "vless",
  settings: {
    // Your inbound settings
  }
};

const result = await client.addInbound(inboundConfig);
console.log('Inbound added:', result);

Update Inbound

const updatedConfig = {
  remark: "Updated VPN Server",
  // Other updated settings
};

const result = await client.updateInbound(inboundId, updatedConfig);
console.log('Inbound updated:', result);

Delete Inbound

const result = await client.deleteInbound(inboundId);
console.log('Inbound deleted:', result);

Client Management (✅ Tested & Working)

Add Client to Inbound

const clientConfig = {
  id: inboundId,
  settings: JSON.stringify({
    clients: [{
      id: "client-uuid-here",
      email: "user23c5n7",
      limitIp: 0,
      totalGB: 0,
      expiryTime: 0,
      enable: true
    }]
  })
};

const result = await client.addClient(clientConfig);

Update Client

const updateConfig = {
  id: inboundId,
  settings: JSON.stringify({
    clients: [/* updated client settings */]
  })
};

const result = await client.updateClient(clientUUID, updateConfig);

Delete Client

const result = await client.deleteClient(inboundId, clientUUID);

Get Client Traffic by Email

const traffic = await client.getClientTrafficsByEmail("user23c5n7");
console.log('Client traffic:', traffic);

Get Client Traffic by UUID

const traffic = await client.getClientTrafficsById("client-uuid");
console.log('Client traffic:', traffic);

Manage Client IPs

// Get client IPs
const ips = await client.getClientIps("user23c5n7");

// Clear client IPs
const result = await client.clearClientIps("user23c5n7");

Traffic Management (✅ Tested & Working)

Reset Individual Client Traffic

const result = await client.resetClientTraffic(inboundId, "user23c5n7");

Reset All Traffic (Global)

const result = await client.resetAllTraffics();

Reset All Client Traffic in Inbound

const result = await client.resetAllClientTraffics(inboundId);

Delete Depleted Clients

const result = await client.deleteDepletedClients(inboundId);

System Operations (✅ Tested & Working)

Get Online Clients

const onlineClients = await client.getOnlineClients();
console.log('Currently online:', onlineClients);

Create System Backup

const result = await client.createBackup();
console.log('Backup created:', result);

Documentation

For comprehensive guides, examples, and implementation patterns, visit our Wiki:

Error Handling

try {
  const inbounds = await client.getInbounds();
  console.log(inbounds);
} catch (error) {
  if (error.message.includes('Login failed')) {
    console.error('Authentication error:', error.message);
  } else if (error.response?.status === 401) {
    console.error('Unauthorized - check your credentials');
  } else {
    console.error('API error:', error.message);
  }
}

Requirements

  • Node.js >= 14.0.0
  • 3x-ui panel with API access enabled

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Testing

# Run login test
npm run test:login

# Run all tests
npm test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Author

Helitha Guruge - @iamhelitha

⚠️ Security Notice: Always store credentials and session cookies securely. Never expose them in client-side code or commit them to version control.