feat: Add Number Insight v2

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

@@ -23,6 +23,7 @@
 import com.vonage.client.insight.InsightClient;
 import com.vonage.client.meetings.MeetingsClient;
 import com.vonage.client.messages.MessagesClient;
+import com.vonage.client.numberinsight2.NumberInsight2Client;
 import com.vonage.client.numbers.NumbersClient;
 import com.vonage.client.proactiveconnect.ProactiveConnectClient;
 import com.vonage.client.redact.RedactClient;
@@ -65,6 +66,7 @@ public class VonageClient {
     private final MeetingsClient meetings;
     private final UsersClient users;
     private final VideoClient video;
+    private final NumberInsight2Client numberInsight2;
 
     private VonageClient(Builder builder) {
         httpWrapper = new HttpWrapper(builder.httpConfig, builder.authCollection);
@@ -86,6 +88,7 @@ private VonageClient(Builder builder) {
         meetings = new MeetingsClient(httpWrapper);
         users = new UsersClient(httpWrapper);
         video = new VideoClient(httpWrapper);
+        numberInsight2 = new NumberInsight2Client(httpWrapper);
     }
 
     public AccountClient getAccountClient() {
@@ -190,6 +193,16 @@ public VideoClient getVideoClient() {
         return video;
     }
 
+    /**
+     * Returns the Number Insight v2 client.
+     *
+     * @return The NI v2 client.
+     * @since 8.2.0
+     */
+    public NumberInsight2Client getNumberInsight2Client() {
+        return numberInsight2;
+    }
+
     /**
      * Generate a JWT for the application the client has been configured with.
      *

src/main/java/com/vonage/client/numberinsight2/FraudCheckRequest.java

@@ -0,0 +1,66 @@
+/*
+ *   Copyright 2024 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.numberinsight2;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.vonage.client.Jsonable;
+import com.vonage.client.common.E164;
+import java.util.EnumSet;
+import java.util.Objects;
+import java.util.Set;
+
+@JsonInclude(value = JsonInclude.Include.NON_NULL)
+class FraudCheckRequest implements Jsonable {
+	private final String type, phone;
+	private final Set<Insight> insights;
+
+	public FraudCheckRequest(String phoneNumber, Insight insight, Insight... others) {
+		type = "phone";
+		phone = new E164(phoneNumber).toString();
+		insights = EnumSet.of(Objects.requireNonNull(insight, "Insight type is required."), others);
+	}
+
+	/**
+	 * Accepted value is “phone” when a phone number is provided.
+	 * 
+	 * @return The request type as a string.
+	 */
+	@JsonProperty("type")
+	public String getType() {
+		return type;
+	}
+
+	/**
+	 * A single phone number that you need insight about in the E.164 format. Don't use a leading + or 00.
+	 * 
+	 * @return The phone number in E.164 format.
+	 */
+	@JsonProperty("phone")
+	public String getPhone() {
+		return phone;
+	}
+
+	/**
+	 * The required insights. Must provide at least one.
+	 * 
+	 * @return The requested insights.
+	 */
+	@JsonProperty("insights")
+	public Set<Insight> getInsights() {
+		return insights;
+	}
+}

src/main/java/com/vonage/client/numberinsight2/FraudCheckResponse.java

@@ -0,0 +1,96 @@
+/*
+ *   Copyright 2024 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.numberinsight2;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.vonage.client.Jsonable;
+import java.util.UUID;
+
+/**
+ * Fraud check results as obtained from {@link NumberInsight2Client#fraudCheck(String, Insight, Insight...)}.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class FraudCheckResponse implements Jsonable {
+	private String type;
+	private UUID requestId;
+	private Phone phone;
+	private FraudScore fraudScore;
+	private SimSwap simSwap;
+
+	protected FraudCheckResponse() {
+	}
+
+	/**
+	 * The type of lookup used in the request. Currently always "phone".
+	 *
+	 * @return The lookup type as a string.
+	 */
+	@JsonProperty("type")
+	protected String getType() {
+		return type;
+	}
+
+	/**
+	 * Unique ID for this request for reference.
+	 * 
+	 * @return The request reference UUID.
+	 */
+	@JsonProperty("request_id")
+	public UUID getRequestId() {
+		return requestId;
+	}
+
+	/**
+	 * An object containing at least the phone number that was used in the fraud check. If {@linkplain Insight#FRAUD_SCORE} was also requested and successful, other phone information (carrier and type) will be returned.
+	 * 
+	 * @return Information about the phone number.
+	 */
+	@JsonProperty("phone")
+	public Phone getPhone() {
+		return phone;
+	}
+
+	/**
+	 * Result of the fraud score insight operation. Only returned if {@linkplain Insight#FRAUD_SCORE} was requested.
+	 * 
+	 * @return The fraud score details, or {@code null} if not applicable.
+	 */
+	@JsonProperty("fraud_score")
+	public FraudScore getFraudScore() {
+		return fraudScore;
+	}
+
+	/**
+	 * Result of the SIM swap insight operation. Only returned if {@linkplain Insight#SIM_SWAP} was requested.
+	 * 
+	 * @return The SIM swap details, or {@code null} if not applicable.
+	 */
+	@JsonProperty("sim_swap")
+	public SimSwap getSimSwap() {
+		return simSwap;
+	}
+
+	/**
+	 * Creates an instance of this class from a JSON payload.
+	 *
+	 * @param json The JSON string to parse.
+	 * @return An instance of this class with the fields populated, if present.
+	 */
+	public static FraudCheckResponse fromJson(String json) {
+		return Jsonable.fromJson(json);
+	}
+}

src/main/java/com/vonage/client/numberinsight2/FraudScore.java

@@ -0,0 +1,72 @@
+/*
+ *   Copyright 2024 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.numberinsight2;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Represents the fraud score insight results in {@link FraudCheckResponse#getFraudScore()}.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class FraudScore {
+	private Integer riskScore;
+	private RiskRecommendation riskRecommendation;
+	private RiskLabel label;
+	private FraudScoreStatus status;
+
+	protected FraudScore() {}
+
+	/**
+	 * Score derived from evaluating fraud-related data associated with the phone number. This ranges from 0-100, with 0 meaning least risk and 100 meaning highest risk.
+	 * 
+	 * @return The risk score as an Integer between 0 and 100.
+	 */
+	@JsonProperty("risk_score")
+	public Integer getRiskScore() {
+		return riskScore;
+	}
+
+	/**
+	 * Recommended action based on the risk score.
+	 * 
+	 * @return The recommendation as an enum.
+	 */
+	@JsonProperty("risk_recommendation")
+	public RiskRecommendation getRiskRecommendation() {
+		return riskRecommendation;
+	}
+
+	/**
+	 * Mapping of risk score to a verbose description.
+	 * 
+	 * @return The risk label as an enum.
+	 */
+	@JsonProperty("label")
+	public RiskLabel getLabel() {
+		return label;
+	}
+
+	/**
+	 * Status of the fraud score API call.
+	 * 
+	 * @return The insight status as an enum.
+	 */
+	@JsonProperty("status")
+	public FraudScoreStatus getStatus() {
+		return status;
+	}
+}

src/main/java/com/vonage/client/numberinsight2/FraudScoreStatus.java

@@ -0,0 +1,24 @@
+/*
+ *   Copyright 2024 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.numberinsight2;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+/**
+ * Represents the status in {@link FraudScore#getStatus()}.
+ */
+public enum FraudScoreStatus {
+	@JsonProperty("completed") COMPLETED
+}

src/main/java/com/vonage/client/numberinsight2/Insight.java

@@ -0,0 +1,32 @@
+/*
+ *   Copyright 2024 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.numberinsight2;
+
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * Represents the type of insights used for a fraud check request.
+ */
+public enum Insight {
+	FRAUD_SCORE,
+	SIM_SWAP;
+
+	@JsonValue
+	@Override
+	public String toString() {
+		return name().toLowerCase();
+	}	
+}