submessage: Add SubmessageData classes for polls.

The sealed class `SubmessageData` is not actually in use, we could
potentially implement a discriminator utilizing the sealed class to
deserialize individual submessage content, but it is far easier to do so
when we have access to the full list of submessages. `SubmessageData` is
there for self-documentation.

It is also worth noting that much of these class definitions are based
on previous reverse engineering effort and the web implementation. See:

- https://github.com/zulip/zulip/blob/304d948416465c1a085122af5d752f03d6797003/web/shared/src/poll_data.ts
- https://github.com/zulip/zulip-mobile/blob/2217c858e207f9f092651dd853051843c3f04422/src/api/modelTypes.js#L800-L861

Due to the flexibility of the submessage API, these classes tend to be
intentionally defensive against unknown or invalid values.

Signed-off-by: Zixuan James Li <[email protected]>

Author: PIG208

lib/api/model/submessage.dart

@@ -18,6 +18,11 @@ class 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 index of this submessage in [Message.submessages];
+  //   * the [WidgetType] of the first [Message.submessages].
   final String content;
   // final int messageId;  // ignored; redundant with [Message.id]
   final int senderId;
@@ -34,3 +39,229 @@ enum SubmessageType {
   widget,
   unknown,
 }
+
+sealed class SubmessageData {}
+
+/// The data encoded in a submessage to make the message a Zulip widget.
+///
+/// Expected from the first [Submessage.content] in the "submessages" field on
+/// the message when there is an widget.
+///
+/// See https://zulip.readthedocs.io/en/latest/subsystems/widgets.html
+sealed class WidgetData extends SubmessageData {
+  WidgetType get widgetType;
+
+  WidgetData();
+
+  factory WidgetData.fromJson(Object? json) {
+    final map = json as Map<String, Object?>;
+    final rawWidgetType = map['widget_type'] as String;
+    return switch (WidgetType.fromRawString(rawWidgetType)) {
+      WidgetType.poll => PollWidgetData.fromJson(map),
+      WidgetType.unknown => UnsupportedWidgetData(json: map),
+    };
+  }
+
+  Object? toJson();
+}
+
+/// As in [WidgetData.widgetType].
+@JsonEnum(alwaysCreate: true)
+enum WidgetType {
+  poll,
+  unknown;
+
+  static WidgetType fromRawString(String raw) => _byRawString[raw] ?? unknown;
+
+  static final _byRawString = _$WidgetTypeEnumMap
+    .map((key, value) => MapEntry(value, key));
+}
+
+/// The data encoded in a submessage to make the message a poll widget.
+@JsonSerializable(fieldRename: FieldRename.snake)
+class PollWidgetData extends WidgetData {
+  @override
+  @JsonKey(includeToJson: true)
+  WidgetType get widgetType => WidgetType.poll;
+
+  /// The initial question and options on the poll.
+  final PollWidgetExtraData extraData;
+
+  PollWidgetData({required this.extraData});
+
+  factory PollWidgetData.fromJson(Map<String, Object?> json) =>
+    _$PollWidgetDataFromJson(json);
+
+  @override
+  Map<String, Object?> toJson() => _$PollWidgetDataToJson(this);
+}
+
+/// As in [PollWidgetData.extraData].
+@JsonSerializable(fieldRename: FieldRename.snake)
+class PollWidgetExtraData {
+  final String question;
+  final List<String> options;
+
+  const PollWidgetExtraData({required this.question, required this.options});
+
+  factory PollWidgetExtraData.fromJson(Map<String, Object?> json) =>
+    _$PollWidgetExtraDataFromJson(json);
+
+  Map<String, Object?> toJson() => _$PollWidgetExtraDataToJson(this);
+}
+
+class UnsupportedWidgetData extends WidgetData {
+  @override
+  @JsonKey(includeToJson: true)
+  WidgetType get widgetType => WidgetType.unknown;
+
+  UnsupportedWidgetData({required this.json});
+
+  final Object? json;
+
+  @override
+  Object? toJson() => json;
+}
+
+/// The data encoded in a submessage that acts on a poll.
+sealed class PollEventSubmessage extends SubmessageData {
+  PollEventSubmessageType get type;
+
+  PollEventSubmessage();
+
+  /// The key for identifying the [optionIndex]'th option added by user
+  /// [senderId] to a poll.
+  ///
+  /// For options that are a part of the initial [PollWidgetData], the
+  /// [senderId] should be `null`.
+  static String optionKey({required int? senderId, required int optionIndex}) =>
+    // "canned" is a canonical constant coined by the web client.
+    '${senderId ?? 'canned'},$optionIndex';
+
+  factory PollEventSubmessage.fromJson(Map<String, Object?> json) {
+    final rawPollEventType = json['type'] as String;
+    switch (PollEventSubmessageType.fromRawString(rawPollEventType)) {
+      case PollEventSubmessageType.newOption: return PollNewOptionEventSubmessage.fromJson(json);
+      case PollEventSubmessageType.question: return PollQuestionEventSubmessage.fromJson(json);
+      case PollEventSubmessageType.vote: return PollVoteEventSubmessage.fromJson(json);
+      case PollEventSubmessageType.unknown: return UnknownPollEventSubmessage(json: json);
+    }
+  }
+
+  Map<String, Object?> toJson();
+}
+
+/// A poll event when an option is added.
+@JsonSerializable(fieldRename: FieldRename.snake)
+class PollNewOptionEventSubmessage extends PollEventSubmessage {
+  @override
+  @JsonKey(includeToJson: true)
+  PollEventSubmessageType get type => PollEventSubmessageType.newOption;
+
+  final String option;
+  /// The index of last [option] added by the sender.
+  @JsonKey(name: 'idx')
+  final int latestOptionIndex;
+
+  PollNewOptionEventSubmessage({required this.option, required this.latestOptionIndex});
+
+  @override
+  factory PollNewOptionEventSubmessage.fromJson(Map<String, Object?> json) =>
+    _$PollNewOptionEventSubmessageFromJson(json);
+
+  @override
+  Map<String, Object?> toJson() => _$PollNewOptionEventSubmessageToJson(this);
+}
+
+/// A poll event when the question has been edited.
+@JsonSerializable(fieldRename: FieldRename.snake)
+class PollQuestionEventSubmessage extends PollEventSubmessage {
+  @override
+  @JsonKey(includeToJson: true)
+  PollEventSubmessageType get type => PollEventSubmessageType.question;
+
+  final String question;
+
+  PollQuestionEventSubmessage({required this.question});
+
+  @override
+  factory PollQuestionEventSubmessage.fromJson(Map<String, Object?> json) =>
+    _$PollQuestionEventSubmessageFromJson(json);
+
+  @override
+  Map<String, Object?> toJson() => _$PollQuestionEventSubmessageToJson(this);
+}
+
+/// A poll event when a vote has been cast or removed.
+@JsonSerializable(fieldRename: FieldRename.snake)
+class PollVoteEventSubmessage extends PollEventSubmessage {
+  @override
+  @JsonKey(includeToJson: true)
+  PollEventSubmessageType get type => PollEventSubmessageType.vote;
+
+  /// The key of the affected option.
+  ///
+  /// See [PollEventSubmessage.optionKey].
+  final String key;
+  @JsonKey(name: 'vote', unknownEnumValue: PollVoteOp.unknown)
+  final PollVoteOp op;
+
+  PollVoteEventSubmessage({required this.key, required this.op});
+
+  @override
+  factory PollVoteEventSubmessage.fromJson(Map<String, Object?> json) {
+    final result = _$PollVoteEventSubmessageFromJson(json);
+    // Crunchy-shell validation
+    final segments = result.key.split(',');
+    final [senderId, optionIndex] = segments;
+    if (senderId != 'canned') {
+      int.parse(senderId, radix: 10);
+    }
+    int.parse(optionIndex, radix: 10);
+    return result;
+  }
+
+  @override
+  Map<String, Object?> toJson() => _$PollVoteEventSubmessageToJson(this);
+}
+
+/// As in [PollVoteEventSubmessage.op].
+@JsonEnum(valueField: 'apiValue')
+enum PollVoteOp {
+  add(apiValue: 1),
+  remove(apiValue: -1),
+  unknown(apiValue: null);
+
+  const PollVoteOp({required this.apiValue});
+
+  final int? apiValue;
+
+  int? toJson() => apiValue;
+}
+
+class UnknownPollEventSubmessage extends PollEventSubmessage {
+  @override
+  @JsonKey(includeToJson: true)
+  PollEventSubmessageType get type => PollEventSubmessageType.unknown;
+
+  final Map<String, Object?> json;
+
+  UnknownPollEventSubmessage({required this.json});
+
+  @override
+  Map<String, Object?> toJson() => json;
+}
+
+/// As in [PollEventSubmessage.type].
+@JsonEnum(fieldRename: FieldRename.snake)
+enum PollEventSubmessageType {
+  newOption,
+  question,
+  vote,
+  unknown;
+
+  static PollEventSubmessageType fromRawString(String raw) => _byRawString[raw]!;
+
+  static final _byRawString = _$PollEventSubmessageTypeEnumMap
+    .map((key, value) => MapEntry(value, key));
+}

lib/api/model/submessage.g.dart

@@ -7,3 +7,33 @@ extension SubmessageChecks on Subject<Submessage> {
   Subject<Object?> get content => has((e) => e.content, 'content');
   Subject<int> get senderId => has((e) => e.senderId, 'senderId');
 }
+
+extension WidgetDataChecks on Subject<WidgetData> {
+  Subject<WidgetType> get widgetType => has((e) => e.widgetType, 'widgetType');
+}
+
+extension PollWidgetDataChecks on Subject<PollWidgetData> {
+  Subject<PollWidgetExtraData> get extraData => has((e) => e.extraData, 'extraData');
+}
+
+extension PollWidgetExtraDataChecks on Subject<PollWidgetExtraData> {
+  Subject<String> get question => has((e) => e.question, 'question');
+  Subject<List<String>> get options => has((e) => e.options, 'options');
+}
+
+extension PollEventChecks on Subject<PollEventSubmessage> {
+  Subject<PollEventSubmessageType> get type => has((e) => e.type, 'type');
+}
+
+extension PollOptionEventChecks on Subject<PollNewOptionEventSubmessage> {
+  Subject<String> get option => has((e) => e.option, 'option');
+}
+
+extension PollQuestionEventChecks on Subject<PollQuestionEventSubmessage> {
+  Subject<String> get question => has((e) => e.question, 'question');
+}
+
+extension PollVoteEventChecks on Subject<PollVoteEventSubmessage> {
+  Subject<String> get key => has((e) => e.key, 'key');
+  Subject<PollVoteOp> get op => has((e) => e.op, 'op');
+}