Skip to content

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 Discord
await bot.member(guildId, userId).timeout("10m", "spam");
await bot.channel(channelId).send("hello");

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.

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().

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.

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 }); // VoiceChannel
const 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.

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.

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.