api: Add Submessage.

We are not storing the list of `Submessage`s directly on the Message objects
as they are pretty obscure until we further parse them into meaningful
data structures for things like polls and todos.

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

Author: PIG208

lib/api/model/model.dart

@@ -481,7 +481,6 @@ sealed class Message {
   final String senderRealmStr;
   @JsonKey(name: 'subject')
   String topic;
-  // final List<string> submessages; // TODO handle
   final int timestamp;
   String get type;
 

lib/api/model/submessage.dart

@@ -0,0 +1,36 @@
+import 'package:json_annotation/json_annotation.dart';
+
+part 'submessage.g.dart';
+
+/// Data used for certain experimental Zulip widgets including polls and todo
+/// lists.
+///
+/// See:
+///   https://zulip.com/api/get-messages#response
+///   https://zulip.readthedocs.io/en/latest/subsystems/widgets.html
+@JsonSerializable(fieldRename: FieldRename.snake)
+class Submessage {
+  const Submessage({
+    required this.msgType,
+    required this.content,
+    required this.senderId,
+  });
+
+  @JsonKey(unknownEnumValue: SubmessageType.unknown)
+  final SubmessageType msgType;
+  final String content;
+  // final int messageId;  // ignored; redundant with [Message.id]
+  final int senderId;
+  // final int id;  // ignored because it is unused
+
+  factory Submessage.fromJson(Map<String, Object?> json) =>
+    _$SubmessageFromJson(json);
+
+  Map<String, Object?> toJson() => _$SubmessageToJson(this);
+}
+
+/// As in [Submessage.msgType].
+enum SubmessageType {
+  widget,
+  unknown,
+}

lib/api/model/submessage.g.dart

@@ -0,0 +1,9 @@
+
+import 'package:checks/checks.dart';
+import 'package:zulip/api/model/submessage.dart';
+
+extension SubmessageChecks on Subject<Submessage> {
+  Subject<SubmessageType> get msgType => has((e) => e.msgType, 'msgType');
+  Subject<Object?> get content => has((e) => e.content, 'content');
+  Subject<int> get senderId => has((e) => e.senderId, 'senderId');
+}

test/api/model/submessage_checks.dart

@@ -0,0 +1,29 @@
+import 'package:checks/checks.dart';
+import 'package:test/scaffolding.dart';
+import 'package:zulip/api/model/submessage.dart';
+
+import '../../example_data.dart' as eg;
+import 'submessage_checks.dart';
+
+void main() {
+  group('Message.submessages', () {
+    test('no crash on unrecognized submessage type', () {
+      final submessageJson = {
+        'content': '[]',
+        'message_id': 123,
+        'sender_id': eg.selfUser.userId,
+        'id': 1,
+      };
+
+      check(Submessage.fromJson({
+        ...submessageJson,
+        'msg_type': 'widget',
+      })).msgType.equals(SubmessageType.widget);
+
+      check(Submessage.fromJson({
+        ...submessageJson,
+        'msg_type': 'unknown_widget',
+      })).msgType.equals(SubmessageType.unknown);
+    });
+  });
+}

test/api/model/submessage_test.dart

@@ -614,6 +614,14 @@ ReactionEvent reactionEvent(Reaction reaction, ReactionOp op, int messageId) {
   );
 }
 
+final pollWidgetDataFavoriteLetter = {
+  'widget_type': 'poll',
+  'extra_data': {
+    'question': 'favorite letter',
+    'options': ['A', 'B', 'C'],
+  }
+};
+
 ////////////////////////////////////////////////////////////////
 // The entire per-account or global state.
 //