From 7f2906eac9293b2400117b80a81c15a381d72a83 Mon Sep 17 00:00:00 2001
From: Sina Madani <sina.madani@vonage.com>
Date: Wed, 4 Sep 2024 16:38:20 +0100
Subject: [PATCH] Number Insight KDocs

---
 .../com/vonage/client/kt/NumberInsight.kt     | 50 +++++++++++++++++++
 .../kotlin/com/vonage/client/kt/VonageTest.kt |  4 +-
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/src/main/kotlin/com/vonage/client/kt/NumberInsight.kt b/src/main/kotlin/com/vonage/client/kt/NumberInsight.kt
index 8d5c054..b0fe45f 100644
--- a/src/main/kotlin/com/vonage/client/kt/NumberInsight.kt
+++ b/src/main/kotlin/com/vonage/client/kt/NumberInsight.kt
@@ -24,20 +24,70 @@ import com.vonage.client.insight.*
  */
 class NumberInsight internal constructor(private val client: InsightClient) {
 
+    /**
+     * Obtain basic insight about a number.
+     *
+     * @param number The phone number to look up in E.164 format.
+     *
+     * @param countryCode (OPTIONAL) The two-character country code in ISO 3166-1 alpha-2 format.
+     *
+     * @return Basic details about the number and insight metadata.
+     */
     fun basic(number: String, countryCode: String? = null): BasicInsightResponse =
         client.getBasicNumberInsight(number, countryCode)
 
+    /**
+     * Obtain standard insight about a number.
+     *
+     * @param number The phone number to look up in E.164 format.
+     *
+     * @param countryCode (OPTIONAL) The two-character country code in ISO 3166-1 alpha-2 format.
+     *
+     * @param cnam (OPTIONAL) Whether the name of the person who owns the phone number should be looked up
+     * and returned in the response. Set to true to receive phone number owner name in the response. This
+     * feature is available for US numbers only and incurs an additional charge.
+     *
+     * @return Standard details about the number and insight metadata.
+     */
     fun standard(number: String, countryCode: String? = null, cnam: Boolean? = null): StandardInsightResponse =
         client.getStandardNumberInsight(StandardInsightRequest.builder()
             .number(number).country(countryCode).cnam(cnam).build()
         )
 
+    /**
+     * Obtain advanced insight about a number synchronously. This is not recommended due to potential timeouts.
+     *
+     * @param number The phone number to look up in E.164 format.
+     *
+     * @param countryCode (OPTIONAL) The two-character country code in ISO 3166-1 alpha-2 format.
+     *
+     * @param cnam (OPTIONAL) Whether the name of the person who owns the phone number should be looked up
+     * and returned in the response. Set to true to receive phone number owner name in the response. This
+     * feature is available for US numbers only and incurs an additional charge.
+     *
+     * @param realTimeData (OPTIONAL) Whether to receive real-time data back in the response.
+     *
+     * @return Advanced details about the number and insight metadata.
+     */
     fun advanced(number: String, countryCode: String? = null, cnam: Boolean = false,
                  realTimeData: Boolean = false): AdvancedInsightResponse =
         client.getAdvancedNumberInsight(AdvancedInsightRequest.builder().async(false)
             .number(number).country(countryCode).cnam(cnam).realTimeData(realTimeData).build()
         )
 
+    /**
+     * Obtain advanced insight about a number asynchronously. This is recommended to avoid timeouts.
+     *
+     * @param number The phone number to look up in E.164 format.
+     *
+     * @param callbackUrl The URL to which the response will be sent.
+     *
+     * @param countryCode (OPTIONAL) The two-character country code in ISO 3166-1 alpha-2 format.
+     *
+     * @param cnam (OPTIONAL) Whether the name of the person who owns the phone number should be looked up
+     * and returned in the response. Set to true to receive phone number owner name in the response. This
+     * feature is available for US numbers only and incurs an additional charge.
+     */
     fun advancedAsync(number: String, callbackUrl: String, countryCode: String? = null, cnam: Boolean = false) {
         client.getAdvancedNumberInsight(
             AdvancedInsightRequest.builder().async(true)
diff --git a/src/test/kotlin/com/vonage/client/kt/VonageTest.kt b/src/test/kotlin/com/vonage/client/kt/VonageTest.kt
index c991ce7..58317d8 100644
--- a/src/test/kotlin/com/vonage/client/kt/VonageTest.kt
+++ b/src/test/kotlin/com/vonage/client/kt/VonageTest.kt
@@ -21,7 +21,7 @@ class VonageTest {
 
     @Test
     fun `live testing placeholder`() {
-        val client = Vonage { authFromEnv() }
-
+        val client = Vonage { authFromEnv(); signatureSecret(null) }
+        println("Finished") // Place debug breakpoint here
     }
 }
\ No newline at end of file