kozabrada123/chorus
kozabrada123
/
chorus
mirror of https://github.com/polyphony-chat/chorus.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Better docs

This commit is contained in:
kozabrada123 2023-07-28 18:45:40 +02:00
parent 577c8a2d71
commit 1f9efa98e3
5 changed files with 55 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/api/channels/channels.rs
View File

@ -39,7 +39,7 @@ impl Channel {
}
/// Modifies a channel with the provided data.
/// Replaces self with the new channel object.
/// Returns the new Channel.
pub async fn modify(
&self,
modify_data: ChannelModifySchema,

8
src/api/channels/messages.rs
View File

@ -10,7 +10,8 @@ use crate::ratelimiter::ChorusRequest;
use crate::types::{Message, MessageSendSchema, Snowflake};
impl Message {
/// Sends a message to the Spacebar server.
/// Sends a message in the channel with the provided channel_id.
/// Returns the sent message.
pub async fn send(
user: &mut UserMeta,
channel_id: Snowflake,
@ -68,14 +69,15 @@ impl Message {
}
impl UserMeta {
/// Sends a message to the Spacebar server.
/// Sends a message in the channel with the provided channel_id.
/// Returns the sent message.
/// # Notes
/// Shorthand call for Message::send()
pub async fn send_message(
&mut self,
message: MessageSendSchema,
channel_id: Snowflake,
) -> ChorusResult<Message, crate::errors::ChorusError> {
) -> ChorusResult<Message> {
Message::send(self, channel_id, message).await
}
}

20
src/api/channels/permissions.rs
View File

@ -11,16 +11,6 @@ use crate::{
impl types::Channel {
/// Edits the permission overwrites for a channel.
///
/// # Arguments
///
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// * `channel_id` - A string slice representing the ID of the channel.
/// * `overwrite` - A [`PermissionOverwrite`] instance representing the new permission overwrites.
///
/// # Returns
///
/// This function returns a result that is either [`Ok(())`] if the request is successful, or an [`Err(ChorusLibError)`].
pub async fn edit_permissions(
user: &mut UserMeta,
channel_id: Snowflake,
@ -48,16 +38,6 @@ impl types::Channel {
}
/// Deletes a permission overwrite for a channel.
///
/// # Arguments
///
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// * `channel_id` - A string slice representing the ID of the channel.
/// * `overwrite_id` - A string slice representing the ID of the permission overwrite to delete.
///
/// # Returns
///
/// This function returns a Result that is either [`Ok(())`] if the request is successfulm or an [`Err(ChorusLibError)`].
pub async fn delete_permission(
user: &mut UserMeta,
channel_id: Snowflake,

92
src/api/channels/reactions.rs
View File

@ -16,12 +16,11 @@ pub struct ReactionMeta {
impl ReactionMeta {
/// Deletes all reactions for a message.
///
/// This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user.
/// # Arguments
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// # Returns
/// A `Result` [`()`] [`crate::errors::ChorusError`] if something went wrong.
///
/// Fires a `Message Reaction Remove All` Gateway event.
///
/// # Reference
/// See <https://discord.com/developers/docs/resources/channel#delete-all-reactions>
pub async fn delete_all(&self, user: &mut UserMeta) -> ChorusResult<()> {
@ -39,13 +38,10 @@ impl ReactionMeta {
}
/// Gets a list of users that reacted with a specific emoji to a message.
/// # Arguments
/// * `emoji` - A string slice containing the emoji to search for. The emoji must be URL Encoded or
/// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
/// format name:id with the emoji name and emoji id.
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// # Returns
/// A Result that is [`Err(crate::errors::ChorusLibError)`] if something went wrong.
///
/// The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
/// To use custom emoji, the format of the emoji string must be name:id.
///
/// # Reference
/// See <https://discord.com/developers/docs/resources/channel#get-reactions>
pub async fn get(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<Vec<PublicUser>> {
@ -65,16 +61,15 @@ impl ReactionMeta {
.await
}
/// Deletes all the reactions for a given `emoji` on a message. This endpoint requires the
/// MANAGE_MESSAGES permission to be present on the current user.
/// # Arguments
/// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or
/// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
/// format name:id with the emoji name and emoji id.
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// # Returns
/// A Result that is [`Err(crate::errors::ChorusLibError)`] if something went wrong.
/// Fires a `Message Reaction Remove Emoji` Gateway event.
/// Deletes all the reactions for a given emoji on a message.
///
/// This endpoint requires the MANAGE_MESSAGES permission.
///
/// The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
/// To use custom emoji, the format of the emoji string must be name:id.
///
/// Fires the `Message Reaction Remove Emoji` Gateway event.
///
/// # Reference
/// See <https://discord.com/developers/docs/resources/channel#delete-all-reactions-for-emoji>
pub async fn delete_emoji(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
@ -92,21 +87,18 @@ impl ReactionMeta {
chorus_request.handle_request_as_result(user).await
}
/// Create a reaction for the message.
/// This endpoint requires the READ_MESSAGE_HISTORY permission
/// to be present on the current user. Additionally, if nobody else has reacted to the message using
/// this emoji, this endpoint requires the ADD_REACTIONS permission to be present on the current
/// user.
/// # Arguments
/// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or
/// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
/// format name:id with the emoji name and emoji id.
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// # Returns
/// A `Result` containing [`()`] or a [`crate::errors::ChorusError`].
/// Create a reaction on a message.
///
/// This endpoint requires the READ_MESSAGE_HISTORY permission.
///
/// Additionally, if nobody else has reacted to the message using this emoji,
/// this endpoint requires the ADD_REACTIONS permission.
///
/// The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
/// To use custom emoji, the format of the emoji string must be name:id.
///
/// # Reference
/// See <https://discord.com/developers/docs/resources/channel#create-reaction>
///
pub async fn create(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
let url = format!(
"{}/channels/{}/messages/{}/reactions/{}/@me/",
@ -122,15 +114,13 @@ impl ReactionMeta {
chorus_request.handle_request_as_result(user).await
}
/// Delete a reaction the current user has made for the message.
/// # Arguments
/// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or
/// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
/// format name:id with the emoji name and emoji id.
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// # Returns
/// A `Result` containing [`()`] or a [`crate::errors::ChorusError`].
/// Deletes a reaction the current user has made to the message.
///
/// The reaction emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
/// To use custom emoji, the format of the emoji string must be name:id.
///
/// Fires a `Message Reaction Remove` Gateway event.
///
/// # Reference
/// See <https://discord.com/developers/docs/resources/channel#delete-own-reaction>
pub async fn remove(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
@ -148,17 +138,15 @@ impl ReactionMeta {
chorus_request.handle_request_as_result(user).await
}
/// Delete a user's reaction to a message.
/// This endpoint requires the MANAGE_MESSAGES permission to be present on the current user.
/// # Arguments
/// * `user_id` - ID of the user whose reaction is to be deleted.
/// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or
/// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
/// format name:id with the emoji name and emoji id.
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// # Returns
/// A [`ChorusResult`] containing [`()`] or a [`crate::errors::ChorusError`].
/// Deletes a user's reaction to a message.
///
/// This endpoint requires the MANAGE_MESSAGES permission.
///
/// The reaction emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
/// To use custom emoji, the format of the emoji string must be name:id.
///
/// Fires a Message Reaction Remove Gateway event.
///
/// # Reference
/// See <https://discord.com/developers/docs/resources/channel#delete-user-reaction>
pub async fn delete_user(

71
src/api/guilds/guilds.rs
View File

@ -11,22 +11,7 @@ use crate::types::Snowflake;
use crate::types::{Channel, ChannelCreateSchema, Guild, GuildCreateSchema};
impl Guild {
/// Creates a new guild with the given parameters.
///
/// # Arguments
///
/// * `user` - A mutable reference to the user creating the guild.
/// * `instance` - A mutable reference to the instance where the guild will be created.
/// * `guild_create_schema` - A reference to the schema containing the guild creation parameters.
///
/// # Returns
///
/// A `Result<Guild>` containing the object of the newly created guild, or an error if the request fails.
///
/// # Errors
///
/// Returns an `ChorusLibError` if the request fails.
///
/// Creates a new guild.
pub async fn create(
user: &mut UserMeta,
guild_create_schema: GuildCreateSchema,
@ -42,17 +27,7 @@ impl Guild {
chorus_request.deserialize_response::<Guild>(user).await
}
/// Deletes a guild.
///
/// # Arguments
///
/// * `user` - A mutable reference to a `User` instance.
/// * `instance` - A mutable reference to an `Instance` instance.
/// * `guild_id` - ID of the guild to delete.
///
/// # Returns
///
/// An `Result` containing an `ChorusLibError` if an error occurred during the request, otherwise `()`.
/// Deletes a guild by its id.
///
/// # Example
///
@ -61,9 +36,9 @@ impl Guild {
/// let mut instance = Instance::new();
/// let guild_id = String::from("1234567890");
///
/// match Guild::delete(&mut user, &mut instance, guild_id) {
/// Some(e) => println!("Error deleting guild: {:?}", e),
/// None => println!("Guild deleted successfully"),
/// match Guild::delete(&mut user, guild_id) {
/// Err(e) => println!("Error deleting guild: {:?}", e),
/// Ok(_) => println!("Guild deleted successfully"),
/// }
/// ```
pub async fn delete(user: &mut UserMeta, guild_id: Snowflake) -> ChorusResult<()> {
@ -81,19 +56,7 @@ impl Guild {
chorus_request.handle_request_as_result(user).await
}
/// Sends a request to create a new channel in the guild.
///
/// # Arguments
///
/// * `url_api` - The base URL for the Discord API.
/// * `token` - A Discord bot token.
/// * `schema` - A `ChannelCreateSchema` struct containing the properties of the new channel.
/// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits.
/// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits.
///
/// # Returns
///
/// A `Result` containing a `reqwest::Response` if the request was successful, or an `ChorusLibError` if there was an error.
/// Creates a new channel in a guild.
pub async fn create_channel(
&self,
user: &mut UserMeta,
@ -102,15 +65,7 @@ impl Guild {
Channel::create(user, self.id, schema).await
}
/// Returns a `Result` containing a vector of `Channel` structs if the request was successful, or an `ChorusLibError` if there was an error.
///
/// # Arguments
///
/// * `url_api` - A string slice that holds the URL of the API.
/// * `token` - A string slice that holds the authorization token.
/// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits.
/// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits.
///
// TODO: Docs: What is this endpoint?
pub async fn channels(&self, user: &mut UserMeta) -> ChorusResult<Vec<Channel>> {
let chorus_request = ChorusRequest {
request: Client::new()
@ -141,16 +96,8 @@ impl Guild {
};
}
/// Returns a `Result` containing a `Guild` struct if the request was successful, or an `ChorusLibError` if there was an error.
///
/// # Arguments
///
/// * `url_api` - A string slice that holds the URL of the API.
/// * `guild_id` - ID of the guild.
/// * `token` - A string slice that holds the authorization token.
/// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits.
/// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits.
///
// TODO: Check if these docs are correct, Im not sure what this endpoint is
/// Fetches a given guild.
pub async fn get(guild_id: Snowflake, user: &mut UserMeta) -> ChorusResult<Guild> {
let chorus_request = ChorusRequest {
request: Client::new()