Support polls (read-only)

lib/api/model/events.dart

@@ -3,6 +3,7 @@ import 'package:json_annotation/json_annotation.dart';
 import '../../model/algorithms.dart';
 import 'json.dart';
 import 'model.dart';
+import 'submessage.dart';
 
 part 'events.g.dart';
 
@@ -63,6 +64,7 @@ sealed class Event {
           case 'remove': return UpdateMessageFlagsRemoveEvent.fromJson(json);
           default: return UnexpectedEvent.fromJson(json);
         }
+      case 'submessage': return SubmessageEvent.fromJson(json);
       case 'typing': return TypingEvent.fromJson(json);
       case 'reaction': return ReactionEvent.fromJson(json);
       case 'heartbeat': return HeartbeatEvent.fromJson(json);
@@ -942,6 +944,41 @@ class UpdateMessageFlagsMessageDetail {
   Map<String, dynamic> toJson() => _$UpdateMessageFlagsMessageDetailToJson(this);
 }
 
+/// A Zulip event of type `submessage`: https://zulip.com/api/get-events#submessage
+@JsonSerializable(fieldRename: FieldRename.snake)
+class SubmessageEvent extends Event {
+  @override
+  @JsonKey(includeToJson: true)
+  String get type => 'submessage';
+
+  @JsonKey(unknownEnumValue: SubmessageType.unknown)
+  final SubmessageType msgType;
+  /// [SubmessageData] encoded in JSON.
+  // We cannot parse the String into one of the [SubmessageData] classes because
+  // information from other submessages are required. Specifically, we need
+  // the parsed [WidgetData] from the first [Message.submessages] of the
+  // corresponding message.
+  final String content;
+  final int messageId;
+  final int senderId;
+  final int submessageId;
+
+  SubmessageEvent({
+    required super.id,
+    required this.msgType,
+    required this.content,
+    required this.messageId,
+    required this.senderId,
+    required this.submessageId,
+  });
+
+  factory SubmessageEvent.fromJson(Map<String, dynamic> json) =>
+    _$SubmessageEventFromJson(json);
+
+  @override
+  Map<String, dynamic> toJson() => _$SubmessageEventToJson(this);
+}
+
 /// A Zulip event of type `typing`:
 ///   https://zulip.com/api/get-events#typing-start
 ///   https://zulip.com/api/get-events#typing-stop

lib/api/model/model.dart

@@ -3,6 +3,7 @@ import 'package:json_annotation/json_annotation.dart';
 import 'events.dart';
 import 'initial_snapshot.dart';
 import 'reaction.dart';
+import 'submessage.dart';
 
 export 'json.dart' show JsonNullable;
 export 'reaction.dart';
@@ -533,6 +534,9 @@ sealed class Message {
   final String senderRealmStr;
   @JsonKey(name: 'subject')
   String topic;
+  /// Poll data if "submessages" describe a poll, `null` otherwise.
+  @JsonKey(name: 'submessages', readValue: _readPoll, fromJson: Poll.fromJson, toJson: Poll.toJson)
+  Poll? poll;
   final int timestamp;
   String get type;
 
@@ -564,6 +568,13 @@ sealed class Message {
     return list.map((raw) => MessageFlag.fromRawString(raw as String)).toList();
   }
 
+  static Poll? _readPoll(Map<Object?, Object?> json, String key) {
+    return Submessage.parseSubmessagesJson(
+      json['submessages'] as List<Object?>? ?? [],
+      messageSenderId: (json['sender_id'] as num).toInt(),
+    );
+  }
+
   Message({
     required this.client,
     required this.content,

lib/api/model/submessage.dart

@@ -1,5 +1,10 @@
+import 'dart:convert';
+
 import 'package:json_annotation/json_annotation.dart';
 
+import '../../log.dart';
+import 'events.dart';
+
 part 'submessage.g.dart';
 
 /// Data used for Zulip "widgets" within messages, like polls and todo lists.
@@ -38,9 +43,33 @@ class Submessage {
   // We cannot parse the String into one of the [SubmessageData] classes because
   // information from other submessages are required. Specifically, we need:
   //   * the index of this submessage in [Message.submessages];
-  //   * the [WidgetType] of the first [Message.submessages].
+  //   * the parsed [WidgetType] from the first [Message.submessages].
   final String content;
 
+  /// Parse a JSON list into a [Poll].
+  // TODO: Use a generalized return type when supporting other Zulip widgets.
+  static Poll? parseSubmessagesJson(List<Object?> json, {
+    required int messageSenderId,
+  }) {
+    final submessages = json.map((e) => Submessage.fromJson(e as Map<String, Object?>)).toList();
+    if (submessages.isEmpty) return null;
+
+    assert(submessages.first.senderId == messageSenderId);
+
+    final widgetData = WidgetData.fromJson(jsonDecode(submessages.first.content));
+    switch (widgetData) {
+      case PollWidgetData():
+        return Poll.fromSubmessages(
+          widgetData: widgetData,
+          pollEventSubmessages: submessages.skip(1),
+          messageSenderId: messageSenderId,
+        );
+      case UnsupportedWidgetData():
+        assert(debugLog('Unsupported widgetData: ${widgetData.json}'));
+        return null;
+    }
+  }
+
   factory Submessage.fromJson(Map<String, Object?> json) =>
     _$SubmessageFromJson(json);
 
@@ -65,7 +94,9 @@ enum SubmessageType {
 ///  * Zero or more submessages with content [PollEventSubmessage] if the
 ///    message is a poll (i.e. if the first submessage was a [PollWidgetData]),
 ///    and similarly for other types of widgets.
-sealed class SubmessageData {}
+sealed class SubmessageData {
+  Object? toJson();
+}
 
 /// The data encoded in a submessage to make the message a Zulip widget.
 ///
@@ -87,6 +118,7 @@ sealed class WidgetData extends SubmessageData {
     };
   }
 
+  @override
   Object? toJson();
 }
 
@@ -173,7 +205,7 @@ sealed class PollEventSubmessage extends SubmessageData {
   ///
   /// For options that are a part of the initial [PollWidgetData], the
   /// [senderId] should be `null`.
-  static String optionKey({required int? senderId, required int idx}) =>
+  static PollOptionKey optionKey({required int? senderId, required int idx}) =>
     // "canned" is a canonical constant coined by the web client:
     //   https://github.com/zulip/zulip/blob/40f59a05c/web/shared/src/poll_data.ts#L238
     '${senderId ?? 'canned'},$idx';
@@ -188,6 +220,7 @@ sealed class PollEventSubmessage extends SubmessageData {
     }
   }
 
+  @override
   Map<String, Object?> toJson();
 }
 
@@ -205,6 +238,8 @@ enum PollEventSubmessageType {
     .map((key, value) => MapEntry(value, key));
 }
 
+typedef PollOptionKey = String;
+
 /// A poll event when an option is added.
 ///
 /// See: https://github.com/zulip/zulip/blob/40f59a05c/web/shared/src/poll_data.ts#L112-L159
@@ -264,7 +299,7 @@ class PollVoteEventSubmessage extends PollEventSubmessage {
   /// The key of the affected option.
   ///
   /// See [PollEventSubmessage.optionKey].
-  final String key;
+  final PollOptionKey key;
   @JsonKey(name: 'vote', unknownEnumValue: PollVoteOp.unknown)
   final PollVoteOp op;
 
@@ -313,3 +348,137 @@ class UnknownPollEventSubmessage extends PollEventSubmessage {
   @override
   Map<String, Object?> toJson() => json;
 }
+
+/// States of a poll Zulip widget.
+///
+/// See also:
+/// - https://zulip.com/help/create-a-poll
+/// - https://github.com/zulip/zulip/blob/304d948416465c1a085122af5d752f03d6797003/web/shared/src/poll_data.ts
+class Poll {
+  /// Construct a poll from submessages.
+  ///
+  /// For a poll Zulip widget, the first submessage's content contains a
+  /// [PollWidgetData], and all the following submessages' content each contains
+  /// a [PollEventSubmessage].
+  factory Poll.fromSubmessages({
+    required PollWidgetData widgetData,
+    required Iterable<Submessage> pollEventSubmessages,
+    required int messageSenderId,
+  }) {
+    final poll = Poll._(
+      messageSenderId: messageSenderId,
+      question: widgetData.extraData.question,
+      options: widgetData.extraData.options,
+    );
+
+    for (final submessage in pollEventSubmessages) {
+      final event = PollEventSubmessage.fromJson(jsonDecode(submessage.content) as Map<String, Object?>);
+      poll._applyEvent(submessage.senderId, event);
+    }
+    return poll;
+  }
+
+  Poll._({
+    required this.messageSenderId,
+    required this.question,
+    required List<String> options,
+  }) {
+    for (int index = 0; index < options.length; index += 1) {
+      // Initial poll options use a placeholder senderId.
+      // See [PollEventSubmessage.optionKey] for details.
+      _addOption(senderId: null, idx: index, option: options[index]);
+    }
+  }
+
+  final int messageSenderId;
+  String question;
+
+  /// The limit of options any single user can add to a poll.
+  ///
+  /// See https://github.com/zulip/zulip/blob/304d948416465c1a085122af5d752f03d6797003/web/shared/src/poll_data.ts#L69-L71
+  static const _maxIdx = 1000;
+
+  Iterable<PollOption> get options => _options.values;
+  /// Contains the text of all options from [_options].
+  final Set<String> _existingOptionTexts = {};
+  final Map<PollOptionKey, PollOption> _options = {};
+
+  void handleSubmessageEvent(SubmessageEvent event) {
+    final PollEventSubmessage? pollEventSubmessage;
+    try {
+      pollEventSubmessage = PollEventSubmessage.fromJson(jsonDecode(event.content) as Map<String, Object?>);
+    } catch (e) {
+      assert(debugLog('Malformed submessage event data for poll: $e\n${jsonEncode(event)}')); // TODO(log)
+      return;
+    }
+    _applyEvent(event.senderId, pollEventSubmessage);
+  }
+
+  void _applyEvent(int senderId, PollEventSubmessage event) {
+    switch (event) {
+      case PollNewOptionEventSubmessage():
+        _addOption(senderId: senderId, idx: event.idx, option: event.option);
+
+      case PollQuestionEventSubmessage():
+        if (senderId != messageSenderId) {
+          // Only the message owner can edit the question.
+          assert(debugLog('unexpected poll data: user $senderId is not allowed to edit the question')); // TODO(log)
+          return;
+        }
+
+        question = event.question;
+
+      case PollVoteEventSubmessage():
+        final option = _options[event.key];
+        if (option == null) {
+          assert(debugLog('vote for unknown key ${event.key}')); // TODO(log)
+          return;
+        }
+
+        switch (event.op) {
+          case PollVoteOp.add:
+            option.voters.add(senderId);
+          case PollVoteOp.remove:
+            option.voters.remove(senderId);
+          case PollVoteOp.unknown:
+            assert(debugLog('unknown vote op ${event.op}')); // TODO(log)
+        }
+
+      case UnknownPollEventSubmessage():
+    }
+  }
+
+  void _addOption({required int? senderId, required int idx, required String option}) {
+    if (idx > _maxIdx || idx < 0) return;
+
+    // The web client suppresses duplicate options, which can be created through
+    // the /poll command as there is no server-side validation.
+    if (_existingOptionTexts.contains(option)) return;
+
+    final key = PollEventSubmessage.optionKey(senderId: senderId, idx: idx);
+    assert(!_options.containsKey(key));
+    _options[key] = PollOption(text: option);
+    _existingOptionTexts.add(option);
+  }
+
+  static Poll? fromJson(Object? json) {
+    // [Submessage.parseSubmessagesJson] does all the heavy lifting for parsing.
+    return json as Poll?;
+  }
+
+  static List<Submessage> toJson(Poll? poll) {
+    // Rather than maintaining a up-to-date submessages list, return as if it is
+    // empty, because we are not sending the submessages to the server anyway.
+    return [];
+  }
+}
+
+class PollOption {
+  PollOption({required this.text});
+
+  final String text;
+  final Set<int> voters = {};
+
+  @override
+  String toString() => 'PollOption(text: $text, voters: {${voters.join(', ')}})';
+}