feat: Support Messages API failover (#40)

SMadani · web-flow · commit f23bfc80c52e · 2025-05-08T14:26:54.000+01:00
* feat: Messages API failover

* docs: Deprecate NV, SimSwap, Verify v1
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,20 @@ 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/).
 
+## [2.1.1] - 2025-05-08
+Adds support for failovers in Messages API
+
+### Changed
+- Bumped Java SDK version to 9.3.1
+
+### Fixed
+- Type inference behaviour of `Custom` client
+
+### Deprecated
+- SIM Swap API
+- Number Verification API
+- Verify legacy (v1) API
+
 ## [2.1.0] - 2025-04-30
 
 ### Added
diff --git a/README.md b/README.md
@@ -52,7 +52,7 @@ See all of our SDKs and integrations on the [Vonage Developer portal](https://de
 ## Installation
 Releases are published to [Maven Central](https://central.sonatype.com/artifact/com.vonage/server-sdk-kotlin).
 Instructions for your build system can be found in the snippets section.
-They're also available from [here](https://search.maven.org/artifact/com.vonage/server-sdk-kotlin/2.1.0/jar).
+They're also available from [here](https://search.maven.org/artifact/com.vonage/server-sdk-kotlin/2.1.1/jar).
 Release notes for each version can be found in the [changelog](CHANGELOG.md).
 
 Here are the instructions for including the SDK in your project:
@@ -62,7 +62,7 @@ Add the following to your `build.gradle` or `build.gradle.kts` file:
 
 ```groovy
 dependencies {
-    implementation("com.vonage:server-sdk-kotlin:2.1.0")
+    implementation("com.vonage:server-sdk-kotlin:2.1.1")
 }
 ```
 
@@ -73,7 +73,7 @@ Add the following to the `<dependencies>` section of your `pom.xml` file:
 <dependency>
     <groupId>com.vonage</groupId>
     <artifactId>server-sdk-kotlin</artifactId>
-    <version>2.1.0</version>
+    <version>2.1.1</version>
 </dependency>
 ```
 
@@ -159,8 +159,8 @@ including [**a searchable list of snippets**](https://github.com/Vonage/vonage-k
 
 The SDK is fully documented with [KDocs](https://kotlinlang.org/docs/kotlin-doc.html), so you should have complete
 documentation from your IDE. You may need to click "Download Sources" in IntelliJ to get the full documentation.
-Alternatively, you can browse the documentation  using a service like [Javadoc.io](https://javadoc.io/doc/com.vonage/server-sdk-kotlin/2.1.0/index.html),
-which renders the documentation for you from [the artifacts on Maven Central](https://repo.maven.apache.org/maven2/com/vonage/server-sdk-kotlin/2.1.0/).
+Alternatively, you can browse the documentation  using a service like [Javadoc.io](https://javadoc.io/doc/com.vonage/server-sdk-kotlin/2.1.1/index.html),
+which renders the documentation for you from [the artifacts on Maven Central](https://repo.maven.apache.org/maven2/com/vonage/server-sdk-kotlin/2.1.1/).
 
 For help with any specific APIs, refer to the relevant documentation on our [developer portal](https://developer.vonage.com/en/documentation),
 using the links provided in the [Supported APIs](#supported-apis) section. For completeness, you can also consult the
diff --git a/pom.xml b/pom.xml
@@ -5,7 +5,7 @@
 
   <groupId>com.vonage</groupId>
   <artifactId>server-sdk-kotlin</artifactId>
-  <version>2.1.0</version>
+  <version>2.1.1</version>
 
   <name>Vonage Kotlin Server SDK</name>
   <description>Kotlin client for Vonage APIs</description>
@@ -55,7 +55,7 @@
     <dependency>
       <groupId>com.vonage</groupId>
       <artifactId>server-sdk</artifactId>
-      <version>9.2.0</version>
+      <version>9.3.1</version>
     </dependency>
     <dependency>
       <groupId>org.jetbrains.kotlin</groupId>
diff --git a/src/main/kotlin/com/vonage/client/kt/Account.kt b/src/main/kotlin/com/vonage/client/kt/Account.kt
@@ -20,7 +20,7 @@ import com.vonage.client.account.*
 /**
  * Implementation of the [Account API](https://developer.vonage.com/en/api/account).
  *
- * *Authentication method:* API key & secret.
+ * *Authentication method:* API key and secret.
  */
 class Account internal constructor(private val client: AccountClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/Application.kt b/src/main/kotlin/com/vonage/client/kt/Application.kt
@@ -26,7 +26,7 @@ import java.util.*
 /**
  * Implementation of the [Application API](https://developer.vonage.com/en/api/application.v2).
  *
- * *Authentication method:* API key & secret.
+ * *Authentication method:* API key and secret.
  */
 class Application internal constructor(private val client: ApplicationClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/Conversion.kt b/src/main/kotlin/com/vonage/client/kt/Conversion.kt
@@ -22,7 +22,7 @@ import java.util.*
 /**
  * Implementation of the [Conversion API](https://developer.vonage.com/en/api/Conversion).
  *
- * *Authentication method:* API key & secret.
+ * *Authentication method:* API key and secret.
  */
 class Conversion internal constructor(private val client: ConversionClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/Messages.kt b/src/main/kotlin/com/vonage/client/kt/Messages.kt
@@ -28,7 +28,7 @@ import java.util.UUID
 /**
  * Implementation of the [Messages API](https://developer.vonage.com/en/api/messages-olympus).
  *
- * *Authentication method:* JWT (recommended), API key & secret (limited functionality).
+ * *Authentication method:* JWT (recommended), API key and secret (limited functionality).
  */
 class Messages internal constructor(private val client: MessagesClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/NumberInsight.kt b/src/main/kotlin/com/vonage/client/kt/NumberInsight.kt
@@ -20,7 +20,7 @@ import com.vonage.client.insight.*
 /**
  * Implementation of the [Number Insight API](https://developer.vonage.com/en/api/number-insight).
  *
- * *Authentication method:* API key & secret.
+ * *Authentication method:* API key and secret.
  */
 class NumberInsight internal constructor(private val client: InsightClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/NumberVerification.kt b/src/main/kotlin/com/vonage/client/kt/NumberVerification.kt
@@ -24,7 +24,10 @@ import java.net.URI
  * Implementation of the [Number Verification API](https://developer.vonage.com/en/api/camara/number-verification).
  *
  * *Authentication method:* JWT.
+ *
+ * @deprecated This API will be moved in a future major release.
  */
+@Deprecated("This API will be moved in a future release.")
 class NumberVerification internal constructor(private val client: NumberVerificationClient) {
     private var redirectUri: URI? = null
 
diff --git a/src/main/kotlin/com/vonage/client/kt/Numbers.kt b/src/main/kotlin/com/vonage/client/kt/Numbers.kt
@@ -20,7 +20,7 @@ import com.vonage.client.numbers.*
 /**
  * Implementation of the [Numbers API](https://developer.vonage.com/en/api/numbers).
  *
- * *Authentication method:* API key & secret.
+ * *Authentication method:* API key and secret.
  */
 class Numbers internal constructor(private val client: NumbersClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/Redact.kt b/src/main/kotlin/com/vonage/client/kt/Redact.kt
@@ -20,7 +20,7 @@ import com.vonage.client.redact.*
 /**
  * Implementation of the [Redact API](https://developer.vonage.com/en/api/redact).
  *
- * *Authentication method:* API key & secret.
+ * *Authentication method:* API key and secret.
  */
 class Redact internal constructor(private val client: RedactClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/SimSwap.kt b/src/main/kotlin/com/vonage/client/kt/SimSwap.kt
@@ -24,7 +24,10 @@ import java.time.Instant
  * Implementation of the [Sim Swap API](https://developer.vonage.com/en/api/camara/sim-swap).
  *
  * *Authentication method:* JWT.
+ *
+ * @deprecated This API will be moved in a future major release.
  */
+@Deprecated("This API will be moved in a future release.")
 class SimSwap internal constructor(private val client: SimSwapClient) {
 
     /**
diff --git a/src/main/kotlin/com/vonage/client/kt/Sms.kt b/src/main/kotlin/com/vonage/client/kt/Sms.kt
@@ -21,7 +21,7 @@ import com.vonage.client.sms.messages.*
 /**
  * Implementation of the [SMS API](https://developer.vonage.com/en/api/sms).
  *
- * *Authentication method:* API key & secret or signature secret.
+ * *Authentication method:* API key and secret or signature secret.
  */
 class Sms internal constructor(private val client: SmsClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/Subaccounts.kt b/src/main/kotlin/com/vonage/client/kt/Subaccounts.kt
@@ -22,7 +22,7 @@ import java.time.Instant
 /**
  * Implementation of the [Subaccounts API](https://developer.vonage.com/en/api/subaccounts).
  *
- * *Authentication method:* API key & secret.
+ * *Authentication method:* API key and secret.
  */
 class Subaccounts internal constructor(private val client: SubaccountsClient) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/Verify.kt b/src/main/kotlin/com/vonage/client/kt/Verify.kt
@@ -21,7 +21,7 @@ import java.util.*
 /**
  * Implementation of the [Verify v2 API](https://developer.vonage.com/en/api/verify.v2).
  *
- * *Authentication method:* JWT (recommended) and API key & secret (limited functionality).
+ * *Authentication method:* JWT (recommended), API key and secret (limited functionality).
  */
 class Verify(private val client: Verify2Client) {
 
diff --git a/src/main/kotlin/com/vonage/client/kt/VerifyLegacy.kt b/src/main/kotlin/com/vonage/client/kt/VerifyLegacy.kt
@@ -20,8 +20,11 @@ import com.vonage.client.verify.*
 /**
  * Implementation of the [Verify v1 API](https://developer.vonage.com/en/api/verify).
  *
- * *Authentication method:* API key & secret or signature secret.
+ * *Authentication method:* API key and secret or signature secret.
+ *
+ * @deprecated Please migrate to [Verify].
  */
+@Deprecated("Please migrate to Verify v2.")
 class VerifyLegacy internal constructor(private val client: VerifyClient) {
 
     /**
diff --git a/src/main/kotlin/com/vonage/client/kt/Vonage.kt b/src/main/kotlin/com/vonage/client/kt/Vonage.kt
@@ -21,7 +21,7 @@ import com.vonage.client.VonageClient
 /**
  * Denotes the version of the Vonage Kotlin SDK being used, in SemVer format.
  */
-const val VONAGE_KOTLIN_SDK_VERSION = "2.1.0"
+const val VONAGE_KOTLIN_SDK_VERSION = "2.1.1"
 
 /**
  * The non-overridable user agent string used by the SDK.
@@ -102,7 +102,10 @@ class Vonage(config: VonageClient.Builder.() -> Unit) {
      * Access to the CAMARA Number Verification API.
      *
      * @return The [NumberVerification] client.
+     *
+     * @deprecated This API will be moved in a future major release.
      */
+    @Deprecated("This API will be removed in a future release.")
     val numberVerification = NumberVerification(client.numberVerificationClient)
 
     /**
@@ -116,7 +119,10 @@ class Vonage(config: VonageClient.Builder.() -> Unit) {
      * Access to the CAMARA SIM Swap API.
      *
      * @return The [SimSwap] client.
+     *
+     * @deprecated This API will be moved in a future major release.
      */
+    @Deprecated("This API will be removed in a future release.")
     val simSwap = SimSwap(client.simSwapClient)
 
     /**
@@ -152,7 +158,10 @@ class Vonage(config: VonageClient.Builder.() -> Unit) {
      * Access to the Vonage Verify v1 API.
      *
      * @return The [VerifyLegacy] client.
+     *
+     * @deprecated Please migrate to [verify].
      */
+    @Deprecated("Please migrate to Verify v2.")
     val verifyLegacy = VerifyLegacy(client.verifyClient)
 
     /**
diff --git a/src/test/kotlin/com/vonage/client/kt/MessagesTest.kt b/src/test/kotlin/com/vonage/client/kt/MessagesTest.kt
@@ -100,14 +100,32 @@ class MessagesTest : AbstractTest() {
             "ttl" to ttl,
             "webhook_url" to webhookUrl,
             "webhook_version" to "v0.1",
+            "failover" to listOf(
+                textBody("rcs", mapOf(
+                    "client_ref" to clientRef,
+                    "webhook_url" to webhookUrl,
+                    "webhook_version" to "v1"
+                )),
+                textBody("whatsapp")
+            ),
             "sms" to mapOf(
                 "content_id" to contentId,
                 "entity_id" to entityId
-            )
+            ),
         )), smsText {
             from(altNumber); to(toNumber); text(text); ttl(ttl)
             clientRef(clientRef); contentId(contentId); entityId(entityId)
             webhookUrl(webhookUrl); webhookVersion(MessagesVersion.V0_1)
+            failover(
+                rcsText {
+                    from(altNumber); to(toNumber); text(text)
+                    clientRef(clientRef); webhookUrl(webhookUrl);
+                    webhookVersion(MessagesVersion.V1)
+                },
+                whatsappText {
+                    from(altNumber); to(toNumber); text(text)
+                }
+            )
         })
     }
 
@@ -665,6 +683,9 @@ class MessagesTest : AbstractTest() {
         val amount = 0.0333
         val channel = Channel.SMS
         val smsCount = 2
+        val workflowId = "3TcNjgZZVM5SwCSSuqHNNDR1cSLnqA2Uik3gAonxNiLgAsUggBEzw2n"
+        val workflowItemNumber = 3
+        val workflowItemsTotal = 5
         val parsed = MessageStatus.fromJson(
             """
                 {
@@ -681,6 +702,11 @@ class MessagesTest : AbstractTest() {
                          "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
                       }
                    },
+                   "workflow": {
+                       "id": "$workflowId",
+                       "item_number": "$workflowItemNumber",
+                       "items_total": "$workflowItemsTotal"
+                   },
                    "client_ref": "$clientRef",
                    "usage": {
                       "currency": "$currency",
@@ -710,6 +736,11 @@ class MessagesTest : AbstractTest() {
         assertEquals(channel, parsed.channel)
         assertEquals(networkCode, parsed.destinationNetworkCode)
         assertEquals(smsCount, parsed.smsTotalCount)
+        val workflow = parsed.workflow
+        assertNotNull(workflow)
+        assertEquals(workflowId, workflow.id)
+        assertEquals(workflowItemNumber, workflow.itemNumber)
+        assertEquals(workflowItemsTotal, workflow.totalItems)
     }
 
     @Test

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ import com.vonage.client.account.*`
`20`	`20`	`/**`
`21`	`21`	`* Implementation of the [Account API](https://developer.vonage.com/en/api/account).`
`22`	`22`	`*`
`23`		`- * Authentication method: API key & secret.`
	`23`	`+ * Authentication method: API key and secret.`
`24`	`24`	`*/`
`25`	`25`	`class Account internal constructor(private val client: AccountClient) {`
`26`	`26`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ import java.util.*`
`26`	`26`	`/**`
`27`	`27`	`* Implementation of the [Application API](https://developer.vonage.com/en/api/application.v2).`
`28`	`28`	`*`
`29`		`- * Authentication method: API key & secret.`
	`29`	`+ * Authentication method: API key and secret.`
`30`	`30`	`*/`
`31`	`31`	`class Application internal constructor(private val client: ApplicationClient) {`
`32`	`32`
Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ import java.util.*`
`22`	`22`	`/**`
`23`	`23`	`* Implementation of the [Conversion API](https://developer.vonage.com/en/api/Conversion).`
`24`	`24`	`*`
`25`		`- * Authentication method: API key & secret.`
	`25`	`+ * Authentication method: API key and secret.`
`26`	`26`	`*/`
`27`	`27`	`class Conversion internal constructor(private val client: ConversionClient) {`
`28`	`28`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ import java.util.UUID`
`28`	`28`	`/**`
`29`	`29`	`* Implementation of the [Messages API](https://developer.vonage.com/en/api/messages-olympus).`
`30`	`30`	`*`
`31`		`- * Authentication method: JWT (recommended), API key & secret (limited functionality).`
	`31`	`+ * Authentication method: JWT (recommended), API key and secret (limited functionality).`
`32`	`32`	`*/`
`33`	`33`	`class Messages internal constructor(private val client: MessagesClient) {`
`34`	`34`