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.application.capabilities;
017
018import com.fasterxml.jackson.annotation.JsonProperty;
019import com.vonage.client.common.Webhook;
020
021/**
022 * Voice capability configuration settings.
023 */
024public final class Voice extends Capability {
025    private Region region;
026    private Boolean signedCallbacks;
027    private Integer conversationsTtl, legPersistenceTime;
028
029    private Voice() {
030    }
031
032    private Voice(Builder builder) {
033        super(builder);
034        region = builder.region;
035        signedCallbacks = builder.signedCallbacks;
036        if ((conversationsTtl = builder.conversationsTtl) != null && (conversationsTtl < 0 || conversationsTtl > 744)) {
037            throw new IllegalArgumentException("Conversations TTL cannot be negative.");
038        }
039        if ((legPersistenceTime = builder.legPersistenceTime) != null && (legPersistenceTime < 0 || legPersistenceTime > 31)) {
040            throw new IllegalArgumentException("Leg persistence time must be positive and less than 31 days.");
041        }
042    }
043
044    /**
045     * The region which all inbound, programmable SIP and SIP connect calls will be sent to unless the call is sent
046     * to a regional endpoint, if the call is using a regional endpoint this will override the application setting.
047     *
048     * @return The region to process calls through as an enum, or {@code null} if not specified (the default).
049     *
050     * @since 7.7.0
051     */
052    @JsonProperty("region")
053    public Region getRegion() {
054        return region;
055    }
056
057    /**
058     * Whether to use signed webhooks for this capability. See
059     * <a href=https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks>
060     * the documentation on webhooks</a> for details.
061     *
062     * @return {@code true} if webhooks are signed, or {@code null} if unknown (the default).
063     *
064     * @since 7.7.0
065     */
066    @JsonProperty("signed_callbacks")
067    public Boolean getSignedCallbacks() {
068        return signedCallbacks;
069    }
070
071    /**
072     * The length of time the named conversation will remain active for after creation, in hours. 0 means infinite.
073     *
074     * @return The time-to-live of the named conversation, or {@code null} if unknown / not applicable (the default).
075     *
076     * @since 7.7.0
077     */
078    @JsonProperty("conversations_ttl")
079    public Integer getConversationsTtl() {
080        return conversationsTtl;
081    }
082
083    /**
084     * Persistence duration for conversation legs, in days. Maximum value is 31, default is 7.
085     *
086     * @return The leg persistence time in dats as an integer, or {@code null} if unknown.
087     *
088     * @since 8.12.0
089     */
090    @JsonProperty("leg_persistence_time")
091    public Integer getLegPersistenceTime() {
092        return legPersistenceTime;
093    }
094
095    @Override
096    public Type getType() {
097        return Type.VOICE;
098    }
099
100    /**
101     * Entry point for constructing an instance of this class.
102     *
103     * @return A new Builder.
104     */
105    public static Builder builder() {
106        return new Builder();
107    }
108
109    public static class Builder extends Capability.Builder<Voice, Builder> {
110        private Region region;
111        private Boolean signedCallbacks;
112        private Integer conversationsTtl, legPersistenceTime;
113
114        /**
115         * Selecting a region means all inbound, programmable SIP and SIP connect calls will be sent to the selected
116         * region unless the call is sent to a regional endpoint, if the call is using a regional endpoint this will
117         * override the application setting. This is an optional parameter.
118         *
119         * @param region The region to process calls through as an enum.
120         *
121         * @return This builder.
122         * @since 7.7.0
123         */
124        public Builder region(Region region) {
125            this.region = region;
126            return this;
127        }
128
129        /**
130         * Whether to use signed webhooks. See
131         * <a href=https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks>
132         * the documentation on webhooks</a> for details.
133         *
134         * @param signed {@code true} to use signed webhooks, {@code false} otherwise.
135         *
136         * @return This builder.
137         * @since 7.7.0
138         */
139        public Builder signedCallbacks(boolean signed) {
140            this.signedCallbacks = signed;
141            return this;
142        }
143
144        /**
145         * The length of time named conversations will remain active for after creation, in hours.
146         * 0 means infinite. Maximum value is 744 (i.e. 31 days).
147         *
148         * @param ttl The conversations time-to-live in hours.
149         *
150         * @return This builder.
151         * @since 7.7.0
152         */
153        public Builder conversationsTtl(int ttl) {
154            this.conversationsTtl = ttl;
155            return this;
156        }
157
158        /**
159         * Persistence duration for conversation legs, in days. Maximum value is 31, default is 7.
160         *
161         * @param legPersistenceTime The leg persistence time in days.
162         *
163         * @return This builder.
164         * @since 8.12.0
165         */
166        public Builder legPersistenceTime(int legPersistenceTime) {
167            this.legPersistenceTime = legPersistenceTime;
168            return this;
169        }
170
171        @Override
172        public Builder addWebhook(Webhook.Type type, Webhook webhook) {
173            return super.addWebhook(type, webhook);
174        }
175
176        @Override
177        public Builder removeWebhook(Webhook.Type type) {
178            return super.removeWebhook(type);
179        }
180
181        /**
182         * Builds the Voice object.
183         *
184         * @return A new Voice capability containing the configured properties.
185         */
186        @Override
187        public Voice build() {
188            return new Voice(this);
189        }
190    }
191}