userSelectors: Add getDisplayEmailForUser

Add function that gives users real email address, if known for
displaying in the UI.  Returns null if the user isn't able 
to see this users real email address.

Add tests for above function.

Author: daleshort

src/api/modelTypes.js

@@ -177,8 +177,14 @@ export type User = {|
   // Current to feature level (FL) 121.
 
   +user_id: UserId,
-  +delivery_email?: string,
+
+  // Currently `delivery_email` is always `string` if present.  A planned
+  // future API may make it sometimes `null`, to explicitly indicate that no
+  // delivery email for this user is visible to us:
+  //   https://chat.zulip.org/#narrow/stream/378-api-design/topic/email.20address.20visibility/near/1296132
+  +delivery_email?: string | null,
   +email: string,
+
   +full_name: string,
 
   // We expect ISO 8601; that's in the doc's example response.
@@ -263,7 +269,7 @@ export type CrossRealmBot = {|
   // Current to feature level (FL) 121.
 
   +user_id: UserId,
-  +delivery_email?: string,
+  +delivery_email?: string | null,
   +email: string,
   +full_name: string,
 

src/users/__tests__/userSelectors-test.js

@@ -6,10 +6,12 @@ import {
   getUserForId,
   getUserIsActive,
   getCustomProfileFieldsForUser,
+  getDisplayEmailForUser,
 } from '../userSelectors';
 import * as eg from '../../__tests__/lib/exampleData';
 import { CustomProfileFieldType } from '../../api/modelTypes';
 import { randInt, randString } from '../../utils/misc';
+import { EmailAddressVisibility } from '../../api/permissionsTypes';
 
 describe('getAllUsersByEmail', () => {
   test('return users mapped by their email', () => {
@@ -290,3 +292,45 @@ describe('getCustomProfileFieldsForUser', () => {
     ).toMatchObject([{ fieldId: 1 }, { fieldId: 3 }]);
   });
 });
+
+describe('getDisplayEmailForUser', () => {
+  const mkUser = fields => ({ ...eg.otherUser, ...fields });
+
+  test('visibility is admin, no delivery_email', () => {
+    const realm = eg.realmState({ emailAddressVisibility: EmailAddressVisibility.Admins });
+    // eslint-disable-next-line no-unused-vars
+    const { delivery_email, ...user } = eg.otherUser;
+    expect(getDisplayEmailForUser(realm, user)).toBeNull();
+  });
+
+  test('email visibility is everyone, no delivery_email', () => {
+    const realm = eg.realmState({ emailAddressVisibility: EmailAddressVisibility.Everyone });
+    // eslint-disable-next-line no-unused-vars
+    const { delivery_email, ...user } = eg.otherUser;
+    expect(getDisplayEmailForUser(realm, user)).toEqual(eg.otherUser.email);
+  });
+
+  test('email visibility is everyone, delivery_email is null', () => {
+    const realm = eg.realmState({ emailAddressVisibility: EmailAddressVisibility.Everyone });
+    const user = mkUser({ delivery_email: null });
+    expect(getDisplayEmailForUser(realm, user)).toBeNull();
+  });
+
+  test('email visibility is everyone, delivery_email is set', () => {
+    const realm = eg.realmState({ emailAddressVisibility: EmailAddressVisibility.Everyone });
+    const user = mkUser({
+      delivery_email: '[email protected]',
+      email: '[email protected]',
+    });
+    expect(getDisplayEmailForUser(realm, user)).toEqual('[email protected]');
+  });
+
+  test('email visibility is admins, delivery_email is set', () => {
+    const realm = eg.realmState({ emailAddressVisibility: EmailAddressVisibility.Admins });
+    const user = mkUser({
+      delivery_email: '[email protected]',
+      email: '[email protected]',
+    });
+    expect(getDisplayEmailForUser(realm, user)).toEqual('[email protected]');
+  });
+});

src/users/userSelectors.js

@@ -13,6 +13,7 @@ import type { RealmState } from '../reduxTypes';
 import { getUsers, getCrossRealmBots, getNonActiveUsers } from '../directSelectors';
 import * as logging from '../utils/logging';
 import { ensureUnreachable } from '../generics';
+import { EmailAddressVisibility } from '../api/permissionsTypes';
 
 /**
  * All users in this Zulip org (aka realm).
@@ -308,3 +309,21 @@ export function getCustomProfileFieldsForUser(
   }
   return fields;
 }
+
+/**
+ * The given user's real email address, if known, for displaying in the UI.
+ *
+ * Null if our user isn't able to see this user's real email address.
+ */
+export function getDisplayEmailForUser(realm: RealmState, user: UserOrBot): string | null {
+  if (user.delivery_email !== undefined) {
+    return user.delivery_email;
+  } else if (realm.emailAddressVisibility === EmailAddressVisibility.Everyone) {
+    // On future servers, we expect this case will never happen: we'll always include
+    // a delivery_email when you have access, including when the visibility is Everyone
+    // https://github.com/zulip/zulip-mobile/pull/5515#discussion_r997731727
+    return user.email;
+  } else {
+    return null;
+  }
+}