docs: Add KDocs to all public methods & classes (#11)

* docs: Vonage (top-level) KDocs * Add top-level docs * SIM Swap KDocs * Conversion KDocs * Redact KDocs * Number Verification KDocs * Application KDocs * Users KDocs * Account KDocs & auth methods * Subaccounts KDocs * SMS KDocs * Messages KDocs * Verify v2 KDocs * Rename test clients, repurpose VonageTest * Number Insight KDocs * Verify v1 KDocs * Fix compilation error * Numbers KDocs * Video minor refactor & KDocs * All Video functions documented * Video KDocs throws clauses * Voice KDocs & small tweaks * Remove combine-only build * Fix compilation error * Revert testing with Java 8 * Fix failing test
Vonage · Sep 6, 2024 · eb682c4 · eb682c4
1 parent f7d443d
commit eb682c4
Show file tree

Hide file tree

Showing 35 changed files with 2,382 additions and 212 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,13 +4,34 @@ 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/).
 
+## [1.0.0] - 2024-09-12
+GA release!
+
+### [1.0.0-beta2] - 2024-09-06
+
+### Added
+- Documentation (KDocs) for all classes and methods
+
+### Changed
+- Moved Video API's `connectToWebSocket`, `startRender` and `sipDial` methods to `ExistingSession`
+- `CallsFilter.Builder.dateStart` and `dateEnd` extension functions now accept `Instant` instead of `String`
+- `Voice.inputAction` requires body
+- `Voice.connectToWebSocket` and `Call.Builder.toWebSocket` `contentType` parameter changed to (mandatory) enum
+
+### Removed
+- `Voice.ExistingCall.transfer(URI)` method
+
 ## [1.0.0-beta1] - 2024-09-02
+Feature-complete beta release
 
 ### Added
 - Video API
 
 ### Changed
-- Standardised `Existing*` classes to extend `ExistingResource` for consistency
+- Renamed `VerifyLegacy.ExistingRequest#search` to `info` for consistency with other APIs
+
+### Changed
+- Standardised `Existing*` classes to extend `ExistingResource` for consistency.
 
 ## [0.9.0] - 2024-08-19
 
@@ -77,10 +98,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `authFromEnv` now checks for absent environment variables before attempting to set them
 
 ## [0.1.0] - 2024-06-25
-
-Initial version.
+Initial version
 
 ### Added
 - Messages API
 - Verify v2 API
-
diff --git a/pom.xml b/pom.xml
@@ -5,7 +5,7 @@
 
   <groupId>com.vonage</groupId>
   <artifactId>server-sdk-kotlin</artifactId>
-  <version>1.0.0-beta1</version>
+  <version>1.0.0-beta2</version>
 
   <name>Vonage Kotlin Server SDK</name>
   <description>Kotlin client for Vonage APIs</description>

diff --git a/src/main/kotlin/com/vonage/client/kt/Account.kt b/src/main/kotlin/com/vonage/client/kt/Account.kt
@@ -17,32 +17,115 @@ package com.vonage.client.kt
 
 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) {
 
+    /**
+     * Obtains the current account remaining balance.
+     *
+     * @return A [BalanceResponse] object containing the current account balance.
+     * @throws [AccountResponseException] If the balance cannot be retrieved.
+     */
     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)