javascript.mdx

title	description
JavaScript	Community maintained Node.js client for the topstats.gg API.

import { Steps, TabItem, Tabs } from '@astrojs/starlight/components'

TopStats SDK

Welcome to the community maintained Node.js client for the topstats.gg API.

1. Install TopStats SDK

   npm install @topstats/sdk

2. Initialize the Client

   import { Client } from "@topstats/sdk";
   
   const client = new Client("YOUR_TOKEN");

3. Make Your First Request

   // Get information about a bot
   const bot = await client.getBot("583807014896140293");
   console.log(bot.name, bot.server_count);

Usage Examples

```typescript // Get detailed bot information const bot = await client.getBot("583807014896140293"); console.log(bot.name, bot.server_count); ``` ```typescript // Get historical statistics const history = await client.getBotHistorical( "583807014896140293", "30d", "monthly_votes" ); console.log(history.data); ``` ```typescript // Get top bots const rankings = await client.getRankings({ sortBy: "monthly_votes_rank", sortMethod: "desc", limit: 10 }); console.log(rankings.data); ```

API Reference

Methods

```typescript getBot(botId: string): Promise

// Example
const bot = await client.getBot("583807014896140293");
```

```typescript getBotHistorical( botId: string, timeFrame: HistoricalTimeFrame, type: HistoricalDataType ): Promise

// Available timeframes
enum HistoricalTimeFrame {
  ALL_TIME = "alltime",
  FIVE_YEARS = "5y",
  THREE_YEARS = "3y",
  ONE_YEAR = "1y",
  NINE_MONTHS = "270d",
  SIX_MONTHS = "180d",
  NINETY_DAYS = "90d",
  THIRTY_DAYS = "30d",
  SEVEN_DAYS = "7d",
  ONE_DAY = "1d",
  TWELVE_HOURS = "12hr",
  SIX_HOURS = "6hr",
}

// Available data types 
enum HistoricalDataType {
  MONTHLY_VOTES = "monthly_votes",
  TOTAL_VOTES = "total_votes",
  SERVER_COUNT = "server_count",
  SHARD_COUNT = "shard_count",
}
```

```typescript getBotRecent(botId: string): Promise

// Example
const recent = await client.getBotRecent("583807014896140293");
```

```typescript getRankings(options: RankingsRequest): Promise

// Example
const rankings = await client.getRankings({
  sortBy: "monthly_votes_rank",
  sortMethod: "desc",
  limit: 250, // Optional, defaults to 100
});
```

Response Types

```typescript interface BotData { id: string; name: string; server_count: number; monthly_votes: number; total_votes: number; // ... and more } ``` ```typescript interface RecentDataResponse { hourlyData: RecentData[]; dailyData: RecentData[]; } ``` ```typescript interface RankingsResponse { totalBotCount: number; data: RankingsData[]; } ```

Error Handling

```typescript try { await client.getBot("invalid-id"); } catch (error) { if (error instanceof RateLimitError) { console.log("Rate limited, try again later"); } else if (error instanceof TopStatsError) { console.error("API Error:", error.message); } } ``` ```typescript try { const bot = await client.getBot("invalid-id"); } catch (error) { switch(true) { case error instanceof RateLimitError: // Handle rate limiting console.log("Rate limited, retry after:", error.retryAfter); break; case error instanceof TopStatsError: // Handle API errors console.error("API Error:", error.message, error.code); break; default: // Handle unexpected errors console.error("Unknown error:", error); } } ```

Rate Limits

The API implements rate limiting to ensure fair usage. For detailed information about rate limits and best practices, please refer to our rate limit documentation.