@matrix-widget-toolkit/api 4.1.2 → 5.0.0

package/README.md

@@ -148,3 +148,12 @@ It returns a promise that resolves with the result of the modal.
 Inside the modal widget, you can use `observeModalButtons()` to listen to clicks on the bottom buttons of the modal.
 You can use `setModalButtonEnabled()` to disable buttons from within the widget.
 Once you are done, you can call `closeModal()` to close the modal and pass the results back to the main widget.
+
+### Delayed events
+
+You can send and update delayed events (MSC4140). The configuration for delayed events on the homeserver
+needs to be applied, for example:
+
+```
+max_event_delay_duration: 24h
+```

package/build/cjs/api/WidgetApiImpl.d.cts

@@ -1,4 +1,4 @@
-import { Capability, IDownloadFileActionFromWidgetResponseData, IGetMediaConfigActionFromWidgetResponseData, IModalWidgetCreateData, IModalWidgetOpenRequestDataButton, IModalWidgetReturnData, IOpenIDCredentials, ISendEventFromWidgetResponseData, IUploadFileActionFromWidgetResponseData, IWidgetApiRequestData, WidgetApi as MatrixWidgetApi, ModalButtonID, Symbols, WidgetEventCapability } from 'matrix-widget-api';
+import { Capability, IDownloadFileActionFromWidgetResponseData, IGetMediaConfigActionFromWidgetResponseData, IModalWidgetCreateData, IModalWidgetOpenRequestDataButton, IModalWidgetReturnData, IOpenIDCredentials, ISendEventFromWidgetResponseData, IUploadFileActionFromWidgetResponseData, IWidgetApiRequestData, WidgetApi as MatrixWidgetApi, ModalButtonID, Symbols, UpdateDelayedEventAction, WidgetEventCapability } from 'matrix-widget-api';
 import { Observable } from 'rxjs';
 import { RoomEvent, StateEvent, ToDeviceMessageEvent, TurnServer, WidgetApi, WidgetConfig, WidgetParameters } from './types';
 /**
@@ -108,6 +108,13 @@ export declare class WidgetApiImpl implements WidgetApi {
         roomId?: string;
         stateKey?: string;
     }): Promise<ISendEventFromWidgetResponseData>;
+    /** {@inheritDoc WidgetApi.sendDelayedStateEvent} */
+    sendDelayedStateEvent<T>(eventType: string, content: T, delay: number, { roomId, stateKey }?: {
+        roomId?: string;
+        stateKey?: string;
+    }): Promise<{
+        delay_id: string;
+    }>;
     /** {@inheritDoc WidgetApi.receiveRoomEvents} */
     receiveRoomEvents<T>(eventType: string, { messageType, roomIds, }?: {
         messageType?: string;
@@ -122,6 +129,14 @@ export declare class WidgetApiImpl implements WidgetApi {
     sendRoomEvent<T>(eventType: string, content: T, { roomId }?: {
         roomId?: string;
     }): Promise<RoomEvent<T>>;
+    /** {@inheritDoc WidgetApi.sendDelayedRoomEvent} */
+    sendDelayedRoomEvent<T>(eventType: string, content: T, delay: number, { roomId }?: {
+        roomId?: string;
+    }): Promise<{
+        delay_id: string;
+    }>;
+    /** {@inheritDoc WidgetApi.updateDelayedEvent} */
+    updateDelayedEvent(delayId: string, action: UpdateDelayedEventAction): Promise<void>;
     /** {@inheritDoc WidgetApi.readEventRelations} */
     readEventRelations(eventId: string, options?: {
         roomId?: string;

package/build/cjs/api/extras/events.d.cts

@@ -1,5 +1,13 @@
 import Joi from 'joi';
 import { RoomEvent, StateEvent, ToDeviceMessageEvent } from '../types';
+/**
+ * The type of the power levels state event.
+ */
+export declare const STATE_EVENT_POWER_LEVELS = "m.room.power_levels";
+/**
+ * The types of type of the create event.
+ */
+export declare const STATE_EVENT_CREATE = "m.room.create";
 /**
  * Check if the given event is a {@link StateEvent}.
  *
@@ -38,3 +46,46 @@ export declare function isValidToDeviceMessageEvent(event: unknown): event is To
 export declare const roomEventSchema: Joi.ObjectSchema<RoomEvent>;
 export declare const stateEventSchema: Joi.ObjectSchema<StateEvent>;
 export declare const toDeviceMessageSchema: Joi.ObjectSchema<ToDeviceMessageEvent>;
+export type StateEventCreateContent = {
+    room_version?: string;
+    creator?: string;
+    additional_creators?: string[];
+};
+export declare const createEventSchema: Joi.ObjectSchema<StateEvent<StateEventCreateContent>>;
+/**
+ * Validates that `event` is has a valid structure for a
+ * {@link StateEventCreateContent}.
+ * @param event - The event to validate.
+ * @returns True, if the event is valid.
+ */
+export declare function isValidCreateEventSchema(event: StateEvent<unknown> | undefined): event is StateEvent<StateEventCreateContent>;
+/**
+ * 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;
+};
+export declare const powerLevelsEventSchema: Joi.ObjectSchema<StateEvent<PowerLevelsStateEvent>>;
+/**
+ * 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>;

package/build/cjs/api/extras/index.d.cts

@@ -1,11 +1,12 @@
 export { generateRoomTimelineCapabilities } from './capabilities';
 export { getRoomMemberDisplayName } from './displayName';
-export { isRoomEvent, isStateEvent, isValidRoomEvent, isValidStateEvent as isValidStateEVent, isValidToDeviceMessageEvent, } from './events';
+export { STATE_EVENT_CREATE, isRoomEvent, isStateEvent, isValidCreateEventSchema, isValidRoomEvent, isValidStateEvent as isValidStateEVent, isValidToDeviceMessageEvent, } from './events';
+export type { PowerLevelsActions, PowerLevelsStateEvent, StateEventCreateContent, } from './events';
 export { WIDGET_CAPABILITY_NAVIGATE, navigateToRoom } from './navigateTo';
 export type { NavigateToRoomOptions } from './navigateTo';
 export { compareOriginServerTS } from './originServerTs';
 export { STATE_EVENT_POWER_LEVELS, calculateUserPowerLevel, hasActionPower, hasRoomEventPower, hasStateEventPower, isValidPowerLevelStateEvent, } from './powerLevel';
-export type { PowerLevelsActions, PowerLevelsStateEvent } from './powerLevel';
+export type { ROOM_VERSION_12_CREATOR, UserPowerLevelType } from './powerLevel';
 export { ROOM_EVENT_REDACTION, isValidRedactionEvent, observeRedactionEvents, redactEvent, } from './redactions';
 export type { Redaction, RedactionRoomEvent } from './redactions';
 export { getContent, getOriginalEventId, isValidEventWithRelatesTo, } from './relatesTo';

package/build/cjs/api/extras/powerLevel.d.cts

@@ -1,55 +1,32 @@
 import { StateEvent } from '../types';
+import type { PowerLevelsActions, PowerLevelsStateEvent, StateEventCreateContent } from './events';
+export { isValidPowerLevelStateEvent, STATE_EVENT_POWER_LEVELS, } from './events';
 /**
- * The name of the power levels state event.
+ * Room version 12 requires us to have something larger than Max integer for room creators.
+ * This is a workaround to allow the room creator to always have the highest power level.
  */
-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>;
+export declare const ROOM_VERSION_12_CREATOR = "ROOM_VERSION_12_CREATOR";
+export type UserPowerLevelType = number | typeof ROOM_VERSION_12_CREATOR;
 /**
  * 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 createRoomStateEvent - the `m.room.create` event for the room
  * @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;
+export declare function hasRoomEventPower(powerLevelStateEvent: PowerLevelsStateEvent | undefined, createRoomStateEvent: StateEvent<StateEventCreateContent> | 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 createRoomStateEvent - the `m.room.create` event for the room
  * @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;
+export declare function hasStateEventPower(powerLevelStateEvent: PowerLevelsStateEvent | undefined, createRoomStateEvent: StateEvent<StateEventCreateContent> | undefined, userId: string | undefined, eventType: string): boolean;
 /**
  * Check if a user has the power to perform a specific action.
  *
@@ -60,19 +37,25 @@ export declare function hasStateEventPower(powerLevelStateEvent: PowerLevelsStat
  *   * redact: Redact a message from another user
  *
  * @param powerLevelStateEvent - the content of the `m.room.power_levels` event
+ * @param createRoomStateEvent - the `m.room.create` event for the room
  * @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;
+export declare function hasActionPower(powerLevelStateEvent: PowerLevelsStateEvent | undefined, createRoomStateEvent: StateEvent<StateEventCreateContent> | undefined, userId: string | undefined, action: PowerLevelsActions): boolean;
 /**
  * Calculate the power level of the user based on a `m.room.power_levels` event.
  *
+ * Note that we return the @see UserPowerLevelType type instead of a number as Room Version 12
+ * gives a Room creator (and additionalCreators) always the highest power level regardless
+ * of the highest next Powerlevel number.
+ *
  * @param powerLevelStateEvent - the content of the `m.room.power_levels` event.
+ * @param createRoomStateEvent - the `m.room.create` event for the room.
  * @param userId - the ID of the user.
  * @returns the power level of the user.
  */
-export declare function calculateUserPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, userId?: string): number;
+export declare function calculateUserPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent | undefined, createRoomStateEvent: StateEvent<StateEventCreateContent> | undefined, userId: string): UserPowerLevelType;
 /**
  * Calculate the power level that a user needs send a specific room event.
  *
@@ -80,15 +63,16 @@ export declare function calculateUserPowerLevel(powerLevelStateEvent: PowerLevel
  * @param eventType - the type of room event
  * @returns the power level that is needed
  */
-export declare function calculateRoomEventPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, eventType: string): number;
+export declare function calculateRoomEventPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent | undefined, 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 createRoomStateEvent - the `m.room.create` event
  * @param eventType - the type of state event
  * @returns the power level that is needed
  */
-export declare function calculateStateEventPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, eventType: string): number;
+export declare function calculateStateEventPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent | undefined, createRoomStateEvent: StateEvent<StateEventCreateContent> | undefined, eventType: string): number;
 /**
  * Calculate the power level that a user needs to perform an action.
  *
@@ -102,4 +86,4 @@ export declare function calculateStateEventPowerLevel(powerLevelStateEvent: Powe
  * @param action - the action
  * @returns the power level that is needed
  */
-export declare function calculateActionPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, action: PowerLevelsActions): number;
+export declare function calculateActionPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent | undefined, action: PowerLevelsActions): number;

package/build/cjs/api/types.d.cts

@@ -1,4 +1,4 @@
-import { Capability, IDownloadFileActionFromWidgetResponseData, IGetMediaConfigActionFromWidgetResponseData, IModalWidgetCreateData, IModalWidgetOpenRequestDataButton, IModalWidgetReturnData, IOpenIDCredentials, IRoomEvent, ISendEventFromWidgetResponseData, IUploadFileActionFromWidgetResponseData, IWidget, IWidgetApiRequest, IWidgetApiRequestData, ModalButtonID, Symbols, WidgetEventCapability } from 'matrix-widget-api';
+import { Capability, IDownloadFileActionFromWidgetResponseData, IGetMediaConfigActionFromWidgetResponseData, IModalWidgetCreateData, IModalWidgetOpenRequestDataButton, IModalWidgetReturnData, IOpenIDCredentials, IRoomEvent, ISendEventFromWidgetResponseData, IUploadFileActionFromWidgetResponseData, IWidget, IWidgetApiRequest, IWidgetApiRequestData, ModalButtonID, Symbols, UpdateDelayedEventAction, WidgetEventCapability } from 'matrix-widget-api';
 import { Observable } from 'rxjs';
 /**
  * Enumeration of widget parameters that can be checked if they are available upon registration.
@@ -265,6 +265,23 @@ export type WidgetApi = {
         roomId?: string;
         stateKey?: string;
     }): Promise<ISendEventFromWidgetResponseData>;
+    /**
+     * Send a delayed state event with a given type to the current room.
+     * @param eventType - The type of the event to send.
+     * @param content - The content of the event.
+     * @param delay - The delay of the event in milliseconds.
+     * @param options - Options for sending the state event.
+     *                  Use `roomId` to send the state event to another room.
+     *                  Use `stateKey` to send a state event with a custom state
+     *                  key.
+     * @returns The result data of delayed event with delay_id.
+     */
+    sendDelayedStateEvent<T>(eventType: string, content: T, delay: number, options?: {
+        roomId?: string;
+        stateKey?: string;
+    }): Promise<{
+        delay_id: string;
+    }>;
     /**
      * Receive all room events of a given type from the current room.
      *
@@ -318,6 +335,28 @@ export type WidgetApi = {
     sendRoomEvent<T>(eventType: string, content: T, options?: {
         roomId?: string;
     }): Promise<RoomEvent<T>>;
+    /**
+     * Send a delayed room event with a given type to the current room.
+     * @param eventType - The type of the event to send.
+     * @param content - The content of the event.
+     * @param delay - The delay of the event in milliseconds.
+     * @param options - Options for sending the state event.
+     *                  Use `roomId` to send the state event to another room.
+     *                  Use `stateKey` to send a state event with a custom state
+     *                  key.
+     * @returns The result data of delayed event with delay_id.
+     */
+    sendDelayedRoomEvent<T>(eventType: string, content: T, delay: number, options?: {
+        roomId?: string;
+    }): Promise<{
+        delay_id: string;
+    }>;
+    /**
+     * Update a delayed event by delay id
+     * @param delayId - The delay id of the event
+     * @param action - The action to update
+     */
+    updateDelayedEvent(delayId: string, action: UpdateDelayedEventAction): Promise<void>;
     /**
      * Receive all events that relate to a given `eventId` by means of MSC2674.
      * `chunk` can include state events or room events.