MSC4140: support filters on delayed event lookup (#5038)

* MSC4140: support filters on delayed event lookup

Support looking up scheduled/finalised delayed events, and looking up a
single delayed event.

* Add test coverage for delayed event lookup filters

* Prettier

* Use it.each for test loop

* Support multiple delayIds

* Support single or multiple delayIds

As it may be more common to look up a single delayed event than to look
up many of them, support passing a single delayID in the lookup function
instead of needing to pass a single-element array.

spec/unit/matrix-client.spec.ts

@@ -1053,17 +1053,28 @@ describe("MatrixClient", function () {
             );
         });
 
-        it("can look up delayed events", async () => {
+        describe("lookups", () => {
-            httpLookups = [
+            const statuses = [undefined, "scheduled" as const, "finalised" as const];
-                {
+            const delayIds = [undefined, "dxyz", ["d123"], ["d456", "d789"]];
-                    method: "GET",
+            const inputs = statuses.flatMap((status) =>
-                    prefix: unstableMSC4140Prefix,
+                delayIds.map((delayId) => [status, delayId] as [(typeof statuses)[0], (typeof delayIds)[0]]),
-                    path: "/delayed_events",
+            );
-                    data: [],
+            it.each(inputs)("can look up delayed events (status = %s, delayId = %s)", async (status, delayId) => {
-                },
+                httpLookups = [
-            ];
+                    {
+                        method: "GET",
+                        prefix: unstableMSC4140Prefix,
+                        path: "/delayed_events",
+                        expectQueryParams: {
+                            status,
+                            delay_id: delayId,
+                        },
+                        data: [],
+                    },
+                ];
 
-            await client._unstable_getDelayedEvents();
+                await client._unstable_getDelayedEvents(status, delayId);
+            });
         });
 
         it("can update delayed events", async () => {

src/@types/requests.ts

@@ -20,6 +20,7 @@ import { type IEventWithRoomId, type SearchKey } from "./search.ts";
 import { type IRoomEventFilter } from "../filter.ts";
 import { type Direction } from "../models/event-timeline.ts";
 import { type PushRuleAction } from "./PushRules.ts";
+import { type MatrixError } from "../matrix.ts";
 import { type IRoomEvent } from "../sync-accumulator.ts";
 import { type EventType, type RelationType, type RoomType } from "./event.ts";
 
@@ -136,12 +137,22 @@ type DelayedPartialStateEvent = DelayedPartialTimelineEvent & {
 
 type DelayedPartialEvent = DelayedPartialTimelineEvent | DelayedPartialStateEvent;
 
+export type DelayedEventInfoItem = DelayedPartialEvent &
+    SendDelayedEventResponse &
+    SendDelayedEventRequestOpts & {
+        running_since: number;
+    };
+
 export type DelayedEventInfo = {
-    delayed_events: (DelayedPartialEvent &
+    scheduled?: DelayedEventInfoItem[];
-        SendDelayedEventResponse &
+    finalised?: {
-        SendDelayedEventRequestOpts & {
+        delayed_event: DelayedEventInfoItem;
-            running_since: number;
+        outcome: "send" | "cancel";
-        })[];
+        reason: "error" | "action" | "delay";
+        error?: MatrixError["data"];
+        event_id?: string;
+        origin_server_ts?: number;
+    }[];
     next_batch?: string;
 };
 

src/client.ts

@@ -3537,13 +3537,17 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     }
 
     /**
-     * Get all pending delayed events for the calling user.
+     * Get information about delayed events owned by the requesting user.
      *
      * Note: This endpoint is unstable, and can throw an `Error`.
      *   Check progress on [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) for more details.
      */
     // eslint-disable-next-line
-    public async _unstable_getDelayedEvents(fromToken?: string): Promise<DelayedEventInfo> {
+    public async _unstable_getDelayedEvents(
+        status?: "scheduled" | "finalised",
+        delayId?: string | string[],
+        fromToken?: string,
+    ): Promise<DelayedEventInfo> {
         if (!(await this.doesServerSupportUnstableFeature(UNSTABLE_MSC4140_DELAYED_EVENTS))) {
             throw new UnsupportedDelayedEventsEndpointError(
                 "Server does not support the delayed events API",
@@ -3551,7 +3555,11 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
             );
         }
 
-        const queryDict = fromToken ? { from: fromToken } : undefined;
+        const queryDict = {
+            from: fromToken,
+            status,
+            delay_id: delayId,
+        };
         return await this.http.authedRequest(Method.Get, "/delayed_events", queryDict, undefined, {
             prefix: `${ClientPrefix.Unstable}/${UNSTABLE_MSC4140_DELAYED_EVENTS}`,
         });