using ZB.MOM.WW.ScadaBridge.Commons.Messages.Integration;

namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;

/// <summary>
/// Site-side fan-out abstraction for cached-call lifecycle telemetry.
/// One <see cref="CachedCallTelemetry"/> packet carries
/// both an audit row and an operational <c>SiteCalls</c> upsert; the
/// implementation routes the audit half through <see cref="IAuditWriter"/>
/// and the operational half through the site-local tracking SQLite store.
/// </summary>
/// <remarks>
/// <para>
/// Defined in Commons so the script runtime (and the StoreAndForward retry
/// loop) can take a dependency on the abstraction rather than on
/// the concrete forwarder living inside <c>ZB.MOM.WW.ScadaBridge.AuditLog</c> — the
/// existing dependency arrow runs from <c>SiteRuntime</c> to Commons, not to
/// AuditLog.
/// </para>
/// <para>
/// <b>Best-effort contract (alog.md §7):</b> implementations MUST swallow
/// internal failures rather than propagating to the calling script.
/// </para>
/// </remarks>
public interface ICachedCallTelemetryForwarder
{
    /// <summary>
    /// Fan one combined-telemetry packet out to the audit writer and the
    /// tracking store. Best-effort — failures on either half are logged and
    /// swallowed; the returned Task completes when both halves have been
    /// attempted.
    /// </summary>
    /// <param name="telemetry">The combined-telemetry packet to fan out.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task ForwardAsync(CachedCallTelemetry telemetry, CancellationToken ct = default);
}
