Merge pull request #198 from element-hq/langleyd/widget-lifecycle-module-api

Widget lifecycle module api

packages/element-web-module-api/element-web-module-api.api.md

@@ -55,6 +55,8 @@ export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiEx
     readonly navigation: NavigationApi;
     readonly rootNode: HTMLElement;
     readonly stores: StoresApi;
+    // @alpha
+    readonly widgetLifecycle: WidgetLifecycleApi;
 }
 
 // @alpha
@@ -64,6 +66,9 @@ export interface BuiltinsApi {
     renderRoomView(roomId: string, props?: RoomViewProps): React.ReactNode;
 }
 
+// @alpha
+export type CapabilitiesApprover = (widget: WidgetDescriptor, requestedCapabilities: Set<string>) => MaybePromise<Set<string> | undefined>;
+
 // @alpha @deprecated (undocumented)
 export interface ChatExportCustomisations<ExportFormat, ExportType> {
     getForceChatExportParameters(): {
@@ -180,6 +185,9 @@ export interface I18nApi {
     translate(this: void, key: keyof Translations, variables?: Variables): string;
 }
 
+// @alpha
+export type IdentityApprover = (widget: WidgetDescriptor) => MaybePromise<boolean | undefined>;
+
 // @alpha @deprecated (undocumented)
 export type LegacyCustomisations<T extends object> = (customisations: T) => void;
 
@@ -234,6 +242,9 @@ export interface MatrixEvent {
     unsigned: Record<string, unknown>;
 }
 
+// @public
+export type MaybePromise<T> = T | PromiseLike<T>;
+
 // @alpha @deprecated (undocumented)
 export interface Media {
     // (undocumented)
@@ -325,6 +336,9 @@ export type OriginalMessageComponentProps = {
     showUrlPreview?: boolean;
 };
 
+// @alpha
+export type PreloadApprover = (widget: WidgetDescriptor) => MaybePromise<boolean | undefined>;
+
 // @public
 export interface Profile {
     displayName?: string;
@@ -422,6 +436,23 @@ export class Watchable<T> {
     watch(listener: (value: T) => void): void;
 }
 
+// @alpha
+export type WidgetDescriptor = {
+    id: string;
+    templateUrl: string;
+    creatorUserId: string;
+    type: string;
+    origin: string;
+    roomId?: string;
+};
+
+// @alpha
+export interface WidgetLifecycleApi {
+    registerCapabilitiesApprover(approver: CapabilitiesApprover): void;
+    registerIdentityApprover(approver: IdentityApprover): void;
+    registerPreloadApprover(approver: PreloadApprover): void;
+}
+
 // @alpha @deprecated (undocumented)
 export interface WidgetPermissionsCustomisations<Widget, Capability> {
     preapproveCapabilities?(widget: Widget, requestedCapabilities: Set<Capability>): Promise<Set<Capability>>;