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 via the `utils` module

packages/api/api-report.api.md

@@ -92,6 +92,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 +175,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";
 

packages/api/src/api/index.ts

@@ -37,5 +37,9 @@ export type {
   WidgetParameters,
   WidgetRegistration,
 } from './types';
+export {
+  makeEventFromSendStateEventResult,
+  sendStateEventWithEventResult,
+} 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,
+  );
+}