ruma-appservice-api 0.15.0

Types for the endpoints in the Matrix application service API.
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

//! `GET /_matrix/app/*/thirdparty/protocol/{protocol}`
//!
//! Fetches metadata about the various third party networks that an application service supports.

pub mod v1 {
    //! `/v1/` ([spec])
    //!
    //! [spec]: https://spec.matrix.org/v1.18/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol

    use std::collections::BTreeMap;

    use ruma_common::{
        api::{auth_scheme::AccessToken, request, response},
        metadata,
        thirdparty::{Protocol, ProtocolInstance, ProtocolInstanceInit},
    };
    use serde::{Deserialize, Serialize};

    metadata! {
        method: GET,
        rate_limited: false,
        authentication: AccessToken,
        path: "/_matrix/app/v1/thirdparty/protocol/{protocol}",
    }

    /// Request type for the `get_protocol` endpoint.
    #[request]
    pub struct Request {
        /// The name of the protocol.
        #[ruma_api(path)]
        pub protocol: String,
    }

    /// Response type for the `get_protocol` endpoint.
    #[response]
    pub struct Response {
        /// Metadata about the protocol.
        #[ruma_api(body)]
        pub protocol: AppserviceProtocol,
    }

    impl Request {
        /// Creates a new `Request` with the given protocol name.
        pub fn new(protocol: String) -> Self {
            Self { protocol }
        }
    }

    impl Response {
        /// Creates a new `Response` with the given protocol.
        pub fn new(protocol: AppserviceProtocol) -> Self {
            Self { protocol }
        }
    }

    /// Metadata about a third party protocol, as returned by an appservice to a homeserver.
    ///
    /// To create an instance of this type, first create a [`ProtocolInit`] and convert it via
    /// `AppserviceProtocol::from` / `.into()`.
    ///
    /// [`ProtocolInit`]: ruma_common::thirdparty::ProtocolInit
    pub type AppserviceProtocol = Protocol<AppserviceProtocolInstance>;

    /// Metadata about an instance of a third party protocol, as returned by an appservice to a
    /// homeserver.
    ///
    /// To create an instance of this type, first create a [`ProtocolInstanceInit`] and convert it
    /// via `AppserviceProtocolInstance::from` / `.into()`.
    #[derive(Clone, Debug, Deserialize, Serialize)]
    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
    pub struct AppserviceProtocolInstance {
        /// A human-readable description for the protocol, such as the name.
        pub desc: String,

        /// An optional content URI representing the protocol.
        #[serde(skip_serializing_if = "Option::is_none")]
        pub icon: Option<String>,

        /// Preset values for `fields` the client may use to search by.
        pub fields: BTreeMap<String, String>,

        /// A unique identifier across all instances.
        pub network_id: String,
    }

    impl From<ProtocolInstanceInit> for AppserviceProtocolInstance {
        fn from(init: ProtocolInstanceInit) -> Self {
            let ProtocolInstanceInit { desc, fields, network_id } = init;
            Self { desc, icon: None, fields, network_id }
        }
    }

    impl From<AppserviceProtocolInstance> for ProtocolInstance {
        fn from(value: AppserviceProtocolInstance) -> Self {
            let AppserviceProtocolInstance { desc, icon, fields, network_id } = value;
            let mut instance =
                ProtocolInstance::from(ProtocolInstanceInit { desc, fields, network_id });
            instance.icon = icon;
            instance
        }
    }
}