zulip_api/message/register/request.rs
1use serde::{Deserialize, Serialize};
2
3use crate::filter::NarrowTuple;
4use crate::{field_access, ClientCapabilities, EventType, IncludeSubscribers};
5
6/// Represents the request to the `Register` Zulip API.
7#[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
8pub struct Request {
9 #[serde(skip_serializing_if = "Option::is_none")]
10 apply_markdown: Option<bool>,
11 #[serde(skip_serializing_if = "Option::is_none")]
12 client_gravatar: Option<bool>,
13 #[serde(skip_serializing_if = "Option::is_none")]
14 include_subscribers: Option<IncludeSubscribers>,
15 #[serde(skip_serializing_if = "Option::is_none")]
16 slim_presence: Option<bool>,
17 #[serde(skip_serializing_if = "Option::is_none")]
18 presence_history_limit_days: Option<u64>,
19 #[serde(skip_serializing_if = "Option::is_none")]
20 event_types: Option<Vec<EventType>>,
21 #[serde(skip_serializing_if = "Option::is_none")]
22 all_public_streams: Option<bool>,
23 #[serde(skip_serializing_if = "Option::is_none")]
24 client_capabilities: Option<ClientCapabilities>,
25 #[serde(skip_serializing_if = "Option::is_none")]
26 fetch_event_types: Option<Vec<EventType>>,
27 #[serde(skip_serializing_if = "Option::is_none")]
28 narrow: Option<Vec<NarrowTuple>>,
29}
30
31impl Request {
32 /// Creates a new [Request].
33 pub const fn new() -> Self {
34 Self {
35 apply_markdown: None,
36 client_gravatar: None,
37 include_subscribers: None,
38 slim_presence: None,
39 presence_history_limit_days: None,
40 event_types: None,
41 all_public_streams: None,
42 client_capabilities: None,
43 fetch_event_types: None,
44 narrow: None,
45 }
46 }
47}
48
49impl Default for Request {
50 fn default() -> Self {
51 Self::new()
52 }
53}
54
55field_access! {
56 Request {
57 /// Set to `true` if you would like the content to be rendered in HTML
58 /// format (otherwise the API will return the raw text that the user entered)
59 apply_markdown: option { bool },
60 /// Whether the client supports computing gravatars URLs. If
61 /// enabled, `avatar_url` will be included in the response only
62 /// if there is a Zulip avatar, and will be `null` for users who
63 /// are using gravatar as their avatar. This option
64 /// significantly reduces the compressed size of user data,
65 /// since gravatar URLs are long, random strings and thus do not
66 /// compress well. The `client_gravatar` field is set to `true` if
67 /// clients can compute their own gravatars.
68 ///
69 /// The default value is `true` for authenticated requests and
70 /// `false` for [unauthenticated requests](https://zulip.com/help/public-access-option).
71 ///
72 /// Passing `true` in an unauthenticated request is an error.
73 ///
74 /// **Changes**: Before Zulip 6.0 (feature level 149), this
75 /// parameter was silently ignored and processed as though it
76 /// were `false` in unauthenticated requests.
77 client_gravatar: option { bool },
78 /// Whether each returned channel object should include a `subscribers`
79 /// field containing a list of the user IDs of its subscribers.
80 include_subscribers: option { IncludeSubscribers },
81 /// If `true`, the `presences` object returned in the response will be keyed
82 /// by user ID and the entry for each user's presence data will be in the
83 /// modern format.
84 ///
85 /// **Changes**: New in Zulip 3.0 (no feature level; API unstable).
86 slim_presence: option { bool },
87 /// Limits how far back in time to fetch user presence data. If not specified,
88 /// defaults to 14 days. A value of N means that the oldest presence data
89 /// fetched will be from at most N days ago.
90 ///
91 /// **Changes**: New in Zulip 10.0 (feature level 288).
92 presence_history_limit_days: option { u64 },
93 /// Whether you would like to request message events from all public
94 /// channels. Useful for workflow bots that you'd like to see all new messages
95 /// sent to public channels. (You can also subscribe the user to private channels).
96 all_public_streams: option { bool },
97 /// Dictionary containing details on features the client supports that are
98 /// relevant to the format of responses sent by the server.
99 client_capabilities: option { ClientCapabilities },
100 }
101}
102
103field_access! {
104 Request {
105 /// A JSON-encoded array indicating which types of events you're interested
106 /// in. Values that you might find useful include:
107 event_types: option_cow_deref { [EventType], Vec<EventType> },
108 /// Same as the `event_types` parameter except that the values in
109 /// `fetch_event_types` are used to fetch initial data. If
110 /// `fetch_event_types` is not provided, `event_types` is used and if
111 /// `event_types` is not provided, this parameter defaults to `null`.
112 ///
113 /// Event types not supported by the server are ignored, in order to simplify
114 /// the implementation of client apps that support multiple server versions.
115 fetch_event_types: option_cow_deref { [EventType], Vec<EventType> },
116 /// A JSON-encoded array of arrays of length 2 indicating the
117 /// [narrow filter(s)](https://zulip.com/api/construct-narrow) for which you'd
118 /// like to receive events for.
119 ///
120 /// For example, to receive events for direct messages (including
121 /// group direct messages) received by the user, one can use
122 /// `"narrow": [["is", "dm"]]`.
123 ///
124 /// Unlike the API for [fetching messages](https://zulip.com/api/get-messages),
125 /// this narrow parameter is simply a filter on messages that the
126 /// user receives through their channel subscriptions (or because
127 /// they are a recipient of a direct message).
128 ///
129 /// This means that a client that requests a `narrow` filter of
130 /// `[["channel", "Denmark"]]` will receive events for new messages
131 /// sent to that channel while the user is subscribed to that
132 /// channel. The client will not receive any message events at all
133 /// if the user is not subscribed to `"Denmark"`.
134 ///
135 /// Newly created bot users are not usually subscribed to any
136 /// channels, so bots using this API need to be
137 /// [subscribed](https://zulip.com/api/subscribe) to any channels whose messages
138 /// you'd like them to process using this endpoint.
139 ///
140 /// See the `all_public_streams` parameter for how to process all
141 /// public channel messages in an organization.
142 ///
143 /// **Changes**: See [changes section](https://zulip.com/api/construct-narrow#changes)
144 /// of search/narrow filter documentation.
145 narrow: option_cow_deref { [NarrowTuple], Vec<NarrowTuple> },
146 }
147}