Merge pull request #405 from quotient-im/kitsune-basejob-store-json-response

Store JSON response in BaseJob + tweaks to the generated code

1 files changed, 222 insertions, 110 deletions

diff --git a/lib/csapi/administrative_contact.h b/lib/csapi/administrative_contact.h
index af98fe9c..53c89272 100644
--- a/lib/csapi/administrative_contact.h
+++ b/lib/csapi/administrative_contact.h
@@ -4,18 +4,15 @@
 
 #pragma once
 
-#include "converters.h"
-
-#include "csapi/../identity/definitions/sid.h"
+#include "csapi/./definitions/request_email_validation.h"
+#include "csapi/./definitions/request_msisdn_validation.h"
+#include "csapi/definitions/auth_data.h"
+#include "csapi/definitions/request_token_response.h"
 
 #include "jobs/basejob.h"
 
-#include <QtCore/QVector>
-
 namespace Quotient {
 
-// Operations
-
 /*! \brief Gets a list of a user's third party identifiers.
  *
  * Gets a list of the third party identifiers that the homeserver has
@@ -63,7 +60,6 @@ public:
      * is necessary but the job itself isn't.
      */
     static QUrl makeRequestUrl(QUrl baseUrl);
-    ~GetAccount3PIDsJob() override;
 
     // Result properties
 
@@ -75,19 +71,36 @@ public:
     ///
     /// Identifiers in this list may be used by the homeserver as, for example,
     /// identifiers that it will accept to reset the user's account password.
-    const QVector<ThirdPartyIdentifier>& threepids() const;
-
-protected:
-    Status parseJson(const QJsonDocument& data) override;
+    QVector<ThirdPartyIdentifier> threepids() const
+    {
+        return loadFromJson<QVector<ThirdPartyIdentifier>>("threepids"_ls);
+    }
+};
 
-private:
-    class Private;
-    QScopedPointer<Private> d;
+template <>
+struct JsonObjectConverter<GetAccount3PIDsJob::ThirdPartyIdentifier> {
+    static void fillFrom(const QJsonObject& jo,
+                         GetAccount3PIDsJob::ThirdPartyIdentifier& result)
+    {
+        fromJson(jo.value("medium"_ls), result.medium);
+        fromJson(jo.value("address"_ls), result.address);
+        fromJson(jo.value("validated_at"_ls), result.validatedAt);
+        fromJson(jo.value("added_at"_ls), result.addedAt);
+    }
 };
 
 /*! \brief Adds contact information to the user's account.
  *
  * Adds contact information to the user's account.
+ *
+ * This endpoint is deprecated in favour of the more specific ``/3pid/add``
+ * and ``/3pid/bind`` endpoints.
+ *
+ * .. Note::
+ *    Previously this endpoint supported a ``bind`` parameter. This parameter
+ *    has been removed, making this endpoint behave as though it was ``false``.
+ *    This results in this endpoint being an equivalent to ``/3pid/bind`` rather
+ *    than dual-purpose.
  */
 class Post3PIDsJob : public BaseJob {
 public:
@@ -99,6 +112,10 @@ public:
         QString clientSecret;
         /// The identity server to use.
         QString idServer;
+        /// An access token previously registered with the identity server.
+        /// Servers can treat this as optional to distinguish between
+        /// r0.5-compatible clients and this specification version.
+        QString idAccessToken;
         /// The session identifier given by the identity server.
         QString sid;
     };
@@ -107,152 +124,247 @@ public:
 
     /*! \brief Adds contact information to the user's account.
      *
+     *
      * \param threePidCreds
      *   The third party credentials to associate with the account.
-     * \param bind
-     *   Whether the homeserver should also bind this third party
-     *   identifier to the account's Matrix ID with the passed identity
-     *   server. Default: ``false``.
      */
-    explicit Post3PIDsJob(const ThreePidCredentials& threePidCreds,
-                          Omittable<bool> bind = none);
+    explicit Post3PIDsJob(const ThreePidCredentials& threePidCreds);
+};
+
+template <>
+struct JsonObjectConverter<Post3PIDsJob::ThreePidCredentials> {
+    static void dumpTo(QJsonObject& jo,
+                       const Post3PIDsJob::ThreePidCredentials& pod)
+    {
+        addParam<>(jo, QStringLiteral("client_secret"), pod.clientSecret);
+        addParam<>(jo, QStringLiteral("id_server"), pod.idServer);
+        addParam<>(jo, QStringLiteral("id_access_token"), pod.idAccessToken);
+        addParam<>(jo, QStringLiteral("sid"), pod.sid);
+    }
+};
+
+/*! \brief Adds contact information to the user's account.
+ *
+ * This API endpoint uses the `User-Interactive Authentication API`_.
+ *
+ * Adds contact information to the user's account. Homeservers should use 3PIDs
+ * added through this endpoint for password resets instead of relying on the
+ * identity server.
+ *
+ * Homeservers should prevent the caller from adding a 3PID to their account if
+ * it has already been added to another user's account on the homeserver.
+ */
+class Add3PIDJob : public BaseJob {
+public:
+    /*! \brief Adds contact information to the user's account.
+     *
+     *
+     * \param clientSecret
+     *   The client secret used in the session with the homeserver.
+     *
+     * \param sid
+     *   The session identifier given by the homeserver.
+     *
+     * \param auth
+     *   Additional authentication information for the
+     *   user-interactive authentication API.
+     */
+    explicit Add3PIDJob(const QString& clientSecret, const QString& sid,
+                        const Omittable<AuthenticationData>& auth = none);
+};
+
+/*! \brief Binds a 3PID to the user's account through an Identity Service.
+ *
+ * Binds a 3PID to the user's account through the specified identity server.
+ *
+ * Homeservers should not prevent this request from succeeding if another user
+ * has bound the 3PID. Homeservers should simply proxy any errors received by
+ * the identity server to the caller.
+ *
+ * Homeservers should track successful binds so they can be unbound later.
+ */
+class Bind3PIDJob : public BaseJob {
+public:
+    /*! \brief Binds a 3PID to the user's account through an Identity Service.
+     *
+     *
+     * \param clientSecret
+     *   The client secret used in the session with the identity server.
+     *
+     * \param idServer
+     *   The identity server to use.
+     *
+     * \param idAccessToken
+     *   An access token previously registered with the identity server.
+     *
+     * \param sid
+     *   The session identifier given by the identity server.
+     */
+    explicit Bind3PIDJob(const QString& clientSecret, const QString& idServer,
+                         const QString& idAccessToken, const QString& sid);
 };
 
 /*! \brief Deletes a third party identifier from the user's account
  *
  * Removes a third party identifier from the user's account. This might not
  * cause an unbind of the identifier from the identity server.
+ *
+ * Unlike other endpoints, this endpoint does not take an ``id_access_token``
+ * parameter because the homeserver is expected to sign the request to the
+ * identity server instead.
  */
 class Delete3pidFromAccountJob : public BaseJob {
 public:
     /*! \brief Deletes a third party identifier from the user's account
      *
+     *
      * \param medium
      *   The medium of the third party identifier being removed.
+     *
      * \param address
      *   The third party address being removed.
+     *
+     * \param idServer
+     *   The identity server to unbind from. If not provided, the homeserver
+     *   MUST use the ``id_server`` the identifier was added through. If the
+     *   homeserver does not know the original ``id_server``, it MUST return
+     *   a ``id_server_unbind_result`` of ``no-support``.
      */
     explicit Delete3pidFromAccountJob(const QString& medium,
-                                      const QString& address);
+                                      const QString& address,
+                                      const QString& idServer = {});
+
+    // Result properties
+
+    /// An indicator as to whether or not the homeserver was able to unbind
+    /// the 3PID from the identity server. ``success`` indicates that the
+    /// indentity server has unbound the identifier whereas ``no-support``
+    /// indicates that the identity server refuses to support the request
+    /// or the homeserver was not able to determine an identity server to
+    /// unbind from.
+    QString idServerUnbindResult() const
+    {
+        return loadFromJson<QString>("id_server_unbind_result"_ls);
+    }
+};
+
+/*! \brief Removes a user's third party identifier from an identity server.
+ *
+ * Removes a user's third party identifier from the provided identity server
+ * without removing it from the homeserver.
+ *
+ * Unlike other endpoints, this endpoint does not take an ``id_access_token``
+ * parameter because the homeserver is expected to sign the request to the
+ * identity server instead.
+ */
+class Unbind3pidFromAccountJob : public BaseJob {
+public:
+    /*! \brief Removes a user's third party identifier from an identity server.
+     *
+     *
+     * \param medium
+     *   The medium of the third party identifier being removed.
+     *
+     * \param address
+     *   The third party address being removed.
+     *
+     * \param idServer
+     *   The identity server to unbind from. If not provided, the homeserver
+     *   MUST use the ``id_server`` the identifier was added through. If the
+     *   homeserver does not know the original ``id_server``, it MUST return
+     *   a ``id_server_unbind_result`` of ``no-support``.
+     */
+    explicit Unbind3pidFromAccountJob(const QString& medium,
+                                      const QString& address,
+                                      const QString& idServer = {});
+
+    // Result properties
+
+    /// An indicator as to whether or not the identity server was able to unbind
+    /// the 3PID. ``success`` indicates that the identity server has unbound the
+    /// identifier whereas ``no-support`` indicates that the identity server
+    /// refuses to support the request or the homeserver was not able to
+    /// determine an identity server to unbind from.
+    QString idServerUnbindResult() const
+    {
+        return loadFromJson<QString>("id_server_unbind_result"_ls);
+    }
 };
 
 /*! \brief Begins the validation process for an email address for association
  * with the user's account.
  *
- * Proxies the Identity Service API ``validate/email/requestToken``, but
- * first checks that the given email address is **not** already associated
- * with an account on this homeserver. This API should be used to request
- * validation tokens when adding an email address to an account. This API's
- * parameters and response are identical to that of the
- * |/register/email/requestToken|_ endpoint.
+ * The homeserver must check that the given email address is **not**
+ * already associated with an account on this homeserver. This API should
+ * be used to request validation tokens when adding an email address to an
+ * account. This API's parameters and response are identical to that of
+ * the |/register/email/requestToken|_ endpoint. The homeserver should validate
+ * the email itself, either by sending a validation email itself or by using
+ * a service it has control over.
  */
 class RequestTokenTo3PIDEmailJob : public BaseJob {
 public:
     /*! \brief Begins the validation process for an email address for
      * association with the user's account.
      *
-     * \param clientSecret
-     *   A unique string generated by the client, and used to identify the
-     *   validation attempt. It must be a string consisting of the characters
-     *   ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it
-     *   must not be empty.
-     * \param email
-     *   The email address to validate.
-     * \param sendAttempt
-     *   The server will only send an email if the ``send_attempt``
-     *   is a number greater than the most recent one which it has seen,
-     *   scoped to that ``email`` + ``client_secret`` pair. This is to
-     *   avoid repeatedly sending the same email in the case of request
-     *   retries between the POSTing user and the identity server.
-     *   The client should increment this value if they desire a new
-     *   email (e.g. a reminder) to be sent.
-     * \param idServer
-     *   The hostname of the identity server to communicate with. May
-     *   optionally include a port.
-     * \param nextLink
-     *   Optional. When the validation is completed, the identity
-     *   server will redirect the user to this URL.
+     *
+     * \param body
+     *   The homeserver must check that the given email address is **not**
+     *   already associated with an account on this homeserver. This API should
+     *   be used to request validation tokens when adding an email address to an
+     *   account. This API's parameters and response are identical to that of
+     *   the |/register/email/requestToken|_ endpoint. The homeserver should
+     * validate the email itself, either by sending a validation email itself or
+     * by using a service it has control over.
      */
-    explicit RequestTokenTo3PIDEmailJob(const QString& clientSecret,
-                                        const QString& email, int sendAttempt,
-                                        const QString& idServer,
-                                        const QString& nextLink = {});
-
-    ~RequestTokenTo3PIDEmailJob() override;
+    explicit RequestTokenTo3PIDEmailJob(const EmailValidationData& body);
 
     // Result properties
 
-    /// An email was sent to the given address.
-    const Sid& data() const;
-
-protected:
-    Status parseJson(const QJsonDocument& data) override;
-
-private:
-    class Private;
-    QScopedPointer<Private> d;
+    /// An email was sent to the given address. Note that this may be an
+    /// email containing the validation token or it may be informing the
+    /// user of an error.
+    RequestTokenResponse data() const
+    {
+        return fromJson<RequestTokenResponse>(jsonData());
+    }
 };
 
 /*! \brief Begins the validation process for a phone number for association with
  * the user's account.
  *
- * Proxies the Identity Service API ``validate/msisdn/requestToken``, but
- * first checks that the given phone number is **not** already associated
- * with an account on this homeserver. This API should be used to request
- * validation tokens when adding a phone number to an account. This API's
- * parameters and response are identical to that of the
- * |/register/msisdn/requestToken|_ endpoint.
+ * The homeserver must check that the given phone number is **not**
+ * already associated with an account on this homeserver. This API should
+ * be used to request validation tokens when adding a phone number to an
+ * account. This API's parameters and response are identical to that of
+ * the |/register/msisdn/requestToken|_ endpoint. The homeserver should validate
+ * the phone number itself, either by sending a validation message itself or by
+ * using a service it has control over.
  */
 class RequestTokenTo3PIDMSISDNJob : public BaseJob {
 public:
     /*! \brief Begins the validation process for a phone number for association
      * with the user's account.
      *
-     * \param clientSecret
-     *   A unique string generated by the client, and used to identify the
-     *   validation attempt. It must be a string consisting of the characters
-     *   ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it
-     *   must not be empty.
-     * \param country
-     *   The two-letter uppercase ISO country code that the number in
-     *   ``phone_number`` should be parsed as if it were dialled from.
-     * \param phoneNumber
-     *   The phone number to validate.
-     * \param sendAttempt
-     *   The server will only send an SMS if the ``send_attempt`` is a
-     *   number greater than the most recent one which it has seen,
-     *   scoped to that ``country`` + ``phone_number`` + ``client_secret``
-     *   triple. This is to avoid repeatedly sending the same SMS in
-     *   the case of request retries between the POSTing user and the
-     *   identity server. The client should increment this value if
-     *   they desire a new SMS (e.g. a reminder) to be sent.
-     * \param idServer
-     *   The hostname of the identity server to communicate with. May
-     *   optionally include a port.
-     * \param nextLink
-     *   Optional. When the validation is completed, the identity
-     *   server will redirect the user to this URL.
+     *
+     * \param body
+     *   The homeserver must check that the given phone number is **not**
+     *   already associated with an account on this homeserver. This API should
+     *   be used to request validation tokens when adding a phone number to an
+     *   account. This API's parameters and response are identical to that of
+     *   the |/register/msisdn/requestToken|_ endpoint. The homeserver should
+     * validate the phone number itself, either by sending a validation message
+     * itself or by using a service it has control over.
      */
-    explicit RequestTokenTo3PIDMSISDNJob(const QString& clientSecret,
-                                         const QString& country,
-                                         const QString& phoneNumber,
-                                         int sendAttempt,
-                                         const QString& idServer,
-                                         const QString& nextLink = {});
-
-    ~RequestTokenTo3PIDMSISDNJob() override;
+    explicit RequestTokenTo3PIDMSISDNJob(const MsisdnValidationData& body);
 
     // Result properties
 
     /// An SMS message was sent to the given phone number.
-    const Sid& data() const;
-
-protected:
-    Status parseJson(const QJsonDocument& data) override;
-
-private:
-    class Private;
-    QScopedPointer<Private> d;
+    RequestTokenResponse data() const
+    {
+        return fromJson<RequestTokenResponse>(jsonData());
+    }
 };
 
 } // namespace Quotient