discordforge-sdk

Node.js SDK for the DiscordForge bot listing platform.
No dependencies. TypeScript included.

---

Installation

npm install discordforge-sdk

Requirements: Node.js 18 or higher.

Quick Start

const { ForgeClient } = require("discordforge-sdk");

const client = new ForgeClient("YOUR_API_KEY", "YOUR_BOT_ID");

// Post your bot stats
await client.postStats({
  serverCount: 1500,
  shardCount: 2,
});

// Check if a user voted
const vote = await client.checkVote("USER_DISCORD_ID");
if (vote.hasVoted) {
  console.log("Thanks for voting!");
}

ESM / TypeScript

import { ForgeClient } from "discordforge-sdk";

const client = new ForgeClient("YOUR_API_KEY", "YOUR_BOT_ID");
const bot = await client.getBot();
console.log(`${bot.name} — ${bot.voteCount} votes`);

API Reference

new ForgeClient(apiKey, botId?, options?)

Parameter	Type	Description
apiKey	string	Your DiscordForge API key
botId	string?	Your bot's Discord snowflake ID (required for checkVote and getBot)
options.timeout	number	Request timeout in ms (default: 10000)
options.retries	number	Auto-retry count on failure (default: 3)

Methods

Method	Returns	Description	Rate Limit
postStats(stats)	Promise<void>	Update your bot's server/shard/user stats	1 req / 5 min
checkVote(userId)	Promise<VoteMetadata>	Check if a user voted in the last 12h	60 req / min
getBot()	Promise<BotInfo>	Fetch your bot's public profile	—
syncCommands(commands)	Promise<{ success, synced }>	Sync up to 200 slash commands	—

new AutoPoster(forgeClient, discordClient, options?)

Automatically posts stats to DiscordForge on a fixed interval. Works with discord.js, Eris, or any client that exposes guilds.cache.size.

const { ForgeClient, AutoPoster } = require("discordforge-sdk");

const forge = new ForgeClient("YOUR_API_KEY");
const poster = new AutoPoster(forge, discordClient);

poster.on("post", (stats) => console.log(`Posted: ${stats.serverCount} servers`));
poster.on("error", (err) => console.error(err));

Option	Type	Default	Description
interval	number	300000	Posting interval in ms (min: 5 minutes)
startImmediately	boolean	true	Post stats as soon as the client is ready
onPost	function	—	Callback fired after each successful post
onError	function	—	Callback fired on posting failure

Method	Description
start()	Start the loop (called automatically on client ready)
stop()	Pause the loop
destroy()	Stop and remove all listeners
isRunning	Whether the poster is active

Types

All interfaces are exported for use in your own code:

import type { BotStats, BotInfo, VoteMetadata, SyncCommand } from "discordforge-sdk";

Usage with discord.js

const { Client, GatewayIntentBits } = require("discord.js");
const { ForgeClient } = require("discordforge-sdk");

const bot = new Client({ intents: [GatewayIntentBits.Guilds] });
const forge = new ForgeClient("YOUR_API_KEY", "YOUR_BOT_ID");

bot.once("ready", async () => {
  // Post stats on startup
  await forge.postStats({ serverCount: bot.guilds.cache.size });

  // Update stats every 30 minutes
  setInterval(async () => {
    await forge.postStats({ serverCount: bot.guilds.cache.size });
  }, 30 * 60 * 1000);

  console.log(`${bot.user.tag} is online — stats synced to DiscordForge`);
});

bot.login("YOUR_BOT_TOKEN");

Error Handling

The SDK throws ForgeAPIError on non-2xx responses. Rate limits (429) are automatically retried.

const { ForgeClient, ForgeAPIError } = require("discordforge-sdk");

try {
  await client.postStats({ serverCount: 100 });
} catch (err) {
  if (err instanceof ForgeAPIError) {
    console.error(`API error ${err.status}:`, err.body);
    if (err.retryAfter) {
      console.log(`Retry after ${err.retryAfter}s`);
    }
  }
}

Examples

See the examples/ directory:

• Posting stats
• Checking votes
• Syncing commands
• discord.js integration

Links

• DiscordForge Dashboard
• API Documentation
• npm Package

License

MIT © DiscordForge