Add audit log reasons to remaining model methods (#2821)

examples/e14_message_components/src/main.rs

@@ -131,7 +131,7 @@ impl EventHandler for Handler {
 
         // Delete the orig message or there will be dangling components (components that still
         // exist, but no collector is running so any user who presses them sees an error)
-        m.delete(&ctx).await.unwrap()
+        m.delete(&ctx, None).await.unwrap()
     }
 }
 

examples/testing/src/main.rs

@@ -148,7 +148,7 @@ async fn message(ctx: &Context, msg: &Message) -> Result<(), serenity::Error> {
     } else if let Some(user_id) = msg.content.strip_prefix("ban ") {
         // Test if banning without a reason actually works
         let user_id: UserId = user_id.trim().parse().unwrap();
-        guild_id.ban(&ctx.http, user_id, 0).await?;
+        guild_id.ban(&ctx.http, user_id, 0, None).await?;
     } else if msg.content == "createtags" {
         channel_id
             .edit(
@@ -231,7 +231,7 @@ async fn message(ctx: &Context, msg: &Message) -> Result<(), serenity::Error> {
             serenity::utils::parse_message_url(forum_post_url).unwrap();
         msg.channel_id.say(ctx, format!("Deleting <#{}> in 10 seconds...", channel_id)).await?;
         tokio::time::sleep(std::time::Duration::from_secs(10)).await;
-        channel_id.delete(&ctx.http).await?;
+        channel_id.delete(&ctx.http, None).await?;
     } else {
         return Ok(());
     }

src/builder/edit_role.rs

@@ -177,9 +177,7 @@ impl<'a> EditRole<'a> {
         };
 
         if let Some(position) = self.position {
-            guild_id
-                .edit_role_position_with_reason(http, role.id, position, self.audit_log_reason)
-                .await?;
+            guild_id.edit_role_position(http, role.id, position, self.audit_log_reason).await?;
         }
         Ok(role)
     }

src/model/channel/channel_id.rs

@@ -95,9 +95,14 @@ impl ChannelId {
     /// set.
     ///
     /// [Manage Channels]: Permissions::MANAGE_CHANNELS
-    pub async fn create_permission(self, http: &Http, target: PermissionOverwrite) -> Result<()> {
+    pub async fn create_permission(
+        self,
+        http: &Http,
+        target: PermissionOverwrite,
+        reason: Option<&str>,
+    ) -> Result<()> {
         let data: PermissionOverwriteData = target.into();
-        http.create_permission(self, data.id, &data, None).await
+        http.create_permission(self, data.id, &data, reason).await
     }
 
     /// React to a [`Message`] with a custom [`Emoji`] or unicode character.
@@ -130,8 +135,8 @@ impl ChannelId {
     /// Returns [`Error::Http`] if the current user lacks permission.
     ///
     /// [Manage Channels]: Permissions::MANAGE_CHANNELS
-    pub async fn delete(self, http: &Http) -> Result<Channel> {
-        http.delete_channel(self, None).await
+    pub async fn delete(self, http: &Http, reason: Option<&str>) -> Result<Channel> {
+        http.delete_channel(self, reason).await
     }
 
     /// Deletes a [`Message`] given its Id.
@@ -146,8 +151,13 @@ impl ChannelId {
     /// Returns [`Error::Http`] if the current user lacks permission to delete the message.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn delete_message(self, http: &Http, message_id: MessageId) -> Result<()> {
-        http.delete_message(self, message_id, None).await
+    pub async fn delete_message(
+        self,
+        http: &Http,
+        message_id: MessageId,
+        reason: Option<&str>,
+    ) -> Result<()> {
+        http.delete_message(self, message_id, reason).await
     }
 
     /// Deletes all messages by Ids from the given vector in the given channel.
@@ -166,7 +176,12 @@ impl ChannelId {
     /// Also will return [`Error::Http`] if the current user lacks permission to delete messages.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn delete_messages(self, http: &Http, message_ids: &[MessageId]) -> Result<()> {
+    pub async fn delete_messages(
+        self,
+        http: &Http,
+        message_ids: &[MessageId],
+        reason: Option<&str>,
+    ) -> Result<()> {
         use crate::model::error::{Maximum, Minimum};
 
         #[derive(serde::Serialize)]
@@ -178,13 +193,13 @@ impl ChannelId {
         Maximum::BulkDeleteAmount.check_overflow(message_ids.len())?;
 
         if message_ids.len() == 1 {
-            self.delete_message(http, message_ids[0]).await
+            self.delete_message(http, message_ids[0], reason).await
         } else {
             let req = DeleteMessages {
                 messages: message_ids,
             };
 
-            http.delete_messages(self, &req, None).await
+            http.delete_messages(self, &req, reason).await
         }
     }
 
@@ -201,12 +216,13 @@ impl ChannelId {
         self,
         http: &Http,
         permission_type: PermissionOverwriteType,
+        reason: Option<&str>,
     ) -> Result<()> {
         let id = match permission_type {
             PermissionOverwriteType::Member(id) => id.into(),
             PermissionOverwriteType::Role(id) => id.get().into(),
         };
-        http.delete_permission(self, id, None).await
+        http.delete_permission(self, id, reason).await
     }
 
     /// Deletes the given [`Reaction`] from the channel.
@@ -503,8 +519,8 @@ impl ChannelId {
     /// many pinned messages.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn pin(self, http: &Http, message_id: MessageId) -> Result<()> {
-        http.pin_message(self, message_id, None).await
+    pub async fn pin(self, http: &Http, message_id: MessageId, reason: Option<&str>) -> Result<()> {
+        http.pin_message(self, message_id, reason).await
     }
 
     /// Crossposts a [`Message`].
@@ -742,8 +758,13 @@ impl ChannelId {
     /// Returns [`Error::Http`] if the current user lacks permission.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn unpin(self, http: &Http, message_id: MessageId) -> Result<()> {
-        http.unpin_message(self, message_id, None).await
+    pub async fn unpin(
+        self,
+        http: &Http,
+        message_id: MessageId,
+        reason: Option<&str>,
+    ) -> Result<()> {
+        http.unpin_message(self, message_id, reason).await
     }
 
     /// Retrieves the channel's webhooks.
@@ -848,8 +869,8 @@ impl ChannelId {
     ///
     /// Returns [`Error::Http`] if the channel is not a stage channel, or if there is no stage
     /// instance currently.
-    pub async fn delete_stage_instance(self, http: &Http) -> Result<()> {
-        http.delete_stage_instance(self, None).await
+    pub async fn delete_stage_instance(self, http: &Http, reason: Option<&str>) -> Result<()> {
+        http.delete_stage_instance(self, reason).await
     }
 
     /// Creates a public thread that is connected to a message.

src/model/channel/guild_channel.rs

@@ -251,8 +251,13 @@ impl GuildChannel {
     /// # Errors
     ///
     /// Returns [`Error::Http`] if the current user lacks permission.
-    pub async fn create_permission(&self, http: &Http, target: PermissionOverwrite) -> Result<()> {
-        self.id.create_permission(http, target).await
+    pub async fn create_permission(
+        &self,
+        http: &Http,
+        target: PermissionOverwrite,
+        reason: Option<&str>,
+    ) -> Result<()> {
+        self.id.create_permission(http, target, reason).await
     }
 
     /// Deletes this channel, returning the channel on a successful deletion.
@@ -267,7 +272,11 @@ impl GuildChannel {
     /// Otherwise returns [`Error::Http`] if the current user lacks permission.
     ///
     /// [Manage Channels]: Permissions::MANAGE_CHANNELS
-    pub async fn delete(&self, cache_http: impl CacheHttp) -> Result<GuildChannel> {
+    pub async fn delete(
+        &self,
+        cache_http: impl CacheHttp,
+        reason: Option<&str>,
+    ) -> Result<GuildChannel> {
         #[cfg(feature = "cache")]
         {
             if let Some(cache) = cache_http.cache() {
@@ -280,7 +289,7 @@ impl GuildChannel {
             }
         }
 
-        let channel = self.id.delete(cache_http.http()).await?;
+        let channel = self.id.delete(cache_http.http(), reason).await?;
         channel.guild().ok_or(Error::Model(ModelError::InvalidChannelType))
     }
 
@@ -298,8 +307,13 @@ impl GuildChannel {
     /// delete either 0 or more than 100 messages.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn delete_messages(&self, http: &Http, message_ids: &[MessageId]) -> Result<()> {
-        self.id.delete_messages(http, message_ids).await
+    pub async fn delete_messages(
+        &self,
+        http: &Http,
+        message_ids: &[MessageId],
+        reason: Option<&str>,
+    ) -> Result<()> {
+        self.id.delete_messages(http, message_ids, reason).await
     }
 
     /// Deletes all permission overrides in the channel from a member or role.
@@ -315,8 +329,9 @@ impl GuildChannel {
         &self,
         http: &Http,
         permission_type: PermissionOverwriteType,
+        reason: Option<&str>,
     ) -> Result<()> {
-        self.id.delete_permission(http, permission_type).await
+        self.id.delete_permission(http, permission_type, reason).await
     }
 
     /// Deletes the given [`Reaction`] from the channel.
@@ -654,8 +669,13 @@ impl GuildChannel {
     /// too many pinned messages.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn pin(&self, http: &Http, message_id: MessageId) -> Result<()> {
-        self.id.pin(http, message_id).await
+    pub async fn pin(
+        &self,
+        http: &Http,
+        message_id: MessageId,
+        reason: Option<&str>,
+    ) -> Result<()> {
+        self.id.pin(http, message_id, reason).await
     }
 
     /// Gets all channel's pins.
@@ -803,8 +823,13 @@ impl GuildChannel {
     /// Returns [`Error::Http`] if the current user lacks permission.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn unpin(&self, http: &Http, message_id: MessageId) -> Result<()> {
-        self.id.unpin(http, message_id).await
+    pub async fn unpin(
+        &self,
+        http: &Http,
+        message_id: MessageId,
+        reason: Option<&str>,
+    ) -> Result<()> {
+        self.id.unpin(http, message_id, reason).await
     }
 
     /// Retrieves the channel's webhooks.
@@ -969,12 +994,12 @@ impl GuildChannel {
     /// Returns [`ModelError::InvalidChannelType`] if the channel is not a stage channel.
     ///
     /// Returns [`Error::Http`] if there is no stage instance currently.
-    pub async fn delete_stage_instance(&self, http: &Http) -> Result<()> {
+    pub async fn delete_stage_instance(&self, http: &Http, reason: Option<&str>) -> Result<()> {
         if self.kind != ChannelType::Stage {
             return Err(Error::Model(ModelError::InvalidChannelType));
         }
 
-        self.id.delete_stage_instance(http).await
+        self.id.delete_stage_instance(http, reason).await
     }
 
     /// Creates a public thread that is connected to a message.

src/model/channel/message.rs

@@ -221,7 +221,7 @@ impl Message {
     /// current user does not have the required permissions.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn delete(&self, cache_http: impl CacheHttp) -> Result<()> {
+    pub async fn delete(&self, cache_http: impl CacheHttp, reason: Option<&str>) -> Result<()> {
         #[cfg(feature = "cache")]
         {
             if let (Some(cache), Some(guild_id)) = (cache_http.cache(), self.guild_id) {
@@ -236,7 +236,7 @@ impl Message {
             }
         }
 
-        self.channel_id.delete_message(cache_http.http(), self.id).await
+        self.channel_id.delete_message(cache_http.http(), self.id, reason).await
     }
 
     /// Deletes all of the [`Reaction`]s associated with the message.
@@ -476,7 +476,7 @@ impl Message {
     /// does not have the required permissions.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn pin(&self, cache_http: impl CacheHttp) -> Result<()> {
+    pub async fn pin(&self, cache_http: impl CacheHttp, reason: Option<&str>) -> Result<()> {
         #[cfg(feature = "cache")]
         {
             if let (Some(cache), Some(guild_id)) = (cache_http.cache(), self.guild_id) {
@@ -489,7 +489,7 @@ impl Message {
             }
         }
 
-        self.channel_id.pin(cache_http.http(), self.id).await
+        self.channel_id.pin(cache_http.http(), self.id, reason).await
     }
 
     /// React to the message with a custom [`Emoji`] or unicode character.
@@ -694,7 +694,7 @@ impl Message {
     /// does not have the required permissions.
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
-    pub async fn unpin(&self, cache_http: impl CacheHttp) -> Result<()> {
+    pub async fn unpin(&self, cache_http: impl CacheHttp, reason: Option<&str>) -> Result<()> {
         #[cfg(feature = "cache")]
         {
             if let (Some(cache), Some(guild_id)) = (cache_http.cache(), self.guild_id) {
@@ -707,7 +707,7 @@ impl Message {
             }
         }
 
-        cache_http.http().unpin_message(self.channel_id, self.id, None).await
+        cache_http.http().unpin_message(self.channel_id, self.id, reason).await
     }
 
     /// Tries to return author's nickname in the current channel's guild.

src/model/channel/mod.rs

@@ -121,10 +121,10 @@ impl Channel {
     /// lacks permission.
     ///
     /// Otherwise will return [`Error::Http`] if the current user does not have permission.
-    pub async fn delete(&self, cache_http: impl CacheHttp) -> Result<()> {
+    pub async fn delete(&self, cache_http: impl CacheHttp, reason: Option<&str>) -> Result<()> {
         match self {
             Self::Guild(public_channel) => {
-                public_channel.delete(cache_http).await?;
+                public_channel.delete(cache_http, reason).await?;
             },
             Self::Private(private_channel) => {
                 private_channel.delete(cache_http.http()).await?;

src/model/channel/private_channel.rs

@@ -69,7 +69,8 @@ impl PrivateChannel {
     /// closing a private channel on the client, which can be re-opened.
     #[allow(clippy::missing_errors_doc)]
     pub async fn delete(&self, http: &Http) -> Result<PrivateChannel> {
-        self.id.delete(http).await?.private().ok_or(Error::Model(ModelError::InvalidChannelType))
+        let resp = self.id.delete(http, None).await?;
+        resp.private().ok_or(Error::Model(ModelError::InvalidChannelType))
     }
 
     /// Deletes all messages by Ids from the given vector in the channel.
@@ -87,7 +88,7 @@ impl PrivateChannel {
     ///
     /// [Manage Messages]: Permissions::MANAGE_MESSAGES
     pub async fn delete_messages(&self, http: &Http, message_ids: &[MessageId]) -> Result<()> {
-        self.id.delete_messages(http, message_ids).await
+        self.id.delete_messages(http, message_ids, None).await
     }
 
     /// Deletes all permission overrides in the channel from a member or role.
@@ -101,7 +102,7 @@ impl PrivateChannel {
         http: &Http,
         permission_type: PermissionOverwriteType,
     ) -> Result<()> {
-        self.id.delete_permission(http, permission_type).await
+        self.id.delete_permission(http, permission_type, None).await
     }
 
     /// Deletes the given [`Reaction`] from the channel.
@@ -202,7 +203,7 @@ impl PrivateChannel {
     ///
     /// Returns [`Error::Http`] if the number of pinned messages would exceed the 50 message limit.
     pub async fn pin(&self, http: &Http, message_id: MessageId) -> Result<()> {
-        self.id.pin(http, message_id).await
+        self.id.pin(http, message_id, None).await
     }
 
     /// Retrieves the list of messages that have been pinned in the private channel.
@@ -318,7 +319,7 @@ impl PrivateChannel {
     /// Returns [`Error::Http`] if the current user lacks permission, if the message was deleted,
     /// or if the channel already has the limit of 50 pinned messages.
     pub async fn unpin(&self, http: &Http, message_id: MessageId) -> Result<()> {
-        self.id.unpin(http, message_id).await
+        self.id.unpin(http, message_id, None).await
     }
 }
 

src/model/error.rs

@@ -117,7 +117,7 @@ impl fmt::Display for Minimum {
 /// #[cfg(feature = "client")]
 /// impl EventHandler for Handler {
 ///     async fn guild_ban_removal(&self, ctx: &Context, guild_id: &GuildId, user: &User) {
-///         match guild_id.ban(&ctx.http, user.id, 8).await {
+///         match guild_id.ban(&ctx.http, user.id, 8, Some("No unbanning people!")).await {
 ///             Ok(()) => {
 ///                 // Ban successful.
 ///             },