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 Gets a list of a user's third-party identifiers.
17 *
18 * Gets a list of the third-party identifiers that the homeserver has
19 * associated with the user's account.
20 *
21 * This is *not* the same as the list of third-party identifiers bound to
22 * the user's Matrix ID in identity servers.
23 *
24 * Identifiers in this list may be used by the homeserver as, for example,
25 * identifiers that it will accept to reset the user's account password.
26 */
27class QUOTIENT_API GetAccount3PIDsJob : public BaseJob {
28public:
29 // Inner data structures
30
31 /// Gets a list of the third-party identifiers that the homeserver has
32 /// associated with the user's account.
33 ///
34 /// This is *not* the same as the list of third-party identifiers bound to
35 /// the user's Matrix ID in identity servers.
36 ///
37 /// Identifiers in this list may be used by the homeserver as, for example,
38 /// identifiers that it will accept to reset the user's account password.
39 struct ThirdPartyIdentifier {
40 /// The medium of the third-party identifier.
41 QString medium;
42 /// The third-party identifier address.
43 QString address;
44 /// The timestamp, in milliseconds, when the identifier was
45 /// validated by the identity server.
46 qint64 validatedAt;
47 /// The timestamp, in milliseconds, when the homeserver associated the
48 /// third-party identifier with the user.
49 qint64 addedAt;
50 };
51
52 // Construction/destruction
53
54 /// Gets a list of a user's third-party identifiers.
55 explicit GetAccount3PIDsJob();
56
57 /*! \brief Construct a URL without creating a full-fledged job object
58 *
59 * This function can be used when a URL for GetAccount3PIDsJob
60 * is necessary but the job itself isn't.
61 */
62 static QUrl makeRequestUrl(QUrl baseUrl);
63
64 // Result properties
65
66 /// Gets a list of the third-party identifiers that the homeserver has
67 /// associated with the user's account.
68 ///
69 /// This is *not* the same as the list of third-party identifiers bound to
70 /// the user's Matrix ID in identity servers.
71 ///
72 /// Identifiers in this list may be used by the homeserver as, for example,
73 /// identifiers that it will accept to reset the user's account password.
74 QVector<ThirdPartyIdentifier> threepids() const
75 {
76 return loadFromJson<QVector<ThirdPartyIdentifier>>(keyName: "threepids"_ls);
77 }
78};
79
80template <>
81struct JsonObjectConverter<GetAccount3PIDsJob::ThirdPartyIdentifier> {
82 static void fillFrom(const QJsonObject& jo,
83 GetAccount3PIDsJob::ThirdPartyIdentifier& result)
84 {
85 fillFromJson(jv: jo.value(key: "medium"_ls), pod&: result.medium);
86 fillFromJson(jv: jo.value(key: "address"_ls), pod&: result.address);
87 fillFromJson(jv: jo.value(key: "validated_at"_ls), pod&: result.validatedAt);
88 fillFromJson(jv: jo.value(key: "added_at"_ls), pod&: result.addedAt);
89 }
90};
91
92/*! \brief Adds contact information to the user's account.
93 *
94 * Adds contact information to the user's account.
95 *
96 * This endpoint is deprecated in favour of the more specific `/3pid/add`
97 * and `/3pid/bind` endpoints.
98 *
99 * **Note:**
100 * Previously this endpoint supported a `bind` parameter. This parameter
101 * has been removed, making this endpoint behave as though it was `false`.
102 * This results in this endpoint being an equivalent to `/3pid/bind` rather
103 * than dual-purpose.
104 */
105class QUOTIENT_API Post3PIDsJob : public BaseJob {
106public:
107 // Inner data structures
108
109 /// The third-party credentials to associate with the account.
110 struct ThreePidCredentials {
111 /// The client secret used in the session with the identity server.
112 QString clientSecret;
113 /// The identity server to use.
114 QString idServer;
115 /// An access token previously registered with the identity server.
116 /// Servers can treat this as optional to distinguish between
117 /// r0.5-compatible clients and this specification version.
118 QString idAccessToken;
119 /// The session identifier given by the identity server.
120 QString sid;
121 };
122
123 // Construction/destruction
124
125 /*! \brief Adds contact information to the user's account.
126 *
127 * \param threePidCreds
128 * The third-party credentials to associate with the account.
129 */
130 explicit Post3PIDsJob(const ThreePidCredentials& threePidCreds);
131
132 // Result properties
133
134 /// An optional field containing a URL where the client must
135 /// submit the validation token to, with identical parameters
136 /// to the Identity Service API's `POST
137 /// /validate/email/submitToken` endpoint (without the requirement
138 /// for an access token). The homeserver must send this token to the
139 /// user (if applicable), who should then be prompted to provide it
140 /// to the client.
141 ///
142 /// If this field is not present, the client can assume that
143 /// verification will happen without the client's involvement
144 /// provided the homeserver advertises this specification version
145 /// in the `/versions` response (ie: r0.5.0).
146 QUrl submitUrl() const { return loadFromJson<QUrl>(keyName: "submit_url"_ls); }
147};
148
149template <>
150struct JsonObjectConverter<Post3PIDsJob::ThreePidCredentials> {
151 static void dumpTo(QJsonObject& jo,
152 const Post3PIDsJob::ThreePidCredentials& pod)
153 {
154 addParam<>(container&: jo, QStringLiteral("client_secret"), value: pod.clientSecret);
155 addParam<>(container&: jo, QStringLiteral("id_server"), value: pod.idServer);
156 addParam<>(container&: jo, QStringLiteral("id_access_token"), value: pod.idAccessToken);
157 addParam<>(container&: jo, QStringLiteral("sid"), value: pod.sid);
158 }
159};
160
161/*! \brief Adds contact information to the user's account.
162 *
163 * This API endpoint uses the [User-Interactive Authentication
164 * API](/client-server-api/#user-interactive-authentication-api).
165 *
166 * Adds contact information to the user's account. Homeservers should use 3PIDs
167 * added through this endpoint for password resets instead of relying on the
168 * identity server.
169 *
170 * Homeservers should prevent the caller from adding a 3PID to their account if
171 * it has already been added to another user's account on the homeserver.
172 */
173class QUOTIENT_API Add3PIDJob : public BaseJob {
174public:
175 /*! \brief Adds contact information to the user's account.
176 *
177 * \param clientSecret
178 * The client secret used in the session with the homeserver.
179 *
180 * \param sid
181 * The session identifier given by the homeserver.
182 *
183 * \param auth
184 * Additional authentication information for the
185 * user-interactive authentication API.
186 */
187 explicit Add3PIDJob(const QString& clientSecret, const QString& sid,
188 const Omittable<AuthenticationData>& auth = none);
189};
190
191/*! \brief Binds a 3PID to the user's account through an Identity Service.
192 *
193 * Binds a 3PID to the user's account through the specified identity server.
194 *
195 * Homeservers should not prevent this request from succeeding if another user
196 * has bound the 3PID. Homeservers should simply proxy any errors received by
197 * the identity server to the caller.
198 *
199 * Homeservers should track successful binds so they can be unbound later.
200 */
201class QUOTIENT_API Bind3PIDJob : public BaseJob {
202public:
203 /*! \brief Binds a 3PID to the user's account through an Identity Service.
204 *
205 * \param clientSecret
206 * The client secret used in the session with the identity server.
207 *
208 * \param idServer
209 * The identity server to use.
210 *
211 * \param idAccessToken
212 * An access token previously registered with the identity server.
213 *
214 * \param sid
215 * The session identifier given by the identity server.
216 */
217 explicit Bind3PIDJob(const QString& clientSecret, const QString& idServer,
218 const QString& idAccessToken, const QString& sid);
219};
220
221/*! \brief Deletes a third-party identifier from the user's account
222 *
223 * Removes a third-party identifier from the user's account. This might not
224 * cause an unbind of the identifier from the identity server.
225 *
226 * Unlike other endpoints, this endpoint does not take an `id_access_token`
227 * parameter because the homeserver is expected to sign the request to the
228 * identity server instead.
229 */
230class QUOTIENT_API Delete3pidFromAccountJob : public BaseJob {
231public:
232 /*! \brief Deletes a third-party identifier from the user's account
233 *
234 * \param medium
235 * The medium of the third-party identifier being removed.
236 *
237 * \param address
238 * The third-party address being removed.
239 *
240 * \param idServer
241 * The identity server to unbind from. If not provided, the homeserver
242 * MUST use the `id_server` the identifier was added through. If the
243 * homeserver does not know the original `id_server`, it MUST return
244 * a `id_server_unbind_result` of `no-support`.
245 */
246 explicit Delete3pidFromAccountJob(const QString& medium,
247 const QString& address,
248 const QString& idServer = {});
249
250 // Result properties
251
252 /// An indicator as to whether or not the homeserver was able to unbind
253 /// the 3PID from the identity server. `success` indicates that the
254 /// identity server has unbound the identifier whereas `no-support`
255 /// indicates that the identity server refuses to support the request
256 /// or the homeserver was not able to determine an identity server to
257 /// unbind from.
258 QString idServerUnbindResult() const
259 {
260 return loadFromJson<QString>(keyName: "id_server_unbind_result"_ls);
261 }
262};
263
264/*! \brief Removes a user's third-party identifier from an identity server.
265 *
266 * Removes a user's third-party identifier from the provided identity server
267 * without removing it from the homeserver.
268 *
269 * Unlike other endpoints, this endpoint does not take an `id_access_token`
270 * parameter because the homeserver is expected to sign the request to the
271 * identity server instead.
272 */
273class QUOTIENT_API Unbind3pidFromAccountJob : public BaseJob {
274public:
275 /*! \brief Removes a user's third-party identifier from an identity server.
276 *
277 * \param medium
278 * The medium of the third-party identifier being removed.
279 *
280 * \param address
281 * The third-party address being removed.
282 *
283 * \param idServer
284 * The identity server to unbind from. If not provided, the homeserver
285 * MUST use the `id_server` the identifier was added through. If the
286 * homeserver does not know the original `id_server`, it MUST return
287 * a `id_server_unbind_result` of `no-support`.
288 */
289 explicit Unbind3pidFromAccountJob(const QString& medium,
290 const QString& address,
291 const QString& idServer = {});
292
293 // Result properties
294
295 /// An indicator as to whether or not the identity server was able to unbind
296 /// the 3PID. `success` indicates that the identity server has unbound the
297 /// identifier whereas `no-support` indicates that the identity server
298 /// refuses to support the request or the homeserver was not able to
299 /// determine an identity server to unbind from.
300 QString idServerUnbindResult() const
301 {
302 return loadFromJson<QString>(keyName: "id_server_unbind_result"_ls);
303 }
304};
305
306/*! \brief Begins the validation process for an email address for association
307 * with the user's account.
308 *
309 * The homeserver must check that the given email address is **not**
310 * already associated with an account on this homeserver. This API should
311 * be used to request validation tokens when adding an email address to an
312 * account. This API's parameters and response are identical to that of
313 * the
314 * [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
315 * endpoint. The homeserver should validate
316 * the email itself, either by sending a validation email itself or by using
317 * a service it has control over.
318 */
319class QUOTIENT_API RequestTokenTo3PIDEmailJob : public BaseJob {
320public:
321 /*! \brief Begins the validation process for an email address for
322 * association with the user's account.
323 *
324 * \param body
325 * The homeserver must check that the given email address is **not**
326 * already associated with an account on this homeserver. This API should
327 * be used to request validation tokens when adding an email address to an
328 * account. This API's parameters and response are identical to that of
329 * the
330 * [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
331 * endpoint. The homeserver should validate
332 * the email itself, either by sending a validation email itself or by
333 * using a service it has control over.
334 */
335 explicit RequestTokenTo3PIDEmailJob(const EmailValidationData& body);
336
337 // Result properties
338
339 /// An email was sent to the given address. Note that this may be an
340 /// email containing the validation token or it may be informing the
341 /// user of an error.
342 RequestTokenResponse response() const
343 {
344 return fromJson<RequestTokenResponse>(json: jsonData());
345 }
346};
347
348/*! \brief Begins the validation process for a phone number for association with
349 * the user's account.
350 *
351 * The homeserver must check that the given phone number is **not**
352 * already associated with an account on this homeserver. This API should
353 * be used to request validation tokens when adding a phone number to an
354 * account. This API's parameters and response are identical to that of
355 * the
356 * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
357 * endpoint. The homeserver should validate
358 * the phone number itself, either by sending a validation message itself or by
359 * using a service it has control over.
360 */
361class QUOTIENT_API RequestTokenTo3PIDMSISDNJob : public BaseJob {
362public:
363 /*! \brief Begins the validation process for a phone number for association
364 * with the user's account.
365 *
366 * \param body
367 * The homeserver must check that the given phone number is **not**
368 * already associated with an account on this homeserver. This API should
369 * be used to request validation tokens when adding a phone number to an
370 * account. This API's parameters and response are identical to that of
371 * the
372 * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
373 * endpoint. The homeserver should validate
374 * the phone number itself, either by sending a validation message itself
375 * or by using a service it has control over.
376 */
377 explicit RequestTokenTo3PIDMSISDNJob(const MsisdnValidationData& body);
378
379 // Result properties
380
381 /// An SMS message was sent to the given phone number.
382 RequestTokenResponse response() const
383 {
384 return fromJson<RequestTokenResponse>(json: jsonData());
385 }
386};
387
388} // namespace Quotient
389