Implement guild ban pagination (#2535)

This implements user pagination for the [Get Guild Bans](https://discord.com/developers/docs/resources/guild#get-guild-bans) endpoint.

src/http/client.rs

@@ -2532,8 +2532,35 @@ impl Http {
         Ok(status.scheduled_maintenances)
     }
 
-    /// Gets all the users that are banned in specific guild.
-    pub async fn get_bans(&self, guild_id: GuildId) -> Result<Vec<Ban>> {
+    /// Gets all the users that are banned in specific guild, with additional options for
+    /// filtering.
+    ///
+    /// If `limit` is left unset, by default at most 1000 worths of data for banned users is
+    /// returned.
+    ///
+    /// If `target` is set, then users will be filtered by Id, such that their Id comes before or
+    /// after the provided [`UserId`] wrapped by the [`UserPagination`].
+    ///
+    /// [`UserId`]: crate::model::id::UserId
+    pub async fn get_bans(
+        &self,
+        guild_id: GuildId,
+        target: Option<UserPagination>,
+        limit: Option<u8>,
+    ) -> Result<Vec<Ban>> {
+        let mut params = vec![];
+
+        if let Some(limit) = limit {
+            params.push(("limit", limit.to_string()));
+        }
+
+        if let Some(target) = target {
+            match target {
+                UserPagination::After(id) => params.push(("after", id.to_string())),
+                UserPagination::Before(id) => params.push(("before", id.to_string())),
+            }
+        }
+
         self.fire(Request {
             body: None,
             multipart: None,
@@ -2542,7 +2569,7 @@ impl Http {
             route: Route::GuildBans {
                 guild_id,
             },
-            params: None,
+            params: Some(params),
         })
         .await
     }

src/http/mod.rs

@@ -165,9 +165,7 @@ impl LightMethod {
     }
 }
 
-/// Representation of the method of a query to send for the [`get_guilds`] function.
-///
-/// [`get_guilds`]: Http::get_guilds
+/// Representation of the method of a query to send for the [`Http::get_guilds`] function.
 #[non_exhaustive]
 pub enum GuildPagination {
     /// The Id to get the guilds after.
@@ -176,9 +174,8 @@ pub enum GuildPagination {
     Before(GuildId),
 }
 
-/// Representation of the method of a query to send for the [`get_scheduled_event_users`] function.
-///
-/// [`get_scheduled_event_users`]: Http::get_scheduled_event_users
+/// Representation of the method of a query to send for the [`Http::get_scheduled_event_users`] and
+/// [`Http::get_bans`] functions.
 #[non_exhaustive]
 pub enum UserPagination {
     /// The Id to get the users after.

src/model/guild/guild_id.rs

@@ -253,7 +253,8 @@ impl GuildId {
         http.as_ref().ban_user(self, user, dmd, reason).await
     }
 
-    /// Gets a list of the guild's bans.
+    /// Gets a list of the guild's bans, with additional options and filtering. See
+    /// [`Http::get_bans`] for details.
     ///
     /// **Note**: Requires the [Ban Members] permission.
     ///
@@ -263,8 +264,13 @@ impl GuildId {
     ///
     /// [Ban Members]: Permissions::BAN_MEMBERS
     #[inline]
-    pub async fn bans(self, http: impl AsRef<Http>) -> Result<Vec<Ban>> {
-        http.as_ref().get_bans(self).await
+    pub async fn bans(
+        self,
+        http: impl AsRef<Http>,
+        target: Option<UserPagination>,
+        limit: Option<u8>,
+    ) -> Result<Vec<Ban>> {
+        http.as_ref().get_bans(self, target, limit).await
     }
 
     /// Gets a list of the guild's audit log entries

src/model/guild/mod.rs

@@ -531,7 +531,8 @@ impl Guild {
         self.banner.as_ref().map(|banner| cdn!("/banners/{}/{}.webp?size=1024", self.id, banner))
     }
 
-    /// Retrieves a list of [`Ban`]s for the guild.
+    /// Gets a list of the guild's bans, with additional options and filtering. See
+    /// [`Http::get_bans`] for details.
     ///
     /// **Note**: Requires the [Ban Members] permission.
     ///
@@ -541,15 +542,20 @@ impl Guild {
     /// does not have permission to perform bans.
     ///
     /// [Ban Members]: Permissions::BAN_MEMBERS
-    pub async fn bans(&self, cache_http: impl CacheHttp) -> Result<Vec<Ban>> {
+    pub async fn bans(
+        &self,
+        cache_http: impl CacheHttp,
+        target: Option<UserPagination>,
+        limit: Option<u8>,
+    ) -> Result<Vec<Ban>> {
         #[cfg(feature = "cache")]
         {
             if let Some(cache) = cache_http.cache() {
                 self.require_perms(cache, Permissions::BAN_MEMBERS)?;
             }
         }
 
-        self.id.bans(cache_http.http()).await
+        self.id.bans(cache_http.http(), target, limit).await
     }
 
     /// Adds a [`User`] to this guild with a valid OAuth2 access token.

src/model/guild/partial_guild.rs

@@ -21,7 +21,7 @@ use crate::collector::{MessageCollector, ReactionCollector};
 #[cfg(feature = "collector")]
 use crate::gateway::ShardMessenger;
 #[cfg(feature = "model")]
-use crate::http::{CacheHttp, Http};
+use crate::http::{CacheHttp, Http, UserPagination};
 #[cfg(feature = "model")]
 use crate::model::application::{Command, CommandPermissions};
 #[cfg(feature = "model")]
@@ -323,7 +323,8 @@ impl PartialGuild {
         self.id.ban_with_reason(http, user, dmd, reason).await
     }
 
-    /// Gets a list of the guild's bans.
+    /// Gets a list of the guild's bans, with additional options and filtering. See
+    /// [`Http::get_bans`] for details.
     ///
     /// Requires the [Ban Members] permission.
     ///
@@ -333,8 +334,13 @@ impl PartialGuild {
     ///
     /// [Ban Members]: Permissions::BAN_MEMBERS
     #[inline]
-    pub async fn bans(&self, http: impl AsRef<Http>) -> Result<Vec<Ban>> {
-        self.id.bans(http).await
+    pub async fn bans(
+        &self,
+        http: impl AsRef<Http>,
+        target: Option<UserPagination>,
+        limit: Option<u8>,
+    ) -> Result<Vec<Ban>> {
+        self.id.bans(http, target, limit).await
     }
 
     /// Gets a list of the guild's audit log entries