ipwhois-rust 1.2.0

//! Deserialized response types for the ipwhois.io API.
//!
//! Every field is an [`Option`] because the API only returns the fields you
//! ask for when the `fields` parameter is set, and several blocks
//! (`security`, `rate`) are gated on plan tier. An [`extra`](LookupResponse::extra)
//! map captures any future fields not yet known to this crate, so a server-
//! side schema bump never breaks existing callers.

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Successful lookup response, or a per-IP entry inside a bulk response.
///
/// In the bulk endpoint each array entry is a `LookupResponse`; entries with
/// `success = false` carry the `message` and `error_type` fields populated by
/// the API instead of the geolocation fields.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct LookupResponse {
    /// `true` for successful lookups; `false` for per-IP errors inside a
    /// bulk response (e.g. "Invalid IP address", "Reserved range").
    #[serde(default)]
    pub success: bool,

    /// The IP address that was looked up. Echoed back by the API.
    pub ip: Option<String>,

    /// `"IPv4"` or `"IPv6"`.
    #[serde(rename = "type")]
    pub ip_type: Option<String>,

    pub continent: Option<String>,
    pub continent_code: Option<String>,
    pub country: Option<String>,
    pub country_code: Option<String>,
    pub region: Option<String>,
    pub region_code: Option<String>,
    pub city: Option<String>,

    pub latitude: Option<f64>,
    pub longitude: Option<f64>,

    pub is_eu: Option<bool>,
    pub postal: Option<String>,
    pub calling_code: Option<String>,
    pub capital: Option<String>,
    /// Comma-separated list of bordering country codes (e.g. `"CA,MX"`).
    pub borders: Option<String>,

    pub flag: Option<Flag>,
    pub connection: Option<Connection>,
    pub timezone: Option<Timezone>,
    pub currency: Option<Currency>,
    pub security: Option<Security>,
    pub rate: Option<Rate>,

    /// Populated when `success = false` (per-IP error inside a bulk response).
    pub message: Option<String>,
    /// Populated alongside `message` when the API tags the error type.
    pub error_type: Option<String>,

    /// Forward-compatibility bucket for any fields not yet modelled by this
    /// crate. New API fields land here without requiring a release.
    #[serde(flatten)]
    pub extra: HashMap<String, serde_json::Value>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Flag {
    pub img: Option<String>,
    pub emoji: Option<String>,
    pub emoji_unicode: Option<String>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Connection {
    pub asn: Option<u64>,
    pub org: Option<String>,
    pub isp: Option<String>,
    pub domain: Option<String>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Timezone {
    pub id: Option<String>,
    pub abbr: Option<String>,
    pub is_dst: Option<bool>,
    pub offset: Option<i64>,
    pub utc: Option<String>,
    pub current_time: Option<String>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Currency {
    pub name: Option<String>,
    pub code: Option<String>,
    pub symbol: Option<String>,
    pub plural: Option<String>,
    pub exchange_rate: Option<f64>,
}

/// Threat-detection block. Returned only when the `security` option is
/// enabled and the API key has Business+ access.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Security {
    pub anonymous: Option<bool>,
    pub proxy: Option<bool>,
    pub vpn: Option<bool>,
    pub tor: Option<bool>,
    pub hosting: Option<bool>,
}

/// Rate-limit block. Returned only when the `rate` option is enabled and
/// the API key has Basic+ access.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Rate {
    pub limit: Option<u64>,
    pub remaining: Option<u64>,
}