zulip-api 0.0.8

//! Zulip API client.

use crate::api::{ApiKey, User};
use crate::error::Error;
use crate::result::Result;
use crate::{
    delete_message, edit_message, emoji_reaction, fetch_api_key, get_file_temporary_url,
    get_message, get_message_history, get_messages, get_read_receipts, mark_all_as_read,
    mark_stream_as_read, mark_topic_as_read, matches_narrow, register, render, report_message,
    send_message, update_message_flags, update_message_flags_narrow, upload_file, version,
};

mod endpoint;
mod tus;

pub use endpoint::Endpoint;

/// Represents the HTTP request timeout.
pub const TIMEOUT: u64 = 5;

/// Represents the main client for interacting with Zulip servers.
#[derive(Clone, Debug)]
pub struct Client {
    http: reqwest::Client,
    url: hyper::Uri,
    user: User,
    key: ApiKey,
}

impl Client {
    /// Creates a new [Client] from the provided Zulip server URL.
    pub fn new(url: hyper::Uri, user: User, key: ApiKey) -> Result<Self> {
        Ok(Self {
            http: Self::http_client()?,
            url,
            user,
            key,
        })
    }

    /// Builder function that sets the HTTP client.
    pub fn with_http(self, http: reqwest::Client) -> Self {
        Self { http, ..self }
    }

    /// Attempts to read [Client] configuration from a `zuliprc` INI file.
    pub fn from_zuliprc(path: &str) -> Result<Self> {
        let cfg = ini!(path);

        let url = cfg["api"]["site"]
            .as_deref()
            .ok_or(Error::io_other("missing zuliprc `site`"))
            .and_then(|u| u.parse().map_err(|err| Error::io_other(format!("{err}"))))?;

        let user = cfg["api"]["email"]
            .as_deref()
            .map(User::from)
            .ok_or(Error::io_other("missing zuliprc `email`"))?;

        let key = cfg["api"]["key"]
            .as_deref()
            .map(ApiKey::from)
            .ok_or(Error::io_other("missing zuliprc `key`"))?;

        Self::new(url, user, key)
    }

    /// Creates a HTTP client for making requests to the Zulip API server.
    pub fn http_client() -> Result<reqwest::Client> {
        let builder = reqwest::Client::builder().user_agent(Self::user_agent());

        #[cfg(target_family = "wasm")]
        {
            builder.build().map_err(Error::from)
        }
        #[cfg(all(not(target_family = "wasm"), feature = "dev"))]
        {
            builder
                .danger_accept_invalid_certs(true)
                .timeout(std::time::Duration::from_secs(TIMEOUT))
                .use_rustls_tls()
                .build()
                .map_err(Error::from)
        }
        #[cfg(all(not(target_family = "wasm"), not(feature = "dev")))]
        {
            builder
                .timeout(std::time::Duration::from_secs(TIMEOUT))
                .use_rustls_tls()
                .build()
                .map_err(Error::from)
        }
    }

    /// Gets the [Client]'s `UserAgent`.
    pub fn user_agent() -> String {
        format!("ZulipRust/{}", version())
    }

    /// Gets the `Authorization` header.
    pub fn auth_header(&self) -> String {
        use base64::{Base64, Encoding};

        let b64 = Base64::encode_string(
            format!("{}:{}", self.user.as_str(), self.key.as_str()).as_bytes(),
        );

        format!("Basic {b64}")
    }

    /// Loads a page from the Zulip.
    ///
    /// - `path`: optional path of the page to load, empty string loads the base path
    pub async fn load_page(&self, path: &str) -> Result<String> {
        let url = if path.is_empty() {
            self.base_url()
        } else {
            format!("{}/{path}", self.base_url())
        };

        let res = self
            .http
            .get(url)
            .header("Authorization", self.auth_header())
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Send message response: {body}");

        Ok(body.into())
    }

    /// Sends a message to the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::send_message;
    /// use zulip_api::message::{MessageTo, MessageType};
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = send_message::Request::new()
    ///     .with_msg_type(MessageType::Channel)
    ///     .with_topic("test topic")
    ///     .with_to(MessageTo::ChannelName("general".into()))
    ///     .with_content("test message".to_string());
    ///
    /// let res = client.send_message(&req).await.unwrap();
    ///
    /// println!("Send message response: {res:?}");
    /// # };
    /// ```
    pub async fn send_message(
        &self,
        msg: &send_message::Request,
    ) -> Result<send_message::Response> {
        let res = self
            .http
            .post(self.endpoint(Endpoint::SendMessage))
            .header("Authorization", self.auth_header())
            .form(msg)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Send message response: {body}");

        serde_json::from_str::<send_message::Response>(body).map_err(Error::from)
    }

    /// Gets a list of messages from the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::get_messages;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = get_messages::Request::new();
    /// let res = client.get_messages(&req).await.unwrap();
    ///
    /// println!("Get messages response: {res:?}");
    /// # };
    /// ```
    pub async fn get_messages(
        &self,
        req: &get_messages::Request,
    ) -> Result<get_messages::Response> {
        let res = self
            .http
            .get(self.endpoint(Endpoint::GetMessages))
            .header("Authorization", self.auth_header())
            .query(req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Get messages response: {body}");

        serde_json::from_str::<get_messages::Response>(body).map_err(Error::from)
    }

    /// Uploads a file to the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::upload_file;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = upload_file::Request::new().with_file_path("/path/to/file.txt");
    /// let res = client.upload_file(&req).await.unwrap();
    ///
    /// println!("Upload file response: {res}");
    /// # };
    /// ```
    pub async fn upload_file(&self, req: &upload_file::Request) -> Result<upload_file::Response> {
        let file_path = req.file_path();
        let md = std::fs::metadata(file_path)?;
        let file_len = md.len() as usize;
        let max_file_len = upload_file::LARGE_FILE;

        if file_len >= max_file_len {
            self.tus_create_and_upload(file_path).await
        } else {
            log::debug!("Sending {file_path}, length: {file_len} using the normal upload");

            let form = reqwest::multipart::Form::new()
                .file("filename", file_path)
                .await?;

            let res = self
                .http
                .post(self.endpoint(Endpoint::UploadFile))
                .header("Authorization", self.auth_header())
                .multipart(form)
                .send()
                .await?;

            let bytes = res.bytes().await?;
            let body = str::from_utf8(&bytes[..])?;

            log::debug!("Upload file response: {body}");

            serde_json::from_str::<upload_file::Response>(body).map_err(Error::from)
        }
    }

    /// Get a temporary URL for access to an [uploaded file](https://zulip.com/api/upload-file) that doesn't require authentication.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::{get_file_temporary_url, upload_file};
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = upload_file::Request::new().with_file_path("/path/to/file.txt");
    /// let res = client.upload_file(&req).await.unwrap();
    ///
    /// println!("Upload file response: {res}");
    ///
    /// let req = get_file_temporary_url::Request::new()
    ///     .with_realm_id(res.realm_id().unwrap())
    ///     .with_filename(res.filename_path().unwrap());
    ///
    /// let res = client.get_file_temporary_url(&req).await.unwrap();
    ///
    /// println!("Get file temporary URL response: {res}");
    /// # };
    /// ```
    pub async fn get_file_temporary_url(
        &self,
        req: &get_file_temporary_url::Request,
    ) -> Result<get_file_temporary_url::Response> {
        let endpoint = self.endpoint(Endpoint::UploadFile);
        let realm_id = req.realm_id();
        let filename = req.filename();

        let res = self
            .http
            .get(format!("{endpoint}/{realm_id}/{filename}"))
            .header("Authorization", self.auth_header())
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Upload file response: {body}");

        serde_json::from_str::<get_file_temporary_url::Response>(body).map_err(Error::from)
    }

    /// Edit a message on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::edit_message;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = edit_message::Request::new()
    ///     .with_message_id(1)
    ///     .with_content("edited content");
    ///
    /// let res = client.edit_message(&req).await.unwrap();
    ///
    /// println!("Edit message response: {res:?}");
    /// # };
    /// ```
    pub async fn edit_message(
        &self,
        req: &edit_message::Request,
    ) -> Result<edit_message::Response> {
        let endpoint = self.endpoint(Endpoint::EditMessage);
        let msg_id = req.message_id();

        let res = self
            .http
            .patch(format!("{endpoint}/{msg_id}"))
            .header("Authorization", self.auth_header())
            .form(req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Edit message response: {body}");

        serde_json::from_str::<edit_message::Response>(body).map_err(Error::from)
    }

    /// Delete a message on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::delete_message;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = delete_message::Request::new()
    ///     .with_message_id(1);
    ///
    /// let res = client.delete_message(&req).await.unwrap();
    ///
    /// println!("Delete message response: {res:?}");
    /// # };
    /// ```
    pub async fn delete_message(
        &self,
        req: &delete_message::Request,
    ) -> Result<delete_message::Response> {
        let endpoint = self.endpoint(Endpoint::DeleteMessage);
        let msg_id = req.message_id();

        let res = self
            .http
            .delete(format!("{endpoint}/{msg_id}"))
            .header("Authorization", self.auth_header())
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Delete message response: {body}");

        serde_json::from_str::<delete_message::Response>(body).map_err(Error::from)
    }

    /// Gets a message on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::get_message;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = get_message::Request::new()
    ///     .with_message_id(1);
    ///
    /// let res = client.get_message(&req).await.unwrap();
    ///
    /// println!("Get message response: {res:?}");
    /// # };
    /// ```
    pub async fn get_message(&self, req: &get_message::Request) -> Result<get_message::Response> {
        let endpoint = self.endpoint(Endpoint::GetMessage);
        let msg_id = req.message_id();

        let res = self
            .http
            .get(format!("{endpoint}/{msg_id}"))
            .header("Authorization", self.auth_header())
            .query(&req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Get message response: {body}");

        serde_json::from_str::<get_message::Response>(body).map_err(Error::from)
    }

    /// Gets a message edit history on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::get_message_history;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = get_message_history::Request::new()
    ///     .with_message_id(1);
    ///
    /// let res = client.get_message_history(&req).await.unwrap();
    ///
    /// println!("Get message history response: {res:?}");
    /// # };
    /// ```
    pub async fn get_message_history(
        &self,
        req: &get_message_history::Request,
    ) -> Result<get_message_history::Response> {
        let endpoint = self.endpoint(Endpoint::GetMessageHistory);
        let msg_id = req.message_id();

        let res = self
            .http
            .get(format!("{endpoint}/{msg_id}/history"))
            .header("Authorization", self.auth_header())
            .query(&req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Get message history response: {body}");

        serde_json::from_str::<get_message_history::Response>(body).map_err(Error::from)
    }

    /// Reports a message for moderation on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::{report_message, ReportType};
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = report_message::Request::new()
    ///     .with_message_id(1)
    ///     .with_report_type(ReportType::Other)
    ///     .with_description("This message insults and mocks Frodo, which is against the code of conduct.");
    ///
    /// let res = client.report_message(&req).await.unwrap();
    ///
    /// println!("Report message response: {res:?}");
    /// # };
    /// ```
    pub async fn report_message(
        &self,
        req: &report_message::Request,
    ) -> Result<report_message::Response> {
        let endpoint = self.endpoint(Endpoint::ReportMessage);
        let msg_id = req.message_id();

        let mut form = reqwest::multipart::Form::new().text("report_type", req.report_type());

        if let Some(description) = req.description() {
            form = form.text("description", description.to_string());
        }

        let res = self
            .http
            .post(format!("{endpoint}/{msg_id}/report"))
            .header("Authorization", self.auth_header())
            .multipart(form)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Get message response: {body}");

        serde_json::from_str::<report_message::Response>(body).map_err(Error::from)
    }

    /// Gets narrow matches on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::filter::{Narrow, Operand, Operator};
    /// use zulip_api::matches_narrow;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let msg_ids = [1u64];
    /// let narrow = [Narrow::new()
    ///     .with_operator(Operator::Has)
    ///     .with_operand(Operand::text("link"))];
    ///
    /// let req = matches_narrow::Request::new()
    ///     .with_msg_ids(msg_ids.as_ref())
    ///     .with_narrow(narrow.as_ref());
    ///
    /// let res = client.matches_narrow(&req).await.unwrap();
    ///
    /// println!("Matches narrow response: {res:?}");
    /// # };
    /// ```
    pub async fn matches_narrow(
        &self,
        req: &matches_narrow::Request,
    ) -> Result<matches_narrow::Response> {
        let res = self
            .http
            .get(self.endpoint(Endpoint::MatchesNarrow))
            .header("Authorization", self.auth_header())
            .query(&[("msg_ids", serde_json::to_string(req.msg_ids())?)])
            .query(&[("narrow", serde_json::to_string(req.narrow())?)])
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Matches narrow response: {body}");

        serde_json::from_str::<matches_narrow::Response>(body).map_err(Error::from)
    }

    /// Adds an emoji reaction to a message on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::emoji_reaction;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = emoji_reaction::Request::new()
    ///     .with_message_id(1)
    ///     .with_emoji_name("+1");
    ///
    /// let res = client.add_reaction(&req).await.unwrap();
    ///
    /// println!("Add emoji reaction response: {res:?}");
    /// # };
    /// ```
    pub async fn add_reaction(
        &self,
        req: &emoji_reaction::Request,
    ) -> Result<emoji_reaction::Response> {
        let url = format!(
            "{}/{}/reactions",
            self.endpoint(Endpoint::Reaction),
            req.message_id()
        );

        let res = self
            .http
            .post(url)
            .header("Authorization", self.auth_header())
            .form(req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Add emoji reaction response: {body}");

        serde_json::from_str::<emoji_reaction::Response>(body).map_err(Error::from)
    }

    /// Removes an emoji reaction from a message on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::emoji_reaction;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = emoji_reaction::Request::new()
    ///     .with_message_id(1)
    ///     .with_emoji_name("+1");
    ///
    /// let res = client.remove_reaction(&req).await.unwrap();
    ///
    /// println!("Remove emoji reaction response: {res:?}");
    /// # };
    /// ```
    pub async fn remove_reaction(
        &self,
        req: &emoji_reaction::Request,
    ) -> Result<emoji_reaction::Response> {
        let url = format!(
            "{}/{}/reactions",
            self.endpoint(Endpoint::Reaction),
            req.message_id()
        );

        let res = self
            .http
            .delete(url)
            .header("Authorization", self.auth_header())
            .form(req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Remove emoji reaction response: {body}");

        serde_json::from_str::<emoji_reaction::Response>(body).map_err(Error::from)
    }

    /// Renders a message from the Zulip server into HTML.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::render;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = render::Request::new()
    ///     .with_content("test message");
    ///
    /// let res = client.render(&req).await.unwrap();
    ///
    /// println!("Render response: {res:?}");
    /// # };
    /// ```
    pub async fn render(&self, req: &render::Request) -> Result<render::Response> {
        let res = self
            .http
            .post(self.endpoint(Endpoint::Render))
            .header("Authorization", self.auth_header())
            .form(req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Render response: {body}");

        serde_json::from_str::<render::Response>(body).map_err(Error::from)
    }

    /// Update message flags on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::{update_message_flags, Flag, Operation};
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = update_message_flags::Request::new()
    ///     .with_messages([1u64].as_ref())
    ///     .with_op(Operation::Add)
    ///     .with_flag(Flag::Read);
    ///
    /// let res = client.update_message_flags(&req).await.unwrap();
    ///
    /// println!("Update message flags response: {res}");
    /// # };
    /// ```
    pub async fn update_message_flags(
        &self,
        req: &update_message_flags::Request,
    ) -> Result<update_message_flags::Response> {
        let form = reqwest::multipart::Form::new()
            .text("messages", serde_json::to_string(req.messages())?)
            .text("op", req.op().as_str())
            .text("flag", req.flag().as_str());

        let res = self
            .http
            .post(self.endpoint(Endpoint::UpdateMessageFlags))
            .header("Authorization", self.auth_header())
            .multipart(form)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Update message flags response: {body}");

        serde_json::from_str::<update_message_flags::Response>(body).map_err(Error::from)
    }

    /// Update message flags for a narrow on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::{update_message_flags_narrow, Flag, Operation};
    /// use zulip_api::filter::{Anchor, Narrow};
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = update_message_flags_narrow::Request::new()
    ///     .with_anchor(Anchor::new())
    ///     .with_include_anchor(true)
    ///     .with_num_before(1)
    ///     .with_num_after(1)
    ///     .with_narrow(vec![Narrow::new()])
    ///     .with_op(Operation::Add)
    ///     .with_flag(Flag::Read);
    ///
    /// let res = client.update_message_flags_narrow(&req).await.unwrap();
    ///
    /// println!("Update message flags for narrow response: {res}");
    /// # };
    /// ```
    pub async fn update_message_flags_narrow(
        &self,
        req: &update_message_flags_narrow::Request,
    ) -> Result<update_message_flags_narrow::Response> {
        let mut form = reqwest::multipart::Form::new()
            .text("anchor", serde_json::to_string(&req.anchor())?)
            .text("num_before", format!("{}", req.num_before()))
            .text("num_after", format!("{}", req.num_after()))
            .text("narrow", serde_json::to_string(req.narrow())?)
            .text("op", req.op().as_str())
            .text("flag", req.flag().as_str());

        if let Some(include_anchor) = req.include_anchor() {
            form = form.text("include_anchor", format!("{include_anchor}"));
        }

        let res = self
            .http
            .post(self.endpoint(Endpoint::UpdateMessageFlagsNarrow))
            .header("Authorization", self.auth_header())
            .multipart(form)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Update message flags for narrow response: {body}");

        serde_json::from_str::<update_message_flags_narrow::Response>(body).map_err(Error::from)
    }

    /// Marks all messages as read on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let res = client.mark_all_as_read().await.unwrap();
    ///
    /// println!("Mark all as read response: {res:?}");
    /// # };
    /// ```
    pub async fn mark_all_as_read(&self) -> Result<mark_all_as_read::Response> {
        let res = self
            .http
            .post(self.endpoint(Endpoint::MarkAllAsRead))
            .header("Authorization", self.auth_header())
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Mark all as read response: {body}");

        serde_json::from_str::<mark_all_as_read::Response>(body).map_err(Error::from)
    }

    /// Marks all messages in a channel as read on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::mark_stream_as_read;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = mark_stream_as_read::Request::new().with_stream_id(1);
    ///
    /// let res = client.mark_stream_as_read(&req).await.unwrap();
    ///
    /// println!("Mark stream as read response: {res:?}");
    /// # };
    /// ```
    pub async fn mark_stream_as_read(
        &self,
        req: &mark_stream_as_read::Request,
    ) -> Result<mark_stream_as_read::Response> {
        let res = self
            .http
            .post(self.endpoint(Endpoint::MarkStreamAsRead))
            .header("Authorization", self.auth_header())
            .form(req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Mark stream as read response: {body}");

        serde_json::from_str::<mark_stream_as_read::Response>(body).map_err(Error::from)
    }

    /// Marks all messages in a topic as read on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::mark_topic_as_read;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = mark_topic_as_read::Request::new()
    ///     .with_stream_id(1)
    ///     .with_topic_name("test topic");
    ///
    /// let res = client.mark_topic_as_read(&req).await.unwrap();
    ///
    /// println!("Mark topic as read response: {res:?}");
    /// # };
    /// ```
    pub async fn mark_topic_as_read(
        &self,
        req: &mark_topic_as_read::Request,
    ) -> Result<mark_topic_as_read::Response> {
        let form = reqwest::multipart::Form::new()
            .text("stream_id", format!("{}", req.stream_id()))
            .text("topic_name", req.topic_name().to_string());

        let res = self
            .http
            .post(self.endpoint(Endpoint::MarkTopicAsRead))
            .header("Authorization", self.auth_header())
            .multipart(form)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Mark topic as read response: {body}");

        serde_json::from_str::<mark_topic_as_read::Response>(body).map_err(Error::from)
    }

    /// Gets a message's read receipts on the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::get_read_receipts;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = get_read_receipts::Request::new()
    ///     .with_message_id(1);
    ///
    /// let res = client.get_read_receipts(&req).await.unwrap();
    ///
    /// println!("Get read receipts response: {res:?}");
    /// # };
    /// ```
    pub async fn get_read_receipts(
        &self,
        req: &get_read_receipts::Request,
    ) -> Result<get_read_receipts::Response> {
        let endpoint = self.endpoint(Endpoint::GetMessage);
        let msg_id = req.message_id();

        let res = self
            .http
            .get(format!("{endpoint}/{msg_id}/read_receipts"))
            .header("Authorization", self.auth_header())
            .query(&req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Get read receipts response: {body}");

        serde_json::from_str::<get_read_receipts::Response>(body).map_err(Error::from)
    }

    /// Registers an event queue with the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::register;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let req = register::Request::new();
    ///
    /// let res = client.register(&req).await.unwrap();
    ///
    /// println!("Register response: {res:?}");
    /// # };
    /// ```
    pub async fn register(&self, req: &register::Request) -> Result<register::Response> {
        let res = self
            .http
            .post(self.endpoint(Endpoint::Register))
            .header("Authorization", self.auth_header())
            .json(req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Register response: {body}");

        serde_json::from_str::<register::Response>(body).map_err(Error::from)
    }

    /// Fetches a user's API key using a username-password authentication method with the Zulip server.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use zulip_api::client::Client;
    /// use zulip_api::fetch_api_key;
    ///
    /// # async {
    /// let client = Client::from_zuliprc(".zuliprc").unwrap();
    ///
    /// let algo = jwt::Algorithm::HS256;
    /// let key = jwt::EncodingKey::from_base64_secret("MWFlMTgyZjg3NzM1MzMyYmUxNDEwYWMyM2RlMDRkNzRlOWIwNmI4Mjc2YjQwMmZmYWMzNjllNTA5ZThiN2I0Mg==").unwrap();
    /// let email = fetch_api_key::Email::new("user@example.dev");
    /// let password = fetch_api_key::Password::new("super_secret_password");
    /// let req = fetch_api_key::Request::create(algo, &key, &email, &password).unwrap();
    ///
    /// let res = client.fetch_api_key(&req).await.unwrap();
    ///
    /// println!("Fetch API key response: {res:?}");
    /// # };
    /// ```
    pub async fn fetch_api_key(
        &self,
        req: &fetch_api_key::Request,
    ) -> Result<fetch_api_key::Response> {
        let res = self
            .http
            .post(self.endpoint(Endpoint::FetchApiKey))
            .form(req)
            .send()
            .await?;

        let bytes = res.bytes().await?;
        let body = str::from_utf8(&bytes[..])?;

        log::debug!("Fetch API key response: {body}");

        serde_json::from_str::<fetch_api_key::Response>(body).map_err(Error::from)
    }

    /// Gets the URL for the provided [Endpoint].
    pub fn endpoint(&self, endpoint: Endpoint) -> String {
        let scheme = self.scheme();
        let host = self.host();

        self.port()
            .map(|port| format!("{scheme}://{host}:{port}/{endpoint}"))
            .unwrap_or_else(|| format!("{scheme}://{host}/{endpoint}"))
    }

    /// Gets the base URL for the Zulip API server.
    pub fn base_url(&self) -> String {
        let scheme = self.scheme();
        let host = self.host();

        self.port()
            .map(|port| format!("{scheme}://{host}:{port}"))
            .unwrap_or_else(|| format!("{scheme}://{host}"))
    }

    /// Gets the Zulip server's URL scheme.
    pub(crate) fn scheme(&self) -> &str {
        self.url.scheme_str().unwrap_or("http")
    }

    /// Gets the Zulip server's URL host.
    pub(crate) fn host(&self) -> &str {
        self.url.host().unwrap_or("chat.zulip.org")
    }

    /// Gets the Zulip server's URL port.
    pub(crate) fn port(&self) -> Option<u16> {
        self.url.port_u16()
    }
}