From 550067f735fca7d592c756b0411ce1f61a40108a Mon Sep 17 00:00:00 2001 From: Sina Madani Date: Wed, 4 Sep 2024 16:58:49 +0100 Subject: [PATCH] Verify v1 KDocs --- CHANGELOG.md | 19 +++-- .../com/vonage/client/kt/VerifyLegacy.kt | 75 ++++++++++++++++++- 2 files changed, 82 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65ac3d5..0a7bd21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/). GA release! ### Added -- Documentation (KDocs) for all classes and methods +- Documentation (KDocs) for all classes and methods. ## [1.0.0-beta1] - 2024-09-02 Feature-complete beta release. @@ -17,7 +17,10 @@ Feature-complete beta release. - 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 @@ -36,8 +39,8 @@ Feature-complete beta release. - Account API ### Changed -- Explicit return types for all methods -- Introduced `ExistingRequest` class to Verify (v2) to reduce duplicating `requestId` parameter +- Explicit return types for all methods. +- Introduced `ExistingRequest` class to Verify (v2) to reduce duplicating `requestId` parameter. ## [0.6.0] - 2024-07-30 @@ -46,8 +49,8 @@ Feature-complete beta release. - Number Verification API ### Changed -- `InputAction.Builder#dtmf` extension method uses `DtmfSettings` builder instead of setters -- `Messages#send` now uses optional Boolean parameter for sandbox instead of separate method +- `InputAction.Builder#dtmf` extension method uses `DtmfSettings` builder instead of setters. +- `Messages#send` now uses optional Boolean parameter for sandbox instead of separate method. ## [0.5.0] - 2024-07-25 @@ -62,7 +65,7 @@ Feature-complete beta release. ## [0.3.1] - 2024-07-12 ### Changed -- Upgraded Java SDK version to 8.9.2 +- Upgraded Java SDK version to 8.9.2. ## [0.3.0] - 2024-07-08 @@ -81,7 +84,7 @@ Feature-complete beta release. - Voice API ### Fixed -- `authFromEnv` now checks for absent environment variables before attempting to set them +- `authFromEnv` now checks for absent environment variables before attempting to set them. ## [0.1.0] - 2024-06-25 Initial version. diff --git a/src/main/kotlin/com/vonage/client/kt/VerifyLegacy.kt b/src/main/kotlin/com/vonage/client/kt/VerifyLegacy.kt index ff31a13..c243658 100644 --- a/src/main/kotlin/com/vonage/client/kt/VerifyLegacy.kt +++ b/src/main/kotlin/com/vonage/client/kt/VerifyLegacy.kt @@ -24,27 +24,94 @@ import com.vonage.client.verify.* */ class VerifyLegacy internal constructor(private val client: VerifyClient) { + /** + * Initiate a verification request. + * + * @param number The phone number to verify in E.164 format. + * + * @param brand The name of the company or app sending the verification request. + * This is what the user will see the sender as on their device. + * + * @param properties A lambda function for specifying additional parameters of the request. + * + * @return A [VerifyResponse] object containing the request ID and status. + */ fun verify(number: String, brand: String, properties: (VerifyRequest.Builder.() -> Unit) = {}): VerifyResponse = client.verify(VerifyRequest.builder(number, brand).apply(properties).build()) + /** + * Generate and send a PIN to your user to authorize a payment, compliant with Payment Services Directive 2. + * + * @param number The phone number to send the request to, in E.164 format. + * + * @param amount The decimal amount of the payment to be confirmed, in Euros. + * + * @param payee Name of the recipient that the user is confirming a payment to. + * + * @param properties (OPTIONAL) A lambda function for specifying additional parameters of the request. + * + * @return A [VerifyResponse] object containing the request ID and status. + */ fun psd2Verify(number: String, amount: Double, payee: String, properties: (Psd2Request.Builder.() -> Unit) = {}): VerifyResponse = client.psd2Verify(Psd2Request.builder(number, amount, payee).apply(properties).build()) + /** + * Use this method to check the status of past or current verification requests. + * + * @param requestIds One or more request IDs to check. + * + * @return Information about the verification request(s). + * + * @see [ExistingRequest.info] An alias for this method. + */ fun search(vararg requestIds: String): SearchVerifyResponse = client.search(*requestIds) - fun request(requestId: String): ExistingRequest = ExistingRequest(requestId) - + /** + * Call this method to work with an existing verification request. + * + * @param response Response object containing the request ID. + */ fun request(response: VerifyResponse): ExistingRequest = request(response.requestId) + /** + * Call this method to work with an existing verification request. + * + * @param requestId ID of the verification request to work with. + */ + fun request(requestId: String): ExistingRequest = ExistingRequest(requestId) + + /** + * Call this method to work with an existing verification request. + * + * @param id ID of the verification request to work with. + */ inner class ExistingRequest internal constructor(id: String): ExistingResource(id) { + /** + * Retrieve details about the verification request. + * + * @return Information about the verification request. + * + * @see [search] An alias for this method. + */ + fun info(): SearchVerifyResponse = client.search(id) + + /** + * Cancel the verification request. + */ fun cancel(): ControlResponse = client.cancelVerification(id) + /** + * Trigger the next verification step. + */ fun advance(): ControlResponse = client.advanceVerification(id) + /** + * Check the verification code. + * + * @param code PIN code to check, as entered by the user. + */ fun check(code: String): CheckResponse = client.check(id, code) - - fun search(): SearchVerifyResponse = client.search(id) } } \ No newline at end of file