chapter-organizer/WebApp/Services/INotesService.cs

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 the system note for a student, or null if none exists.
    /// </summary>
    Task<Note?> GetStudentNoteAsync(int studentId);

    /// <summary>
    /// Gets system notes for the given student ids, keyed by student id.
    /// </summary>
    Task<IReadOnlyDictionary<int, Note>> GetStudentNotesAsync(IEnumerable<int> studentIds);

    /// <summary>
    /// Soft-deletes system notes for the given student ids.
    /// </summary>
    Task SoftDeleteStudentNotesAsync(IEnumerable<int> studentIds, CancellationToken cancellationToken = default);

    /// <summary>
    /// Distinct Field names from student note <c>## Additional fields</c> tables.
    /// </summary>
    Task<IReadOnlyList<string>> GetImportedFieldNamesAsync(CancellationToken cancellationToken = default);

    /// <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);
}