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

@@ -68,6 +68,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;
+
   final UserSettings userSettings;
 
   final List<UserTopicItem>? userTopics; // TODO(server-6)
@@ -151,6 +161,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);
+
+  @override
+  bool operator ==(Object other) {
+    if (other is! UserStatus) return false;
+    return (text, emoji) == (other.text, other.emoji);
+  }
+
+  @override
+  int get hashCode => Object.hash(text, emoji);
+}
+
+/// 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 != '');
+
+  @override
+  bool operator ==(Object other) {
+    if (other is! StatusEmoji) return false;
+    return (emojiName, emojiCode, reactionType) ==
+      (other.emojiName, other.emojiCode, other.reactionType);
+  }
+
+  @override
+  int get hashCode => Object.hash(emojiName, emojiCode, reactionType);
+}
+
+/// 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});
+
+  UserStatus apply(UserStatus old) {
+    return UserStatus(text: text.or(old.text), emoji: emoji.or(old.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 emojiName = json['emoji_name'] as String?;
+    final emojiCode = json['emoji_code'] as String?;
+    final reactionType = json['reaction_type'] as String?;
+
+    if (emojiName == null || emojiCode == null || reactionType == null) {
+      return OptionNone();
+    } else if (emojiName == '' || emojiCode == '' || reactionType == '') {
+      // 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(
+        emojiName: emojiName,
+        emojiCode: emojiCode,
+        reactionType: ReactionType.fromApiValue(reactionType)));
+    }
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      if (text case OptionSome<String?>(:var value))
+        'status_text': value ?? '',
+      if (emoji case OptionSome<StatusEmoji?>(:var value))
+        ...value == null
+          ? {'emoji_name': '', 'emoji_code': '', 'reaction_type': ''}
+          : {
+              'emoji_name': value.emojiName,
+              'emoji_code': value.emojiCode,
+              'reaction_type': value.reactionType,
+            },
+    };
+  }
+}
+
 /// The name of a user setting that has a property in [UserSettings].
 ///
 /// In Zulip event-handling code (for [UserSettingsUpdateEvent]),

lib/api/model/model.dart

@@ -1,6 +1,23 @@
 import 'package:checks/checks.dart';
 import 'package:zulip/api/model/model.dart';
 import 'package:zulip/api/model/submessage.dart';
+import 'package:zulip/basic.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 UserStatusChangeChecks on Subject<UserStatusChange> {
+  Subject<Option<String?>> get text => has((x) => x.text, 'text');
+  Subject<Option<StatusEmoji?>> get emoji => has((x) => x.emoji, 'emoji');
+}
 
 extension UserGroupChecks on Subject<UserGroup> {
   Subject<int> get id => has((x) => x.id, 'id');

test/api/model/model_checks.dart

@@ -4,6 +4,7 @@ import 'package:checks/checks.dart';
 import 'package:json_annotation/json_annotation.dart';
 import 'package:test/scaffolding.dart';
 import 'package:zulip/api/model/model.dart';
+import 'package:zulip/basic.dart';
 
 import '../../example_data.dart' as eg;
 import '../../stdlib_checks.dart';
@@ -25,6 +26,71 @@ void main() {
     });
   });
 
+  test('UserStatusChange', () {
+    void doCheck({
+      required (String? statusText, String? emojiName,
+                String? emojiCode, String? reactionType)          incoming,
+      required (Option<String?> text, Option<StatusEmoji?> emoji) expected,
+    }) {
+      check(UserStatusChange.fromJson({
+        'status_text': incoming.$1,
+        'emoji_name': incoming.$2,
+        'emoji_code': incoming.$3,
+        'reaction_type': incoming.$4,
+      }))
+        ..text.equals(expected.$1)
+        ..emoji.equals(expected.$2);
+    }
+
+    doCheck(
+      incoming: ('Busy', 'working_on_it', '1f6e0', 'unicode_emoji'),
+      expected: (OptionSome('Busy'), OptionSome(StatusEmoji(
+                                       emojiName: 'working_on_it',
+                                       emojiCode: '1f6e0',
+                                       reactionType: ReactionType.unicodeEmoji))));
+
+    doCheck(
+      incoming: ('', 'working_on_it', '1f6e0', 'unicode_emoji'),
+      expected: (OptionSome(null), OptionSome(StatusEmoji(
+                                     emojiName: 'working_on_it',
+                                     emojiCode: '1f6e0',
+                                     reactionType: ReactionType.unicodeEmoji))));
+
+    doCheck(
+      incoming: (null, 'working_on_it', '1f6e0', 'unicode_emoji'),
+      expected: (OptionNone(), OptionSome(StatusEmoji(
+                                 emojiName: 'working_on_it',
+                                 emojiCode: '1f6e0',
+                                 reactionType: ReactionType.unicodeEmoji))));
+
+    doCheck(
+      incoming: ('Busy', '', '', ''),
+      expected: (OptionSome('Busy'), OptionSome(null)));
+
+    doCheck(
+      incoming: ('Busy', null, null, null),
+      expected: (OptionSome('Busy'), OptionNone()));
+
+    doCheck(
+      incoming: ('', '', '', ''),
+      expected: (OptionSome(null), OptionSome(null)));
+
+    doCheck(
+      incoming: (null, null, null, null),
+      expected: (OptionNone(), OptionNone()));
+
+    // For the API quirk when `reaction_type` is 'unicode_emoji' when the
+    // emoji is cleared.
+    doCheck(
+      incoming: ('', '', '', 'unicode_emoji'),
+      expected: (OptionSome(null), OptionSome(null)));
+
+    // Hardly likely to happen from the API standpoint, but we handle it anyway.
+    doCheck(
+      incoming: (null, null, null, 'unicode_emoji'),
+      expected: (OptionNone(), OptionNone()));
+  });
+
   group('User', () {
     final Map<String, dynamic> baseJson = Map.unmodifiable({
       'user_id': 123,

test/api/model/model_test.dart

@@ -1138,6 +1138,7 @@ InitialSnapshot initialSnapshot({
   List<Subscription>? subscriptions,
   UnreadMessagesSnapshot? unreadMsgs,
   List<ZulipStream>? streams,
+  Map<int, UserStatusChange>? userStatuses,
   UserSettings? userSettings,
   List<UserTopicItem>? userTopics,
   RealmWildcardMentionPolicy? realmWildcardMentionPolicy,
@@ -1180,6 +1181,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,