@remnawave/xtls-sdk 0.0.2 → 0.0.3

package/README.md

@@ -1,8 +1,29 @@
-# XTLS API SDK
+# XTLS SDK
 
-A TypeScript SDK for interacting with Xray server statistics via gRPC.
+![GitHub top language](https://img.shields.io/github/languages/top/remnawave/xtls-sdk)
+![GitHub Repo stars](https://img.shields.io/github/stars/remnawave/xtls-sdk)
 
-This package provides a simple and type-safe way to retrieve various statistics from your Xray server, including system stats, user stats, and connection information.
+![npm version](https://img.shields.io/npm/v/@remnawave/xtls-sdk)
+![GitHub Tag](https://img.shields.io/github/v/tag/remnawave/xtls-sdk)
+
+![Build Status](https://img.shields.io/github/actions/workflow/status/remnawave/xtls-sdk/.github/workflows/deploy-lib.yml)
+![Downloads](https://img.shields.io/npm/dt/@remnawave/xtls-sdk)
+![License](https://img.shields.io/npm/l/@remnawave/xtls-sdk)
+![NPM Last Update](https://img.shields.io/npm/last-update/%40remnawave%2Fxtls-sdk)
+
+![Known Vulnerabilities](https://snyk.io/test/github/remnawave/xtls-sdk/badge.svg)
+![Coverage Status](https://img.shields.io/codecov/c/github/remnawave/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
 
@@ -10,95 +31,185 @@ This package provides a simple and type-safe way to retrieve various statistics
 npm install @remnawave/xtls-sdk
 # or
 yarn add @remnawave/xtls-sdk
+# or
+pnpm add @remnawave/xtls-sdk
 ```
 
-## Usage
-
-### Basic Setup
+## Quick Start
 
 ```typescript
 import { XtlsApi } from '@remnawave/xtls-sdk';
 
-// Create a new instance
-const xtlsApi = new XtlsApi('127.0.0.1', '8080');
+// 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
+
+```typescript
+// 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();
 ```
 
-### Examples
+### Response Handling
 
-#### Get System Statistics
+All API methods return a standardized response format:
 
 ```typescript
-const response = await xtlsApi.stats.getSysStats();
+interface ISdkResponse<T> {
+  isOk: boolean;
+  data?: T;
+  message?: string;
+  code?: string;
+}
+```
+
+Example usage:
+
+```typescript
+const response = await api.stats.getSysStats();
 
 if (response.isOk) {
-  console.log('System Stats:', response.data);
+  // Success case
+  console.log('Stats:', response.data);
 } else {
-  console.error('Error:', response.message);
+  // Error case
+  console.error(`Error ${response.code}: ${response.message}`);
 }
 ```
 
-#### Get User Statistics
+### Reset Options
+
+Many methods support statistics reset functionality:
 
 ```typescript
-// Get stats for all users
-const allUsers = await xtlsApi.stats.getAllUsersStats();
+// Get stats and reset counters
+const stats = await api.stats.getUserStats('username', true);
+```
 
-// Get stats for a specific user
-const userStats = await xtlsApi.stats.getUserStats('username123');
+## API Reference
 
-// Check if a user is online
-const onlineStatus = await xtlsApi.stats.getUserOnlineStatus('username123');
-```
+### XtlsApi
 
-#### Connection Statistics
+Main client class for interacting with the XRAY server.
 
 ```typescript
-// Get all inbound connection stats
-const inbounds = await xtlsApi.stats.getAllInboundsStats();
+const api = new XtlsApi(ip: string, port: string);
+```
 
-// Get specific inbound stats
-const inbound = await xtlsApi.stats.getInboundStats('http_in');
+### HandlerService
 
-// Get all outbound connection stats
-const outbounds = await xtlsApi.stats.getAllOutboundsStats();
+Service for managing inbound handlers and their users.
 
-// Get specific outbound stats
-const outbound = await xtlsApi.stats.getOutboundStats('http_out');
-```
+#### User Management Methods
 
-### Reset Statistics
+| 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<br>`username`: User to remove |
 
-Most methods support an optional `reset` parameter to clear statistics after retrieval:
+#### 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:
 
 ```typescript
-// Get and reset user stats
-const stats = await xtlsApi.stats.getUserStats('username123', true);
+// 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);
+}
 ```
 
-## API Reference
+### StatsService
 
-### XtlsApi
+Statistics management service.
 
-- `constructor(ip: string, port: string)`: Creates a new XtlsApi instance
+| 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<br>`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<br>`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<br>`reset`: Reset stats after retrieval |
 
-### StatsService
+## Error Handling
+
+The SDK provides detailed error information through the response object:
+
+```typescript
+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
 
-- `getSysStats()`: Get system statistics
-- `getAllUsersStats(reset?: boolean)`: Get statistics for all users
-- `getUserStats(username: string, reset?: boolean)`: Get statistics for a specific user
-- `getUserOnlineStatus(username: string)`: Check if a user is currently online
-- `getAllInboundsStats(reset?: boolean)`: Get statistics for all inbound connections
-- `getInboundStats(inbound: string, reset?: boolean)`: Get statistics for a specific inbound connection
-- `getAllOutboundsStats(reset?: boolean)`: Get statistics for all outbound connections
-- `getOutboundStats(outbound: string, reset?: boolean)`: Get statistics for a specific outbound connection
+We ❤️‍🔥 contributors! If you'd like to contribute, please check out our [Contributing Guidelines](CONTRIBUTING.md) and feel free to submit a pull request or open an issue.
 
-All methods return a Promise with an `ISdkResponse` type that includes:
+Check [open issues](https://github.com/remnawave/xtls-sdk/issues) to help the progress of this project.
 
-- `isOk`: Boolean indicating success/failure
-- `data`: The requested statistics (when successful)
-- `message`: Error message (when unsuccessful)
-- `code`: Error code (when unsuccessful)
+<p align="center">
+Thanks to the all contributors who have helped improve XTLS SDK:
+</p>
+<p align="center">
+<a href="https://github.com/remnawave/xtls-sdk/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=remnawave/xtls-sdk" />
+</a>
+</p>
 
 ## License
 
-MIT
+MIT License - see the [LICENSE](LICENSE) file for details.

package/build/tests/stats.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stats.spec.d.ts.map

package/build/tests/stats.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.spec.d.ts","sourceRoot":"","sources":["../../tests/stats.spec.ts"],"names":[],"mappings":""}

package/build/tests/stats.spec.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+describe('StatsService', () => {
+    const validIp = '127.0.0.1';
+    const validPort = '8080';
+    let api;
+    beforeEach(() => {
+        api = new index_1.XtlsApi(validIp, validPort);
+    });
+    describe('System Stats', () => {
+        it('should get system stats', async () => {
+            const response = await api.stats.getSysStats();
+            expect(response.isOk).toBe(true);
+            if (response.isOk) {
+                expect(response.data).toBeDefined();
+            }
+        });
+    });
+    describe('User Stats', () => {
+        const testUsername = 'testUser';
+        it('should get all users stats', async () => {
+            const response = await api.stats.getAllUsersStats();
+            expect(response.isOk).toBe(true);
+            if (response.isOk) {
+                expect(Array.isArray(response.data?.users)).toBe(true);
+            }
+        });
+        it('should get all users stats with reset', async () => {
+            const response = await api.stats.getAllUsersStats(true);
+            expect(response.isOk).toBe(true);
+        });
+        it('should get specific user stats', async () => {
+            const response = await api.stats.getUserStats(testUsername);
+            expect(response.isOk).toBe(true);
+        });
+        it('should get user online status', async () => {
+            const response = await api.stats.getUserOnlineStatus(testUsername);
+            expect(response.isOk).toBe(true);
+            if (response.isOk) {
+                expect(typeof response.data?.online).toBe('boolean');
+            }
+        });
+    });
+    describe('Inbound Stats', () => {
+        const testInbound = 'testInbound';
+        it('should get all inbounds stats', async () => {
+            const response = await api.stats.getAllInboundsStats();
+            expect(response.isOk).toBe(true);
+            if (response.isOk) {
+                expect(Array.isArray(response.data?.inbounds)).toBe(true);
+            }
+        });
+        it('should get specific inbound stats', async () => {
+            const response = await api.stats.getInboundStats(testInbound);
+            expect(response.isOk).toBe(true);
+        });
+        it('should get all inbounds stats with reset', async () => {
+            const response = await api.stats.getAllInboundsStats(true);
+            expect(response.isOk).toBe(true);
+        });
+    });
+    describe('Outbound Stats', () => {
+        const testOutbound = 'testOutbound';
+        it('should get all outbounds stats', async () => {
+            const response = await api.stats.getAllOutboundsStats();
+            expect(response.isOk).toBe(true);
+            if (response.isOk) {
+                expect(Array.isArray(response.data?.outbounds)).toBe(true);
+            }
+        });
+        it('should get specific outbound stats', async () => {
+            const response = await api.stats.getOutboundStats(testOutbound);
+            expect(response.isOk).toBe(true);
+        });
+        it('should get all outbounds stats with reset', async () => {
+            const response = await api.stats.getAllOutboundsStats(true);
+            expect(response.isOk).toBe(true);
+        });
+    });
+    afterEach(async () => {
+        if (api?.channel) {
+            await api.channel.close();
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnawave/xtls-sdk",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A Typescript SDK for XRAY (XTLS) Core GRPC Api",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -9,11 +9,29 @@
   ],
   "scripts": {
     "prepublish": "rm -rf build && tsc",
-    "build": "tsc"
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch"
   },
   "author": "Remnawave",
   "license": "MIT",
-  "keywords": [],
+  "keywords": [
+    "xtls",
+    "grpc",
+    "sdk",
+    "xray core api",
+    "typescript",
+    "xray",
+    "xray-core",
+    "api",
+    "client",
+    "network",
+    "proxy",
+    "protocol",
+    "trojan",
+    "vless",
+    "vmess"
+  ],
   "dependencies": {
     "long": "^5.2.3",
     "nice-grpc": "^2.1.10",
@@ -21,8 +39,29 @@
     "tar": "^7.4.3"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.2",
     "@types/node": "^22.9.0",
     "grpc-tools": "^1.12.4",
-    "ts-proto": "^2.2.7"
+    "ts-jest": "^29.1.0",
+    "jest": "^29.5.0",
+    "ts-proto": "^2.2.7",
+    "typescript": "^5.6.3"
+  },
+  "jest": { 
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": ".",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "./coverage",
+    "testEnvironment": "node"
   }
 }