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

namespace OASystem.API.OAMethodLib.SnovioAPI;

/// <summary>
/// Snov.io API 服务。
/// </summary>
public interface ISnovioService
{
    /// <summary>
    /// 使用配置中的 Client ID 和 Client Secret 获取 OAuth 访问令牌。
    /// </summary>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>Snov.io OAuth 访问令牌响应。</returns>
    Task<SnovioAccessTokenResponse> GetAccessTokenAsync(
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 创建 Snov.io 公司数据库搜索任务。
    /// </summary>
    /// <param name="request">公司搜索请求体。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>包含 task_hash 和结果地址的异步任务响应。</returns>
    Task<SnovioCompanySearchStartResponse> StartCompanySearchAsync(
        SnovioCompanySearchRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据 task_hash 获取公司搜索任务当前结果。
    /// </summary>
    /// <param name="taskHash">创建公司搜索任务时返回的 task_hash。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>公司搜索结果响应；任务未完成时可返回处理中状态。</returns>
    Task<SnovioCompanySearchResultResponse> GetCompanySearchResultAsync(
        string taskHash,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 按指定间隔轮询公司搜索任务，直到任务完成、失败或超时。
    /// </summary>
    /// <param name="taskHash">创建公司搜索任务时返回的 task_hash。</param>
    /// <param name="timeout">最大等待时间，未指定时默认 2 分钟。</param>
    /// <param name="pollInterval">两次结果查询之间的间隔，未指定时默认 3 秒。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>任务完成后的公司搜索结果响应。</returns>
    /// <exception cref="TimeoutException">任务在最大等待时间内未完成时抛出。</exception>
    /// <exception cref="InvalidOperationException">Snov.io 返回任务失败状态时抛出。</exception>
    Task<SnovioCompanySearchResultResponse> WaitForCompanySearchResultAsync(
        string taskHash,
        TimeSpan? timeout = null,
        TimeSpan? pollInterval = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 创建公司搜索任务并轮询等待实际结果。
    /// </summary>
    /// <param name="request">公司搜索条件和分页请求体。</param>
    /// <param name="timeout">最大等待时间，未指定时默认 2 分钟。</param>
    /// <param name="pollInterval">两次结果查询之间的间隔，未指定时默认 3 秒。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>任务完成后的公司搜索结果响应。</returns>
    Task<SnovioCompanySearchResultResponse> SearchCompaniesAsync(
        SnovioCompanySearchRequest request,
        TimeSpan? timeout = null,
        TimeSpan? pollInterval = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 创建 Snov.io 域名潜在客户搜索任务。
    /// </summary>
    /// <param name="request">域名潜在客户搜索请求体。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>包含 task_hash 和结果地址的异步任务响应。</returns>
    Task<SnovioDomainProspectsSearchStartResponse> StartDomainProspectsSearchAsync(
        SnovioDomainProspectsSearchRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据 task_hash 获取域名潜在客户搜索任务当前结果。
    /// </summary>
    /// <param name="taskHash">创建域名潜在客户搜索任务时返回的 task_hash。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>域名潜在客户搜索结果响应；任务未完成时可返回处理中状态。</returns>
    Task<SnovioDomainProspectsSearchResultResponse> GetDomainProspectsSearchResultAsync(
        string taskHash,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 按指定间隔轮询域名潜在客户搜索任务，直到任务完成、失败或超时。
    /// </summary>
    /// <param name="taskHash">创建域名潜在客户搜索任务时返回的 task_hash。</param>
    /// <param name="timeout">最大等待时间，未指定时默认 2 分钟。</param>
    /// <param name="pollInterval">两次结果查询之间的间隔，未指定时默认 3 秒。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>任务完成后的域名潜在客户搜索结果响应。</returns>
    /// <exception cref="TimeoutException">任务在最大等待时间内未完成时抛出。</exception>
    /// <exception cref="InvalidOperationException">Snov.io 返回任务失败状态时抛出。</exception>
    Task<SnovioDomainProspectsSearchResultResponse> WaitForDomainProspectsSearchResultAsync(
        string taskHash,
        TimeSpan? timeout = null,
        TimeSpan? pollInterval = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 创建域名潜在客户搜索任务并轮询等待实际结果。
    /// </summary>
    /// <param name="request">域名、职位筛选和分页请求体。</param>
    /// <param name="timeout">最大等待时间，未指定时默认 2 分钟。</param>
    /// <param name="pollInterval">两次结果查询之间的间隔，未指定时默认 3 秒。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>任务完成后的域名潜在客户搜索结果响应。</returns>
    Task<SnovioDomainProspectsSearchResultResponse> SearchDomainProspectsAsync(
        SnovioDomainProspectsSearchRequest request,
        TimeSpan? timeout = null,
        TimeSpan? pollInterval = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 创建指定潜客的邮箱检索任务。
    /// </summary>
    /// <param name="prospectHash">域名潜客搜索结果中返回的 prospect_hash，用于定位单个潜客。</param>
    /// <param name="request">邮箱检索请求体，可选，目前支持 webhook_url 回调地址。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>包含邮箱检索 task_hash 和结果地址的异步任务响应。</returns>
    Task<SnovioProspectEmailSearchStartResponse> StartProspectEmailSearchAsync(
        string prospectHash,
        SnovioProspectEmailSearchRequest? request = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据 task_hash 获取潜客邮箱检索任务当前结果。
    /// </summary>
    /// <param name="taskHash">邮箱检索任务的 task_hash。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>潜客邮箱检索结果响应；任务未完成时可返回处理中状态。</returns>
    Task<SnovioProspectEmailSearchResultResponse> GetProspectEmailSearchResultAsync(
        string taskHash,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 按指定间隔轮询潜客邮箱检索任务，直到任务完成、失败或超时。
    /// </summary>
    /// <param name="taskHash">邮箱检索任务的 task_hash。</param>
    /// <param name="timeout">最大等待时间，未指定时默认 2 分钟。</param>
    /// <param name="pollInterval">两次结果查询之间的间隔，未指定时默认 3 秒。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>任务完成后的潜客邮箱检索结果响应。</returns>
    /// <exception cref="TimeoutException">任务在最大等待时间内未完成时抛出。</exception>
    /// <exception cref="InvalidOperationException">Snov.io 返回任务失败状态时抛出。</exception>
    Task<SnovioProspectEmailSearchResultResponse> WaitForProspectEmailSearchResultAsync(
        string taskHash,
        TimeSpan? timeout = null,
        TimeSpan? pollInterval = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 创建潜客邮箱检索任务并轮询等待实际邮箱结果。
    /// </summary>
    /// <param name="prospectHash">域名潜客搜索结果中返回的 prospect_hash，用于定位单个潜客。</param>
    /// <param name="request">邮箱检索请求体，可选，目前支持 webhook_url 回调地址。</param>
    /// <param name="timeout">最大等待时间，未指定时默认 2 分钟。</param>
    /// <param name="pollInterval">两次结果查询之间的间隔，未指定时默认 3 秒。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>任务完成后的潜客邮箱检索结果响应。</returns>
    Task<SnovioProspectEmailSearchResultResponse> SearchProspectEmailAsync(
        string prospectHash,
        SnovioProspectEmailSearchRequest? request = null,
        TimeSpan? timeout = null,
        TimeSpan? pollInterval = null,
        CancellationToken cancellationToken = default);
}