viewengine.client/Models/RetrievalModels.cs

namespace ViewEngine.Client.Models;

/// <summary>
/// Request to submit a web page retrieval job
/// </summary>
public class SubmitRetrievalRequest
{
    /// <summary>
    /// The URL of the web page to retrieve (scheme optional, will default to https://)
    /// </summary>
    public string Url { get; set; } = string.Empty;

    /// <summary>
    /// Maximum time to wait in seconds (default: 60, max: 300)
    /// </summary>
    public int TimeoutSeconds { get; set; } = 60;

    /// <summary>
    /// Force fresh retrieval, bypassing cache (default: false)
    /// </summary>
    public bool ForceRefresh { get; set; }

    /// <summary>
    /// Number of feeders that must agree (Community mode only, 1-10)
    /// </summary>
    public int? RequiredQuorum { get; set; }

    /// <summary>
    /// Job priority (1=lowest, 10=highest, default: 5). Higher priority costs more.
    /// </summary>
    public int Priority { get; set; } = 5;

    /// <summary>
    /// Route job to specific client's feeder (requires Client Management setup)
    /// </summary>
    public Guid? ClientId { get; set; }

    /// <summary>
    /// Route job using your custom client identifier (alternative to clientId)
    /// </summary>
    public string? CustomUserId { get; set; }

    /// <summary>
    /// Restrict processing to a specific platform: "Android", "iOS", or "Windows" (Community mode only)
    /// </summary>
    public string? PreferredPlatform { get; set; }

    /// <summary>
    /// If true, generate an AI summary of the page content (default: false)
    /// </summary>
    public bool GenerateSummary { get; set; } = false;

    /// <summary>
    /// Target language code for translation (ISO 639-1, e.g., "en", "es", "de", "zh").
    /// If specified and the page is in a different language, content will be translated.
    /// Null = no translation, return content as-is.
    /// </summary>
    public string? TargetLanguage { get; set; }
}

/// <summary>
/// Response from submitting a retrieval request
/// </summary>
public class RetrievalResponse
{
    /// <summary>
    /// Unique identifier for this retrieval request
    /// </summary>
    public Guid RequestId { get; set; }

    /// <summary>
    /// Current status of the request
    /// </summary>
    public string Status { get; set; } = string.Empty;

    /// <summary>
    /// User-friendly message describing the status
    /// </summary>
    public string Message { get; set; } = string.Empty;

    /// <summary>
    /// Estimated wait time in seconds
    /// </summary>
    public int? EstimatedWaitTimeSeconds { get; set; }
}

/// <summary>
/// Status response for a retrieval request
/// </summary>
public class RetrievalStatusResponse
{
    /// <summary>
    /// The request ID
    /// </summary>
    public Guid RequestId { get; set; }

    /// <summary>
    /// The URL being retrieved
    /// </summary>
    public string Url { get; set; } = string.Empty;

    /// <summary>
    /// Current status: queued, processing, validating, complete, failed, canceled
    /// </summary>
    public string Status { get; set; } = string.Empty;

    /// <summary>
    /// User-friendly status message
    /// </summary>
    public string Message { get; set; } = string.Empty;

    /// <summary>
    /// Content information (available when status is complete)
    /// </summary>
    public ContentInfo? Content { get; set; }

    /// <summary>
    /// Error message if status is failed
    /// </summary>
    public string? Error { get; set; }

    /// <summary>
    /// When the request was created
    /// </summary>
    public DateTime CreatedAt { get; set; }

    /// <summary>
    /// When the request was completed
    /// </summary>
    public DateTime? CompletedAt { get; set; }
}

/// <summary>
/// Content information for a completed retrieval
/// </summary>
public class ContentInfo
{
    /// <summary>
    /// URL to download the decrypted page content
    /// </summary>
    public string PageDataUrl { get; set; } = string.Empty;

    /// <summary>
    /// Hash of the retrieved content
    /// </summary>
    public string? ContentHash { get; set; }

    /// <summary>
    /// Artifacts such as screenshots and thumbnails
    /// </summary>
    public ArtifactsInfo? Artifacts { get; set; }

    /// <summary>
    /// Performance and quality metrics
    /// </summary>
    public Dictionary<string, object>? Metrics { get; set; }
}

/// <summary>
/// Artifacts from page retrieval
/// </summary>
public class ArtifactsInfo
{
    /// <summary>
    /// URL to full page screenshot
    /// </summary>
    public string? Screenshot { get; set; }

    /// <summary>
    /// URL to page thumbnail
    /// </summary>
    public string? Thumbnail { get; set; }
}

/// <summary>
/// Page content data returned from the API
/// </summary>
public class PageData
{
    /// <summary>
    /// Page title
    /// </summary>
    public string Title { get; set; } = string.Empty;

    /// <summary>
    /// Full text content of the page
    /// </summary>
    public string Body { get; set; } = string.Empty;

    /// <summary>
    /// Meta description tag content
    /// </summary>
    public string? MetaDescription { get; set; }

    /// <summary>
    /// Final URL after any redirects
    /// </summary>
    public string Url { get; set; } = string.Empty;

    /// <summary>
    /// URL to the page's favicon
    /// </summary>
    public string? FaviconUrl { get; set; }

    /// <summary>
    /// Base64-encoded PNG screenshot of the page (typically 320x180)
    /// </summary>
    public string? Thumbnail { get; set; }

    /// <summary>
    /// Links found in navigation/header areas
    /// </summary>
    public List<LinkInfo> Routes { get; set; } = new();

    /// <summary>
    /// Links found in page body content
    /// </summary>
    public List<LinkInfo> BodyRoutes { get; set; } = new();

    /// <summary>
    /// Optional AI-generated summary of the page content
    /// </summary>
    public string? Summary { get; set; }

    /// <summary>
    /// HTTP status code from the page retrieval.
    /// Null if status code is not available.
    /// Common values: 200 (OK), 404 (Not Found), 500 (Server Error).
    /// </summary>
    public int? HttpStatusCode { get; set; }

    /// <summary>
    /// Returns true if the HTTP status code indicates success (2xx) or is not available.
    /// </summary>
    public bool IsSuccess => HttpStatusCode == null || (HttpStatusCode >= 200 && HttpStatusCode < 300);

    /// <summary>
    /// Returns true if the HTTP status code indicates a client error (4xx).
    /// </summary>
    public bool IsClientError => HttpStatusCode >= 400 && HttpStatusCode < 500;

    /// <summary>
    /// Returns true if the HTTP status code indicates a server error (5xx).
    /// </summary>
    public bool IsServerError => HttpStatusCode >= 500;

    /// <summary>
    /// Language of the page as declared in the HTML lang attribute (e.g., "en", "es", "zh-CN").
    /// Null if not specified in the HTML.
    /// </summary>
    public string? HtmlLang { get; set; }

    /// <summary>
    /// Detected/confirmed language of the content (ISO 639-1 code, e.g., "en", "es", "zh").
    /// May differ from HtmlLang if automatic language detection was performed.
    /// </summary>
    public string? DetectedLanguage { get; set; }

    /// <summary>
    /// If content was translated, this is the target language code.
    /// Null if no translation was performed.
    /// </summary>
    public string? TranslatedTo { get; set; }

    /// <summary>
    /// Original body text before translation.
    /// Only populated if translation occurred.
    /// </summary>
    public string? OriginalBody { get; set; }

    /// <summary>
    /// Original title before translation.
    /// Only populated if translation occurred.
    /// </summary>
    public string? OriginalTitle { get; set; }
}

/// <summary>
/// Information about a link on the page
/// </summary>
public class LinkInfo
{
    /// <summary>
    /// The link URL
    /// </summary>
    public string Url { get; set; } = string.Empty;

    /// <summary>
    /// The anchor text (what the link says)
    /// </summary>
    public string Text { get; set; } = string.Empty;

    /// <summary>
    /// Importance ranking (higher = more important, typically 1-10)
    /// </summary>
    public int Rank { get; set; }

    /// <summary>
    /// How many times this link appears on the page
    /// </summary>
    public int Occurrences { get; set; }

    /// <summary>
    /// Whether this link is likely an advertisement
    /// </summary>
    public bool IsPotentialAd { get; set; }

    /// <summary>
    /// Explanation of why the link was flagged as an ad (null if not an ad)
    /// </summary>
    public string? AdReason { get; set; }
}