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.verify2;
017
018import com.fasterxml.jackson.annotation.JsonProperty;
019import java.net.URI;
020
021/**
022 * Defines properties for mobile network-based authentication. See the
023 * <a href=https://developer.vonage.com/en/verify/verify-v2/guides/silent-authentication>Silent Auth guide</a>
024 * for an overview of how this works.
025 */
026public final class SilentAuthWorkflow extends AbstractNumberWorkflow {
027        private final Boolean sandbox;
028        private final URI redirectUrl;
029
030        SilentAuthWorkflow(Builder builder) {
031                super(builder);
032                sandbox = builder.sandbox;
033                redirectUrl = builder.redirectUrl != null ? URI.create(builder.redirectUrl) : null;
034        }
035
036        /**
037         * Constructs a new Silent Auth verification workflow.
038         *
039         * @param to The number to registered to the device on the network to authenticate.
040         */
041        public SilentAuthWorkflow(String to) {
042                this(builder(to));
043        }
044
045        /**
046         * Constructs a new Silent Auth verification workflow.
047         *
048         * @param to The number to registered to the device on the network to authenticate.
049         * @param sandbox Whether the Vonage Sandbox should be used (for testing purposes).
050         *
051         * @since 7.10.0
052         */
053        public SilentAuthWorkflow(String to, boolean sandbox) {
054                this(builder(to).sandbox(sandbox));
055        }
056
057        /**
058         * Constructs a new Silent Auth verification workflow.
059         *
060         * @param to The number to registered to the device on the network to authenticate.
061         * @param sandbox Whether the Vonage Sandbox should be used (for testing purposes).
062         * @param redirectUrl Optional final redirect added at the end of the check_url request/response lifecycle.
063         *                    Will contain the request_id and code as a URL fragment after the URL.
064         *
065         * @since 8.0.0
066         */
067        public SilentAuthWorkflow(String to, boolean sandbox, String redirectUrl) {
068                this(builder(to).redirectUrl(redirectUrl).sandbox(sandbox));
069        }
070
071        /**
072         * Optional parameter if using the Vonage Sandbox to test Silent Auth integrations.
073         *
074         * @return Whether the Vonage Sandbox will be used, or {@code null} if not specified (the default).
075         *
076         * @since 7.10.0
077         */
078        @JsonProperty("sandbox")
079        public Boolean getSandbox() {
080                return sandbox;
081        }
082
083        /**
084         * Final redirect after {@link VerificationResponse#getCheckUrl()}. See the documentation for integrations.
085         *
086         * @return The optional {@code redirect_url}, or {@code null} if not set (the default).
087         * @since 8.0.0
088         */
089        @JsonProperty("redirect_url")
090        public URI getRedirectUrl() {
091                return redirectUrl;
092        }
093
094        /**
095         * Entrypoint for constructing an instance of this class.
096         *
097         * @param to (REQUIRED) The number to registered to the device on the network to authenticate.
098         *
099         * @return A new Builder.
100         *
101         * @since 8.2.0
102         */
103        public static Builder builder(String to) {
104                return new Builder(to);
105        }
106
107        /**
108         * Builder for constructing a Silent Authentication workflow.
109         *
110         * @since 8.2.0
111         */
112        public static final class Builder extends AbstractNumberWorkflow.Builder<SilentAuthWorkflow, Builder> {
113                private Boolean sandbox;
114                private String redirectUrl;
115
116                private Builder(String to) {
117                        super(Channel.SILENT_AUTH, to);
118                }
119
120                /**
121                 * (OPTIONAL) Whether the Vonage Sandbox should be used (for testing purposes).
122                 *
123                 * @param sandbox {@code true} to use the Vonage sandbox.
124                 *
125                 * @return This builder.
126                 */
127                public Builder sandbox(boolean sandbox) {
128                        this.sandbox = sandbox;
129                        return this;
130                }
131
132                /**
133                 * (OPTIONAL) Final redirect after {@link VerificationResponse#getCheckUrl()}.
134                 * See the documentation for integrations.
135                 *
136                 * @param redirectUrl The full redirect URL as a string.
137                 *
138                 * @return This builder.
139                 */
140                public Builder redirectUrl(String redirectUrl) {
141                        this.redirectUrl = redirectUrl;
142                        return this;
143                }
144
145                @Override
146                public SilentAuthWorkflow build() {
147                        return new SilentAuthWorkflow(this);
148                }
149        }
150}