Core Concepts
Universal parser
One shape for every list response.
Lists name the same concept ten different ways: server_count, guildCount, guilds, servers, count. The parser reads each field in priority order, including nested paths like stats.server_count, and returns UniversalBot:
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
}arrays and votes only
const many = parser.parseBots(list, rawArray);
const justVotes = parser.parseVotes(list, rawResponse);