macltok

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

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

/// every command answers exactly once through `ClientHandle::send` or `execute`.
/// the event stream only ever carries state
#[derive(Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum Command {
    Account(AccountCommand),
    Room(RoomCommand),
    Timeline(TimelineCommand),
    EventContext(EventContextCommand),
    Mentions(crate::MentionsCommand),
    Media(MediaCommand),
    Encryption(EncryptionCommand),
    Notification(NotificationCommand),
    Lifecycle(LifecycleCommand),
    Pack(PackCommand),
    HistoryRepair(crate::HistoryRepairCommand),
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum EventContextCommand {
    Fetch {
        room_id: OwnedRoomId,
        event_id: OwnedEventId,
        before_limit: u16,
        after_limit: u16,
    },
    Before {
        room_id: OwnedRoomId,
        limit: u16,
        token: String,
    },
    After {
        room_id: OwnedRoomId,
        limit: u16,
        token: String,
    },
}

#[derive(Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum AccountCommand {
    Logout,
    SetAccountData {
        event_type: GlobalAccountDataEventType,
        content: Raw<AnyGlobalAccountDataEventContent>,
    },
    SetDisplayName(Option<String>),
    SetAvatar(Option<OwnedMxcUri>),
    /// uploads the image and points the profile at it, same byte cap as any upload
    UploadAvatar {
        mimetype: String,
        bytes: Vec<u8>,
    },
    /// unencrypted, answers with `CommandOutput::Mxc`. same byte cap as any upload
    UploadMedia {
        mimetype: String,
        bytes: Vec<u8>,
    },
    IgnoreUser(OwnedUserId),
    UnignoreUser(OwnedUserId),
    /// writes msc3230 orders so these spaces sort in exactly this sequence, touching as few as it can
    ReorderSpaces(Vec<OwnedRoomId>),
    RenameDevice {
        device_id: OwnedDeviceId,
        display_name: String,
    },
    DeleteDevices {
        device_ids: Vec<OwnedDeviceId>,
        auth: Option<crate::InteractiveAuth>,
    },
}

#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum RoomCommand {
    /// the snapshot turns up as `Event::TimelineReset`. opening an open room sends a fresh one
    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,
    },
    /// muting drops them below what sending a message takes, unmuting puts a muted user back
    /// at users_default and leaves anyone else alone
    MuteUser {
        room_id: OwnedRoomId,
        user_id: OwnedUserId,
        muted: bool,
    },
    /// pinning appends, so the newest pin is last like everywhere else
    SetPinned {
        room_id: OwnedRoomId,
        event_id: OwnedEventId,
        pinned: bool,
    },
    /// adding m.favourite drops m.lowpriority, the way Element does
    SetFavourite {
        room_id: OwnedRoomId,
        favourite: bool,
    },
    /// your name in one room. None goes back to your global name
    SetOwnDisplayName {
        room_id: OwnedRoomId,
        name: Option<String>,
    },
    /// your avatar in one room. None goes back to your global avatar
    SetOwnAvatar {
        room_id: OwnedRoomId,
        avatar: Option<OwnedMxcUri>,
    },
    Create(CreateRoomOptions),
    /// hands back the existing dm if there is one
    CreateDirect(OwnedUserId),
    CancelSend {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
    },
    RetrySend {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
    },
    SetTyping {
        room_id: OwnedRoomId,
        typing: bool,
    },
    /// the key work a send into an encrypted room would otherwise start with, done now.
    /// nothing in a plain room, and a second ask joins the first
    PrepareToSend(OwnedRoomId),
    SetAccountData {
        room_id: OwnedRoomId,
        event_type: RoomAccountDataEventType,
        content: Raw<AnyRoomAccountDataEventContent>,
    },
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
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>,
}

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

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

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

    #[must_use]
    pub fn with_invite(mut self, invite: impl IntoIterator<Item = OwnedUserId>) -> Self {
        self.invite = invite.into_iter().collect();
        self
    }

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

    #[must_use]
    pub const fn with_visibility(mut self, visibility: RoomVisibility) -> Self {
        self.visibility = visibility;
        self
    }

    #[must_use]
    pub const fn with_preset(mut self, preset: RoomPreset) -> Self {
        self.preset = Some(preset);
        self
    }
}

#[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,
    },
    /// the room's pinned events as a timeline of their own, kept current as pins change.
    /// it can't send or paginate, the pins are all it holds
    OpenPinned(OwnedRoomId),
    ClosePinned(OwnedRoomId),
    /// 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,
        target: EventRef,
        content: MessageEditContent,
    },
    /// redacting your own unsent message just cancels it
    Redact {
        timeline_id: TimelineId,
        target: EventRef,
        reason: Option<String>,
    },
    ToggleReaction {
        timeline_id: TimelineId,
        target: EventRef,
        key: String,
        /// a custom emote's shortcode, sent along so clients without the pack can label it
        shortcode: Option<String>,
    },
    /// works on a closed room too, it just can't refuse to move the marker backwards
    MarkRead {
        timeline_id: TimelineId,
        event_id: OwnedEventId,
    },
}

impl TimelineCommand {
    #[must_use]
    pub const fn room_id(&self) -> &OwnedRoomId {
        match self {
            Self::OpenThread { room_id, .. }
            | Self::CloseThread { room_id, .. }
            | Self::OpenPinned(room_id)
            | Self::ClosePinned(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, .. }
            | Self::MarkRead { timeline_id, .. } => timeline_id.room_id(),
        }
    }

    #[must_use]
    pub const fn timeline_id(&self) -> Option<&TimelineId> {
        match self {
            Self::OpenThread { .. }
            | Self::CloseThread { .. }
            | Self::OpenPinned(_)
            | Self::ClosePinned(_) => 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, .. }
            | Self::MarkRead { timeline_id, .. } => Some(timeline_id),
        }
    }
}

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

impl TimelineId {
    #[must_use]
    pub const fn room_id(&self) -> &OwnedRoomId {
        match self {
            Self::Room(room_id) | Self::Thread { room_id, .. } | Self::Pinned(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(_) | Self::Pinned(_) => 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 {
    /// succeeds once the send queue has it. progress and failure arrive as events
    Upload(AttachmentUpload),
}

/// msc2545 pack editing. edits read the server's copy and keep keys macltok doesn't model
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum PackCommand {
    /// body defaults to the shortcode
    SendSticker {
        room_id: OwnedRoomId,
        pack_id: String,
        shortcode: String,
    },
    /// fails if the state key already holds a pack
    CreateRoomPack {
        room_id: OwnedRoomId,
        state_key: String,
        display_name: String,
    },
    /// empties the content, which is all deleting a pack can mean
    Delete(ImagePackSource),
    SetMeta {
        pack: ImagePackSource,
        display_name: Patch<String>,
        avatar: Patch<OwnedMxcUri>,
        usage: Patch<Vec<PackUsage>>,
    },
    /// adds or replaces by shortcode. a replaced image keeps its info unless the url changed
    PutImage {
        pack: ImagePackSource,
        shortcode: String,
        mxc: OwnedMxcUri,
        body: Option<String>,
        usage: Option<Vec<PackUsage>>,
        info: Option<PackImageInfo>,
    },
    /// fails if `to` is taken
    RenameImage {
        pack: ImagePackSource,
        from: String,
        to: String,
    },
    RemoveImage {
        pack: ImagePackSource,
        shortcode: String,
    },
    SetEnabledEverywhere {
        room_id: OwnedRoomId,
        state_key: String,
        enabled: bool,
    },
    /// answers with `CommandOutput::Mxc`, the same uri when it already lives on your homeserver
    Rehost(OwnedMxcUri),
    /// the rest answer with `CommandOutput::Cloned`. clashes get `-2`, `-3` and so on
    CloneImage {
        from_pack: String,
        shortcode: String,
        to: ImagePackSource,
        usage: Option<Vec<PackUsage>>,
    },
    CloneSticker {
        room_id: OwnedRoomId,
        event_id: OwnedEventId,
        to: ImagePackSource,
        shortcode: String,
        usage: Option<Vec<PackUsage>>,
    },
    /// makes the room pack if its state key is free, else merges. images that can't be
    /// fetched are skipped and listed, the rest are written
    ClonePack {
        from_pack: String,
        to: ImagePackSource,
        display_name: Option<String>,
        usage: Option<Vec<PackUsage>>,
    },
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum Patch<T> {
    #[default]
    Keep,
    Clear,
    Set(T),
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct PackImageInfo {
    pub mimetype: Option<String>,
    pub size_bytes: Option<u64>,
    pub width: Option<u64>,
    pub height: Option<u64>,
}

impl PackImageInfo {
    #[must_use]
    pub fn new(
        mimetype: Option<String>,
        size_bytes: Option<u64>,
        width: Option<u64>,
        height: Option<u64>,
    ) -> Self {
        Self {
            mimetype,
            size_bytes,
            width,
            height,
        }
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct AttachmentUpload {
    pub timeline_id: TimelineId,
    pub filename: String,
    pub mimetype: String,
    pub bytes: Vec<u8>,
    pub caption: Option<RichText>,
    pub mentions: MessageMentions,
    pub reply_to: Option<OwnedEventId>,
    pub notify_replied_to: bool,
    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,
            mentions: MessageMentions::default(),
            reply_to: None,
            notify_replied_to: true,
            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))]
#[non_exhaustive]
pub struct UploadThumbnail {
    pub bytes: Vec<u8>,
    pub mimetype: String,
    pub width: u32,
    pub height: u32,
}

impl UploadThumbnail {
    #[must_use]
    pub fn new(bytes: Vec<u8>, mimetype: impl Into<String>, width: u32, height: u32) -> Self {
        Self {
            bytes,
            mimetype: mimetype.into(),
            width,
            height,
        }
    }
}

#[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,
}

#[derive(Clone, Debug, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum CommandOutput {
    Done,
    Room(OwnedRoomId),
    Mxc(OwnedMxcUri),
    /// the shortcodes the copies ended up under, and the ones that couldn't be fetched
    Cloned {
        shortcodes: Vec<String>,
        skipped: Vec<String>,
    },
    EventContext(EventContext),
    EventContextPage(EventContextPage),
    MentionsPage(crate::MentionsPage),
    MentionContext(crate::SavedMentionContext),
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct EventContext {
    pub events_before: Vec<TimelineItem>,
    pub event: Option<TimelineItem>,
    pub events_after: Vec<TimelineItem>,
    pub start_token: Option<String>,
    pub end_token: Option<String>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum EventContextDirection {
    Before,
    After,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct EventContextPage {
    pub direction: EventContextDirection,
    pub events: Vec<TimelineItem>,
    pub next_token: Option<String>,
    pub end_reached: bool,
}

#[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,
    },
    /// m.notice, for bots. clients render it muted and never answer it automatically
    Notice {
        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 notice(content: RichText, mentions: MessageMentions) -> Self {
        Self::Notice { 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, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum Event {
    ConnectionChanged(ConnectionState),
    Authenticated {
        user_id: OwnedUserId,
    },
    /// the tokens rotated. with a `SessionStore` the record is already saved by now,
    /// without one persist a fresh `ClientHandle::session_record()` atomically
    SessionTokensChanged,
    /// the rotated tokens didn't reach the `SessionStore`, so the saved record may not
    /// restore. the engine tries again on the next rotation
    SessionSaveFailed {
        message: String,
    },
    /// the server stopped honouring our token and the engine stops. a soft logout
    /// names the device to log in again as, keeping the store. otherwise the record
    /// and the store are both dead
    SessionAccessRejected {
        soft_logout: Option<OwnedDeviceId>,
    },
    NotificationSettingsChanged,
    VerificationTargetChanged(VerificationTarget),
    RoomsChanged,
    MentionsChanged(crate::MentionsUpdate),
    /// an image pack came, went or changed somewhere. ask `image_packs` again
    ImagePacksChanged,
    /// replaces whatever you had for this timeline. every diff after it applies to it
    TimelineReset {
        timeline_id: TimelineId,
        items: Vector<TimelineItem>,
    },
    TimelineChanged {
        timeline_id: TimelineId,
        diffs: Vec<TimelineDiff>,
    },
    HistoryChanged {
        timeline_id: TimelineId,
        state: HistoryState,
    },
    RecentHistoryChanged {
        room_id: OwnedRoomId,
        state: RecentHistoryState,
    },
    HistoryRepairChanged(crate::HistoryRepairReport),
    #[doc(hidden)]
    PublicationBarrier {
        #[cfg_attr(feature = "serde", serde(skip))]
        acknowledgement: Option<crate::PublicationAck>,
    },
    /// the timeline was closed, or its room was left, and nothing more comes for it
    /// until another `TimelineReset`
    TimelineClosed {
        timeline_id: TimelineId,
    },
    /// a room that stops being watched says so with an empty `users`
    TypingChanged(TypingState),
    MediaUploadProgress {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
        uploaded_bytes: u64,
        total_bytes: u64,
        complete: bool,
    },
    /// not the end of it. `will_retry` means the send queue has another go by itself,
    /// otherwise it waits for `retry_send` or `cancel_send`
    MediaUploadFailed {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
        kind: crate::ErrorKind,
        will_retry: bool,
    },
    /// an upload that turned up in a progress or failure event gets exactly one of
    /// these while the engine runs, and nothing about it after. stopping ends
    /// nothing, `Stopped` covers whatever is still going and the sdk resumes it next run
    MediaUploadFinished {
        room_id: OwnedRoomId,
        transaction_id: OwnedTransactionId,
        outcome: UploadOutcome,
    },
    EncryptionChanged(EncryptionState),
    VerificationChanged(VerificationState),
    /// logout went through and the engine stops. delete the record and the store
    LoggedOut,
    Failed(EngineFailure),
    /// always the last event. keep the saved record unless `LoggedOut` or a
    /// hard `SessionAccessRejected` came first. commands still in flight answer `Interrupted`
    Stopped,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum UploadOutcome {
    Sent {
        event_id: OwnedEventId,
    },
    Cancelled,
    /// its room was forgotten, and the queue with it
    RoomForgotten,
    /// the sdk's update channel overflowed while it ended, so whether it was sent is unknown
    Missed,
}

/// why `Engine::run` came back, when nothing went wrong
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum Termination {
    ShutDown,
    /// every `ClientHandle` was dropped, so nobody could have asked for anything else
    HandlesDropped,
    LoggedOut,
    /// the server rejected our token for good
    AccessRevoked,
    /// the server wants this device to log in again, and its e2ee keys live in the store
    SoftLoggedOut {
        device_id: OwnedDeviceId,
    },
}

impl Termination {
    #[must_use]
    pub const fn retain(&self) -> Retain {
        match self {
            Self::ShutDown | Self::HandlesDropped => Retain::RecordAndStore,
            Self::SoftLoggedOut { .. } => Retain::Store,
            Self::LoggedOut | Self::AccessRevoked => Retain::Nothing,
        }
    }
}

/// what's still worth keeping of the saved record and the store
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum Retain {
    RecordAndStore,
    /// keep the store and a record naming the device to log in again as
    Store,
    Nothing,
}

#[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,
    /// unread events the push rules said to notify about, which is neither of the above
    pub unread_notifications: u64,
    pub encrypted: bool,
    pub space: bool,
    pub direct: bool,
    pub favourite: bool,
    pub low_priority: bool,
    pub avatar: Option<MediaId>,
    pub latest_event_timestamp_ms: Option<u64>,
    pub latest_event: Option<LatestEvent>,
    pub notification_mode: Option<RoomNotificationMode>,
    pub notification_mode_custom: bool,
    pub topic: Option<String>,
    pub canonical_alias: Option<OwnedRoomAliasId>,
    pub joined_members: u64,
    pub invited_members: u64,
    /// who a nameless room gets named after
    pub heroes: Vec<RoomHero>,
    /// set once the room has been upgraded, this is where everyone went
    pub successor: Option<OwnedRoomId>,
    pub inviter: Option<OwnedUserId>,
    /// joined spaces that list this room as a child
    pub parent_spaces: Vec<OwnedRoomId>,
    /// for a space, the children it lists, joined or not
    pub children: Vec<OwnedRoomId>,
    /// a space's msc3230 order. ordered spaces sort first by (order, room id), the rest by room id
    pub space_order: Option<String>,
    /// you can send im.ponies.room_emotes here, so you can make and edit its packs
    pub can_edit_packs: bool,
    /// m.room.pinned_events in order, the newest pin last
    pub pinned_events: Vec<OwnedEventId>,
    pub can_pin: bool,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct RoomHero {
    pub user_id: OwnedUserId,
    pub display_name: Option<String>,
    pub avatar: Option<MediaId>,
}

/// enough for a room list preview line. `kind` and `body` are only set for messages,
/// and an edit shows its new text
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct LatestEvent {
    pub sender: Option<OwnedUserId>,
    pub kind: Option<MessageKind>,
    pub body: Option<String>,
    pub timestamp_ms: Option<u64>,
    pub send_state: SendState,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct Profile {
    pub user_id: OwnedUserId,
    pub display_name: Option<String>,
    pub avatar: Option<MediaId>,
}

/// one room in a space's hierarchy, as the server describes it, which may be a room you're not in
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct SpaceChild {
    pub room_id: OwnedRoomId,
    pub name: String,
    pub topic: Option<String>,
    pub avatar: Option<MediaId>,
    pub canonical_alias: Option<OwnedRoomAliasId>,
    pub joined_members: u64,
    pub space: bool,
    pub children_count: u64,
    pub membership: Option<RoomMembership>,
    pub via: Vec<OwnedServerName>,
    pub suggested: bool,
    pub world_readable: Option<bool>,
    pub guest_can_join: 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))]
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<MediaId>,
    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<MediaId>,
    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))]
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)>,
    /// in rooms from version 12 the creators outrank everyone and aren't listed in `users`
    pub creators: Vec<OwnedUserId>,
}

#[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.matcher().matches(room)
    }

    /// lowercases the search once, for filtering a whole list
    #[must_use]
    pub fn matcher(&self) -> RoomMatcher<'_> {
        RoomMatcher {
            filter: self,
            search: self.search.as_deref().map(str::to_lowercase),
        }
    }
}

#[derive(Debug)]
pub struct RoomMatcher<'a> {
    filter: &'a RoomListFilter,
    search: Option<String>,
}

impl RoomMatcher<'_> {
    #[must_use]
    pub fn matches(&self, room: &RoomSummary) -> bool {
        let filter = self.filter;
        filter
            .membership
            .is_none_or(|membership| room.membership == membership)
            && filter.category.is_none_or(|category| match category {
                RoomCategory::People => room.direct && !room.space,
                RoomCategory::Rooms => !room.direct && !room.space,
                RoomCategory::Spaces => room.space,
            })
            && filter
                .favourite
                .is_none_or(|favourite| room.favourite == favourite)
            && (!filter.unread_only || room.unread_messages > 0 || room.unread_mentions > 0)
            && self.search.as_ref().is_none_or(|search| {
                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))]
#[non_exhaustive]
pub enum RoomCategory {
    People,
    Rooms,
    Spaces,
}

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

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
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<MediaId>,
    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 {
    Event(Box<TimelineEvent>),
    HistoryGap(crate::HistoryGap),
    DayDivider { timestamp_ms: u64 },
    ReadMarker,
    TimelineStart,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
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 Vector<TimelineItem>) -> Result<(), TimelineDiffError> {
        let length = items.len();
        if self.length_after(length).is_none() {
            return Err(TimelineDiffError { length });
        }
        self.apply(items);
        Ok(())
    }

    /// a whole `TimelineChanged` or none of it. whether a diff fits depends only on the
    /// length before it, so the batch is checked against lengths alone before anything
    /// moves. the error carries the length the snapshot would have had at the misfit
    pub fn try_apply_all(
        diffs: Vec<Self>,
        items: &mut Vector<TimelineItem>,
    ) -> Result<(), TimelineDiffError> {
        diffs.iter().try_fold(items.len(), |length, diff| {
            diff.length_after(length)
                .ok_or(TimelineDiffError { length })
        })?;
        for diff in diffs {
            diff.apply(items);
        }
        Ok(())
    }

    fn length_after(&self, length: usize) -> Option<usize> {
        match self {
            Self::Append { values } => Some(length + values.len()),
            Self::Clear => Some(0),
            Self::PushFront { .. } | Self::PushBack { .. } => Some(length + 1),
            Self::PopFront | Self::PopBack => length.checked_sub(1),
            Self::Insert { index, .. } => (*index <= length).then_some(length + 1),
            Self::Set { index, .. } => (*index < length).then_some(length),
            Self::Remove { index } => (*index < length).then(|| length - 1),
            Self::Truncate { length: target } => (*target <= length).then_some(*target),
            Self::Reset { values } => Some(values.len()),
        }
    }

    fn apply(self, items: &mut Vector<TimelineItem>) {
        match self {
            Self::Append { values } => items.extend(values),
            Self::Clear => items.clear(),
            Self::PushFront { value } => items.push_front(value),
            Self::PushBack { value } => items.push_back(value),
            Self::PopFront => {
                items.pop_front();
            }
            Self::PopBack => {
                items.pop_back();
            }
            Self::Insert { index, value } => items.insert(index, value),
            Self::Set { index, value } => {
                items.set(index, value);
            }
            Self::Remove { index } => {
                items.remove(index);
            }
            Self::Truncate { length } => items.truncate(length),
            Self::Reset { values } => *items = values.into_iter().collect(),
        }
    }
}

#[cfg(test)]
mod tests {
    use imbl::{Vector, vector};

    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 = vector![item(1), item(2)];

        TimelineDiff::Append {
            values: vec![item(3)],
        }
        .try_apply(&mut items)
        .unwrap();
        assert_eq!(items, vector![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, vector![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, vector![item(1), item(2), item(3)]);

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

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

        TimelineDiff::Truncate { length: 1 }
            .try_apply(&mut items)
            .unwrap();
        assert_eq!(items, vector![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 = vector![item(1), item(2)];
            assert_eq!(diff.try_apply(&mut items).unwrap_err().length, 2);
            assert_eq!(items, vector![item(1), item(2)]);
        }
        for diff in [TimelineDiff::PopFront, TimelineDiff::PopBack] {
            let mut items = Vector::new();
            assert_eq!(diff.try_apply(&mut items).unwrap_err().length, 0);
            assert!(items.is_empty());
        }
    }

    #[test]
    fn a_batch_that_goes_wrong_halfway_changes_nothing() {
        let mut items = vector![item(1), item(2)];
        let batch = vec![
            TimelineDiff::PushBack { value: item(3) },
            TimelineDiff::PushBack { value: item(4) },
            TimelineDiff::Remove { index: 0 },
            TimelineDiff::Set {
                index: 3,
                value: item(5),
            },
        ];
        assert_eq!(
            TimelineDiff::try_apply_all(batch, &mut items)
                .unwrap_err()
                .length,
            3
        );
        assert_eq!(items, vector![item(1), item(2)]);

        let batch = vec![
            TimelineDiff::PushBack { value: item(3) },
            TimelineDiff::Remove { index: 0 },
            TimelineDiff::Set {
                index: 1,
                value: item(4),
            },
        ];
        TimelineDiff::try_apply_all(batch, &mut items).unwrap();
        assert_eq!(items, vector![item(2), item(4)]);
    }
}

#[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 TimelineEvent {
    pub item_id: TimelineItemId,
    pub event_id: Option<OwnedEventId>,
    pub transaction_id: Option<OwnedTransactionId>,
    pub sender: Sender,
    pub timestamp_ms: u64,
    pub own: bool,
    pub send_state: SendState,
    pub content: TimelineContent,
    pub reply_to: Option<ReplyReference>,
    pub thread_root: Option<OwnedEventId>,
    pub thread_summary: Option<ThreadSummary>,
    pub reactions: Vec<Reaction>,
    pub read_by: Vec<OwnedUserId>,
    pub editable: bool,
}

impl TimelineEvent {
    /// what to hand edit, redact and react. works before the server has echoed it back
    #[must_use]
    pub fn target(&self) -> Option<EventRef> {
        self.event_id
            .clone()
            .map(EventRef::Remote)
            .or_else(|| self.transaction_id.clone().map(EventRef::Local))
    }
}

#[derive(Clone, Debug, Eq, Hash, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub enum EventRef {
    Remote(OwnedEventId),
    /// a local echo, by the transaction id it was queued under
    Local(OwnedTransactionId),
}

impl From<OwnedEventId> for EventRef {
    fn from(event_id: OwnedEventId) -> Self {
        Self::Remote(event_id)
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct Sender {
    pub user_id: OwnedUserId,
    pub display_name: Option<String>,
    pub avatar: Option<MediaId>,
    /// someone else in the room goes by the same name, so show the user id too
    pub name_ambiguous: bool,
}

impl Sender {
    #[must_use]
    pub fn name(&self) -> &str {
        self.display_name
            .as_deref()
            .unwrap_or_else(|| self.user_id.as_str())
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum TimelineContent {
    Message(Message),
    Sticker {
        body: String,
        media: MediaDescriptor,
    },
    Poll {
        question: String,
    },
    Redacted,
    UnableToDecrypt(UtdCause),
    Membership {
        user_id: OwnedUserId,
        display_name: Option<String>,
        change: MembershipChange,
    },
    Profile {
        user_id: OwnedUserId,
        display_name: Option<Change<Option<String>>>,
        avatar: Option<Change<Option<MediaId>>>,
    },
    /// `None` means it was cleared, or the event was redacted
    RoomName(Option<String>),
    RoomTopic(Option<String>),
    RoomAvatar(Option<MediaId>),
    EncryptionEnabled,
    RoomCreated,
    RoomUpgraded {
        successor: OwnedRoomId,
    },
    OtherState {
        event_type: String,
        state_key: String,
    },
    Other {
        event_type: String,
    },
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct Message {
    pub kind: MessageKind,
    pub body: String,
    /// only for `MessageKind::Location`
    pub geo_uri: Option<String>,
    pub formatted_body: Option<String>,
    pub mentions: Option<MessageMentions>,
    pub edited: bool,
    pub media: Option<MediaDescriptor>,
    /// previews the sender attached (msc4095), so showing them asks no one about the url.
    /// one for a url the body doesn't contain is dropped
    pub link_previews: Vec<LinkPreview>,
}

/// a link card, from the sender's own message or from `ClientHandle::url_preview`. page
/// text passes through whoever made it unfiltered, so it arrives trimmed to a sane length
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct LinkPreview {
    /// the url as it appears in the message, or as it was asked about
    pub url: String,
    /// where the page says it lives, when that's somewhere else
    pub canonical_url: Option<String>,
    pub title: Option<String>,
    pub description: Option<String>,
    pub site_name: Option<String>,
    pub image: Option<LinkPreviewImage>,
}

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

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum MessageKind {
    Text,
    Emote,
    Notice,
    ServerNotice,
    Image,
    Video,
    Audio,
    File,
    Location,
    VerificationRequest,
    Other(String),
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum MembershipChange {
    Joined,
    Left,
    Banned,
    Unbanned,
    Kicked,
    KickedAndBanned,
    Invited,
    InvitationAccepted,
    InvitationRejected,
    InvitationRevoked,
    Knocked,
    KnockAccepted,
    KnockRetracted,
    KnockDenied,
    /// nothing a person would call a change, or something the sdk couldn't make sense of
    Other,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct Change<T> {
    pub old: T,
    pub new: T,
}

/// why a message couldn't be read, worth telling the user since some of these they can fix
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum UtdCause {
    Unknown,
    SentBeforeWeJoined,
    VerificationViolation,
    UnsignedDevice,
    UnknownDevice,
    HistoricalMessageAndBackupIsDisabled,
    WithheldForUnverifiedOrInsecureDevice,
    WithheldBySender,
    HistoricalMessageAndDeviceIsUnverified,
}

#[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))]
pub enum SendState {
    Sent,
    Sending,
    /// `will_retry` means macltok has it in hand. otherwise it's wedged until you
    /// `retry_send` or `cancel_send`, so that's when to show a retry button
    Failed {
        will_retry: bool,
    },
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct ReplyReference {
    pub event_id: OwnedEventId,
    pub details: ReplyDetails,
}

/// the replied-to event. macltok asks for it when it isn't loaded, `Pending` then turns into one of the others
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum ReplyDetails {
    Pending,
    Ready {
        sender: Sender,
        content: Box<TimelineContent>,
        timestamp_ms: u64,
    },
    Unavailable,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct Reaction {
    pub key: String,
    /// a custom emote's shortcode, from whichever sender gave one
    pub shortcode: Option<String>,
    /// the custom emote itself, when the key is an image
    pub image: Option<MediaId>,
    pub count: usize,
    pub own: bool,
    pub senders: Vec<OwnedUserId>,
}

/// every custom emote and sticker pack the account can reach, from the user's own
/// pack, each joined room's packs, and the rooms the user enabled everywhere
#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct ImagePacks {
    /// the user's own pack, then the packs of rooms enabled everywhere
    pub global: Vec<ImagePack>,
    /// each joined room's own packs, rooms without any left out
    pub rooms: imbl::HashMap<OwnedRoomId, Vec<ImagePack>>,
}

impl ImagePacks {
    /// what a picker in this room offers. the user's pack, the room's own, then the
    /// rest of the enabled ones, each pack once
    #[must_use]
    pub fn for_room(&self, room_id: Option<&RoomId>) -> Vec<&ImagePack> {
        let is_user = |pack: &&ImagePack| pack.source == ImagePackSource::User;
        let own = room_id.and_then(|room_id| self.rooms.get(room_id));
        let mut packs: Vec<&ImagePack> = self.global.iter().filter(is_user).collect();
        packs.extend(own.into_iter().flatten());
        for pack in self.global.iter().filter(|pack| !is_user(pack)) {
            if !packs.iter().any(|seen| seen.id == pack.id) {
                packs.push(pack);
            }
        }
        packs
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct ImagePack {
    /// `user`, or `room:<room id>:<state key>`, the same across calls
    pub id: String,
    pub display_name: Option<String>,
    pub avatar: Option<MediaId>,
    pub attribution: Option<String>,
    pub source: ImagePackSource,
    pub images: Vec<PackImage>,
    /// your own pack, or a room pack whose state you're allowed to send
    pub editable: bool,
    /// listed in im.ponies.emote_rooms. always true for your own pack
    pub enabled_everywhere: bool,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum ImagePackSource {
    User,
    Room {
        room_id: OwnedRoomId,
        state_key: String,
    },
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct PackImage {
    pub shortcode: String,
    pub media_id: MediaId,
    /// what `toggle_reaction` takes to react with this image
    pub reaction_key: String,
    pub body: Option<String>,
    pub mimetype: Option<String>,
    pub width: Option<u64>,
    pub height: Option<u64>,
    /// the image's own, else its pack's, else both
    pub usage: Vec<PackUsage>,
}

#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum PackUsage {
    Emoticon,
    Sticker,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct MediaDescriptor {
    pub id: MediaId,
    pub kind: MediaKind,
    /// only for unencrypted media, an encrypted file's mxc is ciphertext without the keys
    pub mxc: Option<OwnedMxcUri>,
    pub filename: String,
    pub caption: Option<String>,
    pub mimetype: Option<String>,
    pub size_bytes: Option<u64>,
    pub width: Option<u64>,
    pub height: Option<u64>,
    pub duration_ms: Option<u64>,
    pub blurhash: Option<String>,
    /// the uploader sent a thumbnail, so `MediaSize::Thumbnail` won't need the server to resize
    pub has_thumbnail: bool,
}

#[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)
    }

    /// plain media carries no keys, so it needs no registering and never expires
    pub(crate) fn plain<U: AsRef<str> + ?Sized>(uri: &U) -> Self {
        Self(uri.as_ref().to_owned())
    }

    pub(crate) fn as_plain(&self) -> Option<&MxcUri> {
        self.0.starts_with("mxc://").then(|| self.0.as_str().into())
    }

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

/// media ids are opaque but they do have to survive a trip through a browser. a made up one just fails `MediaUnknown`
impl std::str::FromStr for MediaId {
    type Err = std::convert::Infallible;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        Ok(Self(value.to_owned()))
    }
}

impl From<String> for MediaId {
    fn from(value: String) -> Self {
        Self(value)
    }
}

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))]
#[non_exhaustive]
pub enum MediaSize {
    Full,
    /// a hint. an uploader's own thumbnail wins over the server resizing anything
    Thumbnail {
        width: u32,
        height: u32,
    },
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct Media {
    pub bytes: Arc<[u8]>,
    pub mimetype: String,
}

/// where media lives, for a host that fetches and decrypts it itself
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum MediaLocation {
    File(MediaFile),
    /// a resize of plaintext, so never encrypted. plenty of servers refuse some, and `media`
    /// then fetches `fallback` instead, so should you
    ServerThumbnail {
        url: String,
        fallback: MediaFile,
    },
    /// still in the send queue with no url yet. `media` has the bytes
    Local,
}

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct MediaFile {
    pub url: String,
    pub mimetype: Option<String>,
    pub declared_size: Option<u64>,
    pub encryption: Option<AttachmentEncryption>,
}

/// AES-256-CTR, the only attachment cipher matrix has
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
pub struct AttachmentEncryption {
    /// the JWK `k`, unpadded url-safe base64
    pub key: String,
    /// unpadded base64, the initial counter block
    pub iv: String,
    /// unpadded base64 SHA-256 of the whole ciphertext, so a partial read goes unchecked
    pub sha256: String,
}

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

#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[non_exhaustive]
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))]
pub enum RecentHistoryState {
    /// nothing running and nothing to show, which is also what closing the room leaves
    Idle,
    Loading,
    Loaded,
    Cancelled,
    /// stays until a retry or the room is reopened
    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))]
#[non_exhaustive]
pub enum VerificationAction {
    /// take up a request another device sent, which arrives as `VerificationState::Incoming`
    Accept,
    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,
    /// someone else asked. `Accept` to go ahead, `Cancel` to turn them down
    Incoming {
        user_id: OwnedUserId,
        device_id: Option<OwnedDeviceId>,
    },
    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))]
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 EngineFailure {
    pub kind: EngineErrorKind,
    pub message: String,
}

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