1/******************************************************************************
2 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
3 */
4
5#pragma once
6
7#include <Quotient/csapi/definitions/auth_data.h>
8#include <Quotient/csapi/definitions/request_email_validation.h>
9#include <Quotient/csapi/definitions/request_msisdn_validation.h>
10#include <Quotient/csapi/definitions/request_token_response.h>
11
12#include <Quotient/jobs/basejob.h>
13
14namespace Quotient {
15
16/*! \brief Register for an account on this homeserver.
17 *
18 * This API endpoint uses the [User-Interactive Authentication
19 * API](/client-server-api/#user-interactive-authentication-api), except in the
20 * cases where a guest account is being registered.
21 *
22 * Register for an account on this homeserver.
23 *
24 * There are two kinds of user account:
25 *
26 * - `user` accounts. These accounts may use the full API described in this
27 * specification.
28 *
29 * - `guest` accounts. These accounts may have limited permissions and may not
30 * be supported by all servers.
31 *
32 * If registration is successful, this endpoint will issue an access token
33 * the client can use to authorize itself in subsequent requests.
34 *
35 * If the client does not supply a `device_id`, the server must
36 * auto-generate one.
37 *
38 * The server SHOULD register an account with a User ID based on the
39 * `username` provided, if any. Note that the grammar of Matrix User ID
40 * localparts is restricted, so the server MUST either map the provided
41 * `username` onto a `user_id` in a logical manner, or reject any
42 * `username` which does not comply to the grammar with
43 * `M_INVALID_USERNAME`.
44 *
45 * Matrix clients MUST NOT assume that localpart of the registered
46 * `user_id` matches the provided `username`.
47 *
48 * The returned access token must be associated with the `device_id`
49 * supplied by the client or generated by the server. The server may
50 * invalidate any access token previously associated with that device. See
51 * [Relationship between access tokens and
52 * devices](/client-server-api/#relationship-between-access-tokens-and-devices).
53 *
54 * When registering a guest account, all parameters in the request body
55 * with the exception of `initial_device_display_name` MUST BE ignored
56 * by the server. The server MUST pick a `device_id` for the account
57 * regardless of input.
58 *
59 * Any user ID returned by this API must conform to the grammar given in the
60 * [Matrix specification](/appendices/#user-identifiers).
61 */
62class QUOTIENT_API RegisterJob : public BaseJob {
63public:
64 /*! \brief Register for an account on this homeserver.
65 *
66 * \param kind
67 * The kind of account to register. Defaults to `user`.
68 *
69 * \param auth
70 * Additional authentication information for the
71 * user-interactive authentication API. Note that this
72 * information is *not* used to define how the registered user
73 * should be authenticated, but is instead used to
74 * authenticate the `register` call itself.
75 *
76 * \param username
77 * The basis for the localpart of the desired Matrix ID. If omitted,
78 * the homeserver MUST generate a Matrix ID local part.
79 *
80 * \param password
81 * The desired password for the account.
82 *
83 * \param deviceId
84 * ID of the client device. If this does not correspond to a
85 * known client device, a new device will be created. The server
86 * will auto-generate a device_id if this is not specified.
87 *
88 * \param initialDeviceDisplayName
89 * A display name to assign to the newly-created device. Ignored
90 * if `device_id` corresponds to a known device.
91 *
92 * \param inhibitLogin
93 * If true, an `access_token` and `device_id` should not be
94 * returned from this call, therefore preventing an automatic
95 * login. Defaults to false.
96 *
97 * \param refreshToken
98 * If true, the client supports refresh tokens.
99 */
100 explicit RegisterJob(const QString& kind = QStringLiteral("user"),
101 const Omittable<AuthenticationData>& auth = none,
102 const QString& username = {},
103 const QString& password = {},
104 const QString& deviceId = {},
105 const QString& initialDeviceDisplayName = {},
106 Omittable<bool> inhibitLogin = none,
107 Omittable<bool> refreshToken = none);
108
109 // Result properties
110
111 /// The fully-qualified Matrix user ID (MXID) that has been registered.
112 ///
113 /// Any user ID returned by this API must conform to the grammar given in
114 /// the [Matrix specification](/appendices/#user-identifiers).
115 QString userId() const { return loadFromJson<QString>(keyName: "user_id"_ls); }
116
117 /// An access token for the account.
118 /// This access token can then be used to authorize other requests.
119 /// Required if the `inhibit_login` option is false.
120 QString accessToken() const
121 {
122 return loadFromJson<QString>(keyName: "access_token"_ls);
123 }
124
125 /// A refresh token for the account. This token can be used to
126 /// obtain a new access token when it expires by calling the
127 /// `/refresh` endpoint.
128 ///
129 /// Omitted if the `inhibit_login` option is true.
130 QString refreshToken() const
131 {
132 return loadFromJson<QString>(keyName: "refresh_token"_ls);
133 }
134
135 /// The lifetime of the access token, in milliseconds. Once
136 /// the access token has expired a new access token can be
137 /// obtained by using the provided refresh token. If no
138 /// refresh token is provided, the client will need to re-log in
139 /// to obtain a new access token. If not given, the client can
140 /// assume that the access token will not expire.
141 ///
142 /// Omitted if the `inhibit_login` option is true.
143 Omittable<int> expiresInMs() const
144 {
145 return loadFromJson<Omittable<int>>(keyName: "expires_in_ms"_ls);
146 }
147
148 /// ID of the registered device. Will be the same as the
149 /// corresponding parameter in the request, if one was specified.
150 /// Required if the `inhibit_login` option is false.
151 QString deviceId() const { return loadFromJson<QString>(keyName: "device_id"_ls); }
152};
153
154/*! \brief Begins the validation process for an email to be used during
155 * registration.
156 *
157 * The homeserver must check that the given email address is **not**
158 * already associated with an account on this homeserver. The homeserver
159 * should validate the email itself, either by sending a validation email
160 * itself or by using a service it has control over.
161 */
162class QUOTIENT_API RequestTokenToRegisterEmailJob : public BaseJob {
163public:
164 /*! \brief Begins the validation process for an email to be used during
165 * registration.
166 *
167 * \param body
168 * The homeserver must check that the given email address is **not**
169 * already associated with an account on this homeserver. The homeserver
170 * should validate the email itself, either by sending a validation email
171 * itself or by using a service it has control over.
172 */
173 explicit RequestTokenToRegisterEmailJob(const EmailValidationData& body);
174
175 // Result properties
176
177 /// An email has been sent to the specified address. Note that this
178 /// may be an email containing the validation token or it may be
179 /// informing the user of an error.
180 RequestTokenResponse response() const
181 {
182 return fromJson<RequestTokenResponse>(json: jsonData());
183 }
184};
185
186/*! \brief Requests a validation token be sent to the given phone number for the
187 * purpose of registering an account
188 *
189 * The homeserver must check that the given phone number is **not**
190 * already associated with an account on this homeserver. The homeserver
191 * should validate the phone number itself, either by sending a validation
192 * message itself or by using a service it has control over.
193 */
194class QUOTIENT_API RequestTokenToRegisterMSISDNJob : public BaseJob {
195public:
196 /*! \brief Requests a validation token be sent to the given phone number for
197 * the purpose of registering an account
198 *
199 * \param body
200 * The homeserver must check that the given phone number is **not**
201 * already associated with an account on this homeserver. The homeserver
202 * should validate the phone number itself, either by sending a validation
203 * message itself or by using a service it has control over.
204 */
205 explicit RequestTokenToRegisterMSISDNJob(const MsisdnValidationData& body);
206
207 // Result properties
208
209 /// An SMS message has been sent to the specified phone number. Note
210 /// that this may be an SMS message containing the validation token or
211 /// it may be informing the user of an error.
212 RequestTokenResponse response() const
213 {
214 return fromJson<RequestTokenResponse>(json: jsonData());
215 }
216};
217
218/*! \brief Changes a user's password.
219 *
220 * Changes the password for an account on this homeserver.
221 *
222 * This API endpoint uses the [User-Interactive Authentication
223 * API](/client-server-api/#user-interactive-authentication-api) to ensure the
224 * user changing the password is actually the owner of the account.
225 *
226 * An access token should be submitted to this endpoint if the client has
227 * an active session.
228 *
229 * The homeserver may change the flows available depending on whether a
230 * valid access token is provided. The homeserver SHOULD NOT revoke the
231 * access token provided in the request. Whether other access tokens for
232 * the user are revoked depends on the request parameters.
233 */
234class QUOTIENT_API ChangePasswordJob : public BaseJob {
235public:
236 /*! \brief Changes a user's password.
237 *
238 * \param newPassword
239 * The new password for the account.
240 *
241 * \param logoutDevices
242 * Whether the user's other access tokens, and their associated devices,
243 * should be revoked if the request succeeds.
244 *
245 * When `false`, the server can still take advantage of the [soft logout
246 * method](/client-server-api/#soft-logout) for the user's remaining
247 * devices.
248 *
249 * \param auth
250 * Additional authentication information for the user-interactive
251 * authentication API.
252 */
253 explicit ChangePasswordJob(const QString& newPassword,
254 bool logoutDevices = true,
255 const Omittable<AuthenticationData>& auth = none);
256};
257
258/*! \brief Requests a validation token be sent to the given email address for
259 * the purpose of resetting a user's password
260 *
261 * The homeserver must check that the given email address **is
262 * associated** with an account on this homeserver. This API should be
263 * used to request validation tokens when authenticating for the
264 * `/account/password` endpoint.
265 *
266 * This API's parameters and response are identical to that of the
267 * [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
268 * endpoint, except that
269 * `M_THREEPID_NOT_FOUND` may be returned if no account matching the
270 * given email address could be found. The server may instead send an
271 * email to the given address prompting the user to create an account.
272 * `M_THREEPID_IN_USE` may not be returned.
273 *
274 * The homeserver should validate the email itself, either by sending a
275 * validation email itself or by using a service it has control over.
276 */
277class QUOTIENT_API RequestTokenToResetPasswordEmailJob : public BaseJob {
278public:
279 /*! \brief Requests a validation token be sent to the given email address
280 * for the purpose of resetting a user's password
281 *
282 * \param body
283 * The homeserver must check that the given email address **is
284 * associated** with an account on this homeserver. This API should be
285 * used to request validation tokens when authenticating for the
286 * `/account/password` endpoint.
287 *
288 * This API's parameters and response are identical to that of the
289 * [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
290 * endpoint, except that
291 * `M_THREEPID_NOT_FOUND` may be returned if no account matching the
292 * given email address could be found. The server may instead send an
293 * email to the given address prompting the user to create an account.
294 * `M_THREEPID_IN_USE` may not be returned.
295 *
296 * The homeserver should validate the email itself, either by sending a
297 * validation email itself or by using a service it has control over.
298 */
299 explicit RequestTokenToResetPasswordEmailJob(const EmailValidationData& body);
300
301 // Result properties
302
303 /// An email was sent to the given address.
304 RequestTokenResponse response() const
305 {
306 return fromJson<RequestTokenResponse>(json: jsonData());
307 }
308};
309
310/*! \brief Requests a validation token be sent to the given phone number for the
311 * purpose of resetting a user's password.
312 *
313 * The homeserver must check that the given phone number **is
314 * associated** with an account on this homeserver. This API should be
315 * used to request validation tokens when authenticating for the
316 * `/account/password` endpoint.
317 *
318 * This API's parameters and response are identical to that of the
319 * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
320 * endpoint, except that
321 * `M_THREEPID_NOT_FOUND` may be returned if no account matching the
322 * given phone number could be found. The server may instead send the SMS
323 * to the given phone number prompting the user to create an account.
324 * `M_THREEPID_IN_USE` may not be returned.
325 *
326 * The homeserver should validate the phone number itself, either by sending a
327 * validation message itself or by using a service it has control over.
328 */
329class QUOTIENT_API RequestTokenToResetPasswordMSISDNJob : public BaseJob {
330public:
331 /*! \brief Requests a validation token be sent to the given phone number for
332 * the purpose of resetting a user's password.
333 *
334 * \param body
335 * The homeserver must check that the given phone number **is
336 * associated** with an account on this homeserver. This API should be
337 * used to request validation tokens when authenticating for the
338 * `/account/password` endpoint.
339 *
340 * This API's parameters and response are identical to that of the
341 * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
342 * endpoint, except that
343 * `M_THREEPID_NOT_FOUND` may be returned if no account matching the
344 * given phone number could be found. The server may instead send the SMS
345 * to the given phone number prompting the user to create an account.
346 * `M_THREEPID_IN_USE` may not be returned.
347 *
348 * The homeserver should validate the phone number itself, either by
349 * sending a validation message itself or by using a service it has control
350 * over.
351 */
352 explicit RequestTokenToResetPasswordMSISDNJob(
353 const MsisdnValidationData& body);
354
355 // Result properties
356
357 /// An SMS message was sent to the given phone number.
358 RequestTokenResponse response() const
359 {
360 return fromJson<RequestTokenResponse>(json: jsonData());
361 }
362};
363
364/*! \brief Deactivate a user's account.
365 *
366 * Deactivate the user's account, removing all ability for the user to
367 * login again.
368 *
369 * This API endpoint uses the [User-Interactive Authentication
370 * API](/client-server-api/#user-interactive-authentication-api).
371 *
372 * An access token should be submitted to this endpoint if the client has
373 * an active session.
374 *
375 * The homeserver may change the flows available depending on whether a
376 * valid access token is provided.
377 *
378 * Unlike other endpoints, this endpoint does not take an `id_access_token`
379 * parameter because the homeserver is expected to sign the request to the
380 * identity server instead.
381 */
382class QUOTIENT_API DeactivateAccountJob : public BaseJob {
383public:
384 /*! \brief Deactivate a user's account.
385 *
386 * \param auth
387 * Additional authentication information for the user-interactive
388 * authentication API.
389 *
390 * \param idServer
391 * The identity server to unbind all of the user's 3PIDs from.
392 * If not provided, the homeserver MUST use the `id_server`
393 * that was originally use to bind each identifier. If the
394 * homeserver does not know which `id_server` that was,
395 * it must return an `id_server_unbind_result` of
396 * `no-support`.
397 */
398 explicit DeactivateAccountJob(
399 const Omittable<AuthenticationData>& auth = none,
400 const QString& idServer = {});
401
402 // Result properties
403
404 /// An indicator as to whether or not the homeserver was able to unbind
405 /// the user's 3PIDs from the identity server(s). `success` indicates
406 /// that all identifiers have been unbound from the identity server while
407 /// `no-support` indicates that one or more identifiers failed to unbind
408 /// due to the identity server refusing the request or the homeserver
409 /// being unable to determine an identity server to unbind from. This
410 /// must be `success` if the homeserver has no identifiers to unbind
411 /// for the user.
412 QString idServerUnbindResult() const
413 {
414 return loadFromJson<QString>(keyName: "id_server_unbind_result"_ls);
415 }
416};
417
418/*! \brief Checks to see if a username is available on the server.
419 *
420 * Checks to see if a username is available, and valid, for the server.
421 *
422 * The server should check to ensure that, at the time of the request, the
423 * username requested is available for use. This includes verifying that an
424 * application service has not claimed the username and that the username
425 * fits the server's desired requirements (for example, a server could dictate
426 * that it does not permit usernames with underscores).
427 *
428 * Matrix clients may wish to use this API prior to attempting registration,
429 * however the clients must also be aware that using this API does not normally
430 * reserve the username. This can mean that the username becomes unavailable
431 * between checking its availability and attempting to register it.
432 */
433class QUOTIENT_API CheckUsernameAvailabilityJob : public BaseJob {
434public:
435 /*! \brief Checks to see if a username is available on the server.
436 *
437 * \param username
438 * The username to check the availability of.
439 */
440 explicit CheckUsernameAvailabilityJob(const QString& username);
441
442 /*! \brief Construct a URL without creating a full-fledged job object
443 *
444 * This function can be used when a URL for CheckUsernameAvailabilityJob
445 * is necessary but the job itself isn't.
446 */
447 static QUrl makeRequestUrl(QUrl baseUrl, const QString& username);
448
449 // Result properties
450
451 /// A flag to indicate that the username is available. This should always
452 /// be `true` when the server replies with 200 OK.
453 Omittable<bool> available() const
454 {
455 return loadFromJson<Omittable<bool>>(keyName: "available"_ls);
456 }
457};
458
459} // namespace Quotient
460