using ZB.MOM.WW.ScadaBridge.Communication.Grpc;

namespace ZB.MOM.WW.ScadaBridge.AuditLog.Site.Telemetry;

/// <summary>
/// Mockable abstraction over the central site-audit push surface that
/// <see cref="SiteAuditTelemetryActor"/> uses to forward <see cref="AuditEventBatch"/>
/// payloads. The production implementation is
/// <see cref="SiteCommunicationAuditClient"/> — wired in the Host for site
/// roles, it forwards batches to central via the site's
/// <c>SiteCommunicationActor</c>. Unit tests substitute via NSubstitute
/// against this interface so the actor never needs a live transport.
/// </summary>
public interface ISiteStreamAuditClient
{
    /// <summary>
    /// Forwards <paramref name="batch"/> to the central audit-ingest path. The
    /// returned <see cref="IngestAck"/> carries the <c>accepted_event_ids</c>
    /// the actor will flip to
    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditForwardState.Forwarded"/>
    /// in the site SQLite queue.
    /// </summary>
    /// <param name="batch">The batch of audit events to forward.</param>
    /// <param name="ct">Cancellation token for the operation.</param>
    /// <returns>A task that resolves to the ingest acknowledgement containing accepted event IDs.</returns>
    Task<IngestAck> IngestAuditEventsAsync(AuditEventBatch batch, CancellationToken ct);

    /// <summary>
    /// Forwards the combined <see cref="CachedTelemetryBatch"/>
    /// to the central cached-telemetry ingest path. 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 site-side forwarder
    /// can flip the underlying audit rows to
    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditForwardState.Forwarded"/>
    /// once central has acknowledged them.
    /// </summary>
    /// <remarks>
    /// The production <see cref="SiteCommunicationAuditClient"/> forwards over
    /// the site's central transport; the <see cref="NoOpSiteStreamAuditClient"/>
    /// DI default (used by central and test composition roots) returns an empty
    /// ack so no rows are flipped.
    /// </remarks>
    /// <param name="batch">The batch of cached-call telemetry packets to forward.</param>
    /// <param name="ct">Cancellation token for the operation.</param>
    /// <returns>A task that resolves to the ingest acknowledgement containing accepted event IDs.</returns>
    Task<IngestAck> IngestCachedTelemetryAsync(CachedTelemetryBatch batch, CancellationToken ct);
}