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