api: Add send-message route

Author: chrisbobbe

lib/api/route/messages.dart

@@ -46,3 +46,56 @@ class GetMessagesResult {
 
   Map<String, dynamic> toJson() => _$GetMessagesResultToJson(this);
 }
+
+// https://zulip.com/api/send-message#parameter-topic
+const int kMaxTopicLength = 60;
+
+// https://zulip.com/api/send-message#parameter-content
+const int kMaxMessageLengthCodePoints = 10000;
+
+/// The topic servers understand to mean "there is no topic".
+///
+/// This should match
+///   https://github.com/zulip/zulip/blob/6.0/zerver/actions/message_edit.py#L940
+/// or similar logic at the latest `main`.
+// This is hardcoded in the server, and therefore untranslated; that's
+// zulip/zulip#3639.
+const String kNoTopicTopic = '(no topic)';
+
+/// https://zulip.com/api/send-message
+// TODO currently only handles stream messages; fix
+Future<SendMessageResult> sendMessage(
+  ApiConnection connection, {
+  required String content,
+  required String topic,
+}) async {
+  // assert() is less verbose but would have no effect in production, I think:
+  //   https://dart.dev/guides/language/language-tour#assert
+  if (Uri.parse(connection.auth.realmUrl).origin != 'https://chat.zulip.org') {
+    throw AssertionError('This binding can currently only be used on https://chat.zulip.org.');
+  }
+
+  final data = await connection.post('messages', {
+    'type': RawParameter('stream'), // TODO parametrize
+    'to': 7, // TODO parametrize; this is `#test here`
+    'topic': RawParameter(topic),
+    'content': RawParameter(content),
+  });
+  return SendMessageResult.fromJson(jsonDecode(data));
+}
+
+@JsonSerializable()
+class SendMessageResult {
+  final int id;
+  final String? deliver_at;
+
+  SendMessageResult({
+    required this.id,
+    this.deliver_at,
+  });
+
+  factory SendMessageResult.fromJson(Map<String, dynamic> json) =>
+      _$SendMessageResultFromJson(json);
+
+  Map<String, dynamic> toJson() => _$SendMessageResultToJson(this);
+}