OASystemAPI/OASystem/OASystem.Api/OAMethodLib/SnovioAPI/SnovioModels.cs

using System.Text.Json;
using System.Text.Json.Serialization;

namespace OASystem.API.OAMethodLib.SnovioAPI;

/// <summary>
/// Snov.io OAuth access_token 请求体。
/// </summary>
public sealed class SnovioAccessTokenRequest
{
    /// <summary>
    /// OAuth 授权类型，固定为 client_credentials。
    /// </summary>
    [JsonPropertyName("grant_type")]
    public string GrantType { get; set; } = "client_credentials";

    /// <summary>
    /// Snov.io Client ID。
    /// </summary>
    [JsonPropertyName("client_id")]
    public string ClientId { get; set; } = string.Empty;

    /// <summary>
    /// Snov.io Client Secret。
    /// </summary>
    [JsonPropertyName("client_secret")]
    public string ClientSecret { get; set; } = string.Empty;
}

/// <summary>
/// Snov.io OAuth access_token 响应体。
/// </summary>
public sealed class SnovioAccessTokenResponse
{
    /// <summary>
    /// 访问令牌。
    /// </summary>
    [JsonPropertyName("access_token")]
    public string AccessToken { get; set; } = string.Empty;

    /// <summary>
    /// 令牌类型，通常为 Bearer。
    /// </summary>
    [JsonPropertyName("token_type")]
    public string TokenType { get; set; } = string.Empty;

    /// <summary>
    /// 令牌有效期，单位为秒。
    /// </summary>
    [JsonPropertyName("expires_in")]
    public int ExpiresIn { get; set; }
}

/// <summary>
/// Snov.io 公司数据库搜索请求体。
/// </summary>
public sealed class SnovioCompanySearchRequest
{
    /// <summary>
    /// 结果页码，默认从第 1 页开始。
    /// </summary>
    [JsonPropertyName("page")]
    public int Page { get; set; } = 1;

    /// <summary>
    /// 可选的异步结果回调地址。
    /// </summary>
    [JsonPropertyName("webhook_url")]
    public string? WebhookUrl { get; set; }

    /// <summary>
    /// 公司搜索筛选条件。
    /// </summary>
    [JsonPropertyName("filters")]
    public SnovioCompanySearchFilters Filters { get; set; } = new();
}

/// <summary>
/// Snov.io 公司数据库搜索筛选条件。
/// </summary>
public sealed class SnovioCompanySearchFilters
{
    /// <summary>
    /// 公司名称、行业、规模、营收和成立年份等筛选条件。
    /// </summary>
    [JsonPropertyName("company")]
    public SnovioCompanyFilter Company { get; set; } = new();

    /// <summary>
    /// 公司所在地区的包含和排除条件。
    /// </summary>
    [JsonPropertyName("locations")]
    public SnovioLocationFilter Locations { get; set; } = new();
}

/// <summary>
/// 公司筛选条件。
/// </summary>
public sealed class SnovioCompanyFilter
{
    /// <summary>
    /// 公司名称包含或排除列表。
    /// </summary>
    [JsonPropertyName("name")]
    public SnovioStringListFilter? Name { get; set; }

    /// <summary>
    /// 公司行业包含或排除列表。
    /// </summary>
    [JsonPropertyName("industries")]
    public SnovioStringListFilter? Industries { get; set; }

    /// <summary>
    /// 公司规模数组，例如 ["1-10", "51-200", "10001+", "Self"]。
    /// Snovio 要求数组格式，单值也请传单元素数组。
    /// </summary>
    [JsonPropertyName("size")]
    public List<string>? Size { get; set; }

    /// <summary>
    /// 公司营收最小值和最大值，单位由 Snov.io 数据源定义。
    /// </summary>
    [JsonPropertyName("revenue")]
    public SnovioRevenueFilter? Revenue { get; set; }

    /// <summary>
    /// 公司专长或业务领域列表。
    /// </summary>
    [JsonPropertyName("specialities")]
    public List<string> Specialities { get; set; } = new();

    /// <summary>
    /// 公司成立年份范围。
    /// </summary>
    [JsonPropertyName("founded")]
    public SnovioFoundedFilter? Founded { get; set; }
}

/// <summary>
/// 字符串列表包含/排除条件。
/// </summary>
public sealed class SnovioStringListFilter
{
    /// <summary>
    /// 需要匹配的字符串列表。
    /// </summary>
    [JsonPropertyName("include")]
    public List<string> Include { get; set; } = new();

    /// <summary>
    /// 需要排除的字符串列表。
    /// </summary>
    [JsonPropertyName("exclude")]
    public List<string> Exclude { get; set; } = new();
}

/// <summary>
/// 地区包含/排除条件。
/// </summary>
public sealed class SnovioLocationFilter
{
    /// <summary>
    /// 需要包含的地区条件。
    /// </summary>
    [JsonPropertyName("include")]
    public SnovioLocationFilterItem? Include { get; set; }

    /// <summary>
    /// 需要排除的地区条件。
    /// </summary>
    [JsonPropertyName("exclude")]
    public SnovioLocationFilterItem? Exclude { get; set; }
}

/// <summary>
/// 地区条件明细。
/// </summary>
public sealed class SnovioLocationFilterItem
{
    /// <summary>
    /// 地区名称，例如 London 或 Atlanta。
    /// </summary>
    [JsonPropertyName("locality")]
    public string? Locality { get; set; }

    /// <summary>
    /// 地区类型，例如 city、state、country、region、subregion。
    /// </summary>
    [JsonPropertyName("location_type")]
    public string? LocationType { get; set; }
}

/// <summary>
/// 公司营收范围。
/// </summary>
public sealed class SnovioRevenueFilter
{
    /// <summary>
    /// 营收下限。
    /// </summary>
    [JsonPropertyName("min")]
    public long? Min { get; set; }

    /// <summary>
    /// 营收上限。
    /// </summary>
    [JsonPropertyName("max")]
    public long? Max { get; set; }
}

/// <summary>
/// 公司成立年份范围。
/// </summary>
public sealed class SnovioFoundedFilter
{
    /// <summary>
    /// 成立年份下限。
    /// </summary>
    [JsonPropertyName("from")]
    public int? From { get; set; }

    /// <summary>
    /// 成立年份上限。
    /// </summary>
    [JsonPropertyName("till")]
    public int? Till { get; set; }
}

/// <summary>
/// Snov.io 公司搜索创建任务响应体。
/// </summary>
public sealed class SnovioCompanySearchStartResponse
{
    /// <summary>
    /// 创建任务时通常为空数组。
    /// </summary>
    [JsonPropertyName("data")]
    public List<JsonElement> Data { get; set; } = new();

    /// <summary>
    /// 创建任务的元数据，包含 task_hash 和页码。
    /// </summary>
    [JsonPropertyName("meta")]
    public SnovioCompanySearchStartMeta Meta { get; set; } = new();

    /// <summary>
    /// Snov.io 返回的结果查询地址。
    /// </summary>
    [JsonPropertyName("links")]
    public SnovioApiLinks Links { get; set; } = new();

    /// <summary>
    /// 创建任务响应状态。
    /// </summary>
    [JsonPropertyName("status")]
    public string? Status { get; set; }
}

/// <summary>
/// Snov.io 公司搜索创建任务元数据。
/// </summary>
public sealed class SnovioCompanySearchStartMeta
{
    /// <summary>
    /// 异步公司搜索任务唯一标识，用于查询结果。
    /// </summary>
    [JsonPropertyName("task_hash")]
    public string? TaskHash { get; set; }

    /// <summary>
    /// 本次搜索请求的结果页码。
    /// </summary>
    [JsonPropertyName("page")]
    public int Page { get; set; }
}

/// <summary>
/// Snov.io 公司搜索结果响应体。
/// </summary>
public sealed class SnovioCompanySearchResultResponse
{
    /// <summary>
    /// 公司搜索结果数据。
    /// </summary>
    [JsonPropertyName("data")]
    public SnovioCompanySearchResultData Data { get; set; } = new();

    /// <summary>
    /// 公司搜索任务元数据。
    /// </summary>
    [JsonPropertyName("meta")]
    public SnovioCompanySearchResultMeta Meta { get; set; } = new();

    /// <summary>
    /// 文档示例中该字段为空数组。
    /// </summary>
    [JsonPropertyName("links")]
    public List<JsonElement> Links { get; set; } = new();

    /// <summary>
    /// 任务处理状态，例如 completed 或 in_progress。
    /// </summary>
    [JsonPropertyName("status")]
    public string? Status { get; set; }
}

/// <summary>
/// 公司搜索结果数据。
/// 兼容 Snov.io 任务处理中时 data 为空数组的响应。
/// </summary>
[System.Text.Json.Serialization.JsonConverter(typeof(SnovioCompanySearchResultDataConverter))]
public sealed class SnovioCompanySearchResultData
{
    /// <summary>
    /// 符合筛选条件的公司总数。
    /// </summary>
    [JsonPropertyName("total")]
    public long Total { get; set; }

    /// <summary>
    /// 当前结果页码。
    /// </summary>
    [JsonPropertyName("page")]
    public int Page { get; set; }

    /// <summary>
    /// 结果总页数。
    /// </summary>
    [JsonPropertyName("total_pages")]
    public int TotalPages { get; set; }

    /// <summary>
    /// 当前页的公司列表。
    /// </summary>
    [JsonPropertyName("companies")]
    public List<SnovioCompanySearchCompany> Companies { get; set; } = new();
}

/// <summary>
/// 兼容 Snov.io 公司搜索结果中 data 为对象、空数组或 null 的响应转换器。
/// 任务处理中（in_progress）时 Snovio 返回 "data": []，此时按空结果处理，由轮询继续等待。
/// </summary>
internal sealed class SnovioCompanySearchResultDataConverter
    : System.Text.Json.Serialization.JsonConverter<SnovioCompanySearchResultData>
{
    public override SnovioCompanySearchResultData Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options)
    {
        if (reader.TokenType == JsonTokenType.Null)
            return new SnovioCompanySearchResultData();

        if (reader.TokenType == JsonTokenType.StartArray)
        {
            // 处理中返回空数组，直接跳过。
            using var _ = JsonDocument.ParseValue(ref reader);
            return new SnovioCompanySearchResultData();
        }

        if (reader.TokenType == JsonTokenType.StartObject)
        {
            using var document = JsonDocument.ParseValue(ref reader);
            var root = document.RootElement;
            var result = new SnovioCompanySearchResultData();

            if (root.TryGetProperty("total", out var totalElement) &&
                totalElement.ValueKind == JsonValueKind.Number &&
                totalElement.TryGetInt64(out var total))
            {
                result.Total = total;
            }

            if (root.TryGetProperty("page", out var pageElement) &&
                pageElement.ValueKind == JsonValueKind.Number &&
                pageElement.TryGetInt32(out var page))
            {
                result.Page = page;
            }

            if (root.TryGetProperty("total_pages", out var totalPagesElement) &&
                totalPagesElement.ValueKind == JsonValueKind.Number &&
                totalPagesElement.TryGetInt32(out var totalPages))
            {
                result.TotalPages = totalPages;
            }

            if (root.TryGetProperty("companies", out var companiesElement) &&
                companiesElement.ValueKind == JsonValueKind.Array)
            {
                result.Companies = companiesElement.Deserialize<List<SnovioCompanySearchCompany>>(options)
                                   ?? new List<SnovioCompanySearchCompany>();
            }

            return result;
        }

        throw new System.Text.Json.JsonException(
            "Snov.io 公司搜索结果响应中的 data 必须是对象、数组或 null。");
    }

    public override void Write(
        Utf8JsonWriter writer,
        SnovioCompanySearchResultData value,
        JsonSerializerOptions options)
    {
        writer.WriteStartObject();
        writer.WriteNumber("total", value.Total);
        writer.WriteNumber("page", value.Page);
        writer.WriteNumber("total_pages", value.TotalPages);
        writer.WritePropertyName("companies");
        System.Text.Json.JsonSerializer.Serialize(writer, value.Companies, options);
        writer.WriteEndObject();
    }
}

/// <summary>
/// Snov.io 公司搜索结果中的公司信息。
/// </summary>
public sealed class SnovioCompanySearchCompany
{
    /// <summary>
    /// 公司名称。
    /// </summary>
    [JsonPropertyName("name")]
    public string? Name { get; set; }

    /// <summary>
    /// 公司域名。
    /// </summary>
    [JsonPropertyName("domain")]
    public string? Domain { get; set; }

    /// <summary>
    /// 公司所在地区。
    /// </summary>
    [JsonPropertyName("location")]
    public string? Location { get; set; }

    /// <summary>
    /// 公司所属行业。
    /// </summary>
    [JsonPropertyName("industry")]
    public string? Industry { get; set; }

    /// <summary>
    /// 公司规模。
    /// </summary>
    [JsonPropertyName("size")]
    public string? Size { get; set; }

    /// <summary>
    /// 公司营收信息。
    /// </summary>
    [JsonPropertyName("revenue")]
    public SnovioCompanyRevenue? Revenue { get; set; }

    /// <summary>
    /// 公司 Logo 地址。
    /// </summary>
    [JsonPropertyName("logo_url")]
    public string? LogoUrl { get; set; }
}

/// <summary>
/// 公司搜索结果中的公司营收信息。
/// </summary>
public sealed class SnovioCompanyRevenue
{
    /// <summary>
    /// 营收区间下限。
    /// </summary>
    [JsonPropertyName("min")]
    public long? Min { get; set; }

    /// <summary>
    /// 营收区间上限。
    /// </summary>
    [JsonPropertyName("max")]
    public long? Max { get; set; }

    /// <summary>
    /// Snov.io 返回的营收值。
    /// </summary>
    [JsonPropertyName("reported")]
    public long? Reported { get; set; }
}

/// <summary>
/// 公司搜索结果元数据。
/// </summary>
public sealed class SnovioCompanySearchResultMeta
{
    /// <summary>
    /// 异步公司搜索任务唯一标识。
    /// </summary>
    [JsonPropertyName("task_hash")]
    public string? TaskHash { get; set; }

    /// <summary>
    /// 当前结果页码。
    /// </summary>
    [JsonPropertyName("page")]
    public int Page { get; set; }
}

/// <summary>
/// Snov.io 域名潜在客户搜索请求体。
/// </summary>
public sealed class SnovioDomainProspectsSearchRequest
{
    /// <summary>
    /// 要搜索的公司域名，例如 snov.io。
    /// </summary>
    [JsonPropertyName("domain")]
    public string Domain { get; set; } = string.Empty;

    /// <summary>
    /// 结果页码，默认从第 1 页开始。
    /// </summary>
    [JsonPropertyName("page")]
    public int Page { get; set; } = 1;

    /// <summary>
    /// 潜在客户职位列表，最多 10 个。
    /// </summary>
    [JsonPropertyName("positions")]
    public List<string> Positions { get; set; } = new();

    /// <summary>
    /// 可选的异步结果回调地址。
    /// </summary>
    [JsonPropertyName("webhook_url")]
    public string? WebhookUrl { get; set; }
}

/// <summary>
/// Snov.io 域名潜在客户搜索创建任务响应体。
/// </summary>
public sealed class SnovioDomainProspectsSearchStartResponse
{
    /// <summary>
    /// 创建任务时通常为空数组。
    /// </summary>
    [JsonPropertyName("data")]
    public List<JsonElement> Data { get; set; } = new();

    /// <summary>
    /// 创建任务的元数据，包含域名、页码、职位和 task_hash。
    /// </summary>
    [JsonPropertyName("meta")]
    public SnovioDomainProspectsSearchStartMeta Meta { get; set; } = new();

    /// <summary>
    /// Snov.io 返回的结果查询地址。
    /// </summary>
    [JsonPropertyName("links")]
    public SnovioApiLinks Links { get; set; } = new();

    /// <summary>
    /// 创建任务响应状态。
    /// </summary>
    [JsonPropertyName("status")]
    public string? Status { get; set; }
}

/// <summary>
/// Snov.io 域名潜在客户搜索创建任务元数据。
/// </summary>
public sealed class SnovioDomainProspectsSearchStartMeta
{
    /// <summary>
    /// 本次搜索的公司域名。
    /// </summary>
    [JsonPropertyName("domain")]
    public string? Domain { get; set; }

    /// <summary>
    /// 结果类型，潜客搜索通常为 prospects。
    /// </summary>
    [JsonPropertyName("tab")]
    public string? Tab { get; set; }

    /// <summary>
    /// 异步域名潜客搜索任务唯一标识。
    /// </summary>
    [JsonPropertyName("task_hash")]
    public string? TaskHash { get; set; }

    /// <summary>
    /// 本次搜索请求的结果页码。
    /// </summary>
    [JsonPropertyName("page")]
    public int Page { get; set; }

    /// <summary>
    /// 用于筛选潜客的职位列表。
    /// </summary>
    [JsonPropertyName("positions")]
    public List<string> Positions { get; set; } = new();
}

/// <summary>
/// Snov.io 域名潜在客户搜索结果响应体。
/// </summary>
public sealed class SnovioDomainProspectsSearchResultResponse
{
    /// <summary>
    /// 当前页的潜在客户列表。
    /// </summary>
    [JsonPropertyName("data")]
    public List<SnovioDomainProspect> Data { get; set; } = new();

    /// <summary>
    /// 域名潜在客户搜索结果元数据。
    /// </summary>
    [JsonPropertyName("meta")]
    public SnovioDomainProspectsSearchResultMeta Meta { get; set; } = new();

    /// <summary>
    /// 下一页结果链接信息。
    /// </summary>
    [JsonPropertyName("links")]
    public SnovioApiLinks Links { get; set; } = new();

    /// <summary>
    /// 任务处理状态，例如 completed 或 in_progress。
    /// </summary>
    [JsonPropertyName("status")]
    public string? Status { get; set; }
}

/// <summary>
/// Snov.io 域名潜在客户搜索结果中的潜客信息。
/// </summary>
public sealed class SnovioDomainProspect
{
    /// <summary>
    /// 潜客名。
    /// </summary>
    [JsonPropertyName("first_name")]
    public string? FirstName { get; set; }

    /// <summary>
    /// 潜客姓。
    /// </summary>
    [JsonPropertyName("last_name")]
    public string? LastName { get; set; }

    /// <summary>
    /// 潜客职位。
    /// </summary>
    [JsonPropertyName("position")]
    public string? Position { get; set; }

    /// <summary>
    /// Snov.io 获取该潜客信息的来源页面。
    /// </summary>
    [JsonPropertyName("source_page")]
    public string? SourcePage { get; set; }

    /// <summary>
    /// 启动该潜客邮箱检索任务的地址，地址末段包含 prospect_hash。
    /// </summary>
    [JsonPropertyName("search_emails_start")]
    public string? SearchEmailsStart { get; set; }
}

/// <summary>
/// Snov.io 域名潜在客户搜索结果元数据。
/// </summary>
public sealed class SnovioDomainProspectsSearchResultMeta
{
    /// <summary>
    /// 本次搜索的公司域名。
    /// </summary>
    [JsonPropertyName("domain")]
    public string? Domain { get; set; }

    /// <summary>
    /// 结果类型，潜客搜索通常为 prospects。
    /// </summary>
    [JsonPropertyName("tab")]
    public string? Tab { get; set; }

    /// <summary>
    /// 异步域名潜客搜索任务唯一标识。
    /// </summary>
    [JsonPropertyName("task_hash")]
    public string? TaskHash { get; set; }

    /// <summary>
    /// 当前结果页码。
    /// </summary>
    [JsonPropertyName("page")]
    public int Page { get; set; }

    /// <summary>
    /// 本次搜索使用的职位筛选列表。
    /// </summary>
    [JsonPropertyName("positions")]
    public List<string> Positions { get; set; } = new();

    /// <summary>
    /// 符合条件的潜客总数。
    /// </summary>
    [JsonPropertyName("total_count")]
    public int TotalCount { get; set; }
}

/// <summary>
/// Snov.io 潜客邮箱检索请求体。
/// </summary>
public sealed class SnovioProspectEmailSearchRequest
{
    /// <summary>
    /// 可选的异步任务回调地址。
    /// </summary>
    [JsonPropertyName("webhook_url")]
    public string? WebhookUrl { get; set; }
}

/// <summary>
/// Snov.io 潜客邮箱检索创建任务响应体。
/// </summary>
public sealed class SnovioProspectEmailSearchStartResponse
{
    /// <summary>
    /// 创建任务时通常为空数组。
    /// </summary>
    [JsonPropertyName("data")]
    public List<JsonElement> Data { get; set; } = new();

    /// <summary>
    /// 创建任务的元数据，包含邮箱检索 task_hash。
    /// </summary>
    [JsonPropertyName("meta")]
    public SnovioProspectEmailSearchStartMeta Meta { get; set; } = new();

    /// <summary>
    /// Snov.io 返回的邮箱结果查询地址。
    /// </summary>
    [JsonPropertyName("links")]
    public SnovioApiLinks Links { get; set; } = new();

    /// <summary>
    /// 创建任务响应状态。
    /// </summary>
    [JsonPropertyName("status")]
    public string? Status { get; set; }
}

/// <summary>
/// Snov.io 潜客邮箱检索创建任务元数据。
/// </summary>
public sealed class SnovioProspectEmailSearchStartMeta
{
    /// <summary>
    /// 异步邮箱检索任务唯一标识，用于查询邮箱结果。
    /// </summary>
    [JsonPropertyName("task_hash")]
    public string? TaskHash { get; set; }
}

/// <summary>
/// Snov.io 潜客邮箱检索结果响应体。
/// </summary>
public sealed class SnovioProspectEmailSearchResultResponse
{
    /// <summary>
    /// 潜客邮箱检索结果数据。
    /// </summary>
    [JsonPropertyName("data")]
    public SnovioProspectEmailSearchResultData Data { get; set; } = new();

    /// <summary>
    /// 邮箱检索任务元数据。
    /// </summary>
    [JsonPropertyName("meta")]
    public SnovioProspectEmailSearchResultMeta Meta { get; set; } = new();

    // 文档示例中该字段返回空数组，因此使用 JsonElement 列表兼容实际响应。
    [JsonPropertyName("links")]
    public List<JsonElement> Links { get; set; } = new();

    /// <summary>
    /// 任务处理状态，例如 completed 或 in_progress。
    /// </summary>
    [JsonPropertyName("status")]
    public string? Status { get; set; }
}

/// <summary>
/// Snov.io 潜客邮箱检索结果数据。
/// </summary>
[System.Text.Json.Serialization.JsonConverter(typeof(SnovioProspectEmailSearchResultDataConverter))]
public sealed class SnovioProspectEmailSearchResultData
{
    /// <summary>
    /// 邮箱检索任务开始时间。
    /// </summary>
    [JsonPropertyName("searching_date")]
    public string? SearchingDate { get; set; }

    /// <summary>
    /// 当前潜客检索到的邮箱列表。
    /// </summary>
    [JsonPropertyName("emails")]
    public List<SnovioProspectEmail> Emails { get; set; } = new();
}

/// <summary>
/// 兼容 Snov.io 潜客邮箱结果中 data 为对象或空数组的响应转换器。
/// </summary>
internal sealed class SnovioProspectEmailSearchResultDataConverter
    : System.Text.Json.Serialization.JsonConverter<SnovioProspectEmailSearchResultData>
{
    public override SnovioProspectEmailSearchResultData Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options)
    {
        if (reader.TokenType == JsonTokenType.Null)
            return new SnovioProspectEmailSearchResultData();

        if (reader.TokenType == JsonTokenType.StartObject)
        {
            using var document = JsonDocument.ParseValue(ref reader);
            var root = document.RootElement;
            var result = new SnovioProspectEmailSearchResultData();

            if (root.TryGetProperty("searching_date", out var searchingDate) &&
                searchingDate.ValueKind == JsonValueKind.String)
            {
                result.SearchingDate = searchingDate.GetString();
            }

            if (root.TryGetProperty("emails", out var emailsElement) &&
                emailsElement.ValueKind == JsonValueKind.Array)
            {
                result.Emails = emailsElement.Deserialize<List<SnovioProspectEmail>>(options)
                                ?? new List<SnovioProspectEmail>();
            }

            return result;
        }

        if (reader.TokenType == JsonTokenType.StartArray)
        {
            using var document = JsonDocument.ParseValue(ref reader);
            var emails = document.RootElement.Deserialize<List<SnovioProspectEmail>>(options);

            return new SnovioProspectEmailSearchResultData
            {
                Emails = emails ?? new List<SnovioProspectEmail>()
            };
        }

        throw new System.Text.Json.JsonException(
            "Snov.io 潜客邮箱检索响应中的 data 必须是对象、数组或 null。");
    }

    public override void Write(
        Utf8JsonWriter writer,
        SnovioProspectEmailSearchResultData value,
        JsonSerializerOptions options)
    {
        writer.WriteStartObject();

        if (value.SearchingDate != null)
            writer.WriteString("searching_date", value.SearchingDate);

        writer.WritePropertyName("emails");
        System.Text.Json.JsonSerializer.Serialize(writer, value.Emails, options);

        writer.WriteEndObject();
    }
}

/// <summary>
/// Snov.io 潜客邮箱信息。
/// </summary>
public sealed class SnovioProspectEmail
{
    /// <summary>
    /// 潜客邮箱地址。
    /// </summary>
    [JsonPropertyName("email")]
    public string? Email { get; set; }

    /// <summary>
    /// SMTP 校验状态，例如 valid 或 unknown。
    /// </summary>
    [JsonPropertyName("smtp_status")]
    public string? SmtpStatus { get; set; }
}

/// <summary>
/// Snov.io 潜客邮箱检索结果元数据。
/// </summary>
public sealed class SnovioProspectEmailSearchResultMeta
{
    /// <summary>
    /// 异步邮箱检索任务唯一标识。
    /// </summary>
    [JsonPropertyName("task_hash")]
    public string? TaskHash { get; set; }
}

/// <summary>
/// Snov.io 异步任务结果链接。
/// </summary>
public sealed class SnovioApiLinks
{
    /// <summary>
    /// 当前异步任务的结果查询地址。
    /// </summary>
    [JsonPropertyName("result")]
    public string? Result { get; set; }

    /// <summary>
    /// 下一页结果地址；没有下一页时通常为空字符串或 null。
    /// </summary>
    [JsonPropertyName("next")]
    public string? Next { get; set; }
}