Merge pull request #148 from matrix-org/dbkr/more_requesttokens

Add API calls for other requestToken endpoints

CHANGELOG.md

@@ -2,6 +2,7 @@ Changes in \<unreleased>
 =======================
 
  * Add room.getAliases() and room.getCanonicalAlias
+ * Add API calls `/register/email/requestToken`, `/account/password/email/requestToken` and `/account/3pid/email/requestToken`
 
 Changes in [0.5.4](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.5.4) (2016-06-02)
 ================================================================================================

lib/client.js

@@ -2807,6 +2807,82 @@ MatrixClient.prototype.register = function(username, password,
  */
 MatrixClient.prototype.requestRegisterEmailToken = function(email, clientSecret,
                                                     sendAttempt, nextLink, callback) {
+    return this._requestTokenFromEndpoint(
+        "/register/email/requestToken",
+        email, clientSecret, sendAttempt, nextLink, callback
+    );
+};
+
+/**
+ * Requests an email verification token for the purposes of adding a
+ * third party identifier to an account.
+ * This API proxies the Identity Server /validate/email/requestToken API,
+ * adding specific behaviour for the addition of email addresses to an
+ * account. Specifically, if an account with
+ * the given email address already exists, it will either send an email
+ * to the address informing them of this or return M_THREEPID_IN_USE
+ * (which one is up to the Home Server).
+ *
+ * requestEmailToken calls the equivalent API directly on the ID server,
+ * therefore bypassing the email addition specific logic.
+ *
+ * @param {string} email As requestEmailToken
+ * @param {string} clientSecret As requestEmailToken
+ * @param {number} sendAttempt As requestEmailToken
+ * @param {string} nextLink As requestEmailToken
+ * @param {module:client.callback} callback Optional. As requestEmailToken
+ * @return {module:client.Promise} Resolves: As requestEmailToken
+ */
+MatrixClient.prototype.requestAdd3pidEmailToken = function(email, clientSecret,
+                                                    sendAttempt, nextLink, callback) {
+    return this._requestTokenFromEndpoint(
+        "/account/3pid/email/requestToken",
+        email, clientSecret, sendAttempt, nextLink, callback
+    );
+};
+
+/**
+ * Requests an email verification token for the purposes of resetting
+ * the password on an account.
+ * This API proxies the Identity Server /validate/email/requestToken API,
+ * adding specific behaviour for the password resetting. Specifically,
+ * if no account with the given email address exists, it may either
+ * return M_THREEPID_NOT_FOUND or send an email
+ * to the address informing them of this (which one is up to the Home Server).
+ *
+ * requestEmailToken calls the equivalent API directly on the ID server,
+ * therefore bypassing the password reset specific logic.
+ *
+ * @param {string} email As requestEmailToken
+ * @param {string} clientSecret As requestEmailToken
+ * @param {number} sendAttempt As requestEmailToken
+ * @param {string} nextLink As requestEmailToken
+ * @param {module:client.callback} callback Optional. As requestEmailToken
+ * @return {module:client.Promise} Resolves: As requestEmailToken
+ */
+MatrixClient.prototype.requestPasswordEmailToken = function(email, clientSecret,
+                                                    sendAttempt, nextLink, callback) {
+    return this._requestTokenFromEndpoint(
+        "/account/password/email/requestToken",
+        email, clientSecret, sendAttempt, nextLink, callback
+    );
+};
+
+/**
+ * Internal utility function for requesting validation tokens from usage-specific
+ * requestToken endpoints.
+ *
+ * @param {string} endpoint The endpoint to send the request to
+ * @param {string} email As requestEmailToken
+ * @param {string} clientSecret As requestEmailToken
+ * @param {number} sendAttempt As requestEmailToken
+ * @param {string} nextLink As requestEmailToken
+ * @param {module:client.callback} callback Optional. As requestEmailToken
+ * @return {module:client.Promise} Resolves: As requestEmailToken
+ */
+MatrixClient.prototype._requestTokenFromEndpoint = function(endpoint,
+                                                    email, clientSecret,
+                                                    sendAttempt, nextLink, callback) {
     var id_server_url = url.parse(this.idBaseUrl);
     if (id_server_url.host === null) {
         throw new Error("Invalid ID server URL: " + this.idBaseUrl);
@@ -2820,7 +2896,7 @@ MatrixClient.prototype.requestRegisterEmailToken = function(email, clientSecret,
         id_server: id_server_url.host,
     };
     return this._http.request(
-        callback, "POST", "/register/email/requestToken", undefined,
+        callback, "POST", endpoint, undefined,
         params
     );
 };