Implement guild ban pagination (serenity-rs#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