using ZB.MOM.WW.OtOpcUa.Commons.Messages.Admin;

namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;

/// <summary>
/// Cluster-singleton-proxy client for the <c>AdminOperationsActor</c>. The Blazor UI calls
/// this from any host (admin or driver role); the proxy routes the request to whichever node
/// holds the admin singleton.
/// </summary>
public interface IAdminOperationsClient
{
    /// <summary>Starts a new deployment on the cluster-singleton admin operations actor.</summary>
    /// <param name="createdBy">The user or system identifier triggering the deployment.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>A task representing the asynchronous operation containing the deployment start result.</returns>
    Task<StartDeploymentResult> StartDeploymentAsync(string createdBy, CancellationToken ct);

    /// <summary>
    ///     Acknowledges one alarm via the admin singleton, which republishes the mapped command onto
    ///     the cluster <c>alarm-commands</c> topic for the owning node to apply.
    /// </summary>
    /// <param name="alarmId">The alarm's ScriptedAlarmId.</param>
    /// <param name="user">The acting operator's name (for audit + the alarm-event User field).</param>
    /// <param name="comment">Optional free-text comment; null when none.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>The acknowledge result.</returns>
    Task<AcknowledgeAlarmResult> AcknowledgeAlarmAsync(string alarmId, string user, string? comment, CancellationToken ct);

    /// <summary>
    ///     Shelves or unshelves one alarm via the admin singleton, which republishes the mapped command
    ///     onto the cluster <c>alarm-commands</c> topic for the owning node to apply.
    /// </summary>
    /// <param name="alarmId">The alarm's ScriptedAlarmId.</param>
    /// <param name="user">The acting operator's name (for audit + the alarm-event User field).</param>
    /// <param name="kind">Which shelve action to perform (OneShot / Timed / Unshelve).</param>
    /// <param name="unshelveAtUtc">For <see cref="Messages.Admin.ShelveKind.Timed"/>, when the shelve expires; null otherwise.</param>
    /// <param name="comment">Optional free-text comment; null when none.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>The shelve result.</returns>
    Task<ShelveAlarmResult> ShelveAlarmAsync(
        string alarmId,
        string user,
        Messages.Admin.ShelveKind kind,
        DateTime? unshelveAtUtc,
        string? comment,
        CancellationToken ct);

    /// <summary>
    ///     Generic Ask: forwards <paramref name="message"/> to the AdminOperationsActor
    ///     cluster-singleton proxy and awaits a reply of type <typeparamref name="T"/>.
    ///     The caller is responsible for applying any outer timeout via <paramref name="ct"/>.
    /// </summary>
    /// <typeparam name="T">Expected reply type.</typeparam>
    /// <param name="message">The message to send.</param>
    /// <param name="ct">Cancellation token (caller-controlled timeout).</param>
    Task<T> AskAsync<T>(object message, CancellationToken ct);
}