macltok

public
Star0
Watch0
1 commit 3 branches 0 tags 0 releases3.0 MiB
use std::{fmt, sync::Arc};

use ruma::{
    OwnedDeviceId, OwnedEventId, OwnedMxcUri, OwnedRoomAliasId, OwnedRoomId, OwnedRoomOrAliasId,
    OwnedServerName, OwnedTransactionId, OwnedUserId,
    events::{AnySyncTimelineEvent, room::member::StrippedRoomMemberEvent},
    serde::Raw,
};
#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

#[derive(Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum Command {
    Account(AccountCommand),
    Room(RoomCommand),
    Timeline(TimelineCommand),
    Media(MediaCommand),
    Encryption(EncryptionCommand),
    Notification(NotificationCommand),
    Lifecycle(LifecycleCommand),
}

#[derive(Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum AccountCommand {
    Logout,
    RenameDevice {
        device_id: OwnedDeviceId,
        display_name: String,
    },
    DeleteDevices {
        device_ids: Vec<OwnedDeviceId>,
        auth: Option<crate::InteractiveAuth>,
    },
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum RoomCommand {
    Open(OwnedRoomId),
    Close(OwnedRoomId),
    Join {
        room: OwnedRoomOrAliasId,
        via: Vec<OwnedServerName>,
    },
    Leave(OwnedRoomId),
    Forget(OwnedRoomId),
    AcceptInvite(OwnedRoomId),
    RejectInvite(OwnedRoomId),
    InviteUser {
        room_id: OwnedRoomId,
        user_id: OwnedUserId,
    },
    KickUser {
        room_id: OwnedRoomId,
        user_id: OwnedUserId,
        reason: Option<String>,
    },
    BanUser {
        room_id: OwnedRoomId,
        user_id: OwnedUserId,
        reason: Option<String>,
    },
    UnbanUser {
        room_id: OwnedRoomId,
        user_id: OwnedUserId,
        reason: Option<String>,
    },
    SetPowerLevels {
        room_id: OwnedRoomId,
        changes: PowerLevelChanges,
    },
    SetUserPowerLevel {
        room_id: OwnedRoomId,
        user_id: OwnedUserId,
        level: i64,
    },
    Create(CreateRoomOptions),
    CreateDirect(OwnedUserId),
    CancelSend {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
    },
    RetrySend {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
    },
    MarkRead {
        timeline_id: TimelineId,
        event_id: OwnedEventId,
    },
    SetTyping {
        room_id: OwnedRoomId,
        typing: bool,
    },
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct CreateRoomOptions {
    pub name: Option<String>,
    pub topic: Option<String>,
    pub alias_localpart: Option<String>,
    pub invite: Vec<OwnedUserId>,
    pub direct: bool,
    pub visibility: RoomVisibility,
    pub preset: Option<RoomPreset>,
}

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum RoomVisibility {
    #[default]
    Private,
    Public,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum RoomPreset {
    PrivateChat,
    TrustedPrivateChat,
    PublicChat,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum TimelineCommand {
    OpenThread {
        room_id: OwnedRoomId,
        root_event_id: OwnedEventId,
    },
    CloseThread {
        room_id: OwnedRoomId,
        root_event_id: OwnedEventId,
    },
    /// Re-emit an authoritative reset for an open room or thread without
    /// closing it. The reset arrives before this command's terminal result.
    Resync {
        timeline_id: TimelineId,
    },
    Paginate {
        timeline_id: TimelineId,
        limit: u16,
    },
    Send {
        timeline_id: TimelineId,
        content: MessageContent,
    },
    Edit {
        timeline_id: TimelineId,
        event_id: OwnedEventId,
        content: MessageEditContent,
    },
    Redact {
        timeline_id: TimelineId,
        event_id: OwnedEventId,
        reason: Option<String>,
    },
    ToggleReaction {
        timeline_id: TimelineId,
        event_id: OwnedEventId,
        key: String,
    },
}

impl TimelineCommand {
    #[must_use]
    pub const fn room_id(&self) -> &OwnedRoomId {
        match self {
            Self::OpenThread { room_id, .. } | Self::CloseThread { room_id, .. } => room_id,
            Self::Resync { timeline_id }
            | Self::Paginate { timeline_id, .. }
            | Self::Send { timeline_id, .. }
            | Self::Edit { timeline_id, .. }
            | Self::Redact { timeline_id, .. }
            | Self::ToggleReaction { timeline_id, .. } => timeline_id.room_id(),
        }
    }

    #[must_use]
    pub const fn timeline_id(&self) -> Option<&TimelineId> {
        match self {
            Self::OpenThread { .. } | Self::CloseThread { .. } => None,
            Self::Resync { timeline_id }
            | Self::Paginate { timeline_id, .. }
            | Self::Send { timeline_id, .. }
            | Self::Edit { timeline_id, .. }
            | Self::Redact { timeline_id, .. }
            | Self::ToggleReaction { timeline_id, .. } => Some(timeline_id),
        }
    }
}

#[derive(Clone, Debug, Eq, Hash, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum TimelineId {
    Room(OwnedRoomId),
    Thread {
        room_id: OwnedRoomId,
        root_event_id: OwnedEventId,
    },
}

impl TimelineId {
    #[must_use]
    pub const fn room_id(&self) -> &OwnedRoomId {
        match self {
            Self::Room(room_id) | Self::Thread { room_id, .. } => room_id,
        }
    }

    #[must_use]
    pub fn thread(room_id: OwnedRoomId, root_event_id: OwnedEventId) -> Self {
        Self::Thread {
            room_id,
            root_event_id,
        }
    }

    #[must_use]
    pub fn thread_root(&self) -> Option<&OwnedEventId> {
        match self {
            Self::Room(_) => None,
            Self::Thread { root_event_id, .. } => Some(root_event_id),
        }
    }
}

impl From<OwnedRoomId> for TimelineId {
    fn from(room_id: OwnedRoomId) -> Self {
        Self::Room(room_id)
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum MediaCommand {
    Fetch {
        id: MediaId,
        size: MediaSize,
    },
    Upload {
        timeline_id: TimelineId,
        filename: String,
        mimetype: String,
        bytes: Vec<u8>,
        caption: Option<String>,
    },
    UploadAttachment(AttachmentUpload),
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct AttachmentUpload {
    pub timeline_id: TimelineId,
    pub filename: String,
    pub mimetype: String,
    pub bytes: Vec<u8>,
    pub caption: Option<String>,
    pub details: Option<UploadDetails>,
    pub thumbnail: Option<UploadThumbnail>,
}

impl AttachmentUpload {
    #[must_use]
    pub fn new(
        timeline_id: impl Into<TimelineId>,
        filename: impl Into<String>,
        mimetype: impl Into<String>,
        bytes: Vec<u8>,
    ) -> Self {
        Self {
            timeline_id: timeline_id.into(),
            filename: filename.into(),
            mimetype: mimetype.into(),
            bytes,
            caption: None,
            details: None,
            thumbnail: None,
        }
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum UploadDetails {
    Image {
        width: Option<u32>,
        height: Option<u32>,
        blurhash: Option<String>,
    },
    Video {
        width: Option<u32>,
        height: Option<u32>,
        duration_ms: Option<u64>,
        blurhash: Option<String>,
    },
    Audio {
        duration_ms: Option<u64>,
    },
    Voice {
        duration_ms: u64,
        waveform: Vec<u16>,
    },
    File,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct UploadThumbnail {
    pub bytes: Vec<u8>,
    pub mimetype: String,
    pub width: u32,
    pub height: u32,
}

#[derive(Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum EncryptionCommand {
    Recover(String),
    CreateKeyBackup,
    EnableKeyBackup,
    DisableKeyBackup { delete_from_server: bool },
    RecoverKeyBackup(String),
    StartVerification(VerificationTarget),
    Verify(VerificationAction),
}

impl fmt::Debug for EncryptionCommand {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Recover(_) => formatter.debug_tuple("Recover").field(&"...").finish(),
            Self::CreateKeyBackup => formatter.write_str("CreateKeyBackup"),
            Self::EnableKeyBackup => formatter.write_str("EnableKeyBackup"),
            Self::DisableKeyBackup { delete_from_server } => formatter
                .debug_struct("DisableKeyBackup")
                .field("delete_from_server", delete_from_server)
                .finish(),
            Self::RecoverKeyBackup(_) => formatter
                .debug_tuple("RecoverKeyBackup")
                .field(&"...")
                .finish(),
            Self::StartVerification(target) => formatter
                .debug_tuple("StartVerification")
                .field(target)
                .finish(),
            Self::Verify(action) => formatter.debug_tuple("Verify").field(action).finish(),
        }
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum NotificationCommand {
    SetRoomMode {
        room_id: OwnedRoomId,
        mode: RoomNotificationMode,
    },
    ResetRoomMode(OwnedRoomId),
    SetDefaultMode {
        encrypted: bool,
        one_to_one: bool,
        mode: RoomNotificationMode,
    },
    AddKeyword(String),
    RemoveKeyword(String),
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum LifecycleCommand {
    Shutdown,
}

impl Command {
    #[must_use]
    pub const fn kind(&self) -> CommandKind {
        match self {
            Self::Account(_) => CommandKind::Account,
            Self::Room(_) => CommandKind::Room,
            Self::Timeline(_) => CommandKind::Timeline,
            Self::Media(_) => CommandKind::Media,
            Self::Encryption(_) => CommandKind::Encryption,
            Self::Notification(_) => CommandKind::Notification,
            Self::Lifecycle(_) => CommandKind::Lifecycle,
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum CommandKind {
    Account,
    Room,
    Timeline,
    Media,
    Encryption,
    Notification,
    Lifecycle,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum MessageContent {
    Text {
        content: RichText,
        mentions: MessageMentions,
    },
    Emote {
        content: RichText,
        mentions: MessageMentions,
    },
    Reply {
        event_id: OwnedEventId,
        content: RichText,
        mentions: MessageMentions,
        notify_replied_to: bool,
    },
}

impl MessageContent {
    #[must_use]
    pub fn text(body: impl Into<String>) -> Self {
        Self::Text {
            content: RichText::plain(body),
            mentions: MessageMentions::default(),
        }
    }

    #[must_use]
    pub fn html(body: impl Into<String>, formatted_body: impl Into<String>) -> Self {
        Self::Text {
            content: RichText::html(body, formatted_body),
            mentions: MessageMentions::default(),
        }
    }

    #[must_use]
    pub fn emote(content: RichText, mentions: MessageMentions) -> Self {
        Self::Emote { content, mentions }
    }

    #[must_use]
    pub fn reply(event_id: OwnedEventId, content: RichText, mentions: MessageMentions) -> Self {
        Self::Reply {
            event_id,
            content,
            mentions,
            notify_replied_to: true,
        }
    }

    #[must_use]
    pub fn reply_without_notification(
        event_id: OwnedEventId,
        content: RichText,
        mentions: MessageMentions,
    ) -> Self {
        Self::Reply {
            event_id,
            content,
            mentions,
            notify_replied_to: false,
        }
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum MessageEditContent {
    Text {
        content: RichText,
        mentions: MessageMentions,
    },
    Emote {
        content: RichText,
        mentions: MessageMentions,
    },
}

impl MessageEditContent {
    #[must_use]
    pub fn text(body: impl Into<String>) -> Self {
        Self::Text {
            content: RichText::plain(body),
            mentions: MessageMentions::default(),
        }
    }

    #[must_use]
    pub fn html(body: impl Into<String>, formatted_body: impl Into<String>) -> Self {
        Self::Text {
            content: RichText::html(body, formatted_body),
            mentions: MessageMentions::default(),
        }
    }

    #[must_use]
    pub fn emote(content: RichText, mentions: MessageMentions) -> Self {
        Self::Emote { content, mentions }
    }
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct RichText {
    pub body: String,
    pub formatted_body: Option<String>,
}

impl RichText {
    #[must_use]
    pub fn plain(body: impl Into<String>) -> Self {
        Self {
            body: body.into(),
            formatted_body: None,
        }
    }

    #[must_use]
    pub fn html(body: impl Into<String>, formatted_body: impl Into<String>) -> Self {
        Self {
            body: body.into(),
            formatted_body: Some(formatted_body.into()),
        }
    }
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct MessageMentions {
    pub user_ids: Vec<OwnedUserId>,
    pub room: bool,
}

impl MessageMentions {
    #[must_use]
    pub fn with_user_ids(user_ids: impl IntoIterator<Item = OwnedUserId>) -> Self {
        Self {
            user_ids: user_ids.into_iter().collect(),
            room: false,
        }
    }

    #[must_use]
    pub fn room() -> Self {
        Self {
            user_ids: Vec::new(),
            room: true,
        }
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum Event {
    ConnectionChanged(ConnectionState),
    Authenticated {
        user_id: OwnedUserId,
    },
    /// Refresh tokens changed. Persist a fresh `ClientHandle::session_record()`
    /// atomically; a record captured before this event may no longer restore.
    SessionTokensChanged,
    /// Authentication was rejected. Remove the saved session record and store.
    SessionAccessRejected,
    NotificationSettingsChanged,
    VerificationTargetChanged(VerificationTarget),
    InteractiveAuthRequired {
        id: CommandId,
        command: CommandKind,
        challenge: crate::InteractiveAuthChallenge,
    },
    RoomsChanged,
    /// Authoritative snapshot on open or resync. A resync reset precedes the
    /// corresponding terminal command event on this stream.
    TimelineReset {
        timeline_id: TimelineId,
        items: Vec<TimelineItem>,
    },
    TimelineChanged {
        timeline_id: TimelineId,
        diffs: Vec<TimelineDiff>,
    },
    HistoryChanged {
        timeline_id: TimelineId,
        state: HistoryState,
    },
    TypingChanged(TypingState),
    MediaReady {
        media_id: MediaId,
        size: MediaSize,
        bytes: Arc<[u8]>,
        mimetype: String,
    },
    MediaUploadProgress {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
        uploaded_bytes: u64,
        total_bytes: u64,
        complete: bool,
    },
    MediaUploadFailed {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
        kind: CommandErrorKind,
        recoverable: bool,
    },
    EncryptionChanged(EncryptionState),
    VerificationChanged(VerificationState),
    /// Terminal command success. For sends, this means the SDK send queue
    /// accepted the item; network delivery is reflected by its send state.
    CommandSucceeded {
        id: CommandId,
        command: CommandKind,
    },
    CommandSucceededWithRoom {
        id: CommandId,
        command: CommandKind,
        room_id: OwnedRoomId,
    },
    /// Terminal failure correlated by `CommandFailure::id`.
    CommandFailed(CommandFailure),
    /// Explicit logout completed; delete the saved authentication record.
    LoggedOut,
    Failed(EngineFailure),
    /// Engine stopped without logging out; retain saved credentials for restore.
    Stopped,
}

#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct CommandId(u64);

impl CommandId {
    pub(crate) const fn new(value: u64) -> Self {
        Self(value)
    }

    #[must_use]
    pub const fn get(self) -> u64 {
        self.0
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum ConnectionState {
    Idle,
    Connecting,
    Online,
    Offline,
    Stopped,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct RoomSummary {
    pub room_id: OwnedRoomId,
    pub name: String,
    pub membership: RoomMembership,
    pub unread_messages: u64,
    pub unread_mentions: u64,
    pub encrypted: bool,
    pub space: bool,
    pub direct: bool,
    pub favourite: bool,
    pub low_priority: bool,
    pub avatar: Option<OwnedMxcUri>,
    pub latest_event_timestamp_ms: Option<u64>,
    pub notification_mode: Option<RoomNotificationMode>,
    pub notification_mode_custom: bool,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum RoomNotificationMode {
    AllMessages,
    MentionsAndKeywordsOnly,
    Mute,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct RoomNotificationSettings {
    pub mode: RoomNotificationMode,
    pub custom: bool,
}

#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum PushNotificationStatus {
    Event(Box<PushNotification>),
    NotFound,
    FilteredOut,
    Redacted,
}

#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct PushNotification {
    pub event_id: OwnedEventId,
    pub event: PushNotificationEvent,
    pub sender: PushNotificationSender,
    pub room: PushNotificationRoom,
    pub noisy: Option<bool>,
    pub has_mention: Option<bool>,
    pub thread_id: Option<OwnedEventId>,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct PushNotificationSender {
    pub user_id: OwnedUserId,
    pub display_name: Option<String>,
    pub avatar_url: Option<OwnedMxcUri>,
    pub name_ambiguous: bool,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct PushNotificationRoom {
    pub room_id: OwnedRoomId,
    pub name: String,
    pub avatar_url: Option<OwnedMxcUri>,
    pub canonical_alias: Option<OwnedRoomAliasId>,
    pub topic: Option<String>,
    pub encrypted: Option<bool>,
    pub direct: bool,
    pub joined_members_count: u64,
    pub service_members: Vec<OwnedUserId>,
    pub active_service_members_count: u64,
    pub space: bool,
}

#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum PushNotificationEvent {
    Timeline(Raw<AnySyncTimelineEvent>),
    Invite(Raw<StrippedRoomMemberEvent>),
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct RoomPowerLevels {
    pub ban: i64,
    pub invite: i64,
    pub kick: i64,
    pub redact: i64,
    pub events_default: i64,
    pub state_default: i64,
    pub users_default: i64,
    pub room_notification: i64,
    pub users: Vec<(OwnedUserId, i64)>,
    pub events: Vec<(String, i64)>,
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct PowerLevelChanges {
    pub ban: Option<i64>,
    pub invite: Option<i64>,
    pub kick: Option<i64>,
    pub redact: Option<i64>,
    pub events_default: Option<i64>,
    pub state_default: Option<i64>,
    pub users_default: Option<i64>,
    pub room_notification: Option<i64>,
    pub room_name: Option<i64>,
    pub room_avatar: Option<i64>,
    pub room_topic: Option<i64>,
    pub space_child: Option<i64>,
    pub beacon: Option<i64>,
    pub beacon_info: Option<i64>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum RoomMembership {
    Joined,
    Invited,
    Left,
    Knocked,
    Banned,
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct RoomListFilter {
    pub membership: Option<RoomMembership>,
    pub category: Option<RoomCategory>,
    pub favourite: Option<bool>,
    pub unread_only: bool,
    pub search: Option<String>,
}

impl RoomListFilter {
    #[must_use]
    pub fn with_membership(mut self, membership: RoomMembership) -> Self {
        self.membership = Some(membership);
        self
    }

    #[must_use]
    pub fn with_category(mut self, category: RoomCategory) -> Self {
        self.category = Some(category);
        self
    }

    #[must_use]
    pub fn with_favourite(mut self, favourite: bool) -> Self {
        self.favourite = Some(favourite);
        self
    }

    #[must_use]
    pub const fn with_unread_only(mut self, unread_only: bool) -> Self {
        self.unread_only = unread_only;
        self
    }

    #[must_use]
    pub fn with_search(mut self, search: impl Into<String>) -> Self {
        self.search = Some(search.into());
        self
    }

    #[must_use]
    pub fn matches(&self, room: &RoomSummary) -> bool {
        self.membership
            .is_none_or(|membership| room.membership == membership)
            && self.category.is_none_or(|category| match category {
                RoomCategory::People => room.direct && !room.space,
                RoomCategory::Rooms => !room.direct && !room.space,
                RoomCategory::Spaces => room.space,
            })
            && self
                .favourite
                .is_none_or(|favourite| room.favourite == favourite)
            && (!self.unread_only || room.unread_messages > 0 || room.unread_mentions > 0)
            && self.search.as_ref().is_none_or(|search| {
                let search = search.to_lowercase();
                room.name.to_lowercase().contains(&search)
                    || room.room_id.as_str().to_lowercase().contains(&search)
            })
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum RoomCategory {
    People,
    Rooms,
    Spaces,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum MemberFilter {
    Active,
    Joined,
    Invited,
    All,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum MemberMembership {
    Joined,
    Invited,
    Left,
    Knocked,
    Banned,
    Custom(String),
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct MemberSummary {
    pub user_id: OwnedUserId,
    pub name: String,
    pub display_name: Option<String>,
    pub avatar: Option<OwnedMxcUri>,
    pub membership: MemberMembership,
    pub own: bool,
    pub name_ambiguous: bool,
    pub ignored: bool,
    pub service: bool,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct OwnDevice {
    pub device_id: OwnedDeviceId,
    pub display_name: Option<String>,
    pub last_seen_ip: Option<String>,
    pub last_seen_timestamp_ms: Option<u64>,
    pub current: bool,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum TimelineItem {
    Message(Box<TimelineMessage>),
    DayDivider { timestamp_ms: u64 },
    ReadMarker,
    TimelineStart,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum TimelineDiff {
    Append { values: Vec<TimelineItem> },
    Clear,
    PushFront { value: TimelineItem },
    PushBack { value: TimelineItem },
    PopFront,
    PopBack,
    Insert { index: usize, value: TimelineItem },
    Set { index: usize, value: TimelineItem },
    Remove { index: usize },
    Truncate { length: usize },
    Reset { values: Vec<TimelineItem> },
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
#[error("timeline diff is incompatible with the current {length}-item snapshot")]
pub struct TimelineDiffError {
    pub length: usize,
}

impl TimelineDiff {
    /// Apply a diff only when its indices match the current snapshot.
    /// On error the snapshot is unchanged; request `TimelineCommand::Resync`
    /// and ignore further diffs until the corresponding `TimelineReset`.
    pub fn try_apply(self, items: &mut Vec<TimelineItem>) -> Result<(), TimelineDiffError> {
        let length = items.len();
        match self {
            Self::Append { values } => items.extend(values),
            Self::Clear => items.clear(),
            Self::PushFront { value } => items.insert(0, value),
            Self::PushBack { value } => items.push(value),
            Self::PopFront if length == 0 => return Err(TimelineDiffError { length }),
            Self::PopFront => {
                items.remove(0);
            }
            Self::PopBack if length == 0 => return Err(TimelineDiffError { length }),
            Self::PopBack => {
                items.pop();
            }
            Self::Insert { index, .. } if index > length => {
                return Err(TimelineDiffError { length });
            }
            Self::Insert { index, value } => items.insert(index, value),
            Self::Set { index, .. } if index >= length => return Err(TimelineDiffError { length }),
            Self::Set { index, value } => items[index] = value,
            Self::Remove { index } if index >= length => return Err(TimelineDiffError { length }),
            Self::Remove { index } => {
                items.remove(index);
            }
            Self::Truncate { length: target } if target > length => {
                return Err(TimelineDiffError { length });
            }
            Self::Truncate { length } => items.truncate(length),
            Self::Reset { values } => *items = values,
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::{TimelineDiff, TimelineItem};

    fn item(timestamp_ms: u64) -> TimelineItem {
        TimelineItem::DayDivider { timestamp_ms }
    }

    #[test]
    fn timeline_diff_try_apply_handles_every_variant() {
        let mut items = vec![item(1), item(2)];

        TimelineDiff::Append {
            values: vec![item(3)],
        }
        .try_apply(&mut items)
        .unwrap();
        assert_eq!(items, vec![item(1), item(2), item(3)]);

        TimelineDiff::Clear.try_apply(&mut items).unwrap();
        assert!(items.is_empty());

        TimelineDiff::PushFront { value: item(2) }
            .try_apply(&mut items)
            .unwrap();
        TimelineDiff::PushBack { value: item(3) }
            .try_apply(&mut items)
            .unwrap();
        assert_eq!(items, vec![item(2), item(3)]);

        TimelineDiff::PopFront.try_apply(&mut items).unwrap();
        TimelineDiff::PopBack.try_apply(&mut items).unwrap();
        assert!(items.is_empty());

        TimelineDiff::Reset {
            values: vec![item(1), item(3)],
        }
        .try_apply(&mut items)
        .unwrap();
        TimelineDiff::Insert {
            index: 1,
            value: item(2),
        }
        .try_apply(&mut items)
        .unwrap();
        assert_eq!(items, vec![item(1), item(2), item(3)]);

        TimelineDiff::Set {
            index: 1,
            value: item(4),
        }
        .try_apply(&mut items)
        .unwrap();
        assert_eq!(items, vec![item(1), item(4), item(3)]);

        TimelineDiff::Remove { index: 1 }
            .try_apply(&mut items)
            .unwrap();
        assert_eq!(items, vec![item(1), item(3)]);

        TimelineDiff::Truncate { length: 1 }
            .try_apply(&mut items)
            .unwrap();
        assert_eq!(items, vec![item(1)]);
    }

    #[test]
    fn invalid_timeline_diff_leaves_snapshot_unchanged() {
        let invalid = [
            TimelineDiff::Insert {
                index: 3,
                value: item(3),
            },
            TimelineDiff::Set {
                index: 2,
                value: item(3),
            },
            TimelineDiff::Remove { index: 2 },
            TimelineDiff::Truncate { length: 3 },
        ];
        for diff in invalid {
            let mut items = vec![item(1), item(2)];
            assert_eq!(diff.try_apply(&mut items).unwrap_err().length, 2);
            assert_eq!(items, vec![item(1), item(2)]);
        }
        for diff in [TimelineDiff::PopFront, TimelineDiff::PopBack] {
            let mut items = Vec::new();
            assert_eq!(diff.try_apply(&mut items).unwrap_err().length, 0);
            assert!(items.is_empty());
        }
    }
}

#[derive(Clone, Debug, Eq, Hash, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct TimelineItemId(String);

impl TimelineItemId {
    pub(crate) fn new(value: String) -> Self {
        Self(value)
    }

    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct TimelineMessage {
    pub item_id: TimelineItemId,
    pub event_id: Option<OwnedEventId>,
    pub transaction_id: Option<OwnedTransactionId>,
    pub sender_id: OwnedUserId,
    pub sender_name: String,
    pub body: String,
    pub formatted_body: Option<String>,
    pub mentions: Option<MessageMentions>,
    pub thread_root: Option<OwnedEventId>,
    pub thread_summary: Option<ThreadSummary>,
    pub timestamp_ms: u64,
    pub own: bool,
    pub send_state: SendState,
    pub edited: bool,
    pub unable_to_decrypt: bool,
    pub media: Option<MediaDescriptor>,
    pub reply_to: Option<ReplyReference>,
    pub reactions: Vec<Reaction>,
    pub read_by: Vec<OwnedUserId>,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct ThreadSummary {
    pub reply_count: u32,
    pub latest_event_id: Option<OwnedEventId>,
    pub latest_event_timestamp_ms: Option<u64>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum SendState {
    Sent,
    Queued,
    Sending,
    Failed { retriable: bool },
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct ReplyReference {
    pub event_id: OwnedEventId,
    pub sender_id: Option<OwnedUserId>,
    pub sender_name: Option<String>,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct Reaction {
    pub key: String,
    pub count: usize,
    pub own: bool,
    pub senders: Vec<OwnedUserId>,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct MediaDescriptor {
    pub id: MediaId,
    pub kind: MediaKind,
    pub filename: String,
    pub caption: Option<String>,
    pub mimetype: Option<String>,
    pub size_bytes: Option<u64>,
    pub width: Option<u64>,
    pub height: Option<u64>,
}

#[derive(Clone, Debug, Eq, Hash, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct MediaId(String);

impl MediaId {
    pub(crate) fn new(value: String) -> Self {
        Self(value)
    }

    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl std::fmt::Display for MediaId {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.0.fmt(formatter)
    }
}

#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum MediaSize {
    Thumbnail,
    Full,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum MediaKind {
    Image,
    Video,
    Audio,
    File,
    Sticker,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct TypingState {
    pub room_id: OwnedRoomId,
    pub users: Vec<OwnedUserId>,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum HistoryState {
    Idle,
    Loading,
    StartReached,
    Failed(String),
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct EncryptionState {
    pub device_id: OwnedDeviceId,
    pub device_verified: bool,
    pub recovery: RecoveryState,
    pub key_backup: KeyBackupState,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum KeyBackupState {
    Unknown,
    Creating,
    Enabling,
    Resuming,
    Downloading,
    Enabled,
    Disabling,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum RecoveryState {
    Unknown,
    Disabled,
    Incomplete,
    Enabled,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum VerificationAction {
    Confirm,
    Reject,
    Cancel,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum VerificationTarget {
    OwnIdentity,
    User(OwnedUserId),
    Device {
        user_id: OwnedUserId,
        device_id: OwnedDeviceId,
    },
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum VerificationState {
    Waiting,
    Comparison {
        emojis: Vec<(String, String)>,
        decimals: (u16, u16, u16),
    },
    Confirmed,
    Done,
    Cancelled(String),
    Failed(VerificationFailure),
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum VerificationFailure {
    RequestAcceptance(String),
    SasStartup(String),
    SasAcceptance(String),
    RequestStreamEnded,
    SasStreamEnded,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct CommandFailure {
    pub id: CommandId,
    pub command: CommandKind,
    pub kind: CommandErrorKind,
    pub message: String,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum CommandErrorKind {
    Unauthenticated,
    RoomUnknown,
    RoomNotOpen,
    TimelineNotOpen,
    RoomBusy,
    QueueFull,
    InteractiveAuthRequired,
    EmptyBody,
    MediaUnknown,
    MediaTooLarge,
    MediaUnavailable,
    VerificationInactive,
    VerificationUnsupported,
    NoCrossSigningIdentity,
    RecoveryRejected,
    EventReceiverClosed,
    Network,
    Server,
    Store,
    Timeline,
    Encryption,
    Other,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct EngineFailure {
    pub kind: EngineErrorKind,
    pub message: String,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum EngineErrorKind {
    EventReceiverClosed,
    Watcher,
    Other,
}