@matrix-widget-toolkit/api 4.1.2 → 5.0.0

package/build/index.d.ts

@@ -19,17 +19,23 @@ import { IWidgetApiRequestData } from 'matrix-widget-api';
 import { ModalButtonID } from 'matrix-widget-api';
 import { Observable } from 'rxjs';
 import { Symbols } from 'matrix-widget-api';
+import { UpdateDelayedEventAction } from 'matrix-widget-api';
 import { WidgetApi as WidgetApi_2 } from 'matrix-widget-api';
 import { WidgetEventCapability } from 'matrix-widget-api';
 
 /**
  * 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;
 
 /**
  * Compares two room events by their origin server timestamp.
@@ -134,31 +140,34 @@ export declare function getRoomMemberDisplayName(member: StateEvent<RoomMemberSt
  *   * 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;
 
 /**
  * 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;
 
 /**
  * Checks whether the necessary widget parameters were provided to the widget.
@@ -184,6 +193,14 @@ export declare function isRoomEvent(event: RoomEvent | StateEvent): event is Roo
  */
 export declare function isStateEvent(event: RoomEvent | StateEvent): event is StateEvent;
 
+/**
+ * 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>;
+
 /**
  * Validates that `event` has a valid structure for a
  * {@link EventWithRelatesTo}.
@@ -379,6 +396,12 @@ export declare function repairWidgetRegistration(widgetApi: WidgetApi, registrat
  */
 export declare const ROOM_EVENT_REDACTION = "m.room.redaction";
 
+/**
+ * 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 ROOM_VERSION_12_CREATOR = "ROOM_VERSION_12_CREATOR";
+
 /**
  * Generic type for room events.
  */
@@ -420,7 +443,12 @@ export declare type RoomMemberStateEventContent = {
 export declare function sendStateEventWithEventResult<T>(widgetApi: WidgetApi, type: string, stateKey: string, content: T): Promise<StateEvent<T>>;
 
 /**
- * The name of the power levels state event.
+ * The types of type of the create event.
+ */
+export declare const STATE_EVENT_CREATE = "m.room.create";
+
+/**
+ * The type of the power levels state event.
  */
 export declare const STATE_EVENT_POWER_LEVELS = "m.room.power_levels";
 
@@ -437,6 +465,12 @@ export declare type StateEvent<T = unknown> = Omit<IRoomEvent, 'content' | 'unsi
     content: T;
 };
 
+export declare type StateEventCreateContent = {
+    room_version?: string;
+    creator?: string;
+    additional_creators?: string[];
+};
+
 /**
  * Generic type for to device message events.
  */
@@ -460,6 +494,8 @@ export declare type TurnServer = {
     credential: string;
 };
 
+export declare type UserPowerLevelType = number | typeof ROOM_VERSION_12_CREATOR;
+
 /**
  * The capability that needs to be requested in order to navigate to another room.
  */
@@ -582,6 +618,23 @@ export declare 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.
      *
@@ -635,6 +688,28 @@ export declare 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.
@@ -898,6 +973,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;
@@ -912,6 +994,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matrix-widget-toolkit/api",
-  "version": "4.1.2",
+  "version": "5.0.0",
   "description": "A simplified layer on top of matrix-widget-api to use build widgets.",
   "author": "Nordeck IT + Consulting GmbH",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
   },
   "type": "module",
   "devDependencies": {
-    "@rollup/plugin-commonjs": "28.0.2",
-    "@types/node": "22.13.5",
-    "@types/qs": "6.9.18",
-    "@vitest/coverage-v8": "3.0.7",
-    "typescript": "5.7.3",
-    "vite": "6.2.0",
-    "vitest": "3.0.7"
+    "@rollup/plugin-commonjs": "28.0.6",
+    "@types/node": "22.15.35",
+    "@types/qs": "6.14.0",
+    "@vitest/coverage-v8": "3.2.4",
+    "typescript": "5.8.3",
+    "vite": "6.3.5",
+    "vitest": "3.2.4"
   },
   "scripts": {
     "build": "tsc && rollup --config ../../rollup.config.mjs",