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.fasterxml.jackson.annotation.JsonValue;
025
026import java.util.Locale;
027
028/**
029 * Describes a Verify request when passed to {@link com.nexmo.client.verify.VerifyEndpoint}.
030 */
031public class VerifyRequest extends BaseRequest {
032    private LineType type;
033    private String brand;
034    private String from;
035    private Workflow workflow;
036
037
038
039    /**
040     * Constructor.
041     *
042     * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
043     *               format.
044     * @param brand  (required) The name of the company or app to be verified for. Must not be longer than 18
045     *               characters.
046     * @deprecated this construtor is deprecated use {@link Builder} to contruct a 2FA verify request
047     */
048    @Deprecated
049    public VerifyRequest(final String number, final String brand) {
050        this(number, brand, null, -1, null, null);
051    }
052
053    /**
054     * Constructor.
055     *
056     * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
057     *               format.
058     * @param brand  (required) The name of the company or app you are verifying for. Must not be longer than 18
059     *               characters.
060     * @param from   (optional The Nexmo number to use as the sender for the verification SMS message and calls, in
061     *               <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format.
062     * @deprecated this construtor is deprecated use {@link Builder} to contruct a 2FA verify request
063     */
064    @Deprecated
065    public VerifyRequest(final String number, final String brand, final String from) {
066        this(number, brand, from, -1, null, null);
067    }
068
069    /**
070     * Constructor.
071     *
072     * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
073     *               format.
074     * @param brand  (required) The name of the company or app you are verifying for. Must not be longer than 18
075     *               characters.
076     * @param from   (optional The Nexmo number to use as the sender for the verification SMS message and calls, in
077     *               <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format.
078     * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use
079     *               -1 to use the default value.
080     * @param locale (optional) Override the default locale used for verification. By default the locale is determined
081     *               from the country code included in {@code number}
082     * @deprecated this construtor is deprecated use {@link Builder} instead
083     */
084    @Deprecated
085    public VerifyRequest(final String number, final String brand, final String from, final int length, final Locale locale) {
086        this(number, brand, from, length, locale, null);
087    }
088
089    /**
090     * Constructor.
091     *
092     * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
093     *               format.
094     * @param brand  (required) The name of the company or app you are verifying for. Must not be longer than 18
095     *               characters.
096     * @param from   (optional A short alphanumeric string to specify the SenderID for SMS sent by Verify. Depending on
097     *               the destination of the phone number you are applying, restrictions may apply. By default, sender_id
098     *               is {@code VERIFY}. Must be 11 characters or fewer.
099     * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use
100     *               -1 to use the default value.
101     * @param locale (optional) Override the default locale used for verification. By default the locale is determined
102     *               from the country code included in {@code number}
103     * @param type   (optional) If provided, restrict the verification to the specified network type. Contact
104     *               support@nexmo.com to enable this feature.
105     */
106    @Deprecated
107    public VerifyRequest(final String number, final String brand, final String from, final int length, final Locale locale, final LineType type) {
108        super(number, length, locale);
109
110        this.type = type;
111        this.brand = brand;
112        this.from = from;
113        this.workflow = null;
114        setCountry(null);
115        setPinExpiry(null);
116        setNextEventWait(null);
117    }
118
119    public VerifyRequest(Builder builder) {
120        super(builder.number, builder.length, builder.locale, builder.country, builder.pinExpiry, builder.nextEventWait);
121        brand = builder.brand;
122        from = builder.senderId;
123        type = builder.type;
124        workflow = builder.workflow;
125    }
126
127    /**
128     * @return the name of the company or app to be verified for.
129     */
130    public String getBrand() {
131        return this.brand;
132    }
133
134
135    /**
136     * @return the type of network the verification will be restricted to. This value has no effect unless it has been
137     * enabled by contacting {@code support@nexmo.com}.
138     */
139    public LineType getType() {
140        return type;
141    }
142
143
144    /**
145     * @param type the type of network the verification will be restricted to. This value has no effect unless it has been
146     *        enabled by contacting {@code support@nexmo.com}.
147     * @deprecated since 5.5.0 use {@link VerifyRequest.Builder} to create a 2FA verification request
148     * @see Builder#type(LineType)
149     */
150    public void setType(LineType type) {
151        this.type = type;
152    }
153
154
155    /**
156     * @return the short alphanumeric string to specify the SenderID for SMS sent by Verify, or {@code null} if one was
157     * not provided. This value is specified in some {@link BaseRequest}  sub-class constructors.
158     * <p>
159     * If this value is {@code null</tt>, the sender_id used will be <tt>VERIFY}.
160     */
161    public String getFrom() {
162        return from;
163    }
164
165    /**
166     * @param from the short alphanumeric string to specify the SenderID for SMS sent by Verify.
167     * @deprecated since 5.5.0 use {@link VerifyRequest.Builder} to create a 2FA verification request
168     * @see VerifyRequest.Builder#senderId(String)
169     */
170    public void setFrom(String from) {
171        this.from = from;
172    }
173
174    /**
175     * Types of phone line to be specified for {@link VerifyRequest#type}. This option is not generally available. It will
176     * cause an error to be returned if your account doesn't have access to use this option.
177     */
178    public enum LineType {
179        ALL, MOBILE, LANDLINE,
180    }
181
182    /**
183     * @return The predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your
184     * user.
185     */
186    public Workflow getWorkflow() {
187        return workflow;
188    }
189
190    /**
191     * @param workflow The workflow to use for conveying the PIN to your user.
192     * @deprecated since 5.5.0 use {@link VerifyRequest.Builder} to create a 2FA verification request
193     * @see Builder#workflow(Workflow)
194     */
195    public void setWorkflow(Workflow workflow) {
196        this.workflow = workflow;
197    }
198
199    /**
200     * Enumeration representing different verification workflows.
201     * <p>
202     * See: https://developer.nexmo.com/verify/guides/workflows-and-events for more details.
203     */
204    public enum Workflow {
205        /**
206         * The default workflow.
207         */
208        SMS_TTS_TTS(1),
209        SMS_SMS_TTS(2),
210        TTS_TTS(3),
211        SMS_SMS(4),
212        SMS_TTS(5),
213        SMS(6),
214        TTS(7);
215
216        private final int id;
217
218        Workflow(int id) {
219            this.id = id;
220        }
221
222        @JsonValue
223        public int getId() {
224            return id;
225        }
226    }
227
228    @Override
229    public String toString() {
230        return "VerifyRequest{" +
231                super.toString() +
232                ", type=" + type +
233                ", brand='" + brand + '\'' +
234                ", workflow=" + workflow +
235                '}';
236    }
237
238    /**
239     * @return A new Builder to start building.
240     */
241    public static Builder builder(String number, String brand) {
242        return new Builder(number, brand);
243    }
244
245    /**
246     * Builder to create a Two Factor Authentication request
247     * @since 5.5.0
248     */
249    public static class Builder {
250
251        private String brand;
252        private String senderId;
253        private LineType type;
254        private Workflow workflow;
255        private String number;
256        private Locale locale;
257        private Integer length;
258        private Integer pinExpiry;
259        private Integer nextEventWait;
260        private String country;
261
262        /**
263         * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
264         *               format.
265         * @param brand  (required) The name of the company or app to be verified for. Must not be longer than 18
266         *               characters.
267         */
268        public Builder(String number, String brand) {
269            this.number = number;
270            this.brand = brand;
271        }
272
273        /**
274         * @param senderId the short alphanumeric string to specify the SenderID for SMS sent by Verify.
275         * @return {@link Builder}
276         *
277         */
278        public Builder senderId(String senderId) {
279            this.senderId = senderId;
280            return this;
281        }
282
283        /**
284         * @param type the type of network the verification will be restricted to. This value has no effect unless it has been
285         *        enabled by contacting {@code support@nexmo.com}.
286         * @return {@link Builder}
287         **/
288        public Builder type(LineType type) {
289            this.type = type;
290            return this;
291        }
292
293        /**
294         * Set the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your
295         * user. See https://developer.nexmo.com/verify/guides/workflows-and-events
296         *
297         * @param workflow The workflow to use for conveying the PIN to your user.
298         * @return {@link Builder}
299         */
300        public Builder workflow(Workflow workflow) {
301            this.workflow = workflow;
302            return this;
303        }
304
305        /**
306         * @param locale (optional) Override the default locale used for verification. By default the locale is determined
307         *        from the country code included in {@code number}
308         * @return {@link Builder}
309         */
310        public Builder locale(Locale locale) {
311            this.locale = locale;
312            return this;
313        }
314
315        /**
316         * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use
317         *               -1 to use the default value.
318         * @return {@link Builder}
319         */
320        public Builder length(Integer length) {
321            this.length = length;
322            return this;
323        }
324
325        /**
326         * @param pinExpiry (optional) the PIN validity time from generation, in seconds. Default is 300 seconds
327         * @return {@link Builder}
328         */
329        public Builder pinExpiry(Integer pinExpiry) {
330            this.pinExpiry = pinExpiry;
331            return this;
332        }
333
334        /**
335         * @param nextEventWait (optional) the wait time between attempts to deliver the PIN. A number between 600-900.
336         * @return {@link Builder}
337         */
338        public Builder nextEventWait(Integer nextEventWait) {
339            this.nextEventWait = nextEventWait;
340            return this;
341        }
342
343        /**
344         * The country for the destination phone number.
345         * <p>
346         * If you wish to used localised number formats or you are not sure if number is correctly formatted, set this to a
347         * two-character country code. For example, GB, US. Verify will work out the international phone number for you.
348         * </p>
349         *
350         * @param country  a String containing a 2-character country code
351         * @return {@link Builder}
352         */
353        public Builder country(String country) {
354            this.country = country;
355            return this;
356        }
357
358        public VerifyRequest build() {
359            return new VerifyRequest(this);
360        }
361    }
362}