api: In getMessages, use "dm" operator where possible

This is the last part of #146.

Fixes: #146

Author: gnprice

lib/api/model/narrow.dart

@@ -47,15 +47,53 @@ class ApiNarrowTopic extends ApiNarrowElement {
 }
 
 /// An [ApiNarrowElement] with the 'dm', or legacy 'pm-with', operator.
+///
+/// An instance directly of this class must not be serialized with [jsonEncode],
+/// and more generally its [operator] getter must not be called.
+/// Instead, call [resolve] and use the object it returns.
 class ApiNarrowDm extends ApiNarrowElement {
-  @override String get operator => 'pm-with'; // TODO(#146): use 'dm' where possible
+  @override String get operator {
+    assert(false,
+      "The [operator] getter was called on a plain [ApiNarrowDm].  "
+      "Before passing to [jsonEncode] or otherwise getting [operator], "
+      "the [ApiNarrowDm] must be replaced by the result of [ApiNarrowDm.resolve]."
+    );
+    return "dm";
+  }
 
   @override final List<int> operand;
 
   ApiNarrowDm(this.operand, {super.negated});
 
-  factory ApiNarrowDm.fromJson(Map<String, dynamic> json) => ApiNarrowDm(
-    (json['operand'] as List<dynamic>).map((e) => e as int).toList(),
-    negated: json['negated'] as bool? ?? false,
-  );
+  factory ApiNarrowDm.fromJson(Map<String, dynamic> json) {
+    var operand = (json['operand'] as List<dynamic>).map((e) => e as int).toList();
+    var negated = json['negated'] as bool? ?? false;
+    return (json['operator'] == 'pm-with')
+      ? ApiNarrowPmWith._(operand, negated: negated)
+      : ApiNarrowDmModern._(operand, negated: negated);
+  }
+
+  /// This element resolved, as either an [ApiNarrowDmModern] or an [ApiNarrowPmWith].
+  ApiNarrowDm resolve({required bool legacy}) {
+    return legacy ? ApiNarrowPmWith._(operand, negated: negated)
+                  : ApiNarrowDmModern._(operand, negated: negated);
+  }
+}
+
+/// An [ApiNarrowElement] with the 'dm' operator (and not the legacy 'pm-with').
+///
+/// To construct one of these, use [ApiNarrowDm.resolve].
+class ApiNarrowDmModern extends ApiNarrowDm {
+  @override String get operator => 'dm';
+
+  ApiNarrowDmModern._(super.operand, {super.negated});
+}
+
+/// An [ApiNarrowElement] with the legacy 'pm-with' operator.
+///
+/// To construct one of these, use [ApiNarrowDm.resolve].
+class ApiNarrowPmWith extends ApiNarrowDm {
+  @override String get operator => 'pm-with';
+
+  ApiNarrowPmWith._(super.operand, {super.negated});
 }

lib/api/route/messages.dart

@@ -17,6 +17,13 @@ Future<GetMessagesResult> getMessages(ApiConnection connection, {
   bool? applyMarkdown,
   // bool? useFirstUnreadAnchor // omitted because deprecated
 }) {
+  if (narrow.any((element) => element is ApiNarrowDm)) {
+    final supportsOperatorDm = connection.zulipFeatureLevel! >= 177; // TODO(server-7)
+    narrow = narrow.map((element) => switch (element) {
+      ApiNarrowDm() => element.resolve(legacy: !supportsOperatorDm),
+      _             => element,
+    }).toList();
+  }
   return connection.get('getMessages', GetMessagesResult.fromJson, 'messages', {
     'narrow': narrow,
     'anchor': switch (anchor) {

test/api/route/messages_test.dart

@@ -7,6 +7,7 @@ import 'package:zulip/api/model/narrow.dart';
 import 'package:zulip/api/route/messages.dart';
 import 'package:zulip/model/narrow.dart';
 
+import '../../example_data.dart' as eg;
 import '../../stdlib_checks.dart';
 import '../fake_api.dart';
 import 'route_checks.dart';
@@ -79,9 +80,14 @@ void main() {
           {'operator': 'topic', 'operand': 'stuff'},
         ]));
 
+        await checkNarrow([ApiNarrowDm([123, 234])], jsonEncode([
+          {'operator': 'dm', 'operand': [123, 234]},
+        ]));
+        connection.zulipFeatureLevel = 176;
         await checkNarrow([ApiNarrowDm([123, 234])], jsonEncode([
           {'operator': 'pm-with', 'operand': [123, 234]},
         ]));
+        connection.zulipFeatureLevel = eg.futureZulipFeatureLevel;
       });
     });