@remnawave/xtls-sdk/build/src/stats/stats.service.d.ts

A Typescript SDK for XRAY (XTLS) Core GRPC Api

import { Channel } from 'nice-grpc';
import { GetAllUsersStatsResponseModel, GetUserStatsResponseModel, GetSysStatsResponseModel, GetUserOnlineStatusResponseModel, GetAllInboundsStatsResponseModel, GetInboundStatsResponseModel, GetAllOutboundsStatsResponseModel, GetOutboundStatsResponseModel, GetUsersStatsResponseModel } from './models';
import { StatsServiceClient } from '../xray-protos/app/stats/command/command';
import { ISdkResponse } from '../common/types';
/**
 * Service class for interacting with Xray server statistics.
 * Provides methods to retrieve system and user statistics.
 *
 * @example
 * ```typescript
 * // Create a new StatsService instance
 * const stats = new StatsService(channel);
 *
 * // Get system stats
 * const sysStats = await stats.getSysStats();
 *
 * // Get all users stats
 * const allUsersStats = await stats.getAllUsersStats();
 *
 * // Get specific user stats
 * const userStats = await stats.getUserStats('username123');
 *
 * // Check if user is online
 * const isOnline = await stats.getUserOnlineStatus('username123');
 * ```
 */
export declare class StatsService {
    private readonly channel;
    /**
     * The gRPC client instance for making stats-related requests to the Xray server
     * @private
     */
    private readonly client;
    /**
     * Cached flag indicating whether the remote Xray server supports the
     * `GetUsersStats` unary method. `null` means "not probed yet", `true` means
     * the method is available, `false` means the legacy fallback should be used.
     *
     * The flag is cached for the lifetime of this instance — if the Xray core
     * is upgraded without re-creating the SDK, a manual re-instantiation is
     * required to re-detect support.
     * @private
     */
    private supportsGetUsersStats;
    /**
     * Creates a new StatsService instance
     * @param channel - The gRPC channel to use for communication with the Xray server
     */
    constructor(channel: Channel);
    /**
     * Retrieves system statistics from the Xray server.
     * This includes information about the system's overall performance and resource usage.
     *
     * @returns {Promise<ISdkResponse<GetSysStatsResponseModel>>} A promise that resolves to:
     * - On success: An object with `isOk: true` and `data` containing the system stats
     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
     *
     * @example
     * ```typescript
     * const stats = new StatsService(channel);
     * const response = await stats.getSysStats();
     *
     * if (response.isOk) {
     *   console.log(response.data); // GetSysStatsResponseModel
     * } else {
     *   console.error(response.message); // Error message
     * }
     * ```
     */
    getSysStats(): Promise<ISdkResponse<GetSysStatsResponseModel>>;
    /**
     * Retrieves statistics for all users from the Xray server.
     * This provides a comprehensive view of all user activities and their resource usage.
     *
     * @param {boolean} reset - Whether to reset the statistics after retrieving them. Defaults to false.
     * @returns {Promise<ISdkResponse<GetAllUsersStatsResponseModel>>} A promise that resolves to:
     * - On success: An object with `isOk: true` and `data` containing user stats
     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
     *
     * @example
     * ```typescript
     * const stats = new StatsService(channel);
     *
     * // Get stats without resetting
     * const response = await stats.getAllUsersStats();
     *
     * // Get stats and reset them
     * const responseWithReset = await stats.getAllUsersStats(true);
     *
     * if (response.isOk) {
     *   console.log(response.data.users); // Array of user statistics
     * } else {
     *   console.error(response.message); // Error message
     * }
     * ```
     */
    getAllUsersStats(reset?: boolean): Promise<ISdkResponse<GetAllUsersStatsResponseModel>>;
    /**
     * Retrieves statistics for a specific user from the Xray server.
     * This includes detailed information about the user's network usage, connections, and other metrics.
     *
     * @param {string} username - The username to get statistics for
     * @param {boolean} reset - Whether to reset the statistics after retrieving them. Defaults to false.
     * @returns {Promise<ISdkResponse<GetUserStatsResponseModel>>} A promise that resolves to:
     * - On success: An object with `isOk: true` and `data` containing the user's stats
     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
     *
     * @example
     * ```typescript
     * const stats = new StatsService(channel);
     *
     * // Get user stats without resetting
     * const response = await stats.getUserStats('username123');
     *
     * // Get user stats and reset them
     * const responseWithReset = await stats.getUserStats('username123', true);
     *
     * if (response.isOk) {
     *   console.log(response.data.user); // User statistics
     * } else {
     *   console.error(response.message); // Error message
     * }
     * ```
     */
    getUserStats(username: string, reset?: boolean): Promise<ISdkResponse<GetUserStatsResponseModel>>;
    /**
     * Checks if a specific user is currently online on the Xray server.
     * This method queries the server's real-time connection status for the specified user.
     *
     * @param {string} username - The username to check online status for
     * @returns {Promise<ISdkResponse<GetUserOnlineStatusResponseModel>>} A promise that resolves to:
     * - On success: An object with `isOk: true` and `data` containing the user's online status (`data.online`)
     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
     *
     * @example
     * ```typescript
     * const stats = new StatsService(channel);
     * const response = await stats.getUserOnlineStatus('username123');
     *
     * if (response.isOk) {
     *   if (response.data.online) {
     *     console.log('User is online');
     *   } else {
     *     console.log('User is offline');
     *   }
     * } else {
     *   console.error(response.message); // Error message
     * }
     * ```
     */
    getUserOnlineStatus(username: string): Promise<ISdkResponse<GetUserOnlineStatusResponseModel>>;
    /**
     * Gets statistics for all inbound connections.
     *
     * @param reset - Whether to reset the statistics after retrieving them. Defaults to false.
     * @returns A promise that resolves to an ISdkResponse containing:
     * - On success: An object with `isOk: true` and data containing an array of inbound stats
     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
     *
     * @example
     * ```typescript
     * const stats = new StatsService(channel);
     * const response = await stats.getAllInboundsStats();
     *
     * if (response.isOk) {
     *   console.log('Inbound stats:', response.data.inbounds);
     * } else {
     *   console.error(response.message); // Error message
     * }
     * ```
     */
    getAllInboundsStats(reset?: boolean): Promise<ISdkResponse<GetAllInboundsStatsResponseModel>>;
    /**
     * Gets statistics for a specific inbound connection.
     *
     * @param inbound - The name/tag of the inbound connection to get stats for
     * @param reset - Whether to reset the statistics after retrieving them. Defaults to false.
     * @returns A promise that resolves to an ISdkResponse containing:
     * - On success: An object with `isOk: true` and data containing the inbound stats
     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
     *
     * @example
     * ```typescript
     * const stats = new StatsService(channel);
     * const response = await stats.getInboundStats('http_in');
     *
     * if (response.isOk) {
     *   console.log('Inbound stats:', response.data.stats);
     * } else {
     *   console.error(response.message); // Error message
     * }
     * ```
     */
    getInboundStats(inbound: string, reset?: boolean): Promise<ISdkResponse<GetInboundStatsResponseModel>>;
    /**
     * Gets statistics for all outbound connections.
     *
     * @param reset - Whether to reset the statistics after retrieving them. Defaults to false.
     * @returns A promise that resolves to an ISdkResponse containing:
     * - On success: An object with `isOk: true` and data containing an array of outbound stats
     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
     *
     * @example
     * ```typescript
     * const stats = new StatsService(channel);
     * const response = await stats.getAllOutboundsStats();
     *
     * if (response.isOk) {
     *   console.log('Outbound stats:', response.data.outbounds);
     * } else {
     *   console.error(response.message); // Error message
     * }
     * ```
     */
    getAllOutboundsStats(reset?: boolean): Promise<ISdkResponse<GetAllOutboundsStatsResponseModel>>;
    /**
     * Gets statistics for a specific outbound connection.
     *
     * @param outbound - The name/tag of the outbound connection to get stats for
     * @param reset - Whether to reset the statistics after retrieving them. Defaults to false.
     * @returns A promise that resolves to an ISdkResponse containing:
     * - On success: An object with `isOk: true` and data containing the outbound stats
     * - On failure: An object with `isOk: false` and error details from STATS_ERRORS
     *
     * @example
     * ```typescript
     * const stats = new StatsService(channel);
     * const response = await stats.getOutboundStats('http_out');
     *
     * if (response.isOk) {
     *   console.log('Outbound stats:', response.data.stats);
     * } else {
     *   console.error(response.message); // Error message
     * }
     * ```
     */
    getOutboundStats(outbound: string, reset?: boolean): Promise<ISdkResponse<GetOutboundStatsResponseModel>>;
    /**
     * Retrieves per-user statistics (online IP list and, optionally, traffic)
     * from the Xray server.
     *
     * Prefers the native `GetUsersStats` gRPC method introduced in recent
     * Xray-core versions. If the server replies with `UNIMPLEMENTED` (i.e. the
     * method is missing), transparently falls back to the legacy approach of
     * combining `GetAllOnlineUsers` + `GetStatsOnlineIpList`. The detection
     * result is cached for the lifetime of this service instance, so the
     * `UNIMPLEMENTED` round-trip happens at most once.
     *
     * Note: the `includeTraffic` flag is honored only on the native path. In
     * legacy mode traffic is always returned as `undefined`, since the old
     * endpoints do not expose per-user traffic in a single call.
     *
     * @param includeTraffic - Whether to request traffic counters alongside IPs (native path only).
     * @param reset - Whether to reset the stats after retrieving them.
     */
    getUsersStats(includeTraffic?: boolean, reset?: boolean): Promise<ISdkResponse<GetUsersStatsResponseModel>>;
    /**
     * Legacy fallback for {@link getUsersStats}. Uses `GetAllOnlineUsers` to
     * enumerate currently connected users and then queries
     * `GetStatsOnlineIpList` for each of them in parallel with a bounded
     * worker pool. Always returns `traffic: undefined` for every user.
     * @private
     */
    private getUsersStatsLegacy;
    /**
     * Gets the raw gRPC client for direct access to all stats service methods
     * @returns The underlying StatsServiceClient instance
     */
    get rawClient(): StatsServiceClient;
}
//# sourceMappingURL=stats.service.d.ts.map