botkit-matrix 0.2.0

Matrix implementation for botkit
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

use std::path::PathBuf;

use matrix_sdk::ruma::{OwnedDeviceId, OwnedUserId};

/// Matrix bot configuration
///
/// Configure the homeserver, authentication, command prefix, and other options.
///
/// # Example
/// ```ignore
/// let config = MatrixConfig::new("https://matrix.org")
///     .password_auth("@bot:matrix.org", "password")
///     .command_prefix("!")
///     .auto_join_rooms(true);
/// ```
pub struct MatrixConfig {
    /// Homeserver URL (e.g., "https://matrix.org")
    pub(crate) homeserver_url: String,

    /// Authentication method
    pub(crate) auth: MatrixAuth,

    /// Command prefix for parsing commands from messages (default: "!")
    pub(crate) command_prefix: String,

    /// Device display name for this bot session
    pub(crate) device_name: Option<String>,

    /// State store path for persistence (enables session restore and E2EE key storage)
    pub(crate) state_store_path: Option<PathBuf>,

    /// Whether to auto-join rooms when invited
    pub(crate) auto_join_rooms: bool,
}

/// Authentication options for Matrix
pub enum MatrixAuth {
    /// Username and password login
    Password {
        /// Matrix user ID (e.g., "@bot:matrix.org")
        user_id: String,
        /// Password
        password: String,
    },
    /// Access token (for pre-authenticated sessions)
    AccessToken {
        /// Matrix user ID
        user_id: OwnedUserId,
        /// Access token
        access_token: String,
        /// Device ID (required for E2EE)
        device_id: OwnedDeviceId,
    },
}

impl MatrixConfig {
    /// Create a new Matrix configuration with the given homeserver URL
    ///
    /// Authentication must be configured before building the bot.
    pub fn new(homeserver_url: impl Into<String>) -> Self {
        Self {
            homeserver_url: homeserver_url.into(),
            auth: MatrixAuth::Password {
                user_id: String::new(),
                password: String::new(),
            },
            command_prefix: "!".to_string(),
            device_name: None,
            state_store_path: None,
            auto_join_rooms: false,
        }
    }

    /// Set password authentication
    ///
    /// # Arguments
    /// * `user_id` - Matrix user ID (e.g., "@bot:matrix.org")
    /// * `password` - Password for the account
    pub fn password_auth(
        mut self,
        user_id: impl Into<String>,
        password: impl Into<String>,
    ) -> Self {
        self.auth = MatrixAuth::Password {
            user_id: user_id.into(),
            password: password.into(),
        };
        self
    }

    /// Set access token authentication
    ///
    /// Use this for pre-authenticated sessions. Requires the device ID for E2EE.
    pub fn access_token_auth(
        mut self,
        user_id: OwnedUserId,
        access_token: impl Into<String>,
        device_id: OwnedDeviceId,
    ) -> Self {
        self.auth = MatrixAuth::AccessToken {
            user_id,
            access_token: access_token.into(),
            device_id,
        };
        self
    }

    /// Set the command prefix (default: "!")
    ///
    /// Messages starting with this prefix will be parsed as commands.
    pub fn command_prefix(mut self, prefix: impl Into<String>) -> Self {
        self.command_prefix = prefix.into();
        self
    }

    /// Set the device display name
    ///
    /// This appears in the user's device list.
    pub fn device_name(mut self, name: impl Into<String>) -> Self {
        self.device_name = Some(name.into());
        self
    }

    /// Set the state store path for persistence
    ///
    /// Enables session persistence and E2EE key storage.
    /// Without this, E2EE keys are lost on restart.
    pub fn state_store_path(mut self, path: impl Into<PathBuf>) -> Self {
        self.state_store_path = Some(path.into());
        self
    }

    /// Enable or disable auto-joining rooms when invited
    pub fn auto_join_rooms(mut self, enabled: bool) -> Self {
        self.auto_join_rooms = enabled;
        self
    }
}