Handles
A handle refers to one Discord thing by its ids. It holds no data, so it is cheap to create, can be made before the thing is cached, and fails only when you use it.
import { Client } from "lunibee";
const bot = new Client({ token: process.env.DISCORD_TOKEN!, intents });
const member = await bot.member(guildId, userId).get(); // cache, else Discordawait bot.member(guildId, userId).timeout("10m", "spam");await bot.channel(channelId).send("hello");The three reads
Section titled “The three reads”Every handle reads the same way:
| Method | What it does |
|---|---|
peek() |
Returns the cached value, or undefined. Never makes a request. |
get() |
Returns the cached value, or fetches it from Discord when it is not cached. |
fetch() |
Asks Discord now and refreshes the cache. |
A get() and a fetch() for the same id at the same time share one request, and a Gateway update that arrives while a fetch is in flight is not overwritten by it.
Entry points
Section titled “Entry points”| Call | Handle |
|---|---|
bot.guild(guildId) |
GuildHandle |
bot.channel(channelId) |
ChannelHandle |
bot.member(guildId, userId) |
MemberHandle |
bot.role(guildId, roleId) |
RoleHandle |
bot.person(userId) |
UserHandle (bot.user is the bot’s own account) |
bot.message(channelId, messageId) |
MessageHandle |
Handles lead to each other: bot.guild(id).member(userId), .role(roleId), .channel(channelId), bot.channel(id).message(messageId), member.guild(), member.user(), message.channel().
Actions
Section titled “Actions”| Handle | Methods |
|---|---|
GuildHandle |
ban(userId, options?), unban(userId, reason?), edit(options), leave() |
MemberHandle |
kick(reason?), ban(options?), unban(reason?), edit(options), addRole(roleId, reason?), removeRole(roleId, reason?), timeout(duration | null, reason?) |
RoleHandle |
edit(options), delete(reason?) |
ChannelHandle |
send(message), messages(query?), edit(options), delete(reason?), bulkDelete(ids, reason?) |
MessageHandle |
edit(message), delete(reason?), reply(message), react(emoji), pin(reason?), unpin(reason?), crosspost() |
UserHandle |
dm(), send(message) |
bot.channel(id).as("voice") gets the channel and returns it typed as that kind (several kinds may be passed), or rejects with a TypeError.
Creating channels
Section titled “Creating channels”bot.guild(id).createChannel(options) takes a kind, which decides the other options, and returns a channel typed to match.
const category = await bot.guild(id).createChannel({ kind: "category", name: "Support" });const text = await bot.guild(id).createChannel({ kind: "text", name: "general", parent: category.id, topic: "Say hi", slowmode: 5,});const voice = await bot.guild(id).createChannel({ kind: "voice", name: "Talk", userLimit: 10 }); // VoiceChannelconst forum = await bot.guild(id).createChannel({ kind: "forum", name: "help", tags: [{ name: "bug", emoji: "🐛" }], defaultReaction: "👍", layout: "list",});| Kind | Options besides name, parent, position, permissionOverwrites, reason |
|---|---|
"text", "announcement" |
topic, nsfw, slowmode (0-21600 s), autoArchive |
"voice", "stage" |
bitrate, userLimit (0-99), region, videoQuality ("auto" or "720p"), nsfw |
"category" |
none |
"forum", "media" |
topic, nsfw, slowmode, threadSlowmode, autoArchive, tags, defaultReaction, sortOrder ("latest-activity" or "creation-date"), layout (forum only: "list" or "gallery") |
Emojis are a unicode character or a custom emoji’s id. A name outside 1-100 characters or a number Discord would refuse rejects with a RangeError before any request.
message is text or a full payload (embeds, components, files, …). The audit-log reason goes in reason, or in options.reason where the method takes options.
Durations
Section titled “Durations”timeout() takes milliseconds or text: "90s", "10m", "2h", "1d", "1w", "1h30m". null lifts the timeout. A bad duration rejects with a RangeError before any request. parseDuration() is exported if you need the same parsing.
Collections
Section titled “Collections”bot.guild(id).members and .roles are the guild’s cached collections and change as the Gateway updates them. .channels is a collection of that guild’s cached channels, taken when you read it.
const admins = bot.guild(guildId).members.filter(m => m.permissions.has("Administrator"));const text = bot.guild(guildId).channels.find(c => c.name === "general");The managers (bot.guilds, bot.channels, bot.users) are still there, and are what handles use underneath.
channelCreatePayload(options) is the function that turns these createChannel() options into Discord’s request body. It is exported for code that sends the request itself; it throws for a name or number Discord would refuse.