BREAKING: add docs (#2442)

* refactor(helpers): Organise functions. (#2425)

* refactor: Move stage instance helper functions into `/stages` subdirectory.

* refactor: Move `followChannel.ts` to `/announcements` subdirectory.

* refactor: Move `updateVoiceState.ts` to `/guilds` directory.

* refactor: Move `getPins.ts` to `/messages` directory.

* refactor: Move voice-related helper functions into `/voice` subdirectory.

* refactor: Rename `/scheduledEvents` to `/events`.

* refactor: Move widget-related helper functions into `/widgets` subdirectory.

* refactor: Make `/integrations` a subdirectory of `/guilds`.

* refactor: Move helper functions related to interaction responses into the `/responses` subdirectory.

* refactor: Move `verifySignature.ts` to `/util` directory.

* refactor: Move `getChannelInvites.ts` to `/channels` directory.

* refactor: Make `/invites` a subdirectory of `/guilds`.

* refactor: Move reaction-related helper functions into the /reactions subdirectory.

* refactor: Move `getApplicationInfo.ts` into the `/misc` directory.

* refactor: Move voice-related helper functions from `/voice` to `/guilds/voice`.

* fix: Update and simplify type imports.

* refactor!(helpers): Rename helpers to match Discord API. Create a 1:1 helper-to-endpoint correspondence. (#2427)

* refactor: Move stage instance helper functions into `/stages` subdirectory.

* refactor: Move `followChannel.ts` to `/announcements` subdirectory.

* refactor: Move `updateVoiceState.ts` to `/guilds` directory.

* refactor: Move `getPins.ts` to `/messages` directory.

* refactor: Move voice-related helper functions into `/voice` subdirectory.

* refactor: Rename `/scheduledEvents` to `/events`.

* refactor: Move widget-related helper functions into `/widgets` subdirectory.

* refactor: Make `/integrations` a subdirectory of `/guilds`.

* refactor: Move helper functions related to interaction responses into the `/responses` subdirectory.

* refactor: Move `verifySignature.ts` to `/util` directory.

* refactor: Move `getChannelInvites.ts` to `/channels` directory.

* refactor: Make `/invites` a subdirectory of `/guilds`.

* refactor: Move reaction-related helper functions into the /reactions subdirectory.

* refactor: Move `getApplicationInfo.ts` into the `/misc` directory.

* refactor: Move voice-related helper functions from `/voice` to `/guilds/voice`.

* fix: Update and simplify type imports.

* refactor: Rename `followChannel` -> `followAnnouncementChannel`.

* refactor: Rename `createForumPost` -> `startForumThread`.

* refactor: Normalise keyword `update` -> `edit`.

* refactor: Rename `addToThread` -> `addThreadMember`.

* refactor: Rename `ChannelOverwrite` -> `ChannelPermissions`.

* refactor: Rename `startTyping` -> `triggerTypingIndicator`.

* refactor: Rename `swapChannels` -> `editChannelPositions`.

* refactor: Rename `getPins` -> `getPinnedMessages`.

* refactor: Rename `publish` -> `crosspost`.

* refactor: Normalise keyword `modify` -> `edit`.

* refactor: Normalise naming.

* fix: Imports.

* style: Remove empty object.

* refactor: Split `getArchivedThreads` into three files for public, private and private joined threads.

* refactor: Split `getApplicationCommands` into two files, for guild and global commands respectively.

* refactor: Split `getApplicationCommand` into two files, for guild and global commands respectively.

* fmt: Organise imports.

* misc: Include application command reverse transformer.

* misc: Make ordering of fields match up with the Discord API.

* fix: Add missing payload properties.

* refactor: Split `createApplicationCommand` into two files, for guild and global commands respectively.

* refactor: Split `upsertApplicationCommand` into two files, for guild and global commands respectively.

* refactor: Split `upsertApplicationCommands` into two files, for guild and global commands respectively.

* fix: Update exports.

* refactor: Split `deleteApplicationCommand` into two files, for guild and global commands respectively.

* fix: Add missing exports.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* feat: Create `getInteractionResponse.ts`.

* refactor: Matching API: `InteractionResponse` -> `FollowupMessage`.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Remove `/followups` directory in favour of newly created files in `/responses`.

* refactor: Rename `bot`/`self` -> `own`, `others` -> `user`.

* refactor: Split function into `deleteOwnReaction` and `deleteUserReaction`.

* refactor: Reduce code duplication in processing reaction string.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Rename function name.

* misc: Add aliases to functions to reduce breakage.

* refactor: Rename `startForumThread` -> `createForumThread`.

* misc: Move types from helper file to `/types` and create transformer.

* fix: Imports.

* style: Rename parameter `command` -> `payload`.

* feat: Create interaction response transformer.

* misc: Adapt code to use the interaction response transformer.

* misc: Adapt code to use interaction response transformer.

* refactor: Re-include the keyword `Override` in the file + function names.

* refactor: Rename `updateVoiceState` -> `editVoiceState` for consistency reasons.

Co-authored-by: Skillz4Killz <23035000+Skillz4Killz@users.noreply.github.com>

* BREAKING: docs(helpers): Document helper functions. (#2437)

* refactor: Move stage instance helper functions into `/stages` subdirectory.

* refactor: Move `followChannel.ts` to `/announcements` subdirectory.

* refactor: Move `updateVoiceState.ts` to `/guilds` directory.

* refactor: Move `getPins.ts` to `/messages` directory.

* refactor: Move voice-related helper functions into `/voice` subdirectory.

* refactor: Rename `/scheduledEvents` to `/events`.

* refactor: Move widget-related helper functions into `/widgets` subdirectory.

* refactor: Make `/integrations` a subdirectory of `/guilds`.

* refactor: Move helper functions related to interaction responses into the `/responses` subdirectory.

* refactor: Move `verifySignature.ts` to `/util` directory.

* refactor: Move `getChannelInvites.ts` to `/channels` directory.

* refactor: Make `/invites` a subdirectory of `/guilds`.

* refactor: Move reaction-related helper functions into the /reactions subdirectory.

* refactor: Move `getApplicationInfo.ts` into the `/misc` directory.

* refactor: Move voice-related helper functions from `/voice` to `/guilds/voice`.

* fix: Update and simplify type imports.

* refactor: Rename `followChannel` -> `followAnnouncementChannel`.

* refactor: Rename `createForumPost` -> `startForumThread`.

* refactor: Normalise keyword `update` -> `edit`.

* refactor: Rename `addToThread` -> `addThreadMember`.

* refactor: Rename `ChannelOverwrite` -> `ChannelPermissions`.

* refactor: Rename `startTyping` -> `triggerTypingIndicator`.

* refactor: Rename `swapChannels` -> `editChannelPositions`.

* refactor: Rename `getPins` -> `getPinnedMessages`.

* refactor: Rename `publish` -> `crosspost`.

* refactor: Normalise keyword `modify` -> `edit`.

* refactor: Normalise naming.

* fix: Imports.

* style: Remove empty object.

* refactor: Split `getArchivedThreads` into three files for public, private and private joined threads.

* refactor: Split `getApplicationCommands` into two files, for guild and global commands respectively.

* refactor: Split `getApplicationCommand` into two files, for guild and global commands respectively.

* fmt: Organise imports.

* misc: Include application command reverse transformer.

* misc: Make ordering of fields match up with the Discord API.

* fix: Add missing payload properties.

* refactor: Split `createApplicationCommand` into two files, for guild and global commands respectively.

* refactor: Split `upsertApplicationCommand` into two files, for guild and global commands respectively.

* refactor: Split `upsertApplicationCommands` into two files, for guild and global commands respectively.

* fix: Update exports.

* refactor: Split `deleteApplicationCommand` into two files, for guild and global commands respectively.

* fix: Add missing exports.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* feat: Create `getInteractionResponse.ts`.

* refactor: Matching API: `InteractionResponse` -> `FollowupMessage`.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Remove `/followups` directory in favour of newly created files in `/responses`.

* refactor: Rename `bot`/`self` -> `own`, `others` -> `user`.

* refactor: Split function into `deleteOwnReaction` and `deleteUserReaction`.

* refactor: Reduce code duplication in processing reaction string.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Rename function name.

* misc: Add aliases to functions to reduce breakage.

* refactor: Rename `startForumThread` -> `createForumThread`.

* misc: Move types from helper file to `/types` and create transformer.

* fix: Imports.

* style: Rename parameter `command` -> `payload`.

* feat: Create interaction response transformer.

* misc: Adapt code to use the interaction response transformer.

* misc: Adapt code to use interaction response transformer.

* docs: Document announcement channel helpers.

* docs: Document forum channel helpers.

* docs: Document stage instance helpers.

* misc: Update wording.

* docs: Document thread channel helpers.

* refactor: Re-include the keyword `Override` in the file + function names.

* refactor: Rename `updateVoiceState` -> `editVoiceState` for consistency reasons.

* docs: Document channel helpers.

* docs: Use `parameters` instead of `options` for descriptions.

* docs: Document guild discovery helpers.

* docs: Document emoji helpers.

* docs: Add missing information about which gateway events are fired.

* docs: Document auto moderation helpers.

* docs: Document scheduled event helpers.

* docs: Document integration helpers.

* docs: Document invite helpers.

* refactor: Rename `editWidget` -> `editWidgetSettings`.

* docs: Document guild widget helpers.

* docs: 'event' -> 'gateway event'.

* refactor: Rename `getAuditLogs` -> `getAuditLog`.

* docs: Document guild helpers.

* refactor: Rename `upsert*ApplicationCommand` -> `edit*ApplicationCommand`.

* docs: Document application command helpers.

* docs: Improve consistency in indentation.

* docs: Document interaction response + follow-up message helpers.

* docs: Document gateway event firings for endpoints.

* refactor: Delete `editBotNickname` due to being a subset of `editMember`.

* docs: Fix inconsistency.

* docs: Document member helpers.

* docs: Document reaction helpers.

* docs: Improve consistency.

* docs: Document message helpers.

* docs: Document role helpers.

* docs: Document guild template helpers.

* docs: Fix incorrect gateway event.

* refactor: Rename `sendWebhookMessage` -> `executeWebhook`.

* docs: Document webhook helpers.

* docs: Document voice helpers.

* fmt: Run Deno formatter.

* docs: Improve consistency.

* refactor: Rename the `/widgets` directory to `/widget`.

* fmt: Run Deno formatter.

* misc: Re-add the deleted `editBotNickname()` helper. (#2443)

* refactor: Move stage instance helper functions into `/stages` subdirectory.

* refactor: Move `followChannel.ts` to `/announcements` subdirectory.

* refactor: Move `updateVoiceState.ts` to `/guilds` directory.

* refactor: Move `getPins.ts` to `/messages` directory.

* refactor: Move voice-related helper functions into `/voice` subdirectory.

* refactor: Rename `/scheduledEvents` to `/events`.

* refactor: Move widget-related helper functions into `/widgets` subdirectory.

* refactor: Make `/integrations` a subdirectory of `/guilds`.

* refactor: Move helper functions related to interaction responses into the `/responses` subdirectory.

* refactor: Move `verifySignature.ts` to `/util` directory.

* refactor: Move `getChannelInvites.ts` to `/channels` directory.

* refactor: Make `/invites` a subdirectory of `/guilds`.

* refactor: Move reaction-related helper functions into the /reactions subdirectory.

* refactor: Move `getApplicationInfo.ts` into the `/misc` directory.

* refactor: Move voice-related helper functions from `/voice` to `/guilds/voice`.

* fix: Update and simplify type imports.

* refactor: Rename `followChannel` -> `followAnnouncementChannel`.

* refactor: Rename `createForumPost` -> `startForumThread`.

* refactor: Normalise keyword `update` -> `edit`.

* refactor: Rename `addToThread` -> `addThreadMember`.

* refactor: Rename `ChannelOverwrite` -> `ChannelPermissions`.

* refactor: Rename `startTyping` -> `triggerTypingIndicator`.

* refactor: Rename `swapChannels` -> `editChannelPositions`.

* refactor: Rename `getPins` -> `getPinnedMessages`.

* refactor: Rename `publish` -> `crosspost`.

* refactor: Normalise keyword `modify` -> `edit`.

* refactor: Normalise naming.

* fix: Imports.

* style: Remove empty object.

* refactor: Split `getArchivedThreads` into three files for public, private and private joined threads.

* refactor: Split `getApplicationCommands` into two files, for guild and global commands respectively.

* refactor: Split `getApplicationCommand` into two files, for guild and global commands respectively.

* fmt: Organise imports.

* misc: Include application command reverse transformer.

* misc: Make ordering of fields match up with the Discord API.

* fix: Add missing payload properties.

* refactor: Split `createApplicationCommand` into two files, for guild and global commands respectively.

* refactor: Split `upsertApplicationCommand` into two files, for guild and global commands respectively.

* refactor: Split `upsertApplicationCommands` into two files, for guild and global commands respectively.

* fix: Update exports.

* refactor: Split `deleteApplicationCommand` into two files, for guild and global commands respectively.

* fix: Add missing exports.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* feat: Create `getInteractionResponse.ts`.

* refactor: Matching API: `InteractionResponse` -> `FollowupMessage`.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Remove `/followups` directory in favour of newly created files in `/responses`.

* refactor: Rename `bot`/`self` -> `own`, `others` -> `user`.

* refactor: Split function into `deleteOwnReaction` and `deleteUserReaction`.

* refactor: Reduce code duplication in processing reaction string.

* refactor: Separate file into two to make 1 file correspond to 1 endpoint.

* refactor: Rename function name.

* misc: Add aliases to functions to reduce breakage.

* refactor: Rename `startForumThread` -> `createForumThread`.

* misc: Move types from helper file to `/types` and create transformer.

* fix: Imports.

* style: Rename parameter `command` -> `payload`.

* feat: Create interaction response transformer.

* misc: Adapt code to use the interaction response transformer.

* misc: Adapt code to use interaction response transformer.

* docs: Document announcement channel helpers.

* docs: Document forum channel helpers.

* docs: Document stage instance helpers.

* misc: Update wording.

* docs: Document thread channel helpers.

* refactor: Re-include the keyword `Override` in the file + function names.

* refactor: Rename `updateVoiceState` -> `editVoiceState` for consistency reasons.

* docs: Document channel helpers.

* docs: Use `parameters` instead of `options` for descriptions.

* docs: Document guild discovery helpers.

* docs: Document emoji helpers.

* docs: Add missing information about which gateway events are fired.

* docs: Document auto moderation helpers.

* docs: Document scheduled event helpers.

* docs: Document integration helpers.

* docs: Document invite helpers.

* refactor: Rename `editWidget` -> `editWidgetSettings`.

* docs: Document guild widget helpers.

* docs: 'event' -> 'gateway event'.

* refactor: Rename `getAuditLogs` -> `getAuditLog`.

* docs: Document guild helpers.

* refactor: Rename `upsert*ApplicationCommand` -> `edit*ApplicationCommand`.

* docs: Document application command helpers.

* docs: Improve consistency in indentation.

* docs: Document interaction response + follow-up message helpers.

* docs: Document gateway event firings for endpoints.

* refactor: Delete `editBotNickname` due to being a subset of `editMember`.

* docs: Fix inconsistency.

* docs: Document member helpers.

* docs: Document reaction helpers.

* docs: Improve consistency.

* docs: Document message helpers.

* docs: Document role helpers.

* docs: Document guild template helpers.

* docs: Fix incorrect gateway event.

* refactor: Rename `sendWebhookMessage` -> `executeWebhook`.

* docs: Document webhook helpers.

* docs: Document voice helpers.

* fmt: Run Deno formatter.

* docs: Improve consistency.

* refactor: Rename the `/widgets` directory to `/widget`.

* fmt: Run Deno formatter.

* feat: Re-add `editBotNickname.ts`.

* Update helpers/members/editBotNickname.ts

Co-authored-by: Skillz4Killz <23035000+Skillz4Killz@users.noreply.github.com>

* fix: tests

* fix: bot member tests

* fix: remove submode

* fix: edit bot member returns full member

Co-authored-by: Dorian Oszczęda <vxern@wordcollector.co.uk>

helpers/channels/announcements/followAnnouncementChannel.ts

@@ -0,0 +1,34 @@
+import type { Bot } from "../../../bot.ts";
+import { DiscordFollowedChannel } from "../../../types/discord.ts";
+
+/**
+ * Follows an announcement channel, allowing messages posted within it to be cross-posted into the target channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param sourceChannelId - The ID of the announcement channel to follow.
+ * @param targetChannelId - The ID of the target channel - the channel to cross-post to.
+ * @returns An instance of {@link FollowedChannel}.
+ *
+ * @remarks
+ * Requires the `MANAGE_WEBHOOKS` permission in the __target channel__.
+ *
+ * Fires a _Webhooks Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#follow-announcement-channel}
+ */
+export async function followAnnouncementChannel(
+  bot: Bot,
+  sourceChannelId: bigint,
+  targetChannelId: bigint,
+): Promise<bigint> {
+  const result = await bot.rest.runMethod<DiscordFollowedChannel>(
+    bot.rest,
+    "POST",
+    bot.constants.routes.CHANNEL_FOLLOW(sourceChannelId),
+    {
+      webhook_channel_id: targetChannelId,
+    },
+  );
+
+  return bot.transformers.snowflake(result.webhook_id);
+}

helpers/channels/announcements/mod.ts

@@ -0,0 +1 @@
+export * from "./followAnnouncementChannel.ts";

helpers/channels/createChannel.ts

@@ -2,9 +2,27 @@ import type { Bot } from "../../bot.ts";
 import { Channel } from "../../transformers/channel.ts";
 import { DiscordChannel } from "../../types/discord.ts";
 import { ChannelTypes } from "../../types/shared.ts";
-import { OverwriteReadable } from "./editChannelOverwrite.ts";
+import { OverwriteReadable } from "./editChannelPermissionOverrides.ts";
 
-/** Create a channel in your server. Bot needs MANAGE_CHANNEL permissions in the server. */
+/**
+ * Creates a channel within a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to create the channel within.
+ * @param options - The parameters for the creation of the channel.
+ * @returns An instance of the created {@link Channel}.
+ *
+ * @remarks
+ * Requires the `MANAGE_CHANNELS` permission.
+ *
+ * If setting permission overwrites, only the permissions the bot user has in the guild can be allowed or denied.
+ *
+ * Setting the `MANAGE_ROLES` permission is only possible for guild administrators.
+ *
+ * Fires a _Channel Create_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#create-guild-channel}
+ */
 export async function createChannel(
   bot: Bot,
   guildId: bigint,

helpers/channels/createStageInstance.ts

@@ -1,26 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { StageInstance } from "../../transformers/stageInstance.ts";
-import { DiscordStageInstance } from "../../types/discord.ts";
-
-/** Creates a new Stage instance associated to a Stage channel. Requires the user to be a moderator of the Stage channel. */
-export async function createStageInstance(bot: Bot, options: CreateStageInstance): Promise<StageInstance> {
-  const result = await bot.rest.runMethod<DiscordStageInstance>(
-    bot.rest,
-    "POST",
-    bot.constants.routes.STAGE_INSTANCES(),
-    {
-      channel_id: options.channelId.toString(),
-      topic: options.topic,
-      send_start_notification: options.sendStartNotification,
-    },
-  );
-
-  return bot.transformers.stageInstance(bot, result);
-}
-
-export interface CreateStageInstance {
-  channelId: bigint;
-  topic: string;
-  /** Notify @everyone that the stage instance has started. Requires the MENTION_EVERYONE permission. */
-  sendStartNotification?: boolean;
-}

helpers/channels/deleteChannel.ts

@@ -1,6 +1,30 @@
 import type { Bot } from "../../bot.ts";
 
-/** Delete a channel in your server. Bot needs MANAGE_CHANNEL permissions in the server. Bot needs MANAGE_THREADS permissions in the server if deleting thread. */
+/**
+ * Deletes a channel from within a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to delete.
+ * @returns An instance of the deleted {@link Channel}.
+ *
+ * @remarks
+ * For community guilds, the _Rules_, _Guidelines_ and _Community Update_ channels cannot be deleted.
+ *
+ * If the channel is a thread:
+ * - Requires the `MANAGE_THREADS` permission.
+ *
+ * - Fires a _Thread Delete_ gateway event.
+ *
+ * Otherwise:
+ * - Requires the `MANAGE_CHANNELS` permission.
+ *
+ * - ⚠️ Deleting a category channel does not delete its child channels.
+ *   Instead, they will have their `parent_id` property removed, and a `Channel Update` gateway event will fire for each of them.
+ *
+ * - Fires a _Channel Delete_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#deleteclose-channel}
+ */
 export async function deleteChannel(bot: Bot, channelId: bigint, reason?: string): Promise<void> {
   return await bot.rest.runMethod<void>(
     bot.rest,

helpers/channels/deleteChannelOverwrite.ts

@@ -1,10 +0,0 @@
-import type { Bot } from "../../bot.ts";
-
-/** Delete the channel permission overwrites for a user or role in this channel. Requires `MANAGE_ROLES` permission. */
-export async function deleteChannelOverwrite(bot: Bot, channelId: bigint, overwriteId: bigint): Promise<void> {
-  return await bot.rest.runMethod<void>(
-    bot.rest,
-    "DELETE",
-    bot.constants.routes.CHANNEL_OVERWRITE(channelId, overwriteId),
-  );
-}

helpers/channels/deleteChannelPermissionOverride.ts

@@ -0,0 +1,23 @@
+import type { Bot } from "../../bot.ts";
+
+/**
+ * Deletes a permission override for a user or role in a channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to delete the permission override of.
+ * @param overwriteId - The ID of the permission override to delete.
+ *
+ * @remarks
+ * Requires the `MANAGE_ROLES` permission.
+ *
+ * Fires a _Channel Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#delete-channel-permission}
+ */
+export async function deleteChannelPermissionOverride(bot: Bot, channelId: bigint, overwriteId: bigint): Promise<void> {
+  return await bot.rest.runMethod<void>(
+    bot.rest,
+    "DELETE",
+    bot.constants.routes.CHANNEL_OVERWRITE(channelId, overwriteId),
+  );
+}

helpers/channels/deleteStageInstance.ts

@@ -1,6 +0,0 @@
-import type { Bot } from "../../bot.ts";
-
-/** Deletes the Stage instance. Requires the user to be a moderator of the Stage channel. */
-export async function deleteStageInstance(bot: Bot, channelId: bigint): Promise<void> {
-  return await bot.rest.runMethod<void>(bot.rest, "DELETE", bot.constants.routes.STAGE_INSTANCE(channelId));
-}

helpers/channels/editChannel.ts

@@ -2,9 +2,38 @@ import type { Bot } from "../../bot.ts";
 import { Channel } from "../../transformers/channel.ts";
 import { DiscordChannel } from "../../types/discord.ts";
 import { ChannelTypes, VideoQualityModes } from "../../types/shared.ts";
-import { OverwriteReadable } from "./editChannelOverwrite.ts";
+import { OverwriteReadable } from "./editChannelPermissionOverrides.ts";
 
-/** Update a channel's settings. Requires the `MANAGE_CHANNELS` permission for the guild. */
+/**
+ * Edits a channel's settings.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to edit.
+ * @param options - The parameters for the edit of the channel.
+ * @returns An instance of the edited {@link Channel}.
+ *
+ * @remarks
+ * If editing a channel of type {@link ChannelTypes.GroupDm}:
+ * - Fires a _Channel Update_ gateway event.
+ *
+ * If editing a thread channel:
+ * - Requires the `MANAGE_THREADS` permission __unless__ if setting the `archived` property to `false` when the `locked` property is also `false`, in which case only the `SEND_MESSAGES` permission is required.
+ *
+ * - Fires a _Thread Update_ gateway event.
+ *
+ * If editing a guild channel:
+ * - Requires the `MANAGE_CHANNELS` permission.
+ *
+ * - If modifying permission overrides:
+ *   - Requires the `MANAGE_ROLES` permission.
+ *
+ *   - Only permissions the bot user has in the guild or parent channel can be allowed/denied __unless__ the bot user has a `MANAGE_ROLES` permission override in the channel.
+ *
+ * - If modifying a channel of type {@link ChannelTypes.GuildCategory}:
+ *     - Fires a _Channel Update_ gateway event for each child channel impacted in this change.
+ * - Otherwise:
+ *     - Fires a _Channel Update_ gateway event.
+ */
 export async function editChannel(
   bot: Bot,
   channelId: bigint,

helpers/channels/editChannelPermissionOverrides.ts

@@ -1,8 +1,23 @@
 import type { Bot } from "../../bot.ts";
 import { OverwriteTypes, PermissionStrings } from "../../types/shared.ts";
 
-/** Edit the channel permission overwrites for a user or role in this channel. Requires `MANAGE_ROLES` permission. */
-export async function editChannelOverwrite(
+/**
+ * Edits the permission overrides for a user or role in a channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to edit the permission overrides of.
+ * @param overwrite - The permission override.
+ *
+ * @remarks
+ * Requires the `MANAGE_ROLES` permission.
+ *
+ * Only permissions the bot user has in the guild or parent channel can be allowed/denied __unless__ the bot user has a `MANAGE_ROLES` permission override in the channel.
+ *
+ * Fires a _Channel Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#edit-channel-permissions}
+ */
+export async function editChannelPermissionOverrides(
   bot: Bot,
   channelId: bigint,
   overwrite: OverwriteReadable,

helpers/channels/editChannelPositions.ts

@@ -1,7 +1,22 @@
 import type { Bot } from "../../bot.ts";
 
-/** Modify the positions of channels on the guild. Requires MANAGE_CHANNELS permission. Only channels to be modified are required. */
-export async function swapChannels(
+export const swapChannels = editChannelPositions;
+
+/**
+ * Edits the positions of a set of channels in a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild in which to edit the positions of the channels.
+ * @param channelPositions - A set of objects defining the updated positions of the channels.
+ *
+ * @remarks
+ * Requires the `MANAGE_CHANNELS` permission.
+ *
+ * Fires a _Channel Update_ gateway event for every channel impacted in this change.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#modify-guild-channel-positions}
+ */
+export async function editChannelPositions(
   bot: Bot,
   guildId: bigint,
   channelPositions: ModifyGuildChannelPositions[],

helpers/channels/followChannel.ts

@@ -1,16 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { DiscordFollowedChannel } from "../../types/discord.ts";
-
-/** Follow a News Channel to send messages to a target channel. Requires the `MANAGE_WEBHOOKS` permission in the target channel. Returns the webhook id. */
-export async function followChannel(bot: Bot, sourceChannelId: bigint, targetChannelId: bigint): Promise<bigint> {
-  const result = await bot.rest.runMethod<DiscordFollowedChannel>(
-    bot.rest,
-    "POST",
-    bot.constants.routes.CHANNEL_FOLLOW(sourceChannelId),
-    {
-      webhook_channel_id: targetChannelId,
-    },
-  );
-
-  return bot.transformers.snowflake(result.webhook_id);
-}

helpers/channels/forums/createForumThread.ts

@@ -4,8 +4,25 @@ import { Embed } from "../../../transformers/embed.ts";
 import { DiscordChannel } from "../../../types/discord.ts";
 import { AllowedMentions, FileContent, MessageComponents } from "../../../types/mod.ts";
 
-/** Creates a new public thread from an existing message. Returns a thread channel. */
-export async function createForumPost(
+/**
+ * Creates a new thread in a forum channel, and sends a message within the created thread.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the forum channel to create the thread within.
+ * @param options - The parameters for the creation of the thread.
+ * @returns An instance of {@link Channel} with a nested {@link Message} object.
+ *
+ * @remarks
+ * Requires the `CREATE_MESSAGES` permission.
+ *
+ * Fires a _Thread Create_ gateway event.
+ * Fires a _Message Create_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#start-thread-in-forum-channel}
+ *
+ * @experimental
+ */
+export async function createForumThread(
   bot: Bot,
   channelId: bigint,
   options: CreateForumPostWithMessage,

helpers/channels/forums/mod.ts

@@ -1 +1 @@
-export * from "./createForumPost.ts";
+export * from "./createForumThread.ts";

helpers/channels/getChannel.ts

@@ -2,7 +2,18 @@ import type { Bot } from "../../bot.ts";
 import { Channel } from "../../transformers/channel.ts";
 import { DiscordChannel } from "../../types/discord.ts";
 
-/** Fetches a single channel object from the api. */
+/**
+ * Gets a channel by its ID.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to get.
+ * @returns An instance of {@link Channel}.
+ *
+ * @remarks
+ * If the channel is a thread, a {@link ThreadMember} object is included in the result.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#get-channel}
+ */
 export async function getChannel(bot: Bot, channelId: bigint): Promise<Channel> {
   const result = await bot.rest.runMethod<DiscordChannel>(
     bot.rest,

helpers/channels/getChannelInvites.ts

@@ -2,9 +2,22 @@ import type { Bot } from "../../bot.ts";
 import { DiscordInviteMetadata } from "../../types/discord.ts";
 import { TargetTypes } from "../../types/shared.ts";
 import { Collection } from "../../util/collection.ts";
-import { InviteMetadata } from "./getInvite.ts";
+import { InviteMetadata } from "../guilds/invites/mod.ts";
 
-/** Gets the invites for this channel. Requires MANAGE_CHANNEL */
+/**
+ * Gets the list of invites for a channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to get the invites of.
+ * @returns A collection of {@link InviteMetadata} objects assorted by invite code.
+ *
+ * @remarks
+ * Requires the `MANAGE_CHANNELS` permission.
+ *
+ * Only usable for guild channels.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#get-channel-invites}
+ */
 export async function getChannelInvites(bot: Bot, channelId: bigint): Promise<Collection<string, InviteMetadata>> {
   const results = await bot.rest.runMethod<DiscordInviteMetadata[]>(
     bot.rest,

helpers/channels/getChannelWebhooks.ts

@@ -3,7 +3,18 @@ import { Webhook } from "../../transformers/webhook.ts";
 import { DiscordWebhook } from "../../types/discord.ts";
 import { Collection } from "../../util/collection.ts";
 
-/** Gets the webhooks for this channel. Requires MANAGE_WEBHOOKS */
+/**
+ * Gets a list of webhooks for a channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel which to get the webhooks of.
+ * @returns A collection of {@link Webhook} objects assorted by webhook ID.
+ *
+ * @remarks
+ * Requires the `MANAGE_WEBHOOKS` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/webhook#get-channel-webhooks}
+ */
 export async function getChannelWebhooks(bot: Bot, channelId: bigint): Promise<Collection<bigint, Webhook>> {
   const results = await bot.rest.runMethod<DiscordWebhook[]>(
     bot.rest,

helpers/channels/getChannels.ts

@@ -3,7 +3,18 @@ import { Channel } from "../../transformers/channel.ts";
 import { DiscordChannel } from "../../types/discord.ts";
 import { Collection } from "../../util/collection.ts";
 
-/** Returns a list of guild channel objects. */
+/**
+ * Gets the list of channels for a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the channels of.
+ * @returns A collection of {@link Channel} objects assorted by channel ID.
+ *
+ * @remarks
+ * Excludes threads.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild-channels}
+ */
 export async function getChannels(bot: Bot, guildId: bigint): Promise<Collection<bigint, Channel>> {
   const results = await bot.rest.runMethod<DiscordChannel[]>(
     bot.rest,

helpers/channels/getPins.ts

@@ -1,20 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { Message } from "../../transformers/message.ts";
-import { DiscordMessage } from "../../types/discord.ts";
-import { Collection } from "../../util/collection.ts";
-
-/** Get pinned messages in this channel. */
-export async function getPins(bot: Bot, channelId: bigint): Promise<Collection<bigint, Message>> {
-  const results = await bot.rest.runMethod<DiscordMessage[]>(
-    bot.rest,
-    "GET",
-    bot.constants.routes.CHANNEL_PINS(channelId),
-  );
-
-  return new Collection(
-    results.map((result) => {
-      const message = bot.transformers.message(bot, result);
-      return [message.id, message];
-    }),
-  );
-}

helpers/channels/getStageInstance.ts

@@ -1,14 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { StageInstance } from "../../transformers/stageInstance.ts";
-import { DiscordStageInstance } from "../../types/discord.ts";
-
-/** Gets the stage instance associated with the Stage channel, if it exists. */
-export async function getStageInstance(bot: Bot, channelId: bigint): Promise<StageInstance> {
-  const result = await bot.rest.runMethod<DiscordStageInstance>(
-    bot.rest,
-    "GET",
-    bot.constants.routes.STAGE_INSTANCE(channelId),
-  );
-
-  return bot.transformers.stageInstance(bot, result);
-}

helpers/channels/mod.ts

@@ -1,20 +1,16 @@
-export * from "./threads/mod.ts";
+export * from "./announcements/mod.ts";
 export * from "./forums/mod.ts";
+export * from "./stages/mod.ts";
+export * from "./threads/mod.ts";
 
 export * from "./createChannel.ts";
-export * from "./createStageInstance.ts";
 export * from "./deleteChannel.ts";
-export * from "./deleteChannelOverwrite.ts";
-export * from "./deleteStageInstance.ts";
+export * from "./deleteChannelPermissionOverride.ts";
 export * from "./editChannel.ts";
-export * from "./editChannelOverwrite.ts";
-export * from "./followChannel.ts";
+export * from "./editChannelPermissionOverrides.ts";
 export * from "./getChannel.ts";
+export * from "./getChannelInvites.ts";
 export * from "./getChannels.ts";
 export * from "./getChannelWebhooks.ts";
-export * from "./getPins.ts";
-export * from "./getStageInstance.ts";
-export * from "./startTyping.ts";
-export * from "./swapChannels.ts";
-export * from "./updateStageInstance.ts";
-export * from "./updateVoiceState.ts";
+export * from "./triggerTypingIndicator.ts";
+export * from "./editChannelPositions.ts";

helpers/channels/stages/createStageInstance.ts

@@ -0,0 +1,39 @@
+import type { Bot } from "../../../bot.ts";
+import { StageInstance } from "../../../transformers/stageInstance.ts";
+import { DiscordStageInstance } from "../../../types/discord.ts";
+
+/**
+ * Creates a stage instance associated with a stage channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param options - The parameters for the creation of the stage instance.
+ * @returns An instance of the created {@link StageInstance}.
+ *
+ * @remarks
+ * Requires the user to be a moderator of the stage channel.
+ *
+ * Fires a _Stage Instance Create_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/stage-instance#create-stage-instance}
+ */
+export async function createStageInstance(bot: Bot, options: CreateStageInstance): Promise<StageInstance> {
+  const result = await bot.rest.runMethod<DiscordStageInstance>(
+    bot.rest,
+    "POST",
+    bot.constants.routes.STAGE_INSTANCES(),
+    {
+      channel_id: options.channelId.toString(),
+      topic: options.topic,
+      send_start_notification: options.sendStartNotification,
+    },
+  );
+
+  return bot.transformers.stageInstance(bot, result);
+}
+
+export interface CreateStageInstance {
+  channelId: bigint;
+  topic: string;
+  /** Notify @everyone that the stage instance has started. Requires the MENTION_EVERYONE permission. */
+  sendStartNotification?: boolean;
+}

helpers/channels/stages/deleteStageInstance.ts

@@ -0,0 +1,18 @@
+import type { Bot } from "../../../bot.ts";
+
+/**
+ * Deletes the stage instance associated with a stage channel, if one exists.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the stage channel the stage instance is associated with.
+ *
+ * @remarks
+ * Requires the user to be a moderator of the stage channel.
+ *
+ * Fires a _Stage Instance Delete_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/stage-instance#delete-stage-instance}
+ */
+export async function deleteStageInstance(bot: Bot, channelId: bigint): Promise<void> {
+  return await bot.rest.runMethod<void>(bot.rest, "DELETE", bot.constants.routes.STAGE_INSTANCE(channelId));
+}

helpers/channels/stages/editStageInstance.ts

@@ -0,0 +1,35 @@
+import type { Bot } from "../../../bot.ts";
+import { StageInstance } from "../../../transformers/stageInstance.ts";
+import { DiscordStageInstance } from "../../../types/discord.ts";
+import { AtLeastOne } from "../../../types/shared.ts";
+
+/**
+ * Edits a stage instance.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the stage channel the stage instance is associated with.
+ * @returns An instance of the updated {@link StageInstance}.
+ *
+ * @remarks
+ * Requires the user to be a moderator of the stage channel.
+ *
+ * Fires a _Stage Instance Update_ event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/stage-instance#modify-stage-instance}
+ */
+export async function editStageInstance(
+  bot: Bot,
+  channelId: bigint,
+  data: AtLeastOne<Pick<DiscordStageInstance, "topic">>,
+): Promise<StageInstance> {
+  const result = await bot.rest.runMethod<DiscordStageInstance>(
+    bot.rest,
+    "PATCH",
+    bot.constants.routes.STAGE_INSTANCE(channelId),
+    {
+      topic: data.topic,
+    },
+  );
+
+  return bot.transformers.stageInstance(bot, result);
+}

helpers/channels/stages/getStageInstance.ts

@@ -0,0 +1,22 @@
+import type { Bot } from "../../../bot.ts";
+import { StageInstance } from "../../../transformers/stageInstance.ts";
+import { DiscordStageInstance } from "../../../types/discord.ts";
+
+/**
+ * Gets the stage instance associated with a stage channel, if one exists.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the stage channel the stage instance is associated with.
+ * @returns An instance of {@link StageInstance}.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/stage-instance#get-stage-instance}
+ */
+export async function getStageInstance(bot: Bot, channelId: bigint): Promise<StageInstance> {
+  const result = await bot.rest.runMethod<DiscordStageInstance>(
+    bot.rest,
+    "GET",
+    bot.constants.routes.STAGE_INSTANCE(channelId),
+  );
+
+  return bot.transformers.stageInstance(bot, result);
+}

helpers/channels/stages/mod.ts

@@ -0,0 +1,4 @@
+export * from "./createStageInstance.ts";
+export * from "./deleteStageInstance.ts";
+export * from "./editStageInstance.ts";
+export * from "./getStageInstance.ts";

helpers/channels/startTyping.ts

@@ -1,10 +0,0 @@
-import type { Bot } from "../../bot.ts";
-
-/**
- * Trigger a typing indicator for the specified channel. Generally bots should **NOT** implement this route.
- * However, if a bot is responding to a command and expects the computation to take a few seconds,
- * this endpoint may be called to let the user know that the bot is processing their message.
- */
-export async function startTyping(bot: Bot, channelId: bigint): Promise<void> {
-  return await bot.rest.runMethod<void>(bot.rest, "POST", bot.constants.routes.CHANNEL_TYPING(channelId));
-}

helpers/channels/threads/addThreadMember.ts

@@ -0,0 +1,20 @@
+import type { Bot } from "../../../bot.ts";
+
+/**
+ * Adds a member to a thread.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the thread to add the member to.
+ * @param userId - The user ID of the member to add to the thread.
+ *
+ * @remarks
+ * Requires the ability to send messages in the thread.
+ * Requires the thread not be archived.
+ *
+ * Fires a _Thread Members Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#add-thread-member}
+ */
+export async function addThreadMember(bot: Bot, channelId: bigint, userId: bigint): Promise<void> {
+  return await bot.rest.runMethod<void>(bot.rest, "PUT", bot.constants.routes.THREAD_USER(channelId, userId));
+}

helpers/channels/threads/addToThread.ts

@@ -1,6 +0,0 @@
-import type { Bot } from "../../../bot.ts";
-
-/** Adds a user to a thread. Requires the ability to send messages in the thread. Requires the thread is not archived. */
-export async function addToThread(bot: Bot, threadId: bigint, userId: bigint): Promise<void> {
-  return await bot.rest.runMethod<void>(bot.rest, "PUT", bot.constants.routes.THREAD_USER(threadId, userId));
-}

helpers/channels/threads/getActiveThreads.ts

@@ -3,12 +3,20 @@ import { Channel, ThreadMember } from "../../../mod.ts";
 import { DiscordListActiveThreads } from "../../../types/discord.ts";
 import { Collection } from "../../../util/collection.ts";
 
-export type ActiveThreads = {
-  threads: Collection<bigint, Channel>;
-  members: Collection<bigint, ThreadMember>;
-};
-
-/** Returns all active threads in the guild, including public and private threads. Threads are ordered by their `id`, in descending order. */
+/**
+ * Gets the list of all active threads for a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the threads of.
+ * @returns An instance of {@link ActiveThreads}.
+ *
+ * @remarks
+ * Returns both public and private threads.
+ *
+ * Threads are ordered by the `id` property in descending order.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#list-active-guild-threads}
+ */
 export async function getActiveThreads(bot: Bot, guildId: bigint): Promise<ActiveThreads> {
   const results = await bot.rest.runMethod<DiscordListActiveThreads>(
     bot.rest,
@@ -31,3 +39,8 @@ export async function getActiveThreads(bot: Bot, guildId: bigint): Promise<Activ
     ),
   };
 }
+
+export type ActiveThreads = {
+  threads: Collection<bigint, Channel>;
+  members: Collection<bigint, ThreadMember>;
+};

helpers/channels/threads/getPrivateArchivedThreads.ts

@@ -0,0 +1,50 @@
+import type { Bot } from "../../../bot.ts";
+import { DiscordListArchivedThreads } from "../../../types/discord.ts";
+import { Collection } from "../../../util/collection.ts";
+import { ArchivedThreads, ListArchivedThreads } from "./getPublicArchivedThreads.ts";
+
+/**
+ * Gets the list of private archived threads for a channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to get the archived threads for.
+ * @param options - The parameters for the fetching of threads.
+ * @returns An instance of {@link ArchivedThreads}.
+ *
+ * @remarks
+ * Requires the `READ_MESSAGE_HISTORY` permission.
+ * Requires the `MANAGE_THREADS` permission.
+ *
+ * Returns threads of type {@link ChannelTypes.GuildPrivateThread}.
+ *
+ * Threads are ordered by the `archive_timestamp` property included in the metadata of the object in descending order.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#list-private-archived-threads}
+ */
+export async function getPrivateArchivedThreads(
+  bot: Bot,
+  channelId: bigint,
+  options?: ListArchivedThreads,
+): Promise<ArchivedThreads> {
+  const results = await bot.rest.runMethod<DiscordListArchivedThreads>(
+    bot.rest,
+    "GET",
+    bot.constants.routes.THREAD_ARCHIVED_PRIVATE(channelId, options),
+  );
+
+  return {
+    threads: new Collection(
+      results.threads.map((result) => {
+        const thread = bot.transformers.channel(bot, { channel: result });
+        return [thread.id, thread];
+      }),
+    ),
+    members: new Collection(
+      results.members.map((result) => {
+        const member = bot.transformers.threadMember(bot, result);
+        return [member.id!, member];
+      }),
+    ),
+    hasMore: results.has_more,
+  };
+}

helpers/channels/threads/getPrivateJoinedArchivedThreads.ts

@@ -0,0 +1,49 @@
+import type { Bot } from "../../../bot.ts";
+import { DiscordListArchivedThreads } from "../../../types/discord.ts";
+import { Collection } from "../../../util/collection.ts";
+import { ArchivedThreads, ListArchivedThreads } from "./getPublicArchivedThreads.ts";
+
+/**
+ * Gets the list of private archived threads the bot is a member of for a channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to get the archived threads for.
+ * @param options - The parameters for the fetching of threads.
+ * @returns An instance of {@link ArchivedThreads}.
+ *
+ * @remarks
+ * Requires the `READ_MESSAGE_HISTORY` permission.
+ *
+ * Returns threads of type {@link ChannelTypes.GuildPrivateThread}.
+ *
+ * Threads are ordered by the `id` property in descending order.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#list-joined-private-archived-threads}
+ */
+export async function getPrivateJoinedArchivedThreads(
+  bot: Bot,
+  channelId: bigint,
+  options?: ListArchivedThreads,
+): Promise<ArchivedThreads> {
+  const results = await bot.rest.runMethod<DiscordListArchivedThreads>(
+    bot.rest,
+    "GET",
+    bot.constants.routes.THREAD_ARCHIVED_PRIVATE_JOINED(channelId, options),
+  );
+
+  return {
+    threads: new Collection(
+      results.threads.map((result) => {
+        const thread = bot.transformers.channel(bot, { channel: result });
+        return [thread.id, thread];
+      }),
+    ),
+    members: new Collection(
+      results.members.map((result) => {
+        const member = bot.transformers.threadMember(bot, result);
+        return [member.id!, member];
+      }),
+    ),
+    hasMore: results.has_more,
+  };
+}

helpers/channels/threads/getPublicArchivedThreads.ts

@@ -3,28 +3,33 @@ import { DiscordListArchivedThreads } from "../../../types/discord.ts";
 import { Collection } from "../../../util/collection.ts";
 import { ActiveThreads } from "./getActiveThreads.ts";
 
-export type ArchivedThreads = ActiveThreads & {
-  hasMore: boolean;
-};
-
-/** Get the archived threads for this channel, defaults to public */
-export async function getArchivedThreads(
+/**
+ * Gets the list of public archived threads for a channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to get the archived threads for.
+ * @param options - The parameters for the fetching of threads.
+ * @returns An instance of {@link ArchivedThreads}.
+ *
+ * @remarks
+ * Requires the `READ_MESSAGE_HISTORY` permission.
+ *
+ * If called on a channel of type {@link ChannelTypes.GuildText}, returns threads of type {@link ChannelTypes.GuildPublicThread}.
+ * If called on a channel of type {@link ChannelTypes.GuildNews}, returns threads of type {@link ChannelTypes.GuildNewsThread}.
+ *
+ * Threads are ordered by the `archive_timestamp` property included in the metadata of the object in descending order.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#list-public-archived-threads}
+ */
+export async function getPublicArchivedThreads(
   bot: Bot,
   channelId: bigint,
-  options?: ListArchivedThreads & {
-    type?: "public" | "private" | "privateJoinedThreads";
-  },
+  options?: ListArchivedThreads,
 ): Promise<ArchivedThreads> {
-  const url = options?.type === "privateJoinedThreads"
-    ? bot.constants.routes.THREAD_ARCHIVED_PRIVATE_JOINED(channelId, options)
-    : options?.type === "private"
-    ? bot.constants.routes.THREAD_ARCHIVED_PRIVATE(channelId, options)
-    : bot.constants.routes.THREAD_ARCHIVED_PUBLIC(channelId, options);
-
   const results = await bot.rest.runMethod<DiscordListArchivedThreads>(
     bot.rest,
     "GET",
-    url,
+    bot.constants.routes.THREAD_ARCHIVED_PUBLIC(channelId, options),
   );
 
   return {
@@ -51,3 +56,7 @@ export interface ListArchivedThreads {
   /** Optional maximum number of threads to return */
   limit?: number;
 }
+
+export type ArchivedThreads = ActiveThreads & {
+  hasMore: boolean;
+};

helpers/channels/threads/getThreadMember.ts

@@ -2,12 +2,21 @@ import type { Bot } from "../../../bot.ts";
 import { ThreadMember } from "../../../transformers/threadMember.ts";
 import { DiscordThreadMember } from "../../../types/discord.ts";
 
-/** Returns thread members objects that are members of the thread. */
-export async function getThreadMember(bot: Bot, threadId: bigint, userId: bigint): Promise<ThreadMember> {
+/**
+ * Gets a thread member by their user ID.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the thread to get the thread member of.
+ * @param userId - The user ID of the thread member to get.
+ * @returns An instance of {@link ThreadMember}.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#get-thread-member}
+ */
+export async function getThreadMember(bot: Bot, channelId: bigint, userId: bigint): Promise<ThreadMember> {
   const result = await bot.rest.runMethod<DiscordThreadMember>(
     bot.rest,
     "GET",
-    bot.constants.routes.THREAD_USER(threadId, userId),
+    bot.constants.routes.THREAD_USER(channelId, userId),
   );
 
   return bot.transformers.threadMember(bot, result);

helpers/channels/threads/getThreadMembers.ts

@@ -3,12 +3,23 @@ import { ThreadMember } from "../../../transformers/threadMember.ts";
 import { DiscordThreadMember } from "../../../types/discord.ts";
 import { Collection } from "../../../util/collection.ts";
 
-/** Returns thread members objects that are members of the thread. */
-export async function getThreadMembers(bot: Bot, threadId: bigint): Promise<Collection<bigint, ThreadMember>> {
+/**
+ * Gets the list of thread members for a thread.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the thread to get the thread members of.
+ * @returns A collection of {@link ThreadMember} assorted by user ID.
+ *
+ * @remarks
+ * Requires the application to have the `GUILD_MEMBERS` privileged intent enabled.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#list-thread-members}
+ */
+export async function getThreadMembers(bot: Bot, channelId: bigint): Promise<Collection<bigint, ThreadMember>> {
   const results = await bot.rest.runMethod<DiscordThreadMember[]>(
     bot.rest,
     "GET",
-    bot.constants.routes.THREAD_MEMBERS(threadId),
+    bot.constants.routes.THREAD_MEMBERS(channelId),
   );
 
   return new Collection(

helpers/channels/threads/joinThread.ts

@@ -1,6 +1,18 @@
 import type { Bot } from "../../../bot.ts";
 
-/** Adds the bot to the thread. Cannot join an archived thread. */
-export async function joinThread(bot: Bot, threadId: bigint): Promise<void> {
-  return await bot.rest.runMethod<void>(bot.rest, "PUT", bot.constants.routes.THREAD_ME(threadId));
+/**
+ * Adds the bot user to a thread.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the thread to add the bot user to.
+ *
+ * @remarks
+ * Requires the thread not be archived.
+ *
+ * Fires a _Thread Members Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#join-thread}
+ */
+export async function joinThread(bot: Bot, channelId: bigint): Promise<void> {
+  return await bot.rest.runMethod<void>(bot.rest, "PUT", bot.constants.routes.THREAD_ME(channelId));
 }

helpers/channels/threads/leaveThread.ts

@@ -1,6 +1,18 @@
 import type { Bot } from "../../../bot.ts";
 
-/** Removes the bot from a thread. Requires the thread is not archived. */
-export async function leaveThread(bot: Bot, threadId: bigint): Promise<void> {
-  return await bot.rest.runMethod<void>(bot.rest, "DELETE", bot.constants.routes.THREAD_ME(threadId));
+/**
+ * Removes the bot user from a thread.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the thread to remove the bot user from.
+ *
+ * @remarks
+ * Requires the thread not be archived.
+ *
+ * Fires a _Thread Members Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#leave-thread}
+ */
+export async function leaveThread(bot: Bot, channelId: bigint): Promise<void> {
+  return await bot.rest.runMethod<void>(bot.rest, "DELETE", bot.constants.routes.THREAD_ME(channelId));
 }

helpers/channels/threads/mod.ts

@@ -1,6 +1,8 @@
-export * from "./addToThread.ts";
+export * from "./addThreadMember.ts";
 export * from "./getActiveThreads.ts";
-export * from "./getArchivedThreads.ts";
+export * from "./getPrivateArchivedThreads.ts";
+export * from "./getPrivateJoinedArchivedThreads.ts";
+export * from "./getPublicArchivedThreads.ts";
 export * from "./getThreadMember.ts";
 export * from "./getThreadMembers.ts";
 export * from "./joinThread.ts";

helpers/channels/threads/removeThreadMember.ts

@@ -1,10 +1,26 @@
 import type { Bot } from "../../../bot.ts";
 
-/** Removes a user from a thread. Requires the MANAGE_THREADS permission or that you are the creator of the thread. Also requires the thread is not archived. */
-export async function removeThreadMember(bot: Bot, threadId: bigint, userId: bigint): Promise<void> {
+/**
+ * Removes a member from a thread.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the thread to remove the thread member of.
+ * @param userId - The user ID of the thread member to remove.
+ *
+ * @remarks
+ * If the thread is of type {@link ChannelTypes.GuildPrivateThread}, requires to be the creator of the thread.
+ * Otherwise, requires the `MANAGE_THREADS` permission.
+ *
+ * Requires the thread not be archived.
+ *
+ * Fires a _Thread Members Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#remove-thread-member}
+ */
+export async function removeThreadMember(bot: Bot, channelId: bigint, userId: bigint): Promise<void> {
   return await bot.rest.runMethod<void>(
     bot.rest,
     "DELETE",
-    bot.constants.routes.THREAD_USER(threadId, userId),
+    bot.constants.routes.THREAD_USER(channelId, userId),
   );
 }

helpers/channels/threads/startThreadWithMessage.ts

@@ -2,7 +2,26 @@ import type { Bot } from "../../../bot.ts";
 import { Channel } from "../../../transformers/channel.ts";
 import { DiscordChannel } from "../../../types/discord.ts";
 
-/** Creates a new public thread from an existing message. Returns a thread channel. */
+/**
+ * Creates a thread, using an existing message as its point of origin.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel in which to create the thread.
+ * @param messageId - The ID of the message to use as the thread's point of origin.
+ * @param options - The parameters to use for the creation of the thread.
+ * @returns An instance of the created {@link Channel | Thread}.
+ *
+ * @remarks
+ * If called on a channel of type {@link ChannelTypes.GuildText}, creates a {@link ChannelTypes.GuildPublicThread}.
+ * If called on a channel of type {@link ChannelTypes.GuildNews}, creates a {@link ChannelTypes.GuildNewsThread}.
+ * Does not work on channels of type {@link ChannelTypes.GuildForum}.
+ *
+ * The ID of the created thread will be the same as the ID of the source message.
+ *
+ * Fires a _Thread Create_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#start-thread-from-message}
+ */
 export async function startThreadWithMessage(
   bot: Bot,
   channelId: bigint,

helpers/channels/threads/startThreadWithoutMessage.ts

@@ -3,7 +3,21 @@ import { Channel } from "../../../transformers/channel.ts";
 import { DiscordChannel } from "../../../types/discord.ts";
 import { ChannelTypes } from "../../../types/shared.ts";
 
-/** Creates a new private thread. Returns a thread channel. */
+/**
+ * Creates a thread without using a message as the thread's point of origin.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel in which to create the thread.
+ * @param options - The parameters to use for the creation of the thread.
+ * @returns An instance of the created {@link Channel | Thread}.
+ *
+ * @remarks
+ * Creating a private thread requires the server to be boosted.
+ *
+ * Fires a _Thread Create_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#start-thread-without-message}
+ */
 export async function startThreadWithoutMessage(
   bot: Bot,
   channelId: bigint,

helpers/channels/triggerTypingIndicator.ts

@@ -0,0 +1,20 @@
+import type { Bot } from "../../bot.ts";
+
+export const startTyping = triggerTypingIndicator;
+
+/**
+ * Triggers a typing indicator for the bot user.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel in which to trigger the typing indicator.
+ *
+ * @remarks
+ * Generally, bots should _not_ use this route.
+ *
+ * Fires a _Typing Start_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#trigger-typing-indicator}
+ */
+export async function triggerTypingIndicator(bot: Bot, channelId: bigint): Promise<void> {
+  return await bot.rest.runMethod<void>(bot.rest, "POST", bot.constants.routes.CHANNEL_TYPING(channelId));
+}

helpers/channels/updateStageInstance.ts

@@ -1,22 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { StageInstance } from "../../transformers/stageInstance.ts";
-import { DiscordStageInstance } from "../../types/discord.ts";
-import { AtLeastOne } from "../../types/shared.ts";
-
-/** Updates fields of an existing Stage instance. Requires the user to be a moderator of the Stage channel. */
-export async function updateStageInstance(
-  bot: Bot,
-  channelId: bigint,
-  data: AtLeastOne<Pick<DiscordStageInstance, "topic">>,
-): Promise<StageInstance> {
-  const result = await bot.rest.runMethod<DiscordStageInstance>(
-    bot.rest,
-    "PATCH",
-    bot.constants.routes.STAGE_INSTANCE(channelId),
-    {
-      topic: data.topic,
-    },
-  );
-
-  return bot.transformers.stageInstance(bot, result);
-}

helpers/channels/updateVoiceState.ts

@@ -1,65 +0,0 @@
-import type { Bot } from "../../bot.ts";
-
-/**
- * Updates the bot's voice state
- * Caveats:
- *  - `channel_id` must currently point to a stage channel.
- *  - Bot must already have joined `channel_id`.
- *  - You must have the `MUTE_MEMBERS` permission. But can always suppress yourself.
- *  - You must have the `REQUEST_TO_SPEAK` permission to request to speak. You can always clear your own request to speak.
- *  - You are able to set `request_to_speak_timestamp` to any present or future time.
- *  - When suppressed, the user will have their `request_to_speak_timestamp` removed.
- */
-export async function updateBotVoiceState(bot: Bot, guildId: bigint, options: UpdateSelfVoiceState): Promise<void> {
-  return await bot.rest.runMethod<void>(bot.rest, "PATCH", bot.constants.routes.UPDATE_VOICE_STATE(guildId), {
-    channel_id: options.channelId,
-    suppress: options.suppress,
-    request_to_speak_timestamp: options.requestToSpeakTimestamp
-      ? new Date(options.requestToSpeakTimestamp).toISOString()
-      : options.requestToSpeakTimestamp,
-  });
-}
-
-/**
- * Updates the a user's voice state
- * Caveats:
- *  - `channel_id` must currently point to a stage channel.
- *  - User must already have joined `channel_id`.
- *  - You must have the `MUTE_MEMBERS` permission. But can always suppress yourself.
- *  - When unsuppressed, non-bot users will have their `request_to_speak_timestamp` set to the current time. Bot users will not.
- *  - You must have the `REQUEST_TO_SPEAK` permission to request to speak. You can always clear your own request to speak.
- *  - You are able to set `request_to_speak_timestamp` to any present or future time.
- *  - When suppressed, the user will have their `request_to_speak_timestamp` removed.
- */
-export async function updateUserVoiceState(bot: Bot, guildId: bigint, options: UpdateOthersVoiceState): Promise<void> {
-  return await bot.rest.runMethod<void>(
-    bot.rest,
-    "PATCH",
-    bot.constants.routes.UPDATE_VOICE_STATE(guildId, options.userId),
-    {
-      channel_id: options.channelId,
-      suppress: options.suppress,
-      user_id: options.userId,
-    },
-  );
-}
-
-/** https://discord.com/developers/docs/resources/guild#update-current-user-voice-state */
-export interface UpdateSelfVoiceState {
-  /** The id of the channel the user is currently in */
-  channelId: bigint;
-  /** Toggles the user's suppress state */
-  suppress?: boolean;
-  /** Sets the user's request to speak */
-  requestToSpeakTimestamp?: number | null;
-}
-
-/** https://discord.com/developers/docs/resources/guild#update-user-voice-state */
-export interface UpdateOthersVoiceState {
-  /** The id of the channel the user is currently in */
-  channelId: bigint;
-  /** Toggles the user's suppress state */
-  suppress?: boolean;
-  /** The user id to target */
-  userId: bigint;
-}

helpers/discovery/addDiscoverySubcategory.ts

@@ -1,6 +1,18 @@
 import type { Bot } from "../../bot.ts";
 
-/** Add a discovery subcategory to the guild. Requires the `MANAGE_GUILD` permission. */
+/**
+ * Adds a discovery subcategory to a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to add the subcategory to.
+ * @param categoryId - The ID of the category to add to the guild.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * @privateRemarks
+ * This endpoint is not formally documented.
+ */
 export async function addDiscoverySubcategory(bot: Bot, guildId: bigint, categoryId: number): Promise<void> {
   return await bot.rest.runMethod<void>(
     bot.rest,

helpers/discovery/deleteDiscoverySubcategory.ts

@@ -1,6 +1,18 @@
 import type { Bot } from "../../bot.ts";
 
-/** Deletes a discovery subcategory from the guild. Requires the MANAGE_GUILD permission. Returns a 204 No Content on success. */
+/**
+ * Deletes a discovery subcategory from a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to delete the subcategory from.
+ * @param categoryId - The ID of the category to delete from the guild.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * @privateRemarks
+ * This endpoint is not formally documented.
+ */
 export async function deleteDiscoverySubcategory(bot: Bot, guildId: bigint, categoryId: number): Promise<void> {
   return await bot.rest.runMethod<void>(
     bot.rest,

helpers/discovery/editDiscovery.ts

@@ -2,20 +2,32 @@ import type { Bot } from "../../bot.ts";
 import { DiscordDiscoveryMetadata } from "../../types/discord.ts";
 import { DiscoveryMetadata } from "./getDiscovery.ts";
 
-/** Modify the discovery metadata for the guild. Requires the MANAGE_GUILD permission. Returns the updated discovery metadata object on success. */
+/**
+ * Edits the discovery settings of a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to edit the discovery settings of.
+ * @param options - The parameters for the edit of the discovery settings.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * @privateRemarks
+ * This endpoint is not formally documented.
+ */
 export async function editDiscovery(
   bot: Bot,
   guildId: bigint,
-  data: ModifyGuildDiscoveryMetadata,
+  options: ModifyGuildDiscoveryMetadata,
 ): Promise<DiscoveryMetadata> {
   const result = await bot.rest.runMethod<DiscordDiscoveryMetadata>(
     bot.rest,
     "PATCH",
     bot.constants.routes.DISCOVERY_METADATA(guildId),
     {
-      primary_category_id: data.primaryCategoryId,
-      keywords: data.keywords,
-      emoji_discoverability_enabled: data.emojiDiscoverabilityEnabled,
+      primary_category_id: options.primaryCategoryId,
+      keywords: options.keywords,
+      emoji_discoverability_enabled: options.emojiDiscoverabilityEnabled,
     },
   );
 

helpers/discovery/getDiscovery.ts

@@ -11,7 +11,15 @@ export type DiscoveryMetadata = {
   categoryIds: number[];
 };
 
-/** Returns the discovery metadata object for the guild. Requires the `MANAGE_GUILD` permission. */
+/**
+ * Gets the discovery settings of a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the discovery settings of.
+ *
+ * @privateRemarks
+ * This endpoint is not formally documented.
+ */
 export async function getDiscovery(bot: Bot, guildId: bigint): Promise<DiscoveryMetadata> {
   const result = await bot.rest.runMethod<DiscordDiscoveryMetadata>(
     bot.rest,

helpers/discovery/getDiscoveryCategories.ts

@@ -13,7 +13,14 @@ export type DiscoveryName = {
   localizations?: Record<string, string>;
 };
 
-/** Returns a Collection (mapped by Id of the discovery category object) of discovery category objects that can be used when editing guilds */
+/**
+ * Gets the list of available discovery categories.
+ *
+ * @param bot - The bot instance to use to make the request.
+ *
+ * @privateRemarks
+ * This endpoint is not formally documented.
+ */
 export async function getDiscoveryCategories(bot: Bot): Promise<Collection<bigint, DiscoveryCategory>> {
   const results = await bot.rest.runMethod<DiscordDiscoveryCategory[]>(
     bot.rest,

helpers/discovery/getIsValidDiscoveryTerm.ts

@@ -1,6 +1,15 @@
 import type { Bot } from "../../bot.ts";
 import { DiscordValidateDiscoverySearchTerm } from "../../types/discord.ts";
 
+/**
+ * Gets the validity of a discovery term.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param term - The term to validate.
+ *
+ * @privateRemarks
+ * This endpoint is not formally documented.
+ */
 export async function getIsValidDiscoveryTerm(bot: Bot, term: string): Promise<boolean> {
   const result = await bot.rest.runMethod<DiscordValidateDiscoverySearchTerm>(
     bot.rest,

helpers/emojis/createEmoji.ts

@@ -2,7 +2,23 @@ import type { Bot } from "../../bot.ts";
 import { Emoji } from "../../transformers/emoji.ts";
 import { DiscordEmoji } from "../../types/discord.ts";
 
-/** Create an emoji in the server */
+/**
+ * Creates an emoji in a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild in which to create the emoji.
+ * @param options - The parameters for the creation of the emoji.
+ * @returns An instance of the created {@link Emoji}.
+ *
+ * @remarks
+ * Requires the `MANAGE_EMOJIS_AND_STICKERS` permission.
+ *
+ * Emojis have a maximum file size of 256 kilobits. Attempting to upload a larger emoji will cause the route to return 400 Bad Request.
+ *
+ * Fires a _Guild Emojis Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/emoji#create-guild-emoji}
+ */
 export async function createEmoji(bot: Bot, guildId: bigint, options: CreateGuildEmoji): Promise<Emoji> {
   if (options.image && !options.image.startsWith("data:image/")) {
     options.image = await bot.utils.urlToBase64(options.image);

helpers/emojis/deleteEmoji.ts

@@ -1,6 +1,19 @@
 import type { Bot } from "../../bot.ts";
 
-/** Delete the given emoji. Requires the MANAGE_EMOJIS permission. Returns 204 No Content on success. */
+/**
+ * Deletes an emoji from a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild from which to delete the emoji.
+ * @param id - The ID of the emoji to delete.
+ *
+ * @remarks
+ * Requires the `MANAGE_EMOJIS_AND_STICKERS` permission.
+ *
+ * Fires a _Guild Emojis Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/emoji#delete-guild-emoji}
+ */
 export async function deleteEmoji(bot: Bot, guildId: bigint, id: bigint, reason?: string): Promise<void> {
   return await bot.rest.runMethod<void>(bot.rest, "DELETE", bot.constants.routes.GUILD_EMOJI(guildId, id), {
     reason,

helpers/emojis/editEmoji.ts

@@ -2,7 +2,22 @@ import type { Bot } from "../../bot.ts";
 import { Emoji } from "../../transformers/emoji.ts";
 import { DiscordEmoji } from "../../types/discord.ts";
 
-/** Modify the given emoji. Requires the MANAGE_EMOJIS permission. */
+/**
+ * Edits an emoji.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild in which to edit the emoji.
+ * @param id - The ID of the emoji to edit.
+ * @param options - The parameters for the edit of the emoji.
+ * @returns An instance of the updated {@link Emoji}.
+ *
+ * @remarks
+ * Requires the `MANAGE_EMOJIS_AND_STICKERS` permission.
+ *
+ * Fires a `Guild Emojis Update` gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/emoji#modify-guild-emoji}
+ */
 export async function editEmoji(bot: Bot, guildId: bigint, id: bigint, options: ModifyGuildEmoji): Promise<Emoji> {
   const result = await bot.rest.runMethod<DiscordEmoji>(
     bot.rest,

helpers/emojis/getEmoji.ts

@@ -3,7 +3,14 @@ import { Emoji } from "../../transformers/emoji.ts";
 import { DiscordEmoji } from "../../types/discord.ts";
 
 /**
- * Returns an emoji for the given guild and emoji Id.
+ * Gets an emoji by its ID.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild from which to get the emoji.
+ * @param emojiId - The ID of the emoji to get.
+ * @returns An instance of {@link Emoji}.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/emoji#get-guild-emoji}
  */
 export async function getEmoji(bot: Bot, guildId: bigint, emojiId: bigint): Promise<Emoji> {
   const result = await bot.rest.runMethod<DiscordEmoji>(

helpers/emojis/getEmojiUrl.ts

@@ -1,6 +1,12 @@
 import { Bot } from "../../bot.ts";
 
-/** Creates a url to the emoji from the Discord CDN. */
-export function getEmojiURL(_bot: Bot, id: bigint, animated = false): string {
-  return `https://cdn.discordapp.com/emojis/${id}.${animated ? "gif" : "png"}`;
+/**
+ * Builds a URL to an emoji in the Discord CDN.
+ *
+ * @param emojiId - The ID of the emoji to access.
+ * @param animated - Whether the emoji is animated or static.
+ * @returns The link to the resource.
+ */
+export function getEmojiURL(_bot: Bot, emojiId: bigint, animated = false): string {
+  return `https://cdn.discordapp.com/emojis/${emojiId}.${animated ? "gif" : "png"}`;
 }

helpers/emojis/getEmojis.ts

@@ -4,7 +4,13 @@ import { DiscordEmoji } from "../../types/discord.ts";
 import { Collection } from "../../util/collection.ts";
 
 /**
- * Returns a list of emojis for the given guild.
+ * Gets the list of emojis for a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild which to get the emojis of.
+ * @returns A collection of {@link Emoji} objects assorted by emoji ID.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/emoji#list-guild-emojis}
  */
 export async function getEmojis(bot: Bot, guildId: bigint): Promise<Collection<bigint, Emoji>> {
   const results = await bot.rest.runMethod<DiscordEmoji[]>(

helpers/guilds/automod/createAutomodRule.ts

@@ -8,7 +8,21 @@ import {
   DiscordAutoModerationRuleTriggerMetadataPresets,
 } from "../../../types/discord.ts";
 
-/** Get a rule currently configured for guild. */
+/**
+ * Creates an automod rule in a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to create the rule in.
+ * @param options - The parameters for the creation of the rule.
+ * @returns An instance of the created {@link AutoModerationRule}.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * Fires an _Auto Moderation Rule Create_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/auto-moderation#create-auto-moderation-rule}
+ */
 export async function createAutomodRule(
   bot: Bot,
   guildId: bigint,

helpers/guilds/automod/deleteAutomodRule.ts

@@ -1,6 +1,19 @@
 import { Bot } from "../../../bot.ts";
 
-/** Delete a rule currently configured for guild. */
+/**
+ * Deletes an automod rule.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to delete the rule from.
+ * @param ruleId - The ID of the automod rule to delete.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * Fires an _Auto Moderation Rule Delete_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/auto-moderation#delete-auto-moderation-rule}
+ */
 export async function deleteAutomodRule(bot: Bot, guildId: bigint, ruleId: bigint, reason?: string): Promise<void> {
   return await bot.rest.runMethod<void>(
     bot.rest,

helpers/guilds/automod/editAutomodRule.ts

@@ -7,16 +7,32 @@ import {
   DiscordAutoModerationRuleTriggerMetadataPresets,
 } from "../../../types/discord.ts";
 
-/** Edit a rule currently configured for guild. */
+/**
+ * Edits an automod rule.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to edit the rule in.
+ * @param ruleId - The ID of the rule to edit.
+ * @param options - The parameters for the edit of the rule.
+ * @returns An instance of the edited {@link AutoModerationRule}.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * Fires an _Auto Moderation Rule Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/auto-moderation#modify-auto-moderation-rule}
+ */
 export async function editAutomodRule(
   bot: Bot,
   guildId: bigint,
+  ruleId: bigint,
   options: Partial<EditAutoModerationRuleOptions>,
 ): Promise<AutoModerationRule> {
   const result = await bot.rest.runMethod<DiscordAutoModerationRule>(
     bot.rest,
     "PATCH",
-    bot.constants.routes.AUTOMOD_RULES(guildId),
+    bot.constants.routes.AUTOMOD_RULE(guildId, ruleId),
     {
       name: options.name,
       event_type: options.eventType,

helpers/guilds/automod/getAutomodRule.ts

@@ -2,7 +2,19 @@ import { Bot } from "../../../bot.ts";
 import { AutoModerationRule } from "../../../transformers/automodRule.ts";
 import { DiscordAutoModerationRule } from "../../../types/discord.ts";
 
-/** Get a rule currently configured for guild. */
+/**
+ * Gets an automod rule by its ID.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the rule of.
+ * @param ruleId - The ID of the rule to get.
+ * @returns An instance of {@link AutoModerationRule}.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/auto-moderation#get-auto-moderation-rule}
+ */
 export async function getAutomodRule(bot: Bot, guildId: bigint, ruleId: bigint): Promise<AutoModerationRule> {
   const result = await bot.rest.runMethod<DiscordAutoModerationRule>(
     bot.rest,

helpers/guilds/automod/getAutomodRules.ts

@@ -3,7 +3,18 @@ import { AutoModerationRule } from "../../../transformers/automodRule.ts";
 import { DiscordAutoModerationRule } from "../../../types/discord.ts";
 import { Collection } from "../../../util/collection.ts";
 
-/** Get a list of all rules currently configured for guild. */
+/**
+ * Gets the list of automod rules for a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the rules from.
+ * @returns A collection of {@link AutoModerationRule} objects assorted by rule ID.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/auto-moderation#list-auto-moderation-rules-for-guild}
+ */
 export async function getAutomodRules(bot: Bot, guildId: bigint): Promise<Collection<bigint, AutoModerationRule>> {
   const results = await bot.rest.runMethod<DiscordAutoModerationRule[]>(
     bot.rest,

helpers/guilds/createGuild.ts

@@ -10,7 +10,20 @@ import {
   VerificationLevels,
 } from "../../types/shared.ts";
 
-/** Create a new guild. Returns a guild object on success. Fires a Guild Create Gateway event. This endpoint can be used only by bots in less than 10 guilds. */
+/**
+ * Creates a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param options - The parameters for the creation of the guild.
+ * @returns An instance of the created {@link Guild}.
+ *
+ * @remarks
+ * ⚠️ This route can only be used by bots in __fewer than 10 guilds__.
+ *
+ * Fires a _Guild Create_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#create-guild}
+ */
 export async function createGuild(bot: Bot, options: CreateGuild): Promise<Guild> {
   const result = await bot.rest.runMethod<DiscordGuild>(bot.rest, "POST", bot.constants.routes.GUILDS(), {
     name: options.name,

helpers/guilds/deleteGuild.ts

@@ -1,6 +1,18 @@
 import type { Bot } from "../../bot.ts";
 
-/** Delete a guild permanently. User must be owner. Returns 204 No Content on success. Fires a Guild Delete Gateway event. */
+/**
+ * Deletes a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to delete.
+ *
+ * @remarks
+ * The bot user must be the owner of the guild.
+ *
+ * Fires a _Guild Delete_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#delete-guild}
+ */
 export async function deleteGuild(bot: Bot, guildId: bigint): Promise<void> {
   return await bot.rest.runMethod<void>(bot.rest, "DELETE", bot.constants.routes.GUILD(guildId));
 }

helpers/guilds/editGuild.ts

@@ -9,7 +9,27 @@ import {
   VerificationLevels,
 } from "../../types/shared.ts";
 
-/** Modify a guilds settings. Requires the MANAGE_GUILD permission. */
+// TODO: Put the `shardId` parameter before `options`.
+
+/**
+ * Edits a guild's settings.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to edit.
+ * @param shardId - The ID of the shard the guild is in.
+ * @param options - The parameters for the edit of the guild.
+ * @returns An instance of the edited {@link Guild}.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * If attempting to add or remove the {@link GuildFeatures.Community} feature:
+ * - Requires the `ADMINISTRATOR` permission.
+ *
+ * Fires a _Guild Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#modify-guild}
+ */
 export async function editGuild(bot: Bot, guildId: bigint, options: ModifyGuild, shardId: number): Promise<Guild> {
   if (options.icon && !options.icon.startsWith("data:image/")) {
     options.icon = await bot.utils.urlToBase64(options.icon);

helpers/guilds/editWelcomeScreen.ts

@@ -2,6 +2,21 @@ import type { Bot } from "../../bot.ts";
 import { WelcomeScreen } from "../../transformers/welcomeScreen.ts";
 import { DiscordWelcomeScreen } from "../../types/discord.ts";
 
+/**
+ * Edits a guild's welcome screen.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to edit the welcome screen of.
+ * @param options - The parameters for the edit of the welcome screen.
+ * @returns An instance of the edited {@link WelcomeScreen}.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * Fires a _Guild Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#modify-guild-welcome-screen}
+ */
 export async function editWelcomeScreen(
   bot: Bot,
   guildId: bigint,

helpers/guilds/editWidget.ts

@@ -1,23 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { GuildWidgetSettings } from "../../transformers/widgetSettings.ts";
-import { DiscordGuildWidgetSettings } from "../../types/discord.ts";
-
-/** Modify a guild widget object for the guild. Requires the MANAGE_GUILD permission. */
-export async function editWidget(
-  bot: Bot,
-  guildId: bigint,
-  enabled: boolean,
-  channelId?: string | null,
-): Promise<GuildWidgetSettings> {
-  const result = await bot.rest.runMethod<DiscordGuildWidgetSettings>(
-    bot.rest,
-    "PATCH",
-    bot.constants.routes.GUILD_WIDGET(guildId),
-    {
-      enabled,
-      channel_id: channelId,
-    },
-  );
-
-  return bot.transformers.widgetSettings(bot, result);
-}

helpers/guilds/events/createScheduledEvent.ts

@@ -3,7 +3,23 @@ import { ScheduledEvent } from "../../../transformers/scheduledEvent.ts";
 import { DiscordScheduledEvent } from "../../../types/discord.ts";
 import { ScheduledEventEntityType, ScheduledEventPrivacyLevel } from "../../../types/shared.ts";
 
-/** Create a guild scheduled event in the guild. A guild can have a maximum of 100 events with `SCHEDULED` or `ACTIVE` status at any time. */
+/**
+ * Creates a scheduled event in a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to create the scheduled event in.
+ * @param options - The parameters for the creation of the scheduled event.
+ * @returns An instance of the created {@link ScheduledEvent}.
+ *
+ * @remarks
+ * Requires the `MANAGE_EVENTS` permission.
+ *
+ * A guild can only have a maximum of 100 events with a status of {@link ScheduledEventStatus.Active} or {@link ScheduledEventStatus.Scheduled} (inclusive).
+ *
+ * Fires a _Guild Scheduled Event Create_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild-scheduled-event#create-guild-scheduled-event}
+ */
 export async function createScheduledEvent(
   bot: Bot,
   guildId: bigint,

helpers/guilds/events/deleteScheduledEvent.ts

@@ -0,0 +1,23 @@
+import { Bot } from "../../../bot.ts";
+
+/**
+ * Deletes a scheduled event from a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to delete the scheduled event from.
+ * @param eventId - The ID of the scheduled event to delete.
+ *
+ * @remarks
+ * Requires the `MANAGE_EVENTS` permission.
+ *
+ * Fires a _Guild Scheduled Event Delete_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild-scheduled-event#delete-guild-scheduled-event}
+ */
+export async function deleteScheduledEvent(bot: Bot, guildId: bigint, eventId: bigint): Promise<void> {
+  return await bot.rest.runMethod<void>(
+    bot.rest,
+    "DELETE",
+    bot.constants.routes.GUILD_SCHEDULED_EVENT(guildId, eventId),
+  );
+}

helpers/guilds/events/editScheduledEvent.ts

@@ -3,7 +3,25 @@ import { ScheduledEvent } from "../../../transformers/scheduledEvent.ts";
 import { DiscordScheduledEvent } from "../../../types/discord.ts";
 import { ScheduledEventEntityType, ScheduledEventPrivacyLevel, ScheduledEventStatus } from "../../../types/shared.ts";
 
-/** Modify a guild scheduled event. To start or end an event, use this endpoint to modify the event's status. */
+/**
+ * Edits a scheduled event.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to edit the scheduled event in.
+ * @param eventId - The ID of the scheduled event to edit.
+ * @returns An instance of the edited {@link ScheduledEvent}.
+ *
+ * @remarks
+ * Requires the `MANAGE_EVENTS` permission.
+ *
+ * To start or end an event, modify the event's `status` property.
+ *
+ * The `entity_metadata` property is discarded for events whose `entity_type` is not {@link ScheduledEventEntityType.External}.
+ *
+ * Fires a _Guild Scheduled Event Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild-scheduled-event#modify-guild-scheduled-event}
+ */
 export async function editScheduledEvent(
   bot: Bot,
   guildId: bigint,

helpers/guilds/events/getScheduledEvent.ts

@@ -2,7 +2,17 @@ import { Bot } from "../../../bot.ts";
 import { ScheduledEvent } from "../../../transformers/scheduledEvent.ts";
 import { DiscordScheduledEvent } from "../../../types/discord.ts";
 
-/** Get a guild scheduled event. */
+/**
+ * Gets a scheduled event by its ID.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the scheduled event from.
+ * @param eventId - The ID of the scheduled event to get.
+ * @param options - The parameters for the fetching of the scheduled event.
+ * @returns An instance of {@link ScheduledEvent}.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild-scheduled-event#get-guild-scheduled-event}
+ */
 export async function getScheduledEvent(
   bot: Bot,
   guildId: bigint,

helpers/guilds/events/getScheduledEventUsers.ts

@@ -3,6 +3,25 @@ import { Member, User } from "../../../transformers/member.ts";
 import { DiscordMember, DiscordUser } from "../../../types/discord.ts";
 import { Collection } from "../../../util/collection.ts";
 
+// TODO: This endpoint discards certain data from the result.
+//  Create `ScheduledEventUser` type and parse the data to it.
+
+/**
+ * Gets the list of subscribers to a scheduled event from a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the subscribers to the scheduled event from.
+ * @param eventId - The ID of the scheduled event to get the subscribers of.
+ * @param options - The parameters for the fetching of the subscribers.
+ * @returns A collection of {@link User} objects assorted by user ID.
+ *
+ * @remarks
+ * Requires the `MANAGE_EVENTS` permission.
+ *
+ * Users are ordered by their IDs in _ascending_ order.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild-scheduled-event#get-guild-scheduled-event-users}
+ */
 export async function getScheduledEventUsers(
   bot: Bot,
   guildId: bigint,

helpers/guilds/events/getScheduledEvents.ts

@@ -3,7 +3,16 @@ import { ScheduledEvent } from "../../../transformers/scheduledEvent.ts";
 import { DiscordScheduledEvent } from "../../../types/discord.ts";
 import { Collection } from "../../../util/collection.ts";
 
-/** Get a list of guild scheduled event for the given guild. */
+/**
+ * Gets the list of scheduled events for a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the scheduled events from.
+ * @param options - The parameters for the fetching of the scheduled events.
+ * @returns A collection of {@link ScheduledEvent} objects assorted by event ID.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild-scheduled-event#list-scheduled-events-for-guild}
+ */
 export async function getScheduledEvents(
   bot: Bot,
   guildId: bigint,

helpers/guilds/getAuditLog.ts

@@ -21,8 +21,22 @@ export type AuditLog = {
   applicationCommands: ApplicationCommand[];
 };
 
-/** Returns the audit logs for the guild. Requires VIEW_AUDIT_LOGS permission */
-export async function getAuditLogs(bot: Bot, guildId: bigint, options?: GetGuildAuditLog): Promise<AuditLog> {
+// TODO: Move `AuditLog` into its own transformer file.
+
+/**
+ * Gets a guild's audit log.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the audit log of.
+ * @param options - The parameters for the fetching of the audit log.
+ * @returns An instance of {@link AuditLog}.
+ *
+ * @remarks
+ * Requires the `VIEW_AUDIT_LOG` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/audit-log#get-guild-audit-log}
+ */
+export async function getAuditLog(bot: Bot, guildId: bigint, options?: GetGuildAuditLog): Promise<AuditLog> {
   if (options?.limit) {
     options.limit = options.limit >= 1 && options.limit <= 100 ? options.limit : 50;
   }

helpers/guilds/getAvailableVoiceRegions.ts

@@ -1,20 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { VoiceRegions } from "../../transformers/voiceRegion.ts";
-import { DiscordVoiceRegion } from "../../types/discord.ts";
-import { Collection } from "../../util/collection.ts";
-
-/** Returns an array of voice regions that can be used when creating servers. */
-export async function getAvailableVoiceRegions(bot: Bot): Promise<Collection<string, VoiceRegions>> {
-  const results = await bot.rest.runMethod<DiscordVoiceRegion[]>(
-    bot.rest,
-    "GET",
-    bot.constants.routes.VOICE_REGIONS(),
-  );
-
-  return new Collection(
-    results.map((result) => {
-      const region = bot.transformers.voiceRegion(bot, result);
-      return [region.id, region];
-    }),
-  );
-}

helpers/guilds/getBan.ts

@@ -7,12 +7,26 @@ export type Ban = {
   user: User;
 };
 
-/** Returns a ban object for the given user or a 404 not found if the ban cannot be found. Requires the BAN_MEMBERS permission. */
-export async function getBan(bot: Bot, guildId: bigint, memberId: bigint): Promise<Ban> {
+// TODO: Move `Ban` into its own transformer file.
+
+/**
+ * Gets a ban by user ID.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the ban from.
+ * @param userId - The ID of the user to get the ban for.
+ * @returns An instance of {@link Ban}.
+ *
+ * @remarks
+ * Requires the `BAN_MEMBERS` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild-ban}
+ */
+export async function getBan(bot: Bot, guildId: bigint, userId: bigint): Promise<Ban> {
   const result = await bot.rest.runMethod<DiscordBan>(
     bot.rest,
     "GET",
-    bot.constants.routes.GUILD_BAN(guildId, memberId),
+    bot.constants.routes.GUILD_BAN(guildId, userId),
   );
 
   return {

helpers/guilds/getBans.ts

@@ -3,7 +3,21 @@ import { DiscordBan } from "../../types/discord.ts";
 import { Collection } from "../../util/collection.ts";
 import { Ban } from "./getBan.ts";
 
-/** Returns a list of ban objects for the users banned from this guild. Requires the BAN_MEMBERS permission. */
+/**
+ * Gets the list of bans for a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the list of bans for.
+ * @param options - The parameters for the fetching of the list of bans.
+ * @returns A collection of {@link Ban} objects assorted by user ID.
+ *
+ * @remarks
+ * Requires the `BAN_MEMBERS` permission.
+ *
+ * Users are ordered by their IDs in _ascending_ order.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild-bans}
+ */
 export async function getBans(bot: Bot, guildId: bigint, options?: GetBans): Promise<Collection<bigint, Ban>> {
   const results = await bot.rest.runMethod<DiscordBan[]>(
     bot.rest,

helpers/guilds/getGuild.ts

@@ -3,8 +3,14 @@ import { Guild } from "../../transformers/guild.ts";
 import { DiscordGuild } from "../../types/discord.ts";
 
 /**
- * This function fetches a guild's data. This is not the same data as a GUILD_CREATE.
- * So it does not cache the guild, you must do it manually.
+ * Gets a guild by its ID.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get.
+ * @param options - The parameters for the fetching of the guild.
+ * @returns An instance of {@link Guild}.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild}
  */
 export async function getGuild(
   bot: Bot,

helpers/guilds/getGuildBannerUrl.ts

@@ -1,10 +1,19 @@
 import type { Bot } from "../../bot.ts";
 import { ImageFormat, ImageSize } from "../members/getAvatarUrl.ts";
 
-/** The full URL of the banner from Discords CDN. Undefined if no banner is set. */
+// TODO: Move `banner` from `options` into the parameters and rename to `imageHash`.
+
+/**
+ * Builds a URL to the guild banner stored in the Discord CDN.
+ *
+ * @param bot - The bot instance to use to build the URL.
+ * @param guildId - The ID of the guild to get the link to the banner for.
+ * @param options - The parameters for the building of the URL.
+ * @returns The link to the resource or `undefined` if no banner has been set.
+ */
 export function getGuildBannerURL(
   bot: Bot,
-  id: bigint,
+  guildId: bigint,
   options: {
     banner?: string | bigint;
     size?: ImageSize;
@@ -14,7 +23,7 @@ export function getGuildBannerURL(
   return options.banner
     ? bot.utils.formatImageURL(
       bot.constants.routes.GUILD_BANNER(
-        id,
+        guildId,
         typeof options.banner === "string" ? options.banner : bot.utils.iconBigintToHash(options.banner),
       ),
       options.size || 128,

helpers/guilds/getGuildIconUrl.ts

@@ -1,21 +1,28 @@
 import type { Bot } from "../../bot.ts";
 import { ImageFormat, ImageSize } from "../members/getAvatarUrl.ts";
 
-/** The full URL of the icon from Discords CDN. Undefined when no icon is set. */
+/**
+ * Builds a URL to the guild icon stored in the Discord CDN.
+ *
+ * @param bot - The bot instance to use to build the URL.
+ * @param guildId - The ID of the guild to get the link to the banner for.
+ * @param options - The parameters for the building of the URL.
+ * @returns The link to the resource or `undefined` if no banner has been set.
+ */
 export function getGuildIconURL(
   bot: Bot,
-  id: bigint,
-  icon: bigint | undefined,
+  guildId: bigint,
+  imageHash: bigint | undefined,
   options?: {
     size?: ImageSize;
     format?: ImageFormat;
   },
 ): string | undefined {
-  return icon
+  return imageHash
     ? bot.utils.formatImageURL(
       bot.constants.routes.GUILD_ICON(
-        id,
-        typeof icon === "string" ? icon : bot.utils.iconBigintToHash(icon),
+        guildId,
+        typeof imageHash === "string" ? imageHash : bot.utils.iconBigintToHash(imageHash),
       ),
       options?.size || 128,
       options?.format,

helpers/guilds/getGuildPreview.ts

@@ -18,7 +18,20 @@ export type GuildPreview = {
   stickers: Sticker[];
 };
 
-/** Returns the guild preview object for the given id. If the bot is not in the guild, then the guild must be Discoverable. */
+// TODO: Move `GuildPreview` into its own transformer file.
+
+/**
+ * Gets the preview of a guild by a guild's ID.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the preview of.
+ * @returns An instance of {@link GuildPreview}.
+ *
+ * @remarks
+ * If the bot user is not in the guild, the guild must be lurkable.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild-preview}
+ */
 export async function getGuildPreview(bot: Bot, guildId: bigint): Promise<GuildPreview> {
   const result = await bot.rest.runMethod<DiscordGuildPreview>(
     bot.rest,

helpers/guilds/getGuildSplashUrl.ts

@@ -1,21 +1,29 @@
 import type { Bot } from "../../bot.ts";
 import { ImageFormat, ImageSize } from "../members/getAvatarUrl.ts";
 
-/** The full URL of the splash from Discords CDN. Undefined if no splash is set. */
+/**
+ * Builds the URL to a guild splash stored in the Discord CDN.
+ *
+ * @param bot - The bot instance to use to build the URL.
+ * @param guildId - The ID of the guild to get the splash of.
+ * @param imageHash - The hash identifying the splash image.
+ * @param options - The parameters for the building of the URL.
+ * @returns The link to the resource or `undefined` if the guild does not have a splash image set.
+ */
 export function getGuildSplashURL(
   bot: Bot,
-  id: bigint,
-  splash: bigint | undefined,
+  guildId: bigint,
+  imageHash: bigint | undefined,
   options?: {
     size?: ImageSize;
     format?: ImageFormat;
   },
 ): string | undefined {
-  return splash
+  return imageHash
     ? bot.utils.formatImageURL(
       bot.constants.routes.GUILD_SPLASH(
-        id,
-        typeof splash === "string" ? splash : bot.utils.iconBigintToHash(splash),
+        guildId,
+        typeof imageHash === "string" ? imageHash : bot.utils.iconBigintToHash(imageHash),
       ),
       options?.size || 128,
       options?.format,

helpers/guilds/getPruneCount.ts

@@ -4,7 +4,19 @@ interface DiscordPrunedCount {
   pruned: number;
 }
 
-/** Check how many members would be removed from the server in a prune operation. Requires the KICK_MEMBERS permission */
+/**
+ * Gets the number of members that would be kicked from a guild during pruning.
+ *
+ * @param bot - The bot instance used to make the request
+ * @param guildId - The ID of the guild to get the prune count of.
+ * @param options - The parameters for the fetching of the prune count.
+ * @returns A number indicating the number of members that would be kicked.
+ *
+ * @remarks
+ * Requires the `KICK_MEMBERS` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild-prune-count}
+ */
 export async function getPruneCount(bot: Bot, guildId: bigint, options?: GetGuildPruneCountQuery): Promise<number> {
   if (options?.days && options.days < 1) throw new Error(bot.constants.Errors.PRUNE_MIN_DAYS);
   if (options?.days && options.days > 30) throw new Error(bot.constants.Errors.PRUNE_MAX_DAYS);

helpers/guilds/getVanityUrl.ts

@@ -1,11 +1,26 @@
 import type { Bot } from "../../bot.ts";
 
 export type VanityUrl = {
-  code?: string;
+  code: string | null;
   uses: number;
 };
 
-/** Returns the code and uses of the vanity url for this server if it is enabled else `code` will be null. Requires the `MANAGE_GUILD` permission. */
+// TODO: Move `VanityUrl` into its own transformer file.
+
+/**
+ * Gets information about the vanity url of a guild.
+ *
+ * @param bot - The bot instance used to make the request
+ * @param guildId - The ID of the guild to get the vanity url information for.
+ * @returns An instance of {@link VanityUrl}.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * The `code` property will be `null` if the guild does not have a set vanity url.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild-vanity-url}
+ */
 export async function getVanityUrl(bot: Bot, guildId: bigint): Promise<VanityUrl> {
   return await bot.rest.runMethod<VanityUrl>(
     bot.rest,

helpers/guilds/getVoiceRegions.ts

@@ -1,20 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { VoiceRegions } from "../../transformers/voiceRegion.ts";
-import { DiscordVoiceRegion } from "../../types/discord.ts";
-import { Collection } from "../../util/collection.ts";
-
-/** Returns a list of voice region objects for the guild. Unlike the similar /voice route, this returns VIP servers when the guild is VIP-enabled. */
-export async function getVoiceRegions(bot: Bot, guildId: bigint): Promise<Collection<string, VoiceRegions>> {
-  const results = await bot.rest.runMethod<DiscordVoiceRegion[]>(
-    bot.rest,
-    "GET",
-    bot.constants.routes.GUILD_REGIONS(guildId),
-  );
-
-  return new Collection(
-    results.map((result) => {
-      const region = bot.transformers.voiceRegion(bot, result);
-      return [region.id, region];
-    }),
-  );
-}

helpers/guilds/getWelcomeScreen.ts

@@ -2,7 +2,19 @@ import type { Bot } from "../../bot.ts";
 import { WelcomeScreen } from "../../transformers/welcomeScreen.ts";
 import { DiscordWelcomeScreen } from "../../types/discord.ts";
 
-/** Returns the Welcome Screen object for the guild. Requires the `MANAGE_GUILD` permission. */
+/**
+ * Gets the welcome screen for a guild.
+ *
+ * @param bot - The bot instance used to make the request
+ * @param guildId - The ID of the guild to get the welcome screen for.
+ * @returns An instance of {@link WelcomeScreen}.
+ *
+ * @remarks
+ * If the welcome screen is not enabled:
+ * - Requires the `MANAGE_GUILD` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild-welcome-screen}
+ */
 export async function getWelcomeScreen(bot: Bot, guildId: bigint): Promise<WelcomeScreen> {
   const result = await bot.rest.runMethod<DiscordWelcomeScreen>(
     bot.rest,

helpers/guilds/getWidget.ts

@@ -1,14 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { GuildWidget } from "../../transformers/widget.ts";
-import { DiscordGuildWidget } from "../../types/discord.ts";
-
-/** Returns the widget for the guild. */
-export async function getWidget(bot: Bot, guildId: bigint): Promise<GuildWidget> {
-  const result = await bot.rest.runMethod<DiscordGuildWidget>(
-    bot.rest,
-    "GET",
-    bot.constants.routes.GUILD_WIDGET_JSON(guildId),
-  );
-
-  return bot.transformers.widget(bot, result);
-}

helpers/guilds/getWidgetSettings.ts

@@ -1,14 +0,0 @@
-import type { Bot } from "../../bot.ts";
-import { GuildWidgetSettings } from "../../transformers/widgetSettings.ts";
-import { DiscordGuildWidgetSettings } from "../../types/discord.ts";
-
-/** Returns a guild widget settings object. Requires the MANAGE_GUILD permission. */
-export async function getWidgetSettings(bot: Bot, guildId: bigint): Promise<GuildWidgetSettings> {
-  const result = await bot.rest.runMethod<DiscordGuildWidgetSettings>(
-    bot.rest,
-    "GET",
-    bot.constants.routes.GUILD_WIDGET(guildId),
-  );
-
-  return bot.transformers.widgetSettings(bot, result);
-}

helpers/guilds/integrations/deleteIntegration.ts

@@ -0,0 +1,26 @@
+import type { Bot } from "../../../bot.ts";
+
+/**
+ * Deletes an integration attached to a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild from which to delete the integration.
+ * @param integrationId - The ID of the integration to delete from the guild.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * Deletes all webhooks associated with the integration, and kicks the associated bot if there is one.
+ *
+ * Fires a _Guild Integrations Update_ gateway event.
+ * Fires a _Integration Delete_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#delete-guild-integration}
+ */
+export async function deleteIntegration(bot: Bot, guildId: bigint, integrationId: bigint): Promise<void> {
+  return await bot.rest.runMethod<void>(
+    bot.rest,
+    "DELETE",
+    bot.constants.routes.GUILD_INTEGRATION(guildId, integrationId),
+  );
+}

helpers/guilds/integrations/getIntegrations.ts

@@ -1,9 +1,20 @@
-import type { Bot } from "../../bot.ts";
-import { Integration } from "../../transformers/integration.ts";
-import { DiscordIntegration } from "../../types/discord.ts";
-import { Collection } from "../../util/collection.ts";
+import type { Bot } from "../../../bot.ts";
+import { Integration } from "../../../transformers/integration.ts";
+import { DiscordIntegration } from "../../../types/discord.ts";
+import { Collection } from "../../../util/collection.ts";
 
-/** Returns a list of integrations for the guild. Requires the MANAGE_GUILD permission. */
+/**
+ * Gets the list of integrations attached to a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the list of integrations from.
+ * @returns A collection of {@link Integration} objects assorted by integration ID.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/guild#get-guild-integrations}
+ */
 export async function getIntegrations(bot: Bot, guildId: bigint): Promise<Collection<bigint, Integration>> {
   const results = await bot.rest.runMethod<DiscordIntegration[]>(
     bot.rest,

helpers/guilds/invites/createInvite.ts

@@ -1,9 +1,26 @@
-import type { Bot } from "../../bot.ts";
-import { DiscordInvite } from "../../types/discord.ts";
-import { TargetTypes } from "../../types/shared.ts";
+import type { Bot } from "../../../bot.ts";
+import { DiscordInvite } from "../../../types/discord.ts";
+import { TargetTypes } from "../../../types/shared.ts";
 import { BaseInvite } from "./getInvite.ts";
 
-/** Creates a new invite for this channel. Requires CREATE_INSTANT_INVITE */
+/**
+ * Creates an invite to a channel in a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param channelId - The ID of the channel to create the invite to.
+ * @param options - The parameters for the creation of the invite.
+ * @returns An instance of the created {@link BaseInvite | Invite}.
+ *
+ * @remarks
+ * Requires the `CREATE_INSTANT_INVITE` permission.
+ *
+ * Fires an _Invite Create_ gateway event.
+ *
+ * @privateRemarks
+ * The request body is not optional, and an empty JSON object must be sent regardless of whether any fields are being transmitted.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#create-channel-invite}
+ */
 export async function createInvite(
   bot: Bot,
   channelId: bigint,

helpers/guilds/invites/deleteInvite.ts

@@ -0,0 +1,18 @@
+import type { Bot } from "../../../bot.ts";
+
+/**
+ * Deletes an invite to a channel.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param inviteCode - The invite code of the invite to delete.
+ *
+ * @remarks
+ * Requires the `MANAGE_CHANNELS` permission.
+ *
+ * Fires an _Invite Delete_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/channel#delete-channel-invite}
+ */
+export async function deleteInvite(bot: Bot, inviteCode: string): Promise<void> {
+  return await bot.rest.runMethod<void>(bot.rest, "DELETE", bot.constants.routes.INVITE(inviteCode));
+}

helpers/guilds/invites/getInvite.ts

@@ -1,6 +1,6 @@
-import type { Bot } from "../../bot.ts";
-import { ScheduledEvent, TargetTypes, User } from "../../mod.ts";
-import { DiscordInviteMetadata } from "../../types/discord.ts";
+import type { Bot } from "../../../bot.ts";
+import { ScheduledEvent, TargetTypes, User } from "../../../mod.ts";
+import { DiscordInviteMetadata } from "../../../types/discord.ts";
 
 export type BaseInvite = {
   code: string;
@@ -24,7 +24,16 @@ export type InviteMetadata = BaseInvite & {
   createdAt: number;
 };
 
-/** Returns an invite for the given code or throws an error if the invite doesn't exists. */
+/**
+ * Gets an invite to a channel by its invite code.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param inviteCode - The invite code of the invite to get.
+ * @param options - The parameters for the fetching of the invite.
+ * @returns An instance of {@link BaseInvite | Invite}.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/invite#get-invite}
+ */
 export async function getInvite(bot: Bot, inviteCode: string, options?: GetInvite): Promise<BaseInvite> {
   const result = await bot.rest.runMethod<DiscordInviteMetadata>(
     bot.rest,

helpers/guilds/invites/getInvites.ts

@@ -1,10 +1,21 @@
-import type { Bot } from "../../bot.ts";
-import { TargetTypes } from "../../mod.ts";
-import { DiscordInviteMetadata } from "../../types/discord.ts";
-import { Collection } from "../../util/collection.ts";
+import type { Bot } from "../../../bot.ts";
+import { TargetTypes } from "../../../mod.ts";
+import { DiscordInviteMetadata } from "../../../types/discord.ts";
+import { Collection } from "../../../util/collection.ts";
 import { InviteMetadata } from "./getInvite.ts";
 
-/** Get all the invites for this guild. Requires MANAGE_GUILD permission */
+/**
+ * Gets the list of invites for a guild.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild to get the invites from.
+ * @returns A collection of {@link InviteMetadata | Invite} objects assorted by invite code.
+ *
+ * @remarks
+ * Requires the `MANAGE_GUILD` permission.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/invite#get-invites}
+ */
 export async function getInvites(bot: Bot, guildId: bigint): Promise<Collection<string, InviteMetadata>> {
   const results = await bot.rest.runMethod<DiscordInviteMetadata[]>(
     bot.rest,

helpers/guilds/invites/mod.ts

@@ -1,5 +1,4 @@
 export * from "./createInvite.ts";
 export * from "./deleteInvite.ts";
-export * from "./getChannelInvites.ts";
 export * from "./getInvite.ts";
 export * from "./getInvites.ts";

helpers/guilds/leaveGuild.ts

@@ -1,6 +1,16 @@
 import type { Bot } from "../../bot.ts";
 
-/** Leave a guild */
+/**
+ * Leaves a guild.
+ *
+ * @param bot - The bot instance used to make the request
+ * @param guildId - The ID of the guild to leave.
+ *
+ * @remarks
+ * Fires a _Guild Delete_ event.
+ *
+ * @see {@link https://discord.com/developers/docs/resources/user#leave-guild}
+ */
 export async function leaveGuild(bot: Bot, guildId: bigint): Promise<void> {
   return await bot.rest.runMethod<void>(bot.rest, "DELETE", bot.constants.routes.GUILD_LEAVE(guildId));
 }

helpers/guilds/mod.ts

@@ -1,12 +1,16 @@
 export * from "./automod/mod.ts";
+export * from "./integrations/mod.ts";
+export * from "./invites/mod.ts";
+export * from "./events/mod.ts";
+export * from "./voice/mod.ts";
+export * from "./widget/mod.ts";
+
 export * from "./createGuild.ts";
 export * from "./deleteGuild.ts";
 export * from "./editGuild.ts";
 export * from "./editGuildMfaLevel.ts";
 export * from "./editWelcomeScreen.ts";
-export * from "./editWidget.ts";
-export * from "./getAuditLogs.ts";
-export * from "./getAvailableVoiceRegions.ts";
+export * from "./getAuditLog.ts";
 export * from "./getBan.ts";
 export * from "./getBans.ts";
 export * from "./getGuild.ts";
@@ -16,10 +20,5 @@ export * from "./getGuildPreview.ts";
 export * from "./getGuildSplashUrl.ts";
 export * from "./getPruneCount.ts";
 export * from "./getVanityUrl.ts";
-export * from "./getVoiceRegions.ts";
 export * from "./getWelcomeScreen.ts";
-export * from "./getWidget.ts";
-export * from "./getWidgetImageUrl.ts";
-export * from "./getWidgetSettings.ts";
 export * from "./leaveGuild.ts";
-export * from "./scheduledEvents/mod.ts";

helpers/guilds/scheduledEvents/deleteScheduledEvent.ts

@@ -1,10 +0,0 @@
-import { Bot } from "../../../bot.ts";
-
-/** Delete a scheduled event. */
-export async function deleteScheduledEvent(bot: Bot, guildId: bigint, eventId: bigint): Promise<void> {
-  return await bot.rest.runMethod<void>(
-    bot.rest,
-    "DELETE",
-    bot.constants.routes.GUILD_SCHEDULED_EVENT(guildId, eventId),
-  );
-}

helpers/guilds/voice/connectToVoiceChannel.ts

@@ -1,7 +1,21 @@
-import type { Bot } from "../../bot.ts";
-import { AtLeastOne, GatewayOpcodes } from "../../types/shared.ts";
+import type { Bot } from "../../../bot.ts";
+import { AtLeastOne, GatewayOpcodes } from "../../../types/shared.ts";
 
-/** Connect or join a voice channel inside a guild. By default, the "selfDeaf" option is true. Requires `CONNECT` and `VIEW_CHANNEL` permissions. */
+/**
+ * Connects the bot user to a voice or stage channel.
+ *
+ * This function sends the _Update Voice State_ gateway command over the gateway behind the scenes.
+ *
+ * @param bot - The bot instance to use to make the request.
+ * @param guildId - The ID of the guild the voice channel to leave is in.
+ *
+ * @remarks
+ * Requires the `CONNECT` permission.
+ *
+ * Fires a _Voice State Update_ gateway event.
+ *
+ * @see {@link https://discord.com/developers/docs/topics/gateway#update-voice-state}
+ */
 export async function connectToVoiceChannel(
   bot: Bot,
   guildId: bigint,