From abbe9d2bc73753ae1ef825dd62ad35621add8f2b Mon Sep 17 00:00:00 2001
From: David Baker <dave@matrix.org>
Date: Wed, 6 Jul 2016 15:19:39 +0100
Subject: [PATCH] Add register-specific request token endpoint

As per https://github.com/matrix-org/matrix-doc/pull/343
---
 lib/client.js | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/lib/client.js b/lib/client.js
index dcc38fa89..afbb1b0c8 100644
--- a/lib/client.js
+++ b/lib/client.js
@@ -23,6 +23,7 @@ var PushProcessor = require('./pushprocessor');
  */
 var EventEmitter = require("events").EventEmitter;
 var q = require("q");
+var url = require('url');
 
 var httpApi = require("./http-api");
 var MatrixEvent = require("./models/event").MatrixEvent;
@@ -2784,6 +2785,42 @@ MatrixClient.prototype.register = function(username, password,
     );
 };
 
+/**
+ * Requests an email verification token for the purposes of registration.
+ * This API proxies the Identity Server /validate/email/requestToken API,
+ * adding registration-specific behaviour. Specifically, 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 registration-specific logic.
+ *
+ * @param {string} email
+ * @param {string} clientSecret
+ * @param {string} sendAttempt
+ * @param {string} nextLink Optional
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves: TODO
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.requestRegisterEmailToken = function(email, clientSecret,
+                                                    sendAttempt, nextLink, callback) {
+    var id_server_url = url.parse(this.idBaseUrl);
+
+    var params = {
+        client_secret: clientSecret,
+        email: email,
+        send_attempt: sendAttempt,
+        next_link: nextLink,
+        id_server: id_server_url.host,
+    };
+    return this._http.request(
+        callback, "POST", "/register/email/requestToken", undefined,
+        params
+    );
+};
+
 /**
  * @param {string} user
  * @param {string} password
@@ -3665,6 +3702,11 @@ MatrixClient.prototype.getEventMapper = function() {
 // ==========================
 
 /**
+ * Requests an email verification token directly from an Identity Server.
+ *
+ * Note that the Home Server offers APIs to proxy this API for specific
+ * situations, allowing for better feedback to the user.
+ *
  * @param {string} email
  * @param {string} clientSecret
  * @param {string} sendAttempt