@remnawave/xtls-sdk v0.3.0

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.

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

Add User Methods

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.

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.

License

MIT License - see the LICENSE file for details.