Update MultiInviter to take an options object (#30541)

* Move `inviteUsersToRoom` to `RoomUpgrade`

This method is only used in one place, uses only public methods, and is
undocumented. Let's move it to the place where it is used, to simplify the API
for `RoomInvite`.

* Simplify `inviteUsersToRoom`

`inviteMultipleToRoom` basically never throws, so this code was effectively
unreachable.

* Update MultiInviter to take an options object

I'm going to add another option, so an options object is going to be more
flexible.

* Jump through the coverage hoop with another test

src/utils/MultiInviter.ts

@@ -40,6 +40,12 @@ const USER_ALREADY_JOINED = "IO.ELEMENT.ALREADY_JOINED";
 const USER_ALREADY_INVITED = "IO.ELEMENT.ALREADY_INVITED";
 const USER_BANNED = "IO.ELEMENT.BANNED";
 
+/** Options interface for {@link MultiInviter} */
+export interface MultiInviterOptions {
+    /** Optional callback, fired after each invite */
+    progressCallback?: () => void;
+}
+
 /**
  * Invites multiple addresses to a room, handling rate limiting from the server
  */
@@ -53,12 +59,12 @@ export default class MultiInviter {
     /**
      * @param matrixClient the client of the logged in user
      * @param {string} roomId The ID of the room to invite to
-     * @param {function} progressCallback optional callback, fired after each invite.
+     * @param options Options object
      */
     public constructor(
         private readonly matrixClient: MatrixClient,
         private roomId: string,
-        private readonly progressCallback?: () => void,
+        private readonly options: MultiInviterOptions = {},
     ) {}
 
     public get fatal(): boolean {
@@ -69,9 +75,11 @@ export default class MultiInviter {
      * Invite users to this room. This may only be called once per
      * instance of the class.
      *
+     * Any failures are returned via the {@link CompletionStates} in the result.
+     *
      * @param {array} addresses Array of addresses to invite
      * @param {string} reason Reason for inviting (optional)
-     * @returns {Promise} Resolved when all invitations in the queue are complete
+     * @returns {Promise} Resolved when all invitations in the queue are complete.
      */
     public async invite(addresses: string[], reason?: string): Promise<CompletionStates> {
         if (this.addresses.length > 0) {
@@ -230,7 +238,7 @@ export default class MultiInviter {
                     delete this.errors[address];
 
                     resolve();
-                    this.progressCallback?.();
+                    this.options.progressCallback?.();
                 })
                 .catch((err) => {
                     logger.error(err);

src/utils/RoomUpgrade.ts

@@ -6,11 +6,11 @@ SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Com
 Please see LICENSE files in the repository root for full details.
 */
 
-import { type Room, EventType, ClientEvent, type MatrixClient } from "matrix-js-sdk/src/matrix";
+import { ClientEvent, EventType, type MatrixClient, type Room } from "matrix-js-sdk/src/matrix";
 import { KnownMembership } from "matrix-js-sdk/src/types";
 import { logger } from "matrix-js-sdk/src/logger";
 
-import { inviteUsersToRoom } from "../RoomInvite";
+import { inviteMultipleToRoom, showAnyInviteErrors } from "../RoomInvite";
 import Modal, { type IHandle } from "../Modal";
 import { _t } from "../languageHandler";
 import ErrorDialog from "../components/views/dialogs/ErrorDialog";
@@ -145,3 +145,14 @@ export async function upgradeRoom(
     spinnerModal?.close();
     return newRoomId;
 }
+
+async function inviteUsersToRoom(
+    client: MatrixClient,
+    roomId: string,
+    userIds: string[],
+    progressCallback?: () => void,
+): Promise<void> {
+    const result = await inviteMultipleToRoom(client, roomId, userIds, { progressCallback });
+    const room = client.getRoom(roomId)!;
+    showAnyInviteErrors(result.states, room, result.inviter);
+}