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

/// <summary>
///     A live, one-level-at-a-time browse over a remote address space. Owned by the
///     AdminUI <c>BrowseSessionRegistry</c>; disposed by the registry's TTL reaper or
///     the picker body on close.
/// </summary>
public interface IBrowseSession : IAsyncDisposable
{
    /// <summary>Opaque token identifying this session in the registry.</summary>
    Guid Token { get; }

    /// <summary>Wall-clock time of the most recent successful call. Refreshed on
    /// <see cref="RootAsync"/>, <see cref="ExpandAsync"/>, and
    /// <see cref="AttributesAsync"/>; used by the reaper for idle eviction.</summary>
    DateTime LastUsedUtc { get; }

    /// <summary>Returns the top-level browse nodes.</summary>
    Task<IReadOnlyList<BrowseNode>> RootAsync(CancellationToken cancellationToken);

    /// <summary>Returns the direct children of the node identified by
    /// <paramref name="nodeId"/>.</summary>
    Task<IReadOnlyList<BrowseNode>> ExpandAsync(string nodeId, CancellationToken cancellationToken);

    /// <summary>Returns the attributes of the node identified by <paramref name="nodeId"/>.
    /// Empty for drivers whose tree is uniform (OPC UA Client). Galaxy uses this to populate
    /// the attribute side-panel after the user selects an object.</summary>
    Task<IReadOnlyList<AttributeInfo>> AttributesAsync(string nodeId, CancellationToken cancellationToken);
}
