using Nexus.Api.Models;

namespace Nexus.Api.Services;

/// <summary>
/// Maintains a persistent WebSocket connection to the OpenClaw Gateway
/// for real-time event streaming and health monitoring.
/// </summary>
public interface IGatewayConnector
{
    /// <summary>
    /// Current WebSocket connection state.
    /// </summary>
    GatewayConnectionState ConnectionState { get; }

    /// <summary>
    /// Gateway version reported at last connection.
    /// </summary>
    string? GatewayVersion { get; }

    /// <summary>
    /// Required version from configuration, or null when unpinned.
    /// </summary>
    string? RequiredVersion { get; }

    /// <summary>
    /// Timestamp of the last successful connection attempt.
    /// </summary>
    DateTimeOffset? LastConnectedAt { get; }

    /// <summary>
    /// Number of consecutive failed connection attempts.
    /// </summary>
    int ReconnectAttempts { get; }

    /// <summary>
    /// Detailed status message (e.g. error or version info).
    /// </summary>
    string? StatusMessage { get; }
}

/// <summary>
/// Represents the current connection state of the GatewayConnector.
/// </summary>
public enum GatewayConnectionState
{
    /// <summary>Not yet attempted or initializing.</summary>
    Initializing,
    /// <summary>Connected and healthy.</summary>
    Connected,
    /// <summary>Disconnected, waiting for reconnect.</summary>
    Disconnected,
    /// <summary>Recoverable error, retrying.</summary>
    Reconnecting,
    /// <summary>Failed after maximum retries.</summary>
    Failed
}