feat: add a redirect field to asynchronous request responses

src/KeyringClient.test.ts

@@ -227,6 +227,7 @@ describe('KeyringClient', () => {
       };
       const expectedResponse: KeyringResponse = {
         pending: true,
+        redirect: null,
       };
 
       mockSender.send.mockResolvedValue(expectedResponse);

src/api.ts

@@ -8,6 +8,7 @@ import {
   record,
   string,
   union,
+  nullable,
 } from 'superstruct';
 
 import { JsonRpcRequestStruct } from './JsonRpcRequest';
@@ -115,10 +116,37 @@ export type KeyringAccountData = Infer<typeof KeyringAccountDataStruct>;
 
 export const KeyringResponseStruct = union([
   object({
+    /**
+     * Pending flag.
+     *
+     * Setting the pending flag to true indicates that the request will be
+     * handled asynchronously. The keyring must be called with `approveRequest`
+     * or `rejectRequest` to resolve the request.
+     */
     pending: literal(true),
+
+    /**
+     * Redirect URL.
+     *
+     * If present in the response, MetaMask will display a confirmation dialog
+     * with a link to the redirect URL. The user can choose to follow the link
+     * or cancel the request.
+     */
+    redirect: nullable(string()),
   }),
   object({
+    /**
+     * Pending flag.
+     *
+     * Setting the pending flag to false indicates that the request will be
+     * handled synchronously. The keyring must return the result of the
+     * request execution.
+     */
     pending: literal(false),
+
+    /**
+     * Request result.
+     */
     result: JsonStruct,
   }),
 ]);
@@ -129,6 +157,11 @@ export const KeyringResponseStruct = union([
  * Keyring implementations must return a response with `pending: true` if the
  * request will be handled asynchronously. Otherwise, the response must contain
  * the result of the request and `pending: false`.
+ *
+ * In the asynchronous case, the keyring can return a redirect URL to be shown
+ * to the user. The user can choose to follow the link or cancel the request.
+ * The main use case for this is to redirect the user to a third-party service
+ * to approve the request.
  */
 export type KeyringResponse = Infer<typeof KeyringResponseStruct>;