feat: stage channels (#5456)

* feat: add stage channel type

* feat: initialise stage channel structure

* feat: add STAGE_MODERATOR permissions bitfield

* fix: typo in permissions

* fix(Channel): type selection logic

* feat: add rtcRegion to StageChannel and VoiceChannel

* feat: rtc region editing for stage and voice channels

* feat: stage channel userLimit

* feat: add stage channels to exports

* feat: add computed properties to stage channel

* feat(VoiceState): include stage channel in docs

* feat: allow ability to join stage channels

* feat(StageChannel): join and leave methods

* docs: add StageChannel link in GuildChannel docs

* feat(VoiceState): suppress and requestToSpeakTimestamp

* feat(StageChannel): setRequestToSpeak

* refactor(StageChannel): update setRequestToSpeak

* feat(VoiceState): add moveToSpeakers and moveToAudience

* feat(VoiceState): add methods to move in/out of speakers

* feat(VoiceState): add stage channel sanity checks

* feat(Permissions): add REQUEST_TO_SPEAK

* feat(VoiceState): simpler methods

* docs(VoiceState): add documentation for new methods

* refactor: remove unused error message

* chore: remove debug statements

* chore: revert changes to package-lock.json

* docs(VoiceState): clarify suppress

* docs(VoiceState): add missing @type param

* feat(StageChannel): remove nsfw property

* fix(VoiceState): check permissions in channel

Co-authored-by: Advaith <advaithj1@gmail.com>

* fix(VoiceState): instantiate error with new

Co-authored-by: BannerBomb <BannerBomb55@gmail.com>

* refactor(VoiceState): more readable API route builder

Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com>

* style(VoiceState): fix lint errors

* docs(VoiceState): add example usage for new methods

* docs: setRTCRegion examples

* chore: update typings

* fix(VoiceState): calculate permissions for self

* refactor(VoiceState): tidy up implementation

* Update src/structures/VoiceState.js

Co-authored-by: Jan <66554238+vaporox@users.noreply.github.com>

* refactor: vaporox's suggestions

* style(VoiceState): fix linter errors

* chore: update typings

* chore: remove unused error message

* refactor(VoiceState): use optional chaining

Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com>

* chore: move getters below constructor in typings

* refactor(StageChannel): optional chaining

Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com>

* style(VoiceState): fix lint errors

* docs: fix incorrect types

Co-authored-by: izexi <43889168+izexi@users.noreply.github.com>

* Update src/structures/VoiceChannel.js

Co-authored-by: izexi <43889168+izexi@users.noreply.github.com>

* Update src/structures/VoiceChannel.js

Co-authored-by: izexi <43889168+izexi@users.noreply.github.com>

* refactor(VoiceState): use optional chaining

Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com>

* refactor(StageChannel): remove permission override check in joinable

* refactor: make ChannelTypes a proper enum

* Use createEnum

Co-authored-by: izexi <43889168+izexi@users.noreply.github.com>

* chore: remove unused code from Constants

* refactor(StageChannel): remove unnecessary getters

* chore: update typings

* refactor: introduce BaseGuildVoiceChannel class

* refactor(VoiceChannel): reduce code duplication

* feat: export BaseGuildVoiceChannel

* chore: update typings

* docs: fix typos

* refactor: move setRTCRegion to BaseGuildVoiceChannel

* feat(VoiceState): remove permission checks

* chore: update typings

* Apply suggestions from code review

Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com>
Co-authored-by: Jan <66554238+vaporox@users.noreply.github.com>

* chore: update esm exports and typings

* Update src/structures/VoiceState.js

Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>

Co-authored-by: Advaith <advaithj1@gmail.com>
Co-authored-by: BannerBomb <BannerBomb55@gmail.com>
Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com>
Co-authored-by: Jan <66554238+vaporox@users.noreply.github.com>
Co-authored-by: izexi <43889168+izexi@users.noreply.github.com>
Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>

src/structures/BaseGuildVoiceChannel.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const GuildChannel = require('./GuildChannel');
+const Collection = require('../util/Collection');
+const Permissions = require('../util/Permissions');
+
+/**
+ * Represents a voice-based guild channel on Discord.
+ * @extends {GuildChannel}
+ */
+class BaseGuildVoiceChannel extends GuildChannel {
+  _patch(data) {
+    super._patch(data);
+
+    /**
+     * The RTC region for this voice-based channel. This region is automatically selected if `null`.
+     * @type {?string}
+     */
+    this.rtcRegion = data.rtc_region;
+
+    /**
+     * The bitrate of this voice-based channel
+     * @type {number}
+     */
+    this.bitrate = data.bitrate;
+
+    /**
+     * The maximum amount of users allowed in this channel.
+     * @type {number}
+     */
+    this.userLimit = data.user_limit;
+  }
+
+  /**
+   * The members in this voice-based channel
+   * @type {Collection<Snowflake, GuildMember>}
+   * @readonly
+   */
+  get members() {
+    const coll = new Collection();
+    for (const state of this.guild.voiceStates.cache.values()) {
+      if (state.channelID === this.id && state.member) {
+        coll.set(state.id, state.member);
+      }
+    }
+    return coll;
+  }
+
+  /**
+   * Checks if the voice-based channel is full
+   * @type {boolean}
+   * @readonly
+   */
+  get full() {
+    return this.userLimit > 0 && this.members.size >= this.userLimit;
+  }
+
+  /**
+   * Whether the channel is joinable by the client user
+   * @type {boolean}
+   * @readonly
+   */
+  get joinable() {
+    if (!this.viewable) return false;
+    if (!this.permissionsFor(this.client.user).has(Permissions.FLAGS.CONNECT, false)) return false;
+    return true;
+  }
+
+  /**
+   * Attempts to join this voice-based channel.
+   * @returns {Promise<VoiceConnection>}
+   * @example
+   * // Join a voice-based channel
+   * channel.join()
+   *   .then(connection => console.log('Connected!'))
+   *   .catch(console.error);
+   */
+  join() {
+    return this.client.voice.joinChannel(this);
+  }
+
+  /**
+   * Leaves this voice-based channel.
+   * @example
+   * // Leave a voice-based channel
+   * channel.leave();
+   */
+  leave() {
+    const connection = this.client.voice.connections.get(this.guild.id);
+    if (connection?.channel.id === this.id) connection.disconnect();
+  }
+
+  /**
+   * Sets the RTC region of the channel.
+   * @param {?string} region The new region of the channel. Set to `null` to remove a specific region for the channel
+   * @returns {Promise<BaseGuildVoiceChannel>}
+   * @example
+   * // Set the RTC region to europe
+   * channel.setRTCRegion('europe');
+   * @example
+   * // Remove a fixed region for this channel - let Discord decide automatically
+   * channel.setRTCRegion(null);
+   */
+  setRTCRegion(region) {
+    return this.edit({ rtcRegion: region });
+  }
+}
+
+module.exports = BaseGuildVoiceChannel;

src/structures/Channel.js

@@ -13,7 +13,7 @@ class Channel extends Base {
   constructor(client, data) {
     super(client);
 
-    const type = Object.keys(ChannelTypes)[data.type];
+    const type = ChannelTypes[data.type];
     /**
      * The type of the channel, either:
      * * `dm` - a DM channel
@@ -22,6 +22,7 @@ class Channel extends Base {
      * * `category` - a guild category channel
      * * `news` - a guild news channel
      * * `store` - a guild store channel
+     * * `stage` - a guild stage channel
      * * `unknown` - a generic channel of unknown type, could be Channel or GuildChannel
      * @type {string}
      */
@@ -146,6 +147,11 @@ class Channel extends Base {
             channel = new StoreChannel(guild, data);
             break;
           }
+          case ChannelTypes.STAGE: {
+            const StageChannel = Structures.get('StageChannel');
+            channel = new StageChannel(guild, data);
+            break;
+          }
         }
         if (channel) guild.channels.cache.set(channel.id, channel);
       }

src/structures/GuildChannel.js

@@ -18,6 +18,7 @@ const Util = require('../util/Util');
  * - {@link CategoryChannel}
  * - {@link NewsChannel}
  * - {@link StoreChannel}
+ * - {@link StageChannel}
  * @extends {Channel}
  * @abstract
  */
@@ -319,6 +320,7 @@ class GuildChannel extends Channel {
    * @property {OverwriteResolvable[]|Collection<Snowflake, OverwriteResolvable>} [permissionOverwrites]
    * Permission overwrites for the channel
    * @property {number} [rateLimitPerUser] The ratelimit per user for the channel in seconds
+   * @property {?string} [rtcRegion] The RTC region of the channel
    */
 
   /**
@@ -374,6 +376,7 @@ class GuildChannel extends Channel {
         nsfw: data.nsfw,
         bitrate: data.bitrate || this.bitrate,
         user_limit: typeof data.userLimit !== 'undefined' ? data.userLimit : this.userLimit,
+        rtc_region: typeof data.rtcRegion !== 'undefined' ? data.rtcRegion : this.rtcRegion,
         parent_id: data.parentID,
         lock_permissions: data.lockPermissions,
         rate_limit_per_user: data.rateLimitPerUser,
@@ -594,7 +597,7 @@ class GuildChannel extends Channel {
    */
   get manageable() {
     if (this.client.user.id === this.guild.ownerID) return true;
-    if (this.type === 'voice') {
+    if (this.type === 'voice' || this.type === 'stage') {
       if (!this.permissionsFor(this.client.user).has(Permissions.FLAGS.CONNECT, false)) {
         return false;
       }

src/structures/StageChannel.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const BaseGuildVoiceChannel = require('./BaseGuildVoiceChannel');
+
+/**
+ * Represents a guild stage channel on Discord.
+ * @extends {BaseGuildVoiceChannel}
+ */
+class StageChannel extends BaseGuildVoiceChannel {
+  _patch(data) {
+    super._patch(data);
+
+    /**
+     * The topic of the stage channel
+     * @type {?string}
+     */
+    this.topic = data.topic;
+  }
+
+  /**
+   * Sets the RTC region of the channel.
+   * @name StageChannel#setRTCRegion
+   * @param {?string} region The new region of the channel. Set to `null` to remove a specific region for the channel
+   * @returns {Promise<StageChannel>}
+   * @example
+   * // Set the RTC region to europe
+   * stageChannel.setRTCRegion('europe');
+   * @example
+   * // Remove a fixed region for this channel - let Discord decide automatically
+   * stageChannel.setRTCRegion(null);
+   */
+}
+
+module.exports = StageChannel;

src/structures/VoiceChannel.js

@@ -1,53 +1,13 @@
 'use strict';
 
-const GuildChannel = require('./GuildChannel');
-const Collection = require('../util/Collection');
+const BaseGuildVoiceChannel = require('./BaseGuildVoiceChannel');
 const Permissions = require('../util/Permissions');
 
 /**
  * Represents a guild voice channel on Discord.
- * @extends {GuildChannel}
+ * @extends {BaseGuildVoiceChannel}
  */
-class VoiceChannel extends GuildChannel {
-  _patch(data) {
-    super._patch(data);
-    /**
-     * The bitrate of this voice channel
-     * @type {number}
-     */
-    this.bitrate = data.bitrate;
-
-    /**
-     * The maximum amount of users allowed in this channel - 0 means unlimited.
-     * @type {number}
-     */
-    this.userLimit = data.user_limit;
-  }
-
-  /**
-   * The members in this voice channel
-   * @type {Collection<Snowflake, GuildMember>}
-   * @readonly
-   */
-  get members() {
-    const coll = new Collection();
-    for (const state of this.guild.voiceStates.cache.values()) {
-      if (state.channelID === this.id && state.member) {
-        coll.set(state.id, state.member);
-      }
-    }
-    return coll;
-  }
-
-  /**
-   * Checks if the voice channel is full
-   * @type {boolean}
-   * @readonly
-   */
-  get full() {
-    return this.userLimit > 0 && this.members.size >= this.userLimit;
-  }
-
+class VoiceChannel extends BaseGuildVoiceChannel {
   /**
    * Whether the channel is deletable by the client user
    * @type {boolean}
@@ -72,8 +32,7 @@ class VoiceChannel extends GuildChannel {
    * @readonly
    */
   get joinable() {
-    if (!this.viewable) return false;
-    if (!this.permissionsFor(this.client.user).has(Permissions.FLAGS.CONNECT, false)) return false;
+    if (!super.joinable) return false;
     if (this.full && !this.permissionsFor(this.client.user).has(Permissions.FLAGS.MOVE_MEMBERS, false)) return false;
     return true;
   }
@@ -118,28 +77,17 @@ class VoiceChannel extends GuildChannel {
   }
 
   /**
-   * Attempts to join this voice channel.
-   * @returns {Promise<VoiceConnection>}
+   * Sets the RTC region of the channel.
+   * @name VoiceChannel#setRTCRegion
+   * @param {?string} region The new region of the channel. Set to `null` to remove a specific region for the channel
+   * @returns {Promise<VoiceChannel>}
    * @example
-   * // Join a voice channel
-   * voiceChannel.join()
-   *   .then(connection => console.log('Connected!'))
-   *   .catch(console.error);
-   */
-  join() {
-    return this.client.voice.joinChannel(this);
-  }
-
-  /**
-   * Leaves this voice channel.
+   * // Set the RTC region to europe
+   * voiceChannel.setRTCRegion('europe');
    * @example
-   * // Leave a voice channel
-   * voiceChannel.leave();
+   * // Remove a fixed region for this channel - let Discord decide automatically
+   * voiceChannel.setRTCRegion(null);
    */
-  leave() {
-    const connection = this.client.voice.connections.get(this.guild.id);
-    if (connection && connection.channel.id === this.id) connection.disconnect();
-  }
 }
 
 module.exports = VoiceChannel;

src/structures/VoiceState.js

@@ -63,10 +63,22 @@ class VoiceState extends Base {
      */
     this.streaming = data.self_stream || false;
     /**
-     * The ID of the voice channel that this member is in
+     * The ID of the voice or stage channel that this member is in
      * @type {?Snowflake}
      */
     this.channelID = data.channel_id || null;
+    /**
+     * Whether this member is suppressed from speaking. This property is specific to stage channels only.
+     * @type {boolean}
+     */
+    this.suppress = data.suppress;
+    /**
+     * The time at which the member requested to speak. This property is specific to stage channels only.
+     * @type {?number}
+     */
+    this.requestToSpeakTimestamp = data.request_to_speak_timestamp
+      ? new Date(data.request_to_speak_timestamp).getTime()
+      : null;
     return this;
   }
 
@@ -81,7 +93,7 @@ class VoiceState extends Base {
 
   /**
    * The channel that the member is connected to
-   * @type {?VoiceChannel}
+   * @type {?VoiceChannel|StageChannel}
    * @readonly
    */
   get channel() {
@@ -118,7 +130,7 @@ class VoiceState extends Base {
 
   /**
    * Whether this member is currently speaking. A boolean if the information is available (aka
-   * the bot is connected to any voice channel in the guild), otherwise this is null
+   * the bot is connected to any voice channel or stage channel in the guild), otherwise this is `null`
    * @type {?boolean}
    * @readonly
    */
@@ -147,7 +159,7 @@ class VoiceState extends Base {
   }
 
   /**
-   * Kicks the member from the voice channel.
+   * Kicks the member from the channel.
    * @param {string} [reason] Reason for kicking member from the channel
    * @returns {Promise<GuildMember>}
    */
@@ -196,6 +208,63 @@ class VoiceState extends Base {
     return true;
   }
 
+  /**
+   * Toggles the request to speak in the channel.
+   * Only applicable for stage channels and for the client's own voice state.
+   * @param {boolean} request Whether or not the client is requesting to become a speaker.
+   * @example
+   * // Making the client request to speak in a stage channel (raise its hand)
+   * guild.me.voice.setRequestToSpeak(true);
+   * @example
+   * // Making the client cancel a request to speak
+   * guild.me.voice.setRequestToSpeak(false);
+   */
+  async setRequestToSpeak(request) {
+    const channel = this.channel;
+    if (channel?.type !== 'stage') throw new Error('VOICE_NOT_STAGE_CHANNEL');
+
+    if (this.client.user.id !== this.id) throw new Error('VOICE_STATE_NOT_OWN');
+
+    await this.client.api.guilds(this.guild.id, 'voice-states', '@me').patch({
+      data: {
+        channel_id: this.channelID,
+        request_to_speak_timestamp: request ? new Date().toISOString() : null,
+      },
+    });
+  }
+
+  /**
+   * Suppress/unsuppress the user. Only applicable for stage channels.
+   * @param {boolean} suppressed - Whether or not the user should be suppressed.
+   * @example
+   * // Making the client a speaker
+   * guild.me.voice.setSuppressed(false);
+   * @example
+   * // Making the client an audience member
+   * guild.me.voice.setSuppressed(true);
+   * @example
+   * // Inviting another user to speak
+   * voiceState.setSuppressed(false);
+   * @example
+   * // Moving another user to the audience, or cancelling their invite to speak
+   * voiceState.setSuppressed(true);
+   */
+  async setSuppressed(suppressed) {
+    if (typeof suppressed !== 'boolean') throw new TypeError('VOICE_STATE_INVALID_TYPE', 'suppressed');
+
+    const channel = this.channel;
+    if (channel?.type !== 'stage') throw new Error('VOICE_NOT_STAGE_CHANNEL');
+
+    const target = this.client.user.id === this.id ? '@me' : this.id;
+
+    await this.client.api.guilds(this.guild.id, 'voice-states', target).patch({
+      data: {
+        channel_id: this.channelID,
+        suppress: suppressed,
+      },
+    });
+  }
+
   toJSON() {
     return super.toJSON({
       id: true,