372 lines
21 KiB
TypeScript
372 lines
21 KiB
TypeScript
import { Capability, IOpenIDCredentials, OpenIDRequestState, SimpleObservable, IRoomEvent, IRoomAccountData, ITurnServer, IWidgetApiErrorResponseDataDetails, IRtcTransport, IRtcLivekitGetTokenFromWidgetRequestData, IRtcLivekitGetTokenFromWidgetResponseData, IRtcLivekitDelegateDelayedLeaveFromWidgetRequestData, IRtcLivekitDelegateDelayedLeaveFromWidgetResponseData } 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;
|
|
}
|
|
export interface IRtcTransportsResult {
|
|
rtc_transports: IRtcTransport[];
|
|
}
|
|
/**
|
|
* 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<Capability>} requested The set of requested capabilities.
|
|
* @returns {Promise<Set<Capability>>} Resolves to the allowed capabilities.
|
|
*/
|
|
validateCapabilities(requested: Set<Capability>): Promise<Set<Capability>>;
|
|
/**
|
|
* 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<ISendEventDetails>} 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<ISendEventDetails>;
|
|
/**
|
|
* @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<ISendEventDetails>} 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<ISendEventDetails>;
|
|
/**
|
|
* @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} delay How much later to send the event.
|
|
* @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<ISendDelayedEventDetails>} 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, eventType: string, content: unknown, stateKey?: string | null, roomId?: string | null): Promise<ISendDelayedEventDetails>;
|
|
/**
|
|
* @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} delay How much later to send the event.
|
|
* @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<ISendDelayedEventDetails>} Resolves when the event has been sent with
|
|
* details of that event.
|
|
* @throws Rejected when the event could not be sent.
|
|
*/
|
|
sendDelayedStickyEvent(delay: number, stickyDurationMs: number, eventType: string, content: unknown, roomId?: string | null): Promise<ISendDelayedEventDetails>;
|
|
/**
|
|
* @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<void>;
|
|
/**
|
|
* @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<void>;
|
|
/**
|
|
* @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<void>;
|
|
/**
|
|
* 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<void>} 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<void>;
|
|
/**
|
|
* 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<IRoomAccountData[]>} Resolves to the element of room account data, or an empty array.
|
|
*/
|
|
readRoomAccountData(eventType: string, roomIds?: string[] | null): Promise<IRoomAccountData[]>;
|
|
/**
|
|
* 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<IRoomEvent[]>} 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<IRoomEvent[]>;
|
|
/**
|
|
* 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<IRoomEvent[]>} 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<IRoomEvent[]>;
|
|
/**
|
|
* 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<IRoomEvent[]>;
|
|
/**
|
|
* 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<IRoomEvent[]>} 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<IRoomEvent[]>;
|
|
/**
|
|
* 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<IRoomEvent[]>} Resolves to the events representing the
|
|
* current values of the room state entries.
|
|
*/
|
|
readRoomState(roomId: string, eventType: string, stateKey: string | undefined): Promise<IRoomEvent[]>;
|
|
/**
|
|
* 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<IReadEventRelationsResult>;
|
|
/**
|
|
* 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<IOpenIDUpdate>} observer The observable to feed updates into.
|
|
*/
|
|
askOpenID(observer: SimpleObservable<IOpenIDUpdate>): 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<void>} Resolves when complete.
|
|
* @throws Throws if there's a problem with the navigation, such as invalid format.
|
|
*/
|
|
navigate(uri: string): Promise<void>;
|
|
/**
|
|
* 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<ITurnServer>;
|
|
/**
|
|
* 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<ISearchUserDirectoryResult>;
|
|
/**
|
|
* Get the config for the media repository.
|
|
* @returns Promise which resolves with an object containing the config.
|
|
*/
|
|
getMediaConfig(): Promise<IGetMediaConfigResult>;
|
|
/**
|
|
* Discover the RTC transports (e.g. SFUs, TURN servers) the homeserver
|
|
* supports, by delegating to the authenticated
|
|
* `GET /_matrix/client/v1/rtc/transports` Client-Server endpoint (MSC4143).
|
|
* @returns Promise which resolves with the available transports.
|
|
*/
|
|
getRtcTransports(): Promise<IRtcTransportsResult>;
|
|
/**
|
|
* 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;
|
|
}>;
|
|
/**
|
|
* Obtains a JWT for a LiveKit SFU by calling the homeserver's
|
|
* `/rtc/livekit/get_token` endpoint on the widget's behalf. The widget API
|
|
* will have already verified that the widget has permission to do so.
|
|
* @param data The request data, to be used as the request body verbatim.
|
|
* @returns Resolves to the response body of the endpoint, verbatim.
|
|
* @see {@link https://github.com/matrix-org/matrix-spec-proposals/pull/4533|MSC4533}
|
|
*/
|
|
getRtcLivekitToken(data: IRtcLivekitGetTokenFromWidgetRequestData): Promise<IRtcLivekitGetTokenFromWidgetResponseData>;
|
|
/**
|
|
* Hands a MatrixRTC session's delayed leave event over to the server by
|
|
* calling the homeserver's `/rtc/livekit/delegate_delayed_leave` endpoint on
|
|
* the widget's behalf. The widget API will have already verified that the
|
|
* widget has permission to do so.
|
|
* @param data The request data, to be used as the request body verbatim.
|
|
* @returns Resolves to the response body of the endpoint, verbatim.
|
|
* @see {@link https://github.com/matrix-org/matrix-spec-proposals/pull/4533|MSC4533}
|
|
*/
|
|
delegateRtcLivekitDelayedLeave(data: IRtcLivekitDelegateDelayedLeaveFromWidgetRequestData): Promise<IRtcLivekitDelegateDelayedLeaveFromWidgetResponseData>;
|
|
/**
|
|
* 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;
|
|
}
|