@topstats/sdk
Version:
Official Node.js client for the topstats.gg API
112 lines (111 loc) • 3.77 kB
TypeScript
/**
* @packageDocumentation
* TopStats - Community maintained Node.js client for the topstats.gg API
* @version 1.0.0
*/
import { BotData, HistoricalData, HistoricalTimeFrame, HistoricalDataType, RecentDataResponse } from './types/discord/bots';
import { RankingsRequest, RankingsResponse } from './types/discord/rankings';
import { GetUsersBotsResponse } from './types/discord/users';
import { CompareBotsHistoricalRequest } from './types/discord/compare';
export interface ClientOptions {
/** API Token for authentication */
token: string;
/** Optional custom base URL */
baseUrl?: string;
}
/**
* Main client class for interacting with the TopStats API
* @example
* ```typescript
* const client = new Client({ token: 'your-token' });
* // or
* const client = new Client('your-token');
*
* // Get bot info
* const bot = await client.getBot('123456789');
* ```
*/
export declare class Client {
private readonly token;
private readonly BASE_URL;
/**
* Creates a new TopStats API client
* @param options - Token string or client options object
*/
constructor(options: string | ClientOptions);
/**
* Validates a Discord bot ID format
* @throws {TopStatsError} If ID format is invalid
*/
private validateBotId;
/**
* Makes an HTTP request to the API
* @throws {RateLimitError} When rate limited
* @throws {TopStatsError} For other API errors
*/
private _request;
/**
* Fetches detailed information about a specific bot
* @param botId - The Discord bot ID
* @throws {TopStatsError} If bot ID is invalid
*/
getBot(botId: string): Promise<BotData>;
/**
* Fetch historical data for a specific bot
* @param botId - The Discord bot ID
* @param timeFrame - Time frame for historical data
* @param type - Type of data to fetch
*/
getBotHistorical<T extends HistoricalDataType>(botId: string, timeFrame: HistoricalTimeFrame, type: T): Promise<{
data: Array<Extract<HistoricalData, {
type: T;
}>>;
}>;
/**
* Fetches recent data for a specific bot
* @param botId - The Discord bot ID
*/
getBotRecent(botId: string): Promise<RecentDataResponse>;
/**
* Fetches bot rankings based on specified criteria
* @param options - Ranking options
* @throws {TopStatsError} If limit is invalid
*/
getRankings(options: Omit<RankingsRequest, 'limit'> & {
limit?: number;
}): Promise<RankingsResponse>;
/**
* Fetches a user's bots
* @param id - The Discord user ID
*/
getUsersBots(id: string): Promise<GetUsersBotsResponse>;
/**
* Compare multiple Discord bots.
*
* This method fetches the latest bot stats across multiple bots.
*
* @param ids - Array of Discord bot IDs
* @returns A promise with the comparison data
* @throws {TopStatsError} If any provided bot ID is invalid
*/
compareBots(ids: string[]): Promise<{
data: unknown[];
}>;
/**
* Compare historical data for multiple Discord bots.
*
* This method fetches historical data (based on the provided timeframe and data type)
* for a set of bots.
*
* @param request - Object containing an array of bot IDs, a timeFrame, and a historical data type
* @returns A promise with the historical compare data
* @throws {TopStatsError} If any provided bot ID is invalid
*/
compareBotsHistorical(request: CompareBotsHistoricalRequest): Promise<{
data: Record<string, unknown[]>;
}>;
}
export * from './types/discord/bots';
export * from './types/discord/rankings';
export * from './types/discord/users';
export * from './types/error';