Support stage instances (#1343)

This commit adds support to creating, editing, getting, and deleting stage instances. See discord/discord-api-docs#2898 and discord/discord-api-docs#2933

src/builder/create_stage_instance.rs

@@ -0,0 +1,26 @@
+use std::collections::HashMap;
+
+use serde_json::Value;
+
+use crate::internal::prelude::*;
+
+/// Creates a [`StageInstance`].
+///
+/// [`StageInstance`]: crate::model::channel::StageInstance
+#[derive(Clone, Debug, Default)]
+pub struct CreateStageInstance(pub HashMap<&'static str, Value>);
+
+impl CreateStageInstance {
+    // Sets the stage channel id of the stage channel instance.
+    pub fn channel_id(&mut self, id: u64) -> &mut Self {
+        self.0.insert("channel_id", Value::Number(Number::from(id)));
+        self
+    }
+
+    /// Sets the topic of the stage channel instance.
+    pub fn topic<D: ToString>(&mut self, topic: D) -> &mut Self {
+        self.0.insert("topic", Value::String(topic.to_string()));
+
+        self
+    }
+}

src/builder/edit_stage_instance.rs

@@ -0,0 +1,18 @@
+use std::collections::HashMap;
+
+use serde_json::Value;
+
+/// Edits a [`StageInstance`].
+///
+/// [`StageInstance`]: crate::model::channel::StageInstance
+#[derive(Clone, Debug, Default)]
+pub struct EditStageInstance(pub HashMap<&'static str, Value>);
+
+impl EditStageInstance {
+    /// Sets the topic of the stage channel instance.
+    pub fn topic<D: ToString>(&mut self, topic: D) -> &mut Self {
+        self.0.insert("topic", Value::String(topic.to_string()));
+
+        self
+    }
+}

src/builder/mod.rs

@@ -27,6 +27,7 @@ mod create_interaction_response;
 mod create_interaction_response_followup;
 mod create_invite;
 mod create_message;
+mod create_stage_instance;
 mod edit_channel;
 mod edit_guild;
 mod edit_guild_welcome_screen;
@@ -38,6 +39,7 @@ mod edit_member;
 mod edit_message;
 mod edit_profile;
 mod edit_role;
+mod edit_stage_instance;
 mod edit_voice_state;
 mod edit_webhook_message;
 mod execute_webhook;
@@ -50,6 +52,7 @@ pub use self::{
     create_embed::{CreateEmbed, CreateEmbedAuthor, CreateEmbedFooter, Timestamp},
     create_invite::CreateInvite,
     create_message::CreateMessage,
+    create_stage_instance::CreateStageInstance,
     edit_channel::EditChannel,
     edit_guild::EditGuild,
     edit_guild_welcome_screen::EditGuildWelcomeScreen,
@@ -58,6 +61,7 @@ pub use self::{
     edit_message::EditMessage,
     edit_profile::EditProfile,
     edit_role::EditRole,
+    edit_stage_instance::EditStageInstance,
     edit_voice_state::EditVoiceState,
     edit_webhook_message::EditWebhookMessage,
     execute_webhook::ExecuteWebhook,

src/client/dispatch.rs

@@ -810,5 +810,26 @@ async fn handle_event(
                 event_handler.application_command_delete(context, event.application_command).await;
             });
         },
+        DispatchEvent::Model(Event::StageInstanceCreate(event)) => {
+            let event_handler = Arc::clone(event_handler);
+
+            tokio::spawn(async move {
+                event_handler.stage_instance_create(context, event.stage_instance).await;
+            });
+        },
+        DispatchEvent::Model(Event::StageInstanceUpdate(event)) => {
+            let event_handler = Arc::clone(event_handler);
+
+            tokio::spawn(async move {
+                event_handler.stage_instance_update(context, event.stage_instance).await;
+            });
+        },
+        DispatchEvent::Model(Event::StageInstanceDelete(event)) => {
+            let event_handler = Arc::clone(event_handler);
+
+            tokio::spawn(async move {
+                event_handler.stage_instance_delete(context, event.stage_instance).await;
+            });
+        },
     }
 }

src/client/event_handler.rs

@@ -493,6 +493,21 @@ pub trait EventHandler: Send + Sync {
         _application_command: ApplicationCommand,
     ) {
     }
+
+    /// Dispatched when a stage instance is created.
+    ///
+    /// Provides the created stage instance.
+    async fn stage_instance_create(&self, _ctx: Context, _stage_instance: StageInstance) {}
+
+    /// Dispatched when a stage instance is updated.
+    ///
+    /// Provides the created stage instance.
+    async fn stage_instance_update(&self, _ctx: Context, _stage_instance: StageInstance) {}
+
+    /// Dispatched when a stage instance is deleted.
+    ///
+    /// Provides the created stage instance.
+    async fn stage_instance_delete(&self, _ctx: Context, _stage_instance: StageInstance) {}
 }
 
 /// This core trait for handling raw events

src/http/client.rs

@@ -370,6 +370,16 @@ impl Http {
         .await
     }
 
+    /// Creates a stage instance.
+    pub async fn create_stage_instance(&self, map: &Value) -> Result<StageInstance> {
+        self.fire(Request {
+            body: Some(map.to_string().as_bytes()),
+            headers: None,
+            route: RouteInfo::CreateStageInstance,
+        })
+        .await
+    }
+
     /// Creates an emoji in the given [`Guild`] with the given data.
     ///
     /// View the source code for [`Guild::create_emoji`] method to see what
@@ -742,6 +752,18 @@ impl Http {
         .await
     }
 
+    /// Deletes a stage instance.
+    pub async fn delete_stage_instance(&self, channel_id: u64) -> Result<()> {
+        self.wind(204, Request {
+            body: None,
+            headers: None,
+            route: RouteInfo::DeleteStageInstance {
+                channel_id,
+            },
+        })
+        .await
+    }
+
     /// Deletes an emoji from a server.
     pub async fn delete_emoji(&self, guild_id: u64, emoji_id: u64) -> Result<()> {
         self.wind(204, Request {
@@ -1069,6 +1091,18 @@ impl Http {
         .await
     }
 
+    /// Edits a stage instance.
+    pub async fn edit_stage_instance(&self, channel_id: u64, map: &Value) -> Result<StageInstance> {
+        self.fire(Request {
+            body: Some(map.to_string().as_bytes()),
+            headers: None,
+            route: RouteInfo::EditStageInstance {
+                channel_id,
+            },
+        })
+        .await
+    }
+
     /// Changes emoji information.
     pub async fn edit_emoji(&self, guild_id: u64, emoji_id: u64, map: &Value) -> Result<Emoji> {
         let body = serde_json::to_vec(map)?;
@@ -2004,6 +2038,18 @@ impl Http {
         .await
     }
 
+    /// Gets a stage instance.
+    pub async fn get_stage_instance(&self, channel_id: u64) -> Result<StageInstance> {
+        self.fire(Request {
+            body: None,
+            headers: None,
+            route: RouteInfo::GetStageInstance {
+                channel_id,
+            },
+        })
+        .await
+    }
+
     /// Gets information about the current application.
     ///
     /// **Note**: Only applications may use this endpoint.

src/http/routing.rs

@@ -372,6 +372,18 @@ pub enum Route {
     #[cfg(feature = "unstable_discord_api")]
     #[cfg_attr(docsrs, doc(cfg(feature = "unstable_discord_api")))]
     ApplicationsIdGuildsIdCommandsId(u64),
+    /// Route for the `/stage-instances` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: crate::model::id::ChannelId
+    StageInstances,
+    /// Route for the `/stage-instances/:channel_id` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: crate::model::id::ChannelId
+    StageInstancesChannelId(u64),
     /// Route where no ratelimit headers are in place (i.e. user account-only
     /// routes).
     ///
@@ -849,6 +861,14 @@ impl Route {
     pub fn application_guild_commands_permissions(application_id: u64, guild_id: u64) -> String {
         format!(api!("/applications/{}/guilds/{}/commands/permissions"), application_id, guild_id)
     }
+
+    pub fn stage_instances() -> String {
+        api!("/stage-instances").to_string()
+    }
+
+    pub fn stage_instance(channel_id: u64) -> String {
+        format!(api!("/stage-instances/{}"), channel_id)
+    }
 }
 
 #[derive(Clone, Debug)]
@@ -871,6 +891,7 @@ pub enum RouteInfo<'a> {
     CreateChannel {
         guild_id: u64,
     },
+    CreateStageInstance,
     CreateEmoji {
         guild_id: u64,
     },
@@ -938,6 +959,9 @@ pub enum RouteInfo<'a> {
     DeleteChannel {
         channel_id: u64,
     },
+    DeleteStageInstance {
+        channel_id: u64,
+    },
     DeleteEmoji {
         guild_id: u64,
         emoji_id: u64,
@@ -1023,6 +1047,9 @@ pub enum RouteInfo<'a> {
     EditChannel {
         channel_id: u64,
     },
+    EditStageInstance {
+        channel_id: u64,
+    },
     EditEmoji {
         guild_id: u64,
         emoji_id: u64,
@@ -1158,6 +1185,9 @@ pub enum RouteInfo<'a> {
     GetChannels {
         guild_id: u64,
     },
+    GetStageInstance {
+        channel_id: u64,
+    },
     GetCurrentApplicationInfo,
     GetCurrentUser,
     GetEmojis {
@@ -1381,6 +1411,9 @@ impl<'a> RouteInfo<'a> {
                 Route::GuildsIdChannels(guild_id),
                 Cow::from(Route::guild_channels(guild_id)),
             ),
+            RouteInfo::CreateStageInstance => {
+                (LightMethod::Post, Route::StageInstances, Cow::from(Route::stage_instances()))
+            },
             RouteInfo::CreateEmoji {
                 guild_id,
             } => (
@@ -1516,6 +1549,13 @@ impl<'a> RouteInfo<'a> {
                 Route::ChannelsId(channel_id),
                 Cow::from(Route::channel(channel_id)),
             ),
+            RouteInfo::DeleteStageInstance {
+                channel_id,
+            } => (
+                LightMethod::Delete,
+                Route::StageInstancesChannelId(channel_id),
+                Cow::from(Route::stage_instance(channel_id)),
+            ),
             RouteInfo::DeleteEmoji {
                 emoji_id,
                 guild_id,
@@ -1674,6 +1714,13 @@ impl<'a> RouteInfo<'a> {
                 Route::ChannelsId(channel_id),
                 Cow::from(Route::channel(channel_id)),
             ),
+            RouteInfo::EditStageInstance {
+                channel_id,
+            } => (
+                LightMethod::Patch,
+                Route::StageInstancesChannelId(channel_id),
+                Cow::from(Route::stage_instance(channel_id)),
+            ),
             RouteInfo::EditEmoji {
                 emoji_id,
                 guild_id,
@@ -1913,6 +1960,13 @@ impl<'a> RouteInfo<'a> {
                 Route::ChannelsId(channel_id),
                 Cow::from(Route::channel(channel_id)),
             ),
+            RouteInfo::GetStageInstance {
+                channel_id,
+            } => (
+                LightMethod::Get,
+                Route::StageInstancesChannelId(channel_id),
+                Cow::from(Route::stage_instance(channel_id)),
+            ),
             RouteInfo::GetChannelInvites {
                 channel_id,
             } => (