feat(GuildBanManager): Add bulkCreate() method

#10182 backport
And https://github.com/aiko-chan-ai/discord.js-selfbot-v13/discussions/1219 :?

src/errors/Messages.js

@@ -178,6 +178,7 @@ const Messages = {
   SLASH_COMMAND_SUB_COMMAND_INVALID: n => `${n} is not a valid sub command`,
   INTERACTION_FAILED: 'No responsed from Application Command',
   USER_NOT_STREAMING: 'User is not streaming',
+  BULK_BAN_USERS_OPTION_EMPTY: 'Option "users" array or collection is empty',
 
   // Djs v12
   VOICE_INVALID_HEARTBEAT: 'Tried to set voice heartbeat but no valid interval was specified.',

src/managers/GuildBanManager.js

@@ -199,6 +199,51 @@ class GuildBanManager extends CachedManager {
     await this.client.api.guilds(this.guild.id).bans(id).delete({ reason });
     return this.client.users.resolve(user);
   }
+
+  /**
+   * Options used for bulk banning users from a guild.
+   * @typedef {Object} BulkBanOptions
+   * @property {number} [deleteMessageSeconds] Number of seconds of messages to delete,
+   * must be between 0 and 604800 (7 days), inclusive
+   * @property {string} [reason] The reason for the bans
+   */
+
+  /**
+   * Result of bulk banning users from a guild.
+   * @typedef {Object} BulkBanResult
+   * @property {Snowflake[]} bannedUsers IDs of the banned users
+   * @property {Snowflake[]} failedUsers IDs of the users that could not be banned or were already banned
+   */
+
+  /**
+   * Bulk ban users from a guild, and optionally delete previous messages sent by them.
+   * @param {Collection<Snowflake, UserResolvable>|UserResolvable[]} users The users to ban
+   * @param {BulkBanOptions} [options] The options for bulk banning users
+   * @returns {Promise<BulkBanResult>} Returns an object with `bannedUsers` key containing the IDs of the banned users
+   * and the key `failedUsers` with the IDs that could not be banned or were already banned.
+   * @example
+   * // Bulk ban users by ids (or with user/guild member objects) and delete all their messages from the past 7 days
+   * guild.bans.bulkCreate(['84484653687267328'], { deleteMessageSeconds: 7 * 24 * 60 * 60 })
+   *   .then(result => {
+   *     console.log(`Banned ${result.bannedUsers.length} users, failed to ban ${result.failedUsers.length} users.`)
+   *   })
+   *   .catch(console.error);
+   */
+  async bulkCreate(users, options = {}) {
+    if (!users || !(Array.isArray(users) || users instanceof Collection)) {
+      throw new TypeError('INVALID_TYPE', 'users', 'Array or Collection of UserResolvable', true);
+    }
+    if (typeof options !== 'object') throw new TypeError('INVALID_TYPE', 'options', 'object', true);
+
+    const userIds = users.map(user => this.client.users.resolveId(user));
+    if (userIds.length === 0) throw new Error('BULK_BAN_USERS_OPTION_EMPTY');
+
+    const result = await this.client.api.guilds(this.guild.id)['bulk-ban'].post({
+      data: { delete_message_days: options.deleteMessageSeconds, user_ids: userIds },
+      reason: options.reason,
+    });
+    return { bannedUsers: result.banned_users, failedUsers: result.failed_users };
+  }
 }
 
 module.exports = GuildBanManager;

src/managers/GuildMemberManager.js

@@ -592,6 +592,25 @@ class GuildMemberManager extends CachedManager {
       this.client.on(Events.GUILD_MEMBERS_CHUNK, handler);
     });
   }
+
+  /**
+   * Bulk ban users from a guild, and optionally delete previous messages sent by them.
+   * @param {Collection<Snowflake, UserResolvable>|UserResolvable[]} users The users to ban
+   * @param {BulkBanOptions} [options] The options for bulk banning users
+   * @returns {Promise<BulkBanResult>} Returns an object with `bannedUsers` key containing the IDs of the banned users
+   * and the key `failedUsers` with the IDs that could not be banned or were already banned.
+   * Internally calls the GuildBanManager#bulkCreate method.
+   * @example
+   * // Bulk ban users by ids (or with user/guild member objects) and delete all their messages from the past 7 days
+   * guild.members.bulkBan(['84484653687267328'], { deleteMessageSeconds: 7 * 24 * 60 * 60 })
+   *   .then(result => {
+   *     console.log(`Banned ${result.bannedUsers.length} users, failed to ban ${result.failedUsers.length} users.`)
+   *   })
+   *   .catch(console.error);
+   */
+  bulkBan(users, options = {}) {
+    return this.guild.bans.bulkCreate(users, options);
+  }
 }
 
 module.exports = GuildMemberManager;

typings/index.d.ts

@@ -4302,6 +4302,10 @@ export class GuildMemberManager extends CachedManager<Snowflake, GuildMember, Gu
   public search(options: GuildSearchMembersOptions): Promise<Collection<Snowflake, GuildMember>>;
   public unban(user: UserResolvable, reason?: string): Promise<User | null>;
   public fetchByMemberSafety(timeout?: number): Promise<Collection<Snowflake, GuildMember>>;
+  public bulkBan(
+    users: Collection<Snowflake, UserResolvable> | readonly UserResolvable[],
+    options?: BulkBanOptions,
+  ): Promise<BulkBanResult>;
 }
 
 export class GuildBanManager extends CachedManager<Snowflake, GuildBan, GuildBanResolvable> {
@@ -4311,6 +4315,10 @@ export class GuildBanManager extends CachedManager<Snowflake, GuildBan, GuildBan
   public fetch(options: UserResolvable | FetchBanOptions): Promise<GuildBan>;
   public fetch(options?: FetchBansOptions): Promise<Collection<Snowflake, GuildBan>>;
   public remove(user: UserResolvable, reason?: string): Promise<User | null>;
+  public bulkCreate(
+    users: Collection<Snowflake, UserResolvable> | readonly UserResolvable[],
+    options?: BulkBanOptions,
+  ): Promise<BulkBanResult>;
 }
 
 export class GuildInviteManager extends DataManager<string, Invite, InviteResolvable> {
@@ -5272,6 +5280,13 @@ export interface BanOptions {
   reason?: string;
 }
 
+export interface BulkBanOptions extends Omit<BanOptions, 'deleteMessageDays'> {}
+
+export interface BulkBanResult {
+  bannedUsers: readonly Snowflake[];
+  failedUsers: readonly Snowflake[];
+}
+
 export type Base64Resolvable = Buffer | Base64String;
 
 export type Base64String = string;