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.insight;
017
018import com.vonage.client.*;
019import com.vonage.client.auth.ApiKeyHeaderAuthMethod;
020import com.vonage.client.auth.ApiKeyQueryParamsAuthMethod;
021import com.vonage.client.auth.AuthMethod;
022import com.vonage.client.auth.SignatureAuthMethod;
023import com.vonage.client.common.HttpMethod;
024import java.util.function.Function;
025
026/**
027 * A client for talking to the Vonage Number Insight API. The standard way to obtain an instance of this class is to use
028 * {@link VonageClient#getInsightClient()}.
029 */
030public class InsightClient {
031    final RestEndpoint<BasicInsightRequest, BasicInsightResponse> basic;
032    final RestEndpoint<StandardInsightRequest, StandardInsightResponse> standard;
033    final RestEndpoint<AdvancedInsightRequest, AdvancedInsightResponse> advanced;
034
035    /**
036     * Constructor.
037     *
038     * @param wrapper (REQUIRED) shared HTTP wrapper object used for making REST calls.
039     */
040    public InsightClient(HttpWrapper wrapper) {
041        @SuppressWarnings("unchecked")
042        final class Endpoint<T, R> extends DynamicEndpoint<T, R> {
043            Endpoint(Function<T, String> pathGetter, Class<? extends AuthMethod> auth, R... type) {
044                super(DynamicEndpoint.<T, R> builder(type)
045                        .wrapper(wrapper).requestMethod(HttpMethod.POST)
046                        .authMethod(SignatureAuthMethod.class, auth)
047                        .pathGetter((de, req) -> {
048                            String base = de.getHttpWrapper().getHttpConfig().getApiBaseUri();
049                            return base + "/ni/" + pathGetter.apply(req) + "/json";
050                        })
051                );
052            }
053        }
054
055        basic = new Endpoint<>(req -> "basic", ApiKeyHeaderAuthMethod.class);
056        standard = new Endpoint<>(req -> "standard", ApiKeyQueryParamsAuthMethod.class);
057        advanced = new Endpoint<>(req -> "advanced" + (req.isAsync() ? "/async" : ""), ApiKeyQueryParamsAuthMethod.class);
058    }
059
060    /**
061     * Perform a Basic Insight Request with a number.
062     *
063     * @param number A single phone number that you need insight about in national or international format.
064     *
065     * @return A {@link BasicInsightResponse} representing the response from the Vonage Number Insight API.
066     *
067     * @throws VonageResponseParseException if the response from the API could not be parsed.
068     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
069     */
070    public BasicInsightResponse getBasicNumberInsight(String number) throws VonageResponseParseException, VonageClientException {
071        return getBasicNumberInsight(BasicInsightRequest.withNumber(number));
072    }
073
074    /**
075     * Perform a Basic Insight Request with a number and country.
076     *
077     * @param number  A single phone number that you need insight about in national or international format
078     * @param country If a number does not have a country code or it is uncertain, set the two-character country code.
079     *
080     * @return A {@link BasicInsightResponse} representing the response from the Vonage Number Insight API.
081     *
082     * @throws VonageResponseParseException if the response from the API could not be parsed.
083     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
084     */
085    public BasicInsightResponse getBasicNumberInsight(String number, String country) throws VonageResponseParseException, VonageClientException {
086        return getBasicNumberInsight(BasicInsightRequest.withNumberAndCountry(number, country));
087    }
088
089    /**
090     * Perform a Basic Insight Request with a {@link BasicInsightRequest}.
091     *
092     * @param basicInsightRequest A request object containing the details of the request to make.
093     *
094     * @return A {@link BasicInsightResponse} representing the response from the Vonage Number Insight API.
095     *
096     * @throws VonageResponseParseException if the response from the API could not be parsed.
097     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
098     */
099    public BasicInsightResponse getBasicNumberInsight(BasicInsightRequest basicInsightRequest) throws VonageResponseParseException, VonageClientException {
100        return basic.execute(basicInsightRequest);
101    }
102
103    /**
104     * Perform a Standard Insight Request with a number.
105     *
106     * @param number A single phone number that you need insight about in national or international format.
107     *
108     * @return A {@link StandardInsightResponse} representing the response from the Vonage Number Insight API.
109     *
110     * @throws VonageResponseParseException if the response from the API could not be parsed.
111     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
112     */
113    public StandardInsightResponse getStandardNumberInsight(String number) throws VonageResponseParseException, VonageClientException {
114        return getStandardNumberInsight(StandardInsightRequest.withNumber(number));
115    }
116
117    /**
118     * Perform a Standard Insight Request with a number and country.
119     *
120     * @param number  A single phone number that you need insight about in national or international format.
121     * @param country If a number does not have a country code or it is uncertain, set the two-character country code.
122     *
123     * @return A {@link StandardInsightResponse} representing the response from the Vonage Number Insight API.
124     *
125     * @throws VonageResponseParseException if the response from the API could not be parsed.
126     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
127     */
128    public StandardInsightResponse getStandardNumberInsight(String number, String country) throws VonageResponseParseException, VonageClientException {
129        return getStandardNumberInsight(StandardInsightRequest.withNumberAndCountry(number, country));
130    }
131
132    /**
133     * Perform a Standard Insight Request with a {@link StandardInsightRequest}.
134     *
135     * @param standardInsightRequest A request object containing the details of the request to make.
136     *
137     * @return A {@link StandardInsightResponse} representing the response from the Vonage Number Insight API.
138     *
139     * @throws VonageResponseParseException if the response from the API could not be parsed.
140     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
141     */
142    public StandardInsightResponse getStandardNumberInsight(StandardInsightRequest standardInsightRequest) throws VonageResponseParseException, VonageClientException {
143        return standard.execute(standardInsightRequest);
144    }
145
146    /**
147     * Perform an Advanced Insight Request with a number.
148     *
149     * @param number A single phone number that you need insight about in national or international format.
150     *
151     * @return A {@link AdvancedInsightResponse} representing the response from the Vonage Number Insight API.
152     *
153     * @throws VonageResponseParseException if the response from the API could not be parsed.
154     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
155     */
156    public AdvancedInsightResponse getAdvancedNumberInsight(String number) throws VonageResponseParseException, VonageClientException {
157        return getAdvancedNumberInsight(AdvancedInsightRequest.withNumber(number));
158    }
159
160    /**
161     * Perform an Advanced Insight Request with a number and country.
162     *
163     * @param number  A single phone number that you need insight about in national or international format.
164     * @param country If a number does not have a country code or it is uncertain, set the two-character country code.
165     *
166     * @return A {@link AdvancedInsightResponse} representing the response from the Vonage Number Insight API.
167     *
168     * @throws VonageResponseParseException if the response from the API could not be parsed.
169     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
170     */
171    public AdvancedInsightResponse getAdvancedNumberInsight(String number, String country) throws VonageResponseParseException, VonageClientException {
172        return getAdvancedNumberInsight(AdvancedInsightRequest.withNumberAndCountry(number, country));
173    }
174
175    /**
176     * Perform an Advanced Insight Request with a {@link AdvancedInsightRequest}.
177     *
178     * @param advancedInsightRequest A request object containing the details of the request to make.
179     *
180     * @return A {@link AdvancedInsightResponse} representing the response from the Vonage Number Insight API.
181     *
182     * @throws VonageResponseParseException if the response from the API could not be parsed.
183     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
184     */
185    public AdvancedInsightResponse getAdvancedNumberInsight(AdvancedInsightRequest advancedInsightRequest) throws VonageResponseParseException, VonageClientException {
186        return advanced.execute(advancedInsightRequest);
187    }
188}