using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;

namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;

/// <summary>
/// CentralUI facade over the central-to-site OPC UA browse command. Backs the
/// OPC UA Tag Browser dialog: each tree expansion / manual node-id paste calls
/// <see cref="BrowseChildrenAsync"/>, which forwards a
/// <see cref="BrowseNodeCommand"/> to the owning site via
/// <see cref="ZB.MOM.WW.ScadaBridge.Communication.CommunicationService"/>.
/// </summary>
/// <remarks>
/// The service is the trust boundary for the browse capability: it enforces the
/// <c>Design</c> role at central before any cross-cluster traffic is generated,
/// because site-side actors do not unwrap the central trust envelope. Transport
/// failures (timeouts, unreachable sites) are translated into a typed
/// <see cref="BrowseFailure"/> so the dialog can render an inline error and
/// remain usable (manual node-id paste still works).
/// </remarks>
public interface IBrowseService
{
    /// <summary>
    /// Enumerates the immediate children of an OPC UA node on the live server
    /// backing <paramref name="connectionName"/> at <paramref name="siteId"/>.
    /// Pass <c>null</c> for <paramref name="parentNodeId"/> to browse from the
    /// server root (ObjectsFolder).
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="connectionName">Name of the site-local data connection to browse against — the site's <c>DataConnectionManagerActor</c> indexes its children by name.</param>
    /// <param name="parentNodeId">Node to browse, or <c>null</c> to browse from the server root.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that resolves to a <see cref="BrowseNodeResult"/> containing child nodes or a <see cref="BrowseFailure"/> on error.</returns>
    Task<BrowseNodeResult> BrowseChildrenAsync(
        string siteId,
        string connectionName,
        string? parentNodeId,
        CancellationToken cancellationToken = default);
}
