001/* 002 * Copyright (c) 2011-2017 Nexmo Inc 003 * 004 * Permission is hereby granted, free of charge, to any person obtaining a copy 005 * of this software and associated documentation files (the "Software"), to deal 006 * in the Software without restriction, including without limitation the rights 007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 008 * copies of the Software, and to permit persons to whom the Software is 009 * furnished to do so, subject to the following conditions: 010 * 011 * The above copyright notice and this permission notice shall be included in 012 * all copies or substantial portions of the Software. 013 * 014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 020 * THE SOFTWARE. 021 */ 022package com.nexmo.client.verify; 023 024 025import com.nexmo.client.AbstractClient; 026import com.nexmo.client.HttpWrapper; 027import com.nexmo.client.NexmoClient; 028import com.nexmo.client.NexmoClientException; 029import com.nexmo.client.verify.endpoints.CheckEndpoint; 030import com.nexmo.client.verify.endpoints.ControlEndpoint; 031import com.nexmo.client.verify.endpoints.SearchEndpoint; 032import com.nexmo.client.verify.endpoints.VerifyEndpoint; 033 034import java.io.IOException; 035import java.util.Locale; 036 037/** 038 * A client for talking to the Nexmo Verify API. The standard way to obtain an instance of this class is to use 039 * {@link NexmoClient#getVerifyClient()}. 040 * <p> 041 * Send a verification request with a call to {@link #verify}, confirm the code entered by the user with 042 * {@link #check}, and search in-progress or completed verification requests with {@link #search} 043 * <p> 044 * More information on method parameters can be found at Nexmo website: 045 * <a href="https://docs.nexmo.com/verify">https://docs.nexmo.com/verify</a> 046 */ 047public class VerifyClient extends AbstractClient { 048 049 private CheckEndpoint check; 050 private VerifyEndpoint verify; 051 private SearchEndpoint search; 052 private ControlEndpoint control; 053 054 /** 055 * Constructor. 056 * 057 * @param httpWrapper (required) shared HTTP wrapper object used for making REST calls. 058 */ 059 public VerifyClient(HttpWrapper httpWrapper) { 060 super(httpWrapper); 061 062 this.check = new CheckEndpoint(httpWrapper); 063 this.search = new SearchEndpoint(httpWrapper); 064 this.verify = new VerifyEndpoint(httpWrapper); 065 this.control = new ControlEndpoint(httpWrapper); 066 } 067 068 /** 069 * Send a verification request to a phone number. 070 * 071 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 072 * format. 073 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 074 * characters. 075 * @return a VerifyResult representing the response received from the Verify API call. 076 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 077 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 078 */ 079 public VerifyResult verify(final String number, 080 final String brand) throws IOException, 081 NexmoClientException { 082 return verify.verify(number, brand); 083 } 084 085 /** 086 * Send a verification request to a phone number. 087 * 088 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 089 * format. 090 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 091 * characters. 092 * @param from (optional The Nexmo number to use as the sender for the verification SMS message and calls, in 093 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 094 * @return a VerifyResult representing the response received from the Verify API call. 095 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 096 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 097 */ 098 public VerifyResult verify(final String number, 099 final String brand, 100 final String from) throws IOException, 101 NexmoClientException { 102 return verify.verify(number, brand, from); 103 } 104 105 /** 106 * Send a verification request to a phone number. 107 * 108 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 109 * format. 110 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 111 * characters. 112 * @param from (optional The Nexmo number to use as the sender for the verification SMS message and calls, in 113 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 114 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 115 * -1 to use the default value. 116 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 117 * from the country code included in <tt>number</tt> 118 * @return a VerifyResult representing the response received from the Verify API call. 119 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 120 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 121 */ 122 public VerifyResult verify(final String number, 123 final String brand, 124 final String from, 125 final int length, 126 final Locale locale) throws IOException, 127 NexmoClientException { 128 return verify.verify(number, brand, from, length, locale); 129 } 130 131 /** 132 * Send a verification request to a phone number. 133 * 134 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 135 * format. 136 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 137 * characters. 138 * @param from (optional The Nexmo number to use as the sender for the verification SMS message and calls, in 139 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 140 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 141 * -1 to use the default value. 142 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 143 * from the country code included in <tt>number</tt> 144 * @param type (optional) If provided, restrict the verification to the specified network type. Contact 145 * support@nexmo.com to enable this feature. 146 * @return a VerifyResult representing the response received from the Verify API call. 147 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 148 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 149 */ 150 public VerifyResult verify(final String number, 151 final String brand, 152 final String from, 153 final int length, 154 final Locale locale, 155 final VerifyRequest.LineType type) throws IOException, 156 NexmoClientException { 157 return verify.verify(number, brand, from, length, locale, type); 158 } 159 160 /** 161 * Send a verification request to a phone number. 162 */ 163 public VerifyResult verify(VerifyRequest request) throws IOException, NexmoClientException { 164 return verify.verify(request); 165 } 166 167 /** 168 * Validate a code provided by a user in response to a call from {@link #verify}. 169 * 170 * @param requestId (required) The requestId returned by the <tt>verify</tt> call. 171 * @param code (required) The code entered by the user. 172 * @return a CheckResult representing the response received from the API call. 173 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 174 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 175 */ 176 public CheckResult check(final String requestId, 177 final String code) throws IOException, NexmoClientException { 178 return check.check(requestId, code, null); 179 } 180 181 /** 182 * Validate a code provided by a user in response to a call from {@link #verify}. 183 * 184 * @param requestId (required) The requestId returned by the <tt>verify</tt> call. 185 * @param code (required) The code entered by the user. 186 * @param ipAddress (optional) The IP address obtained from the HTTP request made when the user entered their code. 187 * @return a CheckResult representing the response received from the API call. 188 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 189 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 190 */ 191 public CheckResult check(final String requestId, 192 final String code, 193 final String ipAddress) throws IOException, NexmoClientException { 194 return check.check(requestId, code, ipAddress); 195 } 196 197 /** 198 * Search for a previous verification request. 199 * 200 * @param requestId The requestId of a single Verify request to be looked up. 201 * @return A SearchResult containing the details of the Verify request that was looked up, or <tt>null</tt> if no 202 * record was found. 203 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 204 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 205 */ 206 public SearchResult search(String requestId) throws IOException, NexmoClientException { 207 return search.search(requestId); 208 } 209 210 /** 211 * Search for a previous verification request. 212 * 213 * @param requestIds The requestIds of Verify requests to be looked up. 214 * @return An array SearchResult for each record that was found. 215 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 216 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 217 */ 218 public SearchResult[] search(String... requestIds) throws IOException, NexmoClientException { 219 return search.search(requestIds); 220 } 221 222 /** 223 * Advance a current verification request to the next stage in the process. 224 * 225 * @param requestId The requestId of the ongoing verification request. 226 * @throws IOException If an IO error occurred while making the request. 227 * @throws NexmoClientException If the request failed for some reason. 228 */ 229 public void advanceVerification(String requestId) throws IOException, NexmoClientException { 230 control.execute(new ControlRequest(requestId, VerifyControlCommand.TRIGGER_NEXT_EVENT)); 231 } 232 233 /** 234 * Cancel a current verification request. 235 * 236 * @param requestId The requestId of the ongoing verification request. 237 * @throws IOException If an IO error occurred while making the request. 238 * @throws NexmoClientException If the request failed for some reason. 239 */ 240 public void cancelVerification(String requestId) throws IOException, NexmoClientException { 241 control.execute(new ControlRequest(requestId, VerifyControlCommand.CANCEL)); 242 } 243}