add: stage instances (#924)

* feat: implement stage instances

Reference: https://github.com/discord/discord-api-docs/pull/2898

* feat: implement stage instances

* Update src/types/misc/stage_instance.ts

Co-authored-by: ITOH <to@itoh.at>

* Update src/helpers/misc/delete_stage_instance.ts

Co-authored-by: ITOH <to@itoh.at>

* Update src/types/misc/stage_instance.ts

Co-authored-by: ITOH <to@itoh.at>

* Move stage instances related modules to channels module

* Move to channels

* Move to channels

* Add permission checks

* Add permissions checl

* Ad inhibitors

* style: fix lint warnings

* Do not throw & add import type

Co-authored-by: ITOH <to@itoh.at>

src/helpers/channels/create_stage_instance.ts

@@ -0,0 +1,40 @@
+import { validateLength } from "../../util/validate_length.ts";
+import { Errors } from "../../types/discordeno/errors.ts";
+import { rest } from "../../rest/rest.ts";
+import { endpoints } from "../../util/constants.ts";
+import type { StageInstance } from "../../types/channels/stage_instance.ts";
+import { cacheHandlers } from "../../cache.ts";
+import { ChannelTypes } from "../../types/channels/channel_types.ts";
+import { requireBotChannelPermissions } from "../../util/permissions.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(channelId: bigint, topic: string) {
+  const channel = await cacheHandlers.get("channels", channelId);
+
+  if (channel) {
+    if (channel.type !== ChannelTypes.GuildStageVoice) {
+      throw new Error(Errors.CHANNEL_NOT_STAGE_VOICE);
+    }
+
+    await requireBotChannelPermissions(channel, [
+      "MANAGE_CHANNELS",
+      "MUTE_MEMBERS",
+      "MOVE_MEMBERS",
+    ]);
+  }
+
+  if (
+    !validateLength(topic, { max: 120, min: 1 })
+  ) {
+    throw new Error(Errors.INVALID_TOPIC_LENGTH);
+  }
+
+  return await rest.runMethod<StageInstance>(
+    "post",
+    endpoints.STAGE_INSTANCES,
+    {
+      "channel_id": channelId,
+      topic,
+    },
+  );
+}

src/helpers/channels/delete_stage_instance.ts

@@ -0,0 +1,28 @@
+import { cacheHandlers } from "../../cache.ts";
+import { rest } from "../../rest/rest.ts";
+import { ChannelTypes } from "../../types/channels/channel_types.ts";
+import { Errors } from "../../types/discordeno/errors.ts";
+import { endpoints } from "../../util/constants.ts";
+import { requireBotChannelPermissions } from "../../util/permissions.ts";
+
+/** Deletes the Stage instance. Requires the user to be a moderator of the Stage channel. */
+export async function deleteStageInstance(channelId: bigint) {
+  const channel = await cacheHandlers.get("channels", channelId);
+
+  if (channel) {
+    if (channel.type !== ChannelTypes.GuildStageVoice) {
+      throw new Error(Errors.CHANNEL_NOT_STAGE_VOICE);
+    }
+
+    await requireBotChannelPermissions(channel, [
+      "MUTE_MEMBERS",
+      "MANAGE_CHANNELS",
+      "MOVE_MEMBERS",
+    ]);
+  }
+
+  return await rest.runMethod<undefined>(
+    "delete",
+    endpoints.STAGE_INSTANCE(channelId),
+  );
+}

src/helpers/channels/get_stage_instance.ts

@@ -0,0 +1,22 @@
+import { cacheHandlers } from "../../cache.ts";
+import { rest } from "../../rest/rest.ts";
+import { ChannelTypes } from "../../types/channels/channel_types.ts";
+import type { StageInstance } from "../../types/channels/stage_instance.ts";
+import { Errors } from "../../types/discordeno/errors.ts";
+import { endpoints } from "../../util/constants.ts";
+
+/** Gets the stage instance associated with the Stage channel, if it exists. */
+export async function getStageInstance(channelId: bigint) {
+  const channel = await cacheHandlers.get("channels", channelId);
+
+  if (channel) {
+    if (channel.type !== ChannelTypes.GuildStageVoice) {
+      throw new Error(Errors.CHANNEL_NOT_STAGE_VOICE);
+    }
+  }
+
+  return await rest.runMethod<StageInstance>(
+    "get",
+    endpoints.STAGE_INSTANCE(channelId),
+  );
+}

src/helpers/channels/update_stage_instance.ts

@@ -0,0 +1,42 @@
+import { rest } from "../../rest/rest.ts";
+import { Errors } from "../../types/discordeno/errors.ts";
+import type { StageInstance } from "../../types/channels/stage_instance.ts";
+import { endpoints } from "../../util/constants.ts";
+import { validateLength } from "../../util/validate_length.ts";
+import { cacheHandlers } from "../../cache.ts";
+import { requireBotChannelPermissions } from "../../util/permissions.ts";
+import { ChannelTypes } from "../../types/channels/channel_types.ts";
+
+/** Updates fields of an existing Stage instance. Requires the user to be a moderator of the Stage channel. */
+export async function updateStageInstance(channelId: bigint, topic: string) {
+  const channel = await cacheHandlers.get("channels", channelId);
+
+  if (channel) {
+    if (channel.type !== ChannelTypes.GuildStageVoice) {
+      throw new Error(Errors.CHANNEL_NOT_STAGE_VOICE);
+    }
+
+    await requireBotChannelPermissions(channel, [
+      "MOVE_MEMBERS",
+      "MUTE_MEMBERS",
+      "MANAGE_CHANNELS",
+    ]);
+  }
+
+  if (
+    !validateLength(topic, {
+      min: 1,
+      max: 120,
+    })
+  ) {
+    throw new Error(Errors.INVALID_TOPIC_LENGTH);
+  }
+
+  return await rest.runMethod<StageInstance>(
+    "patch",
+    endpoints.STAGE_INSTANCE(channelId),
+    {
+      topic,
+    },
+  );
+}