Add state event utils and expose them via the utils module

Signed-off-by: Michael Weimann <[email protected]>

.changeset/fresh-peaches-smell.md

@@ -0,0 +1,5 @@
+---
+'@matrix-widget-toolkit/api': minor
+---
+
+The api package now exposes some utility functions

packages/api/api-report.api.md

@@ -29,6 +29,12 @@ export function calculateUserPowerLevel(powerLevelStateEvent: PowerLevelsStateEv
 // @public
 export function compareOriginServerTS<T>(a: RoomEvent<T>, b: RoomEvent<T>): number;
 
+// @public (undocumented)
+export function convertToRawCapabilities(rawCapabilities: Array<WidgetEventCapability | Capability>): string[];
+
+// @public (undocumented)
+export function equalsSet<T>(as: Set<T>, bs: Set<T>): boolean;
+
 // @public
 export type EventWithRelatesTo<RelationType extends string> = RoomEvent<{
     'm.relates_to': RelatesTo<RelationType>;
@@ -74,6 +80,12 @@ export function hasRoomEventPower(powerLevelStateEvent: PowerLevelsStateEvent |
 // @public
 export function hasStateEventPower(powerLevelStateEvent: PowerLevelsStateEvent | undefined, userId: string | undefined, eventType: string): boolean;
 
+// @public (undocumented)
+export function isDefined<T>(arg: T | null | undefined): arg is T;
+
+// @public (undocumented)
+export function isInRoom(matrixEvent: IRoomEvent, currentRoomId: string, roomIds?: string[] | Symbols.AnyRoom): boolean;
+
 // @public
 export function isRoomEvent(event: RoomEvent | StateEvent): event is RoomEvent;
 
@@ -92,6 +104,9 @@ export function isValidRedactionEvent(event: RoomEvent<unknown>): event is Redac
 // @public
 export function isValidRoomMemberStateEvent(event: StateEvent<unknown>): event is StateEvent<RoomMemberStateEventContent>;
 
+// @public
+export function makeEventFromSendStateEventResult<T>(type: string, stateKey: string, content: T, sender: string, sendResult: ISendEventFromWidgetResponseData): StateEvent<T>;
+
 // @public
 export type MembershipState = 'join' | 'invite' | 'leave' | 'ban' | 'knock';
 
@@ -172,6 +187,9 @@ export type RoomMemberStateEventContent = {
     avatar_url?: string | null;
 };
 
+// @public
+export function sendStateEventWithEventResult<T>(widgetApi: WidgetApi, type: string, stateKey: string, content: T): Promise<StateEvent<T>>;
+
 // @public
 export const STATE_EVENT_POWER_LEVELS = "m.room.power_levels";
 
@@ -184,6 +202,9 @@ export type StateEvent<T = unknown> = Omit<IRoomEvent, 'content' | 'unsigned' |
     content: T;
 };
 
+// @public (undocumented)
+export function subtractSet<T>(as: Set<T>, bs: Set<T>): Set<T>;
+
 // @public
 export type ToDeviceMessageEvent<T = unknown> = {
     type: string;
@@ -199,6 +220,9 @@ export type TurnServer = {
     credential: string;
 };
 
+// @public (undocumented)
+export function unique<T>(items: Iterable<T>): T[];
+
 // @public
 export const WIDGET_CAPABILITY_NAVIGATE = "org.matrix.msc2931.navigate";
 

packages/api/src/api/index.ts

@@ -37,5 +37,6 @@ export type {
   WidgetParameters,
   WidgetRegistration,
 } from './types';
+export * from './utils';
 export { WidgetApiImpl } from './WidgetApiImpl';
 export type { WidgetApiOptions } from './WidgetApiImpl';

packages/api/src/api/utils.ts

@@ -17,9 +17,11 @@
 import {
   Capability,
   IRoomEvent,
+  ISendEventFromWidgetResponseData,
   Symbols,
   WidgetEventCapability,
 } from 'matrix-widget-api';
+import { StateEvent, WidgetApi } from './types';
 
 export function convertToRawCapabilities(
   rawCapabilities: Array<WidgetEventCapability | Capability>,
@@ -72,3 +74,56 @@ export function isInRoom(
 
   return roomIds.includes(matrixEvent.room_id);
 }
+
+/**
+ * Create a state event from the arguments.
+ *
+ * @returns A state event with current timestamp origin_server_ts.
+ */
+export function makeEventFromSendStateEventResult<T>(
+  type: string,
+  stateKey: string,
+  content: T,
+  sender: string,
+  sendResult: ISendEventFromWidgetResponseData,
+): StateEvent<T> {
+  if (sendResult.event_id === undefined) {
+    throw new Error('Send state event did not return an event ID');
+  }
+
+  return {
+    content,
+    event_id: sendResult.event_id,
+    origin_server_ts: Date.now(),
+    room_id: sendResult.room_id,
+    sender,
+    state_key: stateKey,
+    type,
+  };
+}
+
+/**
+ * Send a state event and resolve to a "virtual" state event.
+ *
+ * @returns Promise, that resolves to a state event with current timestamp origin_server_ts.
+ */
+export async function sendStateEventWithEventResult<T>(
+  widgetApi: WidgetApi,
+  type: string,
+  stateKey: string,
+  content: T,
+): Promise<StateEvent<T>> {
+  if (widgetApi.widgetParameters.userId === undefined) {
+    throw new Error('Own user ID is undefined');
+  }
+
+  const response = await widgetApi.sendStateEvent(type, content, { stateKey });
+
+  return makeEventFromSendStateEventResult(
+    type,
+    stateKey,
+    content,
+    widgetApi.widgetParameters.userId,
+    response,
+  );
+}