bigdatacloud 1.0.0

Official Rust SDK for BigDataCloud APIs — IP Geolocation, Reverse Geocoding, Phone & Email Verification, Network Engineering
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

use std::collections::HashMap;
use crate::http_client::HttpClient;
use crate::error::{Error, Result};
use crate::models::{PhoneValidationResponse, EmailVerificationResponse};

/// Phone & Email Verification package — 3 endpoints.
#[derive(Clone)]
pub struct VerificationApi {
    http: HttpClient,
}

impl VerificationApi {
    pub fn new(http: HttpClient) -> Self { Self { http } }

    /// Validates a phone number. `country_code` (e.g. "AU") is required.
    /// If you know the caller's IP but not their country, use [`validate_phone_by_ip`] instead.
    pub fn validate_phone(&self, phone_number: &str, country_code: &str) -> Result<PhoneValidationResponse> {
        if phone_number.trim().is_empty() {
            return Err(Error::Api { status_code: 0, endpoint: "validate_phone".to_string(), body: "phone_number must not be empty".to_string() });
        }
        if country_code.trim().is_empty() {
            return Err(Error::Api { status_code: 0, endpoint: "validate_phone".to_string(),
                body: "country_code is required for validate_phone (e.g. \"AU\"). If you know the caller's IP, use validate_phone_by_ip instead.".to_string() });
        }
        let mut p = HashMap::new();
        p.insert("number".to_string(), phone_number.to_string());
        p.insert("countryCode".to_string(), country_code.to_string());
        self.http.get("phone-number-validate", p)
    }

    /// Validates a phone number using `ip` for country detection.
    /// `ip` must be the end user's IP address — never the server's.
    pub fn validate_phone_by_ip(&self, phone_number: &str, ip: &str) -> Result<PhoneValidationResponse> {
        if phone_number.trim().is_empty() {
            return Err(Error::Api { status_code: 0, endpoint: "validate_phone_by_ip".to_string(), body: "phone_number must not be empty".to_string() });
        }
        if ip.trim().is_empty() {
            return Err(Error::Api { status_code: 0, endpoint: "validate_phone_by_ip".to_string(),
                body: "ip is required for validate_phone_by_ip — pass the end user's IP. If you know the country, use validate_phone instead.".to_string() });
        }
        let mut p = HashMap::new();
        p.insert("number".to_string(), phone_number.to_string());
        p.insert("ip".to_string(), ip.to_string());
        self.http.get("phone-number-validate-by-ip", p)
    }

    /// Verifies an email address — checks syntax, mail server, and disposable status.
    pub fn verify_email(&self, email_address: &str) -> Result<EmailVerificationResponse> {
        if email_address.trim().is_empty() {
            return Err(Error::Api { status_code: 0, endpoint: "verify_email".to_string(), body: "email_address must not be empty".to_string() });
        }
        let mut p = HashMap::new();
        p.insert("emailAddress".to_string(), email_address.to_string());
        self.http.get("email-verify", p)
    }
}