using ZB.MOM.WW.HistorianGateway.Contracts.Grpc;

namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway;

/// <summary>
/// Abstraction over the HistorianGateway gRPC client surface consumed by the OtOpcUa historian
/// backend driver. Proto-typed (the wire contract lives in
/// <c>ZB.MOM.WW.HistorianGateway.Contracts.Grpc</c>); the concrete adapter wrapping
/// <c>HistorianGatewayClient</c> is supplied by a later task. The seam exists so the driver and
/// its tests can depend on a fake without a live gateway.
/// </summary>
public interface IHistorianGatewayClient : IAsyncDisposable
{
    /// <summary>Streams raw historian samples for a tag over a time window.</summary>
    IAsyncEnumerable<HistorianSample> ReadRawAsync(
        string tag,
        DateTime startUtc,
        DateTime endUtc,
        int maxValues,
        CancellationToken ct);

    /// <summary>Streams aggregate samples for a tag using the given retrieval mode and interval.</summary>
    IAsyncEnumerable<HistorianAggregateSample> ReadAggregateAsync(
        string tag,
        DateTime startUtc,
        DateTime endUtc,
        RetrievalMode mode,
        TimeSpan interval,
        CancellationToken ct);

    /// <summary>Reads the samples nearest to each of the requested timestamps (unary).</summary>
    Task<IReadOnlyList<HistorianSample>> ReadAtTimeAsync(
        string tag,
        IReadOnlyList<DateTime> timestampsUtc,
        CancellationToken ct);

    /// <summary>Streams historian events over a window, optionally filtered to a single source name.</summary>
    IAsyncEnumerable<HistorianEvent> ReadEventsAsync(
        string? sourceName,
        DateTime startUtc,
        DateTime endUtc,
        int maxEvents,
        CancellationToken ct);

    /// <summary>Writes live values for a tag through the gateway's SQL live-write path.</summary>
    Task<WriteAck> WriteLiveValuesAsync(
        string tag,
        IReadOnlyList<HistorianLiveValue> values,
        CancellationToken ct);

    /// <summary>Sends a single historian event.</summary>
    Task<WriteAck> SendEventAsync(HistorianEvent evt, CancellationToken ct);

    /// <summary>Ensures the supplied tag definitions exist (create-or-update).</summary>
    Task<TagOperationResults> EnsureTagsAsync(
        IReadOnlyList<HistorianTagDefinition> definitions,
        CancellationToken ct);

    /// <summary>Probes gateway/historian reachability.</summary>
    Task<bool> ProbeAsync(CancellationToken ct);

    /// <summary>Reads the gateway's current historian connection status.</summary>
    Task<ConnectionStatus> GetConnectionStatusAsync(CancellationToken ct);
}