· 6 years ago · Jan 06, 2020, 08:12 PM
1/// <reference types="node" />
2import { EventEmitter } from "events";
3import { IStorageProvider } from "./storage/IStorageProvider";
4import { IJoinRoomStrategy } from "./strategies/JoinRoomStrategy";
5import { UnstableApis } from "./UnstableApis";
6import { IPreprocessor } from "./preprocessors/IPreprocessor";
7/**
8 * A client that is capable of interacting with a matrix homeserver.
9 */
10export declare class MatrixClient extends EventEmitter {
11 private homeserverUrl;
12 private accessToken;
13 private storage;
14 /**
15 * The presence status to use while syncing. The valid values are "online" to set the account as online,
16 * "offline" to set the user as offline, "unavailable" for marking the user away, and null for not setting
17 * an explicit presence (the default).
18 *
19 * Has no effect if the client is not syncing. Does not apply until the next sync request.
20 */
21 syncingPresence: "online" | "offline" | "unavailable" | null;
22 /**
23 * The number of milliseconds to wait for new events for on the next sync.
24 *
25 * Has no effect if the client is not syncing. Does not apply until the next sync request.
26 */
27 syncingTimeout: number;
28 private userId;
29 private requestId;
30 private filterId;
31 private stopSyncing;
32 private lastJoinedRoomIds;
33 private impersonatedUserId;
34 private joinStrategy;
35 private eventProcessors;
36 /**
37 * Creates a new matrix client
38 * @param {string} homeserverUrl The homeserver's client-server API URL
39 * @param {string} accessToken The access token for the homeserver
40 * @param {IStorageProvider} storage The storage provider to use. Defaults to MemoryStorageProvider.
41 */
42 constructor(homeserverUrl: string, accessToken: string, storage?: IStorageProvider);
43 /**
44 * Gets the unstable API access class. This is generally not recommended to be
45 * used by clients.
46 * @return {UnstableApis} The unstable API access class.
47 */
48 readonly unstableApis: UnstableApis;
49 /**
50 * Sets a user ID to impersonate as. This will assume that the access token for this client
51 * is for an application service, and that the userId given is within the reach of the
52 * application service. Setting this to null will stop future impersonation. The user ID is
53 * assumed to already be valid
54 * @param {string} userId The user ID to masquerade as
55 */
56 impersonateUserId(userId: string): void;
57 /**
58 * Sets the strategy to use for when joinRoom is called on this client
59 * @param {IJoinRoomStrategy} strategy The strategy to use, or null to use none
60 */
61 setJoinStrategy(strategy: IJoinRoomStrategy): void;
62 /**
63 * Adds a preprocessor to the event pipeline. When this client encounters an event, it
64 * will try to run it through the preprocessors it can in the order they were added.
65 * @param {IPreprocessor} preprocessor the preprocessor to add
66 */
67 addPreprocessor(preprocessor: IPreprocessor): void;
68 private processEvent;
69 /**
70 * Adds a new room alias to the room directory
71 * @param {string} alias The alias to add (eg: "#my-room:matrix.org")
72 * @param {string} roomId The room ID to add the alias to
73 * @returns {Promise} resolves when the alias has been added
74 */
75 createRoomAlias(alias: string, roomId: string): Promise<any>;
76 /**
77 * Removes a room alias from the room directory
78 * @param {string} alias The alias to remove
79 * @returns {Promise} resolves when the alias has been deleted
80 */
81 deleteRoomAlias(alias: string): Promise<any>;
82 /**
83 * Sets the visibility of a room in the directory.
84 * @param {string} roomId The room ID to manipulate the visibility of
85 * @param {"public" | "private"} visibility The visibility to set for the room
86 * @return {Promise} resolves when the visibility has been updated
87 */
88 setDirectoryVisibility(roomId: string, visibility: "public" | "private"): Promise<any>;
89 /**
90 * Gets the visibility of a room in the directory.
91 * @param {string} roomId The room ID to query the visibility of
92 * @return {Promise<"public"|"private">} The visibility of the room
93 */
94 getDirectoryVisibility(roomId: string): Promise<"public" | "private">;
95 /**
96 * Resolves a room ID or alias to a room ID. If the given ID or alias looks like a room ID
97 * already, it will be returned as-is. If the room ID or alias looks like a room alias, it
98 * will be resolved to a room ID if possible. If the room ID or alias is neither, an error
99 * will be raised.
100 * @param {string} roomIdOrAlias the room ID or alias to resolve to a room ID
101 * @returns {Promise<string>} resolves to the room ID
102 */
103 resolveRoom(roomIdOrAlias: string): Promise<string>;
104 /**
105 * Does a room directory lookup for a given room alias
106 * @param {string} roomAlias the room alias to look up in the room directory
107 * @returns {Promise<RoomDirectoryLookupResponse>} resolves to the room's information
108 */
109 lookupRoomAlias(roomAlias: string): Promise<RoomDirectoryLookupResponse>;
110 /**
111 * Invites a user to a room.
112 * @param {string} userId the user ID to invite
113 * @param {string} roomId the room ID to invite the user to
114 * @returns {Promise<*>} resolves when completed
115 */
116 inviteUser(userId: any, roomId: any): Promise<any>;
117 /**
118 * Kicks a user from a room.
119 * @param {string} userId the user ID to kick
120 * @param {string} roomId the room ID to kick the user in
121 * @param {string?} reason optional reason for the kick
122 * @returns {Promise<*>} resolves when completed
123 */
124 kickUser(userId: any, roomId: any, reason?: any): Promise<any>;
125 /**
126 * Bans a user from a room.
127 * @param {string} userId the user ID to ban
128 * @param {string} roomId the room ID to set the ban in
129 * @param {string?} reason optional reason for the ban
130 * @returns {Promise<*>} resolves when completed
131 */
132 banUser(userId: any, roomId: any, reason?: any): Promise<any>;
133 /**
134 * Unbans a user in a room.
135 * @param {string} userId the user ID to unban
136 * @param {string} roomId the room ID to lift the ban in
137 * @returns {Promise<*>} resolves when completed
138 */
139 unbanUser(userId: any, roomId: any): Promise<any>;
140 /**
141 * Gets the current user ID for this client
142 * @returns {Promise<string>} The user ID of this client
143 */
144 getUserId(): Promise<string>;
145 /**
146 * Stops the client from syncing.
147 */
148 stop(): void;
149 /**
150 * Starts syncing the client with an optional filter
151 * @param {*} filter The filter to use, or null for none
152 * @returns {Promise<*>} Resolves when the client has started syncing
153 */
154 start(filter?: any): Promise<any>;
155 private startSync;
156 private doSync;
157 private processSync;
158 /**
159 * Gets an event for a room. Returned as a raw event.
160 * @param {string} roomId the room ID to get the event in
161 * @param {string} eventId the event ID to look up
162 * @returns {Promise<*>} resolves to the found event
163 */
164 getEvent(roomId: string, eventId: string): Promise<any>;
165 /**
166 * Gets the room state for the given room. Returned as raw events.
167 * @param {string} roomId the room ID to get state for
168 * @returns {Promise<*[]>} resolves to the room's state
169 */
170 getRoomState(roomId: string): Promise<any[]>;
171 /**
172 * Gets the state events for a given room of a given type under the given state key.
173 * @param {string} roomId the room ID
174 * @param {string} type the event type
175 * @param {String} stateKey the state key, falsey if not needed
176 * @returns {Promise<*|*[]>} resolves to the state event(s)
177 * @deprecated It is not possible to get an array of events - use getRoomStateEvent instead
178 */
179 getRoomStateEvents(roomId: any, type: any, stateKey: any): Promise<any | any[]>;
180 /**
181 * Gets a state event for a given room of a given type under the given state key.
182 * @param {string} roomId the room ID
183 * @param {string} type the event type
184 * @param {String} stateKey the state key
185 * @returns {Promise<*>} resolves to the state event
186 */
187 getRoomStateEvent(roomId: any, type: any, stateKey: any): Promise<any>;
188 /**
189 * Gets the profile for a given user
190 * @param {string} userId the user ID to lookup
191 * @returns {Promise<*>} the profile of the user
192 */
193 getUserProfile(userId: string): Promise<any>;
194 /**
195 * Sets a new display name for the user.
196 * @param {string} displayName the new display name for the user, or null to clear
197 * @returns {Promise<*>} resolves when complete
198 */
199 setDisplayName(displayName: string): Promise<any>;
200 /**
201 * Sets a new avatar url for the user.
202 * @param {string} avatarUrl the new avatar URL for the user, in the form of a Matrix Content URI
203 * @returns {Promise<*>} resolves when complete
204 */
205 setAvatarUrl(avatarUrl: string): Promise<any>;
206 /**
207 * Joins the given room
208 * @param {string} roomIdOrAlias the room ID or alias to join
209 * @param {string[]} viaServers the server names to try and join through
210 * @returns {Promise<string>} resolves to the joined room ID
211 */
212 joinRoom(roomIdOrAlias: string, viaServers?: string[]): Promise<string>;
213 /**
214 * Gets a list of joined room IDs
215 * @returns {Promise<string[]>} resolves to a list of room IDs the client participates in
216 */
217 getJoinedRooms(): Promise<string[]>;
218 /**
219 * Gets the joined members in a room. The client must be in the room to make this request.
220 * @param {string} roomId The room ID to get the joined members of.
221 * @returns {Promise<string>} The joined user IDs in the room
222 */
223 getJoinedRoomMembers(roomId: string): Promise<string[]>;
224 /**
225 * Gets Messages
226 * @param {string} roomId the room ID to get messages
227 * @returns {Promise<*>} resolves when left
228 */
229 getMessages(roomId: string, limit: number): Promise<string[]>;
230
231 /**
232 * Redact an event in a given room
233 * @param {string} roomId the room ID to send the redaction to
234 * @param {string} eventId the event ID to redact
235 * @param {String} reason an optional reason for redacting the event
236 * @returns {Promise<string>} resolves to the event ID that represents the redaction
237 */
238 redactEvent(roomId: string, eventId: string, reason: string): Promise<string>;
239
240 /**
241 * Leaves the given room
242 * @param {string} roomId the room ID to leave
243 * @returns {Promise<*>} resolves when left
244 */
245 leaveRoom(roomId: string): Promise<any>;
246 /**
247 * Sends a read receipt for an event in a room
248 * @param {string} roomId the room ID to send the receipt to
249 * @param {string} eventId the event ID to set the receipt at
250 * @returns {Promise<*>} resolves when the receipt has been sent
251 */
252 sendReadReceipt(roomId: string, eventId: string): Promise<any>;
253 /**
254 * Sends a notice to the given room
255 * @param {string} roomId the room ID to send the notice to
256 * @param {string} text the text to send
257 * @returns {Promise<string>} resolves to the event ID that represents the message
258 */
259 sendNotice(roomId: string, text: string): Promise<string>;
260 /**
261 * Sends a message to the given room
262 * @param {string} roomId the room ID to send the notice to
263 * @param {string} content the event body to send
264 * @returns {Promise<string>} resolves to the event ID that represents the message
265 */
266 sendMessage(roomId: string, content: any): Promise<string>;
267 /**
268 * Sends a state event to the given room
269 * @param {string} roomId the room ID to send the event to
270 * @param {string} type the event type to send
271 * @param {string} stateKey the state key to send, should not be null
272 * @param {string} content the event body to send
273 * @returns {Promise<string>} resolves to the event ID that represents the message
274 */
275 sendStateEvent(roomId: string, type: string, stateKey: string, content: any): Promise<string>;
276 /**
277 * Creates a room. This does not break out the various options for creating a room
278 * due to the large number of possibilities. See the /createRoom endpoint in the
279 * spec for more information on what to provide for `properties`.
280 * @param {*} properties the properties of the room. See the spec for more information
281 * @returns {Promise<string>} resolves to the room ID that represents the room
282 */
283 createRoom(properties?: any): Promise<string>;
284 /**
285 * Checks if a given user has a required power level
286 * @param {string} userId the user ID to check the power level of
287 * @param {string} roomId the room ID to check the power level in
288 * @param {string} eventType the event type to look for in the `events` property of the power levels
289 * @param {boolean} isState true to indicate the event is intended to be a state event
290 * @returns {Promise<boolean>} resolves to true if the user has the required power level, resolves to false otherwise
291 */
292 userHasPowerLevelFor(userId: string, roomId: string, eventType: string, isState: boolean): Promise<boolean>;
293 /**
294 * Uploads data to the homeserver's media repository.
295 * @param {Buffer} data the content to upload.
296 * @param {string} contentType the content type of the file. Defaults to application/octet-stream
297 * @param {string} filename the name of the file. Optional.
298 * @returns {Promise<string>} resolves to the MXC URI of the content
299 */
300 uploadContent(data: Buffer, contentType?: string, filename?: string): Promise<string>;
301 /**
302 * Determines the upgrade history for a given room as a doubly-linked list styled structure. Given
303 * a room ID in the history of upgrades, the resulting `previous` array will hold any rooms which
304 * are older than the given room. The resulting `newer` array will hold any rooms which are newer
305 * versions of the room. Both arrays will be defined, but may be empty individually. Element zero
306 * of each will always be the nearest to the given room ID and the last element will be the furthest
307 * from the room. The given room will never be in either array.
308 * @param {string} roomId the room ID to get the history of
309 * @returns {Promise<{previous: RoomReference[], newer: RoomReference[]}>} Resolves to the room's
310 * upgrade history
311 */
312 getRoomUpgradeHistory(roomId: string): Promise<{
313 previous: RoomReference[];
314 newer: RoomReference[];
315 current: RoomReference;
316 }>;
317 /**
318 * Performs a web request to the homeserver, applying appropriate authorization headers for
319 * this client.
320 * @param {"GET"|"POST"|"PUT"|"DELETE"} method The HTTP method to use in the request
321 * @param {string} endpoint The endpoint to call. For example: "/_matrix/client/r0/account/whoami"
322 * @param {*} qs The query string to send. Optional.
323 * @param {*} body The request body to send. Optional. Will be converted to JSON unless the type is a Buffer.
324 * @param {number} timeout The number of milliseconds to wait before timing out.
325 * @param {boolean} raw If true, the raw response will be returned instead of the response body.
326 * @param {string} contentType The content type to send. Only used if the `body` is a Buffer.
327 * @returns {Promise<*>} Resolves to the response (body), rejected if a non-2xx status code was returned.
328 */
329 doRequest(method: any, endpoint: any, qs?: any, body?: any, timeout?: number, raw?: boolean, contentType?: string): Promise<any>;
330}
331export interface RoomDirectoryLookupResponse {
332 roomId: string;
333 residentServers: string[];
334}
335export interface RoomReference {
336 /**
337 * The room ID being referenced
338 */
339 roomId: string;
340 /**
341 * The version of the room at the time
342 */
343 version: string;
344 /**
345 * If going backwards, the tombstone event ID, otherwise the creation
346 * event. If the room can't be verified, this will be null. Will be
347 * null if this reference is to the current room.
348 */
349 refEventId: string;
350}