client-api: Add support for the threads list API

According to MSC3856

crates/ruma-client-api/CHANGELOG.md

@@ -10,6 +10,7 @@ Improvements:
 * Add `M_BAD_ALIAS` to `error::ErrorKind`
 * Remove the `unstable-msc3440` feature
   * The fields added to `RoomEventFilter` were removed by MSC3856
+* Add support for the threads list API (MSC3856 / Matrix 1.4)
 
 # 0.15.1
 

crates/ruma-client-api/src/lib.rs

@@ -41,6 +41,7 @@ pub mod state;
 pub mod sync;
 pub mod tag;
 pub mod thirdparty;
+pub mod threads;
 pub mod to_device;
 pub mod typing;
 pub mod uiaa;

crates/ruma-client-api/src/threads.rs

@@ -0,0 +1,3 @@
+//! Endpoints for querying threads in a room.
+
+pub mod get_threads;

crates/ruma-client-api/src/threads/get_threads.rs

@@ -0,0 +1,113 @@
+//! `GET /_matrix/client/*/rooms/{roomId}/threads`
+//!
+//! Retrieve a list of threads in a room, with optional filters.
+
+pub mod v1 {
+    //! `/v1/` ([spec])
+    //!
+    //! [spec]: https://spec.matrix.org/v1.4/client-server-api/#get_matrixclientv1roomsroomidthreads
+
+    use js_int::UInt;
+    use ruma_common::{
+        api::ruma_api,
+        events::AnyTimelineEvent,
+        serde::{Raw, StringEnum},
+        RoomId,
+    };
+
+    use crate::PrivOwnedStr;
+
+    ruma_api! {
+        metadata: {
+            description: "Retrieve a list of threads in a room, with optional filters.",
+            method: GET,
+            name: "get_thread_roots",
+            unstable_path: "/_matrix/client/unstable/org.matrix.msc3856/rooms/:room_id/threads",
+            stable_path: "/_matrix/client/v1/rooms/:room_id/threads",
+            rate_limited: true,
+            authentication: AccessToken,
+            added: 1.4,
+        }
+
+        request: {
+            /// The room ID where the thread roots are located.
+            #[ruma_api(path)]
+            pub room_id: &'a RoomId,
+
+            /// The pagination token to start returning results from.
+            ///
+            /// If `None`, results start at the most recent topological event visible to the user.
+            #[serde(skip_serializing_if = "Option::is_none")]
+            #[ruma_api(query)]
+            pub from: Option<&'a str>,
+
+            /// Which thread roots are of interest to the caller.
+            #[serde(skip_serializing_if = "ruma_common::serde::is_default")]
+            #[ruma_api(query)]
+            pub include: IncludeThreads,
+
+            /// The maximum number of results to return in a single `chunk`.
+            ///
+            /// Servers should apply a default value, and impose a maximum value to avoid resource
+            /// exhaustion.
+            #[serde(skip_serializing_if = "Option::is_none")]
+            #[ruma_api(query)]
+            pub limit: Option<UInt>,
+        }
+
+        response: {
+            /// The thread roots, ordered by the `latest_event` in each event's aggregation bundle.
+            ///
+            /// All events returned include bundled aggregations.
+            pub chunk: Vec<Raw<AnyTimelineEvent>>,
+
+            /// An opaque string to provide to `from` to keep paginating the responses.
+            ///
+            /// If this is `None`, there are no more results to fetch and the client should stop
+            /// paginating.
+            #[serde(skip_serializing_if = "Option::is_none")]
+            pub next_batch: Option<String>,
+        }
+
+        error: crate::Error
+    }
+
+    impl<'a> Request<'a> {
+        /// Creates a new `Request` with the given room ID.
+        pub fn new(room_id: &'a RoomId) -> Self {
+            Self { room_id, from: None, include: IncludeThreads::default(), limit: None }
+        }
+    }
+
+    impl Response {
+        /// Creates a new `Response` with the given chunk.
+        pub fn new(chunk: Vec<Raw<AnyTimelineEvent>>) -> Self {
+            Self { chunk, next_batch: None }
+        }
+    }
+
+    /// Which threads to include in the response.
+    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
+    #[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
+    #[ruma_enum(rename_all = "lowercase")]
+    #[non_exhaustive]
+    pub enum IncludeThreads {
+        /// `all`
+        ///
+        /// Include all thread roots found in the room.
+        ///
+        /// This is the default.
+        #[default]
+        All,
+
+        /// `participated`
+        ///
+        /// Only include thread roots for threads where [`current_user_participated`] is `true`.
+        ///
+        /// [`current_user_participated`]: https://spec.matrix.org/v1.4/client-server-api/#server-side-aggregation-of-mthread-relationships
+        Participated,
+
+        #[doc(hidden)]
+        _Custom(PrivOwnedStr),
+    }
+}