Support sending delayed events (Futures) / MSC4157

src/ClientWidgetApi.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 - 2021 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 2024 The Matrix.org Foundation C.I.C.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@ import { IContentLoadedActionRequest } from "./interfaces/ContentLoadedAction";
 import { WidgetApiFromWidgetAction, WidgetApiToWidgetAction } from "./interfaces/WidgetApiAction";
 import { IWidgetApiErrorResponseData } from "./interfaces/IWidgetApiErrorResponse";
 import { Capability, MatrixCapabilities } from "./interfaces/Capabilities";
-import { IOpenIDUpdate, ISendEventDetails, WidgetDriver } from "./driver/WidgetDriver";
+import { IOpenIDUpdate, ISendEventDetails, ISendFutureDetails, WidgetDriver } from "./driver/WidgetDriver";
 import {
     ICapabilitiesActionResponseData,
     INotifyCapabilitiesActionRequestData,
@@ -94,6 +94,10 @@ import {
     IUploadFileActionFromWidgetActionRequest,
     IUploadFileActionFromWidgetResponseData,
 } from "./interfaces/UploadFileAction";
+import {
+    ISendFutureFromWidgetActionRequest,
+    ISendFutureFromWidgetResponseData,
+} from "./interfaces/SendFutureAction";
 
 /**
  * API handler for the client side of widgets. This raises events
@@ -477,10 +481,9 @@ export class ClientWidgetApi extends EventEmitter {
             });
         }
 
-        const isState = request.data.state_key !== null && request.data.state_key !== undefined;
         let sendEventPromise: Promise<ISendEventDetails>;
-        if (isState) {
-            if (!this.canSendStateEvent(request.data.type, request.data.state_key!)) {
+        if (request.data.state_key != null) {
+            if (!this.canSendStateEvent(request.data.type, request.data.state_key)) {
                 return this.transport.reply<IWidgetApiErrorResponseData>(request, {
                     error: {message: "Cannot send state events of this type"},
                 });
@@ -522,6 +525,63 @@ export class ClientWidgetApi extends EventEmitter {
         });
     }
 
+    private handleSendFuture(request: ISendFutureFromWidgetActionRequest) {
+        if (!request.data.type) {
+            return this.transport.reply<IWidgetApiErrorResponseData>(request, {
+                error: {message: "Invalid request - missing event type"},
+            });
+        }
+
+        let sendFuturePromise: Promise<ISendFutureDetails>;
+        if (request.data.state_key != null) {
+            if (!this.canSendStateEvent(request.data.type, request.data.state_key)) {
+                return this.transport.reply<IWidgetApiErrorResponseData>(request, {
+                    error: {message: "Cannot send state futures of this type"},
+                });
+            }
+
+            sendFuturePromise = this.driver.sendFuture(
+                request.data.future_group_id ?? null,
+                request.data.future_timeout ?? null,
+                request.data.type,
+                request.data.content || {},
+                request.data.state_key,
+                request.data.room_id,
+            );
+        } else {
+            const content = request.data.content as { msgtype?: string } || {};
+            const msgtype = content['msgtype'];
+            if (!this.canSendRoomEvent(request.data.type, msgtype)) {
+                return this.transport.reply<IWidgetApiErrorResponseData>(request, {
+                    error: {message: "Cannot send room futures of this type"},
+                });
+            }
+
+            sendFuturePromise = this.driver.sendFuture(
+                request.data.future_group_id ?? null,
+                request.data.future_timeout ?? null,
+                request.data.type,
+                content,
+                null, // not sending a state event
+                request.data.room_id,
+            );
+        }
+
+        sendFuturePromise.then(sentFuture => {
+            return this.transport.reply<ISendFutureFromWidgetResponseData>(request, {
+                future_group_id: sentFuture.futureGroupId,
+                send_token: sentFuture.sendToken,
+                cancel_token: sentFuture.cancelToken,
+                refresh_token: sentFuture.refreshToken,
+            });
+        }).catch(e => {
+            console.error("error sending future: ", e);
+            return this.transport.reply<IWidgetApiErrorResponseData>(request, {
+                error: {message: "Error sending future"},
+            });
+        });
+    }
+
     private async handleSendToDevice(request: ISendToDeviceFromWidgetActionRequest): Promise<void> {
         if (!request.data.type) {
             await this.transport.reply<IWidgetApiErrorResponseData>(request, {
@@ -770,6 +830,8 @@ export class ClientWidgetApi extends EventEmitter {
                     return this.replyVersions(<ISupportedVersionsActionRequest>ev.detail);
                 case WidgetApiFromWidgetAction.SendEvent:
                     return this.handleSendEvent(<ISendEventFromWidgetActionRequest>ev.detail);
+                case WidgetApiFromWidgetAction.SendFuture:
+                    return this.handleSendFuture(<ISendFutureFromWidgetActionRequest>ev.detail);
                 case WidgetApiFromWidgetAction.SendToDevice:
                     return this.handleSendToDevice(<ISendToDeviceFromWidgetActionRequest>ev.detail);
                 case WidgetApiFromWidgetAction.GetOpenIDCredentials:

src/WidgetApi.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 - 2021 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 2024 The Matrix.org Foundation C.I.C.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -54,6 +54,11 @@ import {
 } from "./interfaces/ModalWidgetActions";
 import { ISetModalButtonEnabledActionRequestData } from "./interfaces/SetModalButtonEnabledAction";
 import { ISendEventFromWidgetRequestData, ISendEventFromWidgetResponseData } from "./interfaces/SendEventAction";
+import {
+    ISendFutureFromWidgetRequestData,
+    ISendFutureFromWidgetResponseData,
+    ISendFutureOptions,
+} from "./interfaces/SendFutureAction";
 import {
     ISendToDeviceFromWidgetRequestData,
     ISendToDeviceFromWidgetResponseData,
@@ -419,6 +424,37 @@ export class WidgetApi extends EventEmitter {
         );
     }
 
+    /**
+     * @experimental This currently relies on an unstable MSC (MSC4140).
+     */
+    public sendRoomFuture(
+        futureOpts: ISendFutureOptions,
+        eventType: string,
+        content: unknown,
+        roomId?: string,
+    ): Promise<ISendFutureFromWidgetResponseData> {
+        return this.transport.send<ISendFutureFromWidgetRequestData, ISendFutureFromWidgetResponseData>(
+            WidgetApiFromWidgetAction.SendFuture,
+            {type: eventType, content, room_id: roomId, ...futureOpts},
+        );
+    }
+
+    /**
+     * @experimental This currently relies on an unstable MSC (MSC4140).
+     */
+    public sendStateFuture(
+        futureOpts: ISendFutureOptions,
+        eventType: string,
+        stateKey: string,
+        content: unknown,
+        roomId?: string,
+    ): Promise<ISendFutureFromWidgetResponseData> {
+        return this.transport.send<ISendFutureFromWidgetRequestData, ISendFutureFromWidgetResponseData>(
+            WidgetApiFromWidgetAction.SendFuture,
+            {type: eventType, content, state_key: stateKey, room_id: roomId, ...futureOpts},
+        );
+    }
+
     /**
      * Sends a to-device event.
      * @param {string} eventType The type of events being sent.

src/driver/WidgetDriver.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 - 2021 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 2024 The Matrix.org Foundation C.I.C.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,6 +29,14 @@ export interface ISendEventDetails {
     eventId: string;
 }
 
+export interface ISendFutureDetails {
+    roomId: string;
+    futureGroupId: string;
+    sendToken: string;
+    cancelToken: string;
+    refreshToken?: string;
+}
+
 export interface IOpenIDUpdate {
     state: OpenIDRequestState;
     token?: IOpenIDCredentials;
@@ -103,6 +111,34 @@ export abstract class WidgetDriver {
         return Promise.reject(new Error("Failed to override function"));
     }
 
+    /**
+     * Sends a future into a room. If `roomId` is falsy, the client should send the future
+     * into the room the user is currently looking at. The widget API will have already
+     * verified that the widget is capable of sending the future's event to that room.
+     * @param {string|null} futureGroupId The ID of the group the future belongs to,
+     * or null if it will be put in a new group.
+     * @param {number|null} futureTimeout The future's timeout, or null for an action future.
+     * @param {string} eventType The event type of the event to be sent by the future.
+     * @param {*} content The content for the event to be sent by the future.
+     * @param {string|null} stateKey The state key if the event to be sent by the future is
+     * a state event, otherwise null. May be an empty string.
+     * @param {string|null} roomId The room ID to send the future to. If falsy, the room the
+     * user is currently looking at.
+     * @returns {Promise<ISendFutureDetails>} Resolves when the future has been sent with
+     * details of that future.
+     * @throws Rejected when the future could not be sent.
+     */
+    public sendFuture(
+        futureGroupId: string | null,
+        futureTimeout: number | null,
+        eventType: string,
+        content: unknown,
+        stateKey: string | null = null,
+        roomId: string | null = null,
+    ): Promise<ISendFutureDetails> {
+        return Promise.reject(new Error("Failed to override function"));
+    }
+
     /**
      * Sends a to-device event. The widget API will have already verified that the widget
      * is capable of sending the event.

src/interfaces/SendFutureAction.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2020 - 2024 The Matrix.org Foundation C.I.C.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { IWidgetApiRequest } from "./IWidgetApiRequest";
+import { IWidgetApiResponseData } from "./IWidgetApiResponse";
+import { ISendEventFromWidgetRequestData } from "./SendEventAction";
+import { WidgetApiFromWidgetAction } from "./WidgetApiAction";
+
+export interface ISendFutureOptions {
+    future_group_id?: string; // eslint-disable-line camelcase
+    future_timeout?: number; // eslint-disable-line camelcase
+}
+
+export interface ISendFutureFromWidgetRequestData extends ISendEventFromWidgetRequestData, ISendFutureOptions {}
+
+export interface ISendFutureFromWidgetActionRequest extends IWidgetApiRequest {
+    action: WidgetApiFromWidgetAction.SendFuture;
+    data: ISendFutureFromWidgetRequestData;
+}
+
+export interface ISendFutureFromWidgetResponseData extends IWidgetApiResponseData {
+    future_group_id: string; // eslint-disable-line camelcase
+    send_token: string; // eslint-disable-line camelcase
+    cancel_token: string; // eslint-disable-line camelcase
+    refresh_token?: string; // eslint-disable-line camelcase
+}

src/interfaces/WidgetApiAction.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 2024 The Matrix.org Foundation C.I.C.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -39,6 +39,7 @@ export enum WidgetApiFromWidgetAction {
     OpenModalWidget = "open_modal",
     SetModalButtonEnabled = "set_button_enabled",
     SendEvent = "send_event",
+    SendFuture = "send_future",
     SendToDevice = "send_to_device",
     WatchTurnServers = "watch_turn_servers",
     UnwatchTurnServers = "unwatch_turn_servers",