Add typed options for createRoom

examples/encryption_bot.ts

@@ -8,6 +8,8 @@ import {
     MatrixClient,
     MessageEvent,
     RichConsoleLogger,
+    RoomPreset,
+    RoomVisibility,
     RustSdkCryptoStorageProvider,
     SimpleFsStorageProvider,
 } from "../src";
@@ -34,7 +36,7 @@ const worksImage = fs.readFileSync("./examples/static/it-works.png");
 const client = new MatrixClient(homeserverUrl, accessToken, storage, crypto);
 
 (async function() {
-    let encryptedRoomId: string;
+    let encryptedRoomId: string|undefined = undefined;
     const joinedRooms = await client.getJoinedRooms();
     await client.crypto.prepare(joinedRooms); // init crypto because we're doing things before the client is started
     for (const roomId of joinedRooms) {
@@ -47,8 +49,8 @@ const client = new MatrixClient(homeserverUrl, accessToken, storage, crypto);
         encryptedRoomId = await client.createRoom({
             invite: [dmTarget],
             is_direct: true,
-            visibility: "private",
-            preset: "trusted_private_chat",
+            visibility: RoomVisibility.Private,
+            preset: RoomPreset.TrustedPrivateChat,
             initial_state: [
                 { type: "m.room.encryption", state_key: "", content: { algorithm: EncryptionAlgorithm.MegolmV1AesSha2 } },
                 { type: "m.room.guest_access", state_key: "", content: { guest_access: "can_join" } },

src/DMs.ts

@@ -1,6 +1,7 @@
 import { MatrixClient } from "./MatrixClient";
 import { EncryptionAlgorithm } from "./models/Crypto";
 import { LogService } from "./logging/LogService";
+import { RoomPreset } from "./models/Room";
 
 /**
  * Handles DM (direct messages) matching between users. Note that bots which
@@ -132,7 +133,7 @@ export class DMs {
             roomId = await this.client.createRoom({
                 invite: [userId],
                 is_direct: true,
-                preset: "trusted_private_chat",
+                preset: RoomPreset.TrustedPrivateChat,
                 initial_state: hasKeys ? [{
                     type: "m.room.encryption",
                     state_key: "",

src/MatrixClient.ts

@@ -45,6 +45,7 @@ import { IWhoAmI } from "./models/Account";
 import { RustSdkCryptoStorageProvider } from "./storage/RustSdkCryptoStorageProvider";
 import { DMs } from "./DMs";
 import { ServerVersions } from "./models/ServerVersions";
+import { RoomCreateOptions, RoomPreset } from "./models/Room";
 
 const SYNC_BACKOFF_MIN_MS = 5000;
 const SYNC_BACKOFF_MAX_MS = 15000;
@@ -1354,15 +1355,14 @@ export class MatrixClient extends EventEmitter {
     }
 
     /**
-     * Creates a room. This does not break out the various options for creating a room
-     * due to the large number of possibilities. See the /createRoom endpoint in the
-     * spec for more information on what to provide for `properties`. Note that creating
+     * Creates a room. See the RoomCreateOptions interface
+     * for more information on what to provide for `properties`. Note that creating
      * a room may cause the bot/appservice to raise a join event.
-     * @param {any} properties the properties of the room. See the spec for more information
+     * @param {any} properties the properties of the room.
      * @returns {Promise<string>} resolves to the room ID that represents the room
      */
     @timedMatrixClientFunctionCall()
-    public createRoom(properties: any = {}): Promise<string> {
+    public createRoom(properties: RoomCreateOptions = {}): Promise<string> {
         return this.doRequest("POST", "/_matrix/client/v3/createRoom", null, properties).then(response => {
             return response['room_id'];
         });
@@ -1713,10 +1713,10 @@ export class MatrixClient extends EventEmitter {
      */
     @timedMatrixClientFunctionCall()
     public async createSpace(opts: SpaceCreateOptions): Promise<Space> {
-        const roomCreateOpts = {
+        const roomCreateOpts: RoomCreateOptions = {
             name: opts.name,
             topic: opts.topic || "",
-            preset: opts.isPublic ? 'public_chat' : 'private_chat',
+            preset: opts.isPublic ? RoomPreset.PublicChat : RoomPreset.PrivateChat,
             room_alias_name: opts.localpart,
             initial_state: [
                 {
@@ -1726,7 +1726,7 @@ export class MatrixClient extends EventEmitter {
                         history_visibility: opts.isPublic ? 'world_readable' : 'shared',
                     },
                 },
-            ] as unknown[],
+            ],
             creation_content: {
                 type: "m.space",
             },

src/index.ts

@@ -54,6 +54,7 @@ export * from "./models/Account";
 export * from "./models/PowerLevelAction";
 export * from "./models/ServerVersions";
 export * from "./models/MatrixError";
+export * from "./models/Room";
 
 // Unstable models
 export * from "./models/unstable/MediaInfo";

src/models/Room.ts

@@ -0,0 +1,135 @@
+import { PowerLevelsEventContent } from "./events/PowerLevelsEvent";
+
+export enum RoomPreset {
+	/**
+	 * Sets:
+	 * - join_rules to `invite`
+	 * - history_visibility to `shared` 
+	 * - guest_access to `can_join`
+	 */
+	PrivateChat = "private_chat",
+	/**
+	 * Sets:
+	 * - join_rules to `invite`
+	 * - history_visibility to `shared` 
+	 * - guest_access to `can_join`
+	 * - All invitees are given the same power level as the room creator.
+	 */
+	TrustedPrivateChat = "trusted_private_chat",
+	/**
+	 * Sets:
+	 * - join_rules to `public`
+	 * - history_visibility to `shared` 
+	 * - guest_access to `forbidden`
+	 */
+	PublicChat = "public_chat",
+}
+
+export enum RoomVisibility {
+	/**
+	 * This visibility indicates that the room will be shown in the published room list. 
+	 */
+	Public = "public",
+	/**
+	 * This visibility indicates that the room will not be included in published room list.
+	 */
+	Private = "private",
+}
+
+export interface RoomCreateOptions {
+	/**
+	 * Extra keys, such as m.federate, to be added to the content of the m.room.create event.
+	 * The server will overwrite the following keys: `creator`, `room_version`.
+	 * Future versions of the specification may allow the server to overwrite other keys.
+	 */
+	creation_content?: {
+		"m.federate"?: boolean,
+		[key: string]: unknown
+	},
+	/**
+	 * A list of state events to set in the new room.
+	 * This allows the user to override the default state events set in the new room.
+	 * The expected format of the state events are an object with `type`, `state_key` and `content` keys set.
+	 * Takes precedence over events set by `preset`, but gets overridden by `name` and `topic` keys.
+	 */
+	initial_state?: {
+		/**
+		 * The content of the event.
+		 */
+		content: any,
+		/**
+		 * The state_key of the state event. Defaults to an empty string.
+		 */
+		state_key?: string,
+		/**
+		 * The type of event to send.
+		 */
+		type: string
+	}[],
+	/**
+	 * A list of user IDs to invite to the room. This will tell the server to invite everyone in the list to the newly created room.
+	 */
+	invite?: string[],
+	invite_3pid?: {
+		/**
+		 * The invitee’s third party identifier.
+		 */
+		address: string;
+		/**
+		 * An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.
+		 */
+		id_access_token: string;
+		/**
+		 * The hostname+port of the identity server which should be used for third party identifier lookups.
+		 */
+		id_server: string;
+		/**
+		 * The kind of address being passed in the address field, for example `email`.
+		 */
+		medium: string;
+	}[],
+	/**
+	 * This flag makes the server set the `is_direct` flag on the `m.room.member` events sent to the users in `invite` and `invite_3pid`.
+	 */
+	is_direct?: boolean;
+	/**
+	 * If this is included, an `m.room.name` event will be sent into the room to indicate the name of the room.
+	 */
+	name?: string;
+	/**
+	 * The power level content to override in the default power level event.
+	 * This object is applied on top of the generated `m.room.power_levels` event content prior to it being sent to the room.
+	 * Defaults to overriding nothing.
+	 */
+	power_level_content_override?: PowerLevelsEventContent,
+	/**
+	 * Convenience parameter for setting various default state events based on a preset.
+	 * 
+	 * If unspecified, the server should use the `visibility` to determine which preset to use.
+	 * A visbility of `public` equates to a preset of `public_chat` and `private` visibility equates to a preset of `private_chat`.
+	 */
+	// Note: Allowing string values for backwards compatibility
+	preset?: RoomPreset|"public_chat"|"private_chat"|"trusted_private_chat",
+	/**
+	 * The desired room alias local part.
+	 * If this is included, a room alias will be created and mapped to the newly created room.
+	 * The alias will belong on the same homeserver which created the room.
+	 */
+	room_alias_name?: string,
+	/**
+	 * The room version to set for the room.
+	 * If not provided, the homeserver is to use its configured default.
+	 * If provided, the homeserver will return a `400` error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not support the room version.
+	 */
+	room_version?: string,
+	/**
+	 * If this is included, an `m.room.topic` event will be sent into the room to indicate the topic for the room.
+	 */
+	topic?: string,
+	/**
+	 * Sets the visibility of the room
+	 * Rooms default to private visibility if this key is not included.
+	 */
+	// Note: Allowing string values for backwards compatibility
+	visibility?: RoomVisibility|"public"|"private",
+}

test/MatrixClientTest.ts

@@ -18,6 +18,7 @@ import {
     OTKs,
     PowerLevelAction,
     redactObjectForLogging,
+    RoomCreateOptions,
     RoomDirectoryLookupResponse,
     RoomEvent,
     RustSdkCryptoStorageProvider,
@@ -2808,8 +2809,8 @@ describe('MatrixClient', () => {
             const { client, http } = createTestClient();
 
             const roomId = "!something:example.org";
-            const properties = {
-                hello: "world",
+            const properties: RoomCreateOptions = {
+                name: "hello world",
                 preset: "public_chat",
             };