api [nfc]: Establish that "local_id" is a JSON-encoded int

This will be used for local echoing.  It's not yet fully documented; see
CZO discussion:
  https://chat.zulip.org/#narrow/channel/412-api-documentation/topic/local_id.2C.20queue_id.2Fsender_queue_id/near/2135340

Author: PIG208

lib/api/model/events.dart

@@ -682,11 +682,26 @@ class MessageEvent extends Event {
   @JsonKey(readValue: _readMessageValue, includeToJson: false)
   final Message message;
 
-  MessageEvent({required super.id, required this.message});
+  // The format of this is documented to be chosen freely by the client.
+  //
+  // When present, this corresponds to the JSON-encoded int, "local_id",
+  // from a previous [sendMessage] call by us.
+  @JsonKey(fromJson: _localMessageIdFromJson, toJson: _localMessageIdToJson)
+  final int? localMessageId;
+
+  MessageEvent({required super.id, required this.message, required this.localMessageId});
 
   static Map<String, dynamic> _readMessageValue(Map<dynamic, dynamic> json, String key) =>
     {...json['message'] as Map<String, dynamic>, 'flags': json['flags']};
 
+  static int? _localMessageIdFromJson(Object? val) {
+    return val == null ? null : int.parse(val as String);
+  }
+
+  static String? _localMessageIdToJson(int? val) {
+    return val?.toString();
+  }
+
   factory MessageEvent.fromJson(Map<String, dynamic> json) =>
     _$MessageEventFromJson(json);
 

lib/api/model/events.g.dart

@@ -176,7 +176,7 @@ Future<SendMessageResult> sendMessage(
   required MessageDestination destination,
   required String content,
   String? queueId,
-  String? localId,
+  int? localId,
   bool? readBySender,
 }) {
   final supportsTypeDirect = connection.zulipFeatureLevel! >= 174; // TODO(server-7)
@@ -194,7 +194,11 @@ Future<SendMessageResult> sendMessage(
       }}),
     'content': RawParameter(content),
     if (queueId != null) 'queue_id': RawParameter(queueId),
-    if (localId != null) 'local_id': localId, // TODO should this use RawParameter?
+    // This is documented to be an optional String whose format is chosen freely
+    // by the client.  Use a JSON-encoded int consistently, so that we know how
+    // to decode it when we receive the corresponding "message" event.
+    // See also: [MessageEvent.localMessageId]
+    if (localId != null) 'local_id': localId,
     if (readBySender != null) 'read_by_sender': readBySender,
   },
   overrideUserAgent: switch ((supportsReadBySender, readBySender)) {

lib/api/route/messages.dart

@@ -39,6 +39,7 @@ extension SubscriptionUpdateEventChecks on Subject<SubscriptionUpdateEvent> {
 
 extension MessageEventChecks on Subject<MessageEvent> {
   Subject<Message> get message => has((e) => e.message, 'message');
+  Subject<int?> get localMessageId => has((e) => e.localMessageId, 'localMessageId');
 }
 
 extension UpdateMessageEventChecks on Subject<UpdateMessageEvent> {

test/api/model/events_checks.dart

@@ -88,6 +88,21 @@ void main() {
     check(mkEvent([MessageFlag.read])).message.flags.deepEquals([MessageFlag.read]);
   });
 
+  test('message: parsing local_message_id', () {
+    final message = eg.streamMessage(flags: []);
+    final event = Event.fromJson({
+      'type': 'message',
+      'id': 1,
+      'message': deepToJson(message) as Map<String, dynamic>,
+      'flags': <MessageFlag>[],
+      'local_message_id': '1234',
+    });
+    check(event).isA<MessageEvent>().localMessageId.equals(1234);
+    check(
+      Event.fromJson(deepToJson(event) as Map<String, dynamic>)
+    ).isA<MessageEvent>().localMessageId.equals(1234);
+  });
+
   group('update_message', () {
     final message = eg.streamMessage();
     final baseJson = {

test/api/model/events_test.dart

@@ -333,7 +333,7 @@ void main() {
       required MessageDestination destination,
       required String content,
       String? queueId,
-      String? localId,
+      int? localId,
       bool? readBySender,
       required Map<String, String> expectedBodyFields,
       String? expectedUserAgent,
@@ -355,15 +355,15 @@ void main() {
         await checkSendMessage(connection,
           destination: StreamDestination(streamId, eg.t(topic)), content: content,
           queueId: 'abc:123',
-          localId: '456',
+          localId: 456,
           readBySender: true,
           expectedBodyFields: {
             'type': 'stream',
             'to': streamId.toString(),
             'topic': topic,
             'content': content,
             'queue_id': 'abc:123',
-            'local_id': '"456"',
+            'local_id': '456',
             'read_by_sender': 'true',
           });
       });

test/api/route/messages_test.dart

@@ -621,7 +621,7 @@ UserTopicEvent userTopicEvent(
 }
 
 MessageEvent messageEvent(Message message) =>
-  MessageEvent(id: 0, message: message);
+  MessageEvent(id: 0, message: message, localMessageId: null);
 
 DeleteMessageEvent deleteMessageEvent(List<StreamMessage> messages) {
   assert(messages.isNotEmpty);