Add MaybePromise

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

@@ -67,7 +67,7 @@ export interface BuiltinsApi {
 }
 
 // @alpha
-export type CapabilitiesApprover = (widget: WidgetDescriptor, requestedCapabilities: Set<string>) => Set<string> | Promise<Set<string> | undefined> | undefined;
+export type CapabilitiesApprover = (widget: WidgetDescriptor, requestedCapabilities: Set<string>) => MaybePromise<Set<string> | undefined>;
 
 // @alpha @deprecated (undocumented)
 export interface ChatExportCustomisations<ExportFormat, ExportType> {
@@ -186,7 +186,7 @@ export interface I18nApi {
 }
 
 // @alpha
-export type IdentityApprover = (widget: WidgetDescriptor) => boolean | Promise<boolean> | undefined;
+export type IdentityApprover = (widget: WidgetDescriptor) => MaybePromise<boolean | undefined>;
 
 // @alpha @deprecated (undocumented)
 export type LegacyCustomisations<T extends object> = (customisations: T) => void;
@@ -242,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)
@@ -334,7 +337,7 @@ export type OriginalMessageComponentProps = {
 };
 
 // @alpha
-export type PreloadApprover = (widget: WidgetDescriptor) => boolean | Promise<boolean> | undefined;
+export type PreloadApprover = (widget: WidgetDescriptor) => MaybePromise<boolean | undefined>;
 
 // @public
 export interface Profile {

packages/element-web-module-api/src/api/widget-lifecycle.ts

@@ -5,6 +5,8 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE files in the repository root for full details.
 */
 
+import type { MaybePromise } from "../utils";
+
 /**
  * A description of a widget passed to approver callbacks.
  * Contains the information needed to make approval decisions.
@@ -31,14 +33,14 @@ export type WidgetDescriptor = {
  * Return `true` to auto-approve, or any other value to defer to the default consent flow.
  * @alpha Subject to change.
  */
-export type PreloadApprover = (widget: WidgetDescriptor) => boolean | Promise<boolean> | undefined;
+export type PreloadApprover = (widget: WidgetDescriptor) => MaybePromise<boolean | undefined>;
 /**
  * Callback that decides whether a widget should be auto-approved to receive
  * the user's OpenID identity token.
  * Return `true` to auto-approve, or any other value to defer to the default consent flow.
  * @alpha Subject to change.
  */
-export type IdentityApprover = (widget: WidgetDescriptor) => boolean | Promise<boolean> | undefined;
+export type IdentityApprover = (widget: WidgetDescriptor) => MaybePromise<boolean | undefined>;
 /**
  * Callback that decides which of a widget's requested capabilities should be auto-approved.
  * Return a `Set` of approved capability strings, or `undefined` to defer to the default consent flow.
@@ -47,7 +49,7 @@ export type IdentityApprover = (widget: WidgetDescriptor) => boolean | Promise<b
 export type CapabilitiesApprover = (
     widget: WidgetDescriptor,
     requestedCapabilities: Set<string>,
-) => Set<string> | Promise<Set<string> | undefined> | undefined;
+) => MaybePromise<Set<string> | undefined>;
 
 /**
  * API for modules to auto-approve widget preloading, identity token requests, and capability requests.

packages/element-web-module-api/src/index.ts

@@ -24,3 +24,4 @@ export type * from "./api/stores";
 export type * from "./api/client";
 export type * from "./api/widget-lifecycle";
 export * from "./api/watchable";
+export type * from "./utils";

packages/element-web-module-api/src/utils.ts

@@ -0,0 +1,13 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * A value that may be a direct value or a Promise resolving to that value.
+ * Useful for callback APIs that can operate synchronously or asynchronously.
+ * @public
+ */
+export type MaybePromise<T> = T | PromiseLike<T>;