@matrix-widget-toolkit/api 4.2.0 → 5.0.1

package/build/index.d.ts

@@ -26,11 +26,16 @@ 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.
@@ -42,6 +47,14 @@ export declare function calculateUserPowerLevel(powerLevelStateEvent: PowerLevel
  */
 export declare function compareOriginServerTS<T>(a: RoomEvent<T>, b: RoomEvent<T>): number;
 
+/**
+ * Compare a user's power level to a normal power level.
+ * @param userPowerLevel - The user's power level
+ * @param normalPowerLevel - The normal power level
+ * @returns True if the user's power level is greater than or equal to the normal power level, false otherwise
+ */
+export declare function compareUserPowerLevelToNormalPowerLevel(userPowerLevel: UserPowerLevelType, normalPowerLevel: number): boolean;
+
 /**
  * Content of a room event that relates to another event.
  */
@@ -135,31 +148,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.
@@ -185,6 +201,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}.
@@ -380,6 +404,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.
  */
@@ -421,7 +451,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";
 
@@ -438,6 +473,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.
  */
@@ -461,6 +502,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.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matrix-widget-toolkit/api",
-  "version": "4.2.0",
+  "version": "5.0.1",
   "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.3",
-    "@types/node": "22.15.30",
+    "@rollup/plugin-commonjs": "28.0.6",
+    "@types/node": "22.15.35",
     "@types/qs": "6.14.0",
-    "@vitest/coverage-v8": "3.2.2",
+    "@vitest/coverage-v8": "3.2.4",
     "typescript": "5.8.3",
     "vite": "6.3.5",
-    "vitest": "3.2.2"
+    "vitest": "3.2.4"
   },
   "scripts": {
     "build": "tsc && rollup --config ../../rollup.config.mjs",