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

package/src/models/events/MessageEvent.ts

@@ -0,0 +1,292 @@
+import { RoomEvent } from "./RoomEvent";
+import { EventRedactedError } from "./InvalidEventError";
+
+/**
+ * The types of messages that are valid in Matrix.
+ * @category Matrix event info
+ * @see MessageEventContent
+ */
+export type MessageType =
+    "m.text"
+    | "m.emote"
+    | "m.notice"
+    | "m.image"
+    | "m.file"
+    | "m.audio"
+    | "m.location"
+    | "m.video"
+    | string;
+
+/**
+ * Information about a file in Matrix
+ * @category Matrix event info
+ * @see MessageEventContent
+ */
+export interface FileInfo {
+    /**
+     * The size of the file in bytes.
+     */
+    size?: number;
+
+    /**
+     * The type of file.
+     */
+    mimetype?: string;
+}
+
+/**
+ * Information about a thumbnail in Matrix
+ * @category Matrix event info
+ * @see MessageEventContent
+ */
+export interface ThumbnailInfo {
+    /**
+     * The size of the thumbnail in bytes.
+     */
+    size?: number;
+
+    /**
+     * The type of thumbnail.
+     */
+    mimetype?: string;
+
+    /**
+     * The intended height of the thumbnail in pixels.
+     */
+    h: number;
+
+    /**
+     * The intended width of the thumbnail in pixels.
+     */
+    w: number;
+}
+
+/**
+ * Information about a file's thumbnail.
+ * @category Matrix event info
+ * @see MessageEventContent
+ */
+export interface ThumbnailedFileInfo {
+    /**
+     * A URL to a thumbnail for the file, if unencrypted.
+     */
+    thumbnail_url?: string;
+
+    /**
+     * The encrypted thumbnail file information, if encrypted.
+     */
+    thumbnail_file?: EncryptedFile;
+
+    /**
+     * Information about the thumbnail. Optionally included if a thumbnail_url is specified.
+     */
+    thumbnail_info?: ThumbnailInfo;
+}
+
+/**
+ * Information about a file that has a thumbnail
+ * @category Matrix event info
+ * @see MessageEventContent
+ */
+export interface FileWithThumbnailInfo extends FileInfo, ThumbnailedFileInfo {
+}
+
+/**
+ * Information about a file that has a width and height.
+ * @category Matrix event info
+ * @see MessageEventContent
+ */
+export interface DimensionalFileInfo extends FileWithThumbnailInfo {
+    /**
+     * The intended height of the media in pixels.
+     */
+    h: number;
+
+    /**
+     * The intended width of the media in pixels.
+     */
+    w: number;
+}
+
+/**
+ * Information about a file that has a time dimension.
+ * @category Matrix event info
+ * @see MessageEventContent
+ */
+export interface TimedFileInfo extends FileInfo {
+    /**
+     * The duration of the media in milliseconds.
+     */
+    duration: number;
+}
+
+/**
+ * Information about a video file.
+ * @category Matrix event info
+ * @see MessageEventContent
+ */
+export interface VideoFileInfo extends DimensionalFileInfo, TimedFileInfo {
+    // No new properties.
+}
+
+/**
+ * The content definition for m.room.message events with a type of m.audio
+ * @category Matrix event contents
+ * @see MessageEvent
+ */
+export interface AudioMessageEventContent extends FileMessageEventContent {
+    /**
+     * Information about the file.
+     */
+    info?: TimedFileInfo;
+}
+
+/**
+ * The content definition for m.room.message events with a type of m.video
+ * @category Matrix event contents
+ * @see MessageEvent
+ */
+export interface VideoMessageEventContent extends FileMessageEventContent {
+    /**
+     * Information about the file.
+     */
+    info?: VideoFileInfo;
+}
+
+/**
+ * The content definition for m.room.message events with a type of m.image
+ * @category Matrix event contents
+ * @see MessageEvent
+ */
+export interface ImageMessageEventContent extends FileMessageEventContent {
+    /**
+     * Information about the file.
+     */
+    info?: DimensionalFileInfo;
+}
+
+/**
+ * The content definition for m.room.message events with a type of m.file
+ * @category Matrix event contents
+ * @see MessageEvent
+ */
+export interface FileMessageEventContent extends MessageEventContent {
+    /**
+     * Information about the file.
+     */
+    info?: FileWithThumbnailInfo;
+
+    /**
+     * URL to the file, if unencrypted.
+     */
+    url: string;
+
+    /**
+     * The encrypted file, if encrypted.
+     */
+    file: EncryptedFile;
+}
+
+/**
+ * An encrypted file.
+ * @category Matrix event contents
+ * @see MessageEvent
+ */
+export interface EncryptedFile {
+    url: string;
+    key: {
+        kty: "oct";
+        key_ops: string[];
+        alg: "A256CTR";
+        k: string;
+        ext: true;
+    };
+    iv: string;
+    hashes: {
+        sha256: string;
+    };
+    v: "v2";
+}
+
+/**
+ * The content definition for m.room.message events with a type of m.location
+ * @category Matrix event contents
+ * @see MessageEvent
+ */
+export interface LocationMessageEventContent extends MessageEventContent {
+    /**
+     * Information about the location.
+     */
+    info?: ThumbnailedFileInfo;
+
+    /**
+     * A geo URI of the location.
+     */
+    geo_uri?: string;
+}
+
+/**
+ * The content definition for m.room.message events with types of m.text, m.emote, and m.notice
+ * @category Matrix event contents
+ * @see MessageEvent
+ */
+export interface TextualMessageEventContent extends MessageEventContent {
+    format?: string;
+    formatted_body?: string;
+}
+
+/**
+ * The content definition for m.room.message events
+ * @category Matrix event contents
+ * @see MessageEvent
+ */
+export interface MessageEventContent {
+    body: string;
+    msgtype: MessageType;
+    external_url?: string;
+}
+
+/**
+ * Represents an m.room.message room event
+ * @category Matrix events
+ */
+export class MessageEvent<T extends MessageEventContent> extends RoomEvent<T> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * Whether or not the event is redacted (or looked redacted).
+     */
+    public get isRedacted(): boolean {
+        // Presume the event redacted if we're missing a body or message type
+        const noContent = !this.content.body && this.content.body !== "";
+        const noMsgtype = !this.content.msgtype && this.content.msgtype !== "";
+        return noContent || noMsgtype;
+    }
+
+    /**
+     * The message's type.
+     */
+    public get messageType(): MessageType {
+        const type = this.content.msgtype;
+        if (!type && type !== "") throw new EventRedactedError("missing msgtype");
+        return type;
+    }
+
+    /**
+     * The `body` of the message.
+     */
+    public get textBody(): string {
+        const body = this.content.body;
+        if (!body && body !== "") throw new EventRedactedError("missing body");
+        return body;
+    }
+
+    /**
+     * The `external_url` of the message, if it exists
+     */
+    public get externalUrl(): string | undefined {
+        return this.content.external_url || undefined;
+    }
+}

package/src/models/events/PinnedEventsEvent.ts

@@ -0,0 +1,30 @@
+import { StateEvent } from "./RoomEvent";
+
+/**
+ * The content definition for m.room.pinned_events events
+ * @category Matrix event contents
+ * @see PinnedEventsEvent
+ */
+export interface PinnedEventsEventContent {
+    /**
+     * The event IDs that are pinned in the room.
+     */
+    pinned: string[];
+}
+
+/**
+ * Represents an m.room.pinned_events state event
+ * @category Matrix events
+ */
+export class PinnedEventsEvent extends StateEvent<PinnedEventsEventContent> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * The event IDs that are pinned in the room.
+     */
+    public get pinnedEventIds(): string[] {
+        return this.content.pinned || [];
+    }
+}

package/src/models/events/PowerLevelsEvent.ts

@@ -0,0 +1,135 @@
+import { StateEvent } from "./RoomEvent";
+
+/**
+ * The content definition for m.room.power_levels events
+ * @category Matrix event contents
+ * @see PowerLevelsEvent
+ */
+export interface PowerLevelsEventContent {
+    /**
+     * The power level required to ban. Default 50.
+     */
+    ban?: number;
+
+    /**
+     * A map of event types to the power level required to send them.
+     */
+    events?: { [eventType: string]: number };
+
+    /**
+     * The power level required to send events in the room. Default 50.
+     */
+    events_default?: number;
+
+    /**
+     * The power level required to invite users to the room. Default 50.
+     */
+    invite?: number;
+
+    /**
+     * The power level required to kick users from the room. Default 50.
+     */
+    kick?: number;
+
+    /**
+     * The power level required to redact other people's events in the room. Default 50.
+     */
+    redact?: number;
+
+    /**
+     * The power level required to send state events in the room. Default 50.
+     */
+    state_default?: number;
+
+    /**
+     * A map of user IDs to power levels.
+     */
+    users?: { [userId: string]: number };
+
+    /**
+     * The power level of users not listed in `users`. Default 0.
+     */
+    users_default?: number;
+
+    /**
+     * Power levels required to send certain kinds of notifications.
+     */
+    notifications?: {
+        /**
+         * The power level required to send "@room" notifications. Default 50.
+         */
+        room?: number;
+    };
+}
+
+function defaultNum(val: number | undefined, def: number): number {
+    if (!val && val !== 0) return def;
+    return val;
+}
+
+/**
+ * Represents an m.room.power_levels state event
+ * @category Matrix events
+ */
+export class PowerLevelsEvent extends StateEvent<PowerLevelsEventContent> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * The power level required to ban users.
+     */
+    public get banLevel(): number {
+        return defaultNum(this.content.ban, 50);
+    }
+
+    /**
+     * The power level required to invite users.
+     */
+    public get inviteLevel(): number {
+        return defaultNum(this.content.invite, 50);
+    }
+
+    /**
+     * The power level required to kick users.
+     */
+    public get kickLevel(): number {
+        return defaultNum(this.content.kick, 50);
+    }
+
+    /**
+     * The power level required to redact messages sent by other users.
+     */
+    public get redactLevel(): number {
+        return defaultNum(this.content.redact, 50);
+    }
+
+    /**
+     * The power level required to send "@room" notifications.
+     */
+    public get notifyWholeRoomLevel(): number {
+        if (!this.content.notifications) return 50;
+        return defaultNum(this.content.notifications.room, 50);
+    }
+
+    /**
+     * The default power level for users.
+     */
+    public get defaultUserLevel(): number {
+        return defaultNum(this.content.users_default, 0);
+    }
+
+    /**
+     * The default power level required to send state events.
+     */
+    public get defaultStateEventLevel(): number {
+        return defaultNum(this.content.state_default, 50);
+    }
+
+    /**
+     * The default power level required to send room events.
+     */
+    public get defaultEventLevel(): number {
+        return defaultNum(this.content.events_default, 50);
+    }
+}

package/src/models/events/PresenceEvent.ts

@@ -0,0 +1,69 @@
+import { MatrixEvent } from "./Event";
+
+/**
+ * The allowed states of presence in Matrix.
+ *
+ * * `online`: The default state when the user is connected to an event stream.
+ * * `unavailable`: The user is not reachable at this time e.g. they are idle.
+ * * `offline`: The user is not connected to an event stream or is explicitly suppressing their profile information from being sent.
+ *
+ * @category Matrix event info
+ * @see PresenceEventContent
+ */
+export type PresenceState = "online" | "offline" | "unavailable";
+
+/**
+ * Event content for m.presence events
+ * @category Matrix event contents
+ * @see PresenceEvent
+ */
+export interface PresenceEventContent {
+    /**
+     * The avatar URL for the user, if any.
+     */
+    avatar_url?: string;
+
+    /**
+     * The display name for the user, if any.
+     */
+    displayname?: string;
+
+    /**
+     * How long ago the user performed some action, in milliseconds.
+     */
+    last_active_ago?: number;
+
+    /**
+     * The user's presence state.
+     *
+     * @see {@link PresenceState} for a description of each presence key.
+     */
+    presence: PresenceState;
+
+    /**
+     * Whether or not the user is currently active.
+     */
+    currently_active?: boolean;
+
+    /**
+     * A status message associated with this presence.
+     */
+    status_msg?: string;
+}
+
+/**
+ * Wraps a m.presence ephemeral event in Matrix
+ * @category Matrix events
+ */
+export class PresenceEvent extends MatrixEvent<PresenceEventContent> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * The current presence state for the user.
+     */
+    public get presence(): PresenceState {
+        return this.content.presence;
+    }
+}

package/src/models/events/RedactionEvent.ts

@@ -0,0 +1,44 @@
+import { RoomEvent } from "./RoomEvent";
+
+/**
+ * The content definition for m.room.redaction events
+ * @category Matrix event contents
+ * @see RedactionEvent
+ */
+export interface RedactionEventContent {
+    /**
+     * The event ID or IDs this event redacts.
+     */
+    redacts?: string | string[]; // MSC2174 & MSC2244
+}
+
+/**
+ * Represents an m.room.redaction room event
+ * @category Matrix events
+ */
+export class RedactionEvent extends RoomEvent<RedactionEventContent> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * The event ID this event redacts.
+     * @deprecated It is possible for multiple events to be redacted depending on the room version.
+     */
+    public get redactsEventId(): string {
+        return this.redactsEventIds[0];
+    }
+
+    /**
+     * The event IDs this event redacts.
+     */
+    public get redactsEventIds(): string[] {
+        if (Array.isArray(this.content.redacts)) {
+            return this.content.redacts;
+        } else if (this.content.redacts) {
+            return [this.content.redacts];
+        } else {
+            return [this.event['redacts']];
+        }
+    }
+}

package/src/models/events/RoomAvatarEvent.ts

@@ -0,0 +1,36 @@
+import { StateEvent } from "./RoomEvent";
+import { DimensionalFileInfo } from "./MessageEvent";
+
+/**
+ * The content definition for m.room.avatar events
+ * @category Matrix event contents
+ * @see RoomAvatarEvent
+ */
+export interface RoomAvatarEventContent {
+    /**
+     * The URL to the image for the avatar of the room.
+     */
+    url: string;
+
+    /**
+     * Optional information about the avatar.
+     */
+    info?: DimensionalFileInfo;
+}
+
+/**
+ * Represents an m.room.avatar state event
+ * @category Matrix events
+ */
+export class RoomAvatarEvent extends StateEvent<RoomAvatarEventContent> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * The URL for the avatar of the room.
+     */
+    public get avatarUrl(): string {
+        return this.content.url;
+    }
+}

package/src/models/events/RoomEvent.ts

@@ -0,0 +1,83 @@
+import { MatrixEvent } from "./Event";
+
+/**
+ * The typical unsigned data found on an event.
+ * @category Matrix event info
+ * @see RoomEvent
+ */
+export interface TypicalUnsigned {
+    /**
+     * The age of this event in seconds.
+     */
+    age?: number;
+
+    /**
+     * Other properties which may be included.
+     */
+    [prop: string]: any;
+}
+
+/**
+ * Empty room event content.
+ * @category Matrix event contents
+ */
+export interface RoomEventContent {
+    // This is empty so people can avoid using RoomEvent<any>
+}
+
+/**
+ * A Matrix room event.
+ * @category Matrix events
+ */
+export class RoomEvent<T extends (Object | unknown) = unknown> extends MatrixEvent<T> {
+    constructor(protected event: any) {
+        super(event);
+    }
+
+    /**
+     * The event ID of this event.
+     */
+    public get eventId(): string {
+        return this.event['event_id'];
+    }
+
+    /**
+     * The timestamp in milliseconds this event was sent.
+     */
+    public get timestamp(): number {
+        return this.event['origin_server_ts'];
+    }
+
+    /**
+     * The unsigned content for this event. May have no properties.
+     */
+    public get unsigned(): TypicalUnsigned {
+        return this.event['unsigned'] || {};
+    }
+}
+
+/**
+ * A room state event.
+ * @category Matrix events
+ */
+export class StateEvent<T extends (Object | unknown) = unknown> extends RoomEvent<T> {
+    constructor(event: any) {
+        super(event);
+    }
+
+    /**
+     * The state key for this event. May be an empty string.
+     */
+    public get stateKey(): string {
+        return this.event['state_key'];
+    }
+
+    /**
+     * The previous content for this state event. Will be an empty
+     * object if there is no previous content.
+     */
+    public get previousContent(): T {
+        return this.unsigned['prev_content'] || this.event['prev_content'] || {}; // v2, v1, fallback
+    }
+}
+

package/src/models/events/RoomNameEvent.ts

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