api: Add InitialSnapshot.userStatuses

Co-authored-by: Greg Price <[email protected]>
Co-authored-by: Chris Bobbe <[email protected]>

Author: 3 people

lib/api/model/initial_snapshot.dart

@@ -66,6 +66,16 @@ class InitialSnapshot {
 
   final List<ZulipStream> streams;
 
+  // In register-queue, the name of this field is the singular "user_status",
+  // even though it actually contains user status information for all the users
+  // that the self-user has access to. Therefore, we prefer to use the plural form.
+  //
+  // The API expresses each status as a change from the "zero status" (see
+  // [UserStatus.zero]), with entries omitted for users whose status is the
+  // zero status.
+  @JsonKey(name: 'user_status')
+  final Map<int, UserStatusChange> userStatuses;
+
   // Servers pre-5.0 don't have `user_settings`, and instead provide whatever
   // user settings they support at toplevel in the initial snapshot. Since we're
   // likely to desupport pre-5.0 servers before wide release, we prefer to
@@ -154,6 +164,7 @@ class InitialSnapshot {
     required this.subscriptions,
     required this.unreadMsgs,
     required this.streams,
+    required this.userStatuses,
     required this.userSettings,
     required this.userTopics,
     required this.realmWildcardMentionPolicy,

lib/api/model/initial_snapshot.g.dart

@@ -1,5 +1,6 @@
 import 'package:json_annotation/json_annotation.dart';
 
+import '../../basic.dart';
 import '../../model/algorithms.dart';
 import 'events.dart';
 import 'initial_snapshot.dart';
@@ -158,6 +159,119 @@ class RealmEmojiItem {
   Map<String, dynamic> toJson() => _$RealmEmojiItemToJson(this);
 }
 
+/// A user's status, with [text] and [emoji] parts.
+///
+/// If a part is null, that part is empty/unset.
+/// For a [UserStatus] with all parts empty, see [zero].
+class UserStatus {
+  /// The text part (e.g. 'Working remotely'), or null if unset.
+  ///
+  /// This won't be the empty string.
+  final String? text;
+
+  /// The emoji part, or null if unset.
+  final StatusEmoji? emoji;
+
+  const UserStatus({required this.text, required this.emoji}) : assert(text != '');
+
+  static const UserStatus zero = UserStatus(text: null, emoji: null);
+}
+
+/// A user's status emoji, as in [UserStatus.emoji].
+class StatusEmoji {
+  final String emojiName;
+  final String emojiCode;
+  final ReactionType reactionType;
+
+  const StatusEmoji({
+    required this.emojiName,
+    required this.emojiCode,
+    required this.reactionType,
+  }) : assert(emojiName != ''), assert(emojiCode != '');
+}
+
+/// A change to part or all of a user's status.
+///
+/// The absence of one of these means there is no change.
+class UserStatusChange {
+  // final Option<bool> away; // deprecated in server-6 (FL-148); ignore
+  final Option<String?> text;
+  final Option<StatusEmoji?> emoji;
+
+  const UserStatusChange({required this.text, required this.emoji});
+
+  factory UserStatusChange.fromJson(Map<String, dynamic> json) {
+    return UserStatusChange(
+      text: _textFromJson(json), emoji: _emojiFromJson(json));
+  }
+
+  static Option<String?> _textFromJson(Map<String, dynamic> json) {
+    return switch (json['status_text'] as String?) {
+      null => OptionNone(),
+      '' => OptionSome(null),
+      final apiValue => OptionSome(apiValue),
+    };
+  }
+
+  static Option<StatusEmoji?> _emojiFromJson(Map<String, dynamic> json) {
+    final reactionType = json['reaction_type'] as String?;
+    final emojiCode = json['emoji_code'] as String?;
+    final emojiName = json['emoji_name'] as String?;
+
+    if (reactionType == null || emojiCode == null || emojiName == null) {
+      return OptionNone();
+    } else if (reactionType == '' || emojiCode == '' || emojiName == '') {
+      // Sometimes `reaction_type` is 'unicode_emoji' when the emoji is cleared.
+      // This is an accident, to be handled by looking at `emoji_code` instead:
+      //   https://chat.zulip.org/#narrow/channel/378-api-design/topic/user.20status/near/2203132
+      return OptionSome(null);
+    } else {
+      return OptionSome(StatusEmoji(
+        reactionType: ReactionType.fromApiValue(reactionType),
+        emojiCode: emojiCode,
+        emojiName: emojiName));
+    }
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      ..._textToJson(text),
+      ..._emojiToJson(emoji),
+    };
+  }
+
+  Map<String, dynamic> _textToJson(Option<String?> text) {
+    return {
+      'status_text': switch (text) {
+        OptionNone<String?>() => null,
+        OptionSome<String?>(:var value) => value ?? '',
+      }
+    };
+  }
+
+  Map<String, dynamic> _emojiToJson(Option<StatusEmoji?> emoji) {
+    return switch (emoji) {
+      OptionNone<StatusEmoji?>() => {
+        'reaction_type': null,
+        'emoji_code': null,
+        'emoji_name': null,
+      },
+      OptionSome<StatusEmoji?>(:var value) =>
+        value == null
+          ? {'reaction_type': '', 'emoji_code': '', 'emoji_name': ''}
+          : {
+              'reaction_type': value.reactionType,
+              'emoji_code': value.emojiCode,
+              'emoji_name': value.emojiName,
+            },
+    };
+  }
+
+  UserStatus apply(UserStatus old) {
+    return UserStatus(text: text.or(old.text), emoji: emoji.or(old.emoji));
+  }
+}
+
 /// The name of a user setting that has a property in [UserSettings].
 ///
 /// In Zulip event-handling code (for [UserSettingsUpdateEvent]),

lib/api/model/model.dart

@@ -2,6 +2,17 @@ import 'package:checks/checks.dart';
 import 'package:zulip/api/model/model.dart';
 import 'package:zulip/api/model/submessage.dart';
 
+extension UserStatusChecks on Subject<UserStatus> {
+  Subject<String?> get text => has((x) => x.text, 'text');
+  Subject<StatusEmoji?> get emoji => has((x) => x.emoji, 'emoji');
+}
+
+extension StatusEmojiChecks on Subject<StatusEmoji> {
+  Subject<String> get emojiName => has((x) => x.emojiName, 'emojiName');
+  Subject<String> get emojiCode => has((x) => x.emojiCode, 'emojiCode');
+  Subject<ReactionType> get reactionType => has((x) => x.reactionType, 'reactionType');
+}
+
 extension UserChecks on Subject<User> {
   Subject<int> get userId => has((x) => x.userId, 'userId');
   Subject<String?> get deliveryEmail => has((x) => x.deliveryEmail, 'deliveryEmail');

test/api/model/model_checks.dart

@@ -1113,6 +1113,7 @@ InitialSnapshot initialSnapshot({
   List<Subscription>? subscriptions,
   UnreadMessagesSnapshot? unreadMsgs,
   List<ZulipStream>? streams,
+  Map<int, UserStatusChange>? userStatuses,
   UserSettings? userSettings,
   List<UserTopicItem>? userTopics,
   RealmWildcardMentionPolicy? realmWildcardMentionPolicy,
@@ -1154,6 +1155,7 @@ InitialSnapshot initialSnapshot({
     subscriptions: subscriptions ?? [], // TODO add subscriptions to default
     unreadMsgs: unreadMsgs ?? _unreadMsgs(),
     streams: streams ?? [], // TODO add streams to default
+    userStatuses: userStatuses ?? {},
     userSettings: userSettings ?? UserSettings(
       twentyFourHourTime: false,
       displayEmojiReactionUsers: true,