DiscordBotListSync-JS

Periodically post your Discord bot's stats (guild count, user count, shard count) to bot list websites. Bring your tokens, get a getStats function ready, and the library handles scheduling, request formats, and error isolation for every supported list.

• Runtime-agnostic - works on Node.js (>= 18), Bun and Deno. Uses only web-standard fetch and timers, zero runtime dependencies.
• Library-agnostic - works with discord.js, Eris, Oceanic, or anything else; you just supply the numbers.
• Global + per-list intervals - defaults to every 10 minutes, each list can override it.
• Fault-tolerant - one list failing (bad token, downtime) never affects the others or crashes your bot.
• Easily extensible - a new bot list adapter is ~15 lines of code.

Supported bot lists

| List | Class | Fields sent | Needs botId? | | -------------------------------------------------------- | ----------------------- | ------------------------------------------------- | -------------- | | Top.gg | TopGG | server_count, shard_count | No | | Discords.com | DiscordsCom | server_count | Yes | | DiscordBotList.com | DiscordBotListCom | server_count, user_count, voice_connections | Yes | | DiscordExtremeList.xyz | DiscordExtremeListXyz | server_count, shard_count | Yes | | Radarcord.net | RadarcordNet | server_count, shard_count | Yes | | Disq.ink | DisqInk | server_count, shard_count | Yes | | Dlist.space | DlistSpace | server_count, shard_count, user_count | Yes | | Discord-Bots.gg | DiscordBotsGG | server_count, shard_count | Yes |

Install

# Bun
bun add @rabbit-company/discord-bot-list-sync
# npm / pnpm / yarn
npm install @rabbit-company/discord-bot-list-sync

Deno can import it via npm: specifiers: import { StatsPoster } from "npm:@rabbit-company/discord-bot-list-sync";

Quick start (discord.js example)

import { Client, GatewayIntentBits } from "discord.js";
import { StatsPoster, TopGG, DiscordsCom } from "@rabbit-company/discord-bot-list-sync";

const client = new Client({ intents: [GatewayIntentBits.Guilds] });

const poster = new StatsPoster({
	botId: process.env.DISCORD_CLIENT_ID, // needed by Discords.com
	interval: 10 * 60 * 1000, // global default: 10 minutes (this is also the built-in default)
	getStats: () => ({
		guildCount: client.guilds.cache.size,
		userCount: client.guilds.cache.reduce((acc, g) => acc + (g.memberCount ?? 0), 0),
		shardCount: client.shard?.count ?? 1,
	}),
	lists: [
		new TopGG({ token: process.env.TOPGG_TOKEN! }),
		// Per-list interval override: post to Discords.com every 30 minutes instead
		new DiscordsCom({ token: process.env.DISCORDS_TOKEN!, interval: 30 * 60 * 1000 }),
	],
	onPost: (list, stats) => console.log(`[stats] posted ${stats.guildCount} guilds to ${list.name}`),
	onError: (list, error) => console.error(`[stats] failed to post to ${list.name}:`, error),
});

client.once("clientReady", () => poster.start()); // "ready" on discord.js v14 and older

// Optional: push fresh numbers immediately after important events
client.on("guildCreate", () => void poster.postNow());
client.on("guildDelete", () => void poster.postNow());

API

new StatsPoster(options)

| Option | Type | Default | Description | | ------------- | ------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------- | | lists | BotList[] | - (required) | The bot list adapters to post to. | | getStats | () => BotStats \| Promise<BotStats> | - (required) | Called on every cycle to collect current stats. | | botId | string | undefined | Your bot's Discord application/client ID. Required if any list needs it (e.g. Discords.com). | | interval | number (ms) | 600000 (10 min) | Global posting interval. | | postOnStart | boolean | true | Post once immediately when start() is called. | | onPost | (list, stats) => void | undefined | Success callback. | | onError | (list, error) => void | undefined | Failure callback. HTTP failures throw BotListError with .status and .responseBody. |

Methods

• poster.start() - starts one timer per list (per-list interval wins over the global one). Timers are unref'd on Node/Bun so they won't keep a dying process alive.
• poster.stop() - clears all timers. start() can be called again later.
• poster.postNow(key?) - posts immediately to all lists, or only to the list with the given key (e.g. "topgg"). Returns Promise<Map<string, { ok: boolean; error?: unknown }>> so you can inspect per-list results. Never throws for HTTP errors.
• poster.running - true while timers are active.

BotStats

interface BotStats {
	guildCount: number; // required
	userCount?: number;
	shardCount?: number;
	voiceConnectionCount?: number;
}

Provide everything you can - each adapter picks only the fields its API supports.

Adding a new bot list

Extend BotList and implement createRequest(). The base class handles JSON serialization, the fetch call, non-2xx error handling, and the requiresBotId guard.

// src/lists/example-list.ts
import { BotList } from "../bot-list.js";
import type { BotStats, HttpRequestSpec, PostContext } from "../types.js";

/**
 * ExampleList - https://example-botlist.com
 * API: POST https://api.example-botlist.com/bots/:id/stats
 * Auth: Authorization: <token>
 */
export class ExampleList extends BotList {
	readonly key = "examplelist"; // unique, lowercase, used in logs & postNow(key)
	readonly name = "ExampleList";
	override readonly requiresBotId = true; // only if the URL/body needs the bot's client ID

	protected createRequest(stats: BotStats, context: PostContext): HttpRequestSpec {
		return {
			url: `https://api.example-botlist.com/bots/${context.botId}/stats`,
			method: "POST",
			headers: { Authorization: this.token },
			body: {
				guilds: stats.guildCount,
				users: stats.userCount, // undefined fields are dropped by JSON.stringify
				shards: stats.shardCount,
			},
		};
	}
}

Then export it from src/lists/index.ts:

export { ExampleList } from "./example-list.js";

That's it - it automatically gets scheduling, per-list intervals, callbacks, and error handling. Add a small test in tests/ mirroring the existing ones to lock in the request shape.

Development

bun install       # install dev dependencies
bun test          # run the test suite (fetch is mocked - no real requests)
bun run typecheck # strict TypeScript check
bun run build     # emit dist/ (ESM JS + .d.ts)

License

MIT