Client
The Client class is the primary entry point for building a Lunibee bot. It coordinates the REST API transport, Gateway WebSocket connection, resource caches, and event system.
Import
Section titled “Import”import { Client } from "lunibee";import { Client } from "lunibee";Constructor
Section titled “Constructor”new Client(options: ClientOptions)| Parameter | Type | Description |
|---|---|---|
options.token |
string |
Required. Discord bot token (an empty token throws a TypeError). |
options.intents |
GatewayIntentResolvable (array) |
Required. Gateway intents to subscribe to, as an array: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages]. An OR-ed number throws a TypeError. |
options.rest |
RESTOptions |
Optional REST client configuration. |
options.gateway |
GatewayOptions |
Optional Gateway configuration. |
options.compress |
boolean |
zlib-stream Gateway compression (off by default); shorthand for gateway: { compress }, which wins when both are set. |
import { Client, IntentBits } from "lunibee";
const client = new Client({ token: process.env.DISCORD_TOKEN!, intents: [IntentBits.guilds, IntentBits.guildMessages, IntentBits.messageContent],});import { Client, IntentBits } from "lunibee";
const client = new Client({ token: process.env.DISCORD_TOKEN, intents: [IntentBits.guilds, IntentBits.guildMessages, IntentBits.messageContent],});Properties
Section titled “Properties”| Property | Type | Description |
|---|---|---|
client.rest |
REST |
Low-level REST transport. |
client.ws / client.gateway |
Gateway |
Active Gateway WebSocket connection. |
client.users |
UserManager |
User cache and fetcher. |
client.guilds |
GuildManager |
Guild cache and fetcher. |
client.channels |
ChannelManager |
Channel cache and fetcher. |
client.application.commands |
ApplicationCommandManager |
Application command manager. |
client.api |
Api |
Chained REST API; see bot.api. |
client.commands |
CommandRegistry |
Commands made with command(); see Commands. |
client.stageInstances |
StageInstanceManager |
Stage instances, cached by stage channel ID. |
client.applicationEmojis |
ApplicationEmojiManager | undefined |
The application’s own emojis; set on READY. |
client.options |
ClientOptions |
The options the client was created with. |
client.user |
UserData | undefined |
Authenticated bot user (available after ready). |
client.state |
ClientState |
Current lifecycle state: "idle", "connecting", "ready", or "destroyed". |
client.ping |
number |
Current WebSocket heartbeat latency in ms. |
client.uptime |
number | null |
Milliseconds since the client became ready, or null. |
client.token |
string | null |
The bot token, or null once destroyed. |
client.readyAt |
Date | undefined |
When the client last became ready. |
Methods
Section titled “Methods”login(token?)
Section titled “login(token?)”Connects to Discord. A token passed here replaces the one from the constructor. Resolves with the token used (do not log it); rejects on a destroyed client.
await client.login();await client.login();destroy()
Section titled “destroy()”Permanently closes the Gateway connection, stops running collectors and clears the user, guild and channel caches.
client.destroy();isReady()
Section titled “isReady()”Returns true if the client is in the "ready" state.
if (client.isReady()) { console.log("Bot is online!");}if (client.isReady()) { console.log("Bot is online!");}setPresence(data)
Section titled “setPresence(data)”Sends a presence update. Returns whether it was sent (false while the Gateway is not connected).
client.setPresence({ status: "online", activities: [{ name: "custom_status", state: "🐝 Buzzing!", type: 4 }],});client.setPresence({ status: "online", activities: [{ name: "custom_status", state: "🐝 Buzzing!", type: 4 }],});Events
Section titled “Events”client.on("ready", (user) => { console.log(`🐝 Logged in as ${user.username}!`);});
client.on("messageCreate", async (message) => { if (message.content === "!ping") { await message.reply("Pong! 🏓"); }});
client.on("interactionCreate", async (interaction) => { if (interaction.isChatInputCommand() && interaction.commandName === "hello") { await interaction.reply({ content: "Hello! 👋" }); }});client.on("ready", (user) => { console.log(`🐝 Logged in as ${user.username}!`);});
client.on("messageCreate", async (message) => { if (message.content === "!ping") { await message.reply("Pong! 🏓"); }});
client.on("interactionCreate", async (interaction) => { if (interaction.isChatInputCommand() && interaction.commandName === "hello") { await interaction.reply({ content: "Hello! 👋" }); }});Full Example
Section titled “Full Example”import { Client, IntentBits, CreateEmbed } from "lunibee";
const client = new Client({ token: process.env.DISCORD_TOKEN!, intents: [IntentBits.guilds, IntentBits.guildMessages, IntentBits.messageContent],});
client.on("ready", (user) => { console.log(`🐝 Ready as ${user.username}`);});
client.on("messageCreate", async (message) => { if (message.author.bot) return; if (message.content === "!status") { const embed = new CreateEmbed() .setTitle("Bot Status") .addFields( { name: "Ping", value: `${client.ping}ms`, inline: true }, { name: "Uptime", value: `${Math.floor((client.uptime ?? 0) / 1000)}s`, inline: true }, ) .setColor(0xf59e0b); await message.reply({ embeds: [embed] }); }});
await client.login();import { Client, IntentBits, CreateEmbed } from "lunibee";
const client = new Client({ token: process.env.DISCORD_TOKEN, intents: [IntentBits.guilds, IntentBits.guildMessages, IntentBits.messageContent],});
client.on("ready", (user) => { console.log(`🐝 Ready as ${user.username}`);});
client.on("messageCreate", async (message) => { if (message.author.bot) return; if (message.content === "!status") { const embed = new CreateEmbed() .setTitle("Bot Status") .addFields( { name: "Ping", value: `${client.ping}ms`, inline: true }, { name: "Uptime", value: `${Math.floor((client.uptime ?? 0) / 1000)}s`, inline: true }, ) .setColor(0xf59e0b); await message.reply({ embeds: [embed] }); }});
await client.login();0.2.0 Additions
Section titled “0.2.0 Additions”Options
Section titled “Options”| Option | Description |
|---|---|
messageCache: { maxSize?, ttl? } |
Opt-in bounded per-channel message cache (maxSize defaults to 100). Without it messages are not cached. |
cache: { users?, members?, roles?, emojis?, presences? } |
Turn off caching of a resource from Gateway events (all true by default), or turn on presences (off by default) to get previous on presenceUpdate. |
allowedMentions (0.2.2) |
Default allowed_mentions for every message the client sends: channel send/edit, message.reply(), interaction replies, edits and follow-ups. A message’s own allowed_mentions wins. Not applied to deferrals or modals. |
Mentions safety
Section titled “Mentions safety”Text that comes from users (AFK reasons, tags, echoed input) can contain @everyone or role mentions. Set a safe default once and opt in per message:
const client = new Client({ token: process.env.DISCORD_TOKEN!, intents: [GatewayIntentBits.Guilds], allowedMentions: { parse: [] }, // nothing pings by default});
await channel.send({ content: `<@${user.id}> welcome!`, allowed_mentions: { users: [user.id] } }); // this one doesMembers
Section titled “Members”| Member | Description |
|---|---|
monetization |
MonetizationManager for SKUs, entitlements and subscriptions; set on READY. |
permissionsFor(memberId, guildOrChannelId) |
Effective permissions from cached state; threads use their parent’s overwrites. Returns null when the guild, member or thread parent is not cached. |
createCollector(event, options) |
Collector over a client event; stopped by destroy(). |
fetchDefaultSoundboardSounds() |
Discord’s default soundboard sounds. |
setActivity(name, { type?, url?, state?, status? }) |
Sets one activity (null clears it); type defaults to Playing, status to "online". Returns whether it was sent. |
sendVoiceState(guildId, channelId, { selfMute?, selfDeaf? }) |
Joins, moves or (with null) leaves a voice channel; returns false instead of throwing when it cannot send. setVoiceState(data) sends a raw payload. |
requestGuildMembers(data) |
Sends a Gateway member request; returns whether it was sent. |
guild(id), channel(id), person(id), member(guildId, userId), role(guildId, roleId), message(channelId, messageId) |
Handles. |
generateInvite({ scopes?, permissions? }) |
OAuth2 invite URL (scopes default to ["bot"]); throws before ready. |
fetchWebhook, fetchGuildPreview, fetchVoiceRegions, fetchInvite, fetchSticker, fetchPremiumStickerPacks, fetchGuildTemplate |
One-off REST fetches. |
interactionWebhookMessage(method, appId, token, messageId, data?) |
Reads, edits or deletes an interaction reply or follow-up. |