namespace GB5Shared.Storage
{
    /// <summary>
    /// Abstraction over physical file storage.
    /// All implementations must be stateless and thread-safe.
    /// The <c>storagePath</c> parameter is an opaque internal key — never expose it to the frontend.
    /// </summary>
    public interface IStorageProvider
    {
        StorageProviderType ProviderType { get; }

        /// <summary>
        /// Saves the stream to storage at the specified relative path.
        /// Creates intermediate directories as needed.
        /// Returns the same <paramref name="storagePath"/> on success.
        /// </summary>
        Task<string> SaveAsync(Stream content, string storagePath, string mimeType, CancellationToken ct = default);

        /// <summary>
        /// Opens a readable stream for the given storage path.
        /// Throws <see cref="FileNotFoundException"/> if not found.
        /// Caller is responsible for disposing the returned stream.
        /// </summary>
        Task<Stream> GetStreamAsync(string storagePath, CancellationToken ct = default);

        /// <summary>
        /// Permanently deletes a file. Returns <c>false</c> if not found (idempotent).
        /// </summary>
        Task<bool> DeleteAsync(string storagePath, CancellationToken ct = default);

        /// <summary>
        /// Checks existence without downloading. Useful for health/integrity checks.
        /// </summary>
        Task<bool> ExistsAsync(string storagePath, CancellationToken ct = default);

        /// <summary>
        /// Moves a file from <paramref name="oldStoragePath"/> to <paramref name="newStoragePath"/>.
        /// For S3 this is CopyObject + DeleteObject. For filesystem this is File.Move.
        /// Returns <c>false</c> if the source does not exist (idempotent).
        /// </summary>
        Task<bool> MoveAsync(string oldStoragePath, string newStoragePath, CancellationToken ct = default);
    }
}