001/*
002 *   Copyright 2024 Vonage
003 *
004 *   Licensed under the Apache License, Version 2.0 (the "License");
005 *   you may not use this file except in compliance with the License.
006 *   You may obtain a copy of the License at
007 *
008 *        http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *   Unless required by applicable law or agreed to in writing, software
011 *   distributed under the License is distributed on an "AS IS" BASIS,
012 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *   See the License for the specific language governing permissions and
014 *   limitations under the License.
015 */
016package com.vonage.client.verify;
017
018import com.fasterxml.jackson.annotation.JsonValue;
019import java.util.Locale;
020import java.util.Map;
021
022/**
023 * Describes a Verify request.
024 */
025public class VerifyRequest extends BaseRequest {
026    private final String brand, from, pinCode;
027    private final Workflow workflow;
028
029    public VerifyRequest(Builder builder) {
030        super(builder.number, builder.length, builder.locale, builder.country, builder.pinExpiry, builder.nextEventWait);
031        if ((brand = builder.brand) != null && brand.length() > 18) {
032            throw new IllegalArgumentException("Brand '"+brand+"' is longer than 18 characters.");
033        }
034        if ((pinCode = builder.pinCode) != null && (pinCode.length() < 4 || pinCode.length() > 10)) {
035            throw new IllegalArgumentException("Pin code must be between 4 and 10 characters.");
036        }
037        from = builder.senderId;
038        workflow = builder.workflow;
039    }
040
041    /**
042     * @return The name of the company or app to be verified for.
043     */
044    public String getBrand() {
045        return this.brand;
046    }
047
048    /**
049     * @return the short alphanumeric string to specify the SenderID for SMS sent by Verify, or {@code null} if one was
050     * not provided. This value is specified in some {@link BaseRequest}  sub-class constructors.
051     * <p>
052     * If this value is {@code null</tt>, the sender_id used will be <tt>VERIFY}.
053     */
054    public String getFrom() {
055        return from;
056    }
057
058    /**
059     * @return The predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your
060     * user.
061     */
062    public Workflow getWorkflow() {
063        return workflow;
064    }
065
066    /**
067     * A custom PIN to send to the user. If a PIN is not provided, Verify will generate a random PIN for you.
068     * This feature is not enabled by default - please discuss with your Account Manager if you would like it enabled.
069     *
070     * @return The custom pin code as a string, or {@code null} if not set.
071     *
072     * @since 7.5.0
073     */
074    public String getPinCode() {
075        return pinCode;
076    }
077
078    @Override
079    public Map<String, String> makeParams() {
080        Map<String, String> params = super.makeParams();
081        if (brand != null) {
082            params.put("brand", brand);
083        }
084        if (from != null) {
085            params.put("sender_id", from);
086        }
087        if (pinCode != null) {
088            params.put("pin_code", pinCode);
089        }
090        if (workflow != null) {
091            params.put("workflow_id", String.valueOf(workflow.id));
092        }
093        return params;
094    }
095
096    /**
097     * Enumeration representing different verification workflows.
098     * <p>
099     * See: <a href="https://developer.nexmo.com/verify/guides/workflows-and-events">https://developer.nexmo.com/verify/guides/workflows-and-events</a> for more details.
100     */
101    public enum Workflow {
102        /**
103         * The default workflow.
104         */
105        SMS_TTS_TTS(1),
106        SMS_SMS_TTS(2),
107        TTS_TTS(3),
108        SMS_SMS(4),
109        SMS_TTS(5),
110        SMS(6),
111        TTS(7);
112
113        private final int id;
114
115        Workflow(int id) {
116            this.id = id;
117        }
118
119        @JsonValue
120        public int getId() {
121            return id;
122        }
123    }
124
125    @Override
126    public String toString() {
127        return "VerifyRequest{" +
128                super.toString() +
129                ", brand='" + brand + '\'' +
130                ", workflow=" + workflow +
131                '}';
132    }
133
134    /**
135     * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
136     *        format.
137     * @param brand  (required) The name of the company or app to be verified for. Must not be longer than 18
138     *        characters.
139     * @return A new Builder to start building.
140     */
141    public static Builder builder(String number, String brand) {
142        return new Builder(number, brand);
143    }
144
145    /**
146     * Builder to create a Two Factor Authentication request
147     * @since 5.5.0
148     */
149    public static class Builder {
150        private String brand, senderId, number, country, pinCode;
151        private Integer length, pinExpiry, nextEventWait;
152        private Workflow workflow;
153        private Locale locale;
154
155        /**
156         * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
157         *               format.
158         * @param brand  (required) The name of the company or app to be verified for. Must not be longer than 18
159         *               characters.
160         */
161        public Builder(String number, String brand) {
162            this.number = number;
163            this.brand = brand;
164        }
165
166        /**
167         * @param senderId the short alphanumeric string to specify the SenderID for SMS sent by Verify.
168         *
169         * @return This builder.
170         */
171        public Builder senderId(String senderId) {
172            this.senderId = senderId;
173            return this;
174        }
175
176        /**
177         * Set the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your
178         * user. See <a href="https://developer.vonage.com/verify/guides/workflows-and-events">https://developer.vonage.com/verify/guides/workflows-and-events</a>
179         *
180         * @param workflow The workflow to use for conveying the PIN to your user.
181         * @return This builder.
182         */
183        public Builder workflow(Workflow workflow) {
184            this.workflow = workflow;
185            return this;
186        }
187
188        /**
189         * @param locale (optional) Override the default locale used for verification. By default the locale is determined
190         *        from the country code included in {@code number}
191         * @return This builder.
192         */
193        public Builder locale(Locale locale) {
194            this.locale = locale;
195            return this;
196        }
197
198        /**
199         * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use
200         *               -1 to use the default value.
201         * @return This builder.
202         */
203        public Builder length(Integer length) {
204            this.length = length;
205            return this;
206        }
207
208        /**
209         * @param pinExpiry (optional) the PIN validity time from generation, in seconds. Default is 300 seconds
210         * @return This builder.
211         */
212        public Builder pinExpiry(Integer pinExpiry) {
213            this.pinExpiry = pinExpiry;
214            return this;
215        }
216
217        /**
218         * @param nextEventWait (optional) the wait time between attempts to deliver the PIN. A number between 600-900.
219         * @return This builder.
220         */
221        public Builder nextEventWait(Integer nextEventWait) {
222            this.nextEventWait = nextEventWait;
223            return this;
224        }
225
226        /**
227         * The country for the destination phone number.
228         * <p>
229         * If you wish to used localised number formats or you are not sure if number is correctly formatted, set this to a
230         * two-character country code. For example, GB, US. Verify will work out the international phone number for you.
231         * </p>
232         *
233         * @param country  a String containing a 2-character country code
234         * @return This builder.
235         */
236        public Builder country(String country) {
237            this.country = country;
238            return this;
239        }
240
241        /**
242         * A custom PIN to send to the user. If a PIN is not provided, Verify will generate a random PIN for you. This
243         * feature is not enabled by default - please discuss with your Account Manager if you would like it enabled.
244         *
245         * @param pinCode The custom code as a string.
246         *
247         * @return This builder.
248         * @since 7.5.0
249         */
250        public Builder pinCode(String pinCode) {
251            this.pinCode = pinCode;
252            return this;
253        }
254
255        /**
256         * Builds the VerifyRequest.
257         *
258         * @return A new VerifyRequest with this builder's properties.
259         */
260        public VerifyRequest build() {
261            return new VerifyRequest(this);
262        }
263    }
264}