Add support for provider detection (#100)

# Description
This PR adds support for the Nylas provider detection endpoint that
allows users to pass in an email address and get the provider that
matches it. This is especially helpful for users that implement native
authentication. This change also enhances the `ProviderSettings` class
by introducing a new static method that is able to match a provider
setting by the provider string
(`ProviderSettings.getProviderSettingsByProvider`). There's also an enum
with all the providers supported for the native authentication flow
(`NativeAuthentication.Provider`).

# Usage
```java
// Set up your client
NylasClient client = new NylasClient();
NativeAuthentication nativeAuthentication = client.application("CLIENT_ID", "CLIENT_SECRET").nativeAuthentication();

// Detect the provider for an email address
NativeAuthentication.DetectedProvider detectedProvider = nativeAuthentication.detectProvider("test@gmail.com");
// The following fields are made available
detectedProvider.isDetected();
detectedProvider.getProviderName();
detectedProvider.getAuthName();
detectedProvider.getEmailAddress();
detectedProvider.isImap();

// You can use the result from above to get the correct provider settings
ProviderSettings detectedSettings = ProviderSettings.getProviderSettingsByProvider(provider.getAuthName());

// The enum is provided for consistency and equality
if(detectedProvider.getAuthName() == NativeAuthentication.Provider.GMAIL.getName()) {
  // do something here for a Gmail case
}
```

# License
<!-- Your PR comment must contain the following line for us to merge the
PR. -->
I confirm that this contribution is made under the terms of the MIT
license and that I have the authority necessary to make this
contribution on behalf of its copyright owner.

Author: mrashed-dev

CHANGELOG.md

@@ -6,6 +6,8 @@ This section contains changes that have been committed but not yet released.
 
 ### Added
 
+* Added support for provider detection
+* Added an enum for all known providers for native authentication
 * Improved webhook notification support with the addition of more notification attributes and event metadata fields
 
 ### Changed

src/main/java/com/nylas/GoogleProviderSettings.java

@@ -19,7 +19,7 @@
 public class GoogleProviderSettings extends ProviderSettings {
 
 	protected GoogleProviderSettings() {
-		super("gmail");
+		super(NativeAuthentication.Provider.GMAIL.getName());
 	}
 
 	public GoogleProviderSettings googleClientId(String googleClientId) {

src/main/java/com/nylas/ImapProviderSettings.java

@@ -10,7 +10,7 @@
 public class ImapProviderSettings extends ProviderSettings {
 
 	protected ImapProviderSettings() {
-		super("imap");
+		super(NativeAuthentication.Provider.IMAP.getName());
 	}
 
 	public ImapProviderSettings imapHost(String imapHost) {

src/main/java/com/nylas/MicrosoftExchangeProviderSettings.java

@@ -11,7 +11,7 @@
 public class MicrosoftExchangeProviderSettings extends ProviderSettings {
 
 	protected MicrosoftExchangeProviderSettings() {
-		super("exchange");
+		super(NativeAuthentication.Provider.EXCHANGE.getName());
 	}
 
 	public MicrosoftExchangeProviderSettings username(String username) {

src/main/java/com/nylas/MicrosoftOffice365ProviderSettings.java

@@ -11,7 +11,7 @@
 public class MicrosoftOffice365ProviderSettings extends ProviderSettings {
 
 	protected MicrosoftOffice365ProviderSettings() {
-		super("office365");
+		super(NativeAuthentication.Provider.OFFICE_365.getName());
 	}
 
 	public MicrosoftOffice365ProviderSettings microsoftClientId(String microsoftClientId) {

src/main/java/com/nylas/NativeAuthentication.java

@@ -17,6 +17,41 @@ public class NativeAuthentication {
 
 	private final NylasApplication application;
 
+	/** Supported providers for Native Authentication */
+	public enum Provider {
+		GMAIL("gmail"),
+		IMAP("imap"),
+		OFFICE_365("office365"),
+		EXCHANGE("exchange"),
+		YAHOO("yahoo"),
+		AOL("aol"),
+		HOTMAIL("hotmail"),
+		OUTLOOK("outlook"),
+		ICLOUD("icloud"),
+
+		;
+
+		private final String name;
+
+		Provider(String name) {
+			this.name = name;
+		}
+
+		public String getName() {
+			return name;
+		}
+
+		public static Provider getProviderByName(String name) {
+			for(Provider provider : Provider.values()) {
+				if(provider.name.equals(name)) {
+					return provider;
+				}
+			}
+
+			return null;
+		}
+	}
+
 	NativeAuthentication(NylasApplication application) {
 		this.application = application;
 	}
@@ -115,6 +150,11 @@ public String execute() throws IOException, RequestFailedException {
 		}
 	}
 
+	/**
+	 * Exchange the code from sending the native authentication for an access token
+	 * @param authorizationCode The code received from the native authentication
+	 * @return The access token details
+	 */
 	public AccessToken fetchToken(String authorizationCode) throws IOException, RequestFailedException {
 		Map<String, Object> params = new HashMap<>();
 		params.put("client_id", application.getClientId());
@@ -125,4 +165,72 @@ public AccessToken fetchToken(String authorizationCode) throws IOException, Requ
 		return application.getClient().executePost(null, tokenUrl, params, AccessToken.class);
 	}
 
+	/**
+	 * Detect which provider an email uses
+	 * @param emailAddress The email address to determine the provider of
+	 * @return The details of the provider detection
+	 */
+	public DetectedProvider detectProvider(String emailAddress) throws RequestFailedException, IOException {
+		Map<String, Object> params = new HashMap<>();
+		params.put("client_id", application.getClientId());
+		params.put("client_secret", application.getClientSecret());
+		params.put("email_address", emailAddress);
+
+		HttpUrl.Builder detectUrl = application.getClient().newUrlBuilder().addPathSegments("connect/detect-provider");
+		return application.getClient().executePost(null, detectUrl, params, DetectedProvider.class);
+	}
+
+	/**
+	 * Get settings of a provider detected from an email
+	 * @param emailAddress The email address to determine the provider of
+	 * @return The settings for the detected provider
+	 */
+	public ProviderSettings getDetectedProviderSettings(String emailAddress) throws RequestFailedException, IOException {
+		DetectedProvider detectedProvider = detectProvider(emailAddress);
+		return ProviderSettings.getProviderSettingsByProvider(detectedProvider.getAuthName());
+	}
+
+	public static class DetectedProvider {
+		private String auth_name;
+		private String email_address;
+		private String provider_name;
+		private Boolean detected;
+		private Boolean is_imap;
+
+		/**
+		 * The provider's auth name to be used in Native Authentication
+		 */
+		public String getAuthName() {
+			return auth_name;
+		}
+
+		/**
+		 * The email address being checked
+		 */
+		public String getEmailAddress() {
+			return email_address;
+		}
+
+		/**
+		 * The name of the detected provider
+		 */
+		public String getProviderName() {
+			return provider_name;
+		}
+
+		/**
+		 * If this account's mail server settings and provider were auto-detected
+		 */
+		public Boolean isDetected() {
+			return detected;
+		}
+
+		/**
+		 * If the account should be authenticated with IMAP.
+		 * If {@link #isDetected()} returns false, ignore this value.
+		 */
+		public Boolean isImap() {
+			return is_imap;
+		}
+	}
 }

src/main/java/com/nylas/ProviderSettings.java

@@ -1,6 +1,7 @@
 package com.nylas;
 
 import static com.nylas.Validations.assertState;
+import com.nylas.NativeAuthentication.Provider;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -19,6 +20,42 @@ public class ProviderSettings {
 
 	private final String providerName;
 	private final Map<String, Object> settings = new HashMap<>();
+
+	/**
+	 * Returns the provider settings for a provider. If the provider is not found, it will return a
+	 * {@link KnownImapProviderSettings} with the provider set to the string passed in.
+	 * @param providerName The provider for the native authentication
+	 * @return The settings for the provider
+	 */
+	public static ProviderSettings getProviderSettingsByProvider(String providerName) {
+		Provider provider = Provider.getProviderByName(providerName);
+		if(provider == null) {
+			return knownImap(providerName);
+		}
+
+		switch (provider) {
+			case GMAIL:
+				return ProviderSettings.google();
+			case IMAP:
+				return ProviderSettings.imap();
+			case OFFICE_365:
+				return ProviderSettings.office365();
+			case EXCHANGE:
+				return ProviderSettings.exchange();
+			case YAHOO:
+				return ProviderSettings.yahoo();
+			case AOL:
+				return ProviderSettings.aol();
+			case HOTMAIL:
+				return ProviderSettings.hotmail();
+			case OUTLOOK:
+				return ProviderSettings.outlook();
+			case ICLOUD:
+				return ProviderSettings.icloud();
+			default:
+				return knownImap(provider.getName());
+		}
+	}
 
 	public static GoogleProviderSettings google() {
 		return new GoogleProviderSettings();
@@ -46,7 +83,7 @@ public static KnownImapProviderSettings knownImap(String provider) {
 	 * NOTE - Many Yahoo accounts currently require the user to generate an App Password for this to work.
 	 */
 	public static KnownImapProviderSettings yahoo() {
-		return new KnownImapProviderSettings("yahoo");
+		return new KnownImapProviderSettings(Provider.YAHOO.getName());
 	}
 
 	/**
@@ -55,19 +92,19 @@ public static KnownImapProviderSettings yahoo() {
 	 * NOTE - Many AOL accounts currently require the user to generate an App Password for this to work.
 	 */
 	public static KnownImapProviderSettings aol() {
-		return new KnownImapProviderSettings("aol");
+		return new KnownImapProviderSettings(Provider.AOL.getName());
 	}
 
 	public static KnownImapProviderSettings hotmail() {
-		return new KnownImapProviderSettings("hotmail");
+		return new KnownImapProviderSettings(Provider.HOTMAIL.getName());
 	}
 
 	public static KnownImapProviderSettings outlook() {
-		return new KnownImapProviderSettings("outlook");
+		return new KnownImapProviderSettings(Provider.OUTLOOK.getName());
 	}
 
 	public static KnownImapProviderSettings icloud() {
-		return new KnownImapProviderSettings("icloud");
+		return new KnownImapProviderSettings(Provider.ICLOUD.getName());
 	}
 
 	public ProviderSettings(String providerName) {