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

package/src/models/Crypto.ts

@@ -0,0 +1,188 @@
+/**
+ * One time key algorithms.
+ * @category Models
+ */
+export enum OTKAlgorithm {
+    Signed = "signed_curve25519",
+    Unsigned = "curve25519",
+}
+
+/**
+ * Label for a one time key.
+ * @category Models
+ */
+export type OTKLabel<Algorithm extends OTKAlgorithm, ID extends string> = `${Algorithm}:${ID}`;
+
+/**
+ * Signatures object.
+ * @category Models
+ */
+export interface Signatures {
+    [entity: string]: {
+        [keyLabel: string]: string;
+    };
+}
+
+/**
+ * A signed_curve25519 one time key.
+ * @category Models
+ */
+export interface SignedCurve25519OTK {
+    key: string;
+    signatures: Signatures;
+    fallback?: boolean;
+}
+
+/**
+ * A fallback key.
+ * @category Models
+ */
+export interface FallbackKey {
+    keyId: string;
+    key: SignedCurve25519OTK & { fallback: true };
+}
+
+/**
+ * One Time Keys structure model.
+ * @category Models
+ */
+export type OTKs =
+    Record<OTKLabel<OTKAlgorithm.Signed, string>, SignedCurve25519OTK>
+    & Record<OTKLabel<OTKAlgorithm.Unsigned, string>, string>;
+
+/**
+ * The counts of each one time key by algorithm.
+ * @category Models
+ */
+export type OTKCounts = {
+    /**
+     * The number of keys which remain unused for the algorithm.
+     */
+    [alg in OTKAlgorithm]?: number;
+};
+
+/**
+ * The available encryption algorithms.
+ * @category Models
+ */
+export enum EncryptionAlgorithm {
+    OlmV1Curve25519AesSha2 = "m.olm.v1.curve25519-aes-sha2",
+    MegolmV1AesSha2 = "m.megolm.v1.aes-sha2",
+}
+
+/**
+ * The key algorithms for device keys.
+ * @category Models
+ */
+export enum DeviceKeyAlgorithm {
+    Ed25519 = "ed25519",
+    Curve25519 = "curve25519",
+}
+
+/**
+ * Label for a device key.
+ * @category Models
+ */
+export type DeviceKeyLabel<Algorithm extends DeviceKeyAlgorithm, ID extends string> = `${Algorithm}:${ID}`;
+
+/**
+ * Represents a user's device.
+ * @category Models
+ */
+export interface UserDevice {
+    user_id: string;
+    device_id: string;
+    algorithms: (EncryptionAlgorithm | string)[];
+    keys: Record<DeviceKeyLabel<DeviceKeyAlgorithm, string>, string>;
+    signatures: Signatures;
+    unsigned?: {
+        [k: string]: any;
+        device_display_name?: string;
+    };
+}
+
+/**
+ * Represents a user's own device.
+ * @category Models
+ */
+export interface OwnUserDevice {
+    device_id: string;
+    display_name?: string;
+    last_seen_ip?: string;
+    last_seen_ts?: number;
+}
+
+/**
+ * Device list response for a multi-user query.
+ * @category Models
+ */
+export interface MultiUserDeviceListResponse {
+    /**
+     * Federation failures, keyed by server name. The mapped object should be a standard
+     * error object.
+     */
+    failures: {
+        [serverName: string]: any;
+    };
+
+    /**
+     * A map of user ID to device ID to device.
+     */
+    device_keys: Record<string, Record<string, UserDevice>>;
+}
+
+/**
+ * One Time Key claim response.
+ * @category Models
+ */
+export interface OTKClaimResponse {
+    /**
+     * Federation failures, keyed by server name. The mapped object should be a standard
+     * error object.
+     */
+    failures: {
+        [serverName: string]: any;
+    };
+
+    /**
+     * The claimed One Time Keys, as a map from user ID to device ID to key ID to OTK.
+     */
+    one_time_keys: Record<string, Record<string, OTKs>>;
+}
+
+/**
+ * An encrypted Olm payload.
+ * @category Models
+ */
+export interface IOlmEncrypted {
+    algorithm: EncryptionAlgorithm.OlmV1Curve25519AesSha2;
+    sender_key: string;
+    ciphertext: {
+        [deviceCurve25519Key: string]: {
+            type: number;
+            body: string; // base64
+        };
+    };
+}
+
+/**
+ * A to-device message.
+ * @category Models
+ */
+export interface IToDeviceMessage<T = any> {
+    type: string;
+    sender: string;
+    content: T;
+}
+
+/**
+ * Encrypted event content for a Megolm-encrypted m.room.encrypted event
+ * @category Models
+ */
+export interface IMegolmEncrypted {
+    algorithm: EncryptionAlgorithm.MegolmV1AesSha2;
+    sender_key: string;
+    ciphertext: string;
+    session_id: string;
+    device_id: string; // sender
+}

package/src/models/EventContext.ts

@@ -0,0 +1,23 @@
+import { RoomEvent, RoomEventContent, StateEvent } from "./events/RoomEvent";
+
+export interface EventContext {
+    /**
+     * The event that was used to build this context.
+     */
+    event: RoomEvent<RoomEventContent>;
+
+    /**
+     * The events that happened before the contextual event.
+     */
+    before: RoomEvent<RoomEventContent>[];
+
+    /**
+     * The events that happened after the contextual event.
+     */
+    after: RoomEvent<RoomEventContent>[];
+
+    /**
+     * The state of the room at the point of the last event returned.
+     */
+    state: StateEvent<RoomEventContent>[];
+}

package/src/models/IdentityServerModels.ts

@@ -0,0 +1,18 @@
+/**
+ * Information about a user on an identity server.
+ * @category Models
+ */
+export interface IdentityServerAccount {
+    user_id: string;
+}
+
+/**
+ * A stored invite on an identity server.
+ * @category Models
+ */
+export interface IdentityServerInvite {
+    display_name: string;
+    public_keys: { public_key: string, key_validity_url: string }[]; // server key then ephemeral key, length of 2
+    public_key: string;
+    token: string;
+}

package/src/models/MSC2176.ts

@@ -0,0 +1,47 @@
+/**
+ * Response object for a batch send operation.
+ * @category Models
+ */
+export interface MSC2716BatchSendResponse {
+    /**
+     * List of historical state event IDs that were inserted
+     */
+    state_events?: string[];
+    /**
+     * List of historical event IDs that were inserted
+     */
+    events?: string[];
+    /**
+     * Chunk ID to be used in the next `sendHistoricalEventBatch` call.
+     */
+    next_chunk_id: string;
+}
+
+// TODO: Verify docs and move to events subdirectory if appropriate
+
+/**
+ * Partial event content for an inserted MSC2716 event.
+ * @category Matrix event contents
+ */
+export interface MSC2716InsertionEventContent {
+    "org.matrix.msc2716.next_chunk_id": string;
+    "org.matrix.msc2716.historical": true;
+}
+
+/**
+ * Partial event content for a chunked MSC2716 event.
+ * @category Matrix event contents
+ */
+export interface MSC2716ChunkEventContent {
+    "org.matrix.msc2716.chunk_id": string;
+    "org.matrix.msc2716.historical": true;
+}
+
+/**
+ * Partial event content for a marked MSC2716 event.
+ * @category Matrix event contents
+ */
+export interface MSC2716MarkerEventContent {
+    "org.matrix.msc2716.insertion_id": string;
+    "org.matrix.msc2716.historical": true;
+}

package/src/models/MatrixError.ts

@@ -0,0 +1,39 @@
+/**
+ * Represents an HTTP error from the Matrix server.
+ * @category Error handling
+ */
+export class MatrixError extends Error {
+    /**
+     * The Matrix error code
+     */
+    public readonly errcode: string;
+
+    /**
+     * Optional human-readable error message.
+     */
+    public readonly error: string;
+
+    /**
+     * If rate limited, the time in milliseconds to wait before retrying the request
+     */
+    public readonly retryAfterMs?: number;
+
+    /**
+     * Creates a new Matrix Error
+     * @param body The error body.
+     * @param statusCode The HTTP status code.
+     */
+    constructor(public readonly body: { errcode: string, error: string, retry_after_ms?: number }, public readonly statusCode: number) {
+        super();
+        this.errcode = body.errcode;
+        this.error = body.error;
+        this.retryAfterMs = body.retry_after_ms;
+    }
+
+    /**
+     * Developer-friendly error message.
+     */
+    public get message() {
+        return `${this.errcode}: ${this.error}`;
+    }
+}

package/src/models/MatrixProfile.ts

@@ -0,0 +1,55 @@
+import { MentionPill, UserID } from "..";
+
+/**
+ * Profile information commonly associated with Matrix profiles
+ * @category Models
+ */
+export interface MatrixProfileInfo {
+    /**
+     * The display name of the user, if any.
+     */
+    displayname?: string;
+
+    /**
+     * A URL to the user's avatar, if any.
+     */
+    avatar_url?: string;
+}
+
+/**
+ * Represents a user's profile, possibly in a room.
+ * @category Models
+ */
+export class MatrixProfile {
+    /**
+     * Creates a new profile representation for a user.
+     * @param {string} userId The user ID the profile is for.
+     * @param {MatrixProfile} profile The profile itself.
+     */
+    constructor(private userId: string, private profile: MatrixProfileInfo) {
+    }
+
+    /**
+     * The display name for the user. This will always return a value, though it
+     * may be based upon their user ID if no explicit display name is set.
+     */
+    public get displayName(): string {
+        if (!this.profile?.displayname) return new UserID(this.userId).localpart;
+        return this.profile.displayname;
+    }
+
+    /**
+     * The avatar URL for the user. If the user does not have an avatar, this will
+     * be null.
+     */
+    public get avatarUrl(): string {
+        return this.profile?.avatar_url || null; // enforce null over boolean semantics
+    }
+
+    /**
+     * A mention pill for this user.
+     */
+    public get mention(): MentionPill {
+        return MentionPill.withDisplayName(this.userId, this.displayName);
+    }
+}

package/src/models/OpenIDConnect.ts

@@ -0,0 +1,10 @@
+/**
+ * An OpenID Connect token from the homeserver.
+ * @category Models
+ */
+export interface OpenIDConnectToken {
+    access_token: string;
+    expires_in: number;
+    matrix_server_name: string;
+    token_type: 'Bearer';
+}

package/src/models/Policies.ts

@@ -0,0 +1,28 @@
+/**
+ * Information about the policies (terms of service) a server may have.
+ * @category Models
+ */
+export interface Policies {
+    policies: {
+        [id: string]: Policy;
+    };
+}
+
+/**
+ * Information about a policy (terms of service) a server may have.
+ * @category Models
+ */
+export interface Policy {
+    version: string;
+
+    [language: string]: TranslatedPolicy | string; // "|string" is required for `version` to work
+}
+
+/**
+ * Information about a (translated) policy (terms of service).
+ * @category Models
+ */
+export interface TranslatedPolicy {
+    name: string;
+    url: string;
+}

package/src/models/PowerLevelAction.ts

@@ -0,0 +1,31 @@
+/**
+ * Actions that can be guarded by power levels.
+ */
+export enum PowerLevelAction {
+    /**
+     * Power level required to ban other users.
+     */
+    Ban = "ban",
+
+    /**
+     * Power level required to kick other users.
+     */
+    Kick = "kick",
+
+    /**
+     * Power level required to redact events sent by other users. Users can redact
+     * their own messages regardless of this power level requirement, unless forbidden
+     * by the `events` section of the power levels content.
+     */
+    RedactEvents = "redact",
+
+    /**
+     * Power level required to invite other users.
+     */
+    Invite = "invite",
+
+    /**
+     * Power level required to notify the whole room with "@room".
+     */
+    NotifyRoom = "notifications.room",
+}

package/src/models/PowerLevelBounds.ts

@@ -0,0 +1,16 @@
+/**
+ * Information on the bounds of a power level change a user can apply.
+ */
+export interface PowerLevelBounds {
+    /**
+     * Whether or not the user can even modify the power level of the user. This
+     * will be false if the user can't send power level events, or the user is
+     * unobtainably high in power.
+     */
+    canModify: boolean;
+
+    /**
+     * The maximum possible power level the user can set on the target user.
+     */
+    maximumPossibleLevel: number;
+}

package/src/models/Presence.ts

@@ -0,0 +1,38 @@
+import { PresenceEventContent, PresenceState } from "./events/PresenceEvent";
+
+/**
+ * Presence information for a user.
+ * @category Models
+ */
+export class Presence {
+    constructor(protected presence: PresenceEventContent) {
+    }
+
+    /**
+     * The state for this presence update.
+     */
+    public get state(): PresenceState {
+        return this.presence.presence;
+    }
+
+    /**
+     * The status message which accompanies this presence. May be falsey.
+     */
+    public get statusMessage(): string {
+        return this.presence.status_msg;
+    }
+
+    /**
+     * How long ago in milliseconds this presence was changed. May be falsey.
+     */
+    public get lastActiveAgo(): number {
+        return this.presence.last_active_ago;
+    }
+
+    /**
+     * Whether or not the user is currently active.
+     */
+    public get currentlyActive(): boolean {
+        return this.presence.currently_active;
+    }
+}

package/src/models/ServerVersions.ts

@@ -0,0 +1,8 @@
+/**
+ * Representation of the server's supported specification versions and unstable feature flags.
+ * @category Models
+ */
+export type ServerVersions = {
+    unstable_features?: Record<string, boolean>;
+    versions: string[];
+};

package/src/models/Spaces.ts

@@ -0,0 +1,167 @@
+import { MatrixClient } from "../MatrixClient";
+import { UserID } from "../helpers/MatrixEntity";
+import { validateSpaceOrderString } from "../simple-validation";
+import { SpaceChildEvent, SpaceChildEventContent } from "./events/SpaceChildEvent";
+
+/**
+ * Options to be specified when creating a Space.
+ * @category Models
+ */
+export interface SpaceCreateOptions {
+    /**
+     * The name of the space.
+     */
+    name: string;
+
+    /**
+     * The topic/description for the space.
+     */
+    topic?: string;
+
+    /**
+     * An MXC URI for the space's avatar.
+     */
+    avatarUrl?: string;
+
+    /**
+     * Whether or not the space should be publicly joinable or not.
+     */
+    isPublic: boolean; // maps to world_readable on true, otherwise private.
+
+    /**
+     * Optional localpart for the alias of the space.
+     */
+    localpart?: string;
+
+    /**
+     * User IDs to invite to the space upon creation.
+     */
+    invites?: string[];
+}
+
+/**
+ * Options for displaying/handling a child room/space.
+ * @category Models
+ */
+export interface SpaceChildEntityOptions {
+    /**
+     * Whether or not the entity is intended to be a suggested entity.
+     */
+    suggested?: boolean;
+
+    /**
+     * Servers to try and join through. When not provided, the SDK will try to
+     * determine a set.
+     */
+    via?: string[];
+
+    /**
+     * A short string to differentiate the rendering order of entities.
+     * @see validateSpaceOrderString
+     */
+    order?: string;
+}
+
+/**
+ * Options for creating a new child space or room.
+ * @category Models
+ */
+export type NewChildOpts = SpaceCreateOptions & SpaceChildEntityOptions;
+
+/**
+ * A mapping of room ID to space child information.
+ * @category Models
+ */
+export interface SpaceEntityMap {
+    [roomId: string]: SpaceChildEvent;
+}
+
+/**
+ * An instance representing a Matrix Space. A space is tied to a room.
+ * @category Models
+ */
+export class Space {
+    public constructor(public readonly roomId: string, public readonly client: MatrixClient) {
+    }
+
+    /**
+     * Creates a new child space under this space.
+     * @param {SpaceCreateOptions} opts The options for the new space.
+     * @returns {Promise<Space>} Resolves to the created space.
+     */
+    public async createChildSpace(opts: NewChildOpts): Promise<Space> {
+        const space = await this.client.createSpace(opts);
+        await this.addChildSpace(space, opts);
+        return space;
+    }
+
+    /**
+     * Adds a child space to the space. Must be joined to both spaces.
+     * @param {Space} space The space to add.
+     * @param {SpaceChildEntityOptions} childOpts Related options for the child's representation.
+     * @returns {Promise<Space>} Resolves when complete.
+     */
+    public async addChildSpace(space: Space, childOpts: SpaceChildEntityOptions = {}): Promise<void> {
+        await this.addChildRoom(space.roomId, childOpts);
+    }
+
+    /**
+     * Removes a child space from the space. Must be joined to the current space (not needed for child space).
+     * @param {Space} space The space to remove.
+     * @returns {Promise<void>} Resolves when complete.
+     */
+    public async removeChildSpace(space: Space): Promise<void> {
+        await this.removeChildRoom(space.roomId);
+    }
+
+    /**
+     * Adds a child room to the space. Must be joined to both the room and the space.
+     * @param {string} roomId The room ID to add.
+     * @param {SpaceChildEntityOptions} childOpts Additional options for the child space.
+     * @returns {Promise<void>} Resolves when complete.
+     */
+    public async addChildRoom(roomId: string, childOpts: SpaceChildEntityOptions = {}): Promise<void> {
+        const via = childOpts.via ?? [new UserID(await this.client.getUserId()).domain];
+        const childContent: SpaceChildEventContent = { via };
+
+        if (childOpts.suggested) childContent.suggested = childOpts.suggested;
+        if (childOpts.order) {
+            validateSpaceOrderString(childOpts.order);
+            childContent.order = childOpts.order;
+        }
+
+        await this.client.sendStateEvent(this.roomId, "m.space.child", roomId, childContent);
+    }
+
+    /**
+     * Removes a child room from the space. Must be joined to the current space (not needed for child room).
+     * @param {string} roomId The room ID to remove.
+     * @returns {Promise<void>} Resolves when complete.
+     */
+    public async removeChildRoom(roomId: string): Promise<void> {
+        await this.client.sendStateEvent(this.roomId, "m.space.child", roomId, {});
+    }
+
+    /**
+     * Gets all the child rooms on the space. These may be spaces or other rooms.
+     * @returns {Promise<SpaceEntityMap>} Resolves to a map of children for this space.
+     */
+    public async getChildEntities(): Promise<SpaceEntityMap> {
+        const roomState = await this.client.getRoomState(this.roomId);
+        const mapping: SpaceEntityMap = {};
+        roomState
+            .filter(s => s.type === "m.space.child")
+            .filter(s => s.content?.via)
+            .forEach(s => mapping[s.state_key] = new SpaceChildEvent(s));
+        return mapping;
+    }
+
+    /**
+     * Invite a user to the current space.
+     * @param {string} userId The user ID to invite.
+     * @returns {Promise<void>} Resolves when completed.
+     */
+    public async inviteUser(userId: string) {
+        return this.client.inviteUser(userId, this.roomId);
+    }
+}

package/src/models/Threepid.ts

@@ -0,0 +1,8 @@
+/**
+ * A Third Party Identifier (3PID or threepid)
+ * @category Models
+ */
+export interface Threepid {
+    kind: "email" | "msisdn" | string;
+    address: string;
+}