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

Moar docs

This commit is contained in:
kozabrada123 2023-07-29 10:23:04 +02:00
parent 8eb2e2008c
commit 83d4ffc4e8
11 changed files with 70 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -114,20 +114,7 @@ impl Guild {
}
impl Channel {
/// Sends a request to create a new channel in a guild.
///
/// # Arguments
///
/// * `token` - A Discord bot token.
/// * `url_api` - The base URL for the Discord API.
/// * `guild_id` - The ID of the guild where the channel will be created.
/// * `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(
user: &mut UserMeta,
guild_id: Snowflake,

34
src/api/guilds/member.rs
View File

@ -9,17 +9,7 @@ use crate::{
};
impl types::GuildMember {
/// Retrieves a guild member by their ID.
///
/// # Arguments
///
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// * `guild_id` - The ID of the guild.
/// * `member_id` - The ID of the member.
///
/// # Returns
///
/// A [`ChorusResult`] containing a [`GuildMember`] if the request succeeds.
/// Retrieves a guild member.
pub async fn get(
user: &mut UserMeta,
guild_id: Snowflake,
@ -41,17 +31,6 @@ impl types::GuildMember {
}
/// Adds a role to a guild member.
///
/// # Arguments
///
/// * `user` - A mutable reference to a `UserMeta` instance.
/// * `guild_id` - The ID of the guild.
/// * `member_id` - The ID of the member.
/// * `role_id` - The ID of the role to add.
///
/// # Returns
///
/// A [`ChorusResult`] containing a [`crate::errors::ChorusError`] if the request fails, or `()` if the request succeeds.
pub async fn add_role(
user: &mut UserMeta,
guild_id: Snowflake,
@ -73,17 +52,6 @@ impl types::GuildMember {
}
/// Removes a role from a guild member.
///
/// # Arguments
///
/// * `user` - A mutable reference to a `UserMeta` instance.
/// * `guild_id` - The ID of the guild.
/// * `member_id` - The ID of the member.
/// * `role_id` - The ID of the role to remove.
///
/// # Returns
///
/// A [`ChorusResult`] containing a [`crate::errors::ChorusError`] if the request fails, or `()` if the request succeeds.
pub async fn remove_role(
user: &mut UserMeta,
guild_id: Snowflake,

54
src/api/guilds/roles.rs
View File

@ -10,16 +10,9 @@ use crate::{
};
impl types::RoleObject {
/// Retrieves all roles for a given guild.
/// Retrieves a list of roles for a given guild.
///
/// # Arguments
///
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// * `guild_id` - The ID of the guild to retrieve roles from.
///
/// # Returns
///
/// An `Option` containing a `Vec` of [`RoleObject`]s if roles were found, or `None` if no roles were found.
/// Returns Ok(None) if the guild has no roles.
pub async fn get_all(
user: &mut UserMeta,
guild_id: Snowflake,
@ -44,16 +37,6 @@ impl types::RoleObject {
}
/// Retrieves a single role for a given guild.
///
/// # Arguments
///
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// * `guild_id` - The ID of the guild to retrieve the role from.
/// * `role_id` - The ID of the role to retrieve.
///
/// # Returns
///
/// A `Result` containing the retrieved [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid.
pub async fn get(
user: &mut UserMeta,
guild_id: Snowflake,
@ -75,16 +58,6 @@ impl types::RoleObject {
}
/// Creates a new role for a given guild.
///
/// # Arguments
///
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// * `guild_id` - The ID of the guild to create the role in.
/// * `role_create_schema` - A [`RoleCreateModifySchema`] instance containing the properties of the role to be created.
///
/// # Returns
///
/// A `Result` containing the newly created [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid.
pub async fn create(
user: &mut UserMeta,
guild_id: Snowflake,
@ -109,17 +82,7 @@ impl types::RoleObject {
.await
}
/// Updates the position of a role in the guild's hierarchy.
///
/// # Arguments
///
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// * `guild_id` - The ID of the guild to update the role position in.
/// * `role_position_update_schema` - A [`RolePositionUpdateSchema`] instance containing the new position of the role.
///
/// # Returns
///
/// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid.
/// Updates the position of a role in a given guild's hierarchy.
pub async fn position_update(
user: &mut UserMeta,
guild_id: Snowflake,
@ -147,17 +110,6 @@ impl types::RoleObject {
}
/// Updates a role in a guild.
///
/// # Arguments
///
/// * `user` - A mutable reference to a [`UserMeta`] instance.
/// * `guild_id` - The ID of the guild to update the role in.
/// * `role_id` - The ID of the role to update.
/// * `role_create_schema` - A [`RoleCreateModifySchema`] instance containing the new properties of the role.
///
/// # Returns
///
/// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid.
pub async fn update(
user: &mut UserMeta,
guild_id: Snowflake,

23
src/api/invites/mod.rs
View File

@ -7,9 +7,11 @@ use crate::ratelimiter::ChorusRequest;
use crate::types::{CreateChannelInviteSchema, GuildInvite, Invite, Snowflake};
impl UserMeta {
/// # Arguments
/// - invite_code: The invite code to accept the invite for.
/// - session_id: The session ID that is accepting the invite, required for guest invites.
/// Accepts an invite to a guild, group DM, or DM.
///
/// Note that the session ID is required for guest invites.
///
/// May fire a Guild Create, Channel Create, and/or Relationship Add Gateway event.
///
/// # Reference:
/// Read <https://discord-userdoccers.vercel.app/resources/invite#accept-invite>
@ -35,7 +37,13 @@ impl UserMeta {
}
request.deserialize_response::<Invite>(self).await
}
/// Creates a new friend invite.
///
/// Note: Spacebar does not yet implement this endpoint.
///
/// # Reference:
/// Read <https://discord-userdoccers.vercel.app/resources/invite#create-user-invite>
pub async fn create_user_invite(&mut self, code: Option<&str>) -> ChorusResult<Invite> {
ChorusRequest {
request: Client::new()
@ -51,7 +59,14 @@ impl UserMeta {
.await
}
pub async fn create_guild_invite(
/// Creates a new invite for a guild channel or group DM.
///
/// # Guild Channels
/// For guild channels, the endpoint
/// requires the CREATE_INSTANT_INVITE permission.
///
/// Guild channel invites also fire an Invite Create Gateway event.
pub async fn create_channel_invite(
&mut self,
create_channel_invite_schema: CreateChannelInviteSchema,
channel_id: Snowflake,

2
src/api/policies/instance/instance.rs
View File

@ -6,8 +6,6 @@ use crate::types::GeneralConfiguration;
impl Instance {
/// Gets the instance policies schema.
/// # Errors
/// [`ChorusError`] - If the request fails.
pub async fn general_configuration_schema(&self) -> ChorusResult<GeneralConfiguration> {
let endpoint_url = self.urls.api.clone() + "/policies/instance/";
let request = match self.client.get(&endpoint_url).send().await {

4
src/api/users/guilds.rs
View File

@ -7,11 +7,11 @@ use crate::ratelimiter::ChorusRequest;
use crate::types::Snowflake;
impl UserMeta {
/// # Arguments:
/// - lurking: Whether the user is lurking in the guild
/// Leaves a given guild.
///
/// # Reference:
/// Read <https://discord-userdoccers.vercel.app/resources/guild#leave-guild>
// TODO: Docs: What is lurking here?
pub async fn leave_guild(&mut self, guild_id: &Snowflake, lurking: bool) -> ChorusResult<()> {
ChorusRequest {
request: Client::new()

49
src/api/users/relationships.rs
View File

@ -12,14 +12,10 @@ use crate::{
};
impl UserMeta {
/// Retrieves the mutual relationships between the authenticated user and the specified user.
/// Retrieves a list of mutual friends between the authenticated user and a given user.
///
/// # Arguments
///
/// * `user_id` - ID of the user to retrieve the mutual relationships with.
///
/// # Returns
/// This function returns a [`ChorusResult<Vec<PublicUser>>`].
/// # Reference
/// See <https://luna.gitlab.io/discord-unofficial-docs/relationships.html#get-users-peer-id-relationships>
pub async fn get_mutual_relationships(
&mut self,
user_id: Snowflake,
@ -38,10 +34,10 @@ impl UserMeta {
.await
}
/// Retrieves the authenticated user's relationships.
/// Retrieves the user's relationships.
///
/// # Returns
/// This function returns a [`ChorusResult<Vec<types::Relationship>>`].
/// # Reference
/// See <https://luna.gitlab.io/discord-unofficial-docs/relationships.html#get-users-me-relationships>
pub async fn get_relationships(&mut self) -> ChorusResult<Vec<types::Relationship>> {
let url = format!(
"{}/users/@me/relationships/",
@ -58,12 +54,8 @@ impl UserMeta {
/// Sends a friend request to a user.
///
/// # Arguments
///
/// * `schema` - A [`FriendRequestSendSchema`] struct that holds the information about the friend request to be sent.
///
/// # Returns
/// This function returns a [`ChorusResult`].
/// # Reference
/// See <https://luna.gitlab.io/discord-unofficial-docs/relationships.html#post-users-me-relationships>
pub async fn send_friend_request(
&mut self,
schema: FriendRequestSendSchema,
@ -80,20 +72,9 @@ impl UserMeta {
chorus_request.handle_request_as_result(self).await
}
/// Modifies the relationship between the authenticated user and the specified user.
/// Modifies the relationship between the authenticated user and a given user.
///
/// # Arguments
///
/// * `user_id` - ID of the user to modify the relationship with.
/// * `relationship_type` - A [`RelationshipType`] enum that specifies the type of relationship to modify.
/// * [`RelationshipType::None`]: Removes the relationship between the two users.
/// * [`RelationshipType::Friends`] | [`RelationshipType::Incoming`] | [`RelationshipType::Outgoing`]:
/// Either accepts an incoming friend request, or sends a new friend request, if there is no
/// incoming friend request from the specified `user_id`.
/// * [`RelationshipType::Blocked`]: Blocks the specified user_id.
///
/// # Returns
/// This function returns an [`ChorusResult`].
/// Can be used to unfriend users, accept or send friend requests and block or unblock users.
pub async fn modify_user_relationship(
&mut self,
user_id: Snowflake,
@ -144,14 +125,10 @@ impl UserMeta {
}
}
/// Removes the relationship between the authenticated user and the specified user.
/// Removes the relationship between the authenticated user and a given user.
///
/// # Arguments
///
/// * `user_id` - ID of the user to remove the relationship with.
///
/// # Returns
/// This function returns a [`ChorusResult`].
/// # Reference
/// See <https://luna.gitlab.io/discord-unofficial-docs/relationships.html#delete-users-me-relationships-peer-id>
pub async fn remove_relationship(&mut self, user_id: Snowflake) -> ChorusResult<()> {
let url = format!(
"{}/users/@me/relationships/{}/",

51
src/api/users/users.rs
View File

@ -12,21 +12,18 @@ use crate::{
};
impl UserMeta {
/// Get a user object by id, or get the current user.
/// Gets a user by id, or if the id is None, gets the current user.
///
/// # Arguments
///
/// * `token` - A valid access token for the API.
/// * `url_api` - The URL to the API.
/// * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved.
///
/// # Errors
///
/// * [`ChorusError`] - If the request fails.
/// # Notes
/// This function is a wrapper around [`User::get`].
pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult<User> {
User::get(user, id).await
}
/// Gets the user's settings.
///
/// # Notes
/// This functions is a wrapper around [`User::get_settings`].
pub async fn get_settings(
token: &String,
url_api: &String,
@ -35,15 +32,7 @@ impl UserMeta {
User::get_settings(token, url_api, instance).await
}
/// Modify the current user's `UserObject`.
///
/// # Arguments
///
/// * `modify_schema` - A `UserModifySchema` object containing the fields to modify.
///
/// # Errors
///
/// Returns an [`ChorusError`] if the request fails or if a password is required but not provided.
/// Modifies the current user's representation. (See [`User`])
pub async fn modify(&mut self, modify_schema: UserModifySchema) -> ChorusResult<User> {
if modify_schema.new_password.is_some()
|| modify_schema.email.is_some()
@ -67,15 +56,7 @@ impl UserMeta {
Ok(user_updated)
}
/// Sends a request to the server which deletes the user from the Instance.
///
/// # Arguments
///
/// * `self` - The `User` object to delete.
///
/// # Returns
///
/// Returns `()` if the user was successfully deleted, or a [`ChorusError`] if an error occurred.
/// Deletes the user from the Instance.
pub async fn delete(mut self) -> ChorusResult<()> {
let request = Client::new()
.post(format!(
@ -92,6 +73,7 @@ impl UserMeta {
}
impl User {
/// Gets a user by id, or if the id is None, gets the current user.
pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult<User> {
let url_api = user.belongs_to.borrow().urls.api.clone();
let url = if id.is_none() {
@ -113,6 +95,7 @@ impl User {
}
}
/// Gets the user's settings.
pub async fn get_settings(
token: &String,
url_api: &String,
@ -140,14 +123,10 @@ impl User {
}
impl Instance {
// Get a user object by id, or get the current user.
// # Arguments
// * `token` - A valid access token for the API.
// * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved.
// # Errors
// * [`ChorusError`] - If the request fails.
// # Notes
// This function is a wrapper around [`User::get`].
/// Gets a user by id, or if the id is None, gets the current user.
///
/// # Notes
/// This function is a wrapper around [`User::get`].
pub async fn get_user(&mut self, token: String, id: Option<&String>) -> ChorusResult<User> {
let mut user = UserMeta::shell(Rc::new(RefCell::new(self.clone())), token).await;
let result = User::get(&mut user, id).await;

8
src/instance.rs
View File

@ -83,6 +83,9 @@ impl fmt::Display for Token {
}
#[derive(Debug)]
/// A UserMeta is a representation of an authenticated user on an [Instance].
/// It is used for most authenticated actions on a Spacebar server.
/// It also has its own [Gateway] connection.
pub struct UserMeta {
pub belongs_to: Rc<RefCell<Instance>>,
pub token: String,
@ -101,6 +104,11 @@ impl UserMeta {
self.token = token;
}
/// Creates a new [UserMeta] from existing data.
///
/// # Notes
/// This isn't the prefered way to create a UserMeta.
/// See [Instance::login_account] and [Instance::register_account] instead.
pub fn new(
belongs_to: Rc<RefCell<Instance>>,
token: String,

13
src/lib.rs
View File

@ -16,8 +16,8 @@ pub mod types;
pub mod voice;
#[derive(Clone, Default, Debug, PartialEq, Eq)]
/// A URLBundle is a struct which bundles together the API-, Gateway- and CDN-URLs of a Spacebar
/// instance.
/// A URLBundle bundles together the API-, Gateway- and CDN-URLs of a Spacebar instance.
///
/// # Notes
/// All the urls can be found on the /api/policies/instance/domains endpoint of a spacebar server
pub struct UrlBundle {
@ -25,7 +25,7 @@ pub struct UrlBundle {
/// Ex: `https://old.server.spacebar.chat/api`
pub api: String,
/// The gateway websocket url.
/// Note that because this is a websocket url, it will always start with `wss://`
/// Note that because this is a websocket url, it will always start with `wss://` or `ws://`
/// Ex: `wss://gateway.old.server.spacebar.chat`
pub wss: String,
/// The CDN's url.
@ -42,9 +42,10 @@ impl UrlBundle {
}
}
/// parse(url: String) parses a URL using the Url library and formats it in a standardized
/// way. If no protocol is given, HTTP (not HTTPS) is assumed.
/// # Example:
/// Parses a URL using the Url library and formats it in a standardized way.
/// If no protocol is given, HTTP (not HTTPS) is assumed.
///
/// # Examples:
/// ```rs
/// let url = parse_url("localhost:3000");
/// ```

2
tests/invites.rs
View File

@ -11,7 +11,7 @@ async fn create_accept_invite() {
.await
.is_err());
let invite = user
.create_guild_invite(create_channel_invite_schema, channel.id)
.create_channel_invite(create_channel_invite_schema, channel.id)
.await
.unwrap();