Skip to content

Commit eb682c4

Browse files
authored
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
1 parent f7d443d commit eb682c4

35 files changed

+2382
-212
lines changed

CHANGELOG.md

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,34 @@ All notable changes to this project will be documented in this file.
44
The format is based on [Keep a Changelog](http://keepachangelog.com/)
55
and this project adheres to [Semantic Versioning](http://semver.org/).
66

7+
## [1.0.0] - 2024-09-12
8+
GA release!
9+
10+
### [1.0.0-beta2] - 2024-09-06
11+
12+
### Added
13+
- Documentation (KDocs) for all classes and methods
14+
15+
### Changed
16+
- Moved Video API's `connectToWebSocket`, `startRender` and `sipDial` methods to `ExistingSession`
17+
- `CallsFilter.Builder.dateStart` and `dateEnd` extension functions now accept `Instant` instead of `String`
18+
- `Voice.inputAction` requires body
19+
- `Voice.connectToWebSocket` and `Call.Builder.toWebSocket` `contentType` parameter changed to (mandatory) enum
20+
21+
### Removed
22+
- `Voice.ExistingCall.transfer(URI)` method
23+
724
## [1.0.0-beta1] - 2024-09-02
25+
Feature-complete beta release
826

927
### Added
1028
- Video API
1129

1230
### Changed
13-
- Standardised `Existing*` classes to extend `ExistingResource` for consistency
31+
- Renamed `VerifyLegacy.ExistingRequest#search` to `info` for consistency with other APIs
32+
33+
### Changed
34+
- Standardised `Existing*` classes to extend `ExistingResource` for consistency.
1435

1536
## [0.9.0] - 2024-08-19
1637

@@ -77,10 +98,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
7798
- `authFromEnv` now checks for absent environment variables before attempting to set them
7899

79100
## [0.1.0] - 2024-06-25
80-
81-
Initial version.
101+
Initial version
82102

83103
### Added
84104
- Messages API
85105
- Verify v2 API
86-

pom.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
<groupId>com.vonage</groupId>
77
<artifactId>server-sdk-kotlin</artifactId>
8-
<version>1.0.0-beta1</version>
8+
<version>1.0.0-beta2</version>
99

1010
<name>Vonage Kotlin Server SDK</name>
1111
<description>Kotlin client for Vonage APIs</description>

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,32 +17,115 @@ package com.vonage.client.kt
1717

1818
import com.vonage.client.account.*
1919

20+
/**
21+
* Implementation of the [Account API](https://developer.vonage.com/en/api/account).
22+
*
23+
* *Authentication method:* API key & secret.
24+
*/
2025
class Account internal constructor(private val client: AccountClient) {
2126

27+
/**
28+
* Obtains the current account remaining balance.
29+
*
30+
* @return A [BalanceResponse] object containing the current account balance.
31+
* @throws [AccountResponseException] If the balance cannot be retrieved.
32+
*/
2233
fun getBalance(): BalanceResponse = client.balance
2334

35+
/**
36+
* You can top up your account using this API when you have enabled auto-reload in the dashboard.
37+
* The amount added by the top-up operation will be the same amount as was added in the payment when
38+
* auto-reload was enabled. Your account balance is checked every 5-10 minutes and if it falls below the
39+
* threshold and auto-reload is enabled, then it will be topped up automatically. Use this method if you
40+
* need to top up at times when your credit may be exhausted more quickly than the auto-reload may occur.
41+
*
42+
* @param transactionId The top-up transaction ID.
43+
*
44+
* @throws [AccountResponseException] If the top-up operation fails.
45+
*/
2446
fun topUp(transactionId: String): Unit = client.topUp(transactionId)
2547

48+
/**
49+
* Updates the top-level account settings. Namely, the URLs for incoming SMS and delivery receipts.
50+
*
51+
* @param incomingSmsUrl The URL to which incoming SMS messages are sent when using SMS API.
52+
* @param deliverReceiptUrl The URL to which delivery receipts are sent when using SMS API.
53+
*
54+
* @return The updated account settings.
55+
*
56+
* @throws [AccountResponseException] If the account settings could not be updated.
57+
*/
2658
fun updateSettings(incomingSmsUrl: String? = null, deliverReceiptUrl: String? = null): SettingsResponse =
2759
client.updateSettings(SettingsRequest(incomingSmsUrl, deliverReceiptUrl))
2860

61+
/**
62+
* Call this method to work with account secrets.
63+
*
64+
* @param apiKey (OPTIONAL) The account API key to manage secrets for. If not provided,
65+
* the default API key (as supplied in the top-level [Vonage] client) will be used.
66+
*
67+
* @return A [Secrets] object with methods to interact with account secrets.
68+
*/
2969
fun secrets(apiKey: String? = null): Secrets = Secrets(apiKey)
3070

71+
/**
72+
* Class for working with account secrets.
73+
*
74+
* @property apiKey The account API key to manage secrets for. If not provided,
75+
* the default API key (as supplied in the top-level [Vonage] client) will be used.
76+
*/
3177
inner class Secrets internal constructor(val apiKey: String? = null) {
3278

79+
/**
80+
* Retrieves secrets for the account.
81+
*
82+
* @return A list of secrets details.
83+
*
84+
* @throws [AccountResponseException] If the secrets cannot be retrieved.
85+
*/
3386
fun list(): List<SecretResponse> = (
3487
if (apiKey == null) client.listSecrets()
3588
else client.listSecrets(apiKey)
3689
).secrets
3790

91+
/**
92+
* Creates a new secret for the account.
93+
*
94+
* @param secret The secret value to associate with the API key, which must follow these rules:
95+
* - Minimum 8 characters
96+
* - Maximum 25 characters
97+
* - Minimum 1 lower case character
98+
* - Minimum 1 upper case character
99+
* - Minimum 1 digit
100+
*
101+
* @return The created secret's metadata.
102+
*
103+
* @throws [AccountResponseException] If the secret cannot be created.
104+
*/
38105
fun create(secret: String): SecretResponse =
39106
if (apiKey == null) client.createSecret(secret)
40107
else client.createSecret(apiKey, secret)
41108

109+
/**
110+
* Retrieves a secret by its ID.
111+
*
112+
* @param secretId ID of the secret to retrieve.
113+
*
114+
* @return The secret's metadata.
115+
*
116+
* @throws [AccountResponseException] If the secret cannot be retrieved.
117+
*/
42118
fun get(secretId: String): SecretResponse =
43119
if (apiKey == null) client.getSecret(secretId)
44120
else client.getSecret(apiKey, secretId)
45121

122+
/**
123+
* Deletes a secret by its ID.
124+
*
125+
* @param secretId ID of the secret to delete.
126+
*
127+
* @throws [AccountResponseException] If the secret cannot be deleted.
128+
*/
46129
fun delete(secretId: String): Unit =
47130
if (apiKey == null) client.revokeSecret(secretId)
48131
else client.revokeSecret(apiKey, secretId)

0 commit comments

Comments
 (0)