XTLS SDK

GitHub top language GitHub Repo stars

npm version GitHub Tag

Build Status Downloads License NPM Last Update

Coverage Status

A TypeScript SDK for interacting with XRAY (XTLS) Core via gRPC API. This package provides a type-safe interface for managing and monitoring your XRAY server, including statistics, user management, and connection information.

Features

🔒 Type-safe API interactions
📊 Comprehensive statistics monitoring
👥 User management capabilities
🔄 Connection monitoring
⚡ Async/Promise-based API
📝 Detailed error handling

Installation

npm install @remnawave/xtls-sdk
# or
yarn add @remnawave/xtls-sdk
# or
pnpm add @remnawave/xtls-sdk

Quick Start

import { XtlsApi } from '@remnawave/xtls-sdk';

// Initialize the API client
const api = new XtlsApi('127.0.0.1', '10085');

// Example: Get system statistics
const stats = await api.stats.getSysStats();
if (stats.isOk) {
  console.log('System Stats:', stats.data);
}

Core Features

Statistics Management

// System Statistics
const sysStats = await api.stats.getSysStats();

// User Statistics
const userStats = await api.stats.getUserStats('username');
const allUsers = await api.stats.getAllUsersStats();
const isOnline = await api.stats.getUserOnlineStatus('username');

// Traffic Statistics
const inbounds = await api.stats.getAllInboundsStats();
const outbounds = await api.stats.getAllOutboundsStats();

Response Handling

All API methods return a standardized response format:

interface ISdkResponse<T> {
  isOk: boolean;
  data?: T;
  message?: string;
  code?: string;
}

Example usage:

const response = await api.stats.getSysStats();

if (response.isOk) {
  // Success case
  console.log('Stats:', response.data);
} else {
  // Error case
  console.error(`Error ${response.code}: ${response.message}`);
}

Reset Options

Many methods support statistics reset functionality:

// Get stats and reset counters
const stats = await api.stats.getUserStats('username', true);

API Reference

XtlsApi

Main client class for interacting with the XRAY server.

const api = new XtlsApi(ip: string, port: string);

HandlerService

Service for managing inbound handlers and their users.

User Management Methods

Method	Description	Parameters
`getInboundUsers(tag: string)`	Get all users from an inbound	`tag`: Inbound handler tag
`getInboundUsersCount(tag: string)`	Get count of users in an inbound	`tag`: Inbound handler tag
`removeUser(tag: string, username: string)`	Remove a user from an inbound	`tag`: Inbound handler tag `username`: User to remove

Add User Methods

Method	Description	Parameters
`addTrojanUser(data: IAddTrojanUser)`	Add Trojan user	`data`: { tag, username, password, level }
`addVlessUser(data: IAddVlessUser)`	Add VLESS user	`data`: { tag, username, uuid, flow, level }
`addShadowsocksUser(data: IAddShadowsocksUser)`	Add Shadowsocks user	`data`: { tag, username, password, cipherType, ivCheck, level }
`addShadowsocks2022User(data: IAddShadowsocks2022User)`	Add Shadowsocks 2022 user	`data`: { tag, username, key, level }
`addSocksUser(data: IAddSocksUser)`	Add SOCKS user	`data`: { tag, username, socks_username, socks_password, level }
`addHttpUser(data: IAddHttpUser)`	Add HTTP user	`data`: { tag, username, http_username, http_password, level }

Example usage:

// Get all users in an inbound
const users = await api.handler.getInboundUsers('main-inbound');
if (users.isOk) {
  console.log('Users:', users.data.users);
}

// Add a new Trojan user
const newUser = await api.handler.addTrojanUser({
  tag: 'main-inbound',
  username: 'user@example.com',
  password: 'secure-password',
  level: 0,
});

// Remove a user
const removed = await api.handler.removeUser('main-inbound', 'user@example.com');

// Get user count
const count = await api.handler.getInboundUsersCount('main-inbound');
if (count.isOk) {
  console.log('Total users:', count.data);
}

StatsService

Statistics management service.

Method	Description	Parameters
`getSysStats()`	Get system statistics	None
`getAllUsersStats(reset?: boolean)`	Get all users' statistics	`reset`: Reset stats after retrieval
`getUserStats(username: string, reset?: boolean)`	Get specific user statistics	`username`: Target user `reset`: Reset stats after retrieval
`getUserOnlineStatus(username: string)`	Check user online status	`username`: Target user
`getAllInboundsStats(reset?: boolean)`	Get all inbound statistics	`reset`: Reset stats after retrieval
`getInboundStats(inbound: string, reset?: boolean)`	Get specific inbound statistics	`inbound`: Inbound tag `reset`: Reset stats after retrieval
`getAllOutboundsStats(reset?: boolean)`	Get all outbound statistics	`reset`: Reset stats after retrieval
`getOutboundStats(outbound: string, reset?: boolean)`	Get specific outbound statistics	`outbound`: Outbound tag `reset`: Reset stats after retrieval

Error Handling

The SDK provides detailed error information through the response object:

try {
  const response = await api.stats.getUserStats('username');
  if (!response.isOk) {
    console.error(`Operation failed: ${response.message}`);
    console.error(`Error code: ${response.code}`);
  }
} catch (error) {
  console.error('Unexpected error:', error);
}

Contributors

We ❤️‍🔥 contributors! If you'd like to contribute, please check out our Contributing Guidelines and feel free to submit a pull request or open an issue.

Check open issues to help the progress of this project.

Thanks to the all contributors who have helped improve XTLS SDK:

License

MIT License - see the LICENSE file for details.

包详细信息

@remnawave/xtls-sdk

自述文件