flow: Annotate exported functions that return the result of a fetch.

To bring us closer to annotating all our exports, for zulip#4907.

Most of these use a new `FixmeUntypedFetchResult` type; see its
jsdoc.

`apiFetch` can be unexported; so, do that, removing the need for an
annotation [1].

`savePushToken` and `forgetPushToken` get `Promise<mixed>` because
we don't actually inspect the returned result at all [2].

`checkCompatibility` gets `Promise<{ status: number, ... }>` because
we'll always be looking at the response status [3].

[1] zulip#4927 (comment)
[2] zulip#4927 (comment)
[3] zulip#4927 (comment)

src/api/apiFetch.js

@@ -2,6 +2,7 @@
 import * as Sentry from '@sentry/react-native';
 import type { UrlParams } from '../utils/url';
 import type { Auth } from './transportTypes';
+import type { FixmeUntypedFetchResult } from './apiTypes';
 import { getAuthHeaders } from './transport';
 import { encodeParamsForUrl } from '../utils/url';
 import userAgent from '../utils/userAgent';
@@ -36,7 +37,7 @@ export const getFetchParams = <P: $Diff<$Exact<RequestOptions>, {| headers: mixe
   };
 };
 
-export const apiFetch = async (
+const apiFetch = async (
   auth: Auth,
   route: string,
   params: $Diff<$Exact<RequestOptions>, {| headers: mixed |}>,
@@ -48,7 +49,7 @@ export const apiCall = async (
   route: string,
   params: $Diff<$Exact<RequestOptions>, {| headers: mixed |}>,
   isSilent: boolean = false,
-): Promise<empty> => {
+): Promise<FixmeUntypedFetchResult> => {
   try {
     networkActivityStart(isSilent);
 
@@ -67,7 +68,7 @@ export const apiCall = async (
     }
 
     const result = interpretApiResponse(response.status, json);
-    /* $FlowFixMe[incompatible-type] We let the caller pretend this data
+    /* $FlowFixMe[incompatible-return] We let the caller pretend this data
          is whatever it wants it to be. */
     return result;
   } catch (errorIllTyped) {
@@ -97,7 +98,7 @@ export const apiGet = async (
   route: string,
   params: UrlParams = {},
   isSilent: boolean = false,
-) =>
+): Promise<FixmeUntypedFetchResult> =>
   apiCall(
     auth,
     `${route}?${encodeParamsForUrl(params)}`,
@@ -107,37 +108,61 @@ export const apiGet = async (
     isSilent,
   );
 
-export const apiPost = async (auth: Auth, route: string, params: UrlParams = {}) =>
+export const apiPost = async (
+  auth: Auth,
+  route: string,
+  params: UrlParams = {},
+): Promise<FixmeUntypedFetchResult> =>
   apiCall(auth, route, {
     method: 'post',
     body: encodeParamsForUrl(params),
   });
 
-export const apiFile = async (auth: Auth, route: string, body: FormData) =>
+export const apiFile = async (
+  auth: Auth,
+  route: string,
+  body: FormData,
+): Promise<FixmeUntypedFetchResult> =>
   apiCall(auth, route, {
     method: 'post',
     body,
   });
 
-export const apiPut = async (auth: Auth, route: string, params: UrlParams = {}) =>
+export const apiPut = async (
+  auth: Auth,
+  route: string,
+  params: UrlParams = {},
+): Promise<FixmeUntypedFetchResult> =>
   apiCall(auth, route, {
     method: 'put',
     body: encodeParamsForUrl(params),
   });
 
-export const apiDelete = async (auth: Auth, route: string, params: UrlParams = {}) =>
+export const apiDelete = async (
+  auth: Auth,
+  route: string,
+  params: UrlParams = {},
+): Promise<FixmeUntypedFetchResult> =>
   apiCall(auth, route, {
     method: 'delete',
     body: encodeParamsForUrl(params),
   });
 
-export const apiPatch = async (auth: Auth, route: string, params: UrlParams = {}) =>
+export const apiPatch = async (
+  auth: Auth,
+  route: string,
+  params: UrlParams = {},
+): Promise<FixmeUntypedFetchResult> =>
   apiCall(auth, route, {
     method: 'patch',
     body: encodeParamsForUrl(params),
   });
 
-export const apiHead = async (auth: Auth, route: string, params: UrlParams = {}) =>
+export const apiHead = async (
+  auth: Auth,
+  route: string,
+  params: UrlParams = {},
+): Promise<FixmeUntypedFetchResult> =>
   apiCall(auth, `${route}?${encodeParamsForUrl(params)}`, {
     method: 'head',
   });

src/api/apiTypes.js

@@ -1,5 +1,14 @@
 /* @flow strict-local */
 
+/**
+ * Temporary placeholder for the resolve type of a `fetch`.
+ *
+ * The `empty` is bogus, as we saw in 4ef0f061e. As mentioned there, it's
+ * because React Native defeats type-checking on `fetch` calls. We expect
+ * that'll be fixed in RN v0.65, with facebook/react-native@6651b7c59.
+ */
+export type FixmeUntypedFetchResult = empty;
+
 export type * from './transportTypes';
 export type * from './modelTypes';
 export type * from './eventTypes';

src/api/checkCompatibility.js

@@ -3,7 +3,7 @@ import userAgent from '../utils/userAgent';
 
 // check with server if current mobile app is compatible with latest backend
 // compatibility fails only if server responds with 400 (but not with 200 or 404)
-export default () =>
+export default (): Promise<{ status: number, ... }> =>
   fetch('https://zulip.com/compatibility', {
     headers: {
       'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8',

src/api/notifications/forgetPushToken.js

@@ -7,7 +7,7 @@ import { apiDelete } from '../apiFetch';
  *
  * @param mobileOS - Choose the server-side API intended for iOS or Android clients.
  */
-export default (auth: Auth, mobileOS: 'ios' | 'android', token: string) => {
+export default (auth: Auth, mobileOS: 'ios' | 'android', token: string): Promise<mixed> => {
   const routeName = mobileOS === 'android' ? 'android_gcm_reg_id' : 'apns_device_token';
   return apiDelete(auth, `users/me/${routeName}`, { token });
 };

src/api/notifications/savePushToken.js

@@ -7,7 +7,7 @@ import { apiPost } from '../apiFetch';
  *
  * @param mobileOS - Choose the server-side API intended for iOS or Android clients.
  */
-export default async (auth: Auth, mobileOS: 'ios' | 'android', token: string) => {
+export default async (auth: Auth, mobileOS: 'ios' | 'android', token: string): Promise<mixed> => {
   const routeName = mobileOS === 'android' ? 'android_gcm_reg_id' : 'apns_device_token';
   const extraParams = mobileOS === 'android' ? {} : { appid: 'org.zulip.Zulip' };
   return apiPost(auth, `users/me/${routeName}`, {