feat: add support for stage channels (#728)

* feat: add support for stage channels

* idk

* Add helpers for voice state

* Rename updateUserVoiceState() to updateVoiceState()

* Update src/types/channels/channel_types.ts

Co-authored-by: ITOH <72305210+itohatweb@users.noreply.github.com>

* Update src/helpers/guilds/update_user_voice_state.ts

Co-authored-by: ITOH <72305210+itohatweb@users.noreply.github.com>

* Update src/helpers/guilds/update_bot_voice_state.ts

Co-authored-by: ITOH <72305210+itohatweb@users.noreply.github.com>

Co-authored-by: ITOH <72305210+itohatweb@users.noreply.github.com>

src/helpers/guilds/update_bot_voice_state.ts

@@ -0,0 +1,28 @@
+import { RequestManager } from "../../rest/request_manager.ts";
+import {
+  DiscordUpdateSelfVoiceState,
+  UpdateSelfVoiceState,
+} from "../../types/guilds/update_self_voice_state.ts";
+import { endpoints } from "../../util/constants.ts";
+import { camelKeysToSnakeCase } from "../../util/utils.ts";
+
+/**
+ * Updates the current user's voice state.
+ * Caveats:
+ *  - `channel_id` must currently point to a stage channel.
+ *  - current user must already have joined `channel_id`.
+ *  - You must have the `MUTE_MEMBERS` permission to unsuppress yourself. You 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.
+ */
+export function updateBotVoiceState(
+  guildId: string,
+  data: UpdateSelfVoiceState,
+) {
+  const payload = camelKeysToSnakeCase<DiscordUpdateSelfVoiceState>(data);
+
+  return RequestManager.patch(
+    endpoints.UPDATE_VOICE_STATE(guildId),
+    payload,
+  );
+}

src/helpers/guilds/update_user_voice_state.ts

@@ -0,0 +1,29 @@
+import { RequestManager } from "../../rest/request_manager.ts";
+import {
+  DiscordUpdateOthersVoiceState,
+  UpdateOthersVoiceState,
+} from "../../types/guilds/update_others_voice_state.ts";
+import { endpoints } from "../../util/constants.ts";
+import { camelKeysToSnakeCase } from "../../util/utils.ts";
+
+/**
+ * Updates another 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. (Since suppression is the only thing that is available currently.)
+ *  - When unsuppressed, non-bot users will have their `request_to_speak_timestamp` set to the current time. Bot users will not.
+ *  - When suppressed, the user will have their `request_to_speak_timestamp` removed.
+ */
+export function updateVoiceState(
+  guildId: string,
+  userId: string,
+  data: UpdateOthersVoiceState,
+) {
+  const payload = camelKeysToSnakeCase<DiscordUpdateOthersVoiceState>(data);
+
+  return RequestManager.patch(
+    endpoints.UPDATE_VOICE_STATE(guildId, userId),
+    payload,
+  );
+}

src/types/channels/channel_types.ts

@@ -14,4 +14,6 @@ export enum DiscordChannelTypes {
   GUILD_NEWS,
   /** A channel in which game developers can sell their game on Discord */
   GUILD_STORE,
+  /** A voice channel for hosting events with an audience */
+  GUILD_STAGE_VOICE = 13,
 }

src/types/guilds/update_others_voice_state.ts

@@ -0,0 +1,13 @@
+import { SnakeCaseProps } from "../util.ts";
+
+export interface UpdateOthersVoiceState {
+  /** The id of the channel the user is currently in */
+  channelId: string;
+  /** Toggles the user's suppress state */
+  suppress?: boolean;
+}
+
+// TODO: add corresponding link to the resource
+export type DiscordUpdateOthersVoiceState = SnakeCaseProps<
+  UpdateOthersVoiceState
+>;

src/types/guilds/update_self_voice_state.ts

@@ -0,0 +1,13 @@
+import { SnakeCaseProps } from "../util.ts";
+
+export interface UpdateSelfVoiceState {
+  /** The id of the channel the user is currently in */
+  channelId: string;
+  /** Toggles the user's suppress state */
+  suppress?: boolean;
+  /** Sets the user's request to speak */
+  requestToSpeakTimestamp?: string | null;
+}
+
+// TODO: add corresponding link to the resource
+export type DiscordUpdateSelfVoiceState = SnakeCaseProps<UpdateSelfVoiceState>;

src/types/permissions/bitwise_permission_flags.ts

@@ -62,4 +62,6 @@ export enum DiscordBitwisePermissionFlags {
   MANAGE_WEBHOOKS = 0x20000000,
   /** Allows management and editing of emojis */
   MANAGE_EMOJIS = 0x40000000,
+  /** Allows for requesting to speak in stage channels. */
+  REQUEST_TO_SPEAK = 0x100000000,
 }

src/types/voice/voice_state.ts

@@ -26,6 +26,8 @@ export interface VoiceState {
   selfVideo: boolean;
   /** Whether this user is muted by the current user */
   suppress: boolean;
+  /** The time at which the user requested to speak */
+  requestToSpeakTimestamp: string | null;
 }
 
 /** https://discord.com/developers/docs/resources/voice#voice-state-object-voice-state-structure */

src/util/constants.ts

@@ -119,6 +119,8 @@ export const endpoints = {
     `${baseEndpoints.BASE_URL}/guilds/templates/${code}`,
   GUILD_TEMPLATES: (guildId: string) => `${GUILDS_BASE(guildId)}/templates`,
   GUILD_PREVIEW: (guildId: string) => `${GUILDS_BASE(guildId)}/preview`,
+  UPDATE_VOICE_STATE: (guildId: string, userId?: string) =>
+    `${GUILDS_BASE(guildId)}/voice-states/${userId ?? "@me"}`,
 
   // Voice
   VOICE_REGIONS: `${baseEndpoints.BASE_URL}/voice/regions`,