feat(Guild): add fetchBan and withReasons to fetchBans (#3170)

* add Guild#fetchBan() & backport BanInfo

* and the typings

* requested changes

* typings overloads

Co-Authored-By: izexi <43889168+izexi@users.noreply.github.com>

* nullable reason typings

Co-Authored-By: izexi <43889168+izexi@users.noreply.github.com>

src/client/rest/RESTMethods.js

@@ -631,6 +631,14 @@ class RESTMethods {
     });
   }
 
+  getGuildBan(guild, user) {
+    const id = this.client.resolver.resolveUserID(user);
+    return this.rest.makeRequest('get', `${Endpoints.Guild(guild).bans}/${id}`, true).then(ban => ({
+      reason: ban.reason,
+      user: this.client.dataManager.newUser(ban.user),
+    }));
+  }
+
   getGuildBans(guild) {
     return this.rest.makeRequest('get', Endpoints.Guild(guild).bans, true).then(bans =>
       bans.reduce((collection, ban) => {

src/structures/Guild.js

@@ -468,16 +468,39 @@ class Guild {
     return this.client.resolver.resolveGuildMember(this, user);
   }
 
+  /**
+   * An object containing information about a guild member's ban.
+   * @typedef {Object} BanInfo
+   * @property {User} user User that was banned
+   * @property {?string} reason Reason the user was banned
+   */
+
+  /**
+   * Fetch a ban for a user.
+   * @returns {Promise<BanInfo>}
+   * @param {UserResolvable} user The user to fetch the ban for
+   * @example
+   * // Get ban
+   * guild.fetchBan(message.author)
+   *   .then(({ user, reason }) => console.log(`${user.tag} was banned for the reason: ${reason}.`))
+   *   .catch(console.error);
+   */
+  fetchBan(user) {
+    return this.client.rest.methods.getGuildBan(this, user);
+  }
+
   /**
    * Fetch a collection of banned users in this guild.
-   * @returns {Promise<Collection<Snowflake, User>>}
+   * @returns {Promise<Collection<Snowflake, User|BanInfo>>}
+   * @param {boolean} [withReasons=false] Whether or not to include the ban reason(s)
    * @example
    * // Fetch bans in guild
    * guild.fetchBans()
    *   .then(bans => console.log(`This guild has ${bans.size} bans`))
    *   .catch(console.error);
    */
-  fetchBans() {
+  fetchBans(withReasons = false) {
+    if (withReasons) return this.client.rest.methods.getGuildBans(this);
     return this.client.rest.methods.getGuildBans(this)
       .then(bans => {
         const users = new Collection();

typings/index.d.ts

@@ -533,7 +533,10 @@ declare module 'discord.js' {
 		public edit(data: GuildEditData, reason?: string): Promise<Guild>;
 		public equals(guild: Guild): boolean;
 		public fetchAuditLogs(options?: GuildAuditLogsFetchOptions): Promise<GuildAuditLogs>;
-		public fetchBans(): Promise<Collection<Snowflake, User>>;
+		public fetchBan(user: UserResolvable): Promise<BanInfo>;
+		public fetchBans(withReasons?: false): Promise<Collection<Snowflake, User>>;
+		public fetchBans(withReasons: true): Promise<Collection<Snowflake, BanInfo>>;
+		public fetchBans(withReasons: boolean): Promise<Collection<Snowflake, BanInfo | User>>;
 		public fetchEmbed(): Promise<GuildEmbedData>;
 		public fetchInvites(): Promise<Collection<Snowflake, Invite>>;
 		public fetchMember(user: UserResolvable, cache?: boolean): Promise<GuildMember>;
@@ -1600,6 +1603,11 @@ declare module 'discord.js' {
 
 	type AwaitReactionsOptions = ReactionCollectorOptions & { errors?: string[] };
 
+	type BanInfo = {
+		user: User;
+		reason: string | null;
+	};
+
 	type BanOptions = {
 		days?: number;
 		reason?: string;