using StellaOps.TaskRunner.Client.Models;

namespace StellaOps.TaskRunner.Client;

/// <summary>
/// Client interface for the TaskRunner WebService API.
/// </summary>
public interface ITaskRunnerClient
{
    #region Pack Runs

    /// <summary>
    /// Creates a new pack run.
    /// </summary>
    /// <param name="request">Run creation request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Created run response.</returns>
    Task<CreatePackRunResponse> CreateRunAsync(
        CreatePackRunRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the current state of a pack run.
    /// </summary>
    /// <param name="runId">Run identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Pack run state or null if not found.</returns>
    Task<PackRunState?> GetRunAsync(
        string runId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Cancels a running pack run.
    /// </summary>
    /// <param name="runId">Run identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Cancel response.</returns>
    Task<CancelRunResponse> CancelRunAsync(
        string runId,
        CancellationToken cancellationToken = default);

    #endregion

    #region Approvals

    /// <summary>
    /// Applies an approval decision to a pending approval gate.
    /// </summary>
    /// <param name="runId">Run identifier.</param>
    /// <param name="approvalId">Approval gate identifier.</param>
    /// <param name="request">Decision request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Approval decision response.</returns>
    Task<ApprovalDecisionResponse> ApplyApprovalDecisionAsync(
        string runId,
        string approvalId,
        ApprovalDecisionRequest request,
        CancellationToken cancellationToken = default);

    #endregion

    #region Logs

    /// <summary>
    /// Streams log entries for a pack run as NDJSON.
    /// </summary>
    /// <param name="runId">Run identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Async enumerable of log entries.</returns>
    IAsyncEnumerable<RunLogEntry> StreamLogsAsync(
        string runId,
        CancellationToken cancellationToken = default);

    #endregion

    #region Artifacts

    /// <summary>
    /// Lists artifacts produced by a pack run.
    /// </summary>
    /// <param name="runId">Run identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Artifact list response.</returns>
    Task<ArtifactListResponse> ListArtifactsAsync(
        string runId,
        CancellationToken cancellationToken = default);

    #endregion

    #region Simulation

    /// <summary>
    /// Simulates a task pack execution without running it.
    /// </summary>
    /// <param name="request">Simulation request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Simulation result.</returns>
    Task<SimulatePackResponse> SimulateAsync(
        SimulatePackRequest request,
        CancellationToken cancellationToken = default);

    #endregion

    #region Metadata

    /// <summary>
    /// Gets OpenAPI metadata including spec URL, version, and signature.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>OpenAPI metadata.</returns>
    Task<OpenApiMetadata> GetOpenApiMetadataAsync(CancellationToken cancellationToken = default);

    #endregion
}

/// <summary>
/// OpenAPI metadata from /.well-known/openapi endpoint.
/// </summary>
public sealed record OpenApiMetadata(
    [property: System.Text.Json.Serialization.JsonPropertyName("specUrl")] string SpecUrl,
    [property: System.Text.Json.Serialization.JsonPropertyName("version")] string Version,
    [property: System.Text.Json.Serialization.JsonPropertyName("buildVersion")] string BuildVersion,
    [property: System.Text.Json.Serialization.JsonPropertyName("eTag")] string ETag,
    [property: System.Text.Json.Serialization.JsonPropertyName("signature")] string Signature);