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 024import com.nexmo.client.AbstractClient; 025import com.nexmo.client.HttpWrapper; 026import com.nexmo.client.NexmoClient; 027import com.nexmo.client.NexmoClientException; 028import com.nexmo.client.verify.endpoints.ControlEndpoint; 029 030import java.io.IOException; 031import java.util.Locale; 032 033/** 034 * A client for talking to the Nexmo Verify API. The standard way to obtain an instance of this class is to use 035 * {@link NexmoClient#getVerifyClient()}. 036 * <p> 037 * Send a verification request with a call to {@link #verify}, confirm the code entered by the user with 038 * {@link #check}, and search in-progress or completed verification requests with {@link #search} 039 * <p> 040 * More information on method parameters can be found at Nexmo website: 041 * <a href="https://docs.nexmo.com/verify">https://docs.nexmo.com/verify</a> 042 */ 043public class VerifyClient extends AbstractClient { 044 045 private CheckEndpoint check; 046 private VerifyEndpoint verify; 047 private SearchEndpoint search; 048 private ControlEndpoint control; 049 050 /** 051 * Constructor. 052 * 053 * @param httpWrapper (required) shared HTTP wrapper object used for making REST calls. 054 */ 055 public VerifyClient(HttpWrapper httpWrapper) { 056 super(httpWrapper); 057 058 this.check = new CheckEndpoint(httpWrapper); 059 this.search = new SearchEndpoint(httpWrapper); 060 this.verify = new VerifyEndpoint(httpWrapper); 061 this.control = new ControlEndpoint(httpWrapper); 062 } 063 064 /** 065 * Send a verification request to a phone number. 066 * 067 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 068 * format. 069 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 070 * characters. 071 * @return a VerifyResult representing the response received from the Verify API call. 072 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 073 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 074 */ 075 public VerifyResult verify(final String number, final String brand) throws IOException, NexmoClientException { 076 return this.verify.verify(number, brand); 077 } 078 079 /** 080 * Send a verification request to a phone number. 081 * 082 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 083 * format. 084 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 085 * characters. 086 * @param from (optional The Nexmo number to use as the sender for the verification SMS message and calls, in 087 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 088 * @return a VerifyResult representing the response received from the Verify API call. 089 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 090 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 091 */ 092 public VerifyResult verify(final String number, 093 final String brand, 094 final String from) throws IOException, NexmoClientException { 095 return this.verify.verify(number, brand, from); 096 } 097 098 /** 099 * Send a verification request to a phone number. 100 * 101 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 102 * format. 103 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 104 * characters. 105 * @param from (optional The Nexmo number to use as the sender for the verification SMS message and calls, in 106 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 107 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 108 * -1 to use the default value. 109 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 110 * from the country code included in <tt>number</tt> 111 * @return a VerifyResult representing the response received from the Verify API call. 112 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 113 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 114 */ 115 public VerifyResult verify(final String number, 116 final String brand, 117 final String from, 118 final int length, 119 final Locale locale) throws IOException, NexmoClientException { 120 return this.verify.verify(number, brand, from, length, locale); 121 } 122 123 /** 124 * Send a verification request to a phone number. 125 * 126 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 127 * format. 128 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 129 * characters. 130 * @param from (optional The Nexmo number to use as the sender for the verification SMS message and calls, in 131 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 132 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 133 * -1 to use the default value. 134 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 135 * from the country code included in <tt>number</tt> 136 * @param type (optional) If provided, restrict the verification to the specified network type. Contact 137 * support@nexmo.com to enable this feature. 138 * @return a VerifyResult representing the response received from the Verify API call. 139 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 140 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 141 */ 142 public VerifyResult verify(final String number, 143 final String brand, 144 final String from, 145 final int length, 146 final Locale locale, 147 final VerifyRequest.LineType type) throws IOException, NexmoClientException { 148 return this.verify.verify(number, brand, from, length, locale, type); 149 } 150 151 /** 152 * Send a verification request to a phone number. 153 */ 154 public VerifyResult verify(VerifyRequest request) throws IOException, NexmoClientException { 155 return this.verify.verify(request); 156 } 157 158 /** 159 * Validate a code provided by a user in response to a call from {@link #verify}. 160 * 161 * @param requestId (required) The requestId returned by the <tt>verify</tt> call. 162 * @param code (required) The code entered by the user. 163 * @return a CheckResult representing the response received from the API call. 164 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 165 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 166 */ 167 public CheckResult check(final String requestId, final String code) throws IOException, NexmoClientException { 168 return this.check.check(requestId, code); 169 } 170 171 /** 172 * Validate a code provided by a user in response to a call from {@link #verify}. 173 * 174 * @param requestId (required) The requestId returned by the <tt>verify</tt> call. 175 * @param code (required) The code entered by the user. 176 * @param ipAddress (optional) The IP address obtained from the HTTP request made when the user entered their code. 177 * @return a CheckResult representing the response received from the API call. 178 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 179 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 180 */ 181 public CheckResult check(final String requestId, 182 final String code, 183 final String ipAddress) throws IOException, NexmoClientException { 184 return this.check.check(requestId, code, ipAddress); 185 } 186 187 /** 188 * Search for a previous verification request. 189 * 190 * @param requestId The requestId of a single Verify request to be looked up. 191 * @return A SearchResult containing the details of the Verify request that was looked up, or <tt>null</tt> if no 192 * record was found. 193 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 194 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 195 */ 196 public SearchResult search(String requestId) throws IOException, NexmoClientException { 197 return this.search.search(requestId)[0]; 198 } 199 200 /** 201 * Search for a previous verification request. 202 * 203 * @param requestIds The requestIds of Verify requests to be looked up. 204 * @return An array SearchResult for each record that was found. 205 * @throws IOException if a network error occurred contacting the Nexmo Verify API. 206 * @throws NexmoClientException if there was a problem with the Nexmo request or response objects. 207 */ 208 public SearchResult[] search(String... requestIds) throws IOException, NexmoClientException { 209 return this.search.search(requestIds); 210 } 211 212 /** 213 * Advance a current verification request to the next stage in the process. 214 * 215 * @param requestId The requestId of the ongoing verification request. 216 * @return A {@link ControlResponse} representing the response from the API. 217 * @throws IOException If an IO error occurred while making the request. 218 * @throws NexmoClientException If the request failed for some reason. 219 */ 220 public ControlResponse advanceVerification(String requestId) throws IOException, NexmoClientException { 221 return this.control.execute(new ControlRequest(requestId, VerifyControlCommand.TRIGGER_NEXT_EVENT)); 222 } 223 224 /** 225 * Cancel a current verification request. 226 * 227 * @param requestId The requestId of the ongoing verification request. 228 * @return A {@link ControlResponse} representing the response from the API. 229 * @throws IOException If an IO error occurred while making the request. 230 * @throws NexmoClientException If the request failed for some reason. 231 */ 232 public ControlResponse cancelVerification(String requestId) throws IOException, NexmoClientException { 233 return this.control.execute(new ControlRequest(requestId, VerifyControlCommand.CANCEL)); 234 } 235}