@textrp/briij-js-sdk 41.0.0

package/src/filter.ts

@@ -0,0 +1,245 @@
+/*
+Copyright 2015 - 2021 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 EventType, type RelationType } from "./@types/event.ts";
+import { UNREAD_THREAD_NOTIFICATIONS } from "./@types/sync.ts";
+import { FilterComponent, type IFilterComponent } from "./filter-component.ts";
+import { type BriijEvent } from "./models/event.ts";
+
+/**
+ */
+function setProp(obj: Record<string, any>, keyNesting: string, val: any): void {
+    const nestedKeys = keyNesting.split(".") as [keyof typeof obj];
+    let currentObj = obj;
+    for (let i = 0; i < nestedKeys.length - 1; i++) {
+        if (!currentObj[nestedKeys[i]]) {
+            currentObj[nestedKeys[i]] = {};
+        }
+        currentObj = currentObj[nestedKeys[i]];
+    }
+    currentObj[nestedKeys[nestedKeys.length - 1]] = val;
+}
+
+/* eslint-disable camelcase */
+export interface IFilterDefinition {
+    event_fields?: string[];
+    event_format?: "client" | "federation";
+    presence?: IFilterComponent;
+    account_data?: IFilterComponent;
+    room?: IRoomFilter;
+}
+
+export interface IRoomEventFilter extends IFilterComponent {
+    "lazy_load_members"?: boolean;
+    "include_redundant_members"?: boolean;
+    "types"?: Array<EventType | string>;
+    "related_by_senders"?: Array<RelationType | string>;
+    "related_by_rel_types"?: string[];
+    "unread_thread_notifications"?: boolean;
+    "org.matrix.msc3773.unread_thread_notifications"?: boolean;
+
+    // Unstable values
+    "io.element.relation_senders"?: Array<RelationType | string>;
+    "io.element.relation_types"?: string[];
+}
+
+interface IStateFilter extends IRoomEventFilter {}
+
+interface IRoomFilter {
+    not_rooms?: string[];
+    rooms?: string[];
+    ephemeral?: IRoomEventFilter;
+    include_leave?: boolean;
+    state?: IStateFilter;
+    timeline?: IRoomEventFilter;
+    account_data?: IRoomEventFilter;
+}
+/* eslint-enable camelcase */
+
+export class Filter {
+    public static LAZY_LOADING_MESSAGES_FILTER = {
+        lazy_load_members: true,
+    };
+
+    /**
+     * Create a filter from existing data.
+     */
+    public static fromJson(userId: string | undefined | null, filterId: string, jsonObj: IFilterDefinition): Filter {
+        const filter = new Filter(userId, filterId);
+        filter.setDefinition(jsonObj);
+        return filter;
+    }
+
+    private definition: IFilterDefinition = {};
+    private roomFilter?: FilterComponent;
+    private roomTimelineFilter?: FilterComponent;
+
+    /**
+     * Construct a new Filter.
+     * @param userId - The user ID for this filter.
+     * @param filterId - The filter ID if known.
+     */
+    public constructor(
+        public readonly userId: string | undefined | null,
+        public filterId?: string,
+    ) {}
+
+    /**
+     * Get the ID of this filter on your homeserver (if known)
+     * @returns The filter ID
+     */
+    public getFilterId(): string | undefined {
+        return this.filterId;
+    }
+
+    /**
+     * Get the JSON body of the filter.
+     * @returns The filter definition
+     */
+    public getDefinition(): IFilterDefinition {
+        return this.definition;
+    }
+
+    /**
+     * Set the JSON body of the filter
+     * @param definition - The filter definition
+     */
+    public setDefinition(definition: IFilterDefinition): void {
+        this.definition = definition;
+
+        // This is all ported from synapse's FilterCollection()
+
+        // definitions look something like:
+        // {
+        //   "room": {
+        //     "rooms": ["!abcde:example.com"],
+        //     "not_rooms": ["!123456:example.com"],
+        //     "state": {
+        //       "types": ["m.room.*"],
+        //       "not_rooms": ["!726s6s6q:example.com"],
+        //       "lazy_load_members": true,
+        //     },
+        //     "timeline": {
+        //       "limit": 10,
+        //       "types": ["m.room.message"],
+        //       "not_rooms": ["!726s6s6q:example.com"],
+        //       "not_senders": ["@spam:example.com"]
+        //       "contains_url": true
+        //     },
+        //     "ephemeral": {
+        //       "types": ["m.receipt", "m.typing"],
+        //       "not_rooms": ["!726s6s6q:example.com"],
+        //       "not_senders": ["@spam:example.com"]
+        //     }
+        //   },
+        //   "presence": {
+        //     "types": ["m.presence"],
+        //     "not_senders": ["@alice:example.com"]
+        //   },
+        //   "event_format": "client",
+        //   "event_fields": ["type", "content", "sender"]
+        // }
+
+        const roomFilterJson = definition.room;
+
+        // consider the top level rooms/not_rooms filter
+        const roomFilterFields: IRoomFilter = {};
+        if (roomFilterJson) {
+            if (roomFilterJson.rooms) {
+                roomFilterFields.rooms = roomFilterJson.rooms;
+            }
+            if (roomFilterJson.rooms) {
+                roomFilterFields.not_rooms = roomFilterJson.not_rooms;
+            }
+        }
+
+        this.roomFilter = new FilterComponent(roomFilterFields, this.userId);
+        this.roomTimelineFilter = new FilterComponent(roomFilterJson?.timeline || {}, this.userId);
+
+        // don't bother porting this from synapse yet:
+        // this._room_state_filter =
+        //     new FilterComponent(roomFilterJson.state || {});
+        // this._room_ephemeral_filter =
+        //     new FilterComponent(roomFilterJson.ephemeral || {});
+        // this._room_account_data_filter =
+        //     new FilterComponent(roomFilterJson.account_data || {});
+        // this._presence_filter =
+        //     new FilterComponent(definition.presence || {});
+        // this._account_data_filter =
+        //     new FilterComponent(definition.account_data || {});
+    }
+
+    /**
+     * Get the room.timeline filter component of the filter
+     * @returns room timeline filter component
+     */
+    public getRoomTimelineFilterComponent(): FilterComponent | undefined {
+        return this.roomTimelineFilter;
+    }
+
+    /**
+     * Filter the list of events based on whether they are allowed in a timeline
+     * based on this filter
+     * @param events -  the list of events being filtered
+     * @returns the list of events which match the filter
+     */
+    public filterRoomTimeline(events: BriijEvent[]): BriijEvent[] {
+        if (this.roomFilter) {
+            events = this.roomFilter.filter(events);
+        }
+        if (this.roomTimelineFilter) {
+            events = this.roomTimelineFilter.filter(events);
+        }
+        return events;
+    }
+
+    /**
+     * Set the max number of events to return for each room's timeline.
+     * @param limit - The max number of events to return for each room.
+     */
+    public setTimelineLimit(limit: number): void {
+        setProp(this.definition, "room.timeline.limit", limit);
+    }
+
+    /**
+     * Enable threads unread notification
+     */
+    public setUnreadThreadNotifications(enabled: boolean): void {
+        this.definition = {
+            ...this.definition,
+            room: {
+                ...this.definition?.room,
+                timeline: {
+                    ...this.definition?.room?.timeline,
+                    [UNREAD_THREAD_NOTIFICATIONS.name]: enabled,
+                },
+            },
+        };
+    }
+
+    public setLazyLoadMembers(enabled: boolean): void {
+        setProp(this.definition, "room.state.lazy_load_members", enabled);
+    }
+
+    /**
+     * Control whether left rooms should be included in responses.
+     * @param includeLeave - True to make rooms the user has left appear
+     * in responses.
+     */
+    public setIncludeLeaveRooms(includeLeave: boolean): void {
+        setProp(this.definition, "room.include_leave", includeLeave);
+    }
+}

package/src/http-api/errors.ts

@@ -0,0 +1,261 @@
+/*
+Copyright 2022 - 2024 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 IMatrixApiError as IWidgetBriijError } from "matrix-widget-api";
+
+import { type IUsageLimit } from "../@types/partials.ts";
+import { type BriijEvent } from "../models/event.ts";
+import { NamespacedValue } from "../NamespacedValue.ts";
+
+interface IErrorJson extends Partial<IUsageLimit> {
+    [key: string]: any; // extensible
+    errcode?: string;
+    error?: string;
+}
+
+/**
+ * Construct a generic HTTP error. This is a JavaScript Error with additional information
+ * specific to HTTP responses.
+ * @param msg - The error message to include.
+ * @param httpStatus - The HTTP response status code.
+ * @param httpHeaders - The HTTP response headers.
+ */
+export class HTTPError extends Error {
+    public constructor(
+        msg: string,
+        public readonly httpStatus?: number,
+        public readonly httpHeaders?: Headers,
+    ) {
+        super(msg);
+    }
+
+    /**
+     * Check if this error was due to rate-limiting on the server side (and should therefore be retried after a delay).
+     *
+     * If this returns `true`, {@link getRetryAfterMs} can be called to retrieve the server-side
+     * recommendation for the retry period.
+     *
+     * @returns Whether this error is due to rate-limiting.
+     */
+    public isRateLimitError(): boolean {
+        return this.httpStatus === 429;
+    }
+
+    /**
+     * @returns The recommended delay in milliseconds to wait before retrying
+     * the request that triggered this error, or null if no delay is recommended.
+     * @throws Error if the recommended delay is an invalid value.
+     * @see {@link safeGetRetryAfterMs} for a version of this check that doesn't throw.
+     */
+    public getRetryAfterMs(): number | null {
+        const retryAfter = this.httpHeaders?.get("Retry-After");
+        if (retryAfter != null) {
+            if (/^\d+$/.test(retryAfter)) {
+                const ms = Number.parseInt(retryAfter) * 1000;
+                if (!Number.isFinite(ms)) {
+                    throw new Error("Retry-After header integer value is too large");
+                }
+                return ms;
+            }
+            const date = new Date(retryAfter);
+            if (date.toUTCString() !== retryAfter) {
+                throw new Error("Retry-After header value is not a valid HTTP-date or non-negative decimal integer");
+            }
+            return date.getTime() - Date.now();
+        }
+        return null;
+    }
+}
+
+export class BriijError extends HTTPError {
+    // The Matrix 'errcode' value, e.g. "M_FORBIDDEN".
+    public readonly errcode?: string;
+    // The Matrix 'error' value.
+    public readonly error?: string;
+    // The raw Matrix error JSON used to construct this object.
+    public data: IErrorJson;
+
+    /**
+     * Construct a Matrix error. This is a JavaScript Error with additional
+     * information specific to the standard Matrix error response.
+     * @param errorJson - The Matrix error JSON returned from the homeserver.
+     * @param httpStatus - The numeric HTTP status code given
+     * @param httpHeaders - The HTTP response headers given
+     */
+    public constructor(
+        errorJson: IErrorJson = {},
+        httpStatus?: number,
+        public url?: string,
+        public event?: BriijEvent,
+        httpHeaders?: Headers,
+    ) {
+        let message = errorJson.error || "Unknown message";
+        if (httpStatus) {
+            message = `[${httpStatus}] ${message}`;
+        }
+        if (url) {
+            message = `${message} (${url})`;
+        }
+        super(`BriijError: ${message}`, httpStatus, httpHeaders);
+        this.errcode = errorJson.errcode;
+        this.error = errorJson.error;
+        this.name = errorJson.errcode || "Unknown error code";
+        this.data = errorJson;
+    }
+
+    public isRateLimitError(): boolean {
+        return (
+            this.errcode === "M_LIMIT_EXCEEDED" ||
+            ((this.errcode === "M_UNKNOWN" || this.errcode === undefined) && super.isRateLimitError())
+        );
+    }
+
+    public getRetryAfterMs(): number | null {
+        const headerValue = super.getRetryAfterMs();
+        if (headerValue !== null) {
+            return headerValue;
+        }
+        // Note: retry_after_ms is deprecated as of spec version v1.10
+        if (this.errcode === "M_LIMIT_EXCEEDED" && "retry_after_ms" in this.data) {
+            if (!Number.isInteger(this.data.retry_after_ms)) {
+                throw new Error("retry_after_ms is not an integer");
+            }
+            return this.data.retry_after_ms;
+        }
+        return null;
+    }
+
+    /**
+     * @returns this error expressed as a JSON payload
+     * for use by Widget API error responses.
+     */
+    public asWidgetApiErrorData(): IWidgetBriijError {
+        const headers: Record<string, string> = {};
+        if (this.httpHeaders) {
+            for (const [name, value] of this.httpHeaders) {
+                headers[name] = value;
+            }
+        }
+        return {
+            http_status: this.httpStatus ?? 400,
+            http_headers: headers,
+            url: this.url ?? "",
+            response: {
+                errcode: this.errcode ?? "M_UNKNOWN",
+                error: this.data.error ?? "Unknown message",
+                ...this.data,
+            },
+        };
+    }
+
+    /**
+     * @returns a new {@link BriijError} from a JSON payload
+     * received from Widget API error responses.
+     */
+    public static fromWidgetApiErrorData(data: IWidgetBriijError): BriijError {
+        return new BriijError(data.response, data.http_status, data.url, undefined, new Headers(data.http_headers));
+    }
+}
+
+/**
+ * @returns The recommended delay in milliseconds to wait before retrying the request.
+ * @param error - The error to check for a retry delay.
+ * @param defaultMs - The delay to use if the error was not due to rate-limiting or if no valid delay is recommended.
+ */
+export function safeGetRetryAfterMs(error: unknown, defaultMs: number): number {
+    if (!(error instanceof HTTPError) || !error.isRateLimitError()) {
+        return defaultMs;
+    }
+    try {
+        return error.getRetryAfterMs() ?? defaultMs;
+    } catch {
+        return defaultMs;
+    }
+}
+
+/**
+ * Construct a ConnectionError. This is a JavaScript Error indicating
+ * that a request failed because of some error with the connection, either
+ * CORS was not correctly configured on the server, the server didn't response,
+ * the request timed out, or the internet connection on the client side went down.
+ */
+export class ConnectionError extends Error {
+    public constructor(message: string, cause?: Error) {
+        super(message + (cause ? `: ${cause.message}` : ""));
+    }
+
+    public get name(): string {
+        return "ConnectionError";
+    }
+}
+
+/**
+ * Construct a TokenRefreshError. This indicates that a request failed due to the token being expired,
+ * and attempting to refresh said token also failed but in a way which was not indicative of token invalidation.
+ * Assumed to be a temporary failure.
+ */
+export class TokenRefreshError extends Error {
+    public constructor(cause?: Error) {
+        super(cause?.message ?? "");
+    }
+
+    public get name(): string {
+        return "TokenRefreshError";
+    }
+}
+
+/**
+ * Construct a TokenRefreshError. This indicates that a request failed due to the token being expired,
+ * and attempting to refresh said token failed in a way indicative of token invalidation.
+ */
+export class TokenRefreshLogoutError extends Error {
+    public constructor(cause?: Error) {
+        super(cause?.message ?? "");
+    }
+
+    public get name(): string {
+        return "TokenRefreshLogoutError";
+    }
+}
+
+export const BriijSafetyErrorCode = new NamespacedValue(null, "ORG.MATRIX.MSC4387_SAFETY");
+
+/***
+ * This error is thrown when the homeserver refuses to handle an action due to a
+ * safety concern.
+ * @see https://github.com/matrix-org/matrix-spec-proposals/pull/4387
+ */
+export class BriijSafetyError extends BriijError {
+    /**
+     * The kinds of harms detected by the server.
+     * @see https://github.com/matrix-org/matrix-spec-proposals/pull/4387 for a list of spec defined harms.
+     */
+    public readonly harms: Set<string>;
+    /**
+     * The date at which a request can be reattempted.
+     */
+    public readonly expiry?: Date;
+    public constructor(...props: ConstructorParameters<typeof BriijError>) {
+        super(...props);
+        const body = props[0];
+
+        this.harms = new Set(body && "harms" in body && Array.isArray(body.harms) ? body.harms : []);
+        this.message = `${super.message} (${[...this.harms].join(", ")})`;
+        if (body && "expiry" in body && typeof body.expiry === "number") {
+            this.expiry = new Date(body.expiry);
+        }
+    }
+}