ruma_client_api/membership/
invite_user.rs

1//! `POST /_matrix/client/*/rooms/{roomId}/invite`
2//!
3//! Invite a user to a room.
4
5pub mod v3 {
6    //! `/v3/` ([spec (MXID)][spec-mxid], [spec (3PID)][spec-3pid])
7    //!
8    //! This endpoint has two forms: one to invite a user
9    //! [by their Matrix identifier][spec-mxid], and one to invite a user
10    //! [by their third party identifier][spec-3pid].
11    //!
12    //! [spec-mxid]: https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3roomsroomidinvite
13    //! [spec-3pid]: https://spec.matrix.org/latest/client-server-api/#thirdparty_post_matrixclientv3roomsroomidinvite
14
15    use ruma_common::{
16        api::{request, response, Metadata},
17        metadata, OwnedRoomId, OwnedUserId,
18    };
19    use serde::{Deserialize, Serialize};
20
21    use crate::membership::Invite3pid;
22
23    const METADATA: Metadata = metadata! {
24        method: POST,
25        rate_limited: true,
26        authentication: AccessToken,
27        history: {
28            1.0 => "/_matrix/client/r0/rooms/:room_id/invite",
29            1.1 => "/_matrix/client/v3/rooms/:room_id/invite",
30        }
31    };
32
33    /// Request type for the `invite_user` endpoint.
34    #[request(error = crate::Error)]
35    pub struct Request {
36        /// The room where the user should be invited.
37        #[ruma_api(path)]
38        pub room_id: OwnedRoomId,
39
40        /// The user to invite.
41        #[serde(flatten)]
42        pub recipient: InvitationRecipient,
43
44        /// Optional reason for inviting the user.
45        #[serde(skip_serializing_if = "Option::is_none")]
46        pub reason: Option<String>,
47    }
48
49    /// Response type for the `invite_user` endpoint.
50    #[response(error = crate::Error)]
51    #[derive(Default)]
52    pub struct Response {}
53
54    impl Request {
55        /// Creates a new `Request` with the given room ID and invitation recipient.
56        pub fn new(room_id: OwnedRoomId, recipient: InvitationRecipient) -> Self {
57            Self { room_id, recipient, reason: None }
58        }
59    }
60
61    impl Response {
62        /// Creates an empty `Response`.
63        pub fn new() -> Self {
64            Self {}
65        }
66    }
67
68    /// Distinguishes between invititations by Matrix or third party identifiers.
69    #[derive(Clone, Debug, Deserialize, Serialize)]
70    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
71    #[serde(untagged)]
72    pub enum InvitationRecipient {
73        /// Used to invite user by their Matrix identifier.
74        UserId {
75            /// Matrix identifier of user.
76            user_id: OwnedUserId,
77        },
78
79        /// Used to invite user by a third party identifier.
80        ThirdPartyId(Invite3pid),
81    }
82
83    #[cfg(test)]
84    mod tests {
85        use assert_matches2::assert_matches;
86        use ruma_common::thirdparty::Medium;
87        use serde_json::{from_value as from_json_value, json};
88
89        use super::InvitationRecipient;
90
91        #[test]
92        fn deserialize_invite_by_user_id() {
93            let incoming =
94                from_json_value::<InvitationRecipient>(json!({ "user_id": "@carl:example.org" }))
95                    .unwrap();
96
97            assert_matches!(incoming, InvitationRecipient::UserId { user_id });
98            assert_eq!(user_id, "@carl:example.org");
99        }
100
101        #[test]
102        fn deserialize_invite_by_3pid() {
103            let incoming = from_json_value::<InvitationRecipient>(json!({
104                "id_server": "example.org",
105                "id_access_token": "abcdefghijklmnop",
106                "medium": "email",
107                "address": "carl@example.org"
108            }))
109            .unwrap();
110
111            assert_matches!(incoming, InvitationRecipient::ThirdPartyId(third_party_id));
112
113            assert_eq!(third_party_id.id_server, "example.org");
114            assert_eq!(third_party_id.id_access_token, "abcdefghijklmnop");
115            assert_eq!(third_party_id.medium, Medium::Email);
116            assert_eq!(third_party_id.address, "carl@example.org");
117        }
118    }
119}
ruma_client_api/membership/invite_user.rs

ruma_client_api/membership/
invite_user.rs
