using StellaOps.Concelier.Connector.Common;

namespace StellaOps.Concelier.Connector.Common.State;

/// <summary>
/// Describes a raw upstream document that should be persisted for a connector during seeding.
/// </summary>
public sealed record SourceStateSeedDocument
{
    /// <summary>
    /// Absolute source URI. Must match the connector's upstream document identifier.
    /// </summary>
    public string Uri { get; init; } = string.Empty;

    /// <summary>
    /// Raw document payload. Required when creating or replacing a document.
    /// </summary>
    public byte[] Content { get; init; } = Array.Empty<byte>();

    /// <summary>
    /// Optional explicit document identifier. When provided it overrides auto-generated IDs.
    /// </summary>
    public Guid? DocumentId { get; init; }

    /// <summary>
    /// MIME type for the document payload.
    /// </summary>
    public string? ContentType { get; init; }

    /// <summary>
    /// Status assigned to the document. Defaults to <see cref="DocumentStatuses.PendingParse"/>.
    /// </summary>
    public string Status { get; init; } = DocumentStatuses.PendingParse;

    /// <summary>
    /// Optional HTTP-style headers persisted alongside the raw document.
    /// </summary>
    public IReadOnlyDictionary<string, string>? Headers { get; init; }

    /// <summary>
    /// Source metadata (connector specific) persisted alongside the raw document.
    /// </summary>
    public IReadOnlyDictionary<string, string>? Metadata { get; init; }

    /// <summary>
    /// Upstream ETag value, if available.
    /// </summary>
    public string? Etag { get; init; }

    /// <summary>
    /// Upstream last-modified timestamp, if available.
    /// </summary>
    public DateTimeOffset? LastModified { get; init; }

    /// <summary>
    /// Optional document expiration. When set a TTL will purge the raw payload after the configured retention.
    /// </summary>
    public DateTimeOffset? ExpiresAt { get; init; }

    /// <summary>
    /// Fetch timestamp stamped onto the document. Defaults to the seed completion timestamp.
    /// </summary>
    public DateTimeOffset? FetchedAt { get; init; }

    /// <summary>
    /// When true, the document ID will be appended to the connector cursor's <c>pendingDocuments</c> set.
    /// </summary>
    public bool AddToPendingDocuments { get; init; } = true;

    /// <summary>
    /// When true, the document ID will be appended to the connector cursor's <c>pendingMappings</c> set.
    /// </summary>
    public bool AddToPendingMappings { get; init; }

    /// <summary>
    /// Optional identifiers that should be recorded on the cursor to avoid duplicate ingestion.
    /// </summary>
    public IReadOnlyCollection<string>? KnownIdentifiers { get; init; }
}

/// <summary>
/// Cursor updates that should accompany seeded documents.
/// </summary>
public sealed record SourceStateSeedCursor
{
    /// <summary>
    /// Optional <c>pendingDocuments</c> additions expressed as document IDs.
    /// </summary>
    public IReadOnlyCollection<Guid>? PendingDocuments { get; init; }

    /// <summary>
    /// Optional <c>pendingMappings</c> additions expressed as document IDs.
    /// </summary>
    public IReadOnlyCollection<Guid>? PendingMappings { get; init; }

    /// <summary>
    /// Optional known advisory identifiers to merge with the cursor.
    /// </summary>
    public IReadOnlyCollection<string>? KnownAdvisories { get; init; }

    /// <summary>
    /// Upstream window watermark tracked by connectors that rely on last-modified cursors.
    /// </summary>
    public DateTimeOffset? LastModifiedCursor { get; init; }

    /// <summary>
    /// Optional fetch timestamp used by connectors that track the last polling instant.
    /// </summary>
    public DateTimeOffset? LastFetchAt { get; init; }

    /// <summary>
    /// Additional cursor fields (string values) to merge.
    /// </summary>
    public IReadOnlyDictionary<string, string>? Additional { get; init; }
}

/// <summary>
/// Seeding specification describing the source, documents, and cursor edits to apply.
/// </summary>
public sealed record SourceStateSeedSpecification
{
    /// <summary>
    /// Source/connector name (e.g. <c>vndr.msrc</c>).
    /// </summary>
    public string Source { get; init; } = string.Empty;

    /// <summary>
    /// Documents that should be inserted or replaced before the cursor update.
    /// </summary>
    public IReadOnlyList<SourceStateSeedDocument> Documents { get; init; } = Array.Empty<SourceStateSeedDocument>();

    /// <summary>
    /// Cursor adjustments applied after documents are persisted.
    /// </summary>
    public SourceStateSeedCursor? Cursor { get; init; }

    /// <summary>
    /// Connector-level known advisory identifiers to merge into the cursor.
    /// </summary>
    public IReadOnlyCollection<string>? KnownAdvisories { get; init; }

    /// <summary>
    /// Optional completion timestamp. Defaults to the processor's time provider.
    /// </summary>
    public DateTimeOffset? CompletedAt { get; init; }
}

/// <summary>
/// Result returned after seeding completes.
/// </summary>
public sealed record SourceStateSeedResult(
    int DocumentsProcessed,
    int PendingDocumentsAdded,
    int PendingMappingsAdded,
    IReadOnlyCollection<Guid> DocumentIds,
    IReadOnlyCollection<Guid> PendingDocumentIds,
    IReadOnlyCollection<Guid> PendingMappingIds,
    IReadOnlyCollection<string> KnownAdvisoriesAdded,
    DateTimeOffset CompletedAt);