1 | /*
|
2 | Copyright 2015, 2016 OpenMarket Ltd
|
3 | Copyright 2017 Vector Creations Ltd
|
4 |
|
5 | Licensed under the Apache License, Version 2.0 (the "License");
|
6 | you may not use this file except in compliance with the License.
|
7 | You may obtain a copy of the License at
|
8 |
|
9 | http://www.apache.org/licenses/LICENSE-2.0
|
10 |
|
11 | Unless required by applicable law or agreed to in writing, software
|
12 | distributed under the License is distributed on an "AS IS" BASIS,
|
13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
14 | See the License for the specific language governing permissions and
|
15 | limitations under the License.
|
16 | */
|
17 | ;
|
18 |
|
19 | /**
|
20 | * This is an internal module. MatrixBaseApis is currently only meant to be used
|
21 | * by {@link client~MatrixClient}.
|
22 | *
|
23 | * @module base-apis
|
24 | */
|
25 |
|
26 | var _typeof2 = require("babel-runtime/helpers/typeof");
|
27 |
|
28 | var _typeof3 = _interopRequireDefault(_typeof2);
|
29 |
|
30 | var _keys = require("babel-runtime/core-js/object/keys");
|
31 |
|
32 | var _keys2 = _interopRequireDefault(_keys);
|
33 |
|
34 | function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
|
35 |
|
36 | var httpApi = require("./http-api");
|
37 | var utils = require("./utils");
|
38 |
|
39 | /**
|
40 | * Low-level wrappers for the Matrix APIs
|
41 | *
|
42 | * @constructor
|
43 | *
|
44 | * @param {Object} opts Configuration options
|
45 | *
|
46 | * @param {string} opts.baseUrl Required. The base URL to the client-server
|
47 | * HTTP API.
|
48 | *
|
49 | * @param {string} opts.idBaseUrl Optional. The base identity server URL for
|
50 | * identity server requests.
|
51 | *
|
52 | * @param {Function} opts.request Required. The function to invoke for HTTP
|
53 | * requests. The value of this property is typically <code>require("request")
|
54 | * </code> as it returns a function which meets the required interface. See
|
55 | * {@link requestFunction} for more information.
|
56 | *
|
57 | * @param {string} opts.accessToken The access_token for this user.
|
58 | *
|
59 | * @param {Number=} opts.localTimeoutMs Optional. The default maximum amount of
|
60 | * time to wait before timing out HTTP requests. If not specified, there is no
|
61 | * timeout.
|
62 | *
|
63 | * @param {Object} opts.queryParams Optional. Extra query parameters to append
|
64 | * to all requests with this client. Useful for application services which require
|
65 | * <code>?user_id=</code>.
|
66 | *
|
67 | * @param {boolean} [opts.useAuthorizationHeader = false] Set to true to use
|
68 | * Authorization header instead of query param to send the access token to the server.
|
69 | */
|
70 | function MatrixBaseApis(opts) {
|
71 | utils.checkObjectHasKeys(opts, ["baseUrl", "request"]);
|
72 |
|
73 | this.baseUrl = opts.baseUrl;
|
74 | this.idBaseUrl = opts.idBaseUrl;
|
75 |
|
76 | var httpOpts = {
|
77 | baseUrl: opts.baseUrl,
|
78 | idBaseUrl: opts.idBaseUrl,
|
79 | accessToken: opts.accessToken,
|
80 | request: opts.request,
|
81 | prefix: httpApi.PREFIX_R0,
|
82 | onlyData: true,
|
83 | extraParams: opts.queryParams,
|
84 | localTimeoutMs: opts.localTimeoutMs,
|
85 | useAuthorizationHeader: opts.useAuthorizationHeader
|
86 | };
|
87 | this._http = new httpApi.MatrixHttpApi(this, httpOpts);
|
88 |
|
89 | this._txnCtr = 0;
|
90 | }
|
91 |
|
92 | /**
|
93 | * Get the Homeserver URL of this client
|
94 | * @return {string} Homeserver URL of this client
|
95 | */
|
96 | MatrixBaseApis.prototype.getHomeserverUrl = function () {
|
97 | return this.baseUrl;
|
98 | };
|
99 |
|
100 | /**
|
101 | * Get the Identity Server URL of this client
|
102 | * @param {boolean} stripProto whether or not to strip the protocol from the URL
|
103 | * @return {string} Identity Server URL of this client
|
104 | */
|
105 | MatrixBaseApis.prototype.getIdentityServerUrl = function () {
|
106 | var stripProto = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
|
107 |
|
108 | if (stripProto && (this.idBaseUrl.startsWith("http://") || this.idBaseUrl.startsWith("https://"))) {
|
109 | return this.idBaseUrl.split("://")[1];
|
110 | }
|
111 | return this.idBaseUrl;
|
112 | };
|
113 |
|
114 | /**
|
115 | * Get the access token associated with this account.
|
116 | * @return {?String} The access_token or null
|
117 | */
|
118 | MatrixBaseApis.prototype.getAccessToken = function () {
|
119 | return this._http.opts.accessToken || null;
|
120 | };
|
121 |
|
122 | /**
|
123 | * @return {boolean} true if there is a valid access_token for this client.
|
124 | */
|
125 | MatrixBaseApis.prototype.isLoggedIn = function () {
|
126 | return this._http.opts.accessToken !== undefined;
|
127 | };
|
128 |
|
129 | /**
|
130 | * Make up a new transaction id
|
131 | *
|
132 | * @return {string} a new, unique, transaction id
|
133 | */
|
134 | MatrixBaseApis.prototype.makeTxnId = function () {
|
135 | return "m" + new Date().getTime() + "." + this._txnCtr++;
|
136 | };
|
137 |
|
138 | // Registration/Login operations
|
139 | // =============================
|
140 |
|
141 | /**
|
142 | * Check whether a username is available prior to registration. An error response
|
143 | * indicates an invalid/unavailable username.
|
144 | * @param {string} username The username to check the availability of.
|
145 | * @return {module:client.Promise} Resolves: to `true`.
|
146 | */
|
147 | MatrixBaseApis.prototype.isUsernameAvailable = function (username) {
|
148 | return this._http.authedRequest(undefined, "GET", '/register/available', { username: username }).then(function (response) {
|
149 | return response.available;
|
150 | });
|
151 | };
|
152 |
|
153 | /**
|
154 | * @param {string} username
|
155 | * @param {string} password
|
156 | * @param {string} sessionId
|
157 | * @param {Object} auth
|
158 | * @param {Object} bindThreepids Set key 'email' to true to bind any email
|
159 | * threepid uses during registration in the ID server. Set 'msisdn' to
|
160 | * true to bind msisdn.
|
161 | * @param {string} guestAccessToken
|
162 | * @param {module:client.callback} callback Optional.
|
163 | * @return {module:client.Promise} Resolves: TODO
|
164 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
165 | */
|
166 | MatrixBaseApis.prototype.register = function (username, password, sessionId, auth, bindThreepids, guestAccessToken, callback) {
|
167 | // backwards compat
|
168 | if (bindThreepids === true) {
|
169 | bindThreepids = { email: true };
|
170 | } else if (bindThreepids === null || bindThreepids === undefined) {
|
171 | bindThreepids = {};
|
172 | }
|
173 |
|
174 | if (auth === undefined || auth === null) {
|
175 | auth = {};
|
176 | }
|
177 | if (sessionId) {
|
178 | auth.session = sessionId;
|
179 | }
|
180 |
|
181 | var params = {
|
182 | auth: auth
|
183 | };
|
184 | if (username !== undefined && username !== null) {
|
185 | params.username = username;
|
186 | }
|
187 | if (password !== undefined && password !== null) {
|
188 | params.password = password;
|
189 | }
|
190 | if (bindThreepids.email) {
|
191 | params.bind_email = true;
|
192 | }
|
193 | if (bindThreepids.msisdn) {
|
194 | params.bind_msisdn = true;
|
195 | }
|
196 | if (guestAccessToken !== undefined && guestAccessToken !== null) {
|
197 | params.guest_access_token = guestAccessToken;
|
198 | }
|
199 | // Temporary parameter added to make the register endpoint advertise
|
200 | // msisdn flows. This exists because there are clients that break
|
201 | // when given stages they don't recognise. This parameter will cease
|
202 | // to be necessary once these old clients are gone.
|
203 | // Only send it if we send any params at all (the password param is
|
204 | // mandatory, so if we send any params, we'll send the password param)
|
205 | if (password !== undefined && password !== null) {
|
206 | params.x_show_msisdn = true;
|
207 | }
|
208 |
|
209 | return this.registerRequest(params, undefined, callback);
|
210 | };
|
211 |
|
212 | /**
|
213 | * Register a guest account.
|
214 | * @param {Object=} opts Registration options
|
215 | * @param {Object} opts.body JSON HTTP body to provide.
|
216 | * @param {module:client.callback} callback Optional.
|
217 | * @return {module:client.Promise} Resolves: TODO
|
218 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
219 | */
|
220 | MatrixBaseApis.prototype.registerGuest = function (opts, callback) {
|
221 | opts = opts || {};
|
222 | opts.body = opts.body || {};
|
223 | return this.registerRequest(opts.body, "guest", callback);
|
224 | };
|
225 |
|
226 | /**
|
227 | * @param {Object} data parameters for registration request
|
228 | * @param {string=} kind type of user to register. may be "guest"
|
229 | * @param {module:client.callback=} callback
|
230 | * @return {module:client.Promise} Resolves: to the /register response
|
231 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
232 | */
|
233 | MatrixBaseApis.prototype.registerRequest = function (data, kind, callback) {
|
234 | var params = {};
|
235 | if (kind) {
|
236 | params.kind = kind;
|
237 | }
|
238 |
|
239 | return this._http.request(callback, "POST", "/register", params, data);
|
240 | };
|
241 |
|
242 | /**
|
243 | * @param {module:client.callback} callback Optional.
|
244 | * @return {module:client.Promise} Resolves: TODO
|
245 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
246 | */
|
247 | MatrixBaseApis.prototype.loginFlows = function (callback) {
|
248 | return this._http.request(callback, "GET", "/login");
|
249 | };
|
250 |
|
251 | /**
|
252 | * @param {string} loginType
|
253 | * @param {Object} data
|
254 | * @param {module:client.callback} callback Optional.
|
255 | * @return {module:client.Promise} Resolves: TODO
|
256 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
257 | */
|
258 | MatrixBaseApis.prototype.login = function (loginType, data, callback) {
|
259 | var login_data = {
|
260 | type: loginType
|
261 | };
|
262 |
|
263 | // merge data into login_data
|
264 | utils.extend(login_data, data);
|
265 |
|
266 | return this._http.authedRequest(callback, "POST", "/login", undefined, login_data);
|
267 | };
|
268 |
|
269 | /**
|
270 | * @param {string} user
|
271 | * @param {string} password
|
272 | * @param {module:client.callback} callback Optional.
|
273 | * @return {module:client.Promise} Resolves: TODO
|
274 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
275 | */
|
276 | MatrixBaseApis.prototype.loginWithPassword = function (user, password, callback) {
|
277 | return this.login("m.login.password", {
|
278 | user: user,
|
279 | password: password
|
280 | }, callback);
|
281 | };
|
282 |
|
283 | /**
|
284 | * @param {string} relayState URL Callback after SAML2 Authentication
|
285 | * @param {module:client.callback} callback Optional.
|
286 | * @return {module:client.Promise} Resolves: TODO
|
287 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
288 | */
|
289 | MatrixBaseApis.prototype.loginWithSAML2 = function (relayState, callback) {
|
290 | return this.login("m.login.saml2", {
|
291 | relay_state: relayState
|
292 | }, callback);
|
293 | };
|
294 |
|
295 | /**
|
296 | * @param {string} redirectUrl The URL to redirect to after the HS
|
297 | * authenticates with CAS.
|
298 | * @return {string} The HS URL to hit to begin the CAS login process.
|
299 | */
|
300 | MatrixBaseApis.prototype.getCasLoginUrl = function (redirectUrl) {
|
301 | return this._http.getUrl("/login/cas/redirect", {
|
302 | "redirectUrl": redirectUrl
|
303 | }, httpApi.PREFIX_UNSTABLE);
|
304 | };
|
305 |
|
306 | /**
|
307 | * @param {string} token Login token previously received from homeserver
|
308 | * @param {module:client.callback} callback Optional.
|
309 | * @return {module:client.Promise} Resolves: TODO
|
310 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
311 | */
|
312 | MatrixBaseApis.prototype.loginWithToken = function (token, callback) {
|
313 | return this.login("m.login.token", {
|
314 | token: token
|
315 | }, callback);
|
316 | };
|
317 |
|
318 | /**
|
319 | * Logs out the current session.
|
320 | * Obviously, further calls that require authorisation should fail after this
|
321 | * method is called. The state of the MatrixClient object is not affected:
|
322 | * it is up to the caller to either reset or destroy the MatrixClient after
|
323 | * this method succeeds.
|
324 | * @param {module:client.callback} callback Optional.
|
325 | * @return {module:client.Promise} Resolves: On success, the empty object
|
326 | */
|
327 | MatrixBaseApis.prototype.logout = function (callback) {
|
328 | return this._http.authedRequest(callback, "POST", '/logout');
|
329 | };
|
330 |
|
331 | /**
|
332 | * Deactivates the logged-in account.
|
333 | * Obviously, further calls that require authorisation should fail after this
|
334 | * method is called. The state of the MatrixClient object is not affected:
|
335 | * it is up to the caller to either reset or destroy the MatrixClient after
|
336 | * this method succeeds.
|
337 | * @param {object} auth Optional. Auth data to supply for User-Interactive auth.
|
338 | * @param {boolean} erase Optional. If set, send as `erase` attribute in the
|
339 | * JSON request body, indicating whether the account should be erased. Defaults
|
340 | * to false.
|
341 | * @return {module:client.Promise} Resolves: On success, the empty object
|
342 | */
|
343 | MatrixBaseApis.prototype.deactivateAccount = function (auth, erase) {
|
344 | if (typeof erase === 'function') {
|
345 | throw new Error('deactivateAccount no longer accepts a callback parameter');
|
346 | }
|
347 |
|
348 | var body = {};
|
349 | if (auth) {
|
350 | body.auth = auth;
|
351 | }
|
352 | if (erase !== undefined) {
|
353 | body.erase = erase;
|
354 | }
|
355 |
|
356 | return this._http.authedRequestWithPrefix(undefined, "POST", '/account/deactivate', undefined, body, httpApi.PREFIX_R0);
|
357 | };
|
358 |
|
359 | /**
|
360 | * Get the fallback URL to use for unknown interactive-auth stages.
|
361 | *
|
362 | * @param {string} loginType the type of stage being attempted
|
363 | * @param {string} authSessionId the auth session ID provided by the homeserver
|
364 | *
|
365 | * @return {string} HS URL to hit to for the fallback interface
|
366 | */
|
367 | MatrixBaseApis.prototype.getFallbackAuthUrl = function (loginType, authSessionId) {
|
368 | var path = utils.encodeUri("/auth/$loginType/fallback/web", {
|
369 | $loginType: loginType
|
370 | });
|
371 |
|
372 | return this._http.getUrl(path, {
|
373 | session: authSessionId
|
374 | }, httpApi.PREFIX_R0);
|
375 | };
|
376 |
|
377 | // Room operations
|
378 | // ===============
|
379 |
|
380 | /**
|
381 | * Create a new room.
|
382 | * @param {Object} options a list of options to pass to the /createRoom API.
|
383 | * @param {string} options.room_alias_name The alias localpart to assign to
|
384 | * this room.
|
385 | * @param {string} options.visibility Either 'public' or 'private'.
|
386 | * @param {string[]} options.invite A list of user IDs to invite to this room.
|
387 | * @param {string} options.name The name to give this room.
|
388 | * @param {string} options.topic The topic to give this room.
|
389 | * @param {module:client.callback} callback Optional.
|
390 | * @return {module:client.Promise} Resolves: <code>{room_id: {string},
|
391 | * room_alias: {string(opt)}}</code>
|
392 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
393 | */
|
394 | MatrixBaseApis.prototype.createRoom = function (options, callback) {
|
395 | // valid options include: room_alias_name, visibility, invite
|
396 | return this._http.authedRequest(callback, "POST", "/createRoom", undefined, options);
|
397 | };
|
398 |
|
399 | /**
|
400 | * @param {string} roomId
|
401 | * @param {module:client.callback} callback Optional.
|
402 | * @return {module:client.Promise} Resolves: TODO
|
403 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
404 | */
|
405 | MatrixBaseApis.prototype.roomState = function (roomId, callback) {
|
406 | var path = utils.encodeUri("/rooms/$roomId/state", { $roomId: roomId });
|
407 | return this._http.authedRequest(callback, "GET", path);
|
408 | };
|
409 |
|
410 | /**
|
411 | * @param {string} groupId
|
412 | * @return {module:client.Promise} Resolves: Group summary object
|
413 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
414 | */
|
415 | MatrixBaseApis.prototype.getGroupSummary = function (groupId) {
|
416 | var path = utils.encodeUri("/groups/$groupId/summary", { $groupId: groupId });
|
417 | return this._http.authedRequest(undefined, "GET", path);
|
418 | };
|
419 |
|
420 | /**
|
421 | * @param {string} groupId
|
422 | * @return {module:client.Promise} Resolves: Group profile object
|
423 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
424 | */
|
425 | MatrixBaseApis.prototype.getGroupProfile = function (groupId) {
|
426 | var path = utils.encodeUri("/groups/$groupId/profile", { $groupId: groupId });
|
427 | return this._http.authedRequest(undefined, "GET", path);
|
428 | };
|
429 |
|
430 | /**
|
431 | * @param {string} groupId
|
432 | * @param {Object} profile The group profile object
|
433 | * @param {string=} profile.name Name of the group
|
434 | * @param {string=} profile.avatar_url MXC avatar URL
|
435 | * @param {string=} profile.short_description A short description of the room
|
436 | * @param {string=} profile.long_description A longer HTML description of the room
|
437 | * @return {module:client.Promise} Resolves: Empty object
|
438 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
439 | */
|
440 | MatrixBaseApis.prototype.setGroupProfile = function (groupId, profile) {
|
441 | var path = utils.encodeUri("/groups/$groupId/profile", { $groupId: groupId });
|
442 | return this._http.authedRequest(undefined, "POST", path, undefined, profile);
|
443 | };
|
444 |
|
445 | /**
|
446 | * @param {string} groupId
|
447 | * @param {object} policy The join policy for the group. Must include at
|
448 | * least a 'type' field which is 'open' if anyone can join the group
|
449 | * the group without prior approval, or 'invite' if an invite is
|
450 | * required to join.
|
451 | * @return {module:client.Promise} Resolves: Empty object
|
452 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
453 | */
|
454 | MatrixBaseApis.prototype.setGroupJoinPolicy = function (groupId, policy) {
|
455 | var path = utils.encodeUri("/groups/$groupId/settings/m.join_policy", { $groupId: groupId });
|
456 | return this._http.authedRequest(undefined, "PUT", path, undefined, {
|
457 | 'm.join_policy': policy
|
458 | });
|
459 | };
|
460 |
|
461 | /**
|
462 | * @param {string} groupId
|
463 | * @return {module:client.Promise} Resolves: Group users list object
|
464 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
465 | */
|
466 | MatrixBaseApis.prototype.getGroupUsers = function (groupId) {
|
467 | var path = utils.encodeUri("/groups/$groupId/users", { $groupId: groupId });
|
468 | return this._http.authedRequest(undefined, "GET", path);
|
469 | };
|
470 |
|
471 | /**
|
472 | * @param {string} groupId
|
473 | * @return {module:client.Promise} Resolves: Group users list object
|
474 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
475 | */
|
476 | MatrixBaseApis.prototype.getGroupInvitedUsers = function (groupId) {
|
477 | var path = utils.encodeUri("/groups/$groupId/invited_users", { $groupId: groupId });
|
478 | return this._http.authedRequest(undefined, "GET", path);
|
479 | };
|
480 |
|
481 | /**
|
482 | * @param {string} groupId
|
483 | * @return {module:client.Promise} Resolves: Group rooms list object
|
484 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
485 | */
|
486 | MatrixBaseApis.prototype.getGroupRooms = function (groupId) {
|
487 | var path = utils.encodeUri("/groups/$groupId/rooms", { $groupId: groupId });
|
488 | return this._http.authedRequest(undefined, "GET", path);
|
489 | };
|
490 |
|
491 | /**
|
492 | * @param {string} groupId
|
493 | * @param {string} userId
|
494 | * @return {module:client.Promise} Resolves: Empty object
|
495 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
496 | */
|
497 | MatrixBaseApis.prototype.inviteUserToGroup = function (groupId, userId) {
|
498 | var path = utils.encodeUri("/groups/$groupId/admin/users/invite/$userId", { $groupId: groupId, $userId: userId });
|
499 | return this._http.authedRequest(undefined, "PUT", path, undefined, {});
|
500 | };
|
501 |
|
502 | /**
|
503 | * @param {string} groupId
|
504 | * @param {string} userId
|
505 | * @return {module:client.Promise} Resolves: Empty object
|
506 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
507 | */
|
508 | MatrixBaseApis.prototype.removeUserFromGroup = function (groupId, userId) {
|
509 | var path = utils.encodeUri("/groups/$groupId/admin/users/remove/$userId", { $groupId: groupId, $userId: userId });
|
510 | return this._http.authedRequest(undefined, "PUT", path, undefined, {});
|
511 | };
|
512 |
|
513 | /**
|
514 | * @param {string} groupId
|
515 | * @param {string} userId
|
516 | * @param {string} roleId Optional.
|
517 | * @return {module:client.Promise} Resolves: Empty object
|
518 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
519 | */
|
520 | MatrixBaseApis.prototype.addUserToGroupSummary = function (groupId, userId, roleId) {
|
521 | var path = utils.encodeUri(roleId ? "/groups/$groupId/summary/$roleId/users/$userId" : "/groups/$groupId/summary/users/$userId", { $groupId: groupId, $roleId: roleId, $userId: userId });
|
522 | return this._http.authedRequest(undefined, "PUT", path, undefined, {});
|
523 | };
|
524 |
|
525 | /**
|
526 | * @param {string} groupId
|
527 | * @param {string} userId
|
528 | * @return {module:client.Promise} Resolves: Empty object
|
529 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
530 | */
|
531 | MatrixBaseApis.prototype.removeUserFromGroupSummary = function (groupId, userId) {
|
532 | var path = utils.encodeUri("/groups/$groupId/summary/users/$userId", { $groupId: groupId, $userId: userId });
|
533 | return this._http.authedRequest(undefined, "DELETE", path, undefined, {});
|
534 | };
|
535 |
|
536 | /**
|
537 | * @param {string} groupId
|
538 | * @param {string} roomId
|
539 | * @param {string} categoryId Optional.
|
540 | * @return {module:client.Promise} Resolves: Empty object
|
541 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
542 | */
|
543 | MatrixBaseApis.prototype.addRoomToGroupSummary = function (groupId, roomId, categoryId) {
|
544 | var path = utils.encodeUri(categoryId ? "/groups/$groupId/summary/$categoryId/rooms/$roomId" : "/groups/$groupId/summary/rooms/$roomId", { $groupId: groupId, $categoryId: categoryId, $roomId: roomId });
|
545 | return this._http.authedRequest(undefined, "PUT", path, undefined, {});
|
546 | };
|
547 |
|
548 | /**
|
549 | * @param {string} groupId
|
550 | * @param {string} roomId
|
551 | * @return {module:client.Promise} Resolves: Empty object
|
552 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
553 | */
|
554 | MatrixBaseApis.prototype.removeRoomFromGroupSummary = function (groupId, roomId) {
|
555 | var path = utils.encodeUri("/groups/$groupId/summary/rooms/$roomId", { $groupId: groupId, $roomId: roomId });
|
556 | return this._http.authedRequest(undefined, "DELETE", path, undefined, {});
|
557 | };
|
558 |
|
559 | /**
|
560 | * @param {string} groupId
|
561 | * @param {string} roomId
|
562 | * @param {bool} isPublic Whether the room-group association is visible to non-members
|
563 | * @return {module:client.Promise} Resolves: Empty object
|
564 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
565 | */
|
566 | MatrixBaseApis.prototype.addRoomToGroup = function (groupId, roomId, isPublic) {
|
567 | if (isPublic === undefined) {
|
568 | isPublic = true;
|
569 | }
|
570 | var path = utils.encodeUri("/groups/$groupId/admin/rooms/$roomId", { $groupId: groupId, $roomId: roomId });
|
571 | return this._http.authedRequest(undefined, "PUT", path, undefined, { "m.visibility": { type: isPublic ? "public" : "private" } });
|
572 | };
|
573 |
|
574 | /**
|
575 | * Configure the visibility of a room-group association.
|
576 | * @param {string} groupId
|
577 | * @param {string} roomId
|
578 | * @param {bool} isPublic Whether the room-group association is visible to non-members
|
579 | * @return {module:client.Promise} Resolves: Empty object
|
580 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
581 | */
|
582 | MatrixBaseApis.prototype.updateGroupRoomVisibility = function (groupId, roomId, isPublic) {
|
583 | // NB: The /config API is generic but there's not much point in exposing this yet as synapse
|
584 | // is the only server to implement this. In future we should consider an API that allows
|
585 | // arbitrary configuration, i.e. "config/$configKey".
|
586 |
|
587 | var path = utils.encodeUri("/groups/$groupId/admin/rooms/$roomId/config/m.visibility", { $groupId: groupId, $roomId: roomId });
|
588 | return this._http.authedRequest(undefined, "PUT", path, undefined, { type: isPublic ? "public" : "private" });
|
589 | };
|
590 |
|
591 | /**
|
592 | * @param {string} groupId
|
593 | * @param {string} roomId
|
594 | * @return {module:client.Promise} Resolves: Empty object
|
595 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
596 | */
|
597 | MatrixBaseApis.prototype.removeRoomFromGroup = function (groupId, roomId) {
|
598 | var path = utils.encodeUri("/groups/$groupId/admin/rooms/$roomId", { $groupId: groupId, $roomId: roomId });
|
599 | return this._http.authedRequest(undefined, "DELETE", path, undefined, {});
|
600 | };
|
601 |
|
602 | /**
|
603 | * @param {string} groupId
|
604 | * @param {Object} opts Additional options to send alongside the acceptance.
|
605 | * @return {module:client.Promise} Resolves: Empty object
|
606 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
607 | */
|
608 | MatrixBaseApis.prototype.acceptGroupInvite = function (groupId) {
|
609 | var opts = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
|
610 |
|
611 | var path = utils.encodeUri("/groups/$groupId/self/accept_invite", { $groupId: groupId });
|
612 | return this._http.authedRequest(undefined, "PUT", path, undefined, opts || {});
|
613 | };
|
614 |
|
615 | /**
|
616 | * @param {string} groupId
|
617 | * @return {module:client.Promise} Resolves: Empty object
|
618 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
619 | */
|
620 | MatrixBaseApis.prototype.joinGroup = function (groupId) {
|
621 | var path = utils.encodeUri("/groups/$groupId/self/join", { $groupId: groupId });
|
622 | return this._http.authedRequest(undefined, "PUT", path, undefined, {});
|
623 | };
|
624 |
|
625 | /**
|
626 | * @param {string} groupId
|
627 | * @return {module:client.Promise} Resolves: Empty object
|
628 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
629 | */
|
630 | MatrixBaseApis.prototype.leaveGroup = function (groupId) {
|
631 | var path = utils.encodeUri("/groups/$groupId/self/leave", { $groupId: groupId });
|
632 | return this._http.authedRequest(undefined, "PUT", path, undefined, {});
|
633 | };
|
634 |
|
635 | /**
|
636 | * @return {module:client.Promise} Resolves: The groups to which the user is joined
|
637 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
638 | */
|
639 | MatrixBaseApis.prototype.getJoinedGroups = function () {
|
640 | var path = utils.encodeUri("/joined_groups");
|
641 | return this._http.authedRequest(undefined, "GET", path);
|
642 | };
|
643 |
|
644 | /**
|
645 | * @param {Object} content Request content
|
646 | * @param {string} content.localpart The local part of the desired group ID
|
647 | * @param {Object} content.profile Group profile object
|
648 | * @return {module:client.Promise} Resolves: Object with key group_id: id of the created group
|
649 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
650 | */
|
651 | MatrixBaseApis.prototype.createGroup = function (content) {
|
652 | var path = utils.encodeUri("/create_group");
|
653 | return this._http.authedRequest(undefined, "POST", path, undefined, content);
|
654 | };
|
655 |
|
656 | /**
|
657 | * @param {string[]} userIds List of user IDs
|
658 | * @return {module:client.Promise} Resolves: Object as exmaple below
|
659 | *
|
660 | * {
|
661 | * "users": {
|
662 | * "@bob:example.com": {
|
663 | * "+example:example.com"
|
664 | * }
|
665 | * }
|
666 | * }
|
667 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
668 | */
|
669 | MatrixBaseApis.prototype.getPublicisedGroups = function (userIds) {
|
670 | var path = utils.encodeUri("/publicised_groups");
|
671 | return this._http.authedRequest(undefined, "POST", path, undefined, { user_ids: userIds });
|
672 | };
|
673 |
|
674 | /**
|
675 | * @param {string} groupId
|
676 | * @param {bool} isPublic Whether the user's membership of this group is made public
|
677 | * @return {module:client.Promise} Resolves: Empty object
|
678 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
679 | */
|
680 | MatrixBaseApis.prototype.setGroupPublicity = function (groupId, isPublic) {
|
681 | var path = utils.encodeUri("/groups/$groupId/self/update_publicity", { $groupId: groupId });
|
682 | return this._http.authedRequest(undefined, "PUT", path, undefined, {
|
683 | publicise: isPublic
|
684 | });
|
685 | };
|
686 |
|
687 | /**
|
688 | * Retrieve a state event.
|
689 | * @param {string} roomId
|
690 | * @param {string} eventType
|
691 | * @param {string} stateKey
|
692 | * @param {module:client.callback} callback Optional.
|
693 | * @return {module:client.Promise} Resolves: TODO
|
694 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
695 | */
|
696 | MatrixBaseApis.prototype.getStateEvent = function (roomId, eventType, stateKey, callback) {
|
697 | var pathParams = {
|
698 | $roomId: roomId,
|
699 | $eventType: eventType,
|
700 | $stateKey: stateKey
|
701 | };
|
702 | var path = utils.encodeUri("/rooms/$roomId/state/$eventType", pathParams);
|
703 | if (stateKey !== undefined) {
|
704 | path = utils.encodeUri(path + "/$stateKey", pathParams);
|
705 | }
|
706 | return this._http.authedRequest(callback, "GET", path);
|
707 | };
|
708 |
|
709 | /**
|
710 | * @param {string} roomId
|
711 | * @param {string} eventType
|
712 | * @param {Object} content
|
713 | * @param {string} stateKey
|
714 | * @param {module:client.callback} callback Optional.
|
715 | * @return {module:client.Promise} Resolves: TODO
|
716 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
717 | */
|
718 | MatrixBaseApis.prototype.sendStateEvent = function (roomId, eventType, content, stateKey, callback) {
|
719 | var pathParams = {
|
720 | $roomId: roomId,
|
721 | $eventType: eventType,
|
722 | $stateKey: stateKey
|
723 | };
|
724 | var path = utils.encodeUri("/rooms/$roomId/state/$eventType", pathParams);
|
725 | if (stateKey !== undefined) {
|
726 | path = utils.encodeUri(path + "/$stateKey", pathParams);
|
727 | }
|
728 | return this._http.authedRequest(callback, "PUT", path, undefined, content);
|
729 | };
|
730 |
|
731 | /**
|
732 | * @param {string} roomId
|
733 | * @param {string} eventId
|
734 | * @param {module:client.callback} callback Optional.
|
735 | * @return {module:client.Promise} Resolves: TODO
|
736 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
737 | */
|
738 | MatrixBaseApis.prototype.redactEvent = function (roomId, eventId, callback) {
|
739 | var path = utils.encodeUri("/rooms/$roomId/redact/$eventId", {
|
740 | $roomId: roomId,
|
741 | $eventId: eventId
|
742 | });
|
743 | return this._http.authedRequest(callback, "POST", path, undefined, {});
|
744 | };
|
745 |
|
746 | /**
|
747 | * @param {string} roomId
|
748 | * @param {Number} limit
|
749 | * @param {module:client.callback} callback Optional.
|
750 | * @return {module:client.Promise} Resolves: TODO
|
751 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
752 | */
|
753 | MatrixBaseApis.prototype.roomInitialSync = function (roomId, limit, callback) {
|
754 | if (utils.isFunction(limit)) {
|
755 | callback = limit;limit = undefined;
|
756 | }
|
757 | var path = utils.encodeUri("/rooms/$roomId/initialSync", { $roomId: roomId });
|
758 | if (!limit) {
|
759 | limit = 30;
|
760 | }
|
761 | return this._http.authedRequest(callback, "GET", path, { limit: limit });
|
762 | };
|
763 |
|
764 | /**
|
765 | * Set a marker to indicate the point in a room before which the user has read every
|
766 | * event. This can be retrieved from room account data (the event type is `m.fully_read`)
|
767 | * and displayed as a horizontal line in the timeline that is visually distinct to the
|
768 | * position of the user's own read receipt.
|
769 | * @param {string} roomId ID of the room that has been read
|
770 | * @param {string} rmEventId ID of the event that has been read
|
771 | * @param {string} rrEventId ID of the event tracked by the read receipt. This is here
|
772 | * for convenience because the RR and the RM are commonly updated at the same time as
|
773 | * each other. Optional.
|
774 | * @return {module:client.Promise} Resolves: the empty object, {}.
|
775 | */
|
776 | MatrixBaseApis.prototype.setRoomReadMarkersHttpRequest = function (roomId, rmEventId, rrEventId) {
|
777 | var path = utils.encodeUri("/rooms/$roomId/read_markers", {
|
778 | $roomId: roomId
|
779 | });
|
780 |
|
781 | var content = {
|
782 | "m.fully_read": rmEventId,
|
783 | "m.read": rrEventId
|
784 | };
|
785 |
|
786 | return this._http.authedRequest(undefined, "POST", path, undefined, content);
|
787 | };
|
788 |
|
789 | // Room Directory operations
|
790 | // =========================
|
791 |
|
792 | /**
|
793 | * @param {Object} options Options for this request
|
794 | * @param {string} options.server The remote server to query for the room list.
|
795 | * Optional. If unspecified, get the local home
|
796 | * server's public room list.
|
797 | * @param {number} options.limit Maximum number of entries to return
|
798 | * @param {string} options.since Token to paginate from
|
799 | * @param {object} options.filter Filter parameters
|
800 | * @param {string} options.filter.generic_search_term String to search for
|
801 | * @param {module:client.callback} callback Optional.
|
802 | * @return {module:client.Promise} Resolves: TODO
|
803 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
804 | */
|
805 | MatrixBaseApis.prototype.publicRooms = function (options, callback) {
|
806 | if (typeof options == 'function') {
|
807 | callback = options;
|
808 | options = {};
|
809 | }
|
810 | if (options === undefined) {
|
811 | options = {};
|
812 | }
|
813 |
|
814 | var query_params = {};
|
815 | if (options.server) {
|
816 | query_params.server = options.server;
|
817 | delete options.server;
|
818 | }
|
819 |
|
820 | if ((0, _keys2.default)(options).length === 0 && (0, _keys2.default)(query_params).length === 0) {
|
821 | return this._http.authedRequest(callback, "GET", "/publicRooms");
|
822 | } else {
|
823 | return this._http.authedRequest(callback, "POST", "/publicRooms", query_params, options);
|
824 | }
|
825 | };
|
826 |
|
827 | /**
|
828 | * Create an alias to room ID mapping.
|
829 | * @param {string} alias The room alias to create.
|
830 | * @param {string} roomId The room ID to link the alias to.
|
831 | * @param {module:client.callback} callback Optional.
|
832 | * @return {module:client.Promise} Resolves: TODO.
|
833 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
834 | */
|
835 | MatrixBaseApis.prototype.createAlias = function (alias, roomId, callback) {
|
836 | var path = utils.encodeUri("/directory/room/$alias", {
|
837 | $alias: alias
|
838 | });
|
839 | var data = {
|
840 | room_id: roomId
|
841 | };
|
842 | return this._http.authedRequest(callback, "PUT", path, undefined, data);
|
843 | };
|
844 |
|
845 | /**
|
846 | * Delete an alias to room ID mapping. This alias must be on your local server
|
847 | * and you must have sufficient access to do this operation.
|
848 | * @param {string} alias The room alias to delete.
|
849 | * @param {module:client.callback} callback Optional.
|
850 | * @return {module:client.Promise} Resolves: TODO.
|
851 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
852 | */
|
853 | MatrixBaseApis.prototype.deleteAlias = function (alias, callback) {
|
854 | var path = utils.encodeUri("/directory/room/$alias", {
|
855 | $alias: alias
|
856 | });
|
857 | return this._http.authedRequest(callback, "DELETE", path, undefined, undefined);
|
858 | };
|
859 |
|
860 | /**
|
861 | * Get room info for the given alias.
|
862 | * @param {string} alias The room alias to resolve.
|
863 | * @param {module:client.callback} callback Optional.
|
864 | * @return {module:client.Promise} Resolves: Object with room_id and servers.
|
865 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
866 | */
|
867 | MatrixBaseApis.prototype.getRoomIdForAlias = function (alias, callback) {
|
868 | // TODO: deprecate this or resolveRoomAlias
|
869 | var path = utils.encodeUri("/directory/room/$alias", {
|
870 | $alias: alias
|
871 | });
|
872 | return this._http.authedRequest(callback, "GET", path);
|
873 | };
|
874 |
|
875 | /**
|
876 | * @param {string} roomAlias
|
877 | * @param {module:client.callback} callback Optional.
|
878 | * @return {module:client.Promise} Resolves: TODO
|
879 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
880 | */
|
881 | MatrixBaseApis.prototype.resolveRoomAlias = function (roomAlias, callback) {
|
882 | // TODO: deprecate this or getRoomIdForAlias
|
883 | var path = utils.encodeUri("/directory/room/$alias", { $alias: roomAlias });
|
884 | return this._http.request(callback, "GET", path);
|
885 | };
|
886 |
|
887 | /**
|
888 | * Get the visibility of a room in the current HS's room directory
|
889 | * @param {string} roomId
|
890 | * @param {module:client.callback} callback Optional.
|
891 | * @return {module:client.Promise} Resolves: TODO
|
892 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
893 | */
|
894 | MatrixBaseApis.prototype.getRoomDirectoryVisibility = function (roomId, callback) {
|
895 | var path = utils.encodeUri("/directory/list/room/$roomId", {
|
896 | $roomId: roomId
|
897 | });
|
898 | return this._http.authedRequest(callback, "GET", path);
|
899 | };
|
900 |
|
901 | /**
|
902 | * Set the visbility of a room in the current HS's room directory
|
903 | * @param {string} roomId
|
904 | * @param {string} visibility "public" to make the room visible
|
905 | * in the public directory, or "private" to make
|
906 | * it invisible.
|
907 | * @param {module:client.callback} callback Optional.
|
908 | * @return {module:client.Promise} Resolves: result object
|
909 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
910 | */
|
911 | MatrixBaseApis.prototype.setRoomDirectoryVisibility = function (roomId, visibility, callback) {
|
912 | var path = utils.encodeUri("/directory/list/room/$roomId", {
|
913 | $roomId: roomId
|
914 | });
|
915 | return this._http.authedRequest(callback, "PUT", path, undefined, { "visibility": visibility });
|
916 | };
|
917 |
|
918 | /**
|
919 | * Set the visbility of a room bridged to a 3rd party network in
|
920 | * the current HS's room directory.
|
921 | * @param {string} networkId the network ID of the 3rd party
|
922 | * instance under which this room is published under.
|
923 | * @param {string} roomId
|
924 | * @param {string} visibility "public" to make the room visible
|
925 | * in the public directory, or "private" to make
|
926 | * it invisible.
|
927 | * @param {module:client.callback} callback Optional.
|
928 | * @return {module:client.Promise} Resolves: result object
|
929 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
930 | */
|
931 | MatrixBaseApis.prototype.setRoomDirectoryVisibilityAppService = function (networkId, roomId, visibility, callback) {
|
932 | var path = utils.encodeUri("/directory/list/appservice/$networkId/$roomId", {
|
933 | $networkId: networkId,
|
934 | $roomId: roomId
|
935 | });
|
936 | return this._http.authedRequest(callback, "PUT", path, undefined, { "visibility": visibility });
|
937 | };
|
938 |
|
939 | // User Directory Operations
|
940 | // =========================
|
941 |
|
942 | /**
|
943 | * Query the user directory with a term matching user IDs, display names and domains.
|
944 | * @param {object} opts options
|
945 | * @param {string} opts.term the term with which to search.
|
946 | * @param {number} opts.limit the maximum number of results to return. The server will
|
947 | * apply a limit if unspecified.
|
948 | * @return {module:client.Promise} Resolves: an array of results.
|
949 | */
|
950 | MatrixBaseApis.prototype.searchUserDirectory = function (opts) {
|
951 | var body = {
|
952 | search_term: opts.term
|
953 | };
|
954 |
|
955 | if (opts.limit !== undefined) {
|
956 | body.limit = opts.limit;
|
957 | }
|
958 |
|
959 | return this._http.authedRequest(undefined, "POST", "/user_directory/search", undefined, body);
|
960 | };
|
961 |
|
962 | // Media operations
|
963 | // ================
|
964 |
|
965 | /**
|
966 | * Upload a file to the media repository on the home server.
|
967 | *
|
968 | * @param {object} file The object to upload. On a browser, something that
|
969 | * can be sent to XMLHttpRequest.send (typically a File). Under node.js,
|
970 | * a a Buffer, String or ReadStream.
|
971 | *
|
972 | * @param {object} opts options object
|
973 | *
|
974 | * @param {string=} opts.name Name to give the file on the server. Defaults
|
975 | * to <tt>file.name</tt>.
|
976 | *
|
977 | * @param {string=} opts.type Content-type for the upload. Defaults to
|
978 | * <tt>file.type</tt>, or <tt>applicaton/octet-stream</tt>.
|
979 | *
|
980 | * @param {boolean=} opts.rawResponse Return the raw body, rather than
|
981 | * parsing the JSON. Defaults to false (except on node.js, where it
|
982 | * defaults to true for backwards compatibility).
|
983 | *
|
984 | * @param {boolean=} opts.onlyContentUri Just return the content URI,
|
985 | * rather than the whole body. Defaults to false (except on browsers,
|
986 | * where it defaults to true for backwards compatibility). Ignored if
|
987 | * opts.rawResponse is true.
|
988 | *
|
989 | * @param {Function=} opts.callback Deprecated. Optional. The callback to
|
990 | * invoke on success/failure. See the promise return values for more
|
991 | * information.
|
992 | *
|
993 | * @param {Function=} opts.progressHandler Optional. Called when a chunk of
|
994 | * data has been uploaded, with an object containing the fields `loaded`
|
995 | * (number of bytes transferred) and `total` (total size, if known).
|
996 | *
|
997 | * @return {module:client.Promise} Resolves to response object, as
|
998 | * determined by this.opts.onlyData, opts.rawResponse, and
|
999 | * opts.onlyContentUri. Rejects with an error (usually a MatrixError).
|
1000 | */
|
1001 | MatrixBaseApis.prototype.uploadContent = function (file, opts) {
|
1002 | return this._http.uploadContent(file, opts);
|
1003 | };
|
1004 |
|
1005 | /**
|
1006 | * Cancel a file upload in progress
|
1007 | * @param {module:client.Promise} promise The promise returned from uploadContent
|
1008 | * @return {boolean} true if canceled, otherwise false
|
1009 | */
|
1010 | MatrixBaseApis.prototype.cancelUpload = function (promise) {
|
1011 | return this._http.cancelUpload(promise);
|
1012 | };
|
1013 |
|
1014 | /**
|
1015 | * Get a list of all file uploads in progress
|
1016 | * @return {array} Array of objects representing current uploads.
|
1017 | * Currently in progress is element 0. Keys:
|
1018 | * - promise: The promise associated with the upload
|
1019 | * - loaded: Number of bytes uploaded
|
1020 | * - total: Total number of bytes to upload
|
1021 | */
|
1022 | MatrixBaseApis.prototype.getCurrentUploads = function () {
|
1023 | return this._http.getCurrentUploads();
|
1024 | };
|
1025 |
|
1026 | // Profile operations
|
1027 | // ==================
|
1028 |
|
1029 | /**
|
1030 | * @param {string} userId
|
1031 | * @param {string} info The kind of info to retrieve (e.g. 'displayname',
|
1032 | * 'avatar_url').
|
1033 | * @param {module:client.callback} callback Optional.
|
1034 | * @return {module:client.Promise} Resolves: TODO
|
1035 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1036 | */
|
1037 | MatrixBaseApis.prototype.getProfileInfo = function (userId, info, callback) {
|
1038 | if (utils.isFunction(info)) {
|
1039 | callback = info;info = undefined;
|
1040 | }
|
1041 |
|
1042 | var path = info ? utils.encodeUri("/profile/$userId/$info", { $userId: userId, $info: info }) : utils.encodeUri("/profile/$userId", { $userId: userId });
|
1043 | return this._http.authedRequest(callback, "GET", path);
|
1044 | };
|
1045 |
|
1046 | // Account operations
|
1047 | // ==================
|
1048 |
|
1049 | /**
|
1050 | * @param {module:client.callback} callback Optional.
|
1051 | * @return {module:client.Promise} Resolves: TODO
|
1052 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1053 | */
|
1054 | MatrixBaseApis.prototype.getThreePids = function (callback) {
|
1055 | var path = "/account/3pid";
|
1056 | return this._http.authedRequest(callback, "GET", path, undefined, undefined);
|
1057 | };
|
1058 |
|
1059 | /**
|
1060 | * @param {Object} creds
|
1061 | * @param {boolean} bind
|
1062 | * @param {module:client.callback} callback Optional.
|
1063 | * @return {module:client.Promise} Resolves: TODO
|
1064 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1065 | */
|
1066 | MatrixBaseApis.prototype.addThreePid = function (creds, bind, callback) {
|
1067 | var path = "/account/3pid";
|
1068 | var data = {
|
1069 | 'threePidCreds': creds,
|
1070 | 'bind': bind
|
1071 | };
|
1072 | return this._http.authedRequest(callback, "POST", path, null, data);
|
1073 | };
|
1074 |
|
1075 | /**
|
1076 | * @param {string} medium The threepid medium (eg. 'email')
|
1077 | * @param {string} address The threepid address (eg. 'bob@example.com')
|
1078 | * this must be as returned by getThreePids.
|
1079 | * @return {module:client.Promise} Resolves: The server response on success
|
1080 | * (generally the empty JSON object)
|
1081 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1082 | */
|
1083 | MatrixBaseApis.prototype.deleteThreePid = function (medium, address) {
|
1084 | var path = "/account/3pid/delete";
|
1085 | var data = {
|
1086 | 'medium': medium,
|
1087 | 'address': address
|
1088 | };
|
1089 | return this._http.authedRequestWithPrefix(undefined, "POST", path, null, data, httpApi.PREFIX_UNSTABLE);
|
1090 | };
|
1091 |
|
1092 | /**
|
1093 | * Make a request to change your password.
|
1094 | * @param {Object} authDict
|
1095 | * @param {string} newPassword The new desired password.
|
1096 | * @param {module:client.callback} callback Optional.
|
1097 | * @return {module:client.Promise} Resolves: TODO
|
1098 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1099 | */
|
1100 | MatrixBaseApis.prototype.setPassword = function (authDict, newPassword, callback) {
|
1101 | var path = "/account/password";
|
1102 | var data = {
|
1103 | 'auth': authDict,
|
1104 | 'new_password': newPassword
|
1105 | };
|
1106 |
|
1107 | return this._http.authedRequest(callback, "POST", path, null, data);
|
1108 | };
|
1109 |
|
1110 | // Device operations
|
1111 | // =================
|
1112 |
|
1113 | /**
|
1114 | * Gets all devices recorded for the logged-in user
|
1115 | * @return {module:client.Promise} Resolves: result object
|
1116 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1117 | */
|
1118 | MatrixBaseApis.prototype.getDevices = function () {
|
1119 | var path = "/devices";
|
1120 | return this._http.authedRequestWithPrefix(undefined, "GET", path, undefined, undefined, httpApi.PREFIX_UNSTABLE);
|
1121 | };
|
1122 |
|
1123 | /**
|
1124 | * Update the given device
|
1125 | *
|
1126 | * @param {string} device_id device to update
|
1127 | * @param {Object} body body of request
|
1128 | * @return {module:client.Promise} Resolves: result object
|
1129 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1130 | */
|
1131 | MatrixBaseApis.prototype.setDeviceDetails = function (device_id, body) {
|
1132 | var path = utils.encodeUri("/devices/$device_id", {
|
1133 | $device_id: device_id
|
1134 | });
|
1135 |
|
1136 | return this._http.authedRequestWithPrefix(undefined, "PUT", path, undefined, body, httpApi.PREFIX_UNSTABLE);
|
1137 | };
|
1138 |
|
1139 | /**
|
1140 | * Delete the given device
|
1141 | *
|
1142 | * @param {string} device_id device to delete
|
1143 | * @param {object} auth Optional. Auth data to supply for User-Interactive auth.
|
1144 | * @return {module:client.Promise} Resolves: result object
|
1145 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1146 | */
|
1147 | MatrixBaseApis.prototype.deleteDevice = function (device_id, auth) {
|
1148 | var path = utils.encodeUri("/devices/$device_id", {
|
1149 | $device_id: device_id
|
1150 | });
|
1151 |
|
1152 | var body = {};
|
1153 |
|
1154 | if (auth) {
|
1155 | body.auth = auth;
|
1156 | }
|
1157 |
|
1158 | return this._http.authedRequestWithPrefix(undefined, "DELETE", path, undefined, body, httpApi.PREFIX_UNSTABLE);
|
1159 | };
|
1160 |
|
1161 | /**
|
1162 | * Delete multiple device
|
1163 | *
|
1164 | * @param {string[]} devices IDs of the devices to delete
|
1165 | * @param {object} auth Optional. Auth data to supply for User-Interactive auth.
|
1166 | * @return {module:client.Promise} Resolves: result object
|
1167 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1168 | */
|
1169 | MatrixBaseApis.prototype.deleteMultipleDevices = function (devices, auth) {
|
1170 | var body = { devices: devices };
|
1171 |
|
1172 | if (auth) {
|
1173 | body.auth = auth;
|
1174 | }
|
1175 |
|
1176 | return this._http.authedRequestWithPrefix(undefined, "POST", "/delete_devices", undefined, body, httpApi.PREFIX_UNSTABLE);
|
1177 | };
|
1178 |
|
1179 | // Push operations
|
1180 | // ===============
|
1181 |
|
1182 | /**
|
1183 | * Gets all pushers registered for the logged-in user
|
1184 | *
|
1185 | * @param {module:client.callback} callback Optional.
|
1186 | * @return {module:client.Promise} Resolves: Array of objects representing pushers
|
1187 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1188 | */
|
1189 | MatrixBaseApis.prototype.getPushers = function (callback) {
|
1190 | var path = "/pushers";
|
1191 | return this._http.authedRequest(callback, "GET", path, undefined, undefined);
|
1192 | };
|
1193 |
|
1194 | /**
|
1195 | * Adds a new pusher or updates an existing pusher
|
1196 | *
|
1197 | * @param {Object} pusher Object representing a pusher
|
1198 | * @param {module:client.callback} callback Optional.
|
1199 | * @return {module:client.Promise} Resolves: Empty json object on success
|
1200 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1201 | */
|
1202 | MatrixBaseApis.prototype.setPusher = function (pusher, callback) {
|
1203 | var path = "/pushers/set";
|
1204 | return this._http.authedRequest(callback, "POST", path, null, pusher);
|
1205 | };
|
1206 |
|
1207 | /**
|
1208 | * @param {module:client.callback} callback Optional.
|
1209 | * @return {module:client.Promise} Resolves: TODO
|
1210 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1211 | */
|
1212 | MatrixBaseApis.prototype.getPushRules = function (callback) {
|
1213 | return this._http.authedRequest(callback, "GET", "/pushrules/");
|
1214 | };
|
1215 |
|
1216 | /**
|
1217 | * @param {string} scope
|
1218 | * @param {string} kind
|
1219 | * @param {string} ruleId
|
1220 | * @param {Object} body
|
1221 | * @param {module:client.callback} callback Optional.
|
1222 | * @return {module:client.Promise} Resolves: TODO
|
1223 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1224 | */
|
1225 | MatrixBaseApis.prototype.addPushRule = function (scope, kind, ruleId, body, callback) {
|
1226 | // NB. Scope not uri encoded because devices need the '/'
|
1227 | var path = utils.encodeUri("/pushrules/" + scope + "/$kind/$ruleId", {
|
1228 | $kind: kind,
|
1229 | $ruleId: ruleId
|
1230 | });
|
1231 | return this._http.authedRequest(callback, "PUT", path, undefined, body);
|
1232 | };
|
1233 |
|
1234 | /**
|
1235 | * @param {string} scope
|
1236 | * @param {string} kind
|
1237 | * @param {string} ruleId
|
1238 | * @param {module:client.callback} callback Optional.
|
1239 | * @return {module:client.Promise} Resolves: TODO
|
1240 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1241 | */
|
1242 | MatrixBaseApis.prototype.deletePushRule = function (scope, kind, ruleId, callback) {
|
1243 | // NB. Scope not uri encoded because devices need the '/'
|
1244 | var path = utils.encodeUri("/pushrules/" + scope + "/$kind/$ruleId", {
|
1245 | $kind: kind,
|
1246 | $ruleId: ruleId
|
1247 | });
|
1248 | return this._http.authedRequest(callback, "DELETE", path);
|
1249 | };
|
1250 |
|
1251 | /**
|
1252 | * Enable or disable a push notification rule.
|
1253 | * @param {string} scope
|
1254 | * @param {string} kind
|
1255 | * @param {string} ruleId
|
1256 | * @param {boolean} enabled
|
1257 | * @param {module:client.callback} callback Optional.
|
1258 | * @return {module:client.Promise} Resolves: result object
|
1259 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1260 | */
|
1261 | MatrixBaseApis.prototype.setPushRuleEnabled = function (scope, kind, ruleId, enabled, callback) {
|
1262 | var path = utils.encodeUri("/pushrules/" + scope + "/$kind/$ruleId/enabled", {
|
1263 | $kind: kind,
|
1264 | $ruleId: ruleId
|
1265 | });
|
1266 | return this._http.authedRequest(callback, "PUT", path, undefined, { "enabled": enabled });
|
1267 | };
|
1268 |
|
1269 | /**
|
1270 | * Set the actions for a push notification rule.
|
1271 | * @param {string} scope
|
1272 | * @param {string} kind
|
1273 | * @param {string} ruleId
|
1274 | * @param {array} actions
|
1275 | * @param {module:client.callback} callback Optional.
|
1276 | * @return {module:client.Promise} Resolves: result object
|
1277 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1278 | */
|
1279 | MatrixBaseApis.prototype.setPushRuleActions = function (scope, kind, ruleId, actions, callback) {
|
1280 | var path = utils.encodeUri("/pushrules/" + scope + "/$kind/$ruleId/actions", {
|
1281 | $kind: kind,
|
1282 | $ruleId: ruleId
|
1283 | });
|
1284 | return this._http.authedRequest(callback, "PUT", path, undefined, { "actions": actions });
|
1285 | };
|
1286 |
|
1287 | // Search
|
1288 | // ======
|
1289 |
|
1290 | /**
|
1291 | * Perform a server-side search.
|
1292 | * @param {Object} opts
|
1293 | * @param {string} opts.next_batch the batch token to pass in the query string
|
1294 | * @param {Object} opts.body the JSON object to pass to the request body.
|
1295 | * @param {module:client.callback} callback Optional.
|
1296 | * @return {module:client.Promise} Resolves: TODO
|
1297 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1298 | */
|
1299 | MatrixBaseApis.prototype.search = function (opts, callback) {
|
1300 | var queryparams = {};
|
1301 | if (opts.next_batch) {
|
1302 | queryparams.next_batch = opts.next_batch;
|
1303 | }
|
1304 | return this._http.authedRequest(callback, "POST", "/search", queryparams, opts.body);
|
1305 | };
|
1306 |
|
1307 | // Crypto
|
1308 | // ======
|
1309 |
|
1310 | /**
|
1311 | * Upload keys
|
1312 | *
|
1313 | * @param {Object} content body of upload request
|
1314 | *
|
1315 | * @param {Object=} opts
|
1316 | *
|
1317 | * @param {string=} opts.device_id explicit device_id to use for upload
|
1318 | * (default is to use the same as that used during auth).
|
1319 | *
|
1320 | * @param {module:client.callback=} callback
|
1321 | *
|
1322 | * @return {module:client.Promise} Resolves: result object. Rejects: with
|
1323 | * an error response ({@link module:http-api.MatrixError}).
|
1324 | */
|
1325 | MatrixBaseApis.prototype.uploadKeysRequest = function (content, opts, callback) {
|
1326 | opts = opts || {};
|
1327 | var deviceId = opts.device_id;
|
1328 | var path = void 0;
|
1329 | if (deviceId) {
|
1330 | path = utils.encodeUri("/keys/upload/$deviceId", {
|
1331 | $deviceId: deviceId
|
1332 | });
|
1333 | } else {
|
1334 | path = "/keys/upload";
|
1335 | }
|
1336 | return this._http.authedRequestWithPrefix(callback, "POST", path, undefined, content, httpApi.PREFIX_UNSTABLE);
|
1337 | };
|
1338 |
|
1339 | /**
|
1340 | * Download device keys
|
1341 | *
|
1342 | * @param {string[]} userIds list of users to get keys for
|
1343 | *
|
1344 | * @param {Object=} opts
|
1345 | *
|
1346 | * @param {string=} opts.token sync token to pass in the query request, to help
|
1347 | * the HS give the most recent results
|
1348 | *
|
1349 | * @return {module:client.Promise} Resolves: result object. Rejects: with
|
1350 | * an error response ({@link module:http-api.MatrixError}).
|
1351 | */
|
1352 | MatrixBaseApis.prototype.downloadKeysForUsers = function (userIds, opts) {
|
1353 | if (utils.isFunction(opts)) {
|
1354 | // opts used to be 'callback'.
|
1355 | throw new Error('downloadKeysForUsers no longer accepts a callback parameter');
|
1356 | }
|
1357 | opts = opts || {};
|
1358 |
|
1359 | var content = {
|
1360 | device_keys: {}
|
1361 | };
|
1362 | if ('token' in opts) {
|
1363 | content.token = opts.token;
|
1364 | }
|
1365 | userIds.forEach(function (u) {
|
1366 | content.device_keys[u] = {};
|
1367 | });
|
1368 |
|
1369 | return this._http.authedRequestWithPrefix(undefined, "POST", "/keys/query", undefined, content, httpApi.PREFIX_UNSTABLE);
|
1370 | };
|
1371 |
|
1372 | /**
|
1373 | * Claim one-time keys
|
1374 | *
|
1375 | * @param {string[]} devices a list of [userId, deviceId] pairs
|
1376 | *
|
1377 | * @param {string} [key_algorithm = signed_curve25519] desired key type
|
1378 | *
|
1379 | * @return {module:client.Promise} Resolves: result object. Rejects: with
|
1380 | * an error response ({@link module:http-api.MatrixError}).
|
1381 | */
|
1382 | MatrixBaseApis.prototype.claimOneTimeKeys = function (devices, key_algorithm) {
|
1383 | var queries = {};
|
1384 |
|
1385 | if (key_algorithm === undefined) {
|
1386 | key_algorithm = "signed_curve25519";
|
1387 | }
|
1388 |
|
1389 | for (var i = 0; i < devices.length; ++i) {
|
1390 | var userId = devices[i][0];
|
1391 | var deviceId = devices[i][1];
|
1392 | var query = queries[userId] || {};
|
1393 | queries[userId] = query;
|
1394 | query[deviceId] = key_algorithm;
|
1395 | }
|
1396 | var content = { one_time_keys: queries };
|
1397 | return this._http.authedRequestWithPrefix(undefined, "POST", "/keys/claim", undefined, content, httpApi.PREFIX_UNSTABLE);
|
1398 | };
|
1399 |
|
1400 | /**
|
1401 | * Ask the server for a list of users who have changed their device lists
|
1402 | * between a pair of sync tokens
|
1403 | *
|
1404 | * @param {string} oldToken
|
1405 | * @param {string} newToken
|
1406 | *
|
1407 | * @return {module:client.Promise} Resolves: result object. Rejects: with
|
1408 | * an error response ({@link module:http-api.MatrixError}).
|
1409 | */
|
1410 | MatrixBaseApis.prototype.getKeyChanges = function (oldToken, newToken) {
|
1411 | var qps = {
|
1412 | from: oldToken,
|
1413 | to: newToken
|
1414 | };
|
1415 |
|
1416 | return this._http.authedRequestWithPrefix(undefined, "GET", "/keys/changes", qps, undefined, httpApi.PREFIX_UNSTABLE);
|
1417 | };
|
1418 |
|
1419 | // Identity Server Operations
|
1420 | // ==========================
|
1421 |
|
1422 | /**
|
1423 | * Requests an email verification token directly from an Identity Server.
|
1424 | *
|
1425 | * Note that the Home Server offers APIs to proxy this API for specific
|
1426 | * situations, allowing for better feedback to the user.
|
1427 | *
|
1428 | * @param {string} email The email address to request a token for
|
1429 | * @param {string} clientSecret A secret binary string generated by the client.
|
1430 | * It is recommended this be around 16 ASCII characters.
|
1431 | * @param {number} sendAttempt If an identity server sees a duplicate request
|
1432 | * with the same sendAttempt, it will not send another email.
|
1433 | * To request another email to be sent, use a larger value for
|
1434 | * the sendAttempt param as was used in the previous request.
|
1435 | * @param {string} nextLink Optional If specified, the client will be redirected
|
1436 | * to this link after validation.
|
1437 | * @param {module:client.callback} callback Optional.
|
1438 | * @return {module:client.Promise} Resolves: TODO
|
1439 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1440 | * @throws Error if No ID server is set
|
1441 | */
|
1442 | MatrixBaseApis.prototype.requestEmailToken = function (email, clientSecret, sendAttempt, nextLink, callback) {
|
1443 | var params = {
|
1444 | client_secret: clientSecret,
|
1445 | email: email,
|
1446 | send_attempt: sendAttempt,
|
1447 | next_link: nextLink
|
1448 | };
|
1449 | return this._http.idServerRequest(callback, "POST", "/validate/email/requestToken", params, httpApi.PREFIX_IDENTITY_V1);
|
1450 | };
|
1451 |
|
1452 | /**
|
1453 | * Submits an MSISDN token to the identity server
|
1454 | *
|
1455 | * This is used when submitting the code sent by SMS to a phone number.
|
1456 | * The ID server has an equivalent API for email but the js-sdk does
|
1457 | * not expose this, since email is normally validated by the user clicking
|
1458 | * a link rather than entering a code.
|
1459 | *
|
1460 | * @param {string} sid The sid given in the response to requestToken
|
1461 | * @param {string} clientSecret A secret binary string generated by the client.
|
1462 | * This must be the same value submitted in the requestToken call.
|
1463 | * @param {string} token The token, as enetered by the user.
|
1464 | *
|
1465 | * @return {module:client.Promise} Resolves: Object, currently with no parameters.
|
1466 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1467 | * @throws Error if No ID server is set
|
1468 | */
|
1469 | MatrixBaseApis.prototype.submitMsisdnToken = function (sid, clientSecret, token) {
|
1470 | var params = {
|
1471 | sid: sid,
|
1472 | client_secret: clientSecret,
|
1473 | token: token
|
1474 | };
|
1475 | return this._http.idServerRequest(undefined, "POST", "/validate/msisdn/submitToken", params, httpApi.PREFIX_IDENTITY_V1);
|
1476 | };
|
1477 |
|
1478 | /**
|
1479 | * Looks up the public Matrix ID mapping for a given 3rd party
|
1480 | * identifier from the Identity Server
|
1481 | * @param {string} medium The medium of the threepid, eg. 'email'
|
1482 | * @param {string} address The textual address of the threepid
|
1483 | * @param {module:client.callback} callback Optional.
|
1484 | * @return {module:client.Promise} Resolves: A threepid mapping
|
1485 | * object or the empty object if no mapping
|
1486 | * exists
|
1487 | * @return {module:http-api.MatrixError} Rejects: with an error response.
|
1488 | */
|
1489 | MatrixBaseApis.prototype.lookupThreePid = function (medium, address, callback) {
|
1490 | var params = {
|
1491 | medium: medium,
|
1492 | address: address
|
1493 | };
|
1494 | return this._http.idServerRequest(callback, "GET", "/lookup", params, httpApi.PREFIX_IDENTITY_V1);
|
1495 | };
|
1496 |
|
1497 | // Direct-to-device messaging
|
1498 | // ==========================
|
1499 |
|
1500 | /**
|
1501 | * Send an event to a specific list of devices
|
1502 | *
|
1503 | * @param {string} eventType type of event to send
|
1504 | * @param {Object.<string, Object<string, Object>>} contentMap
|
1505 | * content to send. Map from user_id to device_id to content object.
|
1506 | * @param {string=} txnId transaction id. One will be made up if not
|
1507 | * supplied.
|
1508 | * @return {module:client.Promise} Resolves to the result object
|
1509 | */
|
1510 | MatrixBaseApis.prototype.sendToDevice = function (eventType, contentMap, txnId) {
|
1511 | var path = utils.encodeUri("/sendToDevice/$eventType/$txnId", {
|
1512 | $eventType: eventType,
|
1513 | $txnId: txnId ? txnId : this.makeTxnId()
|
1514 | });
|
1515 |
|
1516 | var body = {
|
1517 | messages: contentMap
|
1518 | };
|
1519 |
|
1520 | return this._http.authedRequestWithPrefix(undefined, "PUT", path, undefined, body, httpApi.PREFIX_UNSTABLE);
|
1521 | };
|
1522 |
|
1523 | // Third party Lookup API
|
1524 | // ======================
|
1525 |
|
1526 | /**
|
1527 | * Get the third party protocols that can be reached using
|
1528 | * this HS
|
1529 | * @return {module:client.Promise} Resolves to the result object
|
1530 | */
|
1531 | MatrixBaseApis.prototype.getThirdpartyProtocols = function () {
|
1532 | return this._http.authedRequestWithPrefix(undefined, "GET", "/thirdparty/protocols", undefined, undefined, httpApi.PREFIX_UNSTABLE).then(function (response) {
|
1533 | // sanity check
|
1534 | if (!response || (typeof response === "undefined" ? "undefined" : (0, _typeof3.default)(response)) !== 'object') {
|
1535 | throw new Error("/thirdparty/protocols did not return an object: " + response);
|
1536 | }
|
1537 | return response;
|
1538 | });
|
1539 | };
|
1540 |
|
1541 | /**
|
1542 | * Get information on how a specific place on a third party protocol
|
1543 | * may be reached.
|
1544 | * @param {string} protocol The protocol given in getThirdpartyProtocols()
|
1545 | * @param {object} params Protocol-specific parameters, as given in th
|
1546 | * response to getThirdpartyProtocols()
|
1547 | * @return {module:client.Promise} Resolves to the result object
|
1548 | */
|
1549 | MatrixBaseApis.prototype.getThirdpartyLocation = function (protocol, params) {
|
1550 | var path = utils.encodeUri("/thirdparty/location/$protocol", {
|
1551 | $protocol: protocol
|
1552 | });
|
1553 |
|
1554 | return this._http.authedRequestWithPrefix(undefined, "GET", path, params, undefined, httpApi.PREFIX_UNSTABLE);
|
1555 | };
|
1556 |
|
1557 | /**
|
1558 | * MatrixBaseApis object
|
1559 | */
|
1560 | module.exports = MatrixBaseApis;
|
1561 | //# sourceMappingURL=base-apis.js.map |
\ | No newline at end of file |