zulip_api/message/subscription.rs
1use serde::{Deserialize, Serialize};
2use serde_repr::{Deserialize_repr, Serialize_repr};
3
4use crate::message::channel_permission::*;
5use crate::{field_access, impl_default, impl_display, TopicsPolicy};
6
7/// Represents the properties of a channel the user is subscribed to (as well as that user's personal per-channel settings).
8///
9/// **Changes**: Removed `email_address` field from the dictionary in Zulip 8.0 (feature level 226). Removed `role` field from the dictionary in Zulip 6.0 (feature level 133).
10///
11/// Modified from `openapi-generator-cli` output:
12///
13/// ```shell,no_build,no_run
14/// $ openapi-generator-cli generate -g rust -i ./zerver/openapi/zulip.yaml -o zulip-openapi --skip-validate-spec
15/// ```
16///
17/// ```text
18/// /*
19/// * Zulip REST API
20/// *
21/// * Powerful open source group chat
22/// *
23/// * The version of the OpenAPI document: 1.0.0
24/// *
25/// * Generated by: https://openapi-generator.tech
26/// */
27/// ```
28///
29/// See [zerver/openapi/zulip.yaml](https://github.com/zulip/zulip/blob/main/zerver/openapi/zulip.yaml) for the original OpenAPI configuration.
30///
31/// Configuration slightly modified to work with the Rust generator of [`openapi-generator-cli`](https://openapi-generator.tech).
32#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
33pub struct Subscription {
34 #[serde(skip_serializing_if = "Option::is_none")]
35 stream_id: Option<u64>,
36 #[serde(skip_serializing_if = "Option::is_none")]
37 name: Option<String>,
38 #[serde(skip_serializing_if = "Option::is_none")]
39 description: Option<String>,
40 #[serde(skip_serializing_if = "Option::is_none")]
41 rendered_description: Option<String>,
42 #[serde(skip_serializing_if = "Option::is_none")]
43 date_created: Option<u64>,
44 #[serde(skip_serializing_if = "Option::is_none")]
45 creator_id: Option<u64>,
46 #[serde(skip_serializing_if = "Option::is_none")]
47 invite_only: Option<bool>,
48 #[serde(skip_serializing_if = "Option::is_none")]
49 subscribers: Option<Vec<u64>>,
50 #[serde(skip_serializing_if = "Option::is_none")]
51 partial_subscribers: Option<Vec<u64>>,
52 #[serde(skip_serializing_if = "Option::is_none")]
53 desktop_notifications: Option<bool>,
54 #[serde(skip_serializing_if = "Option::is_none")]
55 email_notifications: Option<bool>,
56 #[serde(skip_serializing_if = "Option::is_none")]
57 wildcard_mentions_notify: Option<bool>,
58 #[serde(skip_serializing_if = "Option::is_none")]
59 push_notifications: Option<bool>,
60 #[serde(skip_serializing_if = "Option::is_none")]
61 audible_notifications: Option<bool>,
62 #[serde(skip_serializing_if = "Option::is_none")]
63 pin_to_top: Option<bool>,
64 #[serde(skip_serializing_if = "Option::is_none")]
65 is_muted: Option<bool>,
66 #[serde(skip_serializing_if = "Option::is_none")]
67 in_home_view: Option<bool>,
68 #[serde(skip_serializing_if = "Option::is_none")]
69 is_announcement_only: Option<bool>,
70 #[serde(skip_serializing_if = "Option::is_none")]
71 is_web_public: Option<bool>,
72 #[serde(skip_serializing_if = "Option::is_none")]
73 color: Option<String>,
74 #[serde(skip_serializing_if = "Option::is_none")]
75 stream_post_policy: Option<StreamPostPolicy>,
76 #[serde(skip_serializing_if = "Option::is_none")]
77 message_retention_days: Option<i32>,
78 #[serde(skip_serializing_if = "Option::is_none")]
79 history_public_to_subscribers: Option<bool>,
80 #[serde(skip_serializing_if = "Option::is_none")]
81 first_message_id: Option<u64>,
82 #[serde(skip_serializing_if = "Option::is_none")]
83 folder_id: Option<u64>,
84 #[serde(skip_serializing_if = "Option::is_none")]
85 topics_policy: Option<TopicsPolicy>,
86 #[serde(skip_serializing_if = "Option::is_none")]
87 is_recently_active: Option<bool>,
88 #[serde(skip_serializing_if = "Option::is_none")]
89 stream_weekly_traffic: Option<u64>,
90 #[serde(skip_serializing_if = "Option::is_none")]
91 can_add_subscribers_group: Option<CanAddSubscribersGroup>,
92 #[serde(skip_serializing_if = "Option::is_none")]
93 can_remove_subscribers_group: Option<CanRemoveSubscribersGroup>,
94 #[serde(skip_serializing_if = "Option::is_none")]
95 can_administer_channel_group: Option<CanAdministerChannelGroup>,
96 #[serde(skip_serializing_if = "Option::is_none")]
97 can_delete_any_message_group: Option<CanDeleteAnyMessageGroup>,
98 #[serde(skip_serializing_if = "Option::is_none")]
99 can_delete_own_message_group: Option<CanDeleteOwnMessageGroup>,
100 #[serde(skip_serializing_if = "Option::is_none")]
101 can_move_messages_out_of_channel_group: Option<CanMoveMessagesOutOfChannelGroup>,
102 #[serde(skip_serializing_if = "Option::is_none")]
103 can_move_messages_within_channel_group: Option<CanMoveMessagesWithinChannelGroup>,
104 #[serde(skip_serializing_if = "Option::is_none")]
105 can_send_message_group: Option<CanSendMessageGroup>,
106 #[serde(skip_serializing_if = "Option::is_none")]
107 can_subscribe_group: Option<CanSubscribeGroup>,
108 #[serde(skip_serializing_if = "Option::is_none")]
109 can_resolve_topics_group: Option<CanResolveTopicsGroup>,
110 #[serde(skip_serializing_if = "Option::is_none")]
111 is_archived: Option<bool>,
112 #[serde(skip_serializing_if = "Option::is_none")]
113 subscriber_count: Option<f64>,
114}
115
116impl Subscription {
117 /// Creates a new [Subscription].
118 pub const fn new() -> Self {
119 Self {
120 stream_id: None,
121 name: None,
122 description: None,
123 rendered_description: None,
124 date_created: None,
125 creator_id: None,
126 invite_only: None,
127 subscribers: None,
128 partial_subscribers: None,
129 desktop_notifications: None,
130 email_notifications: None,
131 wildcard_mentions_notify: None,
132 push_notifications: None,
133 audible_notifications: None,
134 pin_to_top: None,
135 is_muted: None,
136 in_home_view: None,
137 is_announcement_only: None,
138 is_web_public: None,
139 color: None,
140 stream_post_policy: None,
141 message_retention_days: None,
142 history_public_to_subscribers: None,
143 first_message_id: None,
144 folder_id: None,
145 topics_policy: None,
146 is_recently_active: None,
147 stream_weekly_traffic: None,
148 can_add_subscribers_group: None,
149 can_remove_subscribers_group: None,
150 can_administer_channel_group: None,
151 can_delete_any_message_group: None,
152 can_delete_own_message_group: None,
153 can_move_messages_out_of_channel_group: None,
154 can_move_messages_within_channel_group: None,
155 can_send_message_group: None,
156 can_subscribe_group: None,
157 can_resolve_topics_group: None,
158 is_archived: None,
159 subscriber_count: None,
160 }
161 }
162}
163
164field_access! {
165 Subscription {
166 /// The unique ID of a channel.
167 stream_id: option { u64 },
168 /// The UNIX timestamp for when the channel was created, in UTC seconds.
169 ///
170 /// **Changes**: New in Zulip 4.0 (feature level 30).
171 date_created: option { u64 },
172 /// The ID of the user who created this channel.
173 ///
174 /// A `null` value means the channel has no recorded creator,
175 /// which is often because the channel is very old,
176 /// was created during realm creation or because it was created via a data import tool or [management command](https://zulip.readthedocs.io/en/latest/production/management-commands.html).
177 ///
178 /// **Changes**: New in Zulip 9.0 (feature level 254).
179 creator_id: option { u64 },
180 /// Specifies whether the channel is private or not.
181 ///
182 /// Only people who have been invited can access a private channel.
183 invite_only: option { bool },
184 /// A boolean specifying whether desktop notifications are enabled for the given channel.
185 ///
186 /// A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_desktop_notifications`, for this channel.
187 desktop_notifications: option { bool },
188 /// A boolean specifying whether email notifications are enabled for the given channel.
189 ///
190 /// A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_email_notifications`, for this channel.
191 email_notifications: option { bool },
192 /// A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this channel.
193 ///
194 /// A `null` value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this channel.
195 wildcard_mentions_notify: option { bool },
196 /// A boolean specifying whether push notifications are enabled for the given channel.
197 ///
198 /// A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_push_notifications`, for this channel.
199 push_notifications: option { bool },
200 /// A boolean specifying whether audible notifications are enabled for the given channel.
201 ///
202 /// A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_audible_notifications`, for this channel.
203 audible_notifications: option { bool },
204 /// A boolean specifying whether the given channel has been pinned to the top.
205 pin_to_top: option { bool },
206 /// Whether the user has muted the channel. Muted channels do not count towards your total unread count and do not show up in the `Combined feed` view (previously known as `All messages`).
207 ///
208 /// **Changes**: Prior to Zulip 2.1.0, this feature was represented by the more confusingly named `in_home_view` (with the opposite value, `in_home_view=!is_muted`).
209 is_muted: option { bool },
210 /// Legacy property for if the given channel is muted, with inverted meaning.
211 ///
212 /// **Changes**: Deprecated in Zulip 2.1.0. Clients should use `is_muted` where available.
213 in_home_view: option { bool },
214 /// Whether only organization administrators can post to the channel.
215 ///
216 /// **Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients should use `stream_post_policy` instead.
217 is_announcement_only: option { bool },
218 /// Whether the channel has been configured to allow unauthenticated access to its message history from the web.
219 is_web_public: option { bool },
220 /// A deprecated representation of a superset of the users who have permission to post messages to the channel available for backwards-compatibility.
221 stream_post_policy: option { StreamPostPolicy },
222 /// Number of days that messages sent to this channel will be stored before being automatically deleted by the [message retention policy](https://zulip.com/help/message-retention-policy).
223 ///
224 /// There are two special values:
225 ///
226 /// - `null`, the default, means the channel will inherit the organization level setting.
227 /// - `-1` encodes retaining messages in this channel forever.
228 ///
229 /// **Changes**: New in Zulip 3.0 (feature level 17).
230 message_retention_days: option { i32 },
231 /// Whether the history of the channel is public to its subscribers.
232 ///
233 /// Currently always true for public channels (i.e. `\"invite_only\": false` implies `\"history_public_to_subscribers\": true`),
234 /// but clients should not make that assumption, as we may change that behavior in the future.
235 history_public_to_subscribers: option { bool },
236 /// The ID of the first message in the channel.
237 ///
238 /// Intended to help clients determine whether they need to display UI like the \"show all topics\" widget that would suggest the channel has older history that can be accessed.
239 ///
240 /// Is `null` for channels with no message history.
241 first_message_id: option { u64 },
242 /// The ID of the folder to which the channel belongs.
243 ///
244 /// Is `null` if channel does not belong to any folder.
245 ///
246 /// **Changes**: New in Zulip 11.0 (feature level 389).
247 folder_id: option { u64 },
248 topics_policy: option { TopicsPolicy },
249 /// Whether the channel has recent message activity.
250 ///
251 /// Clients should use this to implement [hiding inactive channels](https://zulip.com/help/manage-inactive-channels).
252 ///
253 /// **Changes**: New in Zulip 10.0 (feature level 323). Previously, clients implemented the demote_inactive_streams from local message history, resulting in a choppy loading experience.
254 is_recently_active: option { bool },
255 /// The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.
256 ///
257 /// If `null`, the channel was recently created and there is insufficient data to estimate the average traffic.
258 stream_weekly_traffic: option { u64 },
259 /// A boolean indicating whether the channel is [archived](https://zulip.com/help/archive-a-channel).
260 ///
261 /// **Changes**: New in Zulip 10.0 (feature level 315). Previously, subscriptions only included active channels.
262 /// Note that some endpoints will never return archived channels unless the client declares explicit support for them via the `archived_channels` client capability.
263 is_archived: option { bool },
264 /// The total number of non-deactivated users (including bots) who are subscribed to the channel.
265 ///
266 /// Clients are responsible for updating this value using `peer_add` and `peer_remove` events.
267 ///
268 /// The server's internals cannot guarantee this value is correctly synced with `peer_add` and `peer_remove` events for the channel.
269 /// As a result, if a (rare) race occurs between a change in the channel's subscribers and fetching this value,
270 /// it is possible for a client that is correctly following the events protocol to end up with a permanently off-by-one error in the channel's subscriber count.
271 ///
272 /// Clients are recommended to fetch full subscriber data for a channel in contexts where it is important to avoid this risk.
273 /// The official web application, for example, uses this field primarily while waiting to fetch a given channel's full subscriber list from the server.
274 ///
275 /// **Changes**: New in Zulip 11.0 (feature level 394).
276 subscriber_count: option { f64 },
277 }
278}
279
280field_access! {
281 Subscription {
282 /// The name of a channel.
283 name: option_cow_deref { str, String },
284 /// The [description](https://zulip.com/help/change-the-channel-description) of the channel in [Zulip-flavored Markdown](https://zulip.com/help/format-your-message-using-markdown) format,
285 /// intended to be used to prepopulate UI for editing a channel's description.
286 ///
287 /// See [Markdown message formatting](https://zulip.com/api/message-formatting) for details on Zulip's HTML format.
288 ///
289 /// See also `rendered_description`.
290 description: option_cow_deref { str, String },
291 /// The [description](https://zulip.com/help/change-the-channel-description) of the channel rendered as HTML,
292 /// intended to be used when displaying the channel description in a UI.
293 ///
294 /// One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX,
295 /// and other syntax work correctly.
296 ///
297 /// And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.
298 ///
299 /// See also `description`.
300 rendered_description: option_cow_deref { str, String },
301 /// A list of user IDs of users who are also subscribed to a given channel. Included only if `include_subscribers` is `true`.
302 subscribers: option_cow_deref { [u64], Vec<u64> },
303 /// If [`include_subscribers=\"partial\"`](https://zulip.com/api/get-subscriptions#parameter-include_subscribers) was requested, the server may,
304 /// at its discretion, send a `partial_subscribers` list rather than a `subscribers` list for channels with a large number of subscribers.
305 ///
306 /// The `partial_subscribers` list contains an arbitrary subset of the channel's subscribers that is guaranteed to include all bot user
307 /// subscribers as well as all users who have been active in the last 14 days, but otherwise can be chosen arbitrarily by the server.
308 ///
309 /// **Changes**: New in Zulip 11.0 (feature level 412).
310 partial_subscribers: option_cow_deref { [u64], Vec<u64> },
311 /// The user's personal color for the channel.
312 color: option_cow_deref { str, String },
313 }
314}
315
316field_access! {
317 Subscription {
318 can_add_subscribers_group: option_ref { CanAddSubscribersGroup },
319 can_remove_subscribers_group: option_ref { CanRemoveSubscribersGroup },
320 can_administer_channel_group: option_ref { CanAdministerChannelGroup },
321 can_delete_any_message_group: option_ref { CanDeleteAnyMessageGroup },
322 can_delete_own_message_group: option_ref { CanDeleteOwnMessageGroup },
323 can_move_messages_out_of_channel_group: option_ref { CanMoveMessagesOutOfChannelGroup },
324 can_move_messages_within_channel_group: option_ref { CanMoveMessagesWithinChannelGroup },
325 can_send_message_group: option_ref { CanSendMessageGroup },
326 can_subscribe_group: option_ref { CanSubscribeGroup },
327 can_resolve_topics_group: option_ref { CanResolveTopicsGroup },
328 }
329}
330
331impl_default!(Subscription);
332impl_display!(Subscription);
333
334/// Represents A deprecated representation of a superset of the users who
335/// have permission to post messages to the channel available
336/// for backwards-compatibility.
337///
338/// Clients should use `can_send_message_group` instead.
339#[repr(u8)]
340#[derive(Clone, Copy, Debug, Eq, PartialEq, Deserialize_repr, Serialize_repr)]
341pub enum StreamPostPolicy {
342 /// Any user can post.
343 AnyUser = 1,
344 /// Only administrators can post.
345 OnlyAdministrator = 2,
346 /// Only full members can post.
347 OnlyFullMember = 3,
348 /// Only moderators can post.
349 OnlyModerator = 4,
350}
351
352impl StreamPostPolicy {
353 /// Creates a new [StreamPostPolicy].
354 pub const fn new() -> Self {
355 Self::AnyUser
356 }
357}
358
359impl_default!(StreamPostPolicy);
360impl_display!(StreamPostPolicy);