Add Users API (#468)

* Added Users client

* Added User channels

* Updated package-info

* Added cursor to ListUsers

* Added doc on user sort order

* Added BaseUser & utility methods

* Tidied up channels docs

* Added constructors for complex channels

* Fixed getUser

* 100% UsersClient coverage

* 100% channels coverage

* Validate SIP/WS protocols

* Added code to ApiResponseException

* Added note on customData

* Cover getUsersClient in tests

CHANGELOG.md

@@ -4,14 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-# [7.7.0] - 2023-08
+# [7.7.0] - 2023-08-10
+- Added Users API implementation
 - Major refactoring of how endpoints are implemented internally
   - SMS, SNS, Redact, Verify v2, Subaccounts, Messages, Application have been refactored
 - Introduced `Jsonable` and `QueryParams` in addition to `DynamicEndpoint` to reduce boilerplate
 - Added missing fields to Application, capabilities and webhooks
 - Removed `PageList` (replaced by `HalPageResponse`)
 - Improved documentation for Application API implementation
-- Added Users endpoints to Application API implementation
 
 # [7.6.0] - 2023-06-30
 - Added Proactive Connect API implementation

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

@@ -38,8 +38,8 @@
 @JsonInclude(JsonInclude.Include.NON_NULL)
 public class VonageApiResponseException extends VonageClientException implements Jsonable {
 	protected URI type;
-	protected String title, detail, instance;
-	protected List<?> errors;
+	protected String title, detail, instance, code;
+	protected List<?> errors, invalidParameters;
 	@JsonIgnore protected int statusCode;
 
 	protected VonageApiResponseException() {
@@ -109,11 +109,35 @@ public List<?> getErrors() {
 		return errors;
 	}
 
+	/**
+	 * If the request was rejected due to invalid parameters, this will return the
+	 * offending parameters, sometimes along with a description of the errors.
+	 *
+	 * @return The list of invalid parameters, typically as a Map, or {@code null} if not applicable.
+	 *
+	 * @since 7.7.0
+	 */
+	@JsonProperty("invalid_parameters")
+	public List<?> getInvalidParameters() {
+		return invalidParameters;
+	}
+
+	/**
+	 * Name of the error code.
+	 *
+	 * @return The Vonage error code as a string, or {@code null} if unknown / not applicable.
+	 */
+	@JsonProperty("code")
+	public String getCode() {
+		return code;
+	}
+
 	/**
 	 * The API response status code, usually 4xx or 500.
 	 *
 	 * @return The status code.
 	 */
+	@JsonIgnore
 	public int getStatusCode() {
 		return statusCode;
 	}

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

@@ -29,6 +29,7 @@
 import com.vonage.client.sms.SmsClient;
 import com.vonage.client.sns.SnsClient;
 import com.vonage.client.subaccounts.SubaccountsClient;
+import com.vonage.client.users.UsersClient;
 import com.vonage.client.verify.VerifyClient;
 import com.vonage.client.verify2.Verify2Client;
 import com.vonage.client.voice.VoiceClient;
@@ -64,6 +65,7 @@ public class VonageClient {
     private final SubaccountsClient subaccounts;
     private final ProactiveConnectClient proactiveConnect;
     private final MeetingsClient meetings;
+    private final UsersClient users;
 
     private VonageClient(Builder builder) {
         httpWrapper = new HttpWrapper(builder.httpConfig, builder.authCollection);
@@ -84,6 +86,7 @@ private VonageClient(Builder builder) {
         subaccounts = new SubaccountsClient(httpWrapper);
         proactiveConnect = new ProactiveConnectClient(httpWrapper);
         meetings = new MeetingsClient(httpWrapper);
+        users = new UsersClient(httpWrapper);
     }
 
     public AccountClient getAccountClient() {
@@ -178,6 +181,16 @@ public SubaccountsClient getSubaccountsClient() {
         return subaccounts;
     }
 
+    /**
+     *
+     *
+     * @return The Users client.
+     * @since 7.7.0
+     */
+    public UsersClient getUsersClient() {
+        return users;
+    }
+
     /**
      * Generate a JWT for the application the client has been configured with.
      *

src/main/java/com/vonage/client/application/ListApplicationRequest.java

@@ -23,18 +23,18 @@
  * Query parameters for {@link ApplicationClient#listApplications(ListApplicationRequest)}.
  */
 public class ListApplicationRequest implements QueryParamsRequest {
-    private final long pageSize, page;
+    private final int pageSize, page;
 
     private ListApplicationRequest(Builder builder) {
         pageSize = builder.pageSize;
         page = builder.page;
     }
 
-    public long getPageSize() {
+    public int getPageSize() {
         return pageSize;
     }
 
-    public long getPage() {
+    public int getPage() {
         return page;
     }
 
@@ -50,21 +50,25 @@ public Map<String, String> makeParams() {
         return params;
     }
 
+    /**
+     * Entry point for constructing an instance of this class.
+     *
+     * @return A new Builder.
+     */
     public static Builder builder() {
         return new Builder();
     }
 
     public static class Builder {
-        private long pageSize;
-        private long page;
+        private int pageSize, page;
 
         /**
          * @param pageSize The number of applications per page.
          *
          * @return This builder.
          */
         public Builder pageSize(long pageSize) {
-            this.pageSize = pageSize;
+            this.pageSize = (int) pageSize;
             return this;
         }
 
@@ -74,7 +78,7 @@ public Builder pageSize(long pageSize) {
          * @return This builder.
          */
         public Builder page(long page) {
-            this.page = page;
+            this.page = (int) page;
             return this;
         }
 

src/main/java/com/vonage/client/users/BaseUser.java

@@ -0,0 +1,71 @@
+/*
+ *   Copyright 2023 Vonage
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+package com.vonage.client.users;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.vonage.client.Jsonable;
+import java.util.Objects;
+
+/**
+ * Represents the main attributes of a User.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class BaseUser implements Jsonable {
+    String id, name;
+
+    BaseUser() {
+    }
+
+    void setId(String id) {
+        this.id = id;
+    }
+
+    /**
+     * Unique user ID.
+     *
+     * @return The user ID as a string, or {@code null} if unknown.
+     */
+    @JsonProperty("id")
+    public String getId() {
+        return id;
+    }
+
+    /**
+     * Unique name of the user.
+     *
+     * @return The user's name.
+     */
+    @JsonProperty("name")
+    public String getName() {
+        return name;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        BaseUser baseUser = (BaseUser) o;
+        return Objects.equals(id, baseUser.id) && Objects.equals(name, baseUser.name);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id, name);
+    }
+}