Add /v2/users-by-email endpoint

.gitignore

@@ -119,6 +119,7 @@ gradle-app.setting
 modules.xml
 .idea/misc.xml
 *.ipr
+/out/
 
 # End of https://www.gitignore.io/api/intellij+iml
 

README.md

@@ -264,7 +264,7 @@ The Management API is divided into different entities. Each of them have the lis
 * **Logs:** See [Docs](https://auth0.com/docs/api/management/v2#!/Logs/get_logs). Access the methods by calling `mgmt.logEvents()`.
 * **Rules:** See [Docs](https://auth0.com/docs/api/management/v2#!/Rules/get_rules). Access the methods by calling `mgmt.rules()`.
 * **User Blocks:** See [Docs](https://auth0.com/docs/api/management/v2#!/User_Blocks/get_user_blocks). Access the methods by calling `mgmt.userBlocks()`.
-* **Users:** See [Docs](https://auth0.com/docs/api/management/v2#!/Users/get_users). Access the methods by calling `mgmt.users()`.
+* **Users:** See [this](https://auth0.com/docs/api/management/v2#!/Users/get_users) and [this](https://auth0.com/docs/api/management/v2#!/Users_By_Email) Docs. Access the methods by calling `mgmt.users()`.
 * **Blacklists:** See [Docs](https://auth0.com/docs/api/management/v2#!/Blacklists/get_tokens). Access the methods by calling `mgmt.blacklists()`.
 * **Emails:** See [Docs](https://auth0.com/docs/api/management/v2#!/Emails/get_provider). Access the methods by calling `mgmt.emailProvider()`.
 * **Guardian:** See [Docs](https://auth0.com/docs/api/management/v2#!/Guardian/get_factors). Access the methods by calling `mgmt.guardian()`.
@@ -275,6 +275,26 @@ The Management API is divided into different entities. Each of them have the lis
 
 ### Users
 
+#### List by Email
+
+Creates a request to list the Users by Email. This is the preferred and fastest way to query Users by Email, and should be used instead of calling the generic list method with an email query. An API Token with scope `read:users` is needed. If you want the identities.access_token property to be included, you will also need the scope `read:user_idp_tokens`.
+You can pass an optional Filter to narrow the results in the response.
+
+`Request<UsersPage> listByEmail(String email, UserFilter filter)`
+
+Example:
+```java
+FieldsFilter filter = new FieldsFilter(...);
+Request<UsersPage> request = mgmt.users().list("johndoe@auth0.com", filter);
+try {
+    UsersPage response = request.execute();
+} catch (APIException exception) {
+    // api error
+} catch (Auth0Exception exception) {
+    // request error
+}
+```
+
 #### List
 
 Creates a request to list the Users. An API Token with scope `read:users` is needed. If you want the identities.access_token property to be included, you will also need the scope `read:user_idp_tokens`.

src/main/java/com/auth0/client/mgmt/UsersEntity.java

@@ -1,5 +1,6 @@
 package com.auth0.client.mgmt;
 
+import com.auth0.client.mgmt.filter.FieldsFilter;
 import com.auth0.client.mgmt.filter.LogEventFilter;
 import com.auth0.client.mgmt.filter.UserFilter;
 import com.auth0.json.mgmt.guardian.Enrollment;
@@ -23,7 +24,7 @@
 import static com.auth0.client.mgmt.filter.QueryFilter.KEY_QUERY;
 
 /**
- * Class that provides an implementation of the Users methods of the Management API as defined in https://auth0.com/docs/api/management/v2#!/Users
+ * Class that provides an implementation of the Users methods of the Management API as defined in https://auth0.com/docs/api/management/v2#!/Users and https://auth0.com/docs/api/management/v2#!/Users_By_Email
  */
 @SuppressWarnings("WeakerAccess")
 public class UsersEntity extends BaseManagementEntity {
@@ -32,6 +33,35 @@ public class UsersEntity extends BaseManagementEntity {
         super(client, baseUrl, apiToken);
     }
 
+    /**
+     * Request all the Users that match a given email. A token with scope read:users is needed.
+     * If you want the identities.access_token property to be included, you will also need the scope read:user_idp_tokens.
+     * See https://auth0.com/docs/api/management/v2#!/Users_By_Email/get_users_by_email
+     *
+     * @param email  the email of the users to look up.
+     * @param filter the filter to use. Can be null.
+     * @return a Request to execute.
+     */
+    public Request<List<User>> listByEmail(String email, FieldsFilter filter) {
+        Asserts.assertNotNull(email, "email");
+
+        HttpUrl.Builder builder = baseUrl
+                .newBuilder()
+                .addPathSegments("api/v2/users-by-email");
+        builder.addQueryParameter("email", email);
+        if (filter != null) {
+            for (Map.Entry<String, Object> e : filter.getAsMap().entrySet()) {
+                builder.addQueryParameter(e.getKey(), String.valueOf(e.getValue()));
+            }
+        }
+
+        String url = builder.build().toString();
+        CustomRequest<List<User>> request = new CustomRequest<>(client, url, "GET", new TypeReference<List<User>>() {
+        });
+        request.addHeader("Authorization", "Bearer " + apiToken);
+        return request;
+    }
+
     /**
      * Request all the Users. A token with scope read:users is needed.
      * If you want the identities.access_token property to be included, you will also need the scope read:user_idp_tokens.

src/test/java/com/auth0/client/mgmt/UsersEntityTest.java

@@ -1,5 +1,6 @@
 package com.auth0.client.mgmt;
 
+import com.auth0.client.mgmt.filter.FieldsFilter;
 import com.auth0.client.mgmt.filter.LogEventFilter;
 import com.auth0.client.mgmt.filter.UserFilter;
 import com.auth0.json.mgmt.guardian.Enrollment;
@@ -23,6 +24,57 @@
 
 public class UsersEntityTest extends BaseMgmtEntityTest {
 
+    @Test
+    public void shouldListUsersByEmail() throws Exception {
+        Request<List<User>> request = api.users().listByEmail("johndoe@auth0.com", null);
+        assertThat(request, is(notNullValue()));
+
+        server.jsonResponse(MGMT_USERS_LIST, 200);
+        List<User> response = request.execute();
+        RecordedRequest recordedRequest = server.takeRequest();
+
+        assertThat(recordedRequest, hasMethodAndPath("GET", "/api/v2/users-by-email"));
+        assertThat(recordedRequest, hasHeader("Content-Type", "application/json"));
+        assertThat(recordedRequest, hasHeader("Authorization", "Bearer apiToken"));
+        assertThat(recordedRequest, hasQueryParameter("email", "johndoe@auth0.com"));
+
+        assertThat(response, is(notNullValue()));
+        assertThat(response, hasSize(2));
+    }
+
+    @Test
+    public void shouldListUsersByEmailWithFields() throws Exception {
+        FieldsFilter filter = new FieldsFilter().withFields("some,random,fields", true);
+        Request<List<User>> request = api.users().listByEmail("johndoe@auth0.com", filter);
+        assertThat(request, is(notNullValue()));
+
+        server.jsonResponse(MGMT_USERS_LIST, 200);
+        List<User> response = request.execute();
+        RecordedRequest recordedRequest = server.takeRequest();
+
+        assertThat(recordedRequest, hasMethodAndPath("GET", "/api/v2/users-by-email"));
+        assertThat(recordedRequest, hasHeader("Content-Type", "application/json"));
+        assertThat(recordedRequest, hasHeader("Authorization", "Bearer apiToken"));
+        assertThat(recordedRequest, hasQueryParameter("email", "johndoe@auth0.com"));
+        assertThat(recordedRequest, hasQueryParameter("fields", "some,random,fields"));
+        assertThat(recordedRequest, hasQueryParameter("include_fields", "true"));
+
+        assertThat(response, is(notNullValue()));
+        assertThat(response, hasSize(2));
+    }
+
+    @Test
+    public void shouldReturnEmptyUsersByEmail() throws Exception {
+        Request<List<User>> request = api.users().listByEmail("missing@auth0.com", null);
+        assertThat(request, is(notNullValue()));
+
+        server.jsonResponse(MGMT_EMPTY_LIST, 200);
+        List<User> response = request.execute();
+
+        assertThat(response, is(notNullValue()));
+        assertThat(response, is(emptyCollectionOf(User.class)));
+    }
+
     @Test
     public void shouldListUsers() throws Exception {
         Request<UsersPage> request = api.users().list(null);