@matrix-widget-toolkit/api 1.0.1

package/build/index.d.ts

@@ -0,0 +1,959 @@
+/**
+ * @packageDocumentation This is package that wraps `matrix-widget-api` to
+ *                       provide a more convenient API.
+ */
+
+import { Capability } from 'matrix-widget-api';
+import { IModalWidgetCreateData } from 'matrix-widget-api';
+import { IModalWidgetOpenRequestDataButton } from 'matrix-widget-api';
+import { IModalWidgetReturnData } from 'matrix-widget-api';
+import { IOpenIDCredentials } from 'matrix-widget-api';
+import { IRoomEvent } from 'matrix-widget-api';
+import { IWidget } from 'matrix-widget-api';
+import { IWidgetApiRequest } from 'matrix-widget-api';
+import { IWidgetApiRequestData } from 'matrix-widget-api';
+import { ModalButtonID } from 'matrix-widget-api';
+import { Observable } from 'rxjs';
+import { Symbols } from 'matrix-widget-api';
+import { WidgetApi as WidgetApi_2 } from 'matrix-widget-api';
+import { WidgetEventCapability } from 'matrix-widget-api';
+
+/**
+ * Calculate the power level of the user based on a `m.room.power_levels` event.
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event.
+ * @param userId - the ID of the user.
+ * @returns the power level of the user.
+ */
+export declare function calculateUserPowerLevel(powerLevelStateEvent: PowerLevelsStateEvent, userId?: string): number;
+
+/**
+ * Compares two room events by their origin server timestamp.
+ *
+ * @param a - A room event
+ * @param b - A room event
+ * @returns Either zero if the timestamp is equal, \>0 if a is newer, or \<0 if
+ *          b is newer.
+ */
+export declare function compareOriginServerTS<T>(a: RoomEvent<T>, b: RoomEvent<T>): number;
+
+/**
+ * Content of a room event that relates to another event.
+ */
+export declare type EventWithRelatesTo<RelationType extends string> = RoomEvent<{
+    /**
+     * A reference to the event that it relates to.
+     */
+    'm.relates_to': RelatesTo<RelationType>;
+}>;
+
+/**
+ * Extract the widget parameters from the current `window.location`.
+ * @returns The all unprocessed raw widget parameters.
+ */
+export declare function extractRawWidgetParameters(): Record<string, string>;
+
+/**
+ * Extract the parameters used to initialize the widget API from the current
+ * `window.location`.
+ * @returns The parameters required for initializing the widget API.
+ */
+export declare function extractWidgetApiParameters(): WidgetApiParameters;
+
+/**
+ * Extract the widget parameters from the current `window.location`.
+ * @returns The widget parameters.
+ */
+export declare function extractWidgetParameters(): WidgetParameters;
+
+/**
+ * Generate a list of capabilities to access the timeline of other rooms.
+ * If enabled, all previously or future capabilities will apply to _all_
+ * selected rooms.
+ * If `Symbols.AnyRoom` is passed, this is expanded to all joined
+ * or invited rooms the client is able to see, current and future.
+ *
+ * @param roomIds - a list of room ids or `@link Symbols.AnyRoom`.
+ * @returns the generated capabilities.
+ */
+export declare function generateRoomTimelineCapabilities(roomIds: string[] | Symbols.AnyRoom): string[];
+
+/**
+ * Generate a registration URL for the widget based on the current URL and
+ * include all widget parameters (and their placeholders).
+ * @param options - Options for generating the URL.
+ *                  Use `pathName` to include an optional sub path in the URL.
+ *                  Use `includeParameters` to append the widget parameters to
+ *                  the URL, defaults to `true`.
+ * @returns The generated URL.
+ */
+export declare function generateWidgetRegistrationUrl(options?: {
+    pathName?: string;
+    includeParameters?: boolean;
+    widgetParameters?: Partial<WidgetParameters>;
+}): string;
+
+/**
+ * Get the content of the event, independent from whether it contains the
+ * content directly or contains a "m.new_content" key.
+ * @param event - The room event.
+ * @returns Only the content of the room event.
+ */
+export declare function getContent<T>(event: RoomEventOrNewContent<T>): T;
+
+/**
+ * Get the original event id, or the event id of the current event if it
+ * doesn't relates to another event.
+ * @param event - The room event.
+ * @returns The event id of the original event, or the current event id.
+ */
+export declare function getOriginalEventId<T>(event: RoomEventOrNewContent<T>): string;
+
+/**
+ * Generate a unique displayname of a user that is consistent across Matrix clients.
+ *
+ * @remarks The algorithm is based on https://spec.matrix.org/v1.1/client-server-api/#calculating-the-display-name-for-a-user
+ *
+ * @param member - the member to generate a name for.
+ * @param allRoomMembers - a list of all members of the same room.
+ * @returns the displayname that is unique in given the set of all room members.
+ */
+export declare function getRoomMemberDisplayName(member: StateEvent<RoomMemberStateEventContent>, allRoomMembers?: StateEvent<RoomMemberStateEventContent>[]): string;
+
+/**
+ * Check if a user has the power to perform a specific action.
+ *
+ * Supported actions:
+ *   * invite: Invite a new user into the room
+ *   * kick: Kick a user from the room
+ *   * ban: Ban a user from the room
+ *   * redact: Redact a message from another user
+ *
+ * @param powerLevelStateEvent - the content of the `m.room.power_levels` event
+ * @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;
+
+/**
+ * Checks whether all widget parameters were provided to the widget.
+ *
+ * @param widgetApi - The widget api to read the parameters from
+ * @returns True, if all parameters were provided.
+ */
+export declare function hasRequiredWidgetParameters(widgetApi: WidgetApi): 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 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;
+
+/**
+ * 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 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;
+
+/**
+ * Check if the given event is a {@link RoomEvent}.
+ *
+ * @param event - An event that is either a {@link RoomEvent} or a {@link StateEvent}.
+ * @returns True, if the event is a {@link RoomEvent}.
+ */
+export declare function isRoomEvent(event: RoomEvent | StateEvent): event is RoomEvent;
+
+/**
+ * Check if the given event is a {@link StateEvent}.
+ *
+ * @param event - An event that is either a {@link RoomEvent} or a {@link StateEvent}.
+ * @returns True, if the event is a {@link StateEvent}.
+ */
+export declare function isStateEvent(event: RoomEvent | StateEvent): event is StateEvent;
+
+/**
+ * Validates that `event` has a valid structure for a
+ * {@link EventWithRelatesTo}.
+ * @param event - The event to validate.
+ * @returns True, if the event is valid.
+ */
+export declare function isValidEventWithRelatesTo(event: RoomEvent): event is EventWithRelatesTo<string>;
+
+/**
+ * Validates that `event` is has a valid structure for a
+ * {@link PowerLevelsStateEvent}.
+ * @param event - The event to validate.
+ * @returns True, if the event is valid.
+ */
+export declare function isValidPowerLevelStateEvent(event: StateEvent<unknown>): event is StateEvent<PowerLevelsStateEvent>;
+
+/**
+ * Check whether the format of a redaction event is valid.
+ * @param event - The event to check.
+ * @returns True if the event format is valid, otherwise false.
+ */
+export declare function isValidRedactionEvent(event: RoomEvent<unknown>): event is RedactionRoomEvent;
+
+/**
+ * Validates that `event` is has a valid structure for a
+ * {@link RoomMemberStateEventContent}.
+ * @param event - The event to validate.
+ * @returns True, if the event is valid.
+ */
+export declare function isValidRoomMemberStateEvent(event: StateEvent<unknown>): event is StateEvent<RoomMemberStateEventContent>;
+
+/**
+ * The membership state of a user.
+ */
+export declare type MembershipState = 'join' | 'invite' | 'leave' | 'ban' | 'knock';
+
+/**
+ * Navigate the client to another matrix room.
+ *
+ * @remarks This requires the {@link WIDGET_CAPABILITY_NAVIGATE} capability.
+ *
+ * @param widgetApi - the {@link WidgetApi} instance.
+ * @param roomId - the room ID.
+ * @param opts - {@link NavigateToRoomOptions}
+ */
+export declare function navigateToRoom(widgetApi: WidgetApi, roomId: string, opts?: NavigateToRoomOptions): Promise<void>;
+
+/**
+ * Options for the {@link navigateToRoom} function.
+ */
+export declare type NavigateToRoomOptions = {
+    /**
+     * Optional, array of one or more homeserver domains to discover the room.
+     */
+    via?: string[];
+};
+
+/**
+ * Content of a room event that replaces an existing event with
+ * the "m.replace" relation, which means that the content of the
+ * previous event is fully replaced.
+ */
+export declare type NewContentRelatesTo<T> = EventWithRelatesTo<'m.replace'>['content'] & {
+    /**
+     * The new content of the event.
+     */
+    'm.new_content': T;
+};
+
+/**
+ * Observes redaction events in the current room.
+ * @param widgetApi - An instance of the widget API.
+ * @returns An observable of validated redaction events.
+ */
+export declare function observeRedactionEvents(widgetApi: WidgetApi): Observable<RedactionRoomEvent>;
+
+/**
+ * Parse a widget id into the individual fields.
+ * @param widgetId - The widget id to parse.
+ * @returns The individual fields encoded inside a widget id.
+ */
+export declare function parseWidgetId(widgetId: string): WidgetId;
+
+/**
+ * The types of actions.
+ */
+export declare type PowerLevelsActions = 'invite' | 'kick' | 'ban' | 'redact';
+
+/**
+ * The content of an `m.room.power_levels` event.
+ */
+export declare type PowerLevelsStateEvent = {
+    events?: {
+        [key: string]: number;
+    };
+    state_default?: number;
+    events_default?: number;
+    users?: {
+        [key: string]: number;
+    };
+    users_default?: number;
+    ban?: number;
+    invite?: number;
+    kick?: number;
+    redact?: number;
+};
+
+/**
+ * Redacts an event in the current room.
+ * @param widgetApi - An instance of the widget API.
+ * @param eventId - The id of the event to redact.
+ * @returns The redaction event that was send to the room.
+ */
+export declare function redactEvent(widgetApi: WidgetApi, eventId: string): Promise<RedactionRoomEvent>;
+
+/**
+ * The content of an `m.room.redaction` event.
+ */
+export declare type Redaction = {
+    /**
+     * The id of the event that is redacted.
+     */
+    redacts: string;
+};
+
+/**
+ * Types a {@link RoomEvent} to include the properties of a redaction.
+ *
+ * @remarks The redaction event is a special snowflake. The actual data is
+ *          outside the content to make it readable without having to decrypt
+ *          it.
+ */
+export declare type RedactionRoomEvent = RoomEvent<Record<string, never>> & Redaction;
+
+/**
+ * Defines a relation to another event.
+ */
+export declare type RelatesTo<RelationType extends string> = {
+    /**
+     * The event id of the other event.
+     */
+    event_id: string;
+    /**
+     * The relation to the other event.
+     */
+    rel_type: RelationType;
+};
+
+/**
+ * Repair/configure the registration of the current widget.
+ * This steps make sure to include all the required widget parameters in the
+ * URL. Support setting a widget name and additional parameters.
+ *
+ * @param widgetApi - The widget api of the current widget.
+ * @param registration - Optional configuration options for the widget
+ *                       registration, like the display name of the widget.
+ */
+export declare function repairWidgetRegistration(widgetApi: WidgetApi, registration?: WidgetRegistration): Promise<void>;
+
+/**
+ * The name of the redaction room event.
+ */
+export declare const ROOM_EVENT_REDACTION = "m.room.redaction";
+
+/**
+ * Generic type for room events.
+ */
+export declare type RoomEvent<T = unknown> = Omit<IRoomEvent, 'content' | 'state_key' | 'unsigned'> & {
+    content: T;
+};
+
+/**
+ * A room event that either contains the content directly or contains an
+ * "m.new_content" object.
+ */
+export declare type RoomEventOrNewContent<T = unknown> = RoomEvent<T | NewContentRelatesTo<T>>;
+
+/**
+ * The content of an `m.room.member` event.
+ *
+ * @remarks based on https://github.com/matrix-org/matrix-spec/blob/main/data/event-schemas/schema/m.room.member.yaml
+ */
+export declare type RoomMemberStateEventContent = {
+    /**
+     * The membership state of the user.
+     */
+    membership: MembershipState;
+    /**
+     * The display name for this user, if any.
+     */
+    displayname?: string;
+    /**
+     * The avatar URL for this user, if any.
+     */
+    avatar_url?: string;
+};
+
+/**
+ * The name of the power levels state event.
+ */
+export declare const STATE_EVENT_POWER_LEVELS = "m.room.power_levels";
+
+/**
+ * The name of the room member state event.
+ */
+export declare const STATE_EVENT_ROOM_MEMBER = "m.room.member";
+
+/**
+ * Generic type for state events.
+ */
+export declare type StateEvent<T = unknown> = Omit<IRoomEvent, 'content' | 'unsigned' | 'state_key'> & {
+    state_key: string;
+    content: T;
+};
+
+/**
+ * The capability that needs to be requested in order to navigate to another room.
+ */
+export declare const WIDGET_CAPABILITY_NAVIGATE = "org.matrix.msc2931.navigate";
+
+/**
+ * API for communication from the widget to the client.
+ */
+export declare type WidgetApi = {
+    /**
+     * The widget Id of the current widget used for the registration in the room.
+     */
+    readonly widgetId: string;
+    /**
+     * Parameters to the widget that are transmitted via the widget URL.
+     */
+    readonly widgetParameters: Readonly<WidgetParameters>;
+    /**
+     * Get the configuration of the widget, if available.
+     *
+     * @remarks At the moment, this is only available for modal widgets,
+     *          otherwise it's `undefined`.
+     */
+    getWidgetConfig<T extends IWidgetApiRequestData>(): Readonly<WidgetConfig<T> | undefined>;
+    /**
+     * Rerequests the initialy in the constructor passed capabilities.
+     *
+     * This is useful in case the user denied one or all of them.
+     */
+    rerequestInitialCapabilities(): Promise<void>;
+    /**
+     * True, if the initial capabilties passed via the constructor were granted.
+     */
+    hasInitialCapabilities(): boolean;
+    /**
+     * Request a list of capabilities.
+     *
+     * Can be called at any time, not just initially.
+     * Resolves once the user has answered the capabilities request.
+     *
+     * @param capabilities - A list of capabilities that should be requested
+     * @throws error if the capabilities request or one of the capabilities was
+     *         rejected by the user
+     */
+    requestCapabilities(capabilities: Array<WidgetEventCapability | Capability>): Promise<void>;
+    /**
+     * Checks whether the widget has already access to the provided capabilities,
+     * without requesting them.
+     *
+     * @param capabilities - A list of capabilities that should be checked.
+     */
+    hasCapabilities(capabilities: Array<WidgetEventCapability | Capability>): boolean;
+    /**
+     * Receive the last state event of a give type and state key from the current
+     * room if any exists.
+     *
+     * @remarks While one can type the returned event using the generic parameter
+     *          `T`, it is not recommended to rely on this type till further
+     *          validation of the event structure is performed.
+     *
+     * @param eventType - The type of the event to receive.
+     * @param stateKey - Specifies the state key to retrieve, uses `''` (empty
+     *                   string) if no state key is passed.
+     */
+    receiveSingleStateEvent<T>(eventType: string, stateKey?: string): Promise<StateEvent<T> | undefined>;
+    /**
+     * Receives the state events of a give type from the current room if any
+     * exists.
+     *
+     * @remarks While one can type the returned event using the generic parameter
+     *          `T`, it is not recommended to rely on this type till further
+     *          validation of the event structure is performed.
+     *
+     * @param eventType - The type of the event to receive.
+     * @param options - Options for receiving the state event.
+     *                  Use `stateKey` to receive events with a specifc state
+     *                  key.
+     *                  Use `roomIds` to receive the state events from other
+     *                  rooms.
+     *                  Pass `Symbols.AnyRoom` to receive from all rooms of the
+     *                  user.
+     */
+    receiveStateEvents<T>(eventType: string, options?: {
+        stateKey?: string;
+        roomIds?: string[] | Symbols.AnyRoom;
+    }): Promise<StateEvent<T>[]>;
+    /**
+     * Provide an observable that can be used to listen to state event updates of
+     * a given type in the current room.
+     * Initially, the current state event is emitted, if one exists.
+     *
+     * @remarks While one can type the returned event using the generic parameter
+     *          `T`, it is not recommended to rely on this type till further
+     *          validation of the event structure is performed.
+     *
+     * @param eventType - The type of the event to receive.
+     * @param options - Options for receiving the state event.
+     *                  Use `stateKey` to receive events with a specifc state
+     *                  key.
+     *                  Use `roomIds` to receive the state events from other
+     *                  rooms.
+     *                  Pass `Symbols.AnyRoom` to receive from all rooms of the
+     *                  user.
+     */
+    observeStateEvents<T>(eventType: string, options?: {
+        stateKey?: string;
+        roomIds?: string[] | Symbols.AnyRoom;
+    }): Observable<StateEvent<T>>;
+    /**
+     * Send a state event with a given type to the current room and wait till the
+     * operation is completed.
+     * @param eventType - The type of the event to send.
+     * @param content - The content of the event.
+     * @param options - Options for sending the state event.
+     *                  Use `roomId` to send the state event to another room.
+     *                  Use `stateKey` to send a state event with a custom state
+     *                  key.
+     */
+    sendStateEvent<T>(eventType: string, content: T, options?: {
+        roomId?: string;
+        stateKey?: string;
+    }): Promise<StateEvent<T>>;
+    /**
+     * Receive all room events of a given type from the current room.
+     *
+     * @remarks While one can type the returned event using the generic parameter
+     *          `T`, it is not recommended to rely on this type till further
+     *          validation of the event structure is performed.
+     *
+     * @param eventType - The type of the event to receive.
+     * @param options - Options for receiving the room event.
+     *                  Use `messageType` to receive events with a specifc
+     *                  message type.
+     *                  Use `roomIds` to receive the state events from other
+     *                  rooms.
+     *                  Pass `Symbols.AnyRoom` to receive from all rooms of the
+     *                  user.
+     */
+    receiveRoomEvents<T>(eventType: string, options?: {
+        messageType?: string;
+        roomIds?: string[] | Symbols.AnyRoom;
+    }): Promise<Array<RoomEvent<T>>>;
+    /**
+     * Provide an observable that can be used to listen to room event updates of
+     * a given type in the current room.
+     * Initially, the previous room events are emitted.
+     *
+     * @remarks While one can type the returned event using the generic parameter
+     *          `T`, it is not recommended to rely on this type till further
+     *          validation of the event structure is performed.
+     *
+     * @param eventType - The type of the event to receive.
+     * @param options - Options for receiving the room event.
+     *                  Use `messageType` to receive events with a specifc
+     *                  message type.
+     *                  Use `roomIds` to receive the state events from other
+     *                  rooms.
+     *                  Pass `Symbols.AnyRoom` to receive from all rooms of the
+     *                  user.
+     */
+    observeRoomEvents<T>(eventType: string, options?: {
+        messageType?: string;
+        roomIds?: string[] | Symbols.AnyRoom;
+    }): Observable<RoomEvent<T>>;
+    /**
+     * Send a room event with a given type to the current room and wait till the
+     * operation is completed.
+     * @param eventType - The type of the event to send.
+     * @param content - The content of the event.
+     * @param options - Options for sending the room event.
+     *                  Use `roomId` to send the room event to another room.
+     */
+    sendRoomEvent<T>(eventType: string, content: T, options?: {
+        roomId?: string;
+    }): Promise<RoomEvent<T>>;
+    /**
+     * Receive an event with a given `eventId` and all events that relate to it by
+     * means of MSC2674. Both `originalEvent` and `chunk` can include state events
+     * or room events.
+     *
+     * @remarks You can only receive events where the capability to receive it was
+     *          approved. If `originalEvent` is not approved, an exception is thrown.
+     *          If an event in `chunk` is not approve, it is silently skipped. Note
+     *          that the call might return less than `limit` events due to various
+     *          reasons, including missing capabilities or encrypted events.
+     *
+     * @param eventId - The id of the event to receive
+     * @param options - Options for receiving the related events.
+     *                  Use `roomId` to receive the event from another room.
+     *                  Use `limit` to control the page size.
+     *                  Use `from` to request the next page of events by providing
+     *                  `nextToken` of a previous call. If `nextToken === undefined`,
+     *                  no further page exists.
+     *                  Use `relationType` to only return events with that `rel_type`.
+     *                  Use `eventType` to only return events with that `type`.
+     *
+     * @throws if the capability to receive the type of event is missing.
+     */
+    readEventRelations(eventId: string, options?: {
+        roomId?: string;
+        limit?: number;
+        from?: string;
+        relationType?: string;
+        eventType?: string;
+    }): Promise<{
+        originalEvent?: RoomEvent | StateEvent;
+        chunk: Array<RoomEvent | StateEvent>;
+        nextToken?: string;
+    }>;
+    /**
+     * Open a new modal, wait until the modal closes, and return the result.
+     *
+     * This function can only be called from a Widget.
+     *
+     * @param pathName - The path to include a sub path in the URL.
+     * @param name - The name of the modal.
+     * @param options - Options for opening the Modal.
+     *                  Use `buttons` to show buttons in the widget.
+     *                  Use `data` to supply optional data to the modal widget.
+     * @returns The result data of the modal widget.
+     *
+     * @throws if called from a modal widget
+     */
+    openModal<T extends Record<string, unknown> = Record<string, unknown>, U extends IModalWidgetCreateData = IModalWidgetCreateData>(pathName: string, name: string, options?: {
+        buttons?: IModalWidgetOpenRequestDataButton[];
+        data?: U;
+    }): Promise<T | undefined>;
+    /**
+     * Enable or disable a button on a modal widget.
+     *
+     * This function can only be called from a Modal.
+     *
+     * @param buttonId - The id of the button to enable/disable.
+     * @param isEnabled - If `true`, the button is enabled.
+     *                    If `false`, the button is disabled.
+     *
+     * @throws if called from a non-modal widget
+     */
+    setModalButtonEnabled(buttonId: ModalButtonID, isEnabled: boolean): Promise<void>;
+    /**
+     * Provide an observable that emits button clicks.
+     * The emitted values are the button ids.
+     *
+     * This function can only be called from a Modal.
+     *
+     * @throws if called from a non-modal widget
+     */
+    observeModalButtons(): Observable<ModalButtonID>;
+    /**
+     * Close the modal widget.
+     *
+     * This function can only be called from a Modal.
+     *
+     * @param data - Optional data to pass to the widget that opened the modal.
+     *               Defaults to `{ 'm.exited': true }`.
+     *
+     * @throws if called from a non-modal widget
+     */
+    closeModal<T extends IModalWidgetReturnData>(data?: T): Promise<void>;
+    /**
+     * Navigate the client to the given Matrix URI.
+     *
+     * This supports:
+     * - matrix.to urls ({@link https://spec.matrix.org/v1.2/appendices/#matrixto-navigation})
+     *
+     * @remarks In future, the Matrix URI scheme will also be defined. This
+     *          requires the `org.matrix.msc2931.navigate` capability.
+     *
+     * @param uri - the URI to navigate to.
+     * @throws Throws if the URI is invalid or cannot be processed.
+     */
+    navigateTo(uri: string): Promise<void>;
+    /**
+     * Requests an OIDC token that can be used to verify the identity of the
+     * current user at the `/_matrix/federation/v1/openid/userinfo` endpoint of
+     * the home server ({@link https://spec.matrix.org/v1.2/server-server-api/#openid}).
+     * The home server can be accessed from the `matrix_server_name` property.
+     *
+     * @remarks The methods caches the token and only requests a new once if the
+     *          old one expired.
+     */
+    requestOpenIDConnectToken(): Promise<IOpenIDCredentials>;
+};
+
+/**
+ * Implementation of the API from the widget to the client.
+ *
+ * @remarks Widget API is specified here:
+ * https://docs.google.com/document/d/1uPF7XWY_dXTKVKV7jZQ2KmsI19wn9-kFRgQ1tFQP7wQ/edit#heading=h.9rn9lt6ctkgi
+ */
+export declare class WidgetApiImpl implements WidgetApi {
+    /**
+     * Provide access to the underlying widget API from `matrix-widget-sdk`.
+     *
+     * @remarks Normally there is no need to use it, however if features are
+     *          missing from `WidgetApi` it can be handy to work with the
+     *          original API.
+     */
+    readonly matrixWidgetApi: WidgetApi_2;
+    /** {@inheritDoc WidgetApi.widgetId} */
+    readonly widgetId: string;
+    /** {@inheritDoc WidgetApi.widgetParameters} */
+    readonly widgetParameters: WidgetParameters;
+    /**
+     * Initialize a new widget API instance and wait till it is ready.
+     * There should only be one instance of the widget API. The widget API should
+     * be created as early as possible when starting the application. This is
+     * required to match the timing of the API connection establishment with the
+     * client, especially in Safari. Therefore it is recommended to create it
+     * inside the entrypoint, before initializing rendering engines like react.
+     *
+     * @param param0 - {@link WidgetApiOptions}
+     *
+     * @returns A widget API instance ready to use.
+     */
+    static create({ capabilities, supportStandalone, }?: WidgetApiOptions): Promise<WidgetApi>;
+    private widgetConfig;
+    private outstandingCapabilitiesRequest;
+    private outstandingOpenIDConnectTokenRequest;
+    private cachedOpenIdToken;
+    private readonly events$;
+    private readonly initialCapabilities;
+    constructor(
+    /**
+     * Provide access to the underlying widget API from `matrix-widget-sdk`.
+     *
+     * @remarks Normally there is no need to use it, however if features are
+     *          missing from `WidgetApi` it can be handy to work with the
+     *          original API.
+     */
+    matrixWidgetApi: WidgetApi_2, 
+    /** {@inheritDoc WidgetApi.widgetId} */
+    widgetId: string, 
+    /** {@inheritDoc WidgetApi.widgetParameters} */
+    widgetParameters: WidgetParameters, { capabilities, supportStandalone }?: WidgetApiOptions);
+    /**
+     * Initialize the widget API and wait till a connection with the client is
+     * fully established.
+     *
+     * Waits till the user has approved the initial set of capabilities. The
+     * method doesn't fail if the user doesn't approve all of them. It is
+     * required to check manually afterwards.
+     * In case of modal widgets it waits till the `widgetConfig` is received.
+     *
+     * @remarks Should only be called once during startup.
+     */
+    initialize(): Promise<void>;
+    /** {@inheritDoc WidgetApi.getWidgetConfig} */
+    getWidgetConfig<T extends IWidgetApiRequestData>(): Readonly<WidgetConfig<T> | undefined>;
+    /** {@inheritDoc WidgetApi.rerequestInitialCapabilities} */
+    rerequestInitialCapabilities(): Promise<void>;
+    /** {@inheritDoc WidgetApi.hasInitialCapabilities} */
+    hasInitialCapabilities(): boolean;
+    /** {@inheritDoc WidgetApi.requestCapabilities} */
+    requestCapabilities(capabilities: Array<WidgetEventCapability | Capability>): Promise<void>;
+    private requestCapabilitiesInternal;
+    /** {@inheritDoc WidgetApi.hasCapabilities} */
+    hasCapabilities(capabilities: Array<WidgetEventCapability | Capability>): boolean;
+    /** {@inheritDoc WidgetApi.receiveSingleStateEvent} */
+    receiveSingleStateEvent<T>(eventType: string, stateKey?: string): Promise<StateEvent<T> | undefined>;
+    /** {@inheritDoc WidgetApi.receiveStateEvents} */
+    receiveStateEvents<T>(eventType: string, { stateKey, roomIds, }?: {
+        stateKey?: string;
+        roomIds?: string[] | Symbols.AnyRoom;
+    }): Promise<StateEvent<T>[]>;
+    /** {@inheritDoc WidgetApi.observeStateEvents} */
+    observeStateEvents<T>(eventType: string, { stateKey, roomIds, }?: {
+        stateKey?: string;
+        roomIds?: string[] | Symbols.AnyRoom;
+    }): Observable<StateEvent<T>>;
+    /** {@inheritDoc WidgetApi.sendStateEvent} */
+    sendStateEvent<T>(eventType: string, content: T, { roomId, stateKey }?: {
+        roomId?: string;
+        stateKey?: string;
+    }): Promise<StateEvent<T>>;
+    /** {@inheritDoc WidgetApi.receiveRoomEvents} */
+    receiveRoomEvents<T>(eventType: string, { messageType, roomIds, }?: {
+        messageType?: string;
+        roomIds?: string[] | Symbols.AnyRoom;
+    }): Promise<Array<RoomEvent<T>>>;
+    /** {@inheritDoc WidgetApi.observeRoomEvents} */
+    observeRoomEvents<T>(eventType: string, { messageType, roomIds, }?: {
+        messageType?: string;
+        roomIds?: string[] | Symbols.AnyRoom;
+    }): Observable<RoomEvent<T>>;
+    /** {@inheritDoc WidgetApi.sendRoomEvent} */
+    sendRoomEvent<T>(eventType: string, content: T, { roomId }?: {
+        roomId?: string;
+    }): Promise<RoomEvent<T>>;
+    /** {@inheritDoc WidgetApi.readEventRelations} */
+    readEventRelations(eventId: string, options?: {
+        roomId?: string;
+        limit?: number;
+        from?: string;
+        relationType?: string;
+        eventType?: string;
+    }): Promise<{
+        originalEvent?: RoomEvent | StateEvent;
+        chunk: Array<RoomEvent | StateEvent>;
+        nextToken?: string;
+    }>;
+    /** {@inheritDoc WidgetApi.openModal} */
+    openModal<T extends Record<string, unknown> = Record<string, unknown>, U extends IModalWidgetCreateData = IModalWidgetCreateData>(pathName: string, name: string, options?: {
+        buttons?: IModalWidgetOpenRequestDataButton[];
+        data?: U;
+    }): Promise<T | undefined>;
+    /** {@inheritDoc WidgetApi.setModalButtonEnabled} */
+    setModalButtonEnabled(buttonId: ModalButtonID, isEnabled: boolean): Promise<void>;
+    /** {@inheritDoc WidgetApi.observeModalButtons} */
+    observeModalButtons(): Observable<ModalButtonID>;
+    /** {@inheritDoc WidgetApi.closeModal} */
+    closeModal<T extends IModalWidgetReturnData>(data?: T): Promise<void>;
+    /** {@inheritdoc WidgetApi.navigateTo} */
+    navigateTo(uri: string): Promise<void>;
+    /** {@inheritdoc WidgetApi.requestOpenIDConnectToken} */
+    requestOpenIDConnectToken(): Promise<IOpenIDCredentials>;
+    private requestOpenIDConnectTokenInternal;
+}
+
+/**
+ * Options for the {@link WidgetApiImpl.create} function.
+ */
+export declare type WidgetApiOptions = {
+    /**
+     * Optional initial capabilities that should be requested from the user on
+     * load.
+     */
+    capabilities?: Array<WidgetEventCapability | Capability>;
+    /**
+     * Enable the the pop-out button for pinned widgets that support running
+     * without the Widget API.
+     */
+    supportStandalone?: boolean;
+};
+
+/**
+ * Parameters used to initialize the widget API inside the widget.
+ */
+export declare type WidgetApiParameters = {
+    /**
+     * The id of the widget.
+     */
+    widgetId: string;
+    /**
+     * The origin of the client.
+     */
+    clientOrigin: string;
+};
+
+/**
+ * Configuration of a widget, including data passed to it.
+ */
+export declare type WidgetConfig<T extends IWidgetApiRequestData> = Omit<IWidgetApiRequest & IWidget, 'data'> & {
+    data: T;
+};
+
+/**
+ * Individual fields that are decoded inside a widget id.
+ */
+export declare type WidgetId = {
+    /**
+     * The widget id of the main widget if working with modals, or the widget id
+     * of the current widget if not.
+     */
+    mainWidgetId: string;
+    /**
+     * The room id the widget is registered in.
+     */
+    roomId?: string;
+    /**
+     * The user id of the user that registered the widget.
+     */
+    creator?: string;
+    /**
+     * True, if this widget is a modal widget.
+     */
+    isModal: boolean;
+};
+
+/**
+ * Parameters passed from the client to the widget during initialization.
+ */
+export declare type WidgetParameters = {
+    /**
+     * The user id of the current user.
+     */
+    userId?: string;
+    /**
+     * The display name of the current user.
+     *
+     * Might be the user id, if the user has no display name configured.
+     */
+    displayName?: string;
+    /**
+     * The URL of the avatar of the current user.
+     *
+     * Might be unset, if the user has no avatar configured.
+     */
+    avatarUrl?: string;
+    /**
+     * The room id of the room the widget is registered in.
+     */
+    roomId?: string;
+    /**
+     * The current selected theme in the client.
+     *
+     * Right now, it's either "light" or "dark".
+     */
+    theme?: string;
+    /**
+     * The id of the client that this widget is running in, for example
+     * "io.element.web".
+     */
+    clientId?: string;
+    /**
+     * The current selected language in the client.
+     */
+    clientLanguage?: string;
+    /**
+     * Whether the widget was opened by a client or not.
+     *
+     * This is independent from whether the widget API is available or not.
+     * For example, in mobile clients this can be true, but we don't have
+     * access to widgets API there.
+     */
+    isOpenedByClient: boolean;
+};
+
+/**
+ * Configuration of the widget in the room.
+ */
+export declare type WidgetRegistration = {
+    /**
+     * Configure an optional type.
+     *
+     * Make sure to include a custom prefix when using built-in names.
+     * You can discover the available icons in the [Element source code](https://github.com/matrix-org/matrix-react-sdk/blob/9d6d8fc666855ca0c06c71ccb30c74ac4fc8fd12/src/components/views/avatars/WidgetAvatar.tsx#L29-L39).
+     */
+    type?: string;
+    /**
+     * The display name of the widget.
+     */
+    name?: string;
+    /**
+     * The avatar URL used to display an icon on the widget.
+     *
+     * @remarks Not supported at the moment, as uploading avatars to the channel
+     *          is not possible from a widget right now.
+     */
+    avatarUrl?: string;
+    /**
+     * Optional additional data that can be used to initialize the widget.
+     */
+    data?: Record<string, unknown> | {
+        /**
+         * An optional sub title for the widget.
+         */
+        title?: string;
+    };
+};
+
+export { }