Moar docs
This commit is contained in:
parent
8eb2e2008c
commit
83d4ffc4e8
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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 {
|
||||
|
|
|
@ -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()
|
||||
|
|
|
@ -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/{}/",
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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
13
src/lib.rs
|
@ -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");
|
||||
/// ```
|
||||
|
|
|
@ -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();
|
||||
|
||||
|
|
Loading…
Reference in New Issue