Skip to content

Commit 28ddd40

Browse files
committed
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.
1 parent bbff7c1 commit 28ddd40

File tree

6 files changed

+609
-56
lines changed

6 files changed

+609
-56
lines changed

src/ClientWidgetApi.ts

Lines changed: 230 additions & 44 deletions
Large diffs are not rendered by default.

src/driver/WidgetDriver.ts

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,7 @@ export abstract class WidgetDriver {
196196
* the client will return all the events.
197197
* @param eventType The event type to be read.
198198
* @param msgtype The msgtype of the events to be read, if applicable/defined.
199+
* @param stateKey The state key of the events to be read, if applicable/defined.
199200
* @param limit The maximum number of events to retrieve per room. Will be zero to denote "as many
200201
* as possible".
201202
* @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs
@@ -204,6 +205,7 @@ export abstract class WidgetDriver {
204205
* Otherwise, the event ID at which only subsequent events will be returned, as many as specified
205206
* in "limit".
206207
* @returns {Promise<IRoomEvent[]>} Resolves to the room events, or an empty array.
208+
* @deprecated Clients are advised to implement {@link WidgetDriver.readRoomTimeline} instead.
207209
*/
208210
public readRoomEvents(
209211
eventType: string,
@@ -229,6 +231,7 @@ export abstract class WidgetDriver {
229231
* @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs
230232
* to look within, possibly containing Symbols.AnyRoom to denote all known rooms.
231233
* @returns {Promise<IRoomEvent[]>} Resolves to the state events, or an empty array.
234+
* @deprecated Clients are advised to implement {@link WidgetDriver.readRoomTimeline} instead.
232235
*/
233236
public readStateEvents(
234237
eventType: string,
@@ -239,6 +242,53 @@ export abstract class WidgetDriver {
239242
return Promise.resolve([]);
240243
}
241244

245+
/**
246+
* Reads all events of the given type, and optionally `msgtype` (if applicable/defined),
247+
* the user has access to. The widget API will have already verified that the widget is
248+
* capable of receiving the events. Less events than the limit are allowed to be returned,
249+
* but not more.
250+
* @param roomId The ID of the room to look within.
251+
* @param eventType The event type to be read.
252+
* @param msgtype The msgtype of the events to be read, if applicable/defined.
253+
* @param stateKey The state key of the events to be read, if applicable/defined.
254+
* @param limit The maximum number of events to retrieve. Will be zero to denote "as many as
255+
* possible".
256+
* @param since When null, retrieves the number of events specified by the "limit" parameter.
257+
* Otherwise, the event ID at which only subsequent events will be returned, as many as specified
258+
* in "limit".
259+
* @returns {Promise<IRoomEvent[]>} Resolves to the room events, or an empty array.
260+
*/
261+
public readRoomTimeline(
262+
roomId: string,
263+
eventType: string,
264+
msgtype: string | undefined,
265+
stateKey: string | undefined,
266+
limit: number,
267+
since: string | undefined,
268+
): Promise<IRoomEvent[]> {
269+
// For backward compatibility we try the deprecated methods, in case
270+
// they're implemented
271+
if (stateKey === undefined) return this.readRoomEvents(eventType, msgtype, limit, [roomId], since);
272+
else return this.readStateEvents(eventType, stateKey, limit, [roomId]);
273+
}
274+
275+
/**
276+
* Reads the current values of all matching room state entries.
277+
* @param roomId The ID of the room.
278+
* @param eventType The event type of the entries to be read.
279+
* @param stateKey The state key of the entry to be read. If undefined,
280+
* all room state entries with a matching event type should be returned.
281+
* @returns {Promise<IRoomEvent[]>} Resolves to the events representing the
282+
* current values of the room state entries.
283+
*/
284+
public readRoomState(
285+
roomId: string,
286+
eventType: string,
287+
stateKey: string | undefined,
288+
): Promise<IRoomEvent[]> {
289+
return Promise.resolve([]);
290+
}
291+
242292
/**
243293
* Reads all events that are related to a given event. The widget API will
244294
* have already verified that the widget is capable of receiving the event,
@@ -360,6 +410,15 @@ export abstract class WidgetDriver {
360410
throw new Error("Download file is not implemented");
361411
}
362412

413+
/**
414+
* Gets the IDs of all joined or invited rooms currently known to the
415+
* client.
416+
* @returns The room IDs.
417+
*/
418+
public getKnownRooms(): string[] {
419+
throw new Error("Querying known rooms is not implemented");
420+
}
421+
363422
/**
364423
* Expresses an error thrown by this driver in a format compatible with the Widget API.
365424
* @param error The error to handle.

src/index.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ export * from "./interfaces/TurnServerActions";
6060
export * from "./interfaces/ReadRelationsAction";
6161
export * from "./interfaces/GetMediaConfigAction";
6262
export * from "./interfaces/UpdateDelayedEventAction";
63+
export * from "./interfaces/UpdateStateAction";
6364
export * from "./interfaces/UploadFileAction";
6465
export * from "./interfaces/DownloadFileAction";
6566

src/interfaces/UpdateStateAction.ts

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
/*
2+
* Copyright 2024 The Matrix.org Foundation C.I.C.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
import { IWidgetApiRequest, IWidgetApiRequestData } from "./IWidgetApiRequest";
18+
import { WidgetApiToWidgetAction } from "./WidgetApiAction";
19+
import { IWidgetApiResponseData } from "./IWidgetApiResponse";
20+
import { IRoomEvent } from "./IRoomEvent";
21+
22+
export interface IUpdateStateToWidgetRequestData extends IWidgetApiRequestData {
23+
state: IRoomEvent[];
24+
}
25+
26+
export interface IUpdateStateToWidgetActionRequest extends IWidgetApiRequest {
27+
action: WidgetApiToWidgetAction.UpdateState;
28+
data: IUpdateStateToWidgetRequestData;
29+
}
30+
31+
export interface IUpdateStateToWidgetResponseData extends IWidgetApiResponseData {
32+
// nothing
33+
}
34+
35+
export interface IUpdateStateToWidgetActionResponse extends IUpdateStateToWidgetActionRequest {
36+
response: IUpdateStateToWidgetResponseData;
37+
}

src/interfaces/WidgetApiAction.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ export enum WidgetApiToWidgetAction {
2626
ButtonClicked = "button_clicked",
2727
SendEvent = "send_event",
2828
SendToDevice = "send_to_device",
29+
UpdateState = "update_state",
2930
UpdateTurnServers = "update_turn_servers",
3031
}
3132

0 commit comments

Comments
 (0)