Give MatrixClient.invite an options param (#4919)

Author: richvdh

spec/integ/matrix-client-methods.spec.ts

@@ -267,6 +267,59 @@ describe("MatrixClient", function () {
         });
     });
 
+    describe("invite", function () {
+        it("should send request to /invite", async () => {
+            const roomId = "!roomId:server";
+            const userId = "@user:server";
+
+            httpBackend
+                .when("POST", `/rooms/${encodeURIComponent(roomId)}/invite`)
+                .check((request) => {
+                    expect(request.data).toEqual({ user_id: userId });
+                })
+                .respond(200, {});
+
+            const prom = client.invite(roomId, userId);
+            await httpBackend.flushAllExpected();
+            await prom;
+            httpBackend.verifyNoOutstandingExpectation();
+        });
+
+        it("accepts a stringy reason argument", async () => {
+            const roomId = "!roomId:server";
+            const userId = "@user:server";
+
+            httpBackend
+                .when("POST", `/rooms/${encodeURIComponent(roomId)}/invite`)
+                .check((request) => {
+                    expect(request.data).toEqual({ user_id: userId, reason: "testreason" });
+                })
+                .respond(200, {});
+
+            const prom = client.invite(roomId, userId, "testreason");
+            await httpBackend.flushAllExpected();
+            await prom;
+            httpBackend.verifyNoOutstandingExpectation();
+        });
+
+        it("accepts an options object with a reason", async () => {
+            const roomId = "!roomId:server";
+            const userId = "@user:server";
+
+            httpBackend
+                .when("POST", `/rooms/${encodeURIComponent(roomId)}/invite`)
+                .check((request) => {
+                    expect(request.data).toEqual({ user_id: userId, reason: "testreason" });
+                })
+                .respond(200, {});
+
+            const prom = client.invite(roomId, userId, { reason: "testreason" });
+            await httpBackend.flushAllExpected();
+            await prom;
+            httpBackend.verifyNoOutstandingExpectation();
+        });
+    });
+
     describe("knockRoom", function () {
         const roomId = "!some-room-id:example.org";
         const reason = "some reason";

src/@types/requests.ts

@@ -43,6 +43,14 @@ export interface IJoinRoomOpts {
     viaServers?: string[];
 }
 
+/** Options object for {@link MatrixClient.invite}. */
+export interface InviteOpts {
+    /**
+     * The reason for the invite.
+     */
+    reason?: string;
+}
+
 export interface KnockRoomOpts {
     /**
      * The reason for the knock.

src/client.ts

@@ -115,6 +115,7 @@ import {
     type IGuestAccessOpts,
     type IJoinRoomOpts,
     type INotificationsResponse,
+    type InviteOpts,
     type IPaginateOpts,
     type IPresenceOpts,
     type IRedactOpts,
@@ -3755,12 +3756,19 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     }
 
     /**
-     * @param reason - Optional.
-     * @returns Promise which resolves: `{}` an empty object.
-     * @returns Rejects: with an error response.
+     * Send an invite to the given user to join the given room.
+     *
+     * @param roomId - The ID of the room to which the user should be invited.
+     * @param userId - The ID of the user that should be invited.
+     * @param opts - Optional reason object. For backwards compatibility, a string is also accepted, and will be interpreted as a reason.
+     *
+     * @returns An empty object.
      */
-    public invite(roomId: string, userId: string, reason?: string): Promise<EmptyObject> {
-        return this.membershipChange(roomId, userId, KnownMembership.Invite, reason);
+    public invite(roomId: string, userId: string, opts: InviteOpts | string = {}): Promise<EmptyObject> {
+        if (typeof opts != "object") {
+            opts = { reason: opts };
+        }
+        return this.membershipChange(roomId, userId, KnownMembership.Invite, opts.reason);
     }
 
     /**