Add bulk ban (#3543)

packages/bot/src/helpers.ts

@@ -35,6 +35,7 @@ import type {
   CreateGuild,
   CreateGuildApplicationCommandOptions,
   CreateGuildBan,
+  CreateGuildBulkBan,
   CreateGuildChannel,
   CreateGuildEmoji,
   CreateGuildFromTemplate,
@@ -535,6 +536,14 @@ export function createBotHelpers(bot: Bot): BotHelpers {
         bot.transformers.member(bot, snakelize(res), guildId, bot.transformers.snowflake(res.user.id)),
       )
     },
+    bulkBanMembers: async (guildId, options, reason) => {
+      const res = await bot.rest.bulkBanMembers(guildId, options, reason)
+
+      return {
+        bannedUsers: res.bannedUsers.map((x) => bot.transformers.snowflake(x)),
+        failedUsers: res.failedUsers.map((x) => bot.transformers.snowflake(x)),
+      }
+    },
     // All useless void return functions here
     addReaction: async (channelId, messageId, reaction) => {
       return await bot.rest.addReaction(channelId, messageId, reaction)
@@ -872,6 +881,7 @@ export interface BotHelpers {
   getMembers: (guildId: BigString, options: ListGuildMembers) => Promise<Member[]>
   pruneMembers: (guildId: BigString, options: BeginGuildPrune, reason?: string) => Promise<{ pruned: number | null }>
   searchMembers: (guildId: BigString, query: string, options?: Omit<SearchMembers, 'query'>) => Promise<Member[]>
+  bulkBanMembers: (guildId: BigString, options: CreateGuildBulkBan, reason?: string) => Promise<{ bannedUsers: bigint[]; failedUsers: bigint[] }>
   // functions return Void so dont need any special handling
   addReaction: (channelId: BigString, messageId: BigString, reaction: string) => Promise<void>
   addReactions: (channelId: BigString, messageId: BigString, reactions: string[], ordered?: boolean) => Promise<void>

packages/rest/src/manager.ts

@@ -17,6 +17,7 @@ import {
   type DiscordAuditLog,
   type DiscordAutoModerationRule,
   type DiscordBan,
+  type DiscordBulkBan,
   type DiscordChannel,
   type DiscordConnection,
   type DiscordCurrentAuthorization,
@@ -1359,6 +1360,10 @@ export function createRestManager(options: CreateRestManagerOptions): RestManage
       await rest.put<void>(rest.routes.guilds.members.ban(guildId, userId), { body, reason })
     },
 
+    async bulkBanMembers(guildId, options, reason) {
+      return await rest.post<DiscordBulkBan>(rest.routes.guilds.members.bulkBan(guildId), { body: options, reason })
+    },
+
     async editBotMember(guildId, body, reason) {
       return await rest.patch<DiscordMember>(rest.routes.guilds.members.bot(guildId), { body, reason })
     },

packages/rest/src/routes.ts

@@ -372,6 +372,9 @@ export function createRoutes(): RestRoutes {
 
           return url
         },
+        bulkBan: (guildId) => {
+          return `/guilds/${guildId}/bulk-ban`
+        },
         bot: (guildId) => {
           return `/guilds/${guildId}/members/@me`
         },

packages/rest/src/types.ts

@@ -64,6 +64,7 @@ import type {
   CreateGuild,
   CreateGuildApplicationCommandOptions,
   CreateGuildBan,
+  CreateGuildBulkBan,
   CreateGuildChannel,
   CreateGuildEmoji,
   CreateGuildFromTemplate,
@@ -74,6 +75,7 @@ import type {
   CreateStageInstance,
   CreateTemplate,
   DeleteWebhookMessageOptions,
+  DiscordBulkBan,
   EditApplication,
   EditAutoModerationRuleOptions,
   EditBotMemberOptions,
@@ -2620,8 +2622,8 @@ export interface RestManager {
    *
    * @param guildId - The ID of the guild to ban the user from.
    * @param userId - The ID of the user to ban from the guild.
-   * @param {string} [reason] - An optional reason for the action, to be included in the audit log.
    * @param options - The parameters for the creation of the ban.
+   * @param {string} [reason] - An optional reason for the action, to be included in the audit log.
    *
    * @remarks
    * Requires the `BAN_MEMBERS` permission.
@@ -2631,6 +2633,23 @@ export interface RestManager {
    * @see {@link https://discord.com/developers/docs/resources/guild#create-guild-ban}
    */
   banMember: (guildId: BigString, userId: BigString, options?: CreateGuildBan, reason?: string) => Promise<void>
+  /**
+   * Bans up to 200 users from a guild.
+   *
+   * @param guildId - The ID of the guild to ban the users from.
+   * @param options - The users to ban and the other options for the ban.
+   * @param {string} [reason] - An optional reason for the action, to be included in the audit log.
+   *
+   * @remarks
+   * Requires the `BAN_MEMBERS` and `MANAGE_GUILD` permissions.
+   *
+   * If all provided users fail to be banned, discord will respond with an error (code: `500000: Failed to ban users`)
+   *
+   * Fires as many _Guild Ban Add_ gateway events as many user where banned.
+   *
+   * @see {@link https://discord.com/developers/docs/resources/guild#bulk-guild-ban}
+   */
+  bulkBanMembers: (guildId: BigString, options: CreateGuildBulkBan, reason?: string) => Promise<Camelize<DiscordBulkBan>>
   /**
    * Edits the nickname of the bot user.
    *

packages/rest/src/typings/routes.ts

@@ -166,6 +166,8 @@ export interface RestRoutes {
       ban: (guildId: BigString, userId: BigString) => string
       /** Route for handling non-specific bans in a guild. */
       bans: (guildId: BigString, options?: GetBans) => string
+      /** Route for bulk-banning members. */
+      bulkBan: (guildId: BigString) => string
       /** Route for handling a the bot guild member. */
       bot: (guildId: BigString) => string
       /** Route for handling a specific guild member. */

packages/types/src/camel.ts

@@ -28,6 +28,7 @@ import type {
   DiscordAutoModerationRule,
   DiscordAutoModerationRuleTriggerMetadata,
   DiscordBan,
+  DiscordBulkBan,
   DiscordButtonComponent,
   DiscordChannel,
   DiscordChannelMention,
@@ -324,3 +325,4 @@ export interface CamelizedDiscordGuildOnboardingPrompt extends Camelize<DiscordG
 export interface CamelizedDiscordGuildOnboardingOption extends Camelize<DiscordGuildOnboardingPromptOption> {}
 export interface CamelizedDiscordEntitlement extends Camelize<DiscordEntitlement> {}
 export interface CamelizedDiscordSku extends Camelize<DiscordSku> {}
+export interface CamelizedDiscordBulkBan extends Camelize<DiscordBulkBan> {}

packages/types/src/discord.ts

@@ -3129,3 +3129,11 @@ export enum DiscordMessageFlag {
   /** This message is a voice message */
   IsVoiceMessage = 1 << 13,
 }
+
+/** https://discord.com/developers/docs/resources/guild#bulk-guild-ban */
+export interface DiscordBulkBan {
+  /** list of user ids, that were successfully banned */
+  banned_users: string[]
+  /** list of user ids, that were not banned */
+  failed_users: string[]
+}

packages/types/src/discordeno.ts

@@ -1180,7 +1180,23 @@ export interface ModifyGuildTemplate {
 
 /** https://discord.com/developers/docs/resources/guild#create-guild-ban */
 export interface CreateGuildBan {
-  /** Number of seconds to delete messages for, between 0 and 604800 (7 days) */
+  /**
+   * Number of seconds to delete messages for, between 0 and 604800 (7 days)
+   *
+   * @default 0
+   */
+  deleteMessageSeconds?: number
+}
+
+/** https://discord.com/developers/docs/resources/guild#bulk-guild-ban-json-params */
+export interface CreateGuildBulkBan {
+  /** list of user ids to ban (max 200) */
+  userIds: BigString[]
+  /**
+   * Number of seconds to delete messages for, between 0 and 604800 (7 days)
+   *
+   * @default 0
+   */
   deleteMessageSeconds?: number
 }