@textrp/briij-js-sdk 41.0.0

package/src/extensible_events_v1/PollStartEvent.ts

@@ -0,0 +1,207 @@
+/*
+Copyright 2022 - 2023 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 { NamespacedValue } from "matrix-events-sdk";
+
+import { MessageEvent } from "./MessageEvent.ts";
+import { type ExtensibleEventType, type IPartialEvent, isEventTypeSame, M_TEXT } from "../@types/extensible_events.ts";
+import {
+    type KnownPollKind,
+    M_POLL_KIND_DISCLOSED,
+    M_POLL_KIND_UNDISCLOSED,
+    M_POLL_START,
+    type PollStartEventContent,
+    type PollStartSubtype,
+    type PollAnswer,
+} from "../@types/polls.ts";
+import { InvalidEventError } from "./InvalidEventError.ts";
+import { ExtensibleEvent } from "./ExtensibleEvent.ts";
+
+/**
+ * Represents a poll answer. Note that this is represented as a subtype and is
+ * not registered as a parsable event - it is implied for usage exclusively
+ * within the PollStartEvent parsing.
+ */
+export class PollAnswerSubevent extends MessageEvent {
+    /**
+     * The answer ID.
+     */
+    public readonly id: string;
+
+    public constructor(wireFormat: IPartialEvent<PollAnswer>) {
+        super(wireFormat);
+
+        const id = wireFormat.content.id;
+        if (!id || typeof id !== "string") {
+            throw new InvalidEventError("Answer ID must be a non-empty string");
+        }
+        this.id = id;
+    }
+
+    public serialize(): IPartialEvent<object> {
+        return {
+            type: "org.matrix.sdk.poll.answer",
+            content: {
+                id: this.id,
+                ...this.serializeMMessageOnly(),
+            },
+        };
+    }
+
+    /**
+     * Creates a new PollAnswerSubevent from ID and text.
+     * @param id - The answer ID (unique within the poll).
+     * @param text - The text.
+     * @returns The representative answer.
+     */
+    public static from(id: string, text: string): PollAnswerSubevent {
+        return new PollAnswerSubevent({
+            type: "org.matrix.sdk.poll.answer",
+            content: {
+                id: id,
+                [M_TEXT.name]: text,
+            },
+        });
+    }
+}
+
+/**
+ * Represents a poll start event.
+ */
+export class PollStartEvent extends ExtensibleEvent<PollStartEventContent> {
+    /**
+     * The question being asked, as a MessageEvent node.
+     */
+    public readonly question: MessageEvent;
+
+    /**
+     * The interpreted kind of poll. Note that this will infer a value that is known to the
+     * SDK rather than verbatim - this means unknown types will be represented as undisclosed
+     * polls.
+     *
+     * To get the raw kind, use rawKind.
+     */
+    public readonly kind: KnownPollKind;
+
+    /**
+     * The true kind as provided by the event sender. Might not be valid.
+     */
+    public readonly rawKind: string;
+
+    /**
+     * The maximum number of selections a user is allowed to make.
+     */
+    public readonly maxSelections: number;
+
+    /**
+     * The possible answers for the poll.
+     */
+    public readonly answers: PollAnswerSubevent[];
+
+    /**
+     * Creates a new PollStartEvent from a pure format. Note that the event is *not*
+     * parsed here: it will be treated as a literal m.poll.start primary typed event.
+     * @param wireFormat - The event.
+     */
+    public constructor(wireFormat: IPartialEvent<PollStartEventContent>) {
+        super(wireFormat);
+
+        const poll = M_POLL_START.findIn<PollStartSubtype>(this.wireContent);
+
+        if (!poll?.question) {
+            throw new InvalidEventError("A question is required");
+        }
+
+        this.question = new MessageEvent({ type: "org.matrix.sdk.poll.question", content: poll.question });
+
+        this.rawKind = poll.kind;
+        if (M_POLL_KIND_DISCLOSED.matches(this.rawKind)) {
+            this.kind = M_POLL_KIND_DISCLOSED;
+        } else {
+            this.kind = M_POLL_KIND_UNDISCLOSED; // default & assumed value
+        }
+
+        this.maxSelections =
+            Number.isFinite(poll.max_selections) && poll.max_selections! > 0 ? poll.max_selections! : 1;
+
+        if (!Array.isArray(poll.answers)) {
+            throw new InvalidEventError("Poll answers must be an array");
+        }
+        const answers = poll.answers.slice(0, 20).map(
+            (a) =>
+                new PollAnswerSubevent({
+                    type: "org.matrix.sdk.poll.answer",
+                    content: a,
+                }),
+        );
+        if (answers.length <= 0) {
+            throw new InvalidEventError("No answers available");
+        }
+        this.answers = answers;
+    }
+
+    public isEquivalentTo(primaryEventType: ExtensibleEventType): boolean {
+        return isEventTypeSame(primaryEventType, M_POLL_START);
+    }
+
+    public serialize(): IPartialEvent<object> {
+        return {
+            type: M_POLL_START.name,
+            content: {
+                [M_POLL_START.name]: {
+                    question: this.question.serialize().content,
+                    kind: this.rawKind,
+                    max_selections: this.maxSelections,
+                    answers: this.answers.map((a) => a.serialize().content),
+                },
+                [M_TEXT.name]: `${this.question.text}\n${this.answers.map((a, i) => `${i + 1}. ${a.text}`).join("\n")}`,
+            },
+        };
+    }
+
+    /**
+     * Creates a new PollStartEvent from question, answers, and metadata.
+     * @param question - The question to ask.
+     * @param answers - The answers. Should be unique within each other.
+     * @param kind - The kind of poll.
+     * @param maxSelections - The maximum number of selections. Must be 1 or higher.
+     * @returns The representative poll start event.
+     */
+    public static from(
+        question: string,
+        answers: string[],
+        kind: KnownPollKind | string,
+        maxSelections = 1,
+    ): PollStartEvent {
+        return new PollStartEvent({
+            type: M_POLL_START.name,
+            content: {
+                [M_TEXT.name]: question, // unused by parsing
+                [M_POLL_START.name]: {
+                    question: { [M_TEXT.name]: question },
+                    kind: kind instanceof NamespacedValue ? kind.name : kind,
+                    max_selections: maxSelections,
+                    answers: answers.map((a) => ({ id: makeId(), [M_TEXT.name]: a })),
+                },
+            },
+        });
+    }
+}
+
+const LETTERS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+function makeId(): string {
+    return [...Array(16)].map(() => LETTERS.charAt(Math.floor(Math.random() * LETTERS.length))).join("");
+}

package/src/extensible_events_v1/utilities.ts

@@ -0,0 +1,35 @@
+/*
+Copyright 2021 - 2023 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 Optional } from "matrix-events-sdk";
+
+/**
+ * Determines if the given optional was provided a value.
+ * @param s - The optional to test.
+ * @returns True if the value is defined.
+ */
+export function isProvided<T>(s: Optional<T>): s is T {
+    return s !== null && s !== undefined;
+}
+
+/**
+ * Determines if the given optional string is a defined string.
+ * @param s - The input string.
+ * @returns True if the input is a defined string.
+ */
+export function isOptionalAString(s: Optional<string>): s is string {
+    return isProvided(s) && typeof s === "string";
+}

package/src/feature.ts

@@ -0,0 +1,88 @@
+/*
+Copyright 2022 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 IServerVersions } from "./client.ts";
+
+export enum ServerSupport {
+    Stable,
+    Unstable,
+    Unsupported,
+}
+
+export enum Feature {
+    Thread = "Thread",
+    ThreadUnreadNotifications = "ThreadUnreadNotifications",
+    /**
+     * @deprecated this is now exposed as a capability not a feature
+     */
+    LoginTokenRequest = "LoginTokenRequest",
+    RelationBasedRedactions = "RelationBasedRedactions",
+    AccountDataDeletion = "AccountDataDeletion",
+    RelationsRecursion = "RelationsRecursion",
+    IntentionalMentions = "IntentionalMentions",
+}
+
+type FeatureSupportCondition = {
+    unstablePrefixes?: string[];
+    matrixVersion?: string;
+};
+
+const featureSupportResolver: Record<string, FeatureSupportCondition> = {
+    [Feature.Thread]: {
+        unstablePrefixes: ["org.matrix.msc3440"],
+        matrixVersion: "v1.3",
+    },
+    [Feature.ThreadUnreadNotifications]: {
+        unstablePrefixes: ["org.matrix.msc3771", "org.matrix.msc3773"],
+        matrixVersion: "v1.4",
+    },
+    [Feature.LoginTokenRequest]: {
+        unstablePrefixes: ["org.matrix.msc3882"],
+    },
+    [Feature.RelationBasedRedactions]: {
+        unstablePrefixes: ["org.matrix.msc3912"],
+    },
+    [Feature.AccountDataDeletion]: {
+        unstablePrefixes: ["org.matrix.msc3391"],
+    },
+    [Feature.RelationsRecursion]: {
+        unstablePrefixes: ["org.matrix.msc3981"],
+        matrixVersion: "v1.10",
+    },
+    [Feature.IntentionalMentions]: {
+        unstablePrefixes: ["org.matrix.msc3952_intentional_mentions"],
+        matrixVersion: "v1.7",
+    },
+};
+
+export async function buildFeatureSupportMap(versions: IServerVersions): Promise<Map<Feature, ServerSupport>> {
+    const supportMap = new Map<Feature, ServerSupport>();
+    for (const [feature, supportCondition] of Object.entries(featureSupportResolver)) {
+        const supportMatrixVersion = versions.versions?.includes(supportCondition.matrixVersion || "") ?? false;
+        const supportUnstablePrefixes =
+            supportCondition.unstablePrefixes?.every((unstablePrefix) => {
+                return versions.unstable_features?.[unstablePrefix] === true;
+            }) ?? false;
+        if (supportMatrixVersion) {
+            supportMap.set(feature as Feature, ServerSupport.Stable);
+        } else if (supportUnstablePrefixes) {
+            supportMap.set(feature as Feature, ServerSupport.Unstable);
+        } else {
+            supportMap.set(feature as Feature, ServerSupport.Unsupported);
+        }
+    }
+    return supportMap;
+}

package/src/filter-component.ts

@@ -0,0 +1,209 @@
+/*
+Copyright 2016 - 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 RelationType } from "./@types/event.ts";
+import { type BriijEvent } from "./models/event.ts";
+import { FILTER_RELATED_BY_REL_TYPES, FILTER_RELATED_BY_SENDERS, THREAD_RELATION_TYPE } from "./models/thread.ts";
+
+/**
+ * Checks if a value matches a given field value, which may be a * terminated
+ * wildcard pattern.
+ * @param actualValue -  The value to be compared
+ * @param filterValue -  The filter pattern to be compared
+ * @returns true if the actualValue matches the filterValue
+ */
+function matchesWildcard(actualValue: string, filterValue: string): boolean {
+    if (filterValue.endsWith("*")) {
+        const typePrefix = filterValue.slice(0, -1);
+        return actualValue.slice(0, typePrefix.length) === typePrefix;
+    } else {
+        return actualValue === filterValue;
+    }
+}
+
+/* eslint-disable camelcase */
+export interface IFilterComponent {
+    "types"?: string[];
+    "not_types"?: string[];
+    "rooms"?: string[];
+    "not_rooms"?: string[];
+    "senders"?: string[];
+    "not_senders"?: string[];
+    "contains_url"?: boolean;
+    "limit"?: number;
+    "related_by_senders"?: Array<RelationType | string>;
+    "related_by_rel_types"?: string[];
+
+    // Unstable values
+    "io.element.relation_senders"?: Array<RelationType | string>;
+    "io.element.relation_types"?: string[];
+}
+/* eslint-enable camelcase */
+
+/**
+ * FilterComponent is a section of a Filter definition which defines the
+ * types, rooms, senders filters etc to be applied to a particular type of resource.
+ * This is all ported over from synapse's Filter object.
+ *
+ * N.B. that synapse refers to these as 'Filters', and what js-sdk refers to as
+ * 'Filters' are referred to as 'FilterCollections'.
+ */
+export class FilterComponent {
+    public constructor(
+        private filterJson: IFilterComponent,
+        public readonly userId?: string | undefined | null,
+    ) {}
+
+    /**
+     * Checks with the filter component matches the given event
+     * @param event - event to be checked against the filter
+     * @returns true if the event matches the filter
+     */
+    public check(event: BriijEvent): boolean {
+        const bundledRelationships = event.getUnsigned()?.["m.relations"] || {};
+        const relations: Array<string | RelationType> = Object.keys(bundledRelationships);
+        // Relation senders allows in theory a look-up of any senders
+        // however clients can only know about the current user participation status
+        // as sending a whole list of participants could be proven problematic in terms
+        // of performance
+        // This should be improved when bundled relationships solve that problem
+        const relationSenders: string[] = [];
+        if (this.userId && bundledRelationships?.[THREAD_RELATION_TYPE.name]?.current_user_participated) {
+            relationSenders.push(this.userId);
+        }
+
+        return this.checkFields(
+            event.getRoomId(),
+            event.getSender(),
+            event.getType(),
+            event.getContent() ? event.getContent().url !== undefined : false,
+            relations,
+            relationSenders,
+        );
+    }
+
+    /**
+     * Converts the filter component into the form expected over the wire
+     */
+    public toJSON(): object {
+        return Object.fromEntries(
+            Object.entries({
+                types: this.filterJson.types,
+                not_types: this.filterJson.not_types,
+                rooms: this.filterJson.rooms,
+                not_rooms: this.filterJson.not_rooms,
+                senders: this.filterJson.senders,
+                not_senders: this.filterJson.not_senders,
+                contains_url: this.filterJson.contains_url,
+                [FILTER_RELATED_BY_SENDERS.name]: this.filterJson[FILTER_RELATED_BY_SENDERS.name],
+                [FILTER_RELATED_BY_REL_TYPES.name]: this.filterJson[FILTER_RELATED_BY_REL_TYPES.name],
+            }).filter(([_key, value]) => value),
+        );
+    }
+
+    /**
+     * Checks whether the filter component matches the given event fields.
+     * @param roomId -        the roomId for the event being checked
+     * @param sender -        the sender of the event being checked
+     * @param eventType -     the type of the event being checked
+     * @param containsUrl -  whether the event contains a content.url field
+     * @param relationTypes -  whether has aggregated relation of the given type
+     * @param relationSenders - whether one of the relation is sent by the user listed
+     * @returns true if the event fields match the filter
+     */
+    private checkFields(
+        roomId: string | undefined,
+        sender: string | undefined,
+        eventType: string,
+        containsUrl: boolean,
+        relationTypes: Array<RelationType | string>,
+        relationSenders: string[],
+    ): boolean {
+        const literalKeys = {
+            rooms: function (v: string): boolean {
+                return roomId === v;
+            },
+            senders: function (v: string): boolean {
+                return sender === v;
+            },
+            types: function (v: string): boolean {
+                return matchesWildcard(eventType, v);
+            },
+        } as const;
+
+        for (const name in literalKeys) {
+            const matchFunc = literalKeys[<keyof typeof literalKeys>name];
+            const notName = "not_" + name;
+            const disallowedValues = this.filterJson[<`not_${keyof typeof literalKeys}`>notName];
+            if (disallowedValues?.some(matchFunc)) {
+                return false;
+            }
+
+            const allowedValues = this.filterJson[name as keyof typeof literalKeys];
+            if (allowedValues && !allowedValues.some(matchFunc)) {
+                return false;
+            }
+        }
+
+        const containsUrlFilter = this.filterJson.contains_url;
+        if (containsUrlFilter !== undefined && containsUrlFilter !== containsUrl) {
+            return false;
+        }
+
+        const relationTypesFilter = this.filterJson[FILTER_RELATED_BY_REL_TYPES.name];
+        if (relationTypesFilter !== undefined) {
+            if (!this.arrayMatchesFilter(relationTypesFilter, relationTypes)) {
+                return false;
+            }
+        }
+
+        const relationSendersFilter = this.filterJson[FILTER_RELATED_BY_SENDERS.name];
+        if (relationSendersFilter !== undefined) {
+            if (!this.arrayMatchesFilter(relationSendersFilter, relationSenders)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private arrayMatchesFilter(filter: any[], values: any[]): boolean {
+        return (
+            values.length > 0 &&
+            filter.every((value) => {
+                return values.includes(value);
+            })
+        );
+    }
+
+    /**
+     * Filters a list of events down to those which match this filter component
+     * @param events -  Events to be checked against the filter component
+     * @returns events which matched the filter component
+     */
+    public filter(events: BriijEvent[]): BriijEvent[] {
+        return events.filter(this.check, this);
+    }
+
+    /**
+     * Returns the limit field for a given filter component, providing a default of
+     * 10 if none is otherwise specified. Cargo-culted from Synapse.
+     * @returns the limit for this filter component.
+     */
+    public limit(): number {
+        return this.filterJson.limit !== undefined ? this.filterJson.limit : 10;
+    }
+}