namespace StellaOps.Plugin.Abstractions.Capabilities;

/// <summary>
/// Base capability for external system connectors.
/// </summary>
public interface IConnectorCapability
{
    /// <summary>
    /// Connector type identifier, e.g., "scm.github", "registry.ecr", "vault.hashicorp".
    /// </summary>
    string ConnectorType { get; }

    /// <summary>
    /// Human-readable display name.
    /// </summary>
    string DisplayName { get; }

    /// <summary>
    /// Test the connection to the external system.
    /// </summary>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Result of the connection test.</returns>
    Task<ConnectionTestResult> TestConnectionAsync(CancellationToken ct);

    /// <summary>
    /// Get current connection status and metadata.
    /// </summary>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Connection information.</returns>
    Task<ConnectionInfo> GetConnectionInfoAsync(CancellationToken ct);
}

/// <summary>
/// Result of a connection test.
/// </summary>
/// <param name="Success">Whether the connection was successful.</param>
/// <param name="Message">Optional message describing the result.</param>
/// <param name="Latency">Round-trip latency if measured.</param>
/// <param name="Details">Additional diagnostic details.</param>
public sealed record ConnectionTestResult(
    bool Success,
    string? Message = null,
    TimeSpan? Latency = null,
    IReadOnlyDictionary<string, object>? Details = null)
{
    /// <summary>
    /// Creates a successful connection test result.
    /// </summary>
    /// <param name="latency">Optional measured latency.</param>
    /// <returns>A success result.</returns>
    public static ConnectionTestResult Succeeded(TimeSpan? latency = null) =>
        new(true, "Connection successful", latency);

    /// <summary>
    /// Creates a failed connection test result.
    /// </summary>
    /// <param name="message">Description of the failure.</param>
    /// <param name="ex">Optional exception.</param>
    /// <returns>A failure result.</returns>
    public static ConnectionTestResult Failed(string message, Exception? ex = null) =>
        new(false, message, Details: ex != null ? new Dictionary<string, object>
        {
            ["exception"] = ex.GetType().Name,
            ["exceptionMessage"] = ex.Message
        } : null);
}

/// <summary>
/// Information about the current connection state.
/// </summary>
/// <param name="EndpointUrl">The endpoint URL.</param>
/// <param name="AuthenticatedAs">The authenticated identity, if any.</param>
/// <param name="ConnectedSince">When the connection was established.</param>
/// <param name="Metadata">Additional connection metadata.</param>
public sealed record ConnectionInfo(
    string EndpointUrl,
    string? AuthenticatedAs = null,
    DateTimeOffset? ConnectedSince = null,
    IReadOnlyDictionary<string, object>? Metadata = null);