diff --git a/README.md b/README.md index caec647..71f41cb 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ A Kotlin/Java client library for interacting with the [CloudContactAI](https://c - Campaign registration and management for TCR carrier vetting - Manage webhooks for event notifications - Webhook signature validation for security +- Validate email addresses (valid/invalid/risky) and phone numbers (valid/invalid/landline) - Variable substitution in messages - Test environment support - Comprehensive error handling @@ -300,6 +301,40 @@ val singleResponse = ccai.mms.sendSingle( ) ``` +#### Contact Validator + +Validate email addresses and phone numbers. + +> Bulk endpoints accept up to 50 contacts per request and are processed server-side in chunks. + +```kotlin +import com.cloudcontactai.sdk.contactvalidator.PhoneInput + +// Validate a single email +val emailResult = ccai.contactValidator.validateEmail("user@example.com") +println(emailResult.status) // "valid" | "invalid" | "risky" +println(emailResult.metadata["safe_to_send"]) // true | false + +// Validate multiple emails (up to 50, processed server-side in chunks) +val bulkEmails = ccai.contactValidator.validateEmails(listOf( + "user@example.com", + "bad@invalid.xyz" +)) +println(bulkEmails.summary) // ValidationSummary(total=2, valid=1, invalid=1, risky=0, landline=0) + +// Validate a single phone number +val phoneResult = ccai.contactValidator.validatePhone("+15551234567", countryCode = "US") +println(phoneResult.status) // "valid" | "invalid" | "landline" +println(phoneResult.metadata["carrier_type"]) // "mobile" | "landline" | "voip" + +// Validate multiple phone numbers (up to 50, processed server-side in chunks) +val bulkPhones = ccai.contactValidator.validatePhones(listOf( + PhoneInput(phone = "+15551234567"), + PhoneInput(phone = "+15559876543", countryCode = "US") +)) +println(bulkPhones.summary) // ValidationSummary(total=2, valid=1, invalid=0, risky=0, landline=1) +``` + #### Webhook Management ```kotlin diff --git a/pom.xml b/pom.xml index 17146bb..c302f6d 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ com.cloudcontactai ccai-java-sdk - 1.0.9 + 1.1.0 jar CCAI Java SDK diff --git a/src/main/kotlin/com/cloudcontactai/sdk/CCAIClient.kt b/src/main/kotlin/com/cloudcontactai/sdk/CCAIClient.kt index 8ec52f5..c87aaad 100644 --- a/src/main/kotlin/com/cloudcontactai/sdk/CCAIClient.kt +++ b/src/main/kotlin/com/cloudcontactai/sdk/CCAIClient.kt @@ -3,6 +3,7 @@ package com.cloudcontactai.sdk import com.cloudcontactai.sdk.common.ApiClient import com.cloudcontactai.sdk.common.CCAIConfig import com.cloudcontactai.sdk.contact.ContactService +import com.cloudcontactai.sdk.contactvalidator.ContactValidatorService import com.cloudcontactai.sdk.sms.SMSService import com.cloudcontactai.sdk.email.EmailService import com.cloudcontactai.sdk.webhook.WebhookService @@ -12,7 +13,7 @@ import com.cloudcontactai.sdk.campaigns.CampaignService class CCAIClient(private val config: CCAIConfig) { private val apiClient = ApiClient(config) - + val sms = SMSService(config, apiClient) val email = EmailService(config, apiClient) val webhook = WebhookService(config, apiClient) @@ -20,7 +21,8 @@ class CCAIClient(private val config: CCAIConfig) { val contact = ContactService(config, apiClient) val brands = BrandService(config, apiClient) val campaigns = CampaignService(config, apiClient) - + val contactValidator = ContactValidatorService(config, apiClient) + fun close() { // Cleanup resources if needed } diff --git a/src/main/kotlin/com/cloudcontactai/sdk/contactvalidator/ContactValidatorModels.kt b/src/main/kotlin/com/cloudcontactai/sdk/contactvalidator/ContactValidatorModels.kt new file mode 100644 index 0000000..c74a3fc --- /dev/null +++ b/src/main/kotlin/com/cloudcontactai/sdk/contactvalidator/ContactValidatorModels.kt @@ -0,0 +1,38 @@ +package com.cloudcontactai.sdk.contactvalidator + +data class EmailValidationResult( + val contactField: String, + val type: String, + val status: String, + val metadata: Map = emptyMap() +) + +data class PhoneValidationResult( + val contactField: String, + val type: String, + val status: String, + val metadata: Map = emptyMap() +) + +data class ValidationSummary( + val total: Int, + val valid: Int, + val invalid: Int, + val risky: Int, + val landline: Int = 0 +) + +data class BulkEmailValidationResult( + val results: List, + val summary: ValidationSummary +) + +data class BulkPhoneValidationResult( + val results: List, + val summary: ValidationSummary +) + +data class PhoneInput( + val phone: String, + val countryCode: String? = null +) diff --git a/src/main/kotlin/com/cloudcontactai/sdk/contactvalidator/ContactValidatorService.kt b/src/main/kotlin/com/cloudcontactai/sdk/contactvalidator/ContactValidatorService.kt new file mode 100644 index 0000000..b74e5ac --- /dev/null +++ b/src/main/kotlin/com/cloudcontactai/sdk/contactvalidator/ContactValidatorService.kt @@ -0,0 +1,39 @@ +package com.cloudcontactai.sdk.contactvalidator + +import com.cloudcontactai.sdk.common.ApiClient +import com.cloudcontactai.sdk.common.CCAIConfig + +class ContactValidatorService(private val config: CCAIConfig, private val apiClient: ApiClient) { + + fun validateEmail(email: String): EmailValidationResult = + apiClient.request( + method = "POST", + endpoint = "/v1/contact-validator/email", + data = mapOf("email" to email), + responseClass = EmailValidationResult::class.java + ) + + fun validateEmails(emails: List): BulkEmailValidationResult = + apiClient.request( + method = "POST", + endpoint = "/v1/contact-validator/emails", + data = mapOf("emails" to emails), + responseClass = BulkEmailValidationResult::class.java + ) + + fun validatePhone(phone: String, countryCode: String? = null): PhoneValidationResult = + apiClient.request( + method = "POST", + endpoint = "/v1/contact-validator/phone", + data = mapOf("phone" to phone, "countryCode" to countryCode), + responseClass = PhoneValidationResult::class.java + ) + + fun validatePhones(phones: List): BulkPhoneValidationResult = + apiClient.request( + method = "POST", + endpoint = "/v1/contact-validator/phones", + data = mapOf("phones" to phones), + responseClass = BulkPhoneValidationResult::class.java + ) +}