001/*
002 * Copyright (c) 2011-2017 Nexmo Inc
003 *
004 * Permission is hereby granted, free of charge, to any person obtaining a copy
005 * of this software and associated documentation files (the "Software"), to deal
006 * in the Software without restriction, including without limitation the rights
007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
008 * copies of the Software, and to permit persons to whom the Software is
009 * furnished to do so, subject to the following conditions:
010 *
011 * The above copyright notice and this permission notice shall be included in
012 * all copies or substantial portions of the Software.
013 *
014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
020 * THE SOFTWARE.
021 */
022package com.nexmo.client.numbers;
023
024
025import com.nexmo.client.HttpWrapper;
026import com.nexmo.client.NexmoClientException;
027import com.nexmo.client.NexmoResponseParseException;
028
029/**
030 * A client for accessing the Nexmo API calls that manage phone numbers.
031 */
032public class NumbersClient {
033    private ListNumbersEndpoint listNumbers;
034    private SearchNumbersEndpoint searchNumbers;
035    private CancelNumberEndpoint cancelNumber;
036    private BuyNumberEndpoint buyNumber;
037    private UpdateNumberEndpoint updateNumber;
038
039    public NumbersClient(HttpWrapper httpWrapper) {
040        this.listNumbers = new ListNumbersEndpoint(httpWrapper);
041        this.searchNumbers = new SearchNumbersEndpoint(httpWrapper);
042        this.cancelNumber = new CancelNumberEndpoint(httpWrapper);
043        this.buyNumber = new BuyNumberEndpoint(httpWrapper);
044        this.updateNumber = new UpdateNumberEndpoint(httpWrapper);
045    }
046
047    /**
048     * Get the first page of phone numbers assigned to the authenticated account.
049     *
050     * @return A ListNumbersResponse containing the first 10 phone numbers
051     *
052     * @throws NexmoResponseParseException if the response from the API could not be parsed.
053     * @throws NexmoClientException        if an error is returned by the server.
054     */
055    public ListNumbersResponse listNumbers() throws NexmoResponseParseException, NexmoClientException {
056        return this.listNumbers.listNumbers(new ListNumbersFilter());
057    }
058
059    /**
060     * Get a filtered set of numbers assigned to the authenticated account.
061     *
062     * @param filter A ListNumbersFilter describing the filters to be applied to the request.
063     *
064     * @return A ListNumbersResponse containing phone numbers matching the supplied filter.
065     *
066     * @throws NexmoResponseParseException if the response from the API could not be parsed.
067     * @throws NexmoClientException        if an error is returned by the server.
068     */
069    public ListNumbersResponse listNumbers(ListNumbersFilter filter) throws NexmoResponseParseException, NexmoClientException {
070        return this.listNumbers.listNumbers(filter);
071    }
072
073
074    /**
075     * Search for available Nexmo Virtual Numbers.
076     *
077     * @throws NexmoResponseParseException if the response from the API could not be parsed.
078     * @throws NexmoClientException        if an error is returned by the server.
079     */
080    public SearchNumbersResponse searchNumbers(String country) throws NexmoResponseParseException, NexmoClientException {
081        return this.searchNumbers(new SearchNumbersFilter(country));
082    }
083
084    /**
085     * Search for available Nexmo Virtual Numbers.
086     *
087     * @throws NexmoResponseParseException if the response from the API could not be parsed.
088     * @throws NexmoClientException        if an error is returned by the server.
089     */
090    public SearchNumbersResponse searchNumbers(SearchNumbersFilter filter) throws NexmoResponseParseException, NexmoClientException {
091        return this.searchNumbers.searchNumbers(filter);
092    }
093
094    /**
095     * Start renting a Nexmo Virtual Number.
096     *
097     * @param country A String containing a 2-character ISO country code.
098     * @param msisdn  The phone number to be bought.
099     *
100     * @throws NexmoResponseParseException if the response from the API could not be parsed.
101     * @throws NexmoClientException        if an error is returned by the server.
102     */
103    public void buyNumber(String country, String msisdn) throws NexmoResponseParseException, NexmoClientException {
104        this.buyNumber.execute(new BuyNumberRequest(country, msisdn));
105    }
106
107    /**
108     * Stop renting a Nexmo Virtual Number.
109     *
110     * @param country A String containing a 2-character ISO country code.
111     * @param msisdn  The phone number to be cancelled.
112     *
113     * @throws NexmoResponseParseException if the response from the API could not be parsed.
114     * @throws NexmoClientException        if an error is returned by the server.
115     */
116    public void cancelNumber(String country, String msisdn) throws NexmoResponseParseException, NexmoClientException {
117        this.cancelNumber.execute(new CancelNumberRequest(country, msisdn));
118    }
119
120    /**
121     * Update the callbacks and/or application associations for a given Nexmo Virtual Number.
122     *
123     * @param request Details of the updates to be made to the number association.
124     *
125     * @throws NexmoResponseParseException if the response from the API could not be parsed.
126     * @throws NexmoClientException        if an error is returned by the server.
127     */
128    public void updateNumber(UpdateNumberRequest request) throws NexmoResponseParseException, NexmoClientException {
129        this.updateNumber.execute(request);
130    }
131
132    /**
133     * Link a given Nexmo Virtual Number to a Nexmo Application with the given ID.
134     *
135     * @param msisdn  The Nexmo Virtual Number to be updated.
136     * @param country The country for the given msisdn.
137     * @param appId   The ID for the Nexmo Application to be associated with the number.
138     *
139     * @throws NexmoResponseParseException if the response from the API could not be parsed.
140     * @throws NexmoClientException        if an error is returned by the server.
141     */
142    public void linkNumber(String msisdn, String country, String appId) throws NexmoResponseParseException, NexmoClientException {
143        UpdateNumberRequest request = new UpdateNumberRequest(msisdn, country);
144        request.setVoiceCallbackType(UpdateNumberRequest.CallbackType.APP);
145        request.setVoiceCallbackValue(appId);
146        this.updateNumber(request);
147    }
148}