api: Add getSingleMessage binding for GET messages/{message_id}

We'll use this for zulip#5306; see the plan in discussion:
  https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/.23M5306.20Follow.20.2Fnear.2F.20links.20through.20topic.20moves.2Frenames/near/1407930

In particular, we want the stream and topic for a stream message
that might not be in our data structures. We'll use this endpoint to
fetch that information.

Author: chrisbobbe

src/api/index.js

@@ -30,6 +30,7 @@ import deleteMessage from './messages/deleteMessage';
 import deleteTopic from './messages/deleteTopic';
 import getRawMessageContent from './messages/getRawMessageContent';
 import getMessages from './messages/getMessages';
+import getSingleMessage from './messages/getSingleMessage';
 import getMessageHistory from './messages/getMessageHistory';
 import messagesFlags from './messages/messagesFlags';
 import sendMessage from './messages/sendMessage';
@@ -78,6 +79,7 @@ export {
   deleteTopic,
   getRawMessageContent,
   getMessages,
+  getSingleMessage,
   getMessageHistory,
   messagesFlags,
   sendMessage,

src/api/messages/getSingleMessage.js

@@ -0,0 +1,133 @@
+/* @flow strict-local */
+import invariant from 'invariant';
+
+import type { Auth, ApiResponseSuccess } from '../transportTypes';
+import type { Identity, UserId } from '../../types';
+import type { Message } from '../apiTypes';
+import type { PmMessage, StreamMessage, MessageEdit, ReactionType } from '../modelTypes';
+import { apiGet } from '../apiFetch';
+import { identityOfAuth } from '../../account/accountMisc';
+import { AvatarURL } from '../../utils/avatar';
+
+/**
+ * The variant of `Reaction` found in the actual server response.
+ *
+ * Note that reaction events have a *different* variation; see their
+ * handling in `eventToAction`.
+ */
+export type ServerReaction = {|
+  +emoji_name: string,
+  +emoji_code: string,
+  +reaction_type: ReactionType,
+
+  // Our binding assumes FL 120 (see jsdoc), so we don't have to handle FLs
+  // <2 that don't provide `user_id`.
+  +user_id: UserId,
+
+  // Deprecated and "to be removed in a future release":
+  //   https://zulip.com/api/get-message
+  -user: $ReadOnly<{|
+    id: UserId,
+    email: string,
+    full_name: string,
+
+    // Not observed, so marked optional (doc says required)
+    is_mirror_dummy?: boolean,
+  |}>,
+|};
+
+/**
+ * The elements of Message.edit_history found in the actual server response.
+ */
+export type ServerMessageEdit = {|
+  // Our binding assumes FL 120 (see jsdoc), so we don't have to support
+  // the pre-FL 118 shape. This type is written accordingly.
+
+  +prev_content?: string,
+  +prev_rendered_content?: string,
+  +prev_rendered_content_version?: number,
+  +prev_stream?: number,
+  +prev_topic?: string,
+  +stream?: number,
+  +timestamp: number,
+  +topic?: string,
+  +user_id: UserId | null,
+|};
+
+// How `ServerMessage` relates to `Message`, in a way that applies
+// uniformly to `Message`'s subtypes.
+type ServerMessageOf<M: Message> = {|
+  ...$Exact<M>,
+
+  // Can be null. The server hard-codes client_gravatar:
+  //   https://chat.zulip.org/#narrow/stream/378-api-design/topic/.60client_gravatar.60.20in.20.60messages.2F.7Bmessage_id.7D.60/near/1418337
+  +avatar_url: string | null,
+
+  +reactions: $ReadOnlyArray<ServerReaction>,
+
+  // Unlike Message['edit_history'], this can't be `null`.
+  +edit_history?: $ReadOnlyArray<ServerMessageEdit>,
+|};
+
+export type ServerMessage = ServerMessageOf<PmMessage> | ServerMessageOf<StreamMessage>;
+
+// The actual response from the server.  We convert the message to a proper
+// Message before returning it to application code.
+type ServerApiResponseSingleMessage = {|
+  ...$Exact<ApiResponseSuccess>,
+  -raw_content: string, // deprecated
+  +message: ServerMessage,
+|};
+
+/** Exported for tests only. */
+export const migrateMessage = (
+  message: ServerMessage,
+  identity: Identity,
+  allowEditHistory: boolean,
+): Message => ({
+  ...message,
+  avatar_url: AvatarURL.fromUserOrBotData({
+    rawAvatarUrl: message.avatar_url,
+    email: message.sender_email,
+    userId: message.sender_id,
+    realm: identity.realm,
+  }),
+  reactions: message.reactions.map(reaction => {
+    const { user_id, emoji_name, reaction_type, emoji_code } = reaction;
+    return { user_id, emoji_name, reaction_type, emoji_code };
+  }),
+
+  // Why condition on allowEditHistory? See MessageBase['edit_history'].
+  edit_history: allowEditHistory
+    ? (message.edit_history: $ReadOnlyArray<MessageEdit> | void)
+    : null,
+});
+
+/**
+ * See https://zulip.com/api/get-message
+ *
+ * Defined to assume FL 120+. Don't call unless supported.
+ */
+// TODO(server-5.0): Simplify away "FL 120+" notes (in jsdoc and helpers)
+export default async (
+  auth: Auth,
+  args: {|
+    +message_id: number,
+    +apply_markdown: boolean,
+  |},
+
+  // TODO(#4659): Don't get this from callers.
+  zulipFeatureLevel: number,
+
+  // TODO(#4659): Don't get this from callers?
+  allowEditHistory: boolean,
+): Promise<Message> => {
+  invariant(zulipFeatureLevel >= 120, 'api.getSingleMessage assumes FL 120+');
+
+  const { message_id } = args;
+  const response: ServerApiResponseSingleMessage = await apiGet(auth, `messages/${message_id}`, {
+    apply_markdown: true,
+    client_gravatar: true,
+  });
+  return migrateMessage(response.message, identityOfAuth(auth), allowEditHistory);
+};