BotsHub JavaScript SDK

The BotsHub SDK connects a Discord bot to the BotsHub platform. It can read bot metadata, collect aggregate statistics, publish those statistics to BotsHub, and receive platform events such as votes and reviews.

The SDK is designed for server-side Node.js applications and requires Node.js 18 or newer.

Install

npm install botshub

Create a client

Create the client in your bot's server process. Load all credentials from a secure server-side environment or secret manager; never include them in source control, browser code, logs, or public configuration.

import BotsHub from 'botshub';

const hub = new BotsHub({
  appId: process.env.DISCORD_APP_ID,
  botToken: process.env.DISCORD_BOT_TOKEN,
  secret: process.env.BOTSHUB_SECRET,
});

Use with discord.js

Attach an authenticated discord.js client to read information from its local cache without making additional Discord API requests.

hub.attach(discordClient);

const info = await hub.getBotInfo();
const guilds = await hub.getGuilds();
const stats = await hub.getStats();

await hub.postStats();

To publish aggregate statistics periodically:

hub.startAutoPost();

// Stop timers and close connections during application shutdown.
hub.destroy();

Standalone usage

The SDK can use the Discord REST API when a discord.js client is not attached.

const info = await hub.getBotInfo();
const guilds = await hub.getGuilds({ detailed: true });
const commands = await hub.getCommands();

Platform events

BotsHub can deliver application-scoped events through its real-time gateway. Use the SDK credentials generated in the BotsHub owner dashboard and keep the private credential server-side.

import BotsHub, { Event } from 'botshub';

const events = new BotsHub({
  appId: process.env.DISCORD_APP_ID,
  secretKey: process.env.BOTSHUB_SECRET_KEY,
});

events.subscribe(Event.EventVote, async (vote) => {
  await handleVote(vote);
});

events.subscribe(Event.EventReview, async (review) => {
  await handleReview(review);
});

await events.connect();

The gateway automatically authenticates the client, maintains heartbeats, reconnects after temporary failures, and rejects events outside the configured application scope.

Available operations

• attach(client) — use an existing discord.js client.
• getBotInfo() — read basic bot and application metadata.
• getGuilds(options) — read guild counts or detailed guild information.
• getCommands() — read registered application commands.
• getStats() — collect aggregate bot statistics.
• postStats(extra) — send aggregate statistics to BotsHub.
• startAutoPost(intervalMs) — periodically send statistics.
• connect() and disconnect() — manage the real-time event connection.
• subscribe(event, listener) — receive a platform event.
• ping() — check Discord and BotsHub connectivity.
• destroy() — release timers, listeners, cache, and connections.

Security

• Run the SDK only in a trusted server environment.
• Store credentials in environment variables or a dedicated secret manager.
• Never send bot tokens, private keys, user data, or credentials as event data.
• Rotate a credential from the BotsHub dashboard if it may have been exposed.
• Grant the application access only to the secrets it needs.