@matrix-widget-toolkit/api 3.4.2 → 4.0.0

package/build/esm/api/extras/powerLevel.d.ts

@@ -0,0 +1,105 @@
+import { StateEvent } from '../types';
+/**
+ * The name of the power levels state event.
+ */
+export declare const STATE_EVENT_POWER_LEVELS = "m.room.power_levels";
+/**
+ * The types of actions.
+ */
+export type PowerLevelsActions = 'invite' | 'kick' | 'ban' | 'redact';
+/**
+ * The content of an `m.room.power_levels` event.
+ */
+export type PowerLevelsStateEvent = {
+    events?: {
+        [key: string]: number;
+    };
+    state_default?: number;
+    events_default?: number;
+    users?: {
+        [key: string]: number;
+    };
+    users_default?: number;
+    ban?: number;
+    invite?: number;
+    kick?: number;
+    redact?: number;
+};
+/**
+ * Validates that `event` is has a valid structure for a
+ * {@link PowerLevelsStateEvent}.
+ * @param event - The event to validate.
+ * @returns True, if the event is valid.
+ */
+export declare function isValidPowerLevelStateEvent(event: StateEvent<unknown>): event is StateEvent<PowerLevelsStateEvent>;
+/**
+ * Check if a user has the power to send a specific room event.
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event
+ * @param userId - the id of the user
+ * @param eventType - the type of room event
+ * @returns if true, the user has the power
+ */
+export declare function hasRoomEventPower(powerLevelStateEvent: PowerLevelsStateEvent | undefined, userId: string | undefined, eventType: string): boolean;
+/**
+ * Check if a user has the power to send a specific state event.
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event
+ * @param userId - the id of the user
+ * @param eventType - the type of state event
+ * @returns if true, the user has the power
+ */
+export declare function hasStateEventPower(powerLevelStateEvent: PowerLevelsStateEvent | undefined, userId: string | undefined, eventType: string): boolean;
+/**
+ * Check if a user has the power to perform a specific action.
+ *
+ * Supported actions:
+ *   * invite: Invite a new user into the room
+ *   * kick: Kick a user from the room
+ *   * ban: Ban a user from the room
+ *   * redact: Redact a message from another user
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event
+ * @param userId - the id of the user
+ * @param action - the action
+ * @returns if true, the user has the power
+ */
+export declare function hasActionPower(powerLevelStateEvent: PowerLevelsStateEvent | undefined, userId: string | undefined, action: PowerLevelsActions): boolean;
+/**
+ * Calculate the power level of the user based on a `m.room.power_levels` event.
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event.
+ * @param userId - the ID of the user.
+ * @returns the power level of the user.
+ */
+export declare function calculateUserPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, userId?: string): number;
+/**
+ * Calculate the power level that a user needs send a specific room event.
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event
+ * @param eventType - the type of room event
+ * @returns the power level that is needed
+ */
+export declare function calculateRoomEventPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, eventType: string): number;
+/**
+ * Calculate the power level that a user needs send a specific state event.
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event
+ * @param eventType - the type of state event
+ * @returns the power level that is needed
+ */
+export declare function calculateStateEventPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, eventType: string): number;
+/**
+ * Calculate the power level that a user needs to perform an action.
+ *
+ * Supported actions:
+ *   * invite: Invite a new user into the room
+ *   * kick: Kick a user from the room
+ *   * ban: Ban a user from the room
+ *   * redact: Redact a message from another user
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event
+ * @param action - the action
+ * @returns the power level that is needed
+ */
+export declare function calculateActionPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, action: PowerLevelsActions): number;

package/build/esm/api/extras/powerLevel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/esm/api/extras/redactions.d.ts

@@ -0,0 +1,42 @@
+import { Observable } from 'rxjs';
+import { RoomEvent, WidgetApi } from '../types';
+/**
+ * The name of the redaction room event.
+ */
+export declare const ROOM_EVENT_REDACTION = "m.room.redaction";
+/**
+ * The content of an `m.room.redaction` event.
+ */
+export type Redaction = {
+    /**
+     * The id of the event that is redacted.
+     */
+    redacts: string;
+};
+/**
+ * Types a {@link RoomEvent} to include the properties of a redaction.
+ *
+ * @remarks The redaction event is a special snowflake. The actual data is
+ *          outside the content to make it readable without having to decrypt
+ *          it.
+ */
+export type RedactionRoomEvent = RoomEvent<Record<string, never>> & Redaction;
+/**
+ * Check whether the format of a redaction event is valid.
+ * @param event - The event to check.
+ * @returns True if the event format is valid, otherwise false.
+ */
+export declare function isValidRedactionEvent(event: RoomEvent<unknown>): event is RedactionRoomEvent;
+/**
+ * Redacts an event in the current room.
+ * @param widgetApi - An instance of the widget API.
+ * @param eventId - The id of the event to redact.
+ * @returns The redaction event that was send to the room.
+ */
+export declare function redactEvent(widgetApi: WidgetApi, eventId: string): Promise<RedactionRoomEvent>;
+/**
+ * Observes redaction events in the current room.
+ * @param widgetApi - An instance of the widget API.
+ * @returns An observable of validated redaction events.
+ */
+export declare function observeRedactionEvents(widgetApi: WidgetApi): Observable<RedactionRoomEvent>;

package/build/esm/api/extras/redactions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/esm/api/extras/relatesTo.d.ts

@@ -0,0 +1,60 @@
+import { RoomEvent } from '../types';
+/**
+ * Defines a relation to another event.
+ */
+export type RelatesTo<RelationType extends string> = {
+    /**
+     * The event id of the other event.
+     */
+    event_id: string;
+    /**
+     * The relation to the other event.
+     */
+    rel_type: RelationType;
+};
+/**
+ * Content of a room event that relates to another event.
+ */
+export type EventWithRelatesTo<RelationType extends string> = RoomEvent<{
+    /**
+     * A reference to the event that it relates to.
+     */
+    'm.relates_to': RelatesTo<RelationType>;
+}>;
+/**
+ * Content of a room event that replaces an existing event with
+ * the "m.replace" relation, which means that the content of the
+ * previous event is fully replaced.
+ */
+export type NewContentRelatesTo<T> = EventWithRelatesTo<'m.replace'>['content'] & {
+    /**
+     * The new content of the event.
+     */
+    'm.new_content': T;
+};
+/**
+ * A room event that either contains the content directly or contains an
+ * "m.new_content" object.
+ */
+export type RoomEventOrNewContent<T = unknown> = RoomEvent<T | NewContentRelatesTo<T>>;
+/**
+ * Get the original event id, or the event id of the current event if it
+ * doesn't relates to another event.
+ * @param event - The room event.
+ * @returns The event id of the original event, or the current event id.
+ */
+export declare function getOriginalEventId<T>(event: RoomEventOrNewContent<T>): string;
+/**
+ * Get the content of the event, independent from whether it contains the
+ * content directly or contains a "m.new_content" key.
+ * @param event - The room event.
+ * @returns Only the content of the room event.
+ */
+export declare function getContent<T>(event: RoomEventOrNewContent<T>): T;
+/**
+ * Validates that `event` has a valid structure for a
+ * {@link EventWithRelatesTo}.
+ * @param event - The event to validate.
+ * @returns True, if the event is valid.
+ */
+export declare function isValidEventWithRelatesTo(event: RoomEvent): event is EventWithRelatesTo<string>;

package/build/esm/api/extras/relatesTo.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/esm/api/extras/roomMember.d.ts

@@ -0,0 +1,35 @@
+import { StateEvent } from '../types';
+/**
+ * The name of the room member state event.
+ */
+export declare const STATE_EVENT_ROOM_MEMBER = "m.room.member";
+/**
+ * The membership state of a user.
+ */
+export type MembershipState = 'join' | 'invite' | 'leave' | 'ban' | 'knock';
+/**
+ * The content of an `m.room.member` event.
+ *
+ * @remarks based on https://github.com/matrix-org/matrix-spec/blob/main/data/event-schemas/schema/m.room.member.yaml
+ */
+export type RoomMemberStateEventContent = {
+    /**
+     * The membership state of the user.
+     */
+    membership: MembershipState;
+    /**
+     * The display name for this user, if any.
+     */
+    displayname?: string | null;
+    /**
+     * The avatar URL for this user, if any.
+     */
+    avatar_url?: string | null;
+};
+/**
+ * Validates that `event` is has a valid structure for a
+ * {@link RoomMemberStateEventContent}.
+ * @param event - The event to validate.
+ * @returns True, if the event is valid.
+ */
+export declare function isValidRoomMemberStateEvent(event: StateEvent<unknown>): event is StateEvent<RoomMemberStateEventContent>;

package/build/esm/api/extras/roomMember.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/esm/api/index.d.ts

@@ -0,0 +1,8 @@
+export * from './extras';
+export { extractRawWidgetParameters, extractWidgetApiParameters, extractWidgetParameters, parseWidgetId, } from './parameters';
+export type { WidgetApiParameters, WidgetId } from './parameters';
+export { generateWidgetRegistrationUrl, hasRequiredWidgetParameters, repairWidgetRegistration, } from './registration';
+export type { RoomEvent, StateEvent, ToDeviceMessageEvent, TurnServer, WidgetApi, WidgetConfig, WidgetParameters, WidgetRegistration, } from './types';
+export { makeEventFromSendStateEventResult, sendStateEventWithEventResult, } from './utils';
+export { WidgetApiImpl } from './WidgetApiImpl';
+export type { WidgetApiOptions } from './WidgetApiImpl';

package/build/esm/api/parameters.d.ts

@@ -0,0 +1,58 @@
+import { WidgetParameters } from './types';
+/**
+ * Parameters used to initialize the widget API inside the widget.
+ */
+export type WidgetApiParameters = {
+    /**
+     * The id of the widget.
+     */
+    widgetId: string;
+    /**
+     * The origin of the client.
+     */
+    clientOrigin: string;
+};
+/**
+ * Extract the parameters used to initialize the widget API from the current
+ * `window.location`.
+ * @returns The parameters required for initializing the widget API.
+ */
+export declare function extractWidgetApiParameters(): WidgetApiParameters;
+/**
+ * Extract the widget parameters from the current `window.location`.
+ * @returns The all unprocessed raw widget parameters.
+ */
+export declare function extractRawWidgetParameters(): Record<string, string>;
+/**
+ * Extract the widget parameters from the current `window.location`.
+ * @returns The widget parameters.
+ */
+export declare function extractWidgetParameters(): WidgetParameters;
+/**
+ * Individual fields that are decoded inside a widget id.
+ */
+export type WidgetId = {
+    /**
+     * The widget id of the main widget if working with modals, or the widget id
+     * of the current widget if not.
+     */
+    mainWidgetId: string;
+    /**
+     * The room id the widget is registered in.
+     */
+    roomId?: string;
+    /**
+     * The user id of the user that registered the widget.
+     */
+    creator?: string;
+    /**
+     * True, if this widget is a modal widget.
+     */
+    isModal: boolean;
+};
+/**
+ * Parse a widget id into the individual fields.
+ * @param widgetId - The widget id to parse.
+ * @returns The individual fields encoded inside a widget id.
+ */
+export declare function parseWidgetId(widgetId: string): WidgetId;

package/build/esm/api/parameters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/esm/api/registration.d.ts

@@ -0,0 +1,33 @@
+import { WidgetApi, WidgetParameters, WidgetRegistration } from './types';
+/**
+ * Checks whether all widget parameters were provided to the widget.
+ *
+ * @param widgetApi - The widget api to read the parameters from
+ * @returns True, if all parameters were provided.
+ */
+export declare function hasRequiredWidgetParameters(widgetApi: WidgetApi): boolean;
+/**
+ * Generate a registration URL for the widget based on the current URL and
+ * include all widget parameters (and their placeholders).
+ * @param options - Options for generating the URL.
+ *                  Use `pathName` to include an optional sub path in the URL.
+ *                  Use `includeParameters` to append the widget parameters to
+ *                  the URL, defaults to `true`.
+ * @returns The generated URL.
+ */
+export declare function generateWidgetRegistrationUrl(options?: {
+    pathName?: string;
+    includeParameters?: boolean;
+    widgetParameters?: Partial<WidgetParameters>;
+}): string;
+export declare const STATE_EVENT_WIDGETS = "im.vector.modular.widgets";
+/**
+ * Repair/configure the registration of the current widget.
+ * This steps make sure to include all the required widget parameters in the
+ * URL. Support setting a widget name and additional parameters.
+ *
+ * @param widgetApi - The widget api of the current widget.
+ * @param registration - Optional configuration options for the widget
+ *                       registration, like the display name of the widget.
+ */
+export declare function repairWidgetRegistration(widgetApi: WidgetApi, registration?: WidgetRegistration): Promise<void>;

package/build/esm/api/registration.test.d.ts

@@ -0,0 +1 @@
+export {};