using ScadaLink.Communication.Grpc;

namespace ScadaLink.AuditLog.Site.Telemetry;

/// <summary>
/// Mockable abstraction over the central site-stream gRPC client surface that
/// <see cref="SiteAuditTelemetryActor"/> uses to push <see cref="AuditEventBatch"/>
/// payloads. The production implementation (added in Bundle E host wiring)
/// wraps the auto-generated <c>SiteStreamService.SiteStreamServiceClient</c>;
/// unit tests substitute via NSubstitute against this interface so the actor
/// never needs a live gRPC channel.
/// </summary>
public interface ISiteStreamAuditClient
{
    /// <summary>
    /// Pushes <paramref name="batch"/> to the central <c>IngestAuditEvents</c>
    /// RPC. The returned <see cref="IngestAck"/> carries the
    /// <c>accepted_event_ids</c> the actor will flip to
    /// <see cref="ScadaLink.Commons.Types.Enums.AuditForwardState.Forwarded"/>
    /// in the site SQLite queue.
    /// </summary>
    Task<IngestAck> IngestAuditEventsAsync(AuditEventBatch batch, CancellationToken ct);

    /// <summary>
    /// Pushes the combined <see cref="CachedTelemetryBatch"/> (Audit Log #23 / M3)
    /// to the central <c>IngestCachedTelemetry</c> RPC. Each packet carries both
    /// the audit row and the operational <c>SiteCalls</c> upsert; central writes
    /// both in a single MS SQL transaction. Returns the same
    /// <see cref="IngestAck"/> shape as <see cref="IngestAuditEventsAsync"/> so
    /// the M3 site-side forwarder can flip the underlying audit rows to
    /// <see cref="ScadaLink.Commons.Types.Enums.AuditForwardState.Forwarded"/>
    /// once central has acknowledged them.
    /// </summary>
    /// <remarks>
    /// The production gRPC-backed implementation lands in M6 (no site→central
    /// gRPC channel exists today); until then the default
    /// <see cref="NoOpSiteStreamAuditClient"/> binding returns an empty ack and
    /// integration tests substitute a direct-actor client that routes the batch
    /// straight into the in-process <c>AuditLogIngestActor</c>.
    /// </remarks>
    Task<IngestAck> IngestCachedTelemetryAsync(CachedTelemetryBatch batch, CancellationToken ct);
}