@localzet/xtls-sdk

XTLS SDK

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.

Installation

npm install @localzet/xtls-sdk

Quick Start

import { XtlsApi } from '@localzet/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: '[e-mail]',
  password: 'secure-password',
  level: 0,
});

// Remove a user
const removed = await api.handler.removeUser('main-inbound', '[e-mail]');

// 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);
}