feat: Add missing Numbers API fields, documentation & refactoring (#541)

* feat: Add missing Numbers API fields

* Tidy up UpdateNumberRequest

* WIP: More tidying up

* WIP: Improve Numbers documentation

* WIP: Factor out common filter parameters

* WIP: Updating tests

* 100% coverage

* Fix Number Verification URL

* Deprecate Meetings API

* Tidy up tests

* fix build

* fix build

* Deprecate CheckRequest

CHANGELOG.md

@@ -2,6 +2,17 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+# [8.10.0] - 2024-08-02
+- Added `targetApiKey` for buy & cancel number endpoints
+- Added Builder for `UpdateNumberRequest` and deprecated setters
+- Added `app_id` property to `UpdateNumberRequest` (replaces `messagesCallbackValue`)
+- Added `applicationId` and `hasApplication` to `ListNumbersFilter`
+- Builders for `ListNumbersFilter` and `SearchNumbersFilter`
+- Improved / added missing documentation in Numbers API
+- Deprecated setters in Numbers API
+- `state` not included in Number Verification auth URL if null
+- Deprecated Meetings API
+
 # [8.9.4] - 2024-07-25
 - Fixed UUID validation in `ConversationAction.Builder#canHear` and `canSpeak`
   - Changed signature of `canHear` and `canSpeak` methods to return Strings instead of UUIDs

pom.xml

@@ -5,7 +5,7 @@
 
   <groupId>com.vonage</groupId>
   <artifactId>server-sdk</artifactId>
-  <version>8.9.4</version>
+  <version>8.10.0</version>
 
   <name>Vonage Java Server SDK</name>
   <description>Java client for Vonage APIs</description>
@@ -46,6 +46,7 @@
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <nexusUrl>https://oss.sonatype.org</nexusUrl>
     <jackson.version>2.17.2</jackson.version>
+    <jjwt.version>0.12.6</jjwt.version>
   </properties>
 
   <dependencies>
@@ -103,19 +104,19 @@
     <dependency>
       <groupId>io.jsonwebtoken</groupId>
       <artifactId>jjwt-api</artifactId>
-      <version>0.12.6</version>
+      <version>${jjwt.version}</version>
       <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>io.jsonwebtoken</groupId>
       <artifactId>jjwt-impl</artifactId>
-      <version>0.12.6</version>
+      <version>${jjwt.version}</version>
       <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>io.jsonwebtoken</groupId>
       <artifactId>jjwt-jackson</artifactId>
-      <version>0.12.6</version>
+      <version>${jjwt.version}</version>
       <scope>test</scope>
     </dependency>
   </dependencies>

src/main/java/com/vonage/client/HttpWrapper.java

@@ -34,7 +34,7 @@
 public class HttpWrapper {
     private static final String
             CLIENT_NAME = "vonage-java-sdk",
-            CLIENT_VERSION = "8.9.4",
+            CLIENT_VERSION = "8.10.0",
             JAVA_VERSION = System.getProperty("java.version"),
             USER_AGENT = String.format("%s/%s java/%s", CLIENT_NAME, CLIENT_VERSION, JAVA_VERSION);
 

src/main/java/com/vonage/client/QueryParamsRequest.java

@@ -18,11 +18,20 @@
 import java.util.Map;
 
 /**
- * Indicates that a request object has query parameters.
+ * Indicates that a request object has query parameters. This interface
+ * is an internal implementation detail and not part of the SDK's public API.
  *
  * @since 7.7.0
  */
 public interface QueryParamsRequest {
 
+	/**
+	 * Internal method for serializing the fields of this class into query parameters.
+	 * The Map should be mutable so that subclasses can add fields, otherwise the
+	 * method or implementing class should be marked as {@code final}. Duplicate entries
+	 * can be handled by mapping the key to a list of the entries.
+	 *
+	 * @return The query parameters as unique key-value pairs.
+	 */
 	Map<String, ?> makeParams();
 }

src/main/java/com/vonage/client/VonageClient.java

@@ -158,7 +158,10 @@ public ProactiveConnectClient getProactiveConnectClient() {
      *
      * @return The Meetings client.
      * @since 7.6.0
+     *
+     * @deprecated Support for this API will be removed in the next major release.
      */
+    @Deprecated
     public MeetingsClient getMeetingsClient() {
         return meetings;
     }

src/main/java/com/vonage/client/auth/camara/FrontendAuthRequest.java

@@ -40,7 +40,9 @@ public FrontendAuthRequest(String msisdn, URI redirectUrl, UUID applicationId, S
         params.put("client_id", Objects.requireNonNull(applicationId, "Application ID is required.").toString());
         params.put("redirect_uri", Objects.requireNonNull(redirectUrl, "Redirect URL is required.").toString());
         params.put("response_type", "code");
-        params.put("state", state);
+        if (state != null) {
+            params.put("state", state);
+        }
     }
 
     public URI buildOidcUrl() {

src/main/java/com/vonage/client/meetings/MeetingsClient.java

@@ -33,6 +33,12 @@
 import java.util.*;
 import java.util.function.Function;
 
+/**
+ * Meetings API client.
+ *
+ * @deprecated Support for this API will be removed in the next major release.
+ */
+@Deprecated
 public class MeetingsClient {
 	HttpClient httpClient;
 

src/main/java/com/vonage/client/meetings/package-info.java

@@ -21,5 +21,7 @@
  * for an overview of the concepts.
  *
  * @since 7.6.0
+ *
+ * @deprecated Support for this API will be removed in the next major release.
  */
 package com.vonage.client.meetings;

src/main/java/com/vonage/client/numbers/AvailableNumber.java

@@ -15,36 +15,25 @@
  */
 package com.vonage.client.numbers;
 
-import com.vonage.client.JsonableBaseObject;
-
-public class AvailableNumber extends JsonableBaseObject {
-    private String country, msisdn, cost, type;
-    private String[] features;
+/**
+ * Represents a number that is available to buy.
+ */
+public class AvailableNumber extends JsonableNumber {
+    private String cost;
 
     /**
+     * Constructor.
+     *
      * @deprecated This will be made package-private in a future release.
      */
     @Deprecated
     public AvailableNumber() {}
 
-    public String getCountry() {
-        return country;
-    }
-
-    @Deprecated
-    public void setCountry(String country) {
-        this.country = country;
-    }
-
-    public String getMsisdn() {
-        return msisdn;
-    }
-
-    @Deprecated
-    public void setMsisdn(String msisdn) {
-        this.msisdn = msisdn;
-    }
-
+    /**
+     * The monthly rental cost for this number, in Euros.
+     *
+     * @return The rental cost as a string.
+     */
     public String getCost() {
         return cost;
     }
@@ -53,22 +42,4 @@ public String getCost() {
     public void setCost(String cost) {
         this.cost = cost;
     }
-
-    public String getType() {
-        return type;
-    }
-
-    @Deprecated
-    public void setType(String type) {
-        this.type = type;
-    }
-
-    public String[] getFeatures() {
-        return features;
-    }
-
-    @Deprecated
-    public void setFeatures(String[] features) {
-        this.features = features;
-    }
 }

src/main/java/com/vonage/client/numbers/BaseNumberRequest.java

@@ -16,21 +16,37 @@
 package com.vonage.client.numbers;
 
 import com.vonage.client.QueryParamsRequest;
+import com.vonage.client.common.E164;
 import java.util.LinkedHashMap;
 import java.util.Map;
 
-class BaseNumberRequest implements QueryParamsRequest {
+/**
+ * Base class for number management queries.
+ *
+ * @since 8.10.0
+ */
+abstract class BaseNumberRequest implements QueryParamsRequest {
     private final String country, msisdn;
 
-    public BaseNumberRequest(String country, String msisdn) {
-        this.country = country;
-        this.msisdn = msisdn;
+    protected BaseNumberRequest(String country, String msisdn) {
+        this.country = validateCountry(country);
+        this.msisdn = new E164(msisdn).toString();
     }
 
+    /**
+     * Two character country code in ISO 3166-1 alpha-2 format.
+     *
+     * @return The number's country code.
+     */
     public String getCountry() {
         return country;
     }
 
+    /**
+     * Phone number in E.164 format.
+     *
+     * @return The MSISDN as a string.
+     */
     public String getMsisdn() {
         return msisdn;
     }
@@ -42,4 +58,11 @@ public Map<String, String> makeParams() {
         params.put("msisdn", msisdn);
         return params;
     }
+
+    static String validateCountry(String country) {
+        if (country == null || country.length() != 2) {
+            throw new IllegalArgumentException("Country code is required in ISO 3166-1 alpha-2 format.");
+        }
+        return country.toUpperCase();
+    }
 }