mzrs-sdk 0.1.21

//! Clan-scoped handle.

use mzrs_proto::realtime as rt;

use crate::client::MzrsClient;
use crate::error::SdkError;
use crate::handles::ChannelHandle;

/// A handle scoped to a single clan.
///
/// Created via [`MzrsClient::clan`]. All operations performed through this
/// handle automatically supply the clan ID.
///
/// # Example
///
/// ```rust,ignore
/// let clan = client.clan("123456");
/// clan.join_chat().await?;
/// let ch = clan.channel("789012");
/// ch.send_text("Hello!").await?;
/// ```
#[derive(Clone)]
pub struct ClanHandle {
    client: MzrsClient,
    clan_id: String,
}

impl ClanHandle {
    /// Create a new clan handle (called internally by [`MzrsClient::clan`]).
    pub(crate) fn new(client: MzrsClient, clan_id: String) -> Self {
        Self { client, clan_id }
    }

    /// Return the clan ID.
    pub fn id(&self) -> &str {
        &self.clan_id
    }

    /// Return a reference to the underlying client.
    pub fn client(&self) -> &MzrsClient {
        &self.client
    }

    /// Join the clan chat stream.
    #[tracing::instrument(skip(self), fields(clan_id = %self.clan_id))]
    pub async fn join_chat(&self) -> Result<rt::ClanJoin, SdkError> {
        self.client.join_clan_chat(&self.clan_id).await
    }

    /// Update current user's profile inside this clan.
    ///
    /// Fields left as `None` are not changed.
    #[tracing::instrument(skip(self, nick_name, avatar))]
    pub async fn update_my_profile(
        &self,
        nick_name: Option<String>,
        avatar: Option<String>,
    ) -> Result<(), SdkError> {
        self.client
            .update_clan_profile(&self.clan_id, nick_name, avatar)
            .await
    }

    /// Update only current user's avatar inside this clan profile.
    #[tracing::instrument(skip(self, avatar))]
    pub async fn update_my_profile_avatar(&self, avatar: Option<String>) -> Result<(), SdkError> {
        self.client
            .update_clan_profile_avatar(&self.clan_id, avatar)
            .await
    }

    /// Create a [`ChannelHandle`] within this clan.
    pub fn channel(&self, channel_id: impl Into<String>) -> ChannelHandle {
        ChannelHandle::new(self.client.clone(), self.clan_id.clone(), channel_id.into())
    }
}