Account KDocs & auth methods

src/main/kotlin/com/vonage/client/kt/Account.kt

@@ -19,6 +19,8 @@ import com.vonage.client.account.*
 
 /**
  * Implementation of the [Account API](https://developer.vonage.com/en/api/account).
+ *
+ * Authentication method: API key & secret.
  */
 class Account internal constructor(private val client: AccountClient) {
 
@@ -30,28 +32,100 @@ class Account internal constructor(private val client: AccountClient) {
      */
     fun getBalance(): BalanceResponse = client.balance
 
+    /**
+     * You can top up your account using this API when you have enabled auto-reload in the dashboard.
+     * The amount added by the top-up operation will be the same amount as was added in the payment when
+     * auto-reload was enabled. Your account balance is checked every 5-10 minutes and if it falls below the
+     * threshold and auto-reload is enabled, then it will be topped up automatically. Use this method if you
+     * need to top up at times when your credit may be exhausted more quickly than the auto-reload may occur.
+     *
+     * @param transactionId The top-up transaction ID.
+     *
+     * @throws [AccountResponseException] If the top-up operation fails.
+     */
     fun topUp(transactionId: String): Unit = client.topUp(transactionId)
 
+    /**
+     * Updates the top-level account settings. Namely, the URLs for incoming SMS and delivery receipts.
+     *
+     * @param incomingSmsUrl The URL to which incoming SMS messages are sent when using SMS API.
+     * @param deliverReceiptUrl The URL to which delivery receipts are sent when using SMS API.
+     *
+     * @return The updated account settings.
+     *
+     * @throws [AccountResponseException] If the account settings could not be updated.
+     */
     fun updateSettings(incomingSmsUrl: String? = null, deliverReceiptUrl: String? = null): SettingsResponse =
         client.updateSettings(SettingsRequest(incomingSmsUrl, deliverReceiptUrl))
 
+    /**
+     * Call this method to work with account secrets.
+     *
+     * @param apiKey (OPTIONAL) The account API key to manage secrets for. If not provided,
+     * the default API key (as supplied in the top-level [Vonage] client) will be used.
+     *
+     * @return A [Secrets] object with methods to interact with account secrets.
+     */
     fun secrets(apiKey: String? = null): Secrets = Secrets(apiKey)
 
+    /**
+     * Class for working with account secrets.
+     *
+     * @property apiKey The account API key to manage secrets for. If not provided,
+     * the default API key (as supplied in the top-level [Vonage] client) will be used.
+     */
     inner class Secrets internal constructor(val apiKey: String? = null) {
 
+        /**
+         * Retrieves secrets for the account.
+         *
+         * @return A list of secrets details.
+         *
+         * @throws [AccountResponseException] If the secrets cannot be retrieved.
+         */
         fun list(): List<SecretResponse> = (
                 if (apiKey == null) client.listSecrets()
                 else client.listSecrets(apiKey)
             ).secrets
 
+        /**
+         * Creates a new secret for the account.
+         *
+         * @param secret The secret value to associate with the API key, which must follow these rules:
+         * - Minimum 8 characters
+         * - Maximum 25 characters
+         * - Minimum 1 lower case character
+         * - Minimum 1 upper case character
+         * - Minimum 1 digit
+         *
+         * @return The created secret's metadata.
+         *
+         * @throws [AccountResponseException] If the secret cannot be created.
+         */
         fun create(secret: String): SecretResponse =
             if (apiKey == null) client.createSecret(secret)
             else client.createSecret(apiKey, secret)
 
+        /**
+         * Retrieves a secret by its ID.
+         *
+         * @param secretId ID of the secret to retrieve.
+         *
+         * @return The secret's metadata.
+         *
+         * @throws [AccountResponseException] If the secret cannot be retrieved.
+         */
         fun get(secretId: String): SecretResponse =
             if (apiKey == null) client.getSecret(secretId)
             else client.getSecret(apiKey, secretId)
 
+        /**
+         * Deletes a secret by its ID.
+         *
+         * @param secretId ID of the secret to delete.
+         *
+         * @throws [AccountResponseException] If the secret cannot be deleted.
+         */
         fun delete(secretId: String): Unit =
             if (apiKey == null) client.revokeSecret(secretId)
             else client.revokeSecret(apiKey, secretId)

src/main/kotlin/com/vonage/client/kt/Application.kt

@@ -26,6 +26,8 @@ import java.util.*
 
 /**
  * Implementation of the [Application API](https://developer.vonage.com/en/api/application.v2).
+ *
+ * Authentication method: API key & secret.
  */
 class Application internal constructor(private val client: ApplicationClient) {
 

src/main/kotlin/com/vonage/client/kt/Conversion.kt

@@ -21,6 +21,8 @@ import java.util.*
 
 /**
  * Implementation of the [Conversion API](https://developer.vonage.com/en/api/Conversion).
+ *
+ * Authentication method: API key & secret.
  */
 class Conversion internal constructor(private val client: ConversionClient) {
 

src/main/kotlin/com/vonage/client/kt/Messages.kt

@@ -25,6 +25,8 @@ 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).
  */
 class Messages internal constructor(private val client: MessagesClient) {
     fun send(message: MessageRequest, sandbox: Boolean = false): UUID =

src/main/kotlin/com/vonage/client/kt/NumberInsight.kt

@@ -19,6 +19,8 @@ import com.vonage.client.insight.*
 
 /**
  * Implementation of the [Number Insight API](https://developer.vonage.com/en/api/number-insight).
+ *
+ * Authentication method: API key & secret.
  */
 class NumberInsight internal constructor(private val client: InsightClient) {
 

src/main/kotlin/com/vonage/client/kt/NumberVerification.kt

@@ -22,6 +22,8 @@ import java.net.URI
 
 /**
  * Implementation of the [Number Verification API](https://developer.vonage.com/en/api/camara/number-verification).
+ *
+ * Authentication method: JWT.
  */
 class NumberVerification internal constructor(private val client: NumberVerificationClient) {
     private var redirectUri: URI? = null

src/main/kotlin/com/vonage/client/kt/Numbers.kt

@@ -19,6 +19,8 @@ import com.vonage.client.numbers.*
 
 /**
  * Implementation of the [Numbers API](https://developer.vonage.com/en/api/numbers).
+ *
+ * Authentication method: API key & secret.
  */
 class Numbers internal constructor(private val client: NumbersClient) {
 

src/main/kotlin/com/vonage/client/kt/Redact.kt

@@ -19,6 +19,8 @@ import com.vonage.client.redact.*
 
 /**
  * Implementation of the [Redact API](https://developer.vonage.com/en/api/redact).
+ *
+ * Authentication method: API key & secret.
  */
 class Redact internal constructor(private val client: RedactClient) {
 

src/main/kotlin/com/vonage/client/kt/SimSwap.kt

@@ -22,6 +22,8 @@ import java.time.Instant
 
 /**
  * Implementation of the [Sim Swap API](https://developer.vonage.com/en/api/camara/sim-swap).
+ *
+ * Authentication method: JWT.
  */
 class SimSwap internal constructor(private val client: SimSwapClient) {
 

src/main/kotlin/com/vonage/client/kt/Sms.kt

@@ -20,6 +20,8 @@ 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.
  */
 class Sms internal constructor(private val client: SmsClient) {
 

src/main/kotlin/com/vonage/client/kt/Subaccounts.kt

@@ -21,6 +21,8 @@ import java.time.Instant
 
 /**
  * Implementation of the [Subaccounts API](https://developer.vonage.com/en/api/subaccounts).
+ *
+ * Authentication method: API key & secret.
  */
 class Subaccounts internal constructor(private val client: SubaccountsClient) {
 

src/main/kotlin/com/vonage/client/kt/Users.kt

@@ -20,7 +20,7 @@ import com.vonage.client.users.*
 /**
  * Implementation of the [Users API](https://developer.vonage.com/en/api/application.v2#User).
  *
- * This API uses JWT authentication, so requires application ID and private key to be set on the client.
+ * Authentication method: JWT.
  */
 class Users internal constructor(private val client: UsersClient) {
 

src/main/kotlin/com/vonage/client/kt/Verify.kt

@@ -20,6 +20,8 @@ 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).
  */
 class Verify(private val client: Verify2Client) {
 

src/main/kotlin/com/vonage/client/kt/VerifyLegacy.kt

@@ -19,6 +19,8 @@ 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.
  */
 class VerifyLegacy internal constructor(private val client: VerifyClient) {
 

src/main/kotlin/com/vonage/client/kt/Video.kt

@@ -20,6 +20,8 @@ import java.util.*
 
 /**
  * Implementation of the [Video API](https://developer.vonage.com/en/api/video).
+ *
+ * Authentication method: JWT.
  */
 class Video(private val client: VideoClient) {
 

src/main/kotlin/com/vonage/client/kt/Voice.kt

@@ -23,6 +23,8 @@ import java.util.*
 
 /**
  * Implementation of the [Voice API](https://developer.vonage.com/en/api/voice).
+ *
+ * Authentication method: JWT.
  */
 class Voice internal constructor(private val client: VoiceClient) {
 

src/main/kotlin/com/vonage/client/kt/Vonage.kt

@@ -24,9 +24,17 @@ import com.vonage.client.VonageClient
  * your account credentials (API key and secret) and/or application ID and private key depending
  * on which APIs you plan to use. It is recommended that you set the parameters for both
  * authentication methods to maximise compatibility.
+ *
+ * Every sub-client for interacting with each API is exposed as a property of this class. Those classes
+ * document their accepted / preferred authentication type(s). For JWT authentication, you will need to
+ * provide the application ID and private key path. For API key and secret authentication, you will need
+ * to provide the API key and secret. These are specified on the [VonageClient.Builder] when initialising
+ * this class using the provided lambda function.
+ *
+ * @param config The configuration lambda, where you provide your Vonage account credentials.
  */
-class Vonage(init: VonageClient.Builder.() -> Unit) {
-    private val client : VonageClient = VonageClient.builder().apply(init).build()
+class Vonage(config: VonageClient.Builder.() -> Unit) {
+    private val client : VonageClient = VonageClient.builder().apply(config).build()
 
     /**
      * Access to the Vonage Account API.

src/test/kotlin/com/vonage/client/kt/ConversionTest.kt

@@ -18,7 +18,7 @@ package com.vonage.client.kt
 import kotlin.test.*
 
 class ConversionTest : AbstractTest() {
-    private val conversionClient = vonage.conversion
+    private val client = vonage.conversion
     private val smsEndpoint = "sms"
     private val voiceEndpoint = "voice"
 
@@ -33,27 +33,27 @@ class ConversionTest : AbstractTest() {
     fun `submit sms conversion with timestamp`() {
         val delivered = true
         mockSuccess(smsMessageId, smsEndpoint, delivered, true)
-        conversionClient.convertSms(smsMessageId, delivered, timestampDate.toInstant())
+        client.convertSms(smsMessageId, delivered, timestampDate.toInstant())
     }
 
     @Test
     fun `submit sms conversion without timestamp`() {
         val delivered = false
         mockSuccess(smsMessageId, smsEndpoint, delivered, false)
-        conversionClient.convertSms(smsMessageId, delivered)
+        client.convertSms(smsMessageId, delivered)
     }
 
     @Test
     fun `submit voice conversion with timestamp`() {
         val delivered = false
         mockSuccess(callIdStr, voiceEndpoint, delivered, true)
-        conversionClient.convertVoice(callIdStr, delivered, timestamp)
+        client.convertVoice(callIdStr, delivered, timestamp)
     }
 
     @Test
     fun `submit voice conversion without timestamp`() {
         val delivered = true
         mockSuccess(callIdStr, voiceEndpoint, delivered, false)
-        conversionClient.convertVoice(callIdStr, delivered)
+        client.convertVoice(callIdStr, delivered)
     }
 }