using Opc.Ua;

namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Adapters;

/// <summary>
///     Abstracts OPC UA subscription and monitored item management.
/// </summary>
internal interface ISubscriptionAdapter : IDisposable
{
    /// <summary>
    /// Gets the server-assigned subscription identifier for diagnostics and reconnect workflows.
    /// </summary>
    uint SubscriptionId { get; }

    /// <summary>
    ///     Adds a data-change monitored item and returns its client handle for tracking.
    /// </summary>
    /// <param name="nodeId">The node to monitor.</param>
    /// <param name="samplingIntervalMs">The sampling interval in milliseconds.</param>
    /// <param name="onDataChange">Callback when data changes. Receives (nodeIdString, DataValue).</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A client handle that can be used to remove the item.</returns>
    Task<uint> AddDataChangeMonitoredItemAsync(NodeId nodeId, int samplingIntervalMs,
        Action<string, DataValue> onDataChange, CancellationToken ct = default);

    /// <summary>
    ///     Removes a previously added monitored item by its client handle.
    /// </summary>
    /// <param name="clientHandle">The client handle returned when the monitored item was created.</param>
    /// <param name="ct">The cancellation token that aborts the monitored-item removal.</param>
    Task RemoveMonitoredItemAsync(uint clientHandle, CancellationToken ct = default);

    /// <summary>
    ///     Adds an event monitored item with the given event filter.
    /// </summary>
    /// <param name="nodeId">The node to monitor for events.</param>
    /// <param name="samplingIntervalMs">The sampling interval.</param>
    /// <param name="filter">The event filter defining which fields to select.</param>
    /// <param name="onEvent">Callback when events arrive. Receives the event field list.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A client handle for the monitored item.</returns>
    Task<uint> AddEventMonitoredItemAsync(NodeId nodeId, int samplingIntervalMs, EventFilter filter,
        Action<EventFieldList> onEvent, CancellationToken ct = default);

    /// <summary>
    ///     Requests a condition refresh for this subscription.
    /// </summary>
    /// <param name="ct">The cancellation token that aborts the condition refresh request.</param>
    Task ConditionRefreshAsync(CancellationToken ct = default);

    /// <summary>
    ///     Removes all monitored items and deletes the subscription.
    /// </summary>
    /// <param name="ct">The cancellation token that aborts subscription deletion.</param>
    Task DeleteAsync(CancellationToken ct = default);
}