feat(types/guild): add computePruneCount to PruneOptions (#605)

* fix(handlers/guild): rewrite and rename pruneMembers()

* remove breaking change

* Update src/api/handlers/guild.ts

* Update src/types/guild.ts

* Update src/types/guild.ts

* Update src/types/guild.ts

* Update src/api/handlers/guild.ts

* Update src/api/handlers/guild.ts

* Update src/api/handlers/guild.ts

* Update src/types/guild.ts

* Update src/types/guild.ts

* Update src/types/guild.ts

* Update src/api/handlers/guild.ts

* Update src/api/handlers/guild.ts

* Update src/api/handlers/guild.ts

* fmt

* fixes

* Update src/types/guild.ts

Co-authored-by: Skillz4Killz <23035000+Skillz4Killz@users.noreply.github.com>

* fmt

Co-authored-by: Skillz4Killz <23035000+Skillz4Killz@users.noreply.github.com>

src/api/handlers/guild.ts

@@ -529,9 +529,11 @@ export async function swapRoles(guildID: string, rolePositons: PositionSwap) {
 }
 
 /** Check how many members would be removed from the server in a prune operation. Requires the KICK_MEMBERS permission */
-export async function getPruneCount(guildID: string, options: PruneOptions) {
+export async function getPruneCount(guildID: string, options?: PruneOptions) {
-  if (options.days < 1) throw new Error(Errors.PRUNE_MIN_DAYS);
+  if (options?.days && options.days < 1) throw new Error(Errors.PRUNE_MIN_DAYS);
-  if (options.days > 30) throw new Error(Errors.PRUNE_MAX_DAYS);
+  if (options?.days && options.days > 30) {
+    throw new Error(Errors.PRUNE_MAX_DAYS);
+  }
 
   const hasPerm = await botHasPermission(guildID, ["KICK_MEMBERS"]);
   if (!hasPerm) {
@@ -540,16 +542,23 @@ export async function getPruneCount(guildID: string, options: PruneOptions) {
 
   const result = await RequestManager.get(
     endpoints.GUILD_PRUNE(guildID),
-    { ...options, include_roles: options.roles.join(",") },
+    { ...options, include_roles: options?.roles?.join(",") },
   ) as PrunePayload;
 
   return result.pruned;
 }
 
-/** Begin pruning all members in the given time period */
+/**
-export async function pruneMembers(guildID: string, options: PruneOptions) {
+ * Begin a prune operation. Requires the KICK_MEMBERS permission. Returns an object with one 'pruned' key indicating the number of members that were removed in the prune operation. For large guilds it's recommended to set the computePruneCount option to false, forcing 'pruned' to null. Fires multiple Guild Member Remove Gateway events.
-  if (options.days < 1) throw new Error(Errors.PRUNE_MIN_DAYS);
+ * 
-  if (options.days > 30) throw new Error(Errors.PRUNE_MAX_DAYS);
+ * By default, prune will not remove users with roles. You can optionally include specific roles in your prune by providing the roles (resolved to include_roles internally) parameter. Any inactive user that has a subset of the provided role(s) will be included in the prune and users with additional roles will not.
+ */
+export async function pruneMembers(
+  guildID: string,
+  { roles, computePruneCount, ...options }: PruneOptions,
+) {
+  if (options.days && options.days < 1) throw new Error(Errors.PRUNE_MIN_DAYS);
+  if (options.days && options.days > 30) throw new Error(Errors.PRUNE_MAX_DAYS);
 
   const hasPerm = await botHasPermission(guildID, ["KICK_MEMBERS"]);
   if (!hasPerm) {
@@ -558,7 +567,11 @@ export async function pruneMembers(guildID: string, options: PruneOptions) {
 
   const result = await RequestManager.post(
     endpoints.GUILD_PRUNE(guildID),
-    { ...options, include_roles: options.roles.join(",") },
+    {
+      ...options,
+      compute_prune_count: computePruneCount,
+      include_roles: roles,
+    },
   );
 
   return result;

src/types/guild.ts

@@ -547,10 +547,42 @@ export interface PrunePayload {
 }
 
 export interface PruneOptions {
-  /** number of days to count prune for (1 - 30). Defaults to 7 days. */
+  /** Number of days to prune (1-30). Default: 7 */
-  days: number;
+  days?:
-  /** Include members with these role ids */
+    | 1
-  roles: string[];
+    | 2
+    | 3
+    | 4
+    | 5
+    | 6
+    | 7
+    | 8
+    | 9
+    | 10
+    | 11
+    | 12
+    | 13
+    | 14
+    | 15
+    | 16
+    | 17
+    | 18
+    | 19
+    | 20
+    | 21
+    | 22
+    | 23
+    | 24
+    | 25
+    | 26
+    | 27
+    | 28
+    | 29
+    | 30;
+  /** Whether 'pruned' is returned, discouraged for large guilds. Default: true */
+  computePruneCount?: boolean;
+  /** Role(s) to include */
+  roles?: string[];
 }
 
 export interface VoiceState {