using System.Collections.Generic;
using Svrnty.CQRS.Events.Abstractions.EventStore;
using System.Threading;
using System.Threading.Tasks;
using Svrnty.CQRS.Events.Abstractions;

namespace Svrnty.CQRS.Events.ConsumerGroups.Abstractions;

/// <summary>
/// High-level API for consuming event streams as part of a consumer group.
/// Provides automatic offset management, heartbeating, and error handling.
/// </summary>
public interface IConsumerGroupReader
{
    /// <summary>
    /// Start consuming a stream as part of a consumer group.
    /// Returns an async enumerable that yields events from the stream.
    /// The consumer will automatically manage offsets, heartbeats, and polling.
    /// </summary>
    /// <param name="streamName">The stream to consume.</param>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="consumerId">The consumer ID within the group.</param>
    /// <param name="options">Consumer group options.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Async enumerable of events from the stream.</returns>
    /// <remarks>
    /// The enumerable will:
    /// - Start reading from the last committed offset for the group
    /// - Automatically commit offsets based on the configured strategy
    /// - Send periodic heartbeats to maintain consumer registration
    /// - Poll for new events when the stream is caught up
    /// - Handle consumer registration/unregistration
    /// </remarks>
    IAsyncEnumerable<ICorrelatedEvent> ConsumeAsync(
        string streamName,
        string groupId,
        string consumerId,
        ConsumerGroupOptions options,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Manually commit an offset for a consumer.
    /// Useful when using OffsetCommitStrategy.Manual.
    /// </summary>
    /// <param name="streamName">The stream name.</param>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="consumerId">The consumer ID.</param>
    /// <param name="offset">The offset to commit.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task representing the asynchronous operation.</returns>
    Task CommitOffsetAsync(
        string streamName,
        string groupId,
        string consumerId,
        long offset,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Get the last committed offset for a consumer group.
    /// </summary>
    /// <param name="streamName">The stream name.</param>
    /// <param name="groupId">The consumer group ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The last committed offset, or null if no offset has been committed.</returns>
    Task<long?> GetLastCommittedOffsetAsync(
        string streamName,
        string groupId,
        CancellationToken cancellationToken = default);
}