namespace RobotNet10.Script.IO;

/// <summary>
/// Interface for OPC UA connection operations.
/// </summary>
public interface IOpcUaConnection : IDisposable
{
    /// <summary>
    /// Gets the endpoint URL of the OPC UA server.
    /// </summary>
    string EndpointUrl { get; }

    /// <summary>
    /// Gets whether the connection is currently connected.
    /// </summary>
    bool IsConnected { get; }

    /// <summary>
    /// Connects to the OPC UA server.
    /// </summary>
    Task ConnectAsync();

    /// <summary>
    /// Connects to the OPC UA server with username and password.
    /// </summary>
    /// <param name="username">The username.</param>
    /// <param name="password">The password.</param>
    Task ConnectAsync(string username, string password);

    /// <summary>
    /// Disconnects from the OPC UA server.
    /// </summary>
    Task DisconnectAsync();

    /// <summary>
    /// Reads a node value by node ID.
    /// </summary>
    /// <param name="nodeId">The node ID string (e.g., "ns=2;s=MyVariable").</param>
    /// <returns>The read value as object.</returns>
    Task<object?> ReadNodeAsync(string nodeId);

    /// <summary>
    /// Reads multiple node values by node IDs.
    /// </summary>
    /// <param name="nodeIds">Array of node ID strings.</param>
    /// <returns>Dictionary of node ID to value.</returns>
    Task<Dictionary<string, object?>> ReadNodesAsync(string[] nodeIds);

    /// <summary>
    /// Writes a value to a node by node ID.
    /// </summary>
    /// <param name="nodeId">The node ID string.</param>
    /// <param name="value">The value to write.</param>
    Task WriteNodeAsync(string nodeId, object value);

    /// <summary>
    /// Writes multiple values to nodes.
    /// </summary>
    /// <param name="values">Dictionary of node ID to value.</param>
    Task WriteNodesAsync(Dictionary<string, object> values);

    /// <summary>
    /// Browses the node tree starting from the specified node.
    /// </summary>
    /// <param name="nodeId">The starting node ID (null for root).</param>
    /// <returns>Array of child node IDs.</returns>
    Task<string[]> BrowseNodesAsync(string? nodeId = null);
}