// ***********************************************************************
// <copyright file="IFurnitureVariantProvider.cs">
//     Core.Inventory
// </copyright>
// ***********************************************************************
using Core.Adapters.Lib;
using Core.Blueprint.Mongo;
using Core.Inventory.Domain.Contexts.Inventory.Request;

namespace Core.Inventory.Provider.Contracts
{
    /// <summary>
    /// Interface for managing furniture variants associated with a base furniture model.
    /// </summary>
    public interface IFurnitureVariantProvider
    {
        /// <summary>
        /// Creates a new FurnitureVariant entity.
        /// </summary>
        /// <param name="newVariant">The DTO representing the furniture variant.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The created <see cref="FurnitureVariant"/>.</returns>
        ValueTask<FurnitureVariant> CreateAsync(FurnitureVariantRequest newVariant, CancellationToken cancellationToken);

        /// <summary>
        /// Gets a furniture variant entity by its ID.
        /// </summary>
        /// <param name="_id">The unique identifier (_id) of the furniture variant.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The corresponding <see cref="FurnitureVariant"/>.</returns>
        ValueTask<FurnitureVariant> GetByIdAsync(string _id, CancellationToken cancellationToken);

        /// <summary>
        /// Retrieves all furniture variants by a list of variant IDs.
        /// </summary>
        /// <param name="ids">Array of variant IDs.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A list of <see cref="FurnitureVariant"/> matching the specified IDs.</returns>
        ValueTask<IEnumerable<FurnitureVariant>> GetAllByIdsAsync(string[] ids, CancellationToken cancellationToken);

        /// <summary>
        /// Retrieves all furniture variants associated with a base model.
        /// </summary>
        /// <param name="modelId">The ID of the base furniture model.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A list of <see cref="FurnitureVariant"/>.</returns>
        ValueTask<IEnumerable<FurnitureVariant>> GetAllByModelIdAsync(string modelId, CancellationToken cancellationToken);

        /// <summary>
        /// Updates an existing furniture variant by ID.
        /// </summary>
        /// <param name="id">The variant identifier.</param>
        /// <param name="entity">The updated entity data.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The updated <see cref="FurnitureVariant"/>.</returns>
        ValueTask<FurnitureVariant> UpdateAsync(string id, FurnitureVariant entity, CancellationToken cancellationToken);

        /// <summary>
        /// Changes the status of a furniture variant entity.
        /// </summary>
        /// <param name="_id">The entity identifier.</param>
        /// <param name="newStatus">The new status to apply.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The updated <see cref="FurnitureVariant"/>.</returns>
        ValueTask<FurnitureVariant> ChangeStatusAsync(string _id, StatusEnum newStatus, CancellationToken cancellationToken);

        /// <summary>
        /// Retrieves all furniture variant entities.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A list of all <see cref="FurnitureVariant"/> entities.</returns>
        ValueTask<IEnumerable<FurnitureVariant>> GetAllAsync(CancellationToken cancellationToken);
    }
}