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

package/src/models/events/RoomTopicEvent.ts

@@ -0,0 +1,27 @@
+import { StateEvent } from "./RoomEvent";
+
+/**
+ * The content definition for m.room.topic events
+ * @category Matrix event contents
+ * @see RoomTopicEvent
+ */
+export interface RoomTopicEventContent {
+    topic: string;
+}
+
+/**
+ * Represents an m.room.topic state event
+ * @category Matrix events
+ */
+export class RoomTopicEvent extends StateEvent<RoomTopicEventContent> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * The topic of the room.
+     */
+    public get topic(): string {
+        return this.content.topic;
+    }
+}

package/src/models/events/SpaceChildEvent.ts

@@ -0,0 +1,74 @@
+import { StateEvent } from "./RoomEvent";
+
+/**
+ * The content definition for m.space.child events
+ * @category Matrix event contents
+ * @see SpaceChildEvent
+ */
+export interface SpaceChildEventContent {
+    /**
+     * The servers the client should provide to the server when trying to join the room.
+     * When not provided or empty, the child is considered not part of the space.
+     */
+    via: string[];
+
+    /**
+     * A short string to differentiate the rendering order of entities.
+     * @see validateSpaceOrderString
+     */
+    order?: string;
+
+    /**
+     * Whether or not the entity is intended to be a suggested entity.
+     */
+    suggested?: boolean;
+}
+
+/**
+ * Represents an m.space.child state event
+ * @category Matrix events
+ */
+export class SpaceChildEvent extends StateEvent<SpaceChildEventContent> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * The room ID of the space or room this child represents.
+     */
+    public get entityRoomId(): string {
+        return this.stateKey;
+    }
+
+    /**
+     * Whether or not this child is "active" or valid. Inactive children are
+     * not considered part of a space.
+     */
+    public get isActiveChild(): boolean {
+        return !!this.viaServers?.length;
+    }
+
+    /**
+     * The servers the client should provide to the homeserver when trying to
+     * join the entity (room). May be empty or falsey to denote the child is
+     * inactive.
+     */
+    public get viaServers(): string[] {
+        return this.content.via;
+    }
+
+    /**
+     * An optional short string to differentiate the rendering order of entities.
+     * @see validateSpaceOrderString
+     */
+    public get order(): string {
+        return this.content.order;
+    }
+
+    /**
+     * Whether or not the child is a suggested entity for users to join.
+     */
+    public get suggested(): boolean {
+        return this.content.suggested ?? false;
+    }
+}

package/src/models/events/_MissingEvents.md

@@ -0,0 +1,35 @@
+## Missing event types
+
+These are the event types that need definitions.
+
+### r0.6.0
+
+* `m.call.invite`
+* `m.call.candidates`
+* `m.call.answer`
+* `m.call.hangup`
+* `m.typing`
+* `m.receipt`
+* `m.fully_read`
+* `m.key.verification.request`
+* `m.key.verification.start`
+* `m.key.verification.cancel`
+* `m.key.verification.start` (SAS)
+* `m.key.verification.accept`
+* `m.key.verification.key`
+* `m.key.verification.mac`
+* `m.room_key`
+* `m.room_key_request`
+* `m.forwarded_room_key`
+* `m.dummy`
+* `m.room.history_visibility`
+* `m.push_rules`
+* `m.room.third_party_invite`
+* `m.room.guest_access`
+* `m.tag`
+* `m.direct`
+* `m.ignored_user_list`
+* `m.sticker`
+* `m.room.server_acl`
+* `m.room.tombstone`
+* `m.room.message` of type `m.server_notice`

package/src/models/events/converter.ts

@@ -0,0 +1,47 @@
+import { MembershipEvent } from "./MembershipEvent";
+import { RoomEvent, StateEvent } from "./RoomEvent";
+import {
+    AudioMessageEventContent,
+    ImageMessageEventContent,
+    LocationMessageEventContent,
+    MessageEvent,
+    MessageEventContent,
+    TextualMessageEventContent,
+    VideoMessageEventContent,
+} from "./MessageEvent";
+
+/**
+ * Wraps a room event into a more suitable container.
+ * @param {any} event The event object to wrap.
+ * @returns {RoomEvent<any>} An instance of the most suitable container for the event.
+ * @category Matrix events
+ */
+export function wrapRoomEvent(event: any): RoomEvent<any> {
+    if (!event) return null;
+
+    if (typeof (event['state_key']) === 'string') {
+        if (event['type'] === 'm.room.member') {
+            return new MembershipEvent(event);
+        } else {
+            return new StateEvent<any>(event);
+        }
+    } else if (event['type'] === 'm.room.message') {
+        const content = event['content'];
+        const msgtype = content ? content['msgtype'] : null;
+        if (msgtype === "m.text" || msgtype === "m.notice" || msgtype === "m.emote") {
+            return new MessageEvent<TextualMessageEventContent>(event);
+        } else if (msgtype === "m.audio") {
+            return new MessageEvent<AudioMessageEventContent>(event);
+        } else if (msgtype === "m.video") {
+            return new MessageEvent<VideoMessageEventContent>(event);
+        } else if (msgtype === "m.image") {
+            return new MessageEvent<ImageMessageEventContent>(event);
+        } else if (msgtype === "m.location") {
+            return new MessageEvent<LocationMessageEventContent>(event);
+        } else {
+            return new MessageEvent<MessageEventContent>(event);
+        }
+    } else {
+        return new RoomEvent<any>(event);
+    }
+}

package/src/models/unstable/MediaInfo.ts

@@ -0,0 +1,16 @@
+/**
+ * This interface implements the schema defined in [MSC2380](https://github.com/matrix-org/matrix-doc/pull/2380).
+ * @category Unstable APIs
+ */
+export interface MSC2380MediaInfo {
+    content_type: string;
+    width?: number;
+    height?: number;
+    size: number;
+    thumbnails?: {
+        width: number;
+        height: number;
+        ready: boolean;
+    }[];
+    duration?: number;
+}

package/src/preprocessors/IPreprocessor.ts

@@ -0,0 +1,24 @@
+import { MatrixClient } from "../MatrixClient";
+import { EventKind } from "..";
+
+/**
+ * Represents a preprocessor.
+ * @category Preprocessors
+ */
+export interface IPreprocessor {
+    /**
+     * Gets the types of events this preprocessor supports.
+     */
+    getSupportedEventTypes(): string[];
+
+    /**
+     * Processes an event, modifying it in-place if needed.
+     * @param {any} event The event that should be processed.
+     * @param {MatrixClient} client The Matrix client that is providing the event.
+     * @param {EventKind|null|undefined} kind Optional kind identifier for an event. When not
+     * supplied, the event is assumed to be a RoomEvent.
+     * @returns {Promise<any>} Resolved when the event is has been modified. The resolved
+     * value is ignored.
+     */
+    processEvent(event: any, client: MatrixClient, kind?: EventKind): Promise<any>;
+}

package/src/preprocessors/RichRepliesPreprocessor.ts

@@ -0,0 +1,159 @@
+import { MatrixClient } from "../MatrixClient";
+import { IPreprocessor } from "./IPreprocessor";
+import { EventKind, extractRequestError, LogService } from "..";
+
+/**
+ * Metadata for a rich reply. Usually stored under the "mx_richreply"
+ * field of an event (at the top level).
+ * @category Preprocessors
+ * @see RichRepliesPreprocessor
+ */
+export interface IRichReplyMetadata {
+    /**
+     * If true, the preprocessor found some inconsistencies in the reply
+     * information that does not match the specification. For example,
+     * this may indicate that a reply was sent without an HTML component.
+     */
+    wasLenient: boolean;
+
+    /**
+     * The event ID the event references. May be an empty string if
+     * wasLenient is true.
+     */
+    parentEventId: string;
+
+    /**
+     * The fallback plain text the preprocessor found. May be an empty
+     * string if wasLenient is true. The prefix characters to indicate
+     * this is a fallback will have already been removed.
+     */
+    fallbackPlainBody: string;
+
+    /**
+     * The fallback HTML the processor found. May be an empty string if
+     * wasLenient is true. The fallback structure will have already been
+     * removed, leaving just the original assumed HTML.
+     */
+    fallbackHtmlBody: string;
+
+    /**
+     * The user ID that sent the parent event, as determined by the fallback
+     * text. This should not be relied upon for anything serious, and instead
+     * the preprocessor should be configured to fetch the real event to
+     * populate the realEvent property. May be an empty string if wasLenient
+     * is true.
+     */
+    fallbackSender: string;
+
+    /**
+     * If the preprocessor is configured to fetch event content, this field
+     * will contain the event as reported by the homeserver. May be null if
+     * wasLenient is true.
+     */
+    realEvent: any;
+}
+
+/**
+ * Processes rich replies found in events. This automatically strips
+ * the fallback representation from events, providing the information
+ * as a top level "mx_richreply" key. The "mx_richreply" property may
+ * be cast to the type IRichReplyMetadata.
+ * @category Preprocessors
+ */
+export class RichRepliesPreprocessor implements IPreprocessor {
+    /**
+     * Creates a new rich replies preprocessor.
+     * @param fetchRealEventContents If enabled, this preprocessor will
+     * attempt to get the real event contents and append them to the event
+     * information.
+     */
+    public constructor(private fetchRealEventContents = false) {
+    }
+
+    public getSupportedEventTypes(): string[] {
+        return ["m.room.message"];
+    }
+
+    public async processEvent(event: any, client: MatrixClient, kind?: EventKind): Promise<any> {
+        if (kind && kind !== EventKind.RoomEvent) return;
+
+        if (!event["content"]) return;
+        if (!event["content"]["m.relates_to"]) return;
+        if (!event["content"]["m.relates_to"]["m.in_reply_to"]) return;
+
+        const parentEventId = event["content"]["m.relates_to"]["m.in_reply_to"]["event_id"];
+        if (!parentEventId) return;
+
+        let fallbackHtml = "";
+        let fallbackText = "";
+        let fallbackSender = "";
+        let realHtml = event["content"]["formatted_body"];
+        let realText = event["content"]["body"];
+        let lenient = false;
+
+        if (event["content"]["format"] !== "org.matrix.custom.html" || !event["content"]["formatted_body"]) {
+            lenient = true; // Not safe to parse: probably not HTML
+        } else {
+            const formattedBody = event["content"]["formatted_body"];
+            if (!formattedBody.startsWith("<mx-reply>") || formattedBody.indexOf("</mx-reply>") === -1) {
+                lenient = true; // Doesn't look like a reply
+            } else {
+                const parts = formattedBody.split("</mx-reply>");
+                const fbHtml = parts[0];
+                realHtml = parts[1];
+
+                const results = fbHtml.match(/<br[ ]*[/]{0,2}>(.*)<\/blockquote>\s*$/i);
+                if (!results) {
+                    lenient = true;
+                } else {
+                    fallbackHtml = results[1];
+                }
+            }
+        }
+
+        let processedFallback = false;
+        const body = event["content"]["body"] || "";
+        for (const line of body.split("\n")) {
+            if (line.startsWith("> ") && !processedFallback) {
+                fallbackText += line.substring(2) + "\n";
+            } else if (!processedFallback) {
+                realText = "";
+                processedFallback = true;
+            } else {
+                realText += line + "\n";
+            }
+        }
+
+        const firstFallbackLine = fallbackText.split("\n")[0];
+        const matches = firstFallbackLine.match(/<(@.*:.*)>/);
+        if (!matches) {
+            lenient = true;
+        } else {
+            fallbackSender = matches[1];
+        }
+
+        const metadata: IRichReplyMetadata = {
+            wasLenient: lenient,
+            fallbackHtmlBody: fallbackHtml ? fallbackHtml.trim() : "",
+            fallbackPlainBody: fallbackText ? fallbackText.trim() : "",
+            fallbackSender: fallbackSender ? fallbackSender.trim() : "",
+            parentEventId: parentEventId ? parentEventId.trim() : "",
+            realEvent: null,
+        };
+
+        if (this.fetchRealEventContents) {
+            try {
+                metadata.realEvent = await client.getEvent(event["room_id"], parentEventId);
+            } catch (e) {
+                LogService.error("RichRepliesPreprocessor", "Failed to fetch real event:");
+                LogService.error("RichRepliesPreprocessor", extractRequestError(e));
+                metadata.wasLenient = true; // failed to fetch event
+            }
+        }
+
+        event["mx_richreply"] = metadata;
+        event["content"]["body"] = realText.trim();
+        if (realHtml) event["content"]["formatted_body"] = realHtml.trim();
+        return event;
+    }
+}

package/src/request.ts

@@ -0,0 +1,21 @@
+import * as origRequestFn from "request";
+
+let requestFn = origRequestFn;
+
+/**
+ * Sets the function to use for performing HTTP requests. Must be compatible with `request`.
+ * @param fn The new request function.
+ * @category Unit testing
+ */
+export function setRequestFn(fn) {
+    requestFn = fn;
+}
+
+/**
+ * Gets the `request`-compatible function for performing HTTP requests.
+ * @returns The request function.
+ * @category Unit testing
+ */
+export function getRequestFn(): typeof origRequestFn {
+    return requestFn;
+}

package/src/simple-validation.ts

@@ -0,0 +1,30 @@
+/**
+ * Validate the 'order' parameter of a child space entry. It must be a
+ * string between the range of \x20 - \x7F and contain no more than 50
+ * characters.
+ * @param {string} order The 'order' parameter of a m.space.child
+ * @throws {Error} If the string is not valid
+ * @returns {boolean} True if the string is valid
+ * @category Utilities
+ */
+export function validateSpaceOrderString(order: string): true {
+    if (typeof (order) !== 'string') {
+        // Just in case, even though TS should catch this.
+        throw Error('order is not a string');
+    }
+
+    if (order.length === 0) {
+        throw Error('order cannot be empty');
+    }
+
+    if (order.length > 50) {
+        throw Error('order is more than 50 characters and is disallowed');
+    }
+
+    if (!order.match(/^[\x20-\x7E]+$/)) {
+        // String must be between this range
+        throw Error('order contained characters outside the range of the spec.');
+    }
+
+    return true;
+}

package/src/storage/IAppserviceStorageProvider.ts

@@ -0,0 +1,54 @@
+import { ICryptoStorageProvider } from "./ICryptoStorageProvider";
+import { IStorageProvider } from "./IStorageProvider";
+
+/**
+ * A storage provider definition for appservices to use.
+ * @category Storage providers
+ */
+export interface IAppserviceStorageProvider {
+    /**
+     * Tracks a user ID as "registered".
+     * @returns {Promise<any>|void} Resolves when complete.
+     */
+    addRegisteredUser(userId: string): Promise<any> | void;
+
+    /**
+     * Determines if a user ID is registered or not.
+     * @returns {boolean|Promise<boolean>} True if registered. This may be a promise.
+     */
+    isUserRegistered(userId: string): boolean | Promise<boolean>;
+
+    /**
+     * Flags a transaction as completed.
+     * @param {string} transactionId The transaction ID.
+     * @returns {Promise<any>|void} Resolves when complete.
+     */
+    setTransactionCompleted(transactionId: string): Promise<any> | void;
+
+    /**
+     * Determines if a transaction has been flagged as completed.
+     * @param {string} transactionId The transaction ID to check.
+     * @returns {boolean} True if the transaction has been completed. This may be a promise.
+     */
+    isTransactionCompleted(transactionId: string): boolean | Promise<boolean>;
+
+    /**
+     * Gets a storage provider to use for the given user ID.
+     * @param {string} userId The user ID.
+     * @returns {ICryptoStorageProvider} The storage provider.
+     */
+    storageForUser?(userId: string): IStorageProvider;
+}
+
+/**
+ * A storage provider capable of only providing crypto-related storage to appservices.
+ * @category Storage providers
+ */
+export interface IAppserviceCryptoStorageProvider {
+    /**
+     * Gets a storage provider to use for the given user ID.
+     * @param {string} userId The user ID.
+     * @returns {ICryptoStorageProvider} The storage provider.
+     */
+    storageForUser(userId: string): ICryptoStorageProvider;
+}

package/src/storage/ICryptoStorageProvider.ts

@@ -0,0 +1,36 @@
+import { ICryptoRoomInformation } from "../e2ee/ICryptoRoomInformation";
+
+/**
+ * A storage provider capable of only providing crypto-related storage.
+ * @category Storage providers
+ */
+export interface ICryptoStorageProvider {
+    /**
+     * Sets the client's device ID.
+     * @param {string} deviceId The device ID.
+     * @returns {Promise<void>} Resolves when complete.
+     */
+    setDeviceId(deviceId: string): Promise<void>;
+
+    /**
+     * Gets the client's device ID, if known.
+     * @returns {Promise<string>} Resolves to the device ID, or falsy if not known.
+     */
+    getDeviceId(): Promise<string>;
+
+    /**
+     * Stores a room's configuration.
+     * @param {string} roomId The room ID to store the configuration for.
+     * @param {ICryptoRoomInformation} config The room's encryption config. May be empty.
+     * @returns {Promise<void>} Resolves when complete.
+     */
+    storeRoom(roomId: string, config: ICryptoRoomInformation): Promise<void>;
+
+    /**
+     * Gets a room's configuration. If the room is unknown, a falsy value is returned.
+     * @param {string} roomId The room ID to get the configuration for.
+     * @returns {Promise<ICryptoRoomInformation>} Resolves to the room's configuration, or
+     * to falsy if the room is unknown.
+     */
+    getRoom(roomId: string): Promise<ICryptoRoomInformation>;
+}

package/src/storage/IStorageProvider.ts

@@ -0,0 +1,53 @@
+import { IFilterInfo } from "../IFilter";
+
+/**
+ * Represents a storage provider for the matrix client
+ * @category Storage providers
+ */
+export interface IStorageProvider {
+    /**
+     * Sets the sync token, saving it for later retrieval
+     * @param {string} token The token to save
+     * @returns {Promise<any>|void} Resolves when complete.
+     */
+    setSyncToken(token: string | null): Promise<any> | void;
+
+    /**
+     * Gets the last saved sync token, or null if none has been persisted.
+     * @returns {String|Promise<String>} The last sync token, or null. This can
+     * also be a promise for the value.
+     */
+    getSyncToken(): string | Promise<string | null> | null;
+
+    /**
+     * Sets the filter to be used by future clients
+     * @param {IFilterInfo} filter The filter to store
+     * @returns {Promise<any>|void} Resolves when complete.
+     */
+    setFilter(filter: IFilterInfo): Promise<any> | void;
+
+    /**
+     * Gets the last preferred filter for this client
+     * @returns {IFilterInfo|Promise<IFilterInfo>} The last saved filter, or null.
+     * This can also be a promise for the filter.
+     */
+    getFilter(): IFilterInfo | Promise<IFilterInfo>;
+
+    /**
+     * Store a simple string value into the provided key.
+     * @param {string} key The key to store the value under.
+     * @param {string} value The value to store.
+     * @returns {Promise<any> | void} Resolves when complete.
+     */
+    storeValue(key: string, value: string): Promise<any> | void;
+
+    /**
+     * Reads a previously stored value under the given key. If the
+     * key does not exist, null or undefined is returned.
+     * @param {string} key The key to read.
+     * @returns {string|Promise<string|null|undefined>|null|undefined} The
+     * value, or null/undefined if not found. This may also return a promise
+     * of those same values.
+     */
+    readValue(key: string): string | Promise<string | null | undefined> | null | undefined;
+}

package/src/storage/MemoryStorageProvider.ts

@@ -0,0 +1,65 @@
+import { IStorageProvider } from "./IStorageProvider";
+import { IFilterInfo } from "../IFilter";
+import { IAppserviceStorageProvider } from "./IAppserviceStorageProvider";
+
+/**
+ * A storage provider that persists no information by keeping it all in memory.
+ * @category Storage providers
+ */
+export class MemoryStorageProvider implements IStorageProvider, IAppserviceStorageProvider {
+    private namespaced = new Map<string, MemoryStorageProvider>();
+    private syncToken: string;
+    private filter: IFilterInfo;
+    private appserviceUsers: { [userId: string]: { registered: boolean } } = {};
+    private appserviceTransactions: { [txnId: string]: boolean } = {};
+    private kvStore: { [key: string]: string } = {};
+
+    setSyncToken(token: string | null): void {
+        this.syncToken = token;
+    }
+
+    getSyncToken(): string | null {
+        return this.syncToken;
+    }
+
+    setFilter(filter: IFilterInfo): void {
+        this.filter = filter;
+    }
+
+    getFilter(): IFilterInfo {
+        return this.filter;
+    }
+
+    addRegisteredUser(userId: string) {
+        this.appserviceUsers[userId] = {
+            registered: true,
+        };
+    }
+
+    isUserRegistered(userId: string): boolean {
+        return this.appserviceUsers[userId] && this.appserviceUsers[userId].registered;
+    }
+
+    isTransactionCompleted(transactionId: string): boolean {
+        return !!this.appserviceTransactions[transactionId];
+    }
+
+    setTransactionCompleted(transactionId: string) {
+        this.appserviceTransactions[transactionId] = true;
+    }
+
+    readValue(key: string): string | null | undefined {
+        return this.kvStore[key];
+    }
+
+    storeValue(key: string, value: string): void {
+        this.kvStore[key] = value;
+    }
+
+    storageForUser(userId: string): IStorageProvider {
+        if (!this.namespaced.has(userId)) {
+            this.namespaced.set(userId, new MemoryStorageProvider());
+        }
+        return this.namespaced.get(userId);
+    }
+}