001/*
002 *   Copyright 2020 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
018
019import com.vonage.client.*;
020
021/**
022 * A client for talking to the Vonage Number Insight API. The standard way to obtain an instance of this class is to use
023 * {@link VonageClient#getInsightClient()}.
024 */
025public class InsightClient extends AbstractClient {
026    protected BasicInsightEndpoint basic;
027    protected StandardInsightEndpoint standard;
028    protected AdvancedInsightEndpoint advanced;
029
030    /**
031     * Constructor.
032     *
033     * @param httpWrapper (required) shared HTTP wrapper object used for making REST calls.
034     */
035    public InsightClient(HttpWrapper httpWrapper) {
036        super(httpWrapper);
037
038        this.basic = new BasicInsightEndpoint(httpWrapper);
039        this.standard = new StandardInsightEndpoint(httpWrapper);
040        this.advanced = new AdvancedInsightEndpoint(httpWrapper);
041    }
042
043    /**
044     * Perform a Basic Insight Request with a number.
045     *
046     * @param number A single phone number that you need insight about in national or international format.
047     *
048     * @return A {@link BasicInsightResponse} representing the response from the Vonage Number Insight API.
049     *
050     * @throws VonageResponseParseException if the response from the API could not be parsed.
051     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
052     */
053    public BasicInsightResponse getBasicNumberInsight(String number) throws VonageResponseParseException, VonageClientException {
054        return getBasicNumberInsight(BasicInsightRequest.withNumber(number));
055    }
056
057    /**
058     * Perform a Basic Insight Request with a number and country.
059     *
060     * @param number  A single phone number that you need insight about in national or international format
061     * @param country If a number does not have a country code or it is uncertain, set the two-character country code.
062     *
063     * @return A {@link BasicInsightResponse} representing the response from the Vonage Number Insight API.
064     *
065     * @throws VonageResponseParseException if the response from the API could not be parsed.
066     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
067     */
068    public BasicInsightResponse getBasicNumberInsight(String number, String country) throws VonageResponseParseException, VonageClientException {
069        return getBasicNumberInsight(BasicInsightRequest.withNumberAndCountry(number, country));
070    }
071
072    /**
073     * Perform a Basic Insight Request with a {@link BasicInsightRequest}.
074     *
075     * @param basicInsightRequest A request object containing the details of the request to make.
076     *
077     * @return A {@link BasicInsightResponse} representing the response from the Vonage Number Insight API.
078     *
079     * @throws VonageResponseParseException if the response from the API could not be parsed.
080     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
081     */
082    public BasicInsightResponse getBasicNumberInsight(BasicInsightRequest basicInsightRequest) throws VonageResponseParseException, VonageClientException {
083        return this.basic.execute(basicInsightRequest);
084    }
085
086    /**
087     * Perform a Standard Insight Request with a number.
088     *
089     * @param number A single phone number that you need insight about in national or international format.
090     *
091     * @return A {@link StandardInsightResponse} representing the response from the Vonage Number Insight API.
092     *
093     * @throws VonageResponseParseException if the response from the API could not be parsed.
094     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
095     */
096    public StandardInsightResponse getStandardNumberInsight(String number) throws VonageResponseParseException, VonageClientException {
097        return getStandardNumberInsight(StandardInsightRequest.withNumber(number));
098    }
099
100    /**
101     * Perform a Standard Insight Request with a number and country.
102     *
103     * @param number  A single phone number that you need insight about in national or international format.
104     * @param country If a number does not have a country code or it is uncertain, set the two-character country code.
105     *
106     * @return A {@link StandardInsightResponse} representing the response from the Vonage Number Insight API.
107     *
108     * @throws VonageResponseParseException if the response from the API could not be parsed.
109     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
110     */
111    public StandardInsightResponse getStandardNumberInsight(String number, String country) throws VonageResponseParseException, VonageClientException {
112        return getStandardNumberInsight(StandardInsightRequest.withNumberAndCountry(number, country));
113    }
114
115    /**
116     * Perform a Standard Insight Request with a number, country, and cnam.
117     *
118     * @param number  A single phone number that you need insight about in national or international format.
119     * @param country If a number does not have a country code or it is uncertain, set the two-character country code.
120     * @param cnam    Indicates if the name of the person who owns the phone number should also be looked up and
121     *                returned. Set to true to receive phone number owner name in the response. This is only available
122     *                for US numbers and incurs an additional charge.
123     *
124     * @return A {@link StandardInsightResponse} representing the response from the Vonage Number Insight API.
125     *
126     * @throws VonageResponseParseException if the response from the API could not be parsed.
127     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
128     * @deprecated Create a {@link StandardInsightRequest} and use {@link InsightClient#getStandardNumberInsight(StandardInsightRequest)}
129     */
130    @Deprecated
131    public StandardInsightResponse getStandardNumberInsight(String number, String country, boolean cnam) throws VonageResponseParseException, VonageClientException {
132        return getStandardNumberInsight(StandardInsightRequest.builder(number).country(country).cnam(cnam).build());
133    }
134
135    /**
136     * Perform a Standard Insight Request with a {@link StandardInsightRequest}.
137     *
138     * @param standardInsightRequest A request object containing the details of the request to make.
139     *
140     * @return A {@link StandardInsightResponse} representing the response from the Vonage Number Insight API.
141     *
142     * @throws VonageResponseParseException if the response from the API could not be parsed.
143     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
144     */
145    public StandardInsightResponse getStandardNumberInsight(StandardInsightRequest standardInsightRequest) throws VonageResponseParseException, VonageClientException {
146        return this.standard.execute(standardInsightRequest);
147    }
148
149    /**
150     * Perform an Advanced Insight Request with a number.
151     *
152     * @param number A single phone number that you need insight about in national or international format.
153     *
154     * @return A {@link AdvancedInsightResponse} representing the response from the Vonage Number Insight API.
155     *
156     * @throws VonageResponseParseException if the response from the API could not be parsed.
157     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
158     */
159    public AdvancedInsightResponse getAdvancedNumberInsight(String number) throws VonageResponseParseException, VonageClientException {
160        return getAdvancedNumberInsight(AdvancedInsightRequest.withNumber(number));
161    }
162
163    /**
164     * Perform an Advanced Insight Request with a number and country.
165     *
166     * @param number  A single phone number that you need insight about in national or international format.
167     * @param country If a number does not have a country code or it is uncertain, set the two-character country code.
168     *
169     * @return A {@link AdvancedInsightResponse} representing the response from the Vonage Number Insight API.
170     *
171     * @throws VonageResponseParseException if the response from the API could not be parsed.
172     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
173     */
174    public AdvancedInsightResponse getAdvancedNumberInsight(String number, String country) throws VonageResponseParseException, VonageClientException {
175        return getAdvancedNumberInsight(AdvancedInsightRequest.withNumberAndCountry(number, country));
176    }
177
178    /**
179     * Perform an Advanced Insight Request with a number, country, and ipAddress.
180     *
181     * @param number    A single phone number that you need insight about in national or international format.
182     * @param country   If a number does not have a country code or it is uncertain, set the two-character country
183     *                  code.
184     * @param ipAddress The IP address of the user. If supplied, we will compare this to the country the user's phone is
185     *                  located in and return an error if it does not match.
186     *
187     * @return A {@link AdvancedInsightResponse} representing the response from the Vonage Number Insight API.
188     *
189     * @throws VonageResponseParseException if the response from the API could not be parsed.
190     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
191     * @deprecated Create a {@link AdvancedInsightRequest} and use {@link InsightClient#getAdvancedNumberInsight(AdvancedInsightRequest)}
192     */
193    @Deprecated
194    public AdvancedInsightResponse getAdvancedNumberInsight(String number, String country, String ipAddress) throws VonageResponseParseException, VonageClientException {
195        return getAdvancedNumberInsight(AdvancedInsightRequest.builder(number)
196                .country(country)
197                .ipAddress(ipAddress)
198                .build());
199    }
200
201    /**
202     * Perform an Advanced Insight Request with a number, country, ipAddress, and cnam.
203     *
204     * @param number    A single phone number that you need insight about in national or international format.
205     * @param country   If a number does not have a country code or it is uncertain, set the two-character country
206     *                  code.
207     * @param ipAddress The IP address of the user. If supplied, we will compare this to the country the user's phone is
208     *                  located in and return an error if it does not match.
209     * @param cnam      Indicates if the name of the person who owns the phone number should also be looked up and
210     *                  returned. Set to true to receive phone number owner name in the response. This is only available
211     *                  for US numbers and incurs an additional charge.
212     *
213     * @return A {@link AdvancedInsightResponse} representing the response from the Vonage Number Insight API.
214     *
215     * @throws VonageResponseParseException if the response from the API could not be parsed.
216     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
217     * @deprecated Create a {@link AdvancedInsightRequest} and use {@link InsightClient#getAdvancedNumberInsight(AdvancedInsightRequest)}
218     */
219    @Deprecated
220    public AdvancedInsightResponse getAdvancedNumberInsight(String number, String country, String ipAddress, boolean cnam) throws VonageResponseParseException, VonageClientException {
221        return getAdvancedNumberInsight(AdvancedInsightRequest.builder(number)
222                .country(country)
223                .ipAddress(ipAddress)
224                .cnam(cnam)
225                .build());
226    }
227
228    /**
229     * Perform an Advanced Insight Request with a {@link AdvancedInsightRequest}.
230     *
231     * @param advancedInsightRequest A request object containing the details of the request to make.
232     *
233     * @return A {@link AdvancedInsightResponse} representing the response from the Vonage Number Insight API.
234     *
235     * @throws VonageResponseParseException if the response from the API could not be parsed.
236     * @throws VonageClientException        if there was a problem with the Vonage request or response objects.
237     */
238    public AdvancedInsightResponse getAdvancedNumberInsight(AdvancedInsightRequest advancedInsightRequest) throws VonageResponseParseException, VonageClientException {
239        return this.advanced.execute(advancedInsightRequest);
240    }
241}