rustigram-api 0.12.0

use std::future::{Future, IntoFuture};
use std::pin::Pin;

use reqwest::multipart::{Form, Part};
use serde::Serialize;

use rustigram_types::file::{InputFile, InputMedia, InputPaidMedia};
use rustigram_types::keyboard::ReplyMarkup;
use rustigram_types::message::{LinkPreviewOptions, Message, ParseMode, ReplyParameters};
use rustigram_types::poll::InputPollOption;
use rustigram_types::suggested_post::SuggestedPostParameters;
use rustigram_types::user::ChatId;

use crate::client::BotClient;
use crate::error::Result;

// ─── Helper macro ────────────────────────────────────────────────────────────

/// Generates an `IntoFuture` impl that calls `BotClient::post_json`.
macro_rules! impl_into_future {
    ($builder:ident, $return_ty:ty, $method:literal) => {
        impl IntoFuture for $builder {
            type Output = Result<$return_ty>;
            type IntoFuture = Pin<Box<dyn Future<Output = Self::Output> + Send>>;

            fn into_future(self) -> Self::IntoFuture {
                Box::pin(async move { self.client.post_json($method, &self.params).await })
            }
        }
    };
}

// ─── sendMessage ─────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendMessageParams {
    chat_id: ChatId,
    text: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    parse_mode: Option<ParseMode>,
    #[serde(skip_serializing_if = "Option::is_none")]
    entities: Option<Vec<rustigram_types::message::MessageEntity>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    link_preview_options: Option<LinkPreviewOptions>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<ReplyMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    receiver_user_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    callback_query_id: Option<String>,
}

/// Builder for the [`sendMessage`](https://core.telegram.org/bots/api#sendmessage) method.
pub struct SendMessage {
    client: BotClient,
    params: SendMessageParams,
}

impl SendMessage {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        text: impl Into<String>,
    ) -> Self {
        Self {
            client,
            params: SendMessageParams {
                chat_id: chat_id.into(),
                text: text.into(),
                business_connection_id: None,
                message_thread_id: None,
                direct_messages_topic_id: None,
                parse_mode: None,
                entities: None,
                link_preview_options: None,
                disable_notification: None,
                protect_content: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
                reply_parameters: None,
                reply_markup: None,
                suggested_post_parameters: None,
                receiver_user_id: None,
                callback_query_id: None,
            },
        }
    }
    /// Business connection ID for sending on behalf of a business account.
    pub fn business_connection_id(mut self, id: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(id.into());
        self
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sets the text parse mode (`MarkdownV2`, `HTML`, or `Markdown`).
    pub fn parse_mode(mut self, mode: ParseMode) -> Self {
        self.params.parse_mode = Some(mode);
        self
    }
    /// Sets custom message entities instead of using a parse mode.
    pub fn entities(mut self, entities: Vec<rustigram_types::message::MessageEntity>) -> Self {
        self.params.entities = Some(entities);
        self
    }
    /// Configures link preview generation options.
    pub fn link_preview_options(mut self, opts: LinkPreviewOptions) -> Self {
        self.params.link_preview_options = Some(opts);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, id: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(id.into());
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(rp);
        self
    }
    /// Convenience shortcut for `reply_parameters` — sets the reply-to message ID.
    pub fn reply_to(mut self, message_id: i64) -> Self {
        self.params.reply_parameters = Some(ReplyParameters {
            message_id: Some(message_id),
            ephemeral_message_id: None,
            chat_id: None,
            allow_sending_without_reply: None,
            quote: None,
            quote_parse_mode: None,
            quote_entities: None,
            quote_position: None,
            poll_option_id: None,
            checklist_task_id: None,
        });
        self
    }
    /// Convenience shortcut for `reply_parameters` — replies to an ephemeral message.
    ///
    /// A reply to an ephemeral message must itself be sent as an ephemeral
    /// message (see [`receiver_user_id`](Self::receiver_user_id)).
    pub fn reply_to_ephemeral(mut self, ephemeral_message_id: i64) -> Self {
        self.params.reply_parameters = Some(ReplyParameters {
            message_id: None,
            ephemeral_message_id: Some(ephemeral_message_id),
            chat_id: None,
            allow_sending_without_reply: None,
            quote: None,
            quote_parse_mode: None,
            quote_entities: None,
            quote_position: None,
            poll_option_id: None,
            checklist_task_id: None,
        });
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, markup: impl Into<ReplyMarkup>) -> Self {
        self.params.reply_markup = Some(markup.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, params: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(params);
        self
    }
    /// For outgoing ephemeral messages — the user who will receive the message.
    ///
    /// Group and supergroup chats only. Delivery is not guaranteed, especially
    /// if the user is offline. See [`reply_to_ephemeral`](Self::reply_to_ephemeral)
    /// for replying to an existing ephemeral message.
    pub fn receiver_user_id(mut self, id: i64) -> Self {
        self.params.receiver_user_id = Some(id);
        self
    }
    /// For outgoing ephemeral messages — the callback query that triggered it, if any.
    pub fn callback_query_id(mut self, id: impl Into<String>) -> Self {
        self.params.callback_query_id = Some(id.into());
        self
    }
}

impl_into_future!(SendMessage, Message, "sendMessage");

// ─── forwardMessage ───────────────────────────────────────────────────────────

#[derive(Serialize)]
struct ForwardMessageParams {
    chat_id: ChatId,
    from_chat_id: ChatId,
    message_id: i64,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    video_start_timestamp: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
}

/// Builder for the [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) method.
pub struct ForwardMessage {
    client: BotClient,
    params: ForwardMessageParams,
}

impl ForwardMessage {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        from_chat_id: impl Into<ChatId>,
        message_id: i64,
    ) -> Self {
        Self {
            client,
            params: ForwardMessageParams {
                chat_id: chat_id.into(),
                from_chat_id: from_chat_id.into(),
                message_id,
                message_thread_id: None,
                direct_messages_topic_id: None,
                video_start_timestamp: None,
                disable_notification: None,
                protect_content: None,
                message_effect_id: None,
                suggested_post_parameters: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// New start timestamp for a forwarded video.
    pub fn video_start_timestamp(mut self, ts: i64) -> Self {
        self.params.video_start_timestamp = Some(ts);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, v: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(v);
        self
    }
}

impl_into_future!(ForwardMessage, Message, "forwardMessage");

// ─── copyMessage ──────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct CopyMessageParams {
    chat_id: ChatId,
    from_chat_id: ChatId,
    message_id: i64,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    video_start_timestamp: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    caption: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    parse_mode: Option<ParseMode>,
    #[serde(skip_serializing_if = "Option::is_none")]
    caption_entities: Option<Vec<rustigram_types::message::MessageEntity>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    show_caption_above_media: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<ReplyMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
}

/// Builder for the [`copyMessage`](https://core.telegram.org/bots/api#copymessage) method.
pub struct CopyMessage {
    client: BotClient,
    params: CopyMessageParams,
}

impl CopyMessage {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        from_chat_id: impl Into<ChatId>,
        message_id: i64,
    ) -> Self {
        Self {
            client,
            params: CopyMessageParams {
                chat_id: chat_id.into(),
                from_chat_id: from_chat_id.into(),
                message_id,
                message_thread_id: None,
                direct_messages_topic_id: None,
                video_start_timestamp: None,
                caption: None,
                parse_mode: None,
                caption_entities: None,
                show_caption_above_media: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                reply_markup: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
                suggested_post_parameters: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// New start timestamp for a copied video.
    pub fn video_start_timestamp(mut self, ts: i64) -> Self {
        self.params.video_start_timestamp = Some(ts);
        self
    }
    /// Sets the caption (0–1024 characters) for media messages.
    pub fn caption(mut self, c: impl Into<String>) -> Self {
        self.params.caption = Some(c.into());
        self
    }
    /// Sets the text parse mode (`MarkdownV2`, `HTML`, or `Markdown`).
    pub fn parse_mode(mut self, m: ParseMode) -> Self {
        self.params.parse_mode = Some(m);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.params.reply_markup = Some(m.into());
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, v: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(v);
        self
    }
    /// Special entities in the caption, in place of `parse_mode`.
    pub fn caption_entities(
        mut self,
        entities: Vec<rustigram_types::message::MessageEntity>,
    ) -> Self {
        self.params.caption_entities = Some(entities);
        self
    }
    /// Shows the caption above the media instead of below it.
    pub fn show_caption_above_media(mut self, v: bool) -> Self {
        self.params.show_caption_above_media = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(rp);
        self
    }
}

impl_into_future!(
    CopyMessage,
    rustigram_types::message::MessageId,
    "copyMessage"
);

// ─── sendChatAction ───────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendChatActionParams {
    chat_id: ChatId,
    action: ChatAction,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
}

#[derive(Serialize, Clone, Copy)]
/// The chat action to display while the bot is preparing a response.
#[serde(rename_all = "snake_case")]
pub enum ChatAction {
    /// Indicates the bot is composing a message.
    Typing,
    /// Indicates the bot is uploading a photo.
    UploadPhoto,
    /// Indicates the bot is recording a video.
    RecordVideo,
    /// Indicates the bot is uploading a video.
    UploadVideo,
    /// Indicates the bot is recording a voice note.
    RecordVoice,
    /// Indicates the bot is uploading a voice note.
    UploadVoice,
    /// Indicates the bot is uploading a document.
    UploadDocument,
    /// Indicates the bot is choosing a sticker.
    ChooseSticker,
    /// Indicates the bot is finding a location.
    FindLocation,
    /// Indicates the bot is recording a video note.
    RecordVideoNote,
    /// Indicates the bot is uploading a video note.
    UploadVideoNote,
}

/// Builder for the [`sendChatAction`](https://core.telegram.org/bots/api#sendchataction) method.
pub struct SendChatAction {
    client: BotClient,
    params: SendChatActionParams,
}

impl SendChatAction {
    pub(crate) fn new(client: BotClient, chat_id: impl Into<ChatId>, action: ChatAction) -> Self {
        Self {
            client,
            params: SendChatActionParams {
                chat_id: chat_id.into(),
                action,
                business_connection_id: None,
                message_thread_id: None,
            },
        }
    }
    /// Business connection ID for sending on behalf of a business account.
    pub fn business_connection_id(mut self, id: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(id.into());
        self
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
}

impl_into_future!(SendChatAction, bool, "sendChatAction");

// ─── sendDice ─────────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendDiceParams {
    chat_id: ChatId,
    #[serde(skip_serializing_if = "Option::is_none")]
    emoji: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<ReplyMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
}

/// Builder for the [`sendDice`](https://core.telegram.org/bots/api#senddice) method.
pub struct SendDice {
    client: BotClient,
    params: SendDiceParams,
}

impl SendDice {
    pub(crate) fn new(client: BotClient, chat_id: impl Into<ChatId>) -> Self {
        Self {
            client,
            params: SendDiceParams {
                chat_id: chat_id.into(),
                emoji: None,
                message_thread_id: None,
                direct_messages_topic_id: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                reply_markup: None,
                business_connection_id: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
                suggested_post_parameters: None,
            },
        }
    }
    /// The dice/emoji to animate. One of 🎲 🎯 🏀 ⚽ 🎳 🎰.
    pub fn emoji(mut self, e: impl Into<String>) -> Self {
        self.params.emoji = Some(e.into());
        self
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.params.reply_markup = Some(m.into());
        self
    }
    /// Business connection ID for acting on behalf of a business account.
    pub fn business_connection_id(mut self, v: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(v.into());
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, v: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, v: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(v);
        self
    }
}

impl_into_future!(SendDice, Message, "sendDice");

// ─── sendLocation ─────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendLocationParams {
    chat_id: ChatId,
    latitude: f64,
    longitude: f64,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    horizontal_accuracy: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    live_period: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    heading: Option<u16>,
    #[serde(skip_serializing_if = "Option::is_none")]
    proximity_alert_radius: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<ReplyMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    receiver_user_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    callback_query_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
}

/// Builder for the [`sendLocation`](https://core.telegram.org/bots/api#sendlocation) method.
pub struct SendLocation {
    client: BotClient,
    params: SendLocationParams,
}

impl SendLocation {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        latitude: f64,
        longitude: f64,
    ) -> Self {
        Self {
            client,
            params: SendLocationParams {
                chat_id: chat_id.into(),
                latitude,
                longitude,
                message_thread_id: None,
                direct_messages_topic_id: None,
                horizontal_accuracy: None,
                live_period: None,
                heading: None,
                proximity_alert_radius: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                reply_markup: None,
                receiver_user_id: None,
                callback_query_id: None,
                business_connection_id: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
                suggested_post_parameters: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sets the radius of uncertainty for the location, in metres (0–1500).
    pub fn horizontal_accuracy(mut self, v: f64) -> Self {
        self.params.horizontal_accuracy = Some(v);
        self
    }
    /// Sets how long the location stays live, in seconds (60–86400), or
    /// `0x7FFFFFFF` for indefinitely editable live locations. Must be `0`
    /// for ephemeral messages.
    pub fn live_period(mut self, v: u32) -> Self {
        self.params.live_period = Some(v);
        self
    }
    /// Sets the direction of movement in degrees (1–360).
    pub fn heading(mut self, v: u16) -> Self {
        self.params.heading = Some(v);
        self
    }
    /// Sets the maximum distance in metres for proximity alerts.
    pub fn proximity_alert_radius(mut self, v: u32) -> Self {
        self.params.proximity_alert_radius = Some(v);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.params.reply_markup = Some(m.into());
        self
    }
    /// For outgoing ephemeral messages — the user who will receive the message.
    pub fn receiver_user_id(mut self, id: i64) -> Self {
        self.params.receiver_user_id = Some(id);
        self
    }
    /// For outgoing ephemeral messages — the callback query that triggered it, if any.
    pub fn callback_query_id(mut self, id: impl Into<String>) -> Self {
        self.params.callback_query_id = Some(id.into());
        self
    }
    /// Business connection ID for acting on behalf of a business account.
    pub fn business_connection_id(mut self, v: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(v.into());
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, v: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, v: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(v);
        self
    }
}

impl_into_future!(SendLocation, Message, "sendLocation");

// ─── sendContact ──────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendContactParams {
    chat_id: ChatId,
    phone_number: String,
    first_name: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    last_name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    vcard: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<ReplyMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    receiver_user_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    callback_query_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
}

/// Builder for the [`sendContact`](https://core.telegram.org/bots/api#sendcontact) method.
pub struct SendContact {
    client: BotClient,
    params: SendContactParams,
}

impl SendContact {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        phone_number: impl Into<String>,
        first_name: impl Into<String>,
    ) -> Self {
        Self {
            client,
            params: SendContactParams {
                chat_id: chat_id.into(),
                phone_number: phone_number.into(),
                first_name: first_name.into(),
                last_name: None,
                vcard: None,
                message_thread_id: None,
                direct_messages_topic_id: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                reply_markup: None,
                receiver_user_id: None,
                callback_query_id: None,
                business_connection_id: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
                suggested_post_parameters: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sets the last name of the contact.
    pub fn last_name(mut self, v: impl Into<String>) -> Self {
        self.params.last_name = Some(v.into());
        self
    }
    /// Sets the vCard data of the contact.
    pub fn vcard(mut self, v: impl Into<String>) -> Self {
        self.params.vcard = Some(v.into());
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.params.reply_markup = Some(m.into());
        self
    }
    /// For outgoing ephemeral messages — the user who will receive the message.
    pub fn receiver_user_id(mut self, id: i64) -> Self {
        self.params.receiver_user_id = Some(id);
        self
    }
    /// For outgoing ephemeral messages — the callback query that triggered it, if any.
    pub fn callback_query_id(mut self, id: impl Into<String>) -> Self {
        self.params.callback_query_id = Some(id.into());
        self
    }
    /// Business connection ID for acting on behalf of a business account.
    pub fn business_connection_id(mut self, v: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(v.into());
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, v: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, v: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(v);
        self
    }
}

impl_into_future!(SendContact, Message, "sendContact");

// ─── sendPoll ─────────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendPollParams {
    chat_id: ChatId,
    question: String,
    options: Vec<InputPollOption>,
    #[serde(skip_serializing_if = "Option::is_none")]
    question_parse_mode: Option<ParseMode>,
    #[serde(skip_serializing_if = "Option::is_none")]
    question_entities: Option<Vec<rustigram_types::message::MessageEntity>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none", rename = "type")]
    poll_type: Option<rustigram_types::poll::PollType>,
    #[serde(skip_serializing_if = "Option::is_none")]
    is_anonymous: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allows_multiple_answers: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allows_revoting: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    correct_option_ids: Option<Vec<u8>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    explanation: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    explanation_parse_mode: Option<ParseMode>,
    #[serde(skip_serializing_if = "Option::is_none")]
    explanation_entities: Option<Vec<rustigram_types::message::MessageEntity>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    open_period: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    close_date: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    is_closed: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    shuffle_options: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_adding_options: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    hide_results_until_closes: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    description: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    description_parse_mode: Option<ParseMode>,
    #[serde(skip_serializing_if = "Option::is_none")]
    description_entities: Option<Vec<rustigram_types::message::MessageEntity>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<ReplyMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    members_only: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    country_codes: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    media: Option<rustigram_types::poll::InputPollMedia>,
    #[serde(skip_serializing_if = "Option::is_none")]
    explanation_media: Option<rustigram_types::poll::InputPollMedia>,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
}

/// Builder for the [`sendPoll`](https://core.telegram.org/bots/api#sendpoll) method.
pub struct SendPoll {
    client: BotClient,
    params: SendPollParams,
}

impl SendPoll {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        question: impl Into<String>,
        options: Vec<InputPollOption>,
    ) -> Self {
        Self {
            client,
            params: SendPollParams {
                chat_id: chat_id.into(),
                question: question.into(),
                options,
                question_parse_mode: None,
                question_entities: None,
                message_thread_id: None,
                direct_messages_topic_id: None,
                poll_type: None,
                is_anonymous: None,
                allows_multiple_answers: None,
                allows_revoting: None,
                correct_option_ids: None,
                explanation: None,
                explanation_parse_mode: None,
                explanation_entities: None,
                open_period: None,
                close_date: None,
                is_closed: None,
                shuffle_options: None,
                allow_adding_options: None,
                hide_results_until_closes: None,
                description: None,
                description_parse_mode: None,
                description_entities: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                reply_markup: None,
                suggested_post_parameters: None,
                members_only: None,
                country_codes: None,
                media: None,
                explanation_media: None,
                business_connection_id: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sets whether the poll is anonymous.
    pub fn is_anonymous(mut self, v: bool) -> Self {
        self.params.is_anonymous = Some(v);
        self
    }
    /// Allows voters to select multiple answers.
    pub fn allows_multiple_answers(mut self, v: bool) -> Self {
        self.params.allows_multiple_answers = Some(v);
        self
    }
    /// Allows voters to change their vote.
    pub fn allows_revoting(mut self, v: bool) -> Self {
        self.params.allows_revoting = Some(v);
        self
    }
    /// Converts the poll to a quiz with the given correct option indices.
    pub fn quiz(mut self, ids: Vec<u8>) -> Self {
        self.params.poll_type = Some(rustigram_types::poll::PollType::Quiz);
        self.params.correct_option_ids = Some(ids);
        self
    }
    /// Convenience method for a quiz with a single correct option.
    pub fn quiz_single(self, id: u8) -> Self {
        self.quiz(vec![id])
    }
    /// Sets the explanation text shown after a quiz answer.
    pub fn explanation(mut self, text: impl Into<String>) -> Self {
        self.params.explanation = Some(text.into());
        self
    }
    /// Sets the parse mode for the explanation.
    pub fn explanation_parse_mode(mut self, mode: ParseMode) -> Self {
        self.params.explanation_parse_mode = Some(mode);
        self
    }
    /// Sets entities for the explanation.
    pub fn explanation_entities(mut self, e: Vec<rustigram_types::message::MessageEntity>) -> Self {
        self.params.explanation_entities = Some(e);
        self
    }
    /// Sets how long the poll stays open in seconds (5–2628000).
    pub fn open_period(mut self, secs: u32) -> Self {
        self.params.open_period = Some(secs);
        self
    }
    /// Sets the Unix timestamp when the poll closes automatically.
    pub fn close_date(mut self, ts: i64) -> Self {
        self.params.close_date = Some(ts);
        self
    }
    /// Sets whether the options should be shuffled.
    pub fn shuffle_options(mut self, v: bool) -> Self {
        self.params.shuffle_options = Some(v);
        self
    }
    /// Allows users to add their own options to the poll.
    pub fn allow_adding_options(mut self, v: bool) -> Self {
        self.params.allow_adding_options = Some(v);
        self
    }
    /// Hides the poll results until it's closed.
    pub fn hide_results_until_closes(mut self, v: bool) -> Self {
        self.params.hide_results_until_closes = Some(v);
        self
    }
    /// Sets the poll description (0-1024 chars).
    pub fn description(mut self, d: impl Into<String>) -> Self {
        self.params.description = Some(d.into());
        self
    }
    /// Sets description parse mode.
    pub fn description_parse_mode(mut self, mode: ParseMode) -> Self {
        self.params.description_parse_mode = Some(mode);
        self
    }
    /// Sets description entities.
    pub fn description_entities(mut self, e: Vec<rustigram_types::message::MessageEntity>) -> Self {
        self.params.description_entities = Some(e);
        self
    }
    /// Sets the question parse mode.
    pub fn question_parse_mode(mut self, mode: ParseMode) -> Self {
        self.params.question_parse_mode = Some(mode);
        self
    }
    /// Sets question entities.
    pub fn question_entities(mut self, e: Vec<rustigram_types::message::MessageEntity>) -> Self {
        self.params.question_entities = Some(e);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.params.reply_markup = Some(m.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, params: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(params);
        self
    }
    /// Pass `true` to limit voting to users who have been members of the chat for more than
    /// 24 hours; for channel chats only.
    pub fn members_only(mut self, v: bool) -> Self {
        self.params.members_only = Some(v);
        self
    }
    /// Two-letter ISO 3166-1 alpha-2 country codes for countries from which users can vote; channels only.
    pub fn country_codes(mut self, codes: Vec<impl Into<String>>) -> Self {
        self.params.country_codes = Some(codes.into_iter().map(Into::into).collect());
        self
    }

    /// Media added to the poll description.
    pub fn media(mut self, m: rustigram_types::poll::InputPollMedia) -> Self {
        self.params.media = Some(m);
        self
    }

    /// Media added to the quiz explanation.
    pub fn explanation_media(mut self, m: rustigram_types::poll::InputPollMedia) -> Self {
        self.params.explanation_media = Some(m);
        self
    }
    /// Business connection ID for acting on behalf of a business account.
    pub fn business_connection_id(mut self, v: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(v.into());
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
    /// Sends the poll already closed, so it cannot be voted on.
    pub fn is_closed(mut self, v: bool) -> Self {
        self.params.is_closed = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, v: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(v);
        self
    }
}

impl_into_future!(SendPoll, Message, "sendPoll");

// ─── sendMessageDraft ─────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendMessageDraftParams {
    chat_id: ChatId,
    draft_id: i64,
    /// Optional per the spec — a draft may carry only media, or none at all.
    /// The constructor still takes text since that is the common case; use
    /// [`SendMessageDraft::clear_text`] to send without any.
    #[serde(skip_serializing_if = "Option::is_none")]
    text: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    parse_mode: Option<ParseMode>,
    #[serde(skip_serializing_if = "Option::is_none")]
    entities: Option<Vec<rustigram_types::message::MessageEntity>>,
}

/// Builder for the [`sendMessageDraft`](https://core.telegram.org/bots/api#sendmessagedraft) method.
/// Streams a partial message to the user while it is being generated (Bot API 9.5+).
pub struct SendMessageDraft {
    client: BotClient,
    params: SendMessageDraftParams,
}

impl SendMessageDraft {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        draft_id: i64,
        text: impl Into<String>,
    ) -> Self {
        Self {
            client,
            params: SendMessageDraftParams {
                chat_id: chat_id.into(),
                draft_id,
                text: Some(text.into()),
                message_thread_id: None,
                parse_mode: None,
                entities: None,
            },
        }
    }
    /// Sets the text parse mode (`MarkdownV2`, `HTML`, or `Markdown`).
    pub fn parse_mode(mut self, m: ParseMode) -> Self {
        self.params.parse_mode = Some(m);
        self
    }
    /// Sets custom message entities instead of using a parse mode.
    pub fn entities(mut self, e: Vec<rustigram_types::message::MessageEntity>) -> Self {
        self.params.entities = Some(e);
        self
    }
    /// Sends the draft with no text at all, which the API permits.
    pub fn clear_text(mut self) -> Self {
        self.params.text = None;
        self
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, v: i64) -> Self {
        self.params.message_thread_id = Some(v);
        self
    }
}

impl_into_future!(SendMessageDraft, bool, "sendMessageDraft");

// ─── File-sending builders ────────────────────────────────────────────────────
//
// Photo, Audio, Document, Video, Animation, Voice, VideoNote each share a
// similar shape but differ in field names and constraints. We use a common
// pattern: store the InputFile and an optional Form for multipart, and build
// the form lazily in `IntoFuture`.

/// Writes every [`MediaSendOptions`] field onto a multipart form.
///
/// Media senders take one of two paths: an `InputFile::Bytes` upload builds a
/// multipart form, while a file_id or URL goes through `media_json_body`. Those
/// two were maintained by hand and had drifted — the multipart side silently
/// dropped `protect_content`, `allow_paid_broadcast`, `reply_parameters`,
/// `caption_entities`, and `show_caption_above_media`, so a `.reply_to(..)` on
/// an uploaded photo never reached Telegram. Both paths now enumerate the same
/// struct, so a field added to `MediaSendOptions` cannot go missing from one.
fn apply_media_opts(mut form: Form, opts: &MediaSendOptions) -> Form {
    fn json_text(form: Form, key: &'static str, value: &impl Serialize) -> Form {
        // Plain data types; serialisation cannot realistically fail, and the
        // guard keeps a panic out of library code.
        match serde_json::to_string(value) {
            Ok(json) => form.text(key, json),
            Err(_) => form,
        }
    }

    if let Some(v) = &opts.business_connection_id {
        form = form.text("business_connection_id", v.clone());
    }
    if let Some(v) = opts.message_thread_id {
        form = form.text("message_thread_id", v.to_string());
    }
    if let Some(v) = opts.direct_messages_topic_id {
        form = form.text("direct_messages_topic_id", v.to_string());
    }
    if let Some(v) = &opts.caption {
        form = form.text("caption", v.clone());
    }
    if let Some(v) = &opts.parse_mode {
        form = form.text("parse_mode", format!("{v:?}"));
    }
    if let Some(v) = &opts.caption_entities {
        form = json_text(form, "caption_entities", v);
    }
    if let Some(v) = opts.show_caption_above_media {
        form = form.text("show_caption_above_media", v.to_string());
    }
    if let Some(v) = opts.has_spoiler {
        form = form.text("has_spoiler", v.to_string());
    }
    if let Some(v) = opts.disable_notification {
        form = form.text("disable_notification", v.to_string());
    }
    if let Some(v) = opts.protect_content {
        form = form.text("protect_content", v.to_string());
    }
    if let Some(v) = opts.allow_paid_broadcast {
        form = form.text("allow_paid_broadcast", v.to_string());
    }
    if let Some(v) = &opts.message_effect_id {
        form = form.text("message_effect_id", v.clone());
    }
    if let Some(v) = &opts.reply_parameters {
        form = json_text(form, "reply_parameters", v);
    }
    if let Some(v) = &opts.reply_markup {
        form = json_text(form, "reply_markup", v);
    }
    if let Some(v) = &opts.suggested_post_parameters {
        form = json_text(form, "suggested_post_parameters", v);
    }
    if let Some(v) = opts.receiver_user_id {
        form = form.text("receiver_user_id", v.to_string());
    }
    if let Some(v) = &opts.callback_query_id {
        form = form.text("callback_query_id", v.clone());
    }
    form
}

/// Common optional parameters shared by most media-send methods.
#[derive(Default)]
pub struct MediaSendOptions {
    /// Business connection ID for sending on behalf of a business account.
    pub business_connection_id: Option<String>,
    /// Forum topic thread ID.
    pub message_thread_id: Option<i64>,
    /// Identifier of a direct messages chat topic.
    pub direct_messages_topic_id: Option<i64>,
    /// Sets the caption (0–1024 characters) for media messages.
    pub caption: Option<String>,
    /// Parse mode for the caption.
    pub parse_mode: Option<ParseMode>,
    /// Special entities in the caption.
    pub caption_entities: Option<Vec<rustigram_types::message::MessageEntity>>,
    /// Shows the caption above the media instead of below it.
    pub show_caption_above_media: Option<bool>,
    /// Marks the media as a spoiler — blurs it until the user taps to reveal.
    pub has_spoiler: Option<bool>,
    /// Sends the message silently — the recipient receives no notification sound.
    pub disable_notification: Option<bool>,
    /// Protects the message from being forwarded or saved.
    pub protect_content: Option<bool>,
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub allow_paid_broadcast: Option<bool>,
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub message_effect_id: Option<String>,
    /// Reply parameters for this message.
    pub reply_parameters: Option<ReplyParameters>,
    /// Reply markup attached to the message.
    pub reply_markup: Option<ReplyMarkup>,
    /// Suggested post parameters for channel direct messages chats.
    pub suggested_post_parameters: Option<SuggestedPostParameters>,
    /// For outgoing ephemeral messages — identifier of the user who will
    /// receive the message; group and supergroup chats only. Delivery is not
    /// guaranteed, especially if the user is offline.
    pub receiver_user_id: Option<i64>,
    /// For outgoing ephemeral messages — identifier of the callback query
    /// that triggered the message, if any.
    pub callback_query_id: Option<String>,
}

/// Builds the JSON body for a simple (non-file-upload) part of a media send.
fn media_json_body(
    chat_id: &ChatId,
    media_field: &str,
    media_value: &str,
    opts: &MediaSendOptions,
    extra: serde_json::Value,
) -> serde_json::Value {
    let mut map = serde_json::json!({
        "chat_id": chat_id,
        media_field: media_value,
    });
    let obj = map.as_object_mut().unwrap();
    if let Some(v) = &opts.business_connection_id {
        obj.insert("business_connection_id".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.message_thread_id {
        obj.insert("message_thread_id".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.direct_messages_topic_id {
        obj.insert("direct_messages_topic_id".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.caption {
        obj.insert("caption".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.parse_mode {
        obj.insert("parse_mode".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.caption_entities {
        obj.insert("caption_entities".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = opts.show_caption_above_media {
        obj.insert("show_caption_above_media".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = opts.has_spoiler {
        obj.insert("has_spoiler".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = opts.disable_notification {
        obj.insert("disable_notification".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = opts.protect_content {
        obj.insert("protect_content".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = opts.allow_paid_broadcast {
        obj.insert("allow_paid_broadcast".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.message_effect_id {
        obj.insert("message_effect_id".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.reply_parameters {
        obj.insert("reply_parameters".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.reply_markup {
        obj.insert("reply_markup".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.suggested_post_parameters {
        obj.insert("suggested_post_parameters".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = opts.receiver_user_id {
        obj.insert("receiver_user_id".to_owned(), serde_json::json!(v));
    }
    if let Some(v) = &opts.callback_query_id {
        obj.insert("callback_query_id".to_owned(), serde_json::json!(v));
    }
    if let serde_json::Value::Object(extra_obj) = extra {
        for (k, v) in extra_obj {
            obj.insert(k, v);
        }
    }
    map
}

// ─── sendPhoto ────────────────────────────────────────────────────────────────

/// Builder for the [`sendPhoto`](https://core.telegram.org/bots/api#sendphoto) method.
pub struct SendPhoto {
    client: BotClient,
    chat_id: ChatId,
    photo: InputFile,
    opts: MediaSendOptions,
}

impl SendPhoto {
    pub(crate) fn new(client: BotClient, chat_id: impl Into<ChatId>, photo: InputFile) -> Self {
        Self {
            client,
            chat_id: chat_id.into(),
            photo,
            opts: MediaSendOptions::default(),
        }
    }
    /// Business connection ID for sending on behalf of a business account.
    pub fn business_connection_id(mut self, id: impl Into<String>) -> Self {
        self.opts.business_connection_id = Some(id.into());
        self
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.opts.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.opts.direct_messages_topic_id = Some(id);
        self
    }
    /// Sets the caption (0–1024 characters) for media messages.
    pub fn caption(mut self, c: impl Into<String>) -> Self {
        self.opts.caption = Some(c.into());
        self
    }
    /// Sets the caption parse mode (`MarkdownV2`, `HTML`, or `Markdown`).
    pub fn parse_mode(mut self, m: ParseMode) -> Self {
        self.opts.parse_mode = Some(m);
        self
    }
    /// Marks the media as a spoiler — blurs it until the user taps to reveal.
    pub fn has_spoiler(mut self, v: bool) -> Self {
        self.opts.has_spoiler = Some(v);
        self
    }
    /// Special entities in the caption, in place of `parse_mode`.
    pub fn caption_entities(
        mut self,
        entities: Vec<rustigram_types::message::MessageEntity>,
    ) -> Self {
        self.opts.caption_entities = Some(entities);
        self
    }
    /// Shows the caption above the media instead of below it.
    pub fn show_caption_above_media(mut self, v: bool) -> Self {
        self.opts.show_caption_above_media = Some(v);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.opts.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.opts.protect_content = Some(v);
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.opts.allow_paid_broadcast = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.opts.reply_parameters = Some(rp);
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.opts.reply_markup = Some(m.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, params: SuggestedPostParameters) -> Self {
        self.opts.suggested_post_parameters = Some(params);
        self
    }
    /// For outgoing ephemeral messages — the user who will receive the message.
    pub fn receiver_user_id(mut self, id: i64) -> Self {
        self.opts.receiver_user_id = Some(id);
        self
    }
    /// For outgoing ephemeral messages — the callback query that triggered it, if any.
    pub fn callback_query_id(mut self, id: impl Into<String>) -> Self {
        self.opts.callback_query_id = Some(id.into());
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, id: impl Into<String>) -> Self {
        self.opts.message_effect_id = Some(id.into());
        self
    }
}

impl IntoFuture for SendPhoto {
    type Output = Result<Message>;
    type IntoFuture = Pin<Box<dyn Future<Output = Self::Output> + Send>>;

    fn into_future(self) -> Self::IntoFuture {
        Box::pin(async move {
            match &self.photo {
                InputFile::Bytes {
                    filename,
                    data,
                    mime_type,
                } => {
                    let part = Part::bytes(data.clone())
                        .file_name(filename.clone())
                        .mime_str(mime_type)
                        .map_err(|e| crate::error::Error::Decode(e.to_string()))?;
                    let mut form = Form::new().part("photo", part);
                    form = form.text("chat_id", self.chat_id.to_string());
                    form = apply_media_opts(form, &self.opts);
                    self.client.post_multipart("sendPhoto", form).await
                }
                _ => {
                    let body = media_json_body(
                        &self.chat_id,
                        "photo",
                        self.photo.as_str(),
                        &self.opts,
                        serde_json::Value::Null,
                    );
                    self.client.post_json("sendPhoto", &body).await
                }
            }
        })
    }
}

// ─── sendLivePhoto ────────────────────────────────────────────────────────────

/// Builder for the [`sendLivePhoto`](https://core.telegram.org/bots/api#sendlivephoto) method.
pub struct SendLivePhoto {
    client: BotClient,
    chat_id: ChatId,
    live_photo: InputFile,
    photo: InputFile,
    opts: MediaSendOptions,
}

impl SendLivePhoto {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        live_photo: InputFile,
        photo: InputFile,
    ) -> Self {
        Self {
            client,
            chat_id: chat_id.into(),
            live_photo,
            photo,
            opts: MediaSendOptions::default(),
        }
    }
    /// Business connection ID for sending on behalf of a business account.
    pub fn business_connection_id(mut self, id: impl Into<String>) -> Self {
        self.opts.business_connection_id = Some(id.into());
        self
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.opts.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.opts.direct_messages_topic_id = Some(id);
        self
    }
    /// Sets the caption (0–1024 characters).
    pub fn caption(mut self, c: impl Into<String>) -> Self {
        self.opts.caption = Some(c.into());
        self
    }
    /// Sets the caption parse mode.
    pub fn parse_mode(mut self, m: ParseMode) -> Self {
        self.opts.parse_mode = Some(m);
        self
    }
    /// Shows the caption above the media instead of below it.
    pub fn show_caption_above_media(mut self, v: bool) -> Self {
        self.opts.show_caption_above_media = Some(v);
        self
    }
    /// Covers the live photo with a spoiler animation.
    pub fn has_spoiler(mut self, v: bool) -> Self {
        self.opts.has_spoiler = Some(v);
        self
    }
    /// Special entities in the caption, in place of `parse_mode`.
    pub fn caption_entities(
        mut self,
        entities: Vec<rustigram_types::message::MessageEntity>,
    ) -> Self {
        self.opts.caption_entities = Some(entities);
        self
    }
    /// Sends the message as ephemeral, visible only to this user.
    pub fn receiver_user_id(mut self, id: i64) -> Self {
        self.opts.receiver_user_id = Some(id);
        self
    }
    /// Identifier of the callback query this ephemeral message answers.
    pub fn callback_query_id(mut self, id: impl Into<String>) -> Self {
        self.opts.callback_query_id = Some(id.into());
        self
    }
    /// Sends the message silently.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.opts.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.opts.protect_content = Some(v);
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.opts.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (private chats only).
    pub fn message_effect_id(mut self, id: impl Into<String>) -> Self {
        self.opts.message_effect_id = Some(id.into());
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.opts.reply_parameters = Some(rp);
        self
    }
    /// Attaches a reply markup.
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.opts.reply_markup = Some(m.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, params: SuggestedPostParameters) -> Self {
        self.opts.suggested_post_parameters = Some(params);
        self
    }
}

impl IntoFuture for SendLivePhoto {
    type Output = Result<Message>;
    type IntoFuture = Pin<Box<dyn Future<Output = Self::Output> + Send>>;

    fn into_future(self) -> Self::IntoFuture {
        Box::pin(async move {
            let lp_bytes = self.live_photo.requires_multipart();
            let ph_bytes = self.photo.requires_multipart();

            if lp_bytes || ph_bytes {
                let mut form = Form::new();
                form = form.text("chat_id", self.chat_id.to_string());

                if let InputFile::Bytes {
                    filename,
                    data,
                    mime_type,
                } = self.live_photo
                {
                    let part = Part::bytes(data)
                        .file_name(filename)
                        .mime_str(&mime_type)
                        .map_err(|e| crate::error::Error::Decode(e.to_string()))?;
                    form = form.part("live_photo", part);
                } else {
                    form = form.text("live_photo", self.live_photo.as_str().to_owned());
                }

                if let InputFile::Bytes {
                    filename,
                    data,
                    mime_type,
                } = self.photo
                {
                    let part = Part::bytes(data)
                        .file_name(filename)
                        .mime_str(&mime_type)
                        .map_err(|e| crate::error::Error::Decode(e.to_string()))?;
                    form = form.part("photo", part);
                } else {
                    form = form.text("photo", self.photo.as_str().to_owned());
                }

                form = apply_media_opts(form, &self.opts);

                self.client.post_multipart("sendLivePhoto", form).await
            } else {
                let mut body = media_json_body(
                    &self.chat_id,
                    "live_photo",
                    self.live_photo.as_str(),
                    &self.opts,
                    serde_json::json!({}),
                );
                body.as_object_mut()
                    .unwrap()
                    .insert("photo".to_owned(), serde_json::json!(self.photo.as_str()));
                self.client.post_json("sendLivePhoto", &body).await
            }
        })
    }
}

// ─── Macro for simpler media senders (Audio, Document, Video, Animation, Voice, VideoNote, Sticker)

/// One caption-family setter, emitted only for the methods the spec allows it on.
///
/// These five are not universal: `sendVideoNote` and `sendSticker` take no
/// caption at all, and only `sendVideo` and `sendAnimation` accept a spoiler or
/// a caption above the media. Exposing them uniformly gave callers two setters
/// Telegram ignores and withheld three it honours.
macro_rules! caption_setter {
    (caption) => {
        /// Sets the caption (0–1024 characters).
        pub fn caption(mut self, c: impl Into<String>) -> Self {
            self.opts.caption = Some(c.into());
            self
        }
    };
    (parse_mode) => {
        /// Parse mode for the caption.
        pub fn parse_mode(mut self, m: ParseMode) -> Self {
            self.opts.parse_mode = Some(m);
            self
        }
    };
    (caption_entities) => {
        /// Special entities in the caption, in place of `parse_mode`.
        pub fn caption_entities(
            mut self,
            entities: Vec<rustigram_types::message::MessageEntity>,
        ) -> Self {
            self.opts.caption_entities = Some(entities);
            self
        }
    };
    (show_caption_above_media) => {
        /// Shows the caption above the media instead of below it.
        pub fn show_caption_above_media(mut self, v: bool) -> Self {
            self.opts.show_caption_above_media = Some(v);
            self
        }
    };
    (has_spoiler) => {
        /// Marks the media as a spoiler — blurs it until the user taps to reveal.
        pub fn has_spoiler(mut self, v: bool) -> Self {
            self.opts.has_spoiler = Some(v);
            self
        }
    };
}

macro_rules! media_sender {
    ($(#[$doc:meta])* $name:ident, $field:literal, $method:literal, $return_ty:ty,
     [$($extra_field:ident: $extra_ty:ty),*], [$($caption_opt:ident),*]) => {
        $(#[$doc])*
        pub struct $name {
            /// The API client to use for sending the request.
            client: BotClient,
            /// Unique identifier for the target chat or username of the target channel.
            chat_id: ChatId,
            /// The file to send. Can be a file ID, URL, or new upload.
            file: InputFile,
            /// Common optional parameters for media sending.
            opts: MediaSendOptions,
            /// Extra optional parameters specific to this media type.
            $($extra_field: Option<$extra_ty>,)*
        }

        impl $name {
            pub(crate) fn new(client: BotClient, chat_id: impl Into<ChatId>, file: InputFile) -> Self {
                Self {
                    client,
                    chat_id: chat_id.into(),
                    file,
                    opts: MediaSendOptions::default(),
                    $($extra_field: None,)*
                }
            }
            /// Business connection ID for sending on behalf of a business account.
            pub fn business_connection_id(mut self, id: impl Into<String>) -> Self { self.opts.business_connection_id = Some(id.into()); self }
            /// Forum topic thread ID.
            pub fn message_thread_id(mut self, id: i64) -> Self { self.opts.message_thread_id = Some(id); self }
            /// Identifier of a direct messages chat topic.
            pub fn direct_messages_topic_id(mut self, id: i64) -> Self { self.opts.direct_messages_topic_id = Some(id); self }
            // The caption-family setters this method actually takes. Each
            // carries its own doc comment inside `caption_setter!` — a doc
            // comment out here would attach to the macro invocation, which
            // rustdoc drops, and clippy rejects under `-D warnings`.
            $(caption_setter!($caption_opt);)*
            /// Sends the message silently — the recipient receives no notification sound.
            pub fn disable_notification(mut self, v: bool) -> Self { self.opts.disable_notification = Some(v); self }
            /// Attaches a message effect (animated emoji reaction) to the message.
            pub fn message_effect_id(mut self, id: impl Into<String>) -> Self { self.opts.message_effect_id = Some(id.into()); self }
            /// Protects the message from being forwarded or saved.
            pub fn protect_content(mut self, v: bool) -> Self { self.opts.protect_content = Some(v); self }
            /// Allows sending to large audiences at the cost of Telegram Stars.
            pub fn allow_paid_broadcast(mut self, v: bool) -> Self { self.opts.allow_paid_broadcast = Some(v); self }
            /// Reply parameters for this message.
            pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self { self.opts.reply_parameters = Some(rp); self }
            /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
            pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self { self.opts.reply_markup = Some(m.into()); self }
            /// Suggested post parameters for channel direct messages chats.
            pub fn suggested_post_parameters(mut self, params: SuggestedPostParameters) -> Self { self.opts.suggested_post_parameters = Some(params); self }
            /// For outgoing ephemeral messages — the user who will receive the message.
            pub fn receiver_user_id(mut self, id: i64) -> Self { self.opts.receiver_user_id = Some(id); self }
            /// For outgoing ephemeral messages — the callback query that triggered it, if any.
            pub fn callback_query_id(mut self, id: impl Into<String>) -> Self { self.opts.callback_query_id = Some(id.into()); self }

            $(
                #[doc = concat!("Sets the ", stringify!($extra_field), " for the media.")]
                pub fn $extra_field(mut self, v: $extra_ty) -> Self {
                    self.$extra_field = Some(v);
                    self
                }
            )*
        }

        impl IntoFuture for $name {
            type Output = Result<$return_ty>;
            type IntoFuture = Pin<Box<dyn Future<Output = Self::Output> + Send>>;

            fn into_future(self) -> Self::IntoFuture {
                Box::pin(async move {
                    match &self.file {
                        InputFile::Bytes { filename, data, mime_type } => {
                            let part = Part::bytes(data.clone())
                                .file_name(filename.clone())
                                .mime_str(mime_type)
                                .map_err(|e| crate::error::Error::Decode(e.to_string()))?;
                            let mut form = Form::new().part($field, part);
                            form = form.text("chat_id", self.chat_id.to_string());
                            // The shared helper, not a copy of its field list.
                            // This block used to enumerate the options by hand
                            // and covered ten of the seventeen, so every builder
                            // this macro generates silently dropped the other
                            // seven on a byte upload — protect_content and
                            // reply_parameters among them.
                            form = apply_media_opts(form, &self.opts);

                            $(
                                if let Some(ref v) = self.$extra_field {
                                    form = form.text(stringify!($extra_field), v.to_string());
                                }
                            )*

                            self.client.post_multipart($method, form).await
                        }
                        _ => {
                            let mut extra = serde_json::json!({});
                            $(
                                if let Some(ref v) = self.$extra_field {
                                    extra[stringify!($extra_field)] = serde_json::json!(v);
                                }
                            )*
                            let body = media_json_body(&self.chat_id, $field, self.file.as_str(), &self.opts, extra);
                            self.client.post_json($method, &body).await
                        }
                    }
                })
            }
        }
    };
}

media_sender!(
    /// Builder for the [`sendAudio`](https://core.telegram.org/bots/api#sendaudio) method.
    SendAudio,      "audio",      "sendAudio",      Message, [duration: u32, performer: String, title: String, thumbnail: String], [caption, parse_mode, caption_entities]);
media_sender!(
    /// Builder for the [`sendDocument`](https://core.telegram.org/bots/api#senddocument) method.
    SendDocument,  "document",   "sendDocument",  Message, [disable_content_type_detection: bool, thumbnail: String], [caption, parse_mode, caption_entities]);
media_sender!(
    /// Builder for the [`sendVideo`](https://core.telegram.org/bots/api#sendvideo) method.
    SendVideo,      "video",      "sendVideo",      Message, [duration: u32, width: u32, height: u32, supports_streaming: bool, cover: String, start_timestamp: i64, thumbnail: String], [caption, parse_mode, caption_entities, show_caption_above_media, has_spoiler]);
media_sender!(
    /// Builder for the [`sendAnimation`](https://core.telegram.org/bots/api#sendanimation) method.
    SendAnimation, "animation",  "sendAnimation", Message, [duration: u32, width: u32, height: u32, thumbnail: String], [caption, parse_mode, caption_entities, show_caption_above_media, has_spoiler]);
media_sender!(
    /// Builder for the [`sendVoice`](https://core.telegram.org/bots/api#sendvoice) method.
    SendVoice,      "voice",      "sendVoice",      Message, [duration: u32], [caption, parse_mode, caption_entities]);
media_sender!(
    /// Builder for the [`sendVideoNote`](https://core.telegram.org/bots/api#sendvideonote) method.
    SendVideoNote, "video_note", "sendVideoNote", Message, [duration: u32, length: u32, thumbnail: String], []);
media_sender!(
    /// Builder for the [`sendSticker`](https://core.telegram.org/bots/api#sendsticker) method.
    SendSticker,   "sticker",    "sendSticker",    Message, [emoji: String], []);

// ─── deleteMessage / deleteMessages ──────────────────────────────────────────

#[derive(Serialize)]
struct DeleteMessageParams {
    chat_id: ChatId,
    message_id: i64,
}

/// Builder for the [`deleteMessage`](https://core.telegram.org/bots/api#deletemessage) method.
pub struct DeleteMessage {
    client: BotClient,
    params: DeleteMessageParams,
}
impl DeleteMessage {
    pub(crate) fn new(client: BotClient, chat_id: impl Into<ChatId>, message_id: i64) -> Self {
        Self {
            client,
            params: DeleteMessageParams {
                chat_id: chat_id.into(),
                message_id,
            },
        }
    }
}
impl_into_future!(DeleteMessage, bool, "deleteMessage");

#[derive(Serialize)]
struct DeleteMessagesParams {
    chat_id: ChatId,
    message_ids: Vec<i64>,
}

/// Builder for the [`deleteMessages`](https://core.telegram.org/bots/api#deletemessages) method.
pub struct DeleteMessages {
    client: BotClient,
    params: DeleteMessagesParams,
}
impl DeleteMessages {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        message_ids: Vec<i64>,
    ) -> Self {
        Self {
            client,
            params: DeleteMessagesParams {
                chat_id: chat_id.into(),
                message_ids,
            },
        }
    }
}
impl_into_future!(DeleteMessages, bool, "deleteMessages");

// ─── deleteEphemeralMessage ───────────────────────────────────────────────────

#[derive(Serialize)]
struct DeleteEphemeralMessageParams {
    chat_id: ChatId,
    receiver_user_id: i64,
    ephemeral_message_id: i64,
}

/// Builder for the [`deleteEphemeralMessage`](https://core.telegram.org/bots/api#deleteephemeralmessage) method.
///
/// Note that it is not guaranteed that the user will receive the message
/// deletion event, especially if they are offline.
pub struct DeleteEphemeralMessage {
    client: BotClient,
    params: DeleteEphemeralMessageParams,
}
impl DeleteEphemeralMessage {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        receiver_user_id: i64,
        ephemeral_message_id: i64,
    ) -> Self {
        Self {
            client,
            params: DeleteEphemeralMessageParams {
                chat_id: chat_id.into(),
                receiver_user_id,
                ephemeral_message_id,
            },
        }
    }
}
impl_into_future!(DeleteEphemeralMessage, bool, "deleteEphemeralMessage");

// ─── stopPoll ─────────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct StopPollParams {
    chat_id: ChatId,
    message_id: i64,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<rustigram_types::keyboard::InlineKeyboardMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
}

/// Builder for the [`stopPoll`](https://core.telegram.org/bots/api#stoppoll) method.
pub struct StopPoll {
    client: BotClient,
    params: StopPollParams,
}
impl StopPoll {
    pub(crate) fn new(client: BotClient, chat_id: impl Into<ChatId>, message_id: i64) -> Self {
        Self {
            client,
            params: StopPollParams {
                chat_id: chat_id.into(),
                message_id,
                reply_markup: None,
                business_connection_id: None,
            },
        }
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: rustigram_types::keyboard::InlineKeyboardMarkup) -> Self {
        self.params.reply_markup = Some(m);
        self
    }
    /// Business connection ID for acting on behalf of a business account.
    pub fn business_connection_id(mut self, v: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(v.into());
        self
    }
}
impl_into_future!(StopPoll, rustigram_types::poll::Poll, "stopPoll");

// ─── answerCallbackQuery ──────────────────────────────────────────────────────

#[derive(Serialize)]
struct AnswerCallbackQueryParams {
    callback_query_id: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    text: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    show_alert: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    cache_time: Option<u32>,
}

/// Builder for the [`answerCallbackQuery`](https://core.telegram.org/bots/api#answercallbackquery) method.
pub struct AnswerCallbackQuery {
    client: BotClient,
    params: AnswerCallbackQueryParams,
}
impl AnswerCallbackQuery {
    pub(crate) fn new(client: BotClient, callback_query_id: impl Into<String>) -> Self {
        Self {
            client,
            params: AnswerCallbackQueryParams {
                callback_query_id: callback_query_id.into(),
                text: None,
                show_alert: None,
                url: None,
                cache_time: None,
            },
        }
    }
    /// The text of the notification shown to the user. 0–200 characters.
    pub fn text(mut self, t: impl Into<String>) -> Self {
        self.params.text = Some(t.into());
        self
    }
    /// Shows an alert dialog instead of a toast notification for the callback answer.
    pub fn show_alert(mut self, v: bool) -> Self {
        self.params.show_alert = Some(v);
        self
    }
    /// Sets the URL to open when the callback button answer is tapped.
    pub fn url(mut self, u: impl Into<String>) -> Self {
        self.params.url = Some(u.into());
        self
    }
    /// Sets how long the callback answer may be cached on the client in seconds.
    pub fn cache_time(mut self, secs: u32) -> Self {
        self.params.cache_time = Some(secs);
        self
    }
    /// Shorthand for `.text(t).show_alert(true)` — shows a popup alert to the user.
    pub fn alert(self, text: impl Into<String>) -> Self {
        self.text(text).show_alert(true)
    }
}
impl_into_future!(AnswerCallbackQuery, bool, "answerCallbackQuery");
// ─── forwardMessages ──────────────────────────────────────────────────────────

#[derive(Serialize)]
struct ForwardMessagesParams {
    chat_id: ChatId,
    from_chat_id: ChatId,
    message_ids: Vec<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
}

/// Builder for the [`forwardMessages`](https://core.telegram.org/bots/api#forwardmessages) method.
///
/// Forwards 1–100 messages at once, preserving album grouping.
/// Returns a `Vec<MessageId>` of the sent messages.
pub struct ForwardMessages {
    client: BotClient,
    params: ForwardMessagesParams,
}

impl ForwardMessages {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        from_chat_id: impl Into<ChatId>,
        message_ids: Vec<i64>,
    ) -> Self {
        Self {
            client,
            params: ForwardMessagesParams {
                chat_id: chat_id.into(),
                from_chat_id: from_chat_id.into(),
                message_ids,
                message_thread_id: None,
                direct_messages_topic_id: None,
                disable_notification: None,
                protect_content: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sends the messages silently — recipients receive no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the messages from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
}

impl_into_future!(
    ForwardMessages,
    Vec<rustigram_types::message::MessageId>,
    "forwardMessages"
);

// ─── copyMessages ─────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct CopyMessagesParams {
    chat_id: ChatId,
    from_chat_id: ChatId,
    message_ids: Vec<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    remove_caption: Option<bool>,
}

/// Builder for the [`copyMessages`](https://core.telegram.org/bots/api#copymessages) method.
///
/// Copies 1–100 messages without a forward link, preserving album grouping.
/// Returns a `Vec<MessageId>` of the sent messages.
pub struct CopyMessages {
    client: BotClient,
    params: CopyMessagesParams,
}

impl CopyMessages {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        from_chat_id: impl Into<ChatId>,
        message_ids: Vec<i64>,
    ) -> Self {
        Self {
            client,
            params: CopyMessagesParams {
                chat_id: chat_id.into(),
                from_chat_id: from_chat_id.into(),
                message_ids,
                message_thread_id: None,
                direct_messages_topic_id: None,
                disable_notification: None,
                protect_content: None,
                remove_caption: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sends the messages silently — recipients receive no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the messages from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Copies the messages without their captions.
    pub fn remove_caption(mut self, v: bool) -> Self {
        self.params.remove_caption = Some(v);
        self
    }
}

impl_into_future!(
    CopyMessages,
    Vec<rustigram_types::message::MessageId>,
    "copyMessages"
);

// ─── sendVenue ────────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendVenueParams {
    chat_id: ChatId,
    latitude: f64,
    longitude: f64,
    title: String,
    address: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    foursquare_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    foursquare_type: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    google_place_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    google_place_type: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<ReplyMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    receiver_user_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    callback_query_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
}

/// Builder for the [`sendVenue`](https://core.telegram.org/bots/api#sendvenue) method.
pub struct SendVenue {
    client: BotClient,
    params: SendVenueParams,
}

impl SendVenue {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        latitude: f64,
        longitude: f64,
        title: impl Into<String>,
        address: impl Into<String>,
    ) -> Self {
        Self {
            client,
            params: SendVenueParams {
                chat_id: chat_id.into(),
                latitude,
                longitude,
                title: title.into(),
                address: address.into(),
                message_thread_id: None,
                direct_messages_topic_id: None,
                foursquare_id: None,
                foursquare_type: None,
                google_place_id: None,
                google_place_type: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                reply_markup: None,
                receiver_user_id: None,
                callback_query_id: None,
                business_connection_id: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
                suggested_post_parameters: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sets the Foursquare identifier of the venue.
    pub fn foursquare_id(mut self, id: impl Into<String>) -> Self {
        self.params.foursquare_id = Some(id.into());
        self
    }
    /// Sets the Foursquare type of the venue (e.g. `"arts_entertainment/aquarium"`).
    pub fn foursquare_type(mut self, t: impl Into<String>) -> Self {
        self.params.foursquare_type = Some(t.into());
        self
    }
    /// Sets the Google Places identifier of the venue.
    pub fn google_place_id(mut self, id: impl Into<String>) -> Self {
        self.params.google_place_id = Some(id.into());
        self
    }
    /// Sets the Google Places type of the venue.
    pub fn google_place_type(mut self, t: impl Into<String>) -> Self {
        self.params.google_place_type = Some(t.into());
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(rp);
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.params.reply_markup = Some(m.into());
        self
    }
    /// For outgoing ephemeral messages — the user who will receive the message.
    pub fn receiver_user_id(mut self, id: i64) -> Self {
        self.params.receiver_user_id = Some(id);
        self
    }
    /// For outgoing ephemeral messages — the callback query that triggered it, if any.
    pub fn callback_query_id(mut self, id: impl Into<String>) -> Self {
        self.params.callback_query_id = Some(id.into());
        self
    }
    /// Business connection ID for acting on behalf of a business account.
    pub fn business_connection_id(mut self, v: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(v.into());
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, v: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(v);
        self
    }
}

impl_into_future!(SendVenue, Message, "sendVenue");

// ─── sendMediaGroup ───────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendMediaGroupParams {
    chat_id: ChatId,
    /// Array of `InputMedia` objects (photo, video, audio, or document).
    /// Pass the result of `serde_json::to_value(&your_input_media_vec)`.
    media: Vec<InputMedia>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
}

/// Builder for the [`sendMediaGroup`](https://core.telegram.org/bots/api#sendmediagroup) method.
///
/// Sends a group of photos, videos, documents, or audios as an album (2–10 items).
///
pub struct SendMediaGroup {
    client: BotClient,
    params: SendMediaGroupParams,
}

impl SendMediaGroup {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        media: Vec<InputMedia>,
    ) -> Self {
        Self {
            client,
            params: SendMediaGroupParams {
                chat_id: chat_id.into(),
                media,
                message_thread_id: None,
                direct_messages_topic_id: None,
                business_connection_id: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
            },
        }
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Business connection ID for sending on behalf of a business account.
    pub fn business_connection_id(mut self, id: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(id.into());
        self
    }
    /// Sends the messages silently — recipients receive no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the messages from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(rp);
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
}

impl_into_future!(SendMediaGroup, Vec<Message>, "sendMediaGroup");

// ─── sendPaidMedia ────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendPaidMediaParams {
    chat_id: ChatId,
    star_count: u32,
    /// Array of `InputPaidMedia` objects (photo or video).
    /// Pass the result of `serde_json::to_value(&your_paid_media_vec)`.
    media: Vec<InputPaidMedia>,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    payload: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    caption: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    parse_mode: Option<ParseMode>,
    #[serde(skip_serializing_if = "Option::is_none")]
    show_caption_above_media: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<ReplyMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    caption_entities: Option<Vec<rustigram_types::message::MessageEntity>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
}

/// Builder for the [`sendPaidMedia`](https://core.telegram.org/bots/api#sendpaidmedia) method.
///
/// Sends paid media that users must pay Telegram Stars to view (up to 10 items).
///
pub struct SendPaidMedia {
    client: BotClient,
    params: SendPaidMediaParams,
}

impl SendPaidMedia {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        star_count: u32,
        media: Vec<InputPaidMedia>,
    ) -> Self {
        Self {
            client,
            params: SendPaidMediaParams {
                chat_id: chat_id.into(),
                star_count,
                media,
                business_connection_id: None,
                payload: None,
                caption: None,
                parse_mode: None,
                show_caption_above_media: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                reply_markup: None,
                allow_paid_broadcast: None,
                caption_entities: None,
                direct_messages_topic_id: None,
                message_thread_id: None,
                suggested_post_parameters: None,
            },
        }
    }
    /// Business connection ID for sending on behalf of a business account.
    pub fn business_connection_id(mut self, id: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(id.into());
        self
    }
    /// Bot-defined paid media payload (0–128 bytes); not shown to the user.
    pub fn payload(mut self, p: impl Into<String>) -> Self {
        self.params.payload = Some(p.into());
        self
    }
    /// Sets the caption (0–1024 characters).
    pub fn caption(mut self, c: impl Into<String>) -> Self {
        self.params.caption = Some(c.into());
        self
    }
    /// Sets the caption parse mode (`MarkdownV2`, `HTML`, or `Markdown`).
    pub fn parse_mode(mut self, m: ParseMode) -> Self {
        self.params.parse_mode = Some(m);
        self
    }
    /// Shows the caption above the media instead of below it.
    pub fn show_caption_above_media(mut self, v: bool) -> Self {
        self.params.show_caption_above_media = Some(v);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(rp);
        self
    }
    /// Attaches a reply markup (inline keyboard, reply keyboard, etc.).
    pub fn reply_markup(mut self, m: impl Into<ReplyMarkup>) -> Self {
        self.params.reply_markup = Some(m.into());
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Special entities in the caption, in place of `parse_mode`.
    pub fn caption_entities(mut self, v: Vec<rustigram_types::message::MessageEntity>) -> Self {
        self.params.caption_entities = Some(v);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, v: i64) -> Self {
        self.params.direct_messages_topic_id = Some(v);
        self
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, v: i64) -> Self {
        self.params.message_thread_id = Some(v);
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, v: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(v);
        self
    }
}

impl_into_future!(SendPaidMedia, Message, "sendPaidMedia");

// ─── sendGame ─────────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendGameParams {
    chat_id: i64,
    game_short_name: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<rustigram_types::keyboard::InlineKeyboardMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
}

/// Builder for the [`sendGame`](https://core.telegram.org/bots/api#sendgame) method.
///
/// Note: `chat_id` is an integer — games can't be sent to channel direct messages
/// chats or channel chats.
pub struct SendGame {
    client: BotClient,
    params: SendGameParams,
}

impl SendGame {
    pub(crate) fn new(client: BotClient, chat_id: i64, game_short_name: impl Into<String>) -> Self {
        Self {
            client,
            params: SendGameParams {
                chat_id,
                game_short_name: game_short_name.into(),
                business_connection_id: None,
                message_thread_id: None,
                direct_messages_topic_id: None,
                disable_notification: None,
                protect_content: None,
                reply_parameters: None,
                reply_markup: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
            },
        }
    }
    /// Business connection ID for sending on behalf of a business account.
    pub fn business_connection_id(mut self, id: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(id.into());
        self
    }
    /// Forum topic thread ID.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(rp);
        self
    }
    /// Attaches an inline keyboard. The first button must launch the game.
    pub fn reply_markup(mut self, m: rustigram_types::keyboard::InlineKeyboardMarkup) -> Self {
        self.params.reply_markup = Some(m);
        self
    }
    /// Allows sending to large audiences at the cost of Telegram Stars.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Attaches a message effect (animated emoji reaction) to the message.
    pub fn message_effect_id(mut self, v: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(v.into());
        self
    }
}

impl_into_future!(SendGame, Message, "sendGame");

// ─── sendChecklist ────────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendChecklistParams {
    business_connection_id: String,
    chat_id: i64,
    checklist: rustigram_types::checklist::InputChecklist,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<rustigram_types::keyboard::InlineKeyboardMarkup>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
}

/// Builder for the [`sendChecklist`](https://core.telegram.org/bots/api#sendchecklist) method.
///
/// Business bots only — sends a checklist on behalf of a connected business account.
/// Requires the `can_reply` business bot right.
pub struct SendChecklist {
    client: BotClient,
    params: SendChecklistParams,
}

impl SendChecklist {
    pub(crate) fn new(
        client: BotClient,
        business_connection_id: impl Into<String>,
        chat_id: i64,
        checklist: rustigram_types::checklist::InputChecklist,
    ) -> Self {
        Self {
            client,
            params: SendChecklistParams {
                business_connection_id: business_connection_id.into(),
                chat_id,
                checklist,
                direct_messages_topic_id: None,
                disable_notification: None,
                protect_content: None,
                message_effect_id: None,
                reply_parameters: None,
                reply_markup: None,
                suggested_post_parameters: None,
            },
        }
    }
    /// Identifier of a direct messages chat topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sends the message silently — the recipient receives no notification sound.
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Unique identifier of the message effect to add to the message.
    pub fn message_effect_id(mut self, id: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(id.into());
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(rp);
        self
    }
    /// Attaches an inline keyboard to the message.
    pub fn reply_markup(mut self, m: rustigram_types::keyboard::InlineKeyboardMarkup) -> Self {
        self.params.reply_markup = Some(m);
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, params: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(params);
        self
    }
}

impl_into_future!(SendChecklist, Message, "sendChecklist");

// ─── sendRichMessage ──────────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendRichMessageParams {
    chat_id: ChatId,
    rich_message: rustigram_types::rich_message::InputRichMessage,
    #[serde(skip_serializing_if = "Option::is_none")]
    business_connection_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    direct_messages_topic_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    disable_notification: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    protect_content: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allow_paid_broadcast: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_effect_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    suggested_post_parameters: Option<SuggestedPostParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_parameters: Option<ReplyParameters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    reply_markup: Option<rustigram_types::keyboard::ReplyMarkup>,
}

/// Builder for the [`sendRichMessage`](https://core.telegram.org/bots/api#sendrichmessage) method.
pub struct SendRichMessage {
    client: BotClient,
    params: SendRichMessageParams,
}

impl SendRichMessage {
    pub(crate) fn new(
        client: BotClient,
        chat_id: impl Into<ChatId>,
        rich_message: rustigram_types::rich_message::InputRichMessage,
    ) -> Self {
        Self {
            client,
            params: SendRichMessageParams {
                chat_id: chat_id.into(),
                rich_message,
                business_connection_id: None,
                message_thread_id: None,
                direct_messages_topic_id: None,
                disable_notification: None,
                protect_content: None,
                allow_paid_broadcast: None,
                message_effect_id: None,
                suggested_post_parameters: None,
                reply_parameters: None,
                reply_markup: None,
            },
        }
    }

    /// Sets the business connection identifier.
    pub fn business_connection_id(mut self, id: impl Into<String>) -> Self {
        self.params.business_connection_id = Some(id.into());
        self
    }
    /// Sends the message to the specified topic thread.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
    /// Sends the message to the specified direct messages topic.
    pub fn direct_messages_topic_id(mut self, id: i64) -> Self {
        self.params.direct_messages_topic_id = Some(id);
        self
    }
    /// Sends the message silently (no notification sound).
    pub fn disable_notification(mut self, v: bool) -> Self {
        self.params.disable_notification = Some(v);
        self
    }
    /// Protects the message from being forwarded or saved.
    pub fn protect_content(mut self, v: bool) -> Self {
        self.params.protect_content = Some(v);
        self
    }
    /// Allows up to 1 000 messages per second by paying 0.1 Stars per message.
    pub fn allow_paid_broadcast(mut self, v: bool) -> Self {
        self.params.allow_paid_broadcast = Some(v);
        self
    }
    /// Unique identifier of the message effect to add to the message.
    pub fn message_effect_id(mut self, id: impl Into<String>) -> Self {
        self.params.message_effect_id = Some(id.into());
        self
    }
    /// Suggested post parameters for channel direct messages chats.
    pub fn suggested_post_parameters(mut self, p: SuggestedPostParameters) -> Self {
        self.params.suggested_post_parameters = Some(p);
        self
    }
    /// Reply parameters for this message.
    pub fn reply_parameters(mut self, rp: ReplyParameters) -> Self {
        self.params.reply_parameters = Some(rp);
        self
    }
    /// Attaches a reply markup to the message.
    pub fn reply_markup(mut self, m: rustigram_types::keyboard::ReplyMarkup) -> Self {
        self.params.reply_markup = Some(m);
        self
    }
}

impl_into_future!(SendRichMessage, Message, "sendRichMessage");

// ─── sendRichMessageDraft ─────────────────────────────────────────────────────

#[derive(Serialize)]
struct SendRichMessageDraftParams {
    chat_id: i64,
    draft_id: i64,
    rich_message: rustigram_types::rich_message::InputRichMessage,
    #[serde(skip_serializing_if = "Option::is_none")]
    message_thread_id: Option<i64>,
}

/// Builder for the [`sendRichMessageDraft`](https://core.telegram.org/bots/api#sendrichmessagedraft) method.
///
/// Streams a partial rich message as a 30-second ephemeral preview.
/// Once generation is complete, call [`SendRichMessage`] with the full content to persist it.
pub struct SendRichMessageDraft {
    client: BotClient,
    params: SendRichMessageDraftParams,
}

impl SendRichMessageDraft {
    pub(crate) fn new(
        client: BotClient,
        chat_id: i64,
        draft_id: i64,
        rich_message: rustigram_types::rich_message::InputRichMessage,
    ) -> Self {
        Self {
            client,
            params: SendRichMessageDraftParams {
                chat_id,
                draft_id,
                rich_message,
                message_thread_id: None,
            },
        }
    }

    /// Sends the draft to the specified topic thread.
    pub fn message_thread_id(mut self, id: i64) -> Self {
        self.params.message_thread_id = Some(id);
        self
    }
}

impl_into_future!(SendRichMessageDraft, bool, "sendRichMessageDraft");

#[cfg(test)]
mod tests {
    use super::*;
    use crate::client::BotClient;

    fn client() -> BotClient {
        BotClient::from_token("123456:test-token-for-unit-tests").unwrap()
    }

    /// The four parameters Telegram added API-wide had only ever been applied to
    /// `send_message`; these are the siblings that were missing them.
    #[test]
    fn api_wide_parameters_serialize_on_the_json_path() {
        let contact = SendContact::new(client(), 1_i64, "+100", "A")
            .business_connection_id("biz")
            .allow_paid_broadcast(true)
            .message_effect_id("effect")
            .suggested_post_parameters(SuggestedPostParameters {
                price: None,
                send_date: Some(1_700_000_000),
            });
        let json = serde_json::to_value(&contact.params).unwrap();

        assert_eq!(json["business_connection_id"], "biz");
        assert_eq!(json["allow_paid_broadcast"], true);
        assert_eq!(json["message_effect_id"], "effect");
        assert!(json.get("suggested_post_parameters").is_some());
    }

    /// Unset optional parameters must stay off the wire entirely.
    #[test]
    fn unset_parameters_are_omitted() {
        let dice = SendDice::new(client(), 1_i64);
        let json = serde_json::to_value(&dice.params).unwrap();
        for key in [
            "business_connection_id",
            "allow_paid_broadcast",
            "message_effect_id",
            "suggested_post_parameters",
        ] {
            assert!(
                json.get(key).is_none(),
                "{key} should be omitted when unset"
            );
        }
    }

    /// The spec marks this optional; it used to be a bare `String`, so a draft
    /// carrying only media could not be expressed.
    #[test]
    fn message_draft_text_can_be_cleared() {
        let draft = SendMessageDraft::new(client(), 1_i64, 7, "hello");
        assert_eq!(
            serde_json::to_value(&draft.params).unwrap()["text"],
            "hello"
        );

        let empty = SendMessageDraft::new(client(), 1_i64, 7, "hello").clear_text();
        assert!(serde_json::to_value(&empty.params)
            .unwrap()
            .get("text")
            .is_none());
    }

    /// Regression guard for the multipart path. Both send paths must enumerate
    /// the same options struct: the hand-written form used to drop five fields,
    /// so `.reply_to(..)` on an uploaded photo silently never reached Telegram.
    #[test]
    fn multipart_and_json_paths_cover_the_same_options() {
        let source = include_str!("sending.rs");
        let struct_body = source
            .split("pub struct MediaSendOptions {")
            .nth(1)
            .and_then(|s| s.split("\n}").next())
            .expect("MediaSendOptions struct");
        let fields: Vec<&str> = struct_body
            .lines()
            .filter_map(|l| l.trim().strip_prefix("pub "))
            .filter_map(|l| l.split(':').next())
            .collect();
        assert_eq!(
            fields.len(),
            17,
            "field count changed; update both send paths"
        );

        // Both helpers, not one. This guard previously read only
        // `apply_media_opts` while its name claimed both paths, and
        // `message_effect_id` was duly added to the multipart form and left out
        // of the JSON body — a settable option that never reached Telegram on
        // every send by file_id or URL.
        for (helper, path) in [
            ("fn apply_media_opts(", "multipart form"),
            ("fn media_json_body(", "JSON body"),
        ] {
            let body = source
                .split(helper)
                .nth(1)
                .and_then(|s| s.split("\nfn ").next())
                .unwrap_or_else(|| panic!("{helper} body"));
            for field in &fields {
                assert!(
                    body.contains(&format!("opts.{field}")),
                    "`{field}` is settable but never written to the {path}"
                );
            }
        }
    }
}