@textrp/briij-js-sdk 41.0.0

package/src/matrixrtc/types.ts

@@ -0,0 +1,227 @@
+/*
+Copyright 2023-2026 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import type { IContent, IMentions } from "../briij.ts";
+import type { RelationEvent } from "../types.ts";
+import type { CallMembership } from "./CallMembership.ts";
+import { type CallMembershipIdentityParts } from "./EncryptionManager.ts";
+
+export type EncryptionKeyMapKey = string;
+
+export interface EncryptionKeyEntry {
+    index: number;
+    key: string;
+}
+
+/**
+ * The mxID, deviceId and membership timestamp of a RTC session participant.
+ */
+export type ParticipantDeviceInfo = {
+    userId: string;
+    deviceId: string;
+    membershipTs: number;
+};
+
+/**
+ * A type representing the information needed to decrypt video streams.
+ */
+export type InboundEncryptionSession = {
+    key: Uint8Array<ArrayBuffer>;
+    membership: CallMembershipIdentityParts;
+    keyIndex: number;
+    creationTS: number;
+};
+
+/**
+ * The information about the key used to encrypt video streams.
+ */
+export type OutboundEncryptionSession = {
+    key: Uint8Array<ArrayBuffer>;
+    creationTS: number;
+    // The devices that this key is shared with.
+    sharedWith: Array<ParticipantDeviceInfo>;
+    // This is an index acting as the id of the key
+    keyId: number;
+};
+
+export interface EncryptionKeysEventContent {
+    keys: EncryptionKeyEntry[];
+    device_id: string;
+    call_id: string;
+    sent_ts?: number;
+}
+
+/**
+ * THe content of a to-device event that contains encryption keys.
+ */
+export interface EncryptionKeysToDeviceEventContent {
+    keys: { index: number; key: string };
+    member: {
+        id: string;
+        // TODO Remove that it is claimed, need to get the sealed sender from decryption info
+        // Or add some validation on it based on the encryption info
+        claimed_device_id: string;
+    };
+    room_id: string;
+    session: {
+        application: string;
+        call_id: string;
+        scope: string;
+    };
+    // Why is this needed?
+    sent_ts?: number;
+}
+/**
+ * @deprecated Use `RTCNotificationType` instead.
+ */
+export type CallNotifyType = "ring" | "notify";
+/**
+ * @deprecated Use `IRTCNotificationContent` instead.
+ */
+export interface ICallNotifyContent {
+    "application": string;
+    "m.mentions": IMentions;
+    "notify_type": CallNotifyType;
+    "call_id": string;
+}
+
+export type RTCNotificationType = "ring" | "notification";
+
+/**
+ * Represents the intention of the call from the perspective of the sending user.
+ * May be any string, although `"audio"` and `"video"` are commonly accepted values.
+ */
+export type RTCCallIntent = "audio" | "video" | string;
+
+/**
+ * This will check if the content has all the expected fields to be a valid IRTCNotificationContent.
+ * It will also cap the lifetime to 90000ms (1.5 min) if a higher value is provided.
+ * @param content
+ * @throws if the content is invalid
+ * @returns a parsed IRTCNotificationContent
+ */
+export function parseCallNotificationContent(content: IContent): IRTCNotificationContent {
+    if (content["m.mentions"] && typeof content["m.mentions"] !== "object") {
+        throw new Error("malformed m.mentions");
+    }
+    if (typeof content["notification_type"] !== "string") {
+        throw new Error("Missing or invalid notification_type");
+    }
+    if (typeof content["sender_ts"] !== "number") {
+        throw new Error("Missing or invalid sender_ts");
+    }
+    if (typeof content["lifetime"] !== "number") {
+        throw new Error("Missing or invalid lifetime");
+    }
+
+    if (content["relation"] && content["relation"]["rel_type"] !== "m.reference") {
+        throw new Error("Invalid relation");
+    }
+    if (content["m.call.intent"] && typeof content["m.call.intent"] !== "string") {
+        throw new Error("Invalid m.call.intent");
+    }
+
+    const cappedLifetime = content["lifetime"] >= 90000 ? 90000 : content["lifetime"];
+    return { ...content, lifetime: cappedLifetime } as IRTCNotificationContent;
+}
+
+/**
+ * Interface for `org.matrix.msc4075.rtc.notification` events.
+ * Don't cast event content to this directly. Use `parseCallNotificationContent` instead to validate the content first.
+ */
+export interface IRTCNotificationContent extends RelationEvent {
+    "m.mentions"?: IMentions;
+    "notification_type": RTCNotificationType;
+    /**
+     * The initial intent of the calling user.
+     */
+    "m.call.intent"?: RTCCallIntent;
+    "sender_ts": number;
+    "lifetime": number;
+}
+
+/**
+ * MSC4310 decline event content for `org.matrix.msc4310.rtc.decline`.
+ * Sent as a standard m.reference relation to an `org.matrix.msc4075.rtc.notification` event.
+ */
+export interface IRTCDeclineContent extends RelationEvent {}
+
+export enum Status {
+    Disconnected = "Disconnected",
+    Connecting = "Connecting",
+    Connected = "Connected",
+    Disconnecting = "Disconnecting",
+    Unknown = "Unknown",
+}
+
+/**
+ * A type collecting call encryption statistics for a session.
+ */
+export type Statistics = {
+    counters: {
+        /**
+         * The number of times we have sent a room event containing encryption keys.
+         */
+        roomEventEncryptionKeysSent: number;
+        /**
+         * The number of times we have received a room event containing encryption keys.
+         */
+        roomEventEncryptionKeysReceived: number;
+    };
+    totals: {
+        /**
+         * The total age (in milliseconds) of all room events containing encryption keys that we have received.
+         * We track the total age so that we can later calculate the average age of all keys received.
+         */
+        roomEventEncryptionKeysReceivedTotalAge: number;
+    };
+};
+
+export const isMyMembership = (m: CallMembership, userId: string, deviceId: string): boolean =>
+    m.sender === userId && m.deviceId === deviceId;
+
+/**
+ *  A RTC transport is a JSON object that describes how to connect to a RTC member.
+ */
+export interface Transport {
+    type: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Event content for a `m.rtc.slot` state event.
+ */
+export interface RtcSlotEventContent<T extends string = string> {
+    application: {
+        type: T;
+        // other application specific keys
+        [key: string]: unknown;
+    };
+    slot_id: string;
+}
+
+/**
+ * The session description is used to identify a session. Used in the state event.
+ */
+export interface SlotDescription {
+    /**
+     * The application type. e.g. "m.call".
+     */
+    application: string;
+    /**
+     * The application-specific slot ID. e.g. "ROOM".
+     */
+    id: string;
+}

package/src/matrixrtc/utils.ts

@@ -0,0 +1,71 @@
+/*
+Copyright 2025-2026 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { getEncryptionKeyMapKey, type CallMembershipIdentityParts } from "./EncryptionManager.ts";
+import type { InboundEncryptionSession, EncryptionKeyMapKey, SlotDescription } from "./types.ts";
+
+/**
+ * Detects when a key for a given index is outdated.
+ */
+export class OutdatedKeyFilter {
+    // Map of participantId -> keyIndex -> timestamp
+    private tsBuffer: Map<EncryptionKeyMapKey, Map<number, number>> = new Map();
+
+    public constructor() {}
+
+    /**
+     * Check if there is a recent key with the same keyId (index) and then use the creationTS to decide what to
+     * do with the key. If the key received is older than the one already in the buffer, it is ignored.
+     * @param participantId
+     * @param item
+     */
+    public isOutdated(membership: CallMembershipIdentityParts, item: InboundEncryptionSession): boolean {
+        const mapKey = getEncryptionKeyMapKey(membership);
+        if (!this.tsBuffer.has(mapKey)) {
+            this.tsBuffer.set(mapKey, new Map<number, number>());
+        }
+
+        const latestTimestamp = this.tsBuffer.get(mapKey)?.get(item.keyIndex);
+        if (latestTimestamp && latestTimestamp > item.creationTS) {
+            // The existing key is more recent, ignore this one
+            return true;
+        }
+        this.tsBuffer.get(mapKey)!.set(item.keyIndex, item.creationTS);
+        return false;
+    }
+}
+
+/**
+ * Converts a slot ID into it's component application and ID portions.
+ * @param slotId e.g. `m.call#call_id`
+ * @throws If the format of `slotId` is invalid.
+ */
+export function slotIdToDescription(slotId: string): SlotDescription {
+    const [application, id, ...unexpectedAdditionalValues] = slotId.split("#");
+    if (unexpectedAdditionalValues.length) {
+        throw Error(
+            "MatrixRTC Slot IDs *must* only contain two components seperated by one '#'. Additional '#' characters detected.",
+        );
+    }
+    return { application, id };
+}
+
+/**
+ * Converts a SlotDescription into it's slot ID format.
+ */
+export function computeSlotId(slotDescription: SlotDescription): string {
+    return `${slotDescription.application}#${slotDescription.id}`;
+}

package/src/models/MSC3089Branch.ts

@@ -0,0 +1,272 @@
+/*
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { type BriijClient } from "../client.ts";
+import { RelationType, UNSTABLE_MSC3089_BRANCH } from "../@types/event.ts";
+import { type IContent, type BriijEvent } from "./event.ts";
+import { type MSC3089TreeSpace } from "./MSC3089TreeSpace.ts";
+import { EventTimeline } from "./event-timeline.ts";
+import { type FileType } from "../http-api/index.ts";
+import type { ISendEventResponse } from "../@types/requests.ts";
+import { type EncryptedFile } from "../@types/media.ts";
+
+export interface MSC3089EventContent {
+    active?: boolean;
+    name?: string;
+    locked?: boolean;
+    version?: number;
+}
+
+export interface MSC3089EventContent {
+    active?: boolean;
+    name?: string;
+    locked?: boolean;
+    version?: number;
+}
+
+/**
+ * Represents a [MSC3089](https://github.com/matrix-org/matrix-doc/pull/3089) branch - a reference
+ * to a file (leaf) in the tree. Note that this is UNSTABLE and subject to breaking changes
+ * without notice.
+ */
+export class MSC3089Branch {
+    public constructor(
+        private client: BriijClient,
+        public readonly indexEvent: BriijEvent,
+        public readonly directory: MSC3089TreeSpace,
+    ) {
+        // Nothing to do
+    }
+
+    /**
+     * The file ID.
+     */
+    public get id(): string {
+        const stateKey = this.indexEvent.getStateKey();
+        if (!stateKey) {
+            throw new Error("State key not found for branch");
+        }
+        return stateKey;
+    }
+
+    /**
+     * Whether this branch is active/valid.
+     */
+    public get isActive(): boolean {
+        return this.indexEvent.getContent()["active"] === true;
+    }
+
+    /**
+     * Version for the file, one-indexed.
+     */
+    public get version(): number {
+        return this.indexEvent.getContent()["version"] ?? 1;
+    }
+
+    private get roomId(): string {
+        return this.indexEvent.getRoomId()!;
+    }
+
+    /**
+     * Deletes the file from the tree, including all prior edits/versions.
+     * @returns Promise which resolves when complete.
+     */
+    public async delete(): Promise<void> {
+        await this.client.sendStateEvent(this.roomId, UNSTABLE_MSC3089_BRANCH.name, {}, this.id);
+        await this.client.redactEvent(this.roomId, this.id);
+
+        const nextVersion = (await this.getVersionHistory())[1]; // [0] will be us
+        if (nextVersion) await nextVersion.delete(); // implicit recursion
+    }
+
+    /**
+     * Gets the name for this file.
+     * @returns The name, or "Unnamed File" if unknown.
+     */
+    public getName(): string {
+        return this.indexEvent.getContent()["name"] || "Unnamed File";
+    }
+
+    /**
+     * Sets the name for this file.
+     * @param name - The new name for this file.
+     * @returns Promise which resolves when complete.
+     */
+    public async setName(name: string): Promise<void> {
+        await this.client.sendStateEvent(
+            this.roomId,
+            UNSTABLE_MSC3089_BRANCH.name,
+            {
+                ...this.indexEvent.getContent(),
+                name: name,
+            },
+            this.id,
+        );
+    }
+
+    /**
+     * Gets whether or not a file is locked.
+     * @returns True if locked, false otherwise.
+     */
+    public isLocked(): boolean {
+        return this.indexEvent.getContent()["locked"] || false;
+    }
+
+    /**
+     * Sets a file as locked or unlocked.
+     * @param locked - True to lock the file, false otherwise.
+     * @returns Promise which resolves when complete.
+     */
+    public async setLocked(locked: boolean): Promise<void> {
+        await this.client.sendStateEvent(
+            this.roomId,
+            UNSTABLE_MSC3089_BRANCH.name,
+            {
+                ...this.indexEvent.getContent(),
+                locked: locked,
+            },
+            this.id,
+        );
+    }
+
+    /**
+     * Gets information about the file needed to download it.
+     * @returns Information about the file.
+     */
+    public async getFileInfo(): Promise<{ info: EncryptedFile; httpUrl: string }> {
+        const event = await this.getFileEvent();
+
+        const file = event.getOriginalContent()["file"];
+        const httpUrl = this.client.mxcUrlToHttp(file["url"]);
+
+        if (!httpUrl) {
+            throw new Error(`No HTTP URL available for ${file["url"]}`);
+        }
+
+        return { info: file, httpUrl: httpUrl };
+    }
+
+    /**
+     * Gets the event the file points to.
+     * @returns Promise which resolves to the file's event.
+     */
+    public async getFileEvent(): Promise<BriijEvent> {
+        const room = this.client.getRoom(this.roomId);
+        if (!room) throw new Error("Unknown room");
+
+        let event: BriijEvent | undefined = room.getUnfilteredTimelineSet().findEventById(this.id);
+
+        // keep scrolling back if needed until we find the event or reach the start of the room:
+        while (!event && room.getLiveTimeline().getState(EventTimeline.BACKWARDS)!.paginationToken) {
+            await this.client.scrollback(room, 100);
+            event = room.getUnfilteredTimelineSet().findEventById(this.id);
+        }
+
+        if (!event) throw new Error("Failed to find event");
+
+        // Sometimes the event isn't decrypted for us, so do that.
+        await this.client.decryptEventIfNeeded(event);
+
+        return event;
+    }
+
+    /**
+     * Creates a new version of this file with contents in a type that is compatible with BriijClient.uploadContent().
+     * @param name - The name of the file.
+     * @param encryptedContents - The encrypted contents.
+     * @param info - The encrypted file information.
+     * @param additionalContent - Optional event content fields to include in the message.
+     * @returns Promise which resolves to the file event's sent response.
+     */
+    public async createNewVersion(
+        name: string,
+        encryptedContents: FileType,
+        info: EncryptedFile,
+        additionalContent?: IContent,
+    ): Promise<ISendEventResponse> {
+        const fileEventResponse = await this.directory.createFile(name, encryptedContents, info, {
+            ...(additionalContent ?? {}),
+            "m.new_content": true,
+            "m.relates_to": {
+                rel_type: RelationType.Replace,
+                event_id: this.id,
+            },
+        });
+
+        // Update the version of the new event
+        await this.client.sendStateEvent(
+            this.roomId,
+            UNSTABLE_MSC3089_BRANCH.name,
+            {
+                active: true,
+                name: name,
+                version: this.version + 1,
+            },
+            fileEventResponse["event_id"],
+        );
+
+        // Deprecate ourselves
+        await this.client.sendStateEvent(
+            this.roomId,
+            UNSTABLE_MSC3089_BRANCH.name,
+            {
+                ...this.indexEvent.getContent(),
+                active: false,
+            },
+            this.id,
+        );
+
+        return fileEventResponse;
+    }
+
+    /**
+     * Gets the file's version history, starting at this file.
+     * @returns Promise which resolves to the file's version history, with the
+     * first element being the current version and the last element being the first version.
+     */
+    public async getVersionHistory(): Promise<MSC3089Branch[]> {
+        const fileHistory: MSC3089Branch[] = [];
+        fileHistory.push(this); // start with ourselves
+
+        const room = this.client.getRoom(this.roomId);
+        if (!room) throw new Error("Invalid or unknown room");
+
+        // Clone the timeline to reverse it, getting most-recent-first ordering, hopefully
+        // shortening the awful loop below. Without the clone, we can unintentionally mutate
+        // the timeline.
+        const timelineEvents = [...room.getLiveTimeline().getEvents()].reverse();
+
+        // XXX: This is a very inefficient search, but it's the best we can do with the
+        // relations structure we have in the SDK. As of writing, it is not worth the
+        // investment in improving the structure.
+        let childEvent: BriijEvent | undefined;
+        let parentEvent = await this.getFileEvent();
+        do {
+            childEvent = timelineEvents.find((e) => e.replacingEventId() === parentEvent.getId());
+            if (childEvent) {
+                const branch = this.directory.getFile(childEvent.getId()!);
+                if (branch) {
+                    fileHistory.push(branch);
+                    parentEvent = childEvent;
+                } else {
+                    break; // prevent infinite loop
+                }
+            }
+        } while (childEvent);
+
+        return fileHistory;
+    }
+}