using Core.Entities;

namespace WebApp.Services;

public interface INotesService
{
    /// <summary>
    /// Gets all notes, optionally including deleted notes.
    /// </summary>
    /// <param name="includeDeleted">If true, includes soft-deleted notes. Defaults to false.</param>
    Task<IEnumerable<Note>> GetNotesAsync(bool includeDeleted = false);

    /// <summary>
    /// Gets a single note by ID.
    /// </summary>
    Task<Note?> GetNoteAsync(int id);

    /// <summary>
    /// Gets a page-specific note by page identifier.
    /// </summary>
    /// <param name="pageIdentifier">The page identifier (e.g., "Teams", "Registration")</param>
    /// <returns>The note with title "@{pageIdentifier}" or null if not found</returns>
    Task<Note?> GetPageNoteAsync(string pageIdentifier);

    /// <summary>
    /// Gets all history entries for a note.
    /// </summary>
    Task<IEnumerable<NoteHistory>> GetNoteHistoryAsync(int noteId);

    /// <summary>
    /// Creates a new note and initial history entry.
    /// </summary>
    Task<Note> CreateNoteAsync(Note note);

    /// <summary>
    /// Updates an existing note and creates a history entry.
    /// </summary>
    Task<Note> UpdateNoteAsync(Note note);

    /// <summary>
    /// Deletes a note and creates a deletion history entry.
    /// </summary>
    Task DeleteNoteAsync(int id);

    /// <summary>
    /// Gets up to 3 pinned notes, excluding page notes and deleted notes, ordered by most recently updated.
    /// </summary>
    Task<IEnumerable<Note>> GetPinnedNotesAsync();

    /// <summary>
    /// Toggles the pin status of a note, enforcing the 3-note limit.
    /// </summary>
    Task TogglePinNoteAsync(int noteId);

    /// <summary>
    /// Gets all soft-deleted notes.
    /// </summary>
    Task<IEnumerable<Note>> GetDeletedNotesAsync();

    /// <summary>
    /// Restores a soft-deleted note.
    /// </summary>
    Task RestoreNoteAsync(int noteId);
}