api: Add updateMessageFlags and updateMessageFlagsForNarrow routes

Author: sirpengi

lib/api/model/model.dart

@@ -430,7 +430,7 @@ sealed class Message {
   Map<String, dynamic> toJson();
 }
 
-/// As in [Message.flags].
+/// https://zulip.com/api/update-message-flags#available-flags
 @JsonEnum(fieldRename: FieldRename.snake, alwaysCreate: true)
 enum MessageFlag {
   read,

lib/api/route/messages.dart

@@ -288,3 +288,88 @@ Future<void> removeReaction(ApiConnection connection, {
     'reaction_type': RawParameter(reactionType.toJson()),
   });
 }
+
+/// https://zulip.com/api/update-message-flags
+Future<UpdateMessageFlagsResult> updateMessageFlags(ApiConnection connection, {
+  required List<int> messages,
+  required UpdateMessageFlagsOp op,
+  required MessageFlag flag,
+}) {
+  return connection.post('updateMessageFlags', UpdateMessageFlagsResult.fromJson, 'messages/flags', {
+    'messages': messages,
+    'op': RawParameter(op.toJson()),
+    'flag': RawParameter(flag.toJson()),
+  });
+}
+
+/// An `op` value for [updateMessageFlags] and [updateMessageFlagsForNarrow].
+@JsonEnum(fieldRename: FieldRename.snake, alwaysCreate: true)
+enum UpdateMessageFlagsOp {
+  add,
+  remove;
+
+  String toJson() => _$UpdateMessageFlagsOpEnumMap[this]!;
+}
+
+@JsonSerializable(fieldRename: FieldRename.snake)
+class UpdateMessageFlagsResult {
+  final List<int> messages;
+
+  UpdateMessageFlagsResult({
+    required this.messages,
+  });
+
+  factory UpdateMessageFlagsResult.fromJson(Map<String, dynamic> json) =>
+    _$UpdateMessageFlagsResultFromJson(json);
+
+  Map<String, dynamic> toJson() => _$UpdateMessageFlagsResultToJson(this);
+}
+
+/// https://zulip.com/api/update-message-flags-for-narrow
+///
+/// This binding only supports feature levels 155+.
+// TODO(server-6) remove FL 155+ mention in doc, and the related `assert`
+Future<UpdateMessageFlagsForNarrowResult> updateMessageFlagsForNarrow(ApiConnection connection, {
+  required Anchor anchor,
+  bool? includeAnchor,
+  required int numBefore,
+  required int numAfter,
+  required ApiNarrow narrow,
+  required UpdateMessageFlagsOp op,
+  required MessageFlag flag,
+}) {
+  assert(connection.zulipFeatureLevel! >= 155);
+  return connection.post('updateMessageFlagsForNarrow', UpdateMessageFlagsForNarrowResult.fromJson, 'messages/flags/narrow', {
+    'anchor': RawParameter(anchor.toJson()),
+    if (includeAnchor != null) 'include_anchor': includeAnchor,
+    'num_before': numBefore,
+    'num_after': numAfter,
+    'narrow': resolveDmElements(narrow, connection.zulipFeatureLevel!),
+    'op': RawParameter(op.toJson()),
+    'flag': RawParameter(flag.toJson()),
+  });
+}
+
+@JsonSerializable(fieldRename: FieldRename.snake)
+class UpdateMessageFlagsForNarrowResult {
+  final int processedCount;
+  final int updatedCount;
+  final int? firstProcessedId;
+  final int? lastProcessedId;
+  final bool foundOldest;
+  final bool foundNewest;
+
+  UpdateMessageFlagsForNarrowResult({
+    required this.processedCount,
+    required this.updatedCount,
+    required this.firstProcessedId,
+    required this.lastProcessedId,
+    required this.foundOldest,
+    required this.foundNewest,
+  });
+
+  factory UpdateMessageFlagsForNarrowResult.fromJson(Map<String, dynamic> json) =>
+    _$UpdateMessageFlagsForNarrowResultFromJson(json);
+
+  Map<String, dynamic> toJson() => _$UpdateMessageFlagsForNarrowResultToJson(this);
+}

lib/api/route/messages.g.dart

@@ -451,4 +451,124 @@ void main() {
       });
     });
   });
+
+  group('updateMessageFlags', () {
+    Future<UpdateMessageFlagsResult> checkUpdateMessageFlags(
+      FakeApiConnection connection, {
+      required List<int> messages,
+      required UpdateMessageFlagsOp op,
+      required MessageFlag flag,
+      required Map<String, String> expected,
+    }) async {
+      final result = await updateMessageFlags(connection,
+        messages: messages, op: op, flag: flag);
+      check(connection.lastRequest).isA<http.Request>()
+        ..method.equals('POST')
+        ..url.path.equals('/api/v1/messages/flags')
+        ..bodyFields.deepEquals(expected);
+      return result;
+    }
+
+    test('smoke', () {
+      return FakeApiConnection.with_((connection) async {
+        connection.prepare(json:
+          UpdateMessageFlagsResult(messages: [1, 2]).toJson());
+        await checkUpdateMessageFlags(connection,
+          messages: [1, 2, 3],
+          op: UpdateMessageFlagsOp.add, flag: MessageFlag.read,
+          expected: {
+            'messages': jsonEncode([1, 2, 3]),
+            'op': 'add',
+            'flag': 'read',
+          });
+      });
+    });
+  });
+
+  group('updateMessageFlagsForNarrow', () {
+    Future<UpdateMessageFlagsForNarrowResult> checkUpdateMessageFlagsForNarrow(
+      FakeApiConnection connection, {
+      required Anchor anchor,
+      required int numBefore,
+      required int numAfter,
+      required ApiNarrow narrow,
+      required UpdateMessageFlagsOp op,
+      required MessageFlag flag,
+      required Map<String, String> expected,
+    }) async {
+      final result = await updateMessageFlagsForNarrow(connection,
+        anchor: anchor, numBefore: numBefore, numAfter: numAfter,
+        narrow: narrow, op: op, flag: flag);
+      check(connection.lastRequest).isA<http.Request>()
+        ..method.equals('POST')
+        ..url.path.equals('/api/v1/messages/flags/narrow')
+        ..bodyFields.deepEquals(expected);
+      return result;
+    }
+
+    UpdateMessageFlagsForNarrowResult mkResult({required bool foundOldest}) =>
+      UpdateMessageFlagsForNarrowResult(
+        processedCount: 11, updatedCount: 3,
+        firstProcessedId: null, lastProcessedId: null,
+        foundOldest: foundOldest, foundNewest: true);
+
+    test('smoke', () {
+      return FakeApiConnection.with_((connection) async {
+        connection.prepare(json: mkResult(foundOldest: true).toJson());
+        await checkUpdateMessageFlagsForNarrow(connection,
+          anchor: AnchorCode.oldest,
+          numBefore: 0, numAfter: 20,
+          narrow: const AllMessagesNarrow().apiEncode(),
+          op: UpdateMessageFlagsOp.add, flag: MessageFlag.read,
+          expected: {
+            'anchor': 'oldest',
+            'num_before': '0',
+            'num_after': '20',
+            'narrow': jsonEncode([]),
+            'op': 'add',
+            'flag': 'read',
+          });
+      });
+    });
+
+    test('narrow uses resolveDmElements to encode', () {
+      return FakeApiConnection.with_(zulipFeatureLevel: 176, (connection) async {
+        connection.prepare(json: mkResult(foundOldest: true).toJson());
+        await checkUpdateMessageFlagsForNarrow(connection,
+          anchor: AnchorCode.oldest,
+          numBefore: 0, numAfter: 20,
+          narrow: [ApiNarrowDm([123, 234])],
+          op: UpdateMessageFlagsOp.add, flag: MessageFlag.read,
+          expected: {
+            'anchor': 'oldest',
+            'num_before': '0',
+            'num_after': '20',
+            'narrow': jsonEncode([
+              {'operator': 'pm-with', 'operand': [123, 234]},
+            ]),
+            'op': 'add',
+            'flag': 'read',
+          });
+      });
+    });
+
+    test('numeric anchor', () {
+      return FakeApiConnection.with_((connection) async {
+        connection.prepare(json: mkResult(foundOldest: false).toJson());
+        await checkUpdateMessageFlagsForNarrow(connection,
+          anchor: const NumericAnchor(42),
+          numBefore: 0, numAfter: 20,
+          narrow: const AllMessagesNarrow().apiEncode(),
+          op: UpdateMessageFlagsOp.add, flag: MessageFlag.read,
+          expected: {
+            'anchor': '42',
+            'num_before': '0',
+            'num_after': '20',
+            'narrow': jsonEncode([]),
+            'op': 'add',
+            'flag': 'read',
+          });
+      });
+    });
+  });
 }