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.numbers;
017
018
019import com.vonage.client.HttpWrapper;
020import com.vonage.client.VonageClientException;
021import com.vonage.client.VonageResponseParseException;
022
023/**
024 * A client for accessing the Vonage API calls that manage phone numbers.
025 */
026public class NumbersClient {
027    private ListNumbersEndpoint listNumbers;
028    private SearchNumbersEndpoint searchNumbers;
029    private CancelNumberEndpoint cancelNumber;
030    private BuyNumberEndpoint buyNumber;
031    private UpdateNumberEndpoint updateNumber;
032
033    public NumbersClient(HttpWrapper httpWrapper) {
034        this.listNumbers = new ListNumbersEndpoint(httpWrapper);
035        this.searchNumbers = new SearchNumbersEndpoint(httpWrapper);
036        this.cancelNumber = new CancelNumberEndpoint(httpWrapper);
037        this.buyNumber = new BuyNumberEndpoint(httpWrapper);
038        this.updateNumber = new UpdateNumberEndpoint(httpWrapper);
039    }
040
041    /**
042     * Get the first page of phone numbers assigned to the authenticated account.
043     *
044     * @return A ListNumbersResponse containing the first 10 phone numbers
045     *
046     * @throws VonageResponseParseException if the response from the API could not be parsed.
047     * @throws VonageClientException        if an error is returned by the server.
048     */
049    public ListNumbersResponse listNumbers() throws VonageResponseParseException, VonageClientException {
050        return this.listNumbers.listNumbers(new ListNumbersFilter());
051    }
052
053    /**
054     * Get a filtered set of numbers assigned to the authenticated account.
055     *
056     * @param filter A ListNumbersFilter describing the filters to be applied to the request.
057     *
058     * @return A ListNumbersResponse containing phone numbers matching the supplied filter.
059     *
060     * @throws VonageResponseParseException if the response from the API could not be parsed.
061     * @throws VonageClientException        if an error is returned by the server.
062     */
063    public ListNumbersResponse listNumbers(ListNumbersFilter filter) throws VonageResponseParseException, VonageClientException {
064        return this.listNumbers.listNumbers(filter);
065    }
066
067
068    /**
069     * Search for available Vonage Virtual Numbers.
070     *
071     * @throws VonageResponseParseException if the response from the API could not be parsed.
072     * @throws VonageClientException        if an error is returned by the server.
073     */
074    public SearchNumbersResponse searchNumbers(String country) throws VonageResponseParseException, VonageClientException {
075        return this.searchNumbers(new SearchNumbersFilter(country));
076    }
077
078    /**
079     * Search for available Vonage Virtual Numbers.
080     *
081     * @throws VonageResponseParseException if the response from the API could not be parsed.
082     * @throws VonageClientException        if an error is returned by the server.
083     */
084    public SearchNumbersResponse searchNumbers(SearchNumbersFilter filter) throws VonageResponseParseException, VonageClientException {
085        return this.searchNumbers.searchNumbers(filter);
086    }
087
088    /**
089     * Start renting a Vonage Virtual Number.
090     *
091     * @param country A String containing a 2-character ISO country code.
092     * @param msisdn  The phone number to be bought.
093     *
094     * @throws VonageResponseParseException if the response from the API could not be parsed.
095     * @throws VonageClientException        if an error is returned by the server.
096     */
097    public void buyNumber(String country, String msisdn) throws VonageResponseParseException, VonageClientException {
098        this.buyNumber.execute(new BuyNumberRequest(country, msisdn));
099    }
100
101    /**
102     * Stop renting a Vonage Virtual Number.
103     *
104     * @param country A String containing a 2-character ISO country code.
105     * @param msisdn  The phone number to be cancelled.
106     *
107     * @throws VonageResponseParseException if the response from the API could not be parsed.
108     * @throws VonageClientException        if an error is returned by the server.
109     */
110    public void cancelNumber(String country, String msisdn) throws VonageResponseParseException, VonageClientException {
111        this.cancelNumber.execute(new CancelNumberRequest(country, msisdn));
112    }
113
114    /**
115     * Update the callbacks and/or application associations for a given Vonage Virtual Number.
116     *
117     * @param request Details of the updates to be made to the number association.
118     *
119     * @throws VonageResponseParseException if the response from the API could not be parsed.
120     * @throws VonageClientException        if an error is returned by the server.
121     */
122    public void updateNumber(UpdateNumberRequest request) throws VonageResponseParseException, VonageClientException {
123        this.updateNumber.execute(request);
124    }
125
126    /**
127     * Link a given Vonage Virtual Number to a Vonage Application with the given ID.
128     *
129     * @param msisdn  The Vonage Virtual Number to be updated.
130     * @param country The country for the given msisdn.
131     * @param appId   The ID for the Vonage Application to be associated with the number.
132     *
133     * @throws VonageResponseParseException if the response from the API could not be parsed.
134     * @throws VonageClientException        if an error is returned by the server.
135     */
136    public void linkNumber(String msisdn, String country, String appId) throws VonageResponseParseException, VonageClientException {
137        UpdateNumberRequest request = new UpdateNumberRequest(msisdn, country);
138        request.setVoiceCallbackType(UpdateNumberRequest.CallbackType.APP);
139        request.setVoiceCallbackValue(appId);
140        this.updateNumber(request);
141    }
142}