From a3d7bc7798005d3d084a40a68e93270f0df664fe Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Fri, 11 Jul 2025 17:21:57 +0100
Subject: [PATCH] Give `MatrixClient.invite` an options param

---
 spec/integ/matrix-client-methods.spec.ts | 53 ++++++++++++++++++++++++
 src/@types/requests.ts                   |  8 ++++
 src/client.ts                            | 18 +++++---
 3 files changed, 74 insertions(+), 5 deletions(-)

diff --git a/spec/integ/matrix-client-methods.spec.ts b/spec/integ/matrix-client-methods.spec.ts
index f4e207b508..0ab10be43b 100644
--- a/spec/integ/matrix-client-methods.spec.ts
+++ b/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";
diff --git a/src/@types/requests.ts b/src/@types/requests.ts
index f933012247..a618f6d936 100644
--- a/src/@types/requests.ts
+++ b/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.
diff --git a/src/client.ts b/src/client.ts
index 6ee06d4294..d2de367e2d 100644
--- a/src/client.ts
+++ b/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);
     }
 
     /**