Add support for the GET Guild Ban endpoint (#3362)

This adds supports for the GET `/guilds/{guild.id}/bans/{user.id}` endpoint,
allowing one to get a single `model::guild::Ban` for a specific user in a
guild.

Discord Documentation:

https://discord.com/developers/docs/resources/guild#get-guild-ban

Closes #3341

Author: AshleyBilbrey

src/http/client.rs

@@ -2794,6 +2794,40 @@ impl Http {
         .await
     }
 
+    /// Gets a [`Ban`] for a specific user in a guild. Returns [`None`] if no ban was found
+    /// matching both the [`GuildId`] and [`UserId`].
+    ///
+    /// **Note**: Requires that you have the [Ban Members] permission
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::Http`] if the current user lacks permission.
+    ///
+    /// [Ban Members]: Permissions::BAN_MEMBERS
+    pub async fn get_ban(&self, guild_id: GuildId, user_id: UserId) -> Result<Option<Ban>> {
+        let result = self
+            .fire(Request {
+                body: None,
+                multipart: None,
+                headers: None,
+                method: LightMethod::Get,
+                route: Route::GuildBan {
+                    guild_id,
+                    user_id,
+                },
+                params: None,
+            })
+            .await;
+
+        match result {
+            Ok(ban) => Ok(Some(ban)),
+            Err(Error::Http(ref err)) if err.status_code() == Some(StatusCode::NOT_FOUND) => {
+                Ok(None)
+            },
+            Err(e) => Err(e),
+        }
+    }
+
     /// Gets all audit logs in a specific guild.
     pub async fn get_audit_logs(
         &self,

src/model/guild/guild_id.rs

@@ -300,6 +300,21 @@ impl GuildId {
         http.as_ref().get_bans(self, target, limit).await
     }
 
+    /// Gets a user's ban from the guild.
+    /// See [`Http::get_ban`] for details.
+    ///
+    /// **Note**: Requires the [Ban Members] permission.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::Http`] if the current user lacks permission.
+    ///
+    /// [Ban Members]: Permissions::BAN_MEMBERS
+    #[inline]
+    pub async fn get_ban(self, http: impl AsRef<Http>, user_id: UserId) -> Result<Option<Ban>> {
+        http.as_ref().get_ban(self, user_id).await
+    }
+
     /// Gets a list of the guild's audit log entries
     ///
     /// **Note**: Requires the [View Audit Log] permission.

src/model/guild/mod.rs

@@ -587,6 +587,32 @@ impl Guild {
         self.id.bans(cache_http.http(), target, limit).await
     }
 
+    /// Gets a user's ban from the guild.
+    /// See [`Http::get_bans`] for details.
+    ///
+    /// **Note**: Requires the [Ban Members] permission.
+    ///
+    /// # Errors
+    ///
+    /// If the `cache` is enabled, returns a [`ModelError::InvalidPermissions`] if the current user
+    /// does not have permission to perform bans.
+    ///
+    /// [Ban Members]: Permissions::BAN_MEMBERS
+    pub async fn get_ban(
+        &self,
+        cache_http: impl CacheHttp,
+        user_id: UserId,
+    ) -> Result<Option<Ban>> {
+        #[cfg(feature = "cache")]
+        {
+            if let Some(cache) = cache_http.cache() {
+                self.require_perms(cache, Permissions::BAN_MEMBERS)?;
+            }
+        }
+
+        self.id.get_ban(cache_http.http(), user_id).await
+    }
+
     /// Adds a [`User`] to this guild with a valid OAuth2 access token.
     ///
     /// Returns the created [`Member`] object, or nothing if the user is already a member of the

src/model/guild/partial_guild.rs

@@ -340,6 +340,21 @@ impl PartialGuild {
         self.id.bans(http, target, limit).await
     }
 
+    /// Gets a user's ban from the guild.
+    /// See [`Http::get_bans`] for details.
+    ///
+    /// Requires the [Ban Members] permission.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::Http`] if the current user lacks permission.
+    ///
+    /// [Ban Members]: Permissions::BAN_MEMBERS
+    #[inline]
+    pub async fn get_ban(&self, http: impl AsRef<Http>, user_id: UserId) -> Result<Option<Ban>> {
+        self.id.get_ban(http, user_id).await
+    }
+
     /// Gets a list of the guild's audit log entries
     ///
     /// **Note**: Requires the [View Audit Log] permission.