Add HTTP soundboard support (#3374)

Adds support for [Soundboard sounds][soundboard].

This only adds the models and HTTP endpoints, as there are also gateway events.

[soundboard]: https://discord.com/developers/docs/resources/soundboard

Author: arqunis

src/builder/create_soundboard.rs

@@ -0,0 +1,128 @@
+#[cfg(feature = "http")]
+use super::Builder;
+use super::CreateAttachment;
+#[cfg(feature = "http")]
+use crate::http::CacheHttp;
+#[cfg(feature = "http")]
+use crate::internal::prelude::*;
+use crate::model::prelude::*;
+
+/// A builder to create a soundboard sound.
+///
+/// [Discord docs](https://discord.com/developers/docs/resources/soundboard#soundboard-resource)
+#[derive(Clone, Debug)]
+#[must_use]
+pub struct CreateSoundboard<'a> {
+    name: String,
+    sound: String,
+    volume: f64,
+    emoji_id: Option<EmojiId>,
+    emoji_name: Option<String>,
+    audit_log_reason: Option<&'a str>,
+}
+
+impl<'a> CreateSoundboard<'a> {
+    /// Creates a new builder with the given data.
+    pub fn new(name: impl Into<String>, sound: &CreateAttachment) -> Self {
+        Self {
+            name: name.into(),
+            sound: sound.to_base64(),
+            volume: 1.0,
+            emoji_id: None,
+            emoji_name: None,
+            audit_log_reason: None,
+        }
+    }
+
+    /// Set the name of the soundboard sound, replacing the current value as set in [`Self::new`].
+    ///
+    /// **Note**: Must be between 2 and 32 characters long.
+    pub fn name(mut self, name: impl Into<String>) -> Self {
+        self.name = name.into();
+        self
+    }
+
+    /// Set the sound file. Replaces the current value as set in [`Self::new`].
+    ///
+    /// **Note**: Must be audio that is encoded in MP3 or OGG, max 512 KB, max
+    /// duration 5.2 seconds.
+    pub fn sound(mut self, sound: &CreateAttachment) -> Self {
+        self.sound = sound.to_base64();
+        self
+    }
+
+    /// Set the volume of the soundboard sound.
+    ///
+    /// **Note**: Must be between 0 to 1.
+    pub fn volume(mut self, volume: f64) -> Self {
+        self.volume = volume;
+        self
+    }
+
+    /// Set the ID of the custom emoji.
+    pub fn emoji_id(mut self, id: EmojiId) -> Self {
+        self.emoji_id = Some(id);
+        self
+    }
+
+    /// Set the Unicode character of the custom emoji.
+    pub fn emoji_name(mut self, name: String) -> Self {
+        self.emoji_name = Some(name);
+        self
+    }
+
+    /// Sets the request's audit log reason.
+    pub fn audit_log_reason(mut self, reason: &'a str) -> Self {
+        self.audit_log_reason = Some(reason);
+        self
+    }
+}
+
+#[cfg(feature = "http")]
+#[async_trait::async_trait]
+impl Builder for CreateSoundboard<'_> {
+    type Context<'ctx> = GuildId;
+    type Built = Soundboard;
+
+    /// Creates a new soundboard in the guild with the data set.
+    ///
+    /// **Note**: Requires the [Create Guild Expressions] permission.
+    ///
+    /// # Errors
+    ///
+    /// If the `cache` is enabled, returns a [`ModelError::InvalidPermissions`] if the current user
+    /// lacks permission. Otherwise returns [`Error::Http`], as well as if invalid data is given.
+    ///
+    /// [Create Guild Expressions]: Permissions::CREATE_GUILD_EXPRESSIONS
+    async fn execute(
+        self,
+        cache_http: impl CacheHttp,
+        ctx: Self::Context<'_>,
+    ) -> Result<Self::Built> {
+        #[cfg(feature = "cache")]
+        crate::utils::user_has_guild_perms(
+            &cache_http,
+            ctx,
+            Permissions::CREATE_GUILD_EXPRESSIONS,
+        )?;
+
+        #[derive(serde::Serialize)]
+        struct CreateSoundboard {
+            name: String,
+            sound: String,
+            volume: f64,
+            emoji_id: Option<EmojiId>,
+            emoji_name: Option<String>,
+        }
+
+        let map = CreateSoundboard {
+            name: self.name,
+            sound: self.sound,
+            volume: self.volume,
+            emoji_id: self.emoji_id,
+            emoji_name: self.emoji_name,
+        };
+
+        cache_http.http().create_guild_soundboard(ctx, &map, self.audit_log_reason).await
+    }
+}

src/builder/edit_soundboard.rs

@@ -0,0 +1,100 @@
+#[cfg(feature = "http")]
+use super::Builder;
+#[cfg(feature = "http")]
+use crate::http::CacheHttp;
+#[cfg(feature = "http")]
+use crate::internal::prelude::*;
+use crate::model::prelude::*;
+
+/// A builder to create or edit a [`Soundboard`] for use via a number of model methods.
+///
+/// These are:
+///
+/// - [`Guild::edit_soundboard`]
+/// - [`PartialGuild::edit_soundboard`]
+/// - [`GuildId::edit_soundboard`]
+///
+/// [Discord docs](https://discord.com/developers/docs/resources/soundboard#soundboard-resource)
+#[derive(Clone, Debug, Default, Serialize)]
+#[must_use]
+pub struct EditSoundboard<'a> {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    volume: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    emoji_id: Option<EmojiId>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    emoji_name: Option<String>,
+
+    #[serde(skip)]
+    audit_log_reason: Option<&'a str>,
+}
+
+impl<'a> EditSoundboard<'a> {
+    /// Equivalent to [`Self::default`].
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// The name of the soundboard sound to set.
+    ///
+    /// **Note**: Must be between 2 and 32 characters long.
+    pub fn name(mut self, name: impl Into<String>) -> Self {
+        self.name = Some(name.into());
+        self
+    }
+
+    /// Set the volume of the soundboard sound.
+    ///
+    /// **Note**: Must be between 0 to 1.
+    pub fn volume(mut self, volume: f64) -> Self {
+        self.volume = volume.into();
+        self
+    }
+
+    /// Set the ID of the custom emoji.
+    pub fn emoji_id(mut self, id: EmojiId) -> Self {
+        self.emoji_id = Some(id);
+        self
+    }
+
+    /// Set the Unicode character of the custom emoji.
+    pub fn emoji_name(mut self, name: String) -> Self {
+        self.emoji_name = Some(name);
+        self
+    }
+
+    /// Sets the request's audit log reason.
+    pub fn audit_log_reason(mut self, reason: &'a str) -> Self {
+        self.audit_log_reason = Some(reason);
+        self
+    }
+}
+
+#[cfg(feature = "http")]
+#[async_trait::async_trait]
+impl Builder for EditSoundboard<'_> {
+    type Context<'ctx> = (GuildId, SoundId);
+    type Built = Soundboard;
+
+    /// Edits the soundboard sound.
+    ///
+    /// **Note**: If the soundboard sound was created by the current user, requires either the
+    /// [Create Guild Expressions] or the [Manage Guild Expressions] permission. Otherwise, the
+    /// [Manage Guild Expressions] permission is required.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::Http`] if the current user lacks permission, or if invalid data is given.
+    ///
+    /// [Create Guild Expressions]: Permissions::CREATE_GUILD_EXPRESSIONS
+    /// [Manage Guild Expressions]: Permissions::MANAGE_GUILD_EXPRESSIONS
+    async fn execute(
+        self,
+        cache_http: impl CacheHttp,
+        ctx: Self::Context<'_>,
+    ) -> Result<Self::Built> {
+        cache_http.http().edit_guild_soundboard(ctx.0, ctx.1, &self, self.audit_log_reason).await
+    }
+}

src/builder/mod.rs

@@ -53,6 +53,7 @@ mod create_invite;
 mod create_message;
 pub mod create_poll;
 mod create_scheduled_event;
+mod create_soundboard;
 mod create_stage_instance;
 mod create_sticker;
 mod create_thread;
@@ -68,6 +69,7 @@ mod edit_message;
 mod edit_profile;
 mod edit_role;
 mod edit_scheduled_event;
+mod edit_soundboard;
 mod edit_stage_instance;
 mod edit_sticker;
 mod edit_thread;
@@ -95,6 +97,7 @@ pub use create_invite::*;
 pub use create_message::*;
 pub use create_poll::{CreatePoll, CreatePollAnswer};
 pub use create_scheduled_event::*;
+pub use create_soundboard::*;
 pub use create_stage_instance::*;
 pub use create_sticker::*;
 pub use create_thread::*;
@@ -110,6 +113,7 @@ pub use edit_message::*;
 pub use edit_profile::*;
 pub use edit_role::*;
 pub use edit_scheduled_event::*;
+pub use edit_soundboard::*;
 pub use edit_stage_instance::*;
 pub use edit_sticker::*;
 pub use edit_thread::*;