import { Capability, IOpenIDCredentials, OpenIDRequestState, SimpleObservable, IRoomEvent, IRoomAccountData, ITurnServer, IWidgetApiErrorResponseDataDetails } from ".."; export interface ISendEventDetails { roomId: string; eventId: string; } export interface ISendDelayedEventDetails { roomId: string; delayId: string; } export interface IOpenIDUpdate { state: OpenIDRequestState; token?: IOpenIDCredentials; } export interface IReadEventRelationsResult { chunk: IRoomEvent[]; nextBatch?: string; prevBatch?: string; } export interface ISearchUserDirectoryResult { limited: boolean; results: Array<{ userId: string; displayName?: string; avatarUrl?: string; }>; } export interface IGetMediaConfigResult { [key: string]: unknown; "m.upload.size"?: number; } /** * Represents the functions and behaviour the widget-api is unable to * do, such as prompting the user for information or interacting with * the UI. Clients are expected to implement this class and override * any functions they need/want to support. * * This class assumes the client will have a context of a Widget * instance already. */ export declare abstract class WidgetDriver { /** * Verifies the widget's requested capabilities, returning the ones * it is approved to use. Mutating the requested capabilities will * have no effect. * * This SHOULD result in the user being prompted to approve/deny * capabilities. * * By default this rejects all capabilities (returns an empty set). * @param {Set} requested The set of requested capabilities. * @returns {Promise>} Resolves to the allowed capabilities. */ validateCapabilities(requested: Set): Promise>; /** * Sends an event into a room. If `roomId` is falsy, the client should send the event * into the room the user is currently looking at. The widget API will have already * verified that the widget is capable of sending the event to that room. * @param {string} eventType The event type to be sent. * @param {*} content The content for the event. * @param {string|null} stateKey The state key if this is a state event, otherwise null. * May be an empty string. * @param {string|null} roomId The room ID to send the event to. If falsy, the room the * user is currently looking at. * @returns {Promise} Resolves when the event has been sent with * details of that event. * @throws Rejected when the event could not be sent. */ sendEvent(eventType: string, content: unknown, stateKey?: string | null, roomId?: string | null): Promise; /** * @experimental Part of MSC4407 * Sends a sticky event into a room. If `roomId` is falsy, the client should send the event * into the room the user is currently looking at. The widget API will have already * verified that the widget is capable of sending the event to that room. * @param {number} stickyDurationMs The length of time a sticky event may remain sticky, in milliseconds. * @param {string} eventType The event type to be sent. * @param {*} content The content for the event. * @param {string|null} roomId The room ID to send the event to. If falsy, the room the * user is currently looking at. * @returns {Promise} Resolves when the event has been sent with * details of that event. * @throws Rejected when the event could not be sent. */ sendStickyEvent(stickyDurationMs: number, eventType: string, content: unknown, roomId?: string | null): Promise; /** * @experimental Part of MSC4140 & MSC4157 * Sends a delayed event into a room. If `roomId` is falsy, the client should send it * into the room the user is currently looking at. The widget API will have already * verified that the widget is capable of sending the event to that room. * @param {number|null} delay How much later to send the event, or null to not send the * event automatically. May not be null if {@link parentDelayId} is null. * @param {string|null} parentDelayId The ID of the delayed event this one is grouped with, * or null if it will be put in a new group. May not be null if {@link delay} is null. * @param {string} eventType The event type of the event to be sent. * @param {*} content The content for the event to be sent. * @param {string|null} stateKey The state key if the event to be sent a state event, * otherwise null. May be an empty string. * @param {string|null} roomId The room ID to send the event to. If falsy, the room the * user is currently looking at. * @returns {Promise} Resolves when the delayed event has been * prepared with details of how to refer to it for updating/sending/canceling it later. * @throws Rejected when the delayed event could not be sent. */ sendDelayedEvent(delay: number | null, parentDelayId: string | null, eventType: string, content: unknown, stateKey?: string | null, roomId?: string | null): Promise; /** * @experimental Part of MSC4140, MSC4157 and MSC4407 * Sends a delayed sticky event into a room. If `roomId` is falsy, the client should send the event * into the room the user is currently looking at. The widget API will have already * verified that the widget is capable of sending the event to that room. * @param {number} stickyDurationMs The length of time a sticky event may remain sticky, in milliseconds. * @param {number|null} delay How much later to send the event, or null to not send the * event automatically. May not be null if {@link parentDelayId} is null. * @param {string|null} parentDelayId The ID of the delayed event this one is grouped with, * or null if it will be put in a new group. May not be null if {@link delay} is null. * @param {string} eventType The event type to be sent. * @param {*} content The content for the event. * @param {string|null} roomId The room ID to send the event to. If falsy, the room the * user is currently looking at. * @returns {Promise} Resolves when the event has been sent with * details of that event. * @throws Rejected when the event could not be sent. */ sendDelayedStickyEvent(delay: number | null, parentDelayId: string | null, stickyDurationMs: number, eventType: string, content: unknown, roomId?: string | null): Promise; /** * @experimental Part of MSC4140 & MSC4157 * Cancel the scheduled delivery of the delayed event matching the provided {@link delayId}. * @throws Rejected when there is no matching delayed event, * or when the delayed event failed to be cancelled. */ cancelScheduledDelayedEvent(delayId: string): Promise; /** * @experimental Part of MSC4140 & MSC4157 * Restart the scheduled delivery of the delayed event matching the provided {@link delayId}. * @throws Rejected when there is no matching delayed event, * or when the delayed event failed to be restarted. */ restartScheduledDelayedEvent(delayId: string): Promise; /** * @experimental Part of MSC4140 & MSC4157 * Immediately send the delayed event matching the provided {@link delayId}, * instead of waiting for its scheduled delivery. * @throws Rejected when there is no matching delayed event, * or when the delayed event failed to be sent. */ sendScheduledDelayedEvent(delayId: string): Promise; /** * Sends a to-device event. The widget API will have already verified that the widget * is capable of sending the event. * @param {string} eventType The event type to be sent. * @param {boolean} encrypted Whether to encrypt the message contents. * @param {Object} contentMap A map from user ID and device ID to event content. * @returns {Promise} Resolves when the event has been sent. * @throws Rejected when the event could not be sent. */ sendToDevice(eventType: string, encrypted: boolean, contentMap: { [userId: string]: { [deviceId: string]: object; }; }): Promise; /** * Reads an element of room account data. The widget API will have already verified that the widget is * capable of receiving the `eventType` of the requested information. If `roomIds` is supplied, it may * contain `Symbols.AnyRoom` to denote that the piece of room account data in each of the client's known * rooms should be returned. When `null`, only the room the user is currently looking at should be considered. * @param eventType The event type to be read. * @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs * to look within, possibly containing Symbols.AnyRoom to denote all known rooms. * @returns {Promise} Resolves to the element of room account data, or an empty array. */ readRoomAccountData(eventType: string, roomIds?: string[] | null): Promise; /** * Reads all events of the given type, and optionally `msgtype` (if applicable/defined), * the user has access to. The widget API will have already verified that the widget is * capable of receiving the events. Less events than the limit are allowed to be returned, * but not more. If `roomIds` is supplied, it may contain `Symbols.AnyRoom` to denote that * `limit` in each of the client's known rooms should be returned. When `null`, only the * room the user is currently looking at should be considered. If `since` is specified but * the event ID isn't present in the number of events fetched by the client due to `limit`, * the client will return all the events. * @param eventType The event type to be read. * @param msgtype The msgtype of the events to be read, if applicable/defined. * @param stateKey The state key of the events to be read, if applicable/defined. * @param limit The maximum number of events to retrieve per room. Will be zero to denote "as many * as possible". * @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs * to look within, possibly containing Symbols.AnyRoom to denote all known rooms. * @param since When null, retrieves the number of events specified by the "limit" parameter. * Otherwise, the event ID at which only subsequent events will be returned, as many as specified * in "limit". * @returns {Promise} Resolves to the room events, or an empty array. * @deprecated Clients are advised to implement {@link WidgetDriver.readRoomTimeline} instead. */ readRoomEvents(eventType: string, msgtype: string | undefined, limit: number, roomIds?: string[] | null, since?: string): Promise; /** * Reads all events of the given type, and optionally state key (if applicable/defined), * the user has access to. The widget API will have already verified that the widget is * capable of receiving the events. Less events than the limit are allowed to be returned, * but not more. If `roomIds` is supplied, it may contain `Symbols.AnyRoom` to denote that * `limit` in each of the client's known rooms should be returned. When `null`, only the * room the user is currently looking at should be considered. * @param eventType The event type to be read. * @param stateKey The state key of the events to be read, if applicable/defined. * @param limit The maximum number of events to retrieve. Will be zero to denote "as many * as possible". * @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs * to look within, possibly containing Symbols.AnyRoom to denote all known rooms. * @returns {Promise} Resolves to the state events, or an empty array. * @deprecated Clients are advised to implement {@link WidgetDriver.readRoomTimeline} instead. */ readStateEvents(eventType: string, stateKey: string | undefined, limit: number, roomIds?: string[] | null): Promise; /** * Gets all sticky events of the given type the user has access to. * The widget API will have already verified that the widget is capable of receiving the events. * * This is needed because widgets will get only live messages as they appear in the timeline. * However, sticky events act like a state, and the current state is made by events that may have been * sent before the widget was loaded. * Events are sticky for 1h maximum, so the widget has access to the past hour of sticky events maximum. * * @experimental Part of MSC4407 - Sticky Events (Widget API) * @param roomId - The ID of the room. */ readStickyEvents(roomId: string): Promise; /** * Reads all events of the given type, and optionally `msgtype` (if applicable/defined), * the user has access to. The widget API will have already verified that the widget is * capable of receiving the events. Less events than the limit are allowed to be returned, * but not more. * @param roomId The ID of the room to look within. * @param eventType The event type to be read. * @param msgtype The msgtype of the events to be read, if applicable/defined. * @param stateKey The state key of the events to be read, if applicable/defined. * @param limit The maximum number of events to retrieve. Will be zero to denote "as many as * possible". * @param since When null, retrieves the number of events specified by the "limit" parameter. * Otherwise, the event ID at which only subsequent events will be returned, as many as specified * in "limit". * @returns {Promise} Resolves to the room events, or an empty array. */ readRoomTimeline(roomId: string, eventType: string, msgtype: string | undefined, stateKey: string | undefined, limit: number, since: string | undefined): Promise; /** * Reads the current values of all matching room state entries. * @param roomId The ID of the room. * @param eventType The event type of the entries to be read. * @param stateKey The state key of the entry to be read. If undefined, * all room state entries with a matching event type should be returned. * @returns {Promise} Resolves to the events representing the * current values of the room state entries. */ readRoomState(roomId: string, eventType: string, stateKey: string | undefined): Promise; /** * Reads all events that are related to a given event. The widget API will * have already verified that the widget is capable of receiving the event, * or will make sure to reject access to events which are returned from this * function, but are not capable of receiving. If `relationType` or `eventType` * are set, the returned events should already be filtered. Less events than * the limit are allowed to be returned, but not more. * @param eventId The id of the parent event to be read. * @param roomId The room to look within. When undefined, the user's * currently viewed room. * @param relationType The relationship type of child events to search for. * When undefined, all relations are returned. * @param eventType The event type of child events to search for. When undefined, * all related events are returned. * @param from The pagination token to start returning results from, as * received from a previous call. If not supplied, results start at the most * recent topological event known to the server. * @param to The pagination token to stop returning results at. If not * supplied, results continue up to limit or until there are no more events. * @param limit The maximum number of events to retrieve per room. If not * supplied, the server will apply a default limit. * @param direction The direction to search for according to MSC3715 * @returns Resolves to the room relations. */ readEventRelations(eventId: string, roomId?: string, relationType?: string, eventType?: string, from?: string, to?: string, limit?: number, direction?: "f" | "b"): Promise; /** * Asks the user for permission to validate their identity through OpenID Connect. The * interface for this function is an observable which accepts the state machine of the * OIDC exchange flow. For example, if the client/user blocks the request then it would * feed back a `{state: Blocked}` into the observable. Similarly, if the user already * approved the widget then a `{state: Allowed}` would be fed into the observable alongside * the token itself. If the client is asking for permission, it should feed in a * `{state: PendingUserConfirmation}` followed by the relevant Allowed or Blocked state. * * The widget API will reject the widget's request with an error if this contract is not * met properly. By default, the widget driver will block all OIDC requests. * @param {SimpleObservable} observer The observable to feed updates into. */ askOpenID(observer: SimpleObservable): void; /** * Navigates the client with a matrix.to URI. In future this function will also be provided * with the Matrix URIs once matrix.to is replaced. The given URI will have already been * lightly checked to ensure it looks like a valid URI, though the implementation is recommended * to do further checks on the URI. * @param {string} uri The URI to navigate to. * @returns {Promise} Resolves when complete. * @throws Throws if there's a problem with the navigation, such as invalid format. */ navigate(uri: string): Promise; /** * Polls for TURN server data, yielding an initial set of credentials as soon as possible, and * thereafter yielding new credentials whenever the previous ones expire. The widget API will * have already verified that the widget has permission to access TURN servers. * @yields {ITurnServer} The TURN server URIs and credentials currently available to the client. */ getTurnServers(): AsyncGenerator; /** * Search for users in the user directory. * @param searchTerm The term to search for. * @param limit The maximum number of results to return. If not supplied, the * @returns Resolves to the search results. */ searchUserDirectory(searchTerm: string, limit?: number): Promise; /** * Get the config for the media repository. * @returns Promise which resolves with an object containing the config. */ getMediaConfig(): Promise; /** * Upload a file to the media repository on the homeserver. * @param file - The object to upload. Something that can be sent to * XMLHttpRequest.send (typically a File). * @returns Resolves to the location of the uploaded file. */ uploadFile(file: XMLHttpRequestBodyInit): Promise<{ contentUri: string; }>; /** * Download a file from the media repository on the homeserver. * @param contentUri - MXC URI of the file to download. * @returns Resolves to the contents of the file. */ downloadFile(contentUri: string): Promise<{ file: XMLHttpRequestBodyInit; }>; /** * Gets the IDs of all joined or invited rooms currently known to the * client. * @returns The room IDs. */ getKnownRooms(): string[]; /** * Expresses an error thrown by this driver in a format compatible with the Widget API. * @param error The error to handle. * @returns The error expressed as a {@link IWidgetApiErrorResponseDataDetails}, * or undefined if it cannot be expressed as one. */ processError(error: unknown): IWidgetApiErrorResponseDataDetails | undefined; }