using System;
using System.Threading;
using System.Threading.Tasks;

namespace Svrnty.CQRS.Sagas.Abstractions;

/// <summary>
/// Orchestrates saga execution.
/// </summary>
public interface ISagaOrchestrator
{
    /// <summary>
    /// Starts a new saga instance with a generated correlation ID.
    /// </summary>
    /// <typeparam name="TSaga">The saga type.</typeparam>
    /// <typeparam name="TData">The saga data type.</typeparam>
    /// <param name="initialData">The initial saga data.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The saga state.</returns>
    Task<SagaState> StartAsync<TSaga, TData>(TData initialData, CancellationToken cancellationToken = default)
        where TSaga : ISaga<TData>
        where TData : class, ISagaData, new();

    /// <summary>
    /// Starts a new saga instance with a specific correlation ID.
    /// </summary>
    /// <typeparam name="TSaga">The saga type.</typeparam>
    /// <typeparam name="TData">The saga data type.</typeparam>
    /// <param name="initialData">The initial saga data.</param>
    /// <param name="correlationId">The correlation ID for tracing.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The saga state.</returns>
    Task<SagaState> StartAsync<TSaga, TData>(TData initialData, Guid correlationId, CancellationToken cancellationToken = default)
        where TSaga : ISaga<TData>
        where TData : class, ISagaData, new();

    /// <summary>
    /// Gets the current state of a saga by its ID.
    /// </summary>
    /// <param name="sagaId">The saga instance ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The saga state, or null if not found.</returns>
    Task<SagaState?> GetStateAsync(Guid sagaId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the current state of a saga by its correlation ID.
    /// </summary>
    /// <param name="correlationId">The correlation ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The saga state, or null if not found.</returns>
    Task<SagaState?> GetStateByCorrelationIdAsync(Guid correlationId, CancellationToken cancellationToken = default);
}