Documentation

pick your package manager

npm install @potenfyrstudios/discord-botlists
bun add @potenfyrstudios/discord-botlists
pnpm add @potenfyrstudios/discord-botlistsCopy

statsProvider: full control, any framework or none

const lists = new Botlists({
  statsProvider: async () => ({
    serverCount: shardManager.totalGuilds,
    shardCount: shardManager.shardCount,
    shards: shardManager.perShardCounts,
  }),
});

// or per call, no constructor changes
await lists.postStats({ serverCount: myGuildCount });Copy

the usual setup

import { Client } from 'discord.js';
import { Botlists } from '@potenfyrstudios/discord-botlists';

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

const lists = new Botlists({
  client,                       // optional: discord.js or Eris client
  tokens: {
    'top.gg': process.env.TOPGG_TOKEN,
    'discordbotlist.com': process.env.DBL_TOKEN,
  },
  webhook: {
    port: 8080,                 // default 8080
    path: '/discord-botlists',  // default
    secret: process.env.WEBHOOK_SECRET,
  },
  startupStatusCheck: true,     // print the status table on first postStats
});Copy

// every list you have a token for
const report = await lists.postStats({ serverCount: 120 });
report.posted;  // 4
report.failed;  // 0
report.skipped; // lists without tokens

// shard aware posting
await lists.postStats({
  serverCount: client.guilds.cache.size,
  shardCount: client.shard?.count,
  shards: await client.shard?.fetchClientValues('guilds.cache.size') as number[],
});

// only some lists, or skip some
await lists.postStats({ serverCount: 120 }, { only: ['top.gg', 'botlist.me'] });
await lists.postStats({ serverCount: 120 }, { skip: ['bots.ondiscord.xyz'] });

// one specific list
await lists.postStatsTo('radarcord', { serverCount: 120 });

// one request, botblock fans out to every list for you
await lists.postViaBotBlock({ serverCount: 120 });Copy

auto posting on an interval

lists.startAutoPost(30 * 60 * 1000); // every 30 minutes, minimum 60s
lists.stopAutoPost();Copy

await lists.startWebhooks();
console.log(lists.webhook.address); // http://localhost:8080/discord-botlists

// give each dashboard:
//   https://yourdomain.dev/discord-botlists/top.gg
//   https://yourdomain.dev/discord-botlists/botlist.me

lists.on('vote', (vote) => {
  vote.listId;     // 'top.gg'
  vote.voterId;    // '160105994217586689'
  vote.voterName;  // 'someuser'
  vote.weight;     // 2 on weekend multiplier lists
  vote.weekend;    // true
  vote.isTest;     // dashboard test button
  vote.query;      // { ref: 'partner' }
  vote.raw;        // untouched original body
});

lists.on('review', (review) => {
  review.rating;   // 1 to 5 when sent
  review.content;  // review text
});

lists.on('comment', onComment);
lists.on('rating', onRating);
lists.on('test', (vote) => console.log('test from', vote.listId));
lists.on('statsPosted', (report) => console.log(report.posted, 'lists updated'));
lists.on('error', (error) => console.error(error.message));Copy

// express, fastify, whatever you already run
app.post('/webhooks/:list', (req, res) => {
  lists.ingestWebhook(req.params.list, req.body);
  res.sendStatus(200);
});Copy

wire it up

const lists = new Botlists({
  client,
  announcer: {
    enabled: true,               // required - off by default
    format: 'embed-v2',          // 'text' | 'embed' | 'embed-v2'
    webhooks: [process.env.VOTE_WEBHOOK_URL!],   // Discord channel webhooks
    external: ['https://api.example.com/hooks/votes'], // JSON { source, event, list, vote }
    username: 'Vote Alerts',     // optional webhook identity overrides
    color: 0x5865f2,
    links: [{ label: 'Vote Again', url: 'https://top.gg/bot/YOUR_BOT/vote', emoji: '🗳️' }],
    announceTestVotes: false,    // dashboard test deliveries: ignore by default
  },
});Copy

three render formats

// 'text' - plain message content from a {placeholder} template
{ format: 'text', template: '🗳️ {voter} voted on {list}!' }

// 'embed' - classic rich embed (title, description, color, timestamp, thumbnail)
{ format: 'embed' }

// 'embed-v2' - Components V2: section + avatar accessory, separator,
// link buttons; the IS_COMPONENTS_V2 flag is set for you
{ format: 'embed-v2' }Copy

standalone use

import { Botlists, VoteAnnouncer } from '@potenfyrstudios/discord-botlists';

const announcer = new VoteAnnouncer({ format: 'embed-v2', webhooks: [url] });
announcer.on('delivered', (d) => console.log('sent to', d.target, d.status));
const lists = new Botlists({ client });
lists.on('vote', (vote) => announcer.announce(vote));Copy

security options

const lists = new Botlists({
  webhook: {
    port: 8080,
    secret: {
      'top.gg': 'shared-secret-for-topgg',
      'botlist.me': 'another-secret',
    },
    security: {
      // HMAC-SHA256 signing keys per list. when present, requests from that
      // list must carry a valid signature in x-signature-256 /
      // x-hub-signature-256 / x-signature.
      hmac: { 'top.gg': 'webhook-signing-key' },

      // per ip rate limit (default 30/min). extra requests get 429.
      rateLimit: { max: 30, windowMs: 60_000 },

      // ban an ip after N consecutive auth failures (default 10),
      // for M ms (default 15 minutes). banned ips get 403.
      banAfterFailures: 10,
      banDurationMs: 15 * 60_000,

      // only these lists may POST at all. others get 403.
      allowedLists: ['top.gg', 'botlist.me', 'discordbotlist.com'],

      // set true behind nginx/cloudflare so rate limits use the real ip.
      trustProxy: true,

      // only for local testing: accept unsigned posts.
      requireSecret: false,
    },
  },
});Copy

verify a v1 delivery inside your own framework route

// With headers passed, ingest() enforces transport auth itself and returns
// null on a bad signature. Without headers it trusts your framework's auth
// and only parses.
const parsed = lists.webhook.ingest('top.gg', req.body, {
  headers: { 'x-topgg-signature': req.headers['x-topgg-signature'] },
});
if (!parsed) return res.status(401).end();Copy

const bot = await lists.fetchBot('discord.bots.gg', '557628352828014614');
bot.name;        // 'Ticket Tool'
bot.prefix;      // '$ (Customizable)'
bot.library;     // 'discord.js'

const votes = await lists.fetchVotes('top.gg');       // number | null
const voted = await lists.hasVoted('top.gg', userId); // boolean | null
const found = await lists.searchBots('botlist.me', 'music', 5);

lists.widgetUrl('top.gg');  // widget image url
lists.viewBotUrl('top.gg'); // listing page urlCopy

import { UniversalParser } from '@potenfyrstudios/discord-botlists';

const parser = new UniversalParser();
const bot = parser.parseBot(listRecord, rawApiResponse);

interface UniversalBot {
  listId: string;      listName: string;
  id: string;          name: string;
  avatar: string | null;
  owners: string[];
  serverCount: number | null;
  votes: number | null;         monthlyVotes: number | null;
  certified: boolean | null;
  ratings: { average: number | null; count: number | null };
  tags: string[];
  raw: unknown;        fetchedAt: number;
  // ...description, invite, prefix, library, github, supportServer
}Copy

arrays and votes only

const many = parser.parseBots(list, rawArray);
const justVotes = parser.parseVotes(list, rawResponse);Copy

const board = await lists.refreshStatus();
board.summary; // { live: 33, deprecated: 0, shutdown: 0, unknown: 0 }

board.entries[0];
// { listId, listName, website, state, httpStatus, latencyMs, lastChecked }

// probe, print the unicode console table, get github issue links for dead lists
await lists.checkAndReportStatus();Copy

const lists = new Botlists({
  lists: [{
    id: 'my-list.dev',
    name: 'My List',
    website: 'https://my-list.dev',
    apiPost: 'https://api.my-list.dev/bots/:id/stats',
    postField: 'server_count',
    postMethod: 'POST',
    authHeader: 'Authorization',
    tokenEnvKey: 'DBL_MYLIST',
    webhook: { header: 'Authorization', voterField: 'user_id', eventField: null },
    supports: { post: true, get: false, widget: false, webhook: true },
    apiDocs: null, apiGet: null, viewBot: null, widget: null,
    shardField: null, shardIdField: null, shardsArrayField: null,
  }],
});Copy