@jeongsu816/matrix-bot-sdk 0.0.0-stage → 0.8.1

package/src/PantalaimonClient.ts

@@ -0,0 +1,62 @@
+/**
+ * A client specifically designed to interact with Pantalaimon instead of
+ * a Matrix homeserver. The key part of this is managing the access token
+ * and username/password for interacting with Pantalaimon.
+ *
+ * If the storage provider given claims to have an access token for
+ * this client, it will be used even if Pantalaimon considers it invalid.
+ *
+ * Expected usage:
+ * <code>
+ *     const storage = new SimpleFsStorageProvider("storage/bot.json");
+ *     const pantalaimon = new PantalaimonClient("http://localhost:8008", storage);
+ *
+ *     // Note that the credentials will only be used if there is no available access token.
+ *     const client = await pantalaimon.createClientWithCredentials("username", "password");
+ * </code>
+ */
+import { IStorageProvider } from "./storage/IStorageProvider";
+import { MatrixClient } from "./MatrixClient";
+import { MatrixAuth } from "./MatrixAuth";
+
+const ACCESS_TOKEN_STORAGE_KEY = "pantalaimon_access_token";
+
+// TODO: Write a test for this (it's hard because of the many interactions with different parts)
+
+/**
+ * Supporting functions for interacting with a Pantalaimon instance.
+ * @category Encryption
+ */
+export class PantalaimonClient {
+    /**
+     * Creates a new PantalaimonClient class for interacting with Pantalaimon. The storage
+     * provider given will also be used in the client.
+     * @param {string} homeserverUrl The homeserver (Pantalaimon) URL to interact with.
+     * @param {IStorageProvider} storageProvider The storage provider to back the client with.
+     */
+    public constructor(private homeserverUrl: string, private storageProvider: IStorageProvider) {
+        // nothing to do
+    }
+
+    /**
+     * Authenticates and creates the Pantalaimon-capable client. The username and password given
+     * are only used if the storage provider does not reveal an access token.
+     * @param {string} username The username to log in with, if needed.
+     * @param {string} password The password to log in with, if needed.
+     * @returns {Promise<MatrixClient>} Resolves to a MatrixClient ready for interacting with Pantalaimon.
+     */
+    public async createClientWithCredentials(username: string, password: string): Promise<MatrixClient> {
+        const accessToken = await Promise.resolve(this.storageProvider.readValue(ACCESS_TOKEN_STORAGE_KEY));
+        if (accessToken) {
+            return new MatrixClient(this.homeserverUrl, accessToken, this.storageProvider);
+        }
+
+        const auth = new MatrixAuth(this.homeserverUrl);
+        const authedClient = await auth.passwordLogin(username, password);
+
+        await Promise.resolve(this.storageProvider.storeValue(ACCESS_TOKEN_STORAGE_KEY, authedClient.accessToken));
+
+        // We recreate the client to ensure we set it up with the right storage provider.
+        return new MatrixClient(this.homeserverUrl, authedClient.accessToken, this.storageProvider);
+    }
+}

package/src/SynapseAdminApis.ts

@@ -0,0 +1,482 @@
+import { MatrixClient } from "./MatrixClient";
+import { MatrixError } from "./models/MatrixError";
+
+/**
+ * Information about a user on Synapse.
+ * @category Admin APIs
+ */
+export interface SynapseUser {
+    /***
+     * The display name of the user, if set.
+     */
+    displayname?: string;
+
+    /**
+     * External IDs for the user.
+     */
+    external_ids?: {
+        auth_provider: string;
+        external_id: string;
+    }[];
+
+    /**
+     * A set of 3PIDs for the user.
+     */
+    threepids?: {
+        medium: string;
+        address: string;
+    }[];
+
+    /**
+     * The avatar URL (usually MXC URI) for the user, if set.
+     */
+    avatar_url?: string;
+
+    /**
+     * Whether or not the user is a Synapse administrator.
+     */
+    admin?: boolean;
+
+    /**
+     * Whether or not the user is deactivated.
+     */
+    deactivated?: boolean;
+}
+
+/**
+ * Added information to include when updating/creating a user.
+ * @category Admin APIs
+ */
+export interface SynapseUserProperties extends SynapseUser {
+    /**
+     * The password for the user. Leave undefined to leave unchanged.
+     */
+    password?: string;
+}
+
+/**
+ * Information about a user on Synapse.
+ * @category Admin APIs
+ */
+export interface SynapseUserListing {
+    /**
+     * User ID.
+     */
+    name: string;
+
+    /**
+     * Whether or not the user is a guest. 1 is true, 0 is false.
+     */
+    is_guest: number;
+
+    /**
+     * Whether or not the user is an admin. 1 is true, 0 is false.
+     */
+    admin: number;
+
+    /**
+     * Whether or not the user is deactivated. 1 is true, 0 is false.
+     */
+    deactivated: number;
+
+    /**
+     * The type of user, if relevant.
+     */
+    user_type: string | null;
+
+    /**
+     * The hash of the user's password, if relevant.
+     */
+    password_hash: string | null;
+
+    /**
+     * The display name of the user, if set.
+     */
+    displayname: string | null;
+
+    /**
+     * The avatar for the user, if set.
+     */
+    avatar_url: string | null;
+}
+
+/**
+ * A resulting list of users on Synapse.
+ * @category Admin APIs
+ */
+export interface SynapseUserList {
+    /**
+     * A set of users matching the criteria.
+     */
+    users: SynapseUserListing[];
+
+    /**
+     * The token to use to get the next set of users.
+     */
+    next_token: string;
+
+    /**
+     * The total number of users on the Synapse instance.
+     */
+    total: number;
+}
+
+/**
+ * A registration token on Synapse
+ * @category Admin APIs
+ */
+export interface SynapseRegistrationToken {
+    token: string;
+    uses_allowed: null | number;
+    pending: number;
+    completed: number;
+    expiry_time: null | number;
+}
+
+export interface SynapseRegistrationTokenUpdateOptions {
+    /**
+     * The integer number of times the token can be used to complete a registration before it becomes invalid.
+     * If null the token will have an unlimited number of uses.
+     * Default: unlimited uses.
+     */
+    uses_allowed?: number | null;
+
+    /**
+     * The latest time the token is valid. Given as the number of milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch).
+     * If null the token will not expire.
+     * Default: token does not expire.
+     */
+    expiry_time?: number | null;
+
+}
+
+export interface SynapseRegistrationTokenOptions extends SynapseRegistrationTokenUpdateOptions {
+    /**
+     * The registration token. A string of no more than 64 characters that consists only of characters matched by the regex [A-Za-z0-9._~-].
+     * Default: randomly generated.
+     */
+    token?: string;
+
+    /**
+     * The length of the token randomly generated if token is not specified. Must be between 1 and 64 inclusive.
+     * Default: 16.
+     */
+    length?: number;
+}
+
+/**
+ * Information about a room on Synapse.
+ * @category Admin APIs
+ */
+export interface SynapseRoomListing {
+    room_id: string;
+    name: string;
+    canonical_alias: string;
+    joined_members: number;
+    joined_local_members: number;
+    version: string;
+    creator: string;
+    encryption: string; // algorithm
+    federatable: boolean;
+    public: boolean;
+    join_rules: string;
+    guest_access: string;
+    history_visibility: string;
+    state_events: number;
+}
+
+/**
+ * A resulting list of rooms on Synapse.
+ * @category Admin APIs
+ */
+export interface SynapseRoomList {
+    rooms: SynapseRoomListing[];
+
+    offset: string;
+    total_rooms: number;
+    next_batch: string;
+    prev_batch: string;
+}
+
+/**
+ * Available properties on a Synapse room listing to order by.
+ * @category Admin APIs
+ */
+export enum SynapseRoomProperty {
+    Name = "name",
+    CanonicalAlias = "canonical_alias",
+    JoinedMembers = "joined_members",
+    JoinedLocalMembers = "joined_local_members",
+    Version = "version",
+    Creator = "creator",
+    Encryption = "encryption",
+    CanFederate = "federatable",
+    IsPublic = "public",
+    JoinRules = "join_rules",
+    GuestAccess = "guest_access",
+    HistoryVisibility = "history_visibility",
+    NumStateEvents = "state_events",
+}
+
+export interface SynapseListUserOptions {
+    /**
+     * Filters to only return users with user IDs that contain this value. This parameter is ignored when using the name parameter.
+     */
+    user_id?: string;
+
+    /**
+     * Filters to only return users with user ID localparts or displaynames that contain this value.
+     */
+    name?: string;
+
+    /**
+     * If false will exclude guest users. Defaults to true to include guest users.
+     */
+    guests?: boolean;
+
+    /**
+     * If true will include deactivated users. Defaults to false to exclude deactivated users.
+     */
+    deactivated?: boolean;
+
+    /**
+     * The method by which to sort the returned list of users. If the ordered field has duplicates, the
+     * second order is always by ascending name, which guarantees a stable ordering.
+     * **Caution**: The database only has indexes on the columns `name` and `creation_ts`. This means
+     * that if a different sort order is used, it can cause a large load on the database.
+     */
+    order_by?: "name" | "is_guest" | "admin" | "user_type" | "deactivated" | "shadow_banned" | "displayname" | "avatar_url" | "creation_ts";
+
+    /**
+     * The number of results to return at a time.
+     */
+    limit?: number;
+}
+
+/**
+ * Access to various administrative APIs specifically available in Synapse.
+ * @category Admin APIs
+ */
+export class SynapseAdminApis {
+    constructor(private client: MatrixClient) {
+    }
+
+    /**
+     * Get information about a user. The client making the request must be an admin user.
+     * @param {string} userId The user ID to check.
+     * @returns {Promise<SynapseUser>} The resulting Synapse user record
+     */
+    public async getUser(userId: string): Promise<SynapseUser> {
+        return this.client.doRequest(
+            "GET", "/_synapse/admin/v2/users/" + encodeURIComponent(userId),
+        );
+    }
+
+    /**
+     * Create or update a given user on a Synapse server. The
+     * client making the request must be an admin user.
+     * @param {string} userId The user ID to check.
+     * @param {SynapseUserProperties} opts Options to set when creating or updating the user.
+     * @returns {Promise<SynapseUser>} The resulting Synapse user record
+     */
+    public async upsertUser(userId: string, opts: SynapseUserProperties = {}): Promise<SynapseUser> {
+        return this.client.doRequest(
+            "PUT", "/_synapse/admin/v2/users/" + encodeURIComponent(userId), undefined, opts,
+        );
+    }
+
+    /**
+     * Get a list of users registered with Synapse, optionally filtered by some criteria. The
+     * client making the request must be an admin user.
+     * @param {string} from The token to continue listing users from.
+     * @param {number} limit The maximum number of users to request.
+     * @param {string} name Optional localpart or display name filter for results.
+     * @param {boolean} guests Whether or not to include guest accounts. Default true.
+     * @param {boolean} deactivated Whether or not to include deactivated accounts. Default false.
+     * @returns {Promise<SynapseUserList>} A batch of user results.
+     */
+    public async listUsers(from?: string, limit?: number, name?: string, guests = true, deactivated = false): Promise<SynapseUserList> {
+        const qs = { guests, deactivated };
+        if (from) qs['from'] = from;
+        if (limit) qs['limit'] = limit;
+        if (name) qs['name'] = name;
+        return this.client.doRequest("GET", "/_synapse/admin/v2/users", qs);
+    }
+
+    /**
+     * Get a list of all users registered with Synapse, optionally filtered by some criteria. The
+     * client making the request must be an admin user.
+     *
+     * This method returns an async generator that can be used to filter results.
+     * @param options Options to pass to the user listing function
+     * @example
+     * for await (const user of synapseAdminApis.listAllUsers()) {
+     *    if (user.name === '@alice:example.com') {
+     *       return user;
+     *    }
+     * }
+     */
+    public async* listAllUsers(options: SynapseListUserOptions = {}): AsyncGenerator<SynapseUserListing> {
+        let from: string | undefined = undefined;
+        let response: SynapseUserList;
+        do {
+            const qs = {
+                ...options,
+                ...(from && { from }),
+            };
+            response = await this.client.doRequest("GET", "/_synapse/admin/v2/users", qs);
+            for (const user of response.users) {
+                yield user;
+            }
+            from = response.next_token;
+        } while (from);
+    }
+
+    /**
+     * Determines if the given user is a Synapse server administrator for this homeserver. The
+     * client making the request must be an admin user themselves (check with `isSelfAdmin`)
+     * @param {string} userId The user ID to check.
+     * @returns {Promise<boolean>} Resolves to true if the user is an admin, false otherwise.
+     * Throws if there's an error.
+     */
+    public async isAdmin(userId: string): Promise<boolean> {
+        const response = await this.client.doRequest("GET", `/_synapse/admin/v1/users/${encodeURIComponent(userId)}/admin`);
+        return response['admin'] || false;
+    }
+
+    /**
+     * Determines if the current user is an admin for the Synapse homeserver.
+     * @returns {Promise<boolean>} Resolve to true if the user is an admin, false otherwise.
+     * Throws if there's an error.
+     */
+    public async isSelfAdmin(): Promise<boolean> {
+        try {
+            return await this.isAdmin(await this.client.getUserId());
+        } catch (err) {
+            if (err instanceof MatrixError && err.errcode === 'M_FORBIDDEN') {
+                return false;
+            }
+            throw err;
+        }
+    }
+
+    /**
+     * Lists the rooms on the server.
+     * @param {string} searchTerm A term to search for in the room names
+     * @param {string} from A previous batch token to search from
+     * @param {number} limit The maximum number of rooms to return
+     * @param {SynapseRoomProperty} orderBy A property of rooms to order by
+     * @param {boolean} reverseOrder True to reverse the orderBy direction.
+     * @returns {Promise<SynapseRoomList>} Resolves to the server's rooms, ordered and filtered.
+     */
+    public async listRooms(searchTerm?: string, from?: string, limit?: number, orderBy?: SynapseRoomProperty, reverseOrder = false): Promise<SynapseRoomList> {
+        const params = {};
+        if (from) params['from'] = from;
+        if (limit) params['limit'] = limit;
+        if (searchTerm) params['search_term'] = searchTerm;
+        if (orderBy) params['order_by'] = orderBy;
+        if (reverseOrder) {
+            params['dir'] = 'b';
+        } else {
+            params['dir'] = 'f';
+        }
+        return this.client.doRequest("GET", "/_synapse/admin/v1/rooms", params);
+    }
+
+    /**
+     * Gets a list of state events in a room.
+     * @param {string} roomId The room ID to get state for.
+     * @returns {Promise<any[]>} Resolves to the room's state events.
+     */
+    public async getRoomState(roomId: string): Promise<any[]> {
+        const r = await this.client.doRequest("GET", `/_synapse/admin/v1/rooms/${encodeURIComponent(roomId)}/state`);
+        return r?.['state'] || [];
+    }
+
+    /**
+     * Deletes a room from the server, purging all record of it.
+     * @param {string} roomId The room to delete.
+     * @returns {Promise} Resolves when complete.
+     */
+    public async deleteRoom(roomId: string): Promise<void> {
+        return this.client.doRequest("DELETE", `/_synapse/admin/v2/rooms/${encodeURIComponent(roomId)}`, {}, { purge: true });
+    }
+
+    /**
+     * Gets the status of all active deletion tasks, and all those completed in the last 24h, for the given room_id.
+     * @param {string} roomId The room ID to get deletion state for.
+     * @returns {Promise<any[]>} Resolves to the room's deletion status results.
+     */
+    public async getDeleteRoomState(roomId: string): Promise<any[]> {
+        const r = await this.client.doRequest("GET", `/_synapse/admin/v2/rooms/${encodeURIComponent(roomId)}/delete_status`);
+        return r?.['results'] || [];
+    }
+
+    /**
+     * List all registration tokens on the homeserver.
+     * @param valid If true, only valid tokens are returned.
+     * If false, only tokens that have expired or have had all uses exhausted are returned.
+     * If omitted, all tokens are returned regardless of validity.
+
+     * @returns An array of registration tokens.
+     */
+    public async listRegistrationTokens(valid?: boolean): Promise<SynapseRegistrationToken[]> {
+        const res = await this.client.doRequest("GET", `/_synapse/admin/v1/registration_tokens`, { valid });
+        return res.registration_tokens;
+    }
+
+    /**
+     * Get details about a single token.
+     * @param token The token to fetch.
+     * @returns A registration tokens, or null if not found.
+     */
+    public async getRegistrationToken(token: string): Promise<SynapseRegistrationToken | null> {
+        try {
+            return await this.client.doRequest("GET", `/_synapse/admin/v1/registration_tokens/${encodeURIComponent(token)}`);
+        } catch (e) {
+            if (e?.statusCode === 404) {
+                return null;
+            }
+            throw e;
+        }
+    }
+
+    /**
+     * Create a new registration token.
+     * @param options Options to pass to the request.
+     * @returns The newly created token.
+     */
+    public async createRegistrationToken(options: SynapseRegistrationTokenOptions = {}): Promise<SynapseRegistrationToken> {
+        return this.client.doRequest("POST", `/_synapse/admin/v1/registration_tokens/new`, undefined, options);
+    }
+
+    /**
+     * Update an existing registration token.
+     * @param token The token to update.
+     * @param options Options to pass to the request.
+     * @returns The newly created token.
+     */
+    public async updateRegistrationToken(token: string, options: SynapseRegistrationTokenUpdateOptions): Promise<SynapseRegistrationToken> {
+        return this.client.doRequest("PUT", `/_synapse/admin/v1/registration_tokens/${encodeURIComponent(token)}`, undefined, options);
+    }
+
+    /**
+     * Delete a registration token
+     * @param token The token to update.
+     * @returns A promise that resolves upon success.
+     */
+    public async deleteRegistrationToken(token: string): Promise<void> {
+        return this.client.doRequest("DELETE", `/_synapse/admin/v1/registration_tokens/${encodeURIComponent(token)}`, undefined, {});
+    }
+
+    /**
+     * Grants another user the highest power available to a local user who is in the room.
+     * If the user is not in the room, and it is not publicly joinable, then invite the user.
+     * @param roomId The room to make the user admin in.
+     * @param userId The user to make admin in the room. If undefined, it uses the authenticated user.
+     * @returns Resolves when complete.
+     */
+    public async makeRoomAdmin(roomId: string, userId?: string): Promise<void> {
+        return this.client.doRequest("POST", `/_synapse/admin/v1/rooms/${encodeURIComponent(roomId)}/make_room_admin`, {}, { user_id: userId });
+    }
+}

package/src/SynchronousMatrixClient.ts

@@ -0,0 +1,129 @@
+import { MatrixClient } from "./MatrixClient";
+
+/**
+ * A MatrixClient class that handles events in sync for the /sync loop, instead
+ * of trying to push its way through the /sync loop as fast as possible. It is
+ * intended that the consumer extend this class and override the onWhatever()
+ * functions it needs. All of the onWhatever() functions have a default behaviour
+ * of doing nothing.
+ */
+export abstract class SynchronousMatrixClient extends MatrixClient {
+    /**
+     * Creates a new SynchronousMatrixClient. Note that this accepts a MatrixClient, though
+     * much of the class's properties are not brought over. Always convert your MatrixClient
+     * instance to a SynchronousMatrixClient as soon as possible to avoid diversion in which
+     * properties are proxied over.
+     * @param {MatrixClient} baseClient The client to wrap.
+     */
+    protected constructor(baseClient: MatrixClient) {
+        super(baseClient.homeserverUrl, baseClient.accessToken, baseClient.storageProvider);
+    }
+
+    private async handleEvent(emitType: string, arg1: any, arg2: any): Promise<any> {
+        if (emitType === 'account_data') await this.onAccountData(arg1);
+        if (emitType === 'room.account_data') await this.onRoomAccountData(arg1, arg2);
+        if (emitType === 'room.leave') await this.onRoomLeave(arg1, arg2);
+        if (emitType === 'room.invite') await this.onRoomInvite(arg1, arg2);
+        if (emitType === 'room.join') await this.onRoomJoin(arg1, arg2);
+        if (emitType === 'room.archived') await this.onRoomArchived(arg1, arg2);
+        if (emitType === 'room.upgraded') await this.onRoomUpgraded(arg1, arg2);
+        if (emitType === 'room.message') await this.onRoomMessage(arg1, arg2);
+        if (emitType === 'room.event') await this.onRoomEvent(arg1, arg2);
+
+        // Still emit though for easier support of plugins.
+        this.emit(emitType, arg1, arg2);
+    }
+
+    protected startSyncInternal(): Promise<any> {
+        return this.startSync(this.handleEvent.bind(this));
+    }
+
+    /**
+     * Handles the `account_data` event raised by the client.
+     * @param {any} event The account data event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onAccountData(event: any): Promise<any> {
+        return;
+    }
+
+    /**
+     * Handles the `room.account_data` event raised by the client.
+     * @param {string} roomId The Room ID the account data applies to.
+     * @param {any} event The room account data event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onRoomAccountData(roomId: string, event: any): Promise<any> {
+        return;
+    }
+
+    /**
+     * Handles the `room.leave` event raised by the client.
+     * @param {string} roomId The Room ID the event happened in.
+     * @param {any} event The event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onRoomLeave(roomId: string, event: any): Promise<any> {
+        return;
+    }
+
+    /**
+     * Handles the `room.invite` event raised by the client.
+     * @param {string} roomId The Room ID the event happened in.
+     * @param {any} event The event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onRoomInvite(roomId: string, event: any): Promise<any> {
+        return;
+    }
+
+    /**
+     * Handles the `room.join` event raised by the client.
+     * @param {string} roomId The Room ID the event happened in.
+     * @param {any} event The event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onRoomJoin(roomId: string, event: any): Promise<any> {
+        return;
+    }
+
+    /**
+     * Handles the `room.message` event raised by the client.
+     * @param {string} roomId The Room ID the event happened in.
+     * @param {any} event The event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onRoomMessage(roomId: string, event: any): Promise<any> {
+        return;
+    }
+
+    /**
+     * Handles the `room.archived` event raised by the client.
+     * @param {string} roomId The Room ID the event happened in.
+     * @param {any} event The event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onRoomArchived(roomId: string, event: any): Promise<any> {
+        return;
+    }
+
+    /**
+     * Handles the `room.upgraded` event raised by the client.
+     * @param {string} roomId The Room ID the event happened in.
+     * @param {any} event The event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onRoomUpgraded(roomId: string, event: any): Promise<any> {
+        return;
+    }
+
+    /**
+     * Handles the `room.event` event raised by the client.
+     * @param {string} roomId The Room ID the event happened in.
+     * @param {any} event The event.
+     * @returns {Promise<any>} Resolves when complete.
+     */
+    protected onRoomEvent(roomId: string, event: any): Promise<any> {
+        return;
+    }
+}