namespace StellaOps.Signals.Contracts;

/// <summary>
/// Interface for consuming signals from the signal bus.
/// Implemented by services that process signals.
/// </summary>
public interface ISignalConsumer
{
    /// <summary>
    /// Consumes signals from the signal bus as an async enumerable.
    /// </summary>
    /// <param name="filterType">Optional signal type to filter by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Async enumerable of signal envelopes.</returns>
    IAsyncEnumerable<SignalEnvelope> ConsumeAsync(
        SignalType? filterType = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the latest signal for a given key.
    /// </summary>
    /// <param name="signalKey">The signal key to look up.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The signal envelope if found, null otherwise.</returns>
    ValueTask<SignalEnvelope?> GetLatestAsync(
        string signalKey,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all signals for a given PURL.
    /// </summary>
    /// <param name="purl">The package URL to look up.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Collection of signal envelopes for the PURL.</returns>
    ValueTask<IReadOnlyList<SignalEnvelope>> GetByPurlAsync(
        string purl,
        CancellationToken cancellationToken = default);
}