Skip to content

Client & Gateway Lifecycle

The Client class in lunibee is the primary orchestrator that connects the REST API, Gateway WebSocket, caching layers, and event dispatchers into a cohesive bot interface.

Lunibee supports specifying intents as arrays or bitwise OR combinations. The public constants are:

  • IntentBits — idiomatic camelCase constants.
  • GatewayIntentBits — Discord-standard PascalCase constants.
import { Client, IntentBits } from "lunibee";
const client = new Client({
token: process.env.DISCORD_TOKEN!,
intents: [
IntentBits.guilds,
IntentBits.guildMessages,
IntentBits.messageContent,
],
});
import { Client, GatewayIntentBits } from "lunibee";
const client = new Client({
token: process.env.DISCORD_TOKEN!,
intents: [
GatewayIntentBits.Guilds,
GatewayIntentBits.GuildMessages,
GatewayIntentBits.MessageContent,
],
});
PascalCase (GatewayIntentBits) camelCase (IntentBits) Bit Shift Type
Guilds guilds 1 << 0 Standard
GuildMembers guildMembers 1 << 1 Privileged
GuildModeration guildModeration 1 << 2 Standard
GuildExpressions guildExpressions 1 << 3 Standard
GuildIntegrations guildIntegrations 1 << 4 Standard
GuildWebhooks guildWebhooks 1 << 5 Standard
GuildInvites guildInvites 1 << 6 Standard
GuildVoiceStates guildVoiceStates 1 << 7 Standard
GuildPresences guildPresences 1 << 8 Privileged
GuildMessages guildMessages 1 << 9 Standard
GuildMessageReactions guildMessageReactions 1 << 10 Standard
GuildMessageTyping guildMessageTyping 1 << 11 Standard
DirectMessages directMessages 1 << 12 Standard
DirectMessageReactions directMessageReactions 1 << 13 Standard
DirectMessageTyping directMessageTyping 1 << 14 Standard
MessageContent messageContent 1 << 15 Privileged
GuildScheduledEvents guildScheduledEvents 1 << 16 Standard
AutoModerationConfiguration autoModerationConfiguration 1 << 20 Standard
AutoModerationExecution autoModerationExecution 1 << 21 Standard
GuildMessagePolls guildMessagePolls 1 << 24 Standard
DirectMessagePolls directMessagePolls 1 << 25 Standard

GuildMembers, GuildPresences, and MessageContent are privileged Gateway intents and must be enabled for the bot in the Discord Developer Portal before use.

ActivityEnum holds Discord’s activity types: Playing, Streaming, Listening, Watching, Custom and Competing.

The short way (0.3.1) is bot.setActivity("the logs", { type: ActivityEnum.Watching, status: "idle" }); bot.setActivity(null) clears it. See Presence & Activity. setPresence() below takes the full presence object.

import { ActivityEnum } from "lunibee";
client.setPresence({
status: "online",
activities: [
{
name: "custom_status",
state: "⚡ Running on Bun & Lunibee",
type: ActivityEnum.Custom,
},
],
});

Returns the current WebSocket ping in milliseconds. This value is updated on every heartbeat acknowledgement from the gateway, and is -1 until the first one.

console.log(`Current ping: ${client.ping}ms`);

The client exposes several top-level methods to fetch resources without needing a cached guild or channel:

  • fetchWebhook(id, token?): Fetches a webhook.
  • fetchGuildPreview(guildId): Fetches preview information for a guild.
  • fetchVoiceRegions(): Returns an array of available voice regions.
  • generateInvite(options): Generates a bot invite link based on the provided permissions and scopes.
  • fetchInvite(code, options?): Fetches an invite by its code.
  • fetchSticker(id): Fetches a specific sticker by its ID.
  • fetchPremiumStickerPacks(): Fetches the list of premium sticker packs.
  • fetchGuildTemplate(code): Fetches a guild template by its code.

Joins, moves between, or leaves (channelId: null) a voice channel. Returns false without sending when disconnected, rate limited, or when the guild belongs to another shard. setVoiceState(payload) sends a raw opcode 4 payload ({ guild_id, channel_id, self_mute, self_deaf }) instead.

client.sendVoiceState(guildId, channelId, {
selfDeaf: false,
selfMute: true,
});

Requests offline or all members for a guild. This requires the GuildMembers intent.

client.requestGuildMembers({
guild_id: guildId,
query: "",
limit: 0,
});

In addition to standard entity events (like MessageCreate), the client emits events related to the gateway session lifecycle:

  • Ready: Emitted when the client connects and identifies successfully.
  • Resumed: Emitted when the client successfully resumes a dropped WebSocket connection without needing to re-identify.
  • InvalidSession: Emitted when the gateway rejects the session. Depending on the payload, the client will either attempt to resume or start a fresh session.

client.createCollector(event, options) collects the first argument of a client event and unsubscribes when it ends.

const collector = client.createCollector("interactionCreate", {
filter: (i) => i.isButton(),
idle: 30_000, // stop after 30s without a match
max: 5,
signal: controller.signal, // stop on abort
});
for await (const interaction of collector) {
if (interaction.isButton()) await interaction.deferUpdate();
}
const collected = await collector.wait();
await client.channels.endPoll(channelId, messageId);
await client.channels.fetchPollVoters(channelId, messageId, answerId);
await client.guilds.stickers(guildId).fetchAll();
await client.guilds.soundboard(guildId).fetchAll();
await client.channels.sendSoundboardSound(voiceChannelId, { soundId });
await client.monetization?.fetchEntitlements({ userId });
client.on("entitlementCreate", (entitlement) => { /* grant premium */ });