Distinguish room state and timeline events (#116)

* Distinguish room state and timeline events

This is an implementation of an update to MSC2762, which provides a new action for informing widgets of changes to room state.

* Try to clarify comment?

Author: robintown

src/ClientWidgetApi.ts

@@ -196,6 +196,7 @@ export abstract class WidgetDriver {
      * the client will return all the events.
      * @param eventType The event type to be read.
      * @param msgtype The msgtype of the events to be read, if applicable/defined.
+     * @param stateKey The state key of the events to be read, if applicable/defined.
      * @param limit The maximum number of events to retrieve per room. Will be zero to denote "as many
      * as possible".
      * @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs
@@ -204,6 +205,7 @@ export abstract class WidgetDriver {
      * Otherwise, the event ID at which only subsequent events will be returned, as many as specified
      * in "limit".
      * @returns {Promise<IRoomEvent[]>} Resolves to the room events, or an empty array.
+     * @deprecated Clients are advised to implement {@link WidgetDriver.readRoomTimeline} instead.
      */
     public readRoomEvents(
         eventType: string,
@@ -229,6 +231,7 @@ export abstract class WidgetDriver {
      * @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs
      * to look within, possibly containing Symbols.AnyRoom to denote all known rooms.
      * @returns {Promise<IRoomEvent[]>} Resolves to the state events, or an empty array.
+     * @deprecated Clients are advised to implement {@link WidgetDriver.readRoomTimeline} instead.
      */
     public readStateEvents(
         eventType: string,
@@ -239,6 +242,53 @@ export abstract class WidgetDriver {
         return Promise.resolve([]);
     }
 
+    /**
+     * Reads all events of the given type, and optionally `msgtype` (if applicable/defined),
+     * the user has access to. The widget API will have already verified that the widget is
+     * capable of receiving the events. Less events than the limit are allowed to be returned,
+     * but not more.
+     * @param roomId The ID of the room to look within.
+     * @param eventType The event type to be read.
+     * @param msgtype The msgtype of the events to be read, if applicable/defined.
+     * @param stateKey The state key of the events to be read, if applicable/defined.
+     * @param limit The maximum number of events to retrieve. Will be zero to denote "as many as
+     * possible".
+     * @param since When null, retrieves the number of events specified by the "limit" parameter.
+     * Otherwise, the event ID at which only subsequent events will be returned, as many as specified
+     * in "limit".
+     * @returns {Promise<IRoomEvent[]>} Resolves to the room events, or an empty array.
+     */
+    public readRoomTimeline(
+        roomId: string,
+        eventType: string,
+        msgtype: string | undefined,
+        stateKey: string | undefined,
+        limit: number,
+        since: string | undefined,
+    ): Promise<IRoomEvent[]> {
+        // For backward compatibility we try the deprecated methods, in case
+        // they're implemented
+        if (stateKey === undefined) return this.readRoomEvents(eventType, msgtype, limit, [roomId], since);
+        else return this.readStateEvents(eventType, stateKey, limit, [roomId]);
+    }
+
+    /**
+     * Reads the current values of all matching room state entries.
+     * @param roomId The ID of the room.
+     * @param eventType The event type of the entries to be read.
+     * @param stateKey The state key of the entry to be read. If undefined,
+     * all room state entries with a matching event type should be returned.
+     * @returns {Promise<IRoomEvent[]>} Resolves to the events representing the
+     * current values of the room state entries.
+     */
+    public readRoomState(
+        roomId: string,
+        eventType: string,
+        stateKey: string | undefined,
+    ): Promise<IRoomEvent[]> {
+        return Promise.resolve([]);
+    }
+
     /**
      * Reads all events that are related to a given event. The widget API will
      * have already verified that the widget is capable of receiving the event,
@@ -360,6 +410,15 @@ export abstract class WidgetDriver {
         throw new Error("Download file is not implemented");
     }
 
+    /**
+     * Gets the IDs of all joined or invited rooms currently known to the
+     * client.
+     * @returns The room IDs.
+     */
+    public getKnownRooms(): string[] {
+        throw new Error("Querying known rooms is not implemented");
+    }
+
     /**
      * Expresses an error thrown by this driver in a format compatible with the Widget API.
      * @param error The error to handle.

src/driver/WidgetDriver.ts

@@ -60,6 +60,7 @@ export type * from "./interfaces/TurnServerActions";
 export type * from "./interfaces/ReadRelationsAction";
 export type * from "./interfaces/GetMediaConfigAction";
 export * from "./interfaces/UpdateDelayedEventAction";
+export type * from "./interfaces/UpdateStateAction";
 export type * from "./interfaces/UploadFileAction";
 export type * from "./interfaces/DownloadFileAction";
 export type * from "./interfaces/ThemeChangeAction";

src/index.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright 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, IWidgetApiRequestData } from "./IWidgetApiRequest";
+import { WidgetApiToWidgetAction } from "./WidgetApiAction";
+import { IWidgetApiResponseData } from "./IWidgetApiResponse";
+import { IRoomEvent } from "./IRoomEvent";
+
+export interface IUpdateStateToWidgetRequestData extends IWidgetApiRequestData {
+    state: IRoomEvent[];
+}
+
+export interface IUpdateStateToWidgetActionRequest extends IWidgetApiRequest {
+    action: WidgetApiToWidgetAction.UpdateState;
+    data: IUpdateStateToWidgetRequestData;
+}
+
+export interface IUpdateStateToWidgetResponseData extends IWidgetApiResponseData {
+    // nothing
+}
+
+export interface IUpdateStateToWidgetActionResponse extends IUpdateStateToWidgetActionRequest {
+    response: IUpdateStateToWidgetResponseData;
+}

src/interfaces/UpdateStateAction.ts

@@ -28,6 +28,7 @@ export enum WidgetApiToWidgetAction {
     ButtonClicked = "button_clicked",
     SendEvent = "send_event",
     SendToDevice = "send_to_device",
+    UpdateState = "update_state",
     UpdateTurnServers = "update_turn_servers",
 }