feat(GuildMember): Add timeouts

src/managers/GuildMemberManager.js

@@ -223,6 +223,19 @@ class GuildMemberManager extends CachedManager {
     return data.reduce((col, member) => col.set(member.user.id, this._add(member, cache)), new Collection());
   }
 
+  /**
+   * The data for editing a guild member.
+   * @typedef {Object} GuildMemberEditData
+   * @property {?string} [nick] The nickname to set for the member
+   * @property {Collection<Snowflake, Role>|RoleResolvable[]} [roles] The roles or role ids to apply
+   * @property {boolean} [mute] Whether or not the member should be muted
+   * @property {boolean} [deaf] Whether or not the member should be deafened
+   * @property {GuildVoiceChannelResolvable|null} [channel] Channel to move the member to
+   * (if they are connected to voice), or `null` if you want to disconnect them from voice
+   * @property {Date|number|null} [communicationDisabledUntil] The date, timestamp or time in seconds
+   * for the member's communication to be disabled until. Provide `null` to remove the timeout.
+   */
+
   /**
    * Edits a member of the guild.
    * <info>The user must be a member of the guild</info>
@@ -249,6 +262,24 @@ class GuildMemberManager extends CachedManager {
       _data.channel = undefined;
     }
     _data.roles &&= _data.roles.map(role => (role instanceof Role ? role.id : role));
+
+    if (typeof _data.communicationDisabledUntil !== 'undefined') {
+      if (_data.communicationDisabledUntil === null) {
+        _data.communication_disabled_until = null;
+      } else {
+        let date = new Date(_data.communicationDisabledUntil);
+        if (date.getUTCFullYear() <= 2015) {
+          // Assume seconds
+          const dateFromSeconds = new Date();
+          date = new Date(
+            dateFromSeconds.setUTCSeconds(dateFromSeconds.getUTCSeconds() + _data.communicationDisabledUntil),
+          );
+        }
+
+        _data.communication_disabled_until = date.toISOString();
+      }
+    }
+
     let endpoint = this.client.api.guilds(this.guild.id);
     if (id === this.client.user.id) {
       const keys = Object.keys(_data);

src/structures/GuildMember.js

@@ -53,6 +53,12 @@ class GuildMember extends Base {
      */
     this.pending = false;
 
+    /**
+     * The timestamp this member's timeout will be removed
+     * @type {?number}
+     */
+    this.communicationDisabledUntilTimestamp = null;
+
     this._roles = [];
     if (data) this._patch(data);
   }
@@ -82,6 +88,11 @@ class GuildMember extends Base {
     }
     if ('roles' in data) this._roles = data.roles;
     this.pending = data.pending ?? false;
+
+    if ('communication_disabled_until' in data) {
+      this.communicationDisabledUntilTimestamp =
+        data.communication_disabled_until === null ? null : new Date(data.communication_disabled_until).getTime();
+    }
   }
 
   _clone() {
@@ -159,6 +170,15 @@ class GuildMember extends Base {
     return this.joinedTimestamp ? new Date(this.joinedTimestamp) : null;
   }
 
+  /**
+   * The time this member's timeout will be removed
+   * @type {?Date}
+   * @readonly
+   */
+  get communicationDisabledUntil() {
+    return this.communicationDisabledUntilTimestamp ? new Date(this.communicationDisabledUntilTimestamp) : null;
+  }
+
   /**
    * The last time this member started boosting the guild
    * @type {?Date}
@@ -267,17 +287,6 @@ class GuildMember extends Base {
     return channel.permissionsFor(this);
   }
 
-  /**
-   * The data for editing a guild member.
-   * @typedef {Object} GuildMemberEditData
-   * @property {?string} [nick] The nickname to set for the member
-   * @property {Collection<Snowflake, Role>|RoleResolvable[]} [roles] The roles or role ids to apply
-   * @property {boolean} [mute] Whether or not the member should be muted
-   * @property {boolean} [deaf] Whether or not the member should be deafened
-   * @property {GuildVoiceChannelResolvable|null} [channel] Channel to move the member to
-   * (if they are connected to voice), or `null` if you want to disconnect them from voice
-   */
-
   /**
    * Edits this member.
    * @param {GuildMemberEditData} data The data to edit the member with
@@ -337,6 +346,22 @@ class GuildMember extends Base {
     return this.guild.members.ban(this, options);
   }
 
+  /**
+   * Timeouts this guild member.
+   * @param {Date|number|null} timeout The date, timestamp or time in seconds
+   * for the member's communication to be disabled until. Provide `null` to remove the timeout.
+   * @param {string} [reason] The reason for this timeout.
+   * @returns {Promise<GuildMember>}
+   * @example
+   * // Timeout a guild member for 5 minutes
+   * guildMember.timeout(300, 'They deserved it')
+   *   .then(console.log)
+   *   .catch(console.error);
+   */
+  timeout(timeout, reason) {
+    return this.edit({ communicationDisabledUntil: timeout }, reason);
+  }
+
   /**
    * Fetches this GuildMember.
    * @param {boolean} [force=true] Whether to skip the cache check and request the API
@@ -363,6 +388,7 @@ class GuildMember extends Base {
       this.nickname === member.nickname &&
       this.avatar === member.avatar &&
       this.pending === member.pending &&
+      this.communicationDisabledUntilTimestamp === member.communicationDisabledUntilTimestamp &&
       (this._roles === member._roles ||
         (this._roles.length === member._roles.length && this._roles.every((role, i) => role === member._roles[i])))
     );

src/util/Permissions.js

@@ -98,6 +98,7 @@ class Permissions extends BitField {
  * * `USE_EXTERNAL_STICKERS` (use stickers from different guilds)
  * * `SEND_MESSAGES_IN_THREADS`
  * * `START_EMBEDDED_ACTIVITIES`
+ * * `MODERATE_MEMBERS`
  * @type {Object<string, bigint>}
  * @see {@link https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags}
  */
@@ -144,6 +145,7 @@ Permissions.FLAGS = {
   USE_EXTERNAL_STICKERS: 1n << 37n,
   SEND_MESSAGES_IN_THREADS: 1n << 38n,
   START_EMBEDDED_ACTIVITIES: 1n << 39n,
+  MODERATE_MEMBERS: 1n << 40n,
 };
 
 /**

typings/index.d.ts

@@ -1069,6 +1069,8 @@ export class GuildMember extends PartialTextBasedChannel(Base) {
   public guild: Guild;
   public readonly id: Snowflake;
   public pending: boolean;
+  public readonly communicationDisabledUntil: Date | null;
+  public communicationDisabledUntilTimestamp: number | null;
   public readonly joinedAt: Date | null;
   public joinedTimestamp: number | null;
   public readonly kickable: boolean;
@@ -1084,6 +1086,7 @@ export class GuildMember extends PartialTextBasedChannel(Base) {
   public readonly voice: VoiceState;
   public avatarURL(options?: ImageURLOptions): string | null;
   public ban(options?: BanOptions): Promise<GuildMember>;
+  public timeout(timeout: number | null, reason?: string): Promise<GuildMember>;
   public fetch(force?: boolean): Promise<GuildMember>;
   public createDM(force?: boolean): Promise<DMChannel>;
   public deleteDM(): Promise<DMChannel>;
@@ -4481,6 +4484,7 @@ export interface GuildMemberEditData {
   mute?: boolean;
   deaf?: boolean;
   channel?: GuildVoiceChannelResolvable | null;
+  communicationDisabledUntil?: number | null;
 }
 
 export type GuildMemberResolvable = GuildMember | UserResolvable;
@@ -4971,7 +4975,8 @@ export type PermissionString =
   | 'CREATE_PRIVATE_THREADS'
   | 'USE_EXTERNAL_STICKERS'
   | 'SEND_MESSAGES_IN_THREADS'
-  | 'START_EMBEDDED_ACTIVITIES';
+  | 'START_EMBEDDED_ACTIVITIES'
+  | 'MODERATE MEMBERS';
 
 export type RecursiveArray<T> = ReadonlyArray<T | RecursiveArray<T>>;