feat(api): playlist CRUD + item management + preview (#153 backend)

Add write endpoints to PlaylistController for the playlist editor: group
create/rename/delete, playlist create/read/update/delete, item list read,
and draft playout preview. Introduces a RenamePlaylistGroup command/handler
(the one missing Application-layer operation) plus request/response DTOs.

Endpoints (verb / route / route-Name):
- POST   /api/playlists/groups        CreatePlaylistGroup
- PUT    /api/playlists/groups/{id}    UpdatePlaylistGroup (rename)
- DELETE /api/playlists/groups/{id}    DeletePlaylistGroup
- GET    /api/playlists/{id}           GetPlaylistById
- GET    /api/playlists/{id}/items     GetPlaylistItems
- POST   /api/playlists                CreatePlaylistInGroup
- PUT    /api/playlists/{id}           UpdatePlaylist (rename + replace items)
- DELETE /api/playlists/{id}           DeletePlaylist
- POST   /api/playlists/preview        PreviewPlaylist

404-vs-422: unknown-id on GET items / PUT / DELETE returns 404 via a
controller-side existence pre-check (mirrors TemplateController.DeleteGroup),
leaving existing shared handlers untouched; validation failures return 422.
RenamePlaylistGroup returns NotFoundError -> 404 for a missing group.

Regenerated wwwroot/openapi/v1.json, docs/endpoint-index.md, and the SPA
client types (web/src/api/generated/v1.d.ts). No SPA screen in this change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ErsatzTV/Controllers/Api/PlaylistController.cs

@@ -1,5 +1,11 @@
+using System.ComponentModel.DataAnnotations;
+using System.Globalization;
 using ErsatzTV.Application.MediaCollections;
+using ErsatzTV.Application.Scheduling;
+using ErsatzTV.Controllers.Api.Requests;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Api.MediaCollections;
+using ErsatzTV.Extensions;
 using MediatR;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
@@ -17,7 +23,64 @@ public class PlaylistController(IMediator mediator) : ControllerBase
     public async Task<List<PlaylistGroupResponseModel>> GetGroups(CancellationToken cancellationToken)
     {
         List<PlaylistGroupViewModel> groups = await mediator.Send(new GetAllPlaylistGroups(), cancellationToken);
-        return groups.Map(g => new PlaylistGroupResponseModel(g.Id, g.Name, g.PlaylistCount, g.IsSystem)).ToList();
+        return groups.Map(ProjectToGroupResponse).ToList();
+    }
+
+    [HttpPost("/api/playlists/groups", Name = "CreatePlaylistGroup")]
+    [Tags("Playlists")]
+    [EndpointSummary("Create a playlist group")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(PlaylistGroupResponseModel), StatusCodes.Status201Created)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> CreateGroup(
+        [Required] [FromBody] CreatePlaylistGroupRequest request,
+        CancellationToken cancellationToken)
+    {
+        Either<BaseError, PlaylistGroupViewModel> result =
+            await mediator.Send(request.ToCommand(), cancellationToken);
+        return result.ToCreatedResult(
+            g => $"/api/playlists/groups/{g.Id}",
+            ProjectToGroupResponse);
+    }
+
+    [HttpPut("/api/playlists/groups/{id:int}", Name = "UpdatePlaylistGroup")]
+    [Tags("Playlists")]
+    [EndpointSummary("Rename a playlist group")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(PlaylistGroupResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> UpdateGroup(
+        int id,
+        [Required] [FromBody] UpdatePlaylistGroupRequest request,
+        CancellationToken cancellationToken)
+    {
+        Either<BaseError, PlaylistGroupViewModel> result =
+            await mediator.Send(request.ToCommand(id), cancellationToken);
+        return result.Match(
+            Left: error => error.ToErrorResult(),
+            Right: vm => (IActionResult)new OkObjectResult(ProjectToGroupResponse(vm)));
+    }
+
+    [HttpDelete("/api/playlists/groups/{id:int}", Name = "DeletePlaylistGroup")]
+    [Tags("Playlists")]
+    [EndpointSummary("Delete a playlist group")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> DeleteGroup(int id, CancellationToken cancellationToken)
+    {
+        List<PlaylistGroupViewModel> groups = await mediator.Send(new GetAllPlaylistGroups(), cancellationToken);
+        if (groups.All(g => g.Id != id))
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        Option<BaseError> result = await mediator.Send(new DeletePlaylistGroup(id), cancellationToken);
+        return result.Match<IActionResult>(
+            Some: error => error.ToErrorResult(),
+            None: () => new NoContentResult());
     }
 
     [HttpGet("/api/playlists", Name = "GetPlaylists")]
@@ -32,6 +95,147 @@ public class PlaylistController(IMediator mediator) : ControllerBase
     {
         List<PlaylistViewModel> playlists =
             await mediator.Send(new GetPlaylistsByPlaylistGroupId(playlistGroupId), cancellationToken);
-        return playlists.Map(p => new PlaylistResponseModel(p.Id, p.PlaylistGroupId, p.Name, p.IsSystem)).ToList();
+        return playlists.Map(ProjectToPlaylistResponse).ToList();
     }
+
+    [HttpGet("/api/playlists/{id:int}", Name = "GetPlaylistById")]
+    [Tags("Playlists")]
+    [EndpointSummary("Get a playlist by id")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(PlaylistResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
+    {
+        Option<PlaylistViewModel> result = await mediator.Send(new GetPlaylistById(id), cancellationToken);
+        return result.Map(ProjectToPlaylistResponse).ToGetResult();
+    }
+
+    [HttpGet("/api/playlists/{id:int}/items", Name = "GetPlaylistItems")]
+    [Tags("Playlists")]
+    [EndpointSummary("Get the items in a playlist")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<PlaylistItemResponseModel>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetItems(int id, CancellationToken cancellationToken)
+    {
+        Option<PlaylistViewModel> maybePlaylist = await mediator.Send(new GetPlaylistById(id), cancellationToken);
+        if (maybePlaylist.IsNone)
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        List<PlaylistItemViewModel> items = await mediator.Send(new GetPlaylistItems(id), cancellationToken);
+        return new OkObjectResult(items.Map(ProjectToItemResponse).ToList());
+    }
+
+    [HttpPost("/api/playlists", Name = "CreatePlaylistInGroup")]
+    [Tags("Playlists")]
+    [EndpointSummary("Create a playlist")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(PlaylistResponseModel), StatusCodes.Status201Created)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> Create(
+        [Required] [FromBody] CreatePlaylistRequest request,
+        CancellationToken cancellationToken)
+    {
+        Either<BaseError, PlaylistViewModel> result = await mediator.Send(request.ToCommand(), cancellationToken);
+        return result.ToCreatedResult(
+            p => $"/api/playlists/{p.Id}",
+            ProjectToPlaylistResponse);
+    }
+
+    [HttpPut("/api/playlists/{id:int}", Name = "UpdatePlaylist")]
+    [Tags("Playlists")]
+    [EndpointSummary("Update a playlist (rename and replace its items)")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<PlaylistItemResponseModel>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> Update(
+        int id,
+        [Required] [FromBody] ReplacePlaylistRequest request,
+        CancellationToken cancellationToken)
+    {
+        Option<PlaylistViewModel> maybePlaylist = await mediator.Send(new GetPlaylistById(id), cancellationToken);
+        if (maybePlaylist.IsNone)
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        Either<BaseError, List<PlaylistItemViewModel>> result =
+            await mediator.Send(request.ToCommand(id), cancellationToken);
+        return result.Match(
+            Left: error => error.ToErrorResult(),
+            Right: items => (IActionResult)new OkObjectResult(items.Map(ProjectToItemResponse).ToList()));
+    }
+
+    [HttpDelete("/api/playlists/{id:int}", Name = "DeletePlaylist")]
+    [Tags("Playlists")]
+    [EndpointSummary("Delete a playlist")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> Delete(int id, CancellationToken cancellationToken)
+    {
+        Option<PlaylistViewModel> maybePlaylist = await mediator.Send(new GetPlaylistById(id), cancellationToken);
+        if (maybePlaylist.IsNone)
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        Option<BaseError> result = await mediator.Send(new DeletePlaylist(id), cancellationToken);
+        return result.Match<IActionResult>(
+            Some: error => error.ToErrorResult(),
+            None: () => new NoContentResult());
+    }
+
+    [HttpPost("/api/playlists/preview", Name = "PreviewPlaylist")]
+    [Tags("Playlists")]
+    [EndpointSummary("Preview the playout of a draft playlist")]
+    [EndpointDescription("Builds a preview playout from the posted draft playlist items (no persistence).")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<PlaylistPreviewItemResponseModel>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> Preview(
+        [Required] [FromBody] ReplacePlaylistRequest request,
+        CancellationToken cancellationToken)
+    {
+        Either<BaseError, List<PlayoutItemPreviewViewModel>> result =
+            await mediator.Send(new PreviewPlaylistPlayout(request.ToReplaceCommand()), cancellationToken);
+        return result.Match(
+            Left: error => error.ToErrorResult(),
+            Right: items => (IActionResult)new OkObjectResult(items.Map(ProjectToPreviewResponse).ToList()));
+    }
+
+    private static PlaylistGroupResponseModel ProjectToGroupResponse(PlaylistGroupViewModel vm) =>
+        new(vm.Id, vm.Name, vm.PlaylistCount, vm.IsSystem);
+
+    private static PlaylistResponseModel ProjectToPlaylistResponse(PlaylistViewModel vm) =>
+        new(vm.Id, vm.PlaylistGroupId, vm.Name, vm.IsSystem);
+
+    private static PlaylistItemResponseModel ProjectToItemResponse(PlaylistItemViewModel vm) =>
+        new(
+            vm.Id,
+            vm.Index,
+            vm.CollectionType,
+            vm.Collection?.Id,
+            vm.Collection?.Name,
+            vm.MultiCollection?.Id,
+            vm.MultiCollection?.Name,
+            vm.SmartCollection?.Id,
+            vm.SmartCollection?.Name,
+            vm.MediaItem?.MediaItemId,
+            vm.MediaItem?.Name,
+            vm.PlaybackOrder,
+            vm.Count,
+            vm.PlayAll,
+            vm.IncludeInProgramGuide);
+
+    private static PlaylistPreviewItemResponseModel ProjectToPreviewResponse(PlayoutItemPreviewViewModel vm) =>
+        new(
+            vm.Title,
+            vm.Start.ToString(@"hh\:mm\:ss", CultureInfo.InvariantCulture),
+            vm.Finish.ToString(@"hh\:mm\:ss", CultureInfo.InvariantCulture),
+            vm.Duration);
 }

ErsatzTV/Controllers/Api/Requests/CreatePlaylistGroupRequest.cs

@@ -0,0 +1,9 @@
+#nullable enable
+using ErsatzTV.Application.MediaCollections;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record CreatePlaylistGroupRequest(string? Name)
+{
+    public CreatePlaylistGroup ToCommand() => new(Name ?? string.Empty);
+}

ErsatzTV/Controllers/Api/Requests/CreatePlaylistRequest.cs

@@ -0,0 +1,9 @@
+#nullable enable
+using ErsatzTV.Application.MediaCollections;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record CreatePlaylistRequest(int PlaylistGroupId, string? Name)
+{
+    public CreatePlaylist ToCommand() => new(PlaylistGroupId, Name ?? string.Empty);
+}

ErsatzTV/Controllers/Api/Requests/ReplacePlaylistRequest.cs

@@ -0,0 +1,48 @@
+#nullable enable
+using System.Collections.Generic;
+using System.Linq;
+using ErsatzTV.Application.MediaCollections;
+using ErsatzTV.Core.Domain;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record PlaylistItemRequest(
+    int Index,
+    CollectionType CollectionType,
+    int? CollectionId,
+    int? MultiCollectionId,
+    int? SmartCollectionId,
+    int? MediaItemId,
+    PlaybackOrder PlaybackOrder,
+    int? Count,
+    bool PlayAll,
+    bool IncludeInProgramGuide)
+{
+    public ReplacePlaylistItem ToReplaceCommand(int index) =>
+        new(
+            index,
+            CollectionType,
+            CollectionId,
+            MultiCollectionId,
+            SmartCollectionId,
+            MediaItemId,
+            PlaybackOrder,
+            Count,
+            PlayAll,
+            IncludeInProgramGuide);
+}
+
+public record ReplacePlaylistRequest(string? Name, List<PlaylistItemRequest>? Items)
+{
+    public ReplacePlaylistItems ToCommand(int id) =>
+        new(id, Name ?? string.Empty, BuildItems());
+
+    // Preview operates on the posted draft, so there is no persisted playlist id (0).
+    public ReplacePlaylistItems ToReplaceCommand() =>
+        new(0, Name ?? string.Empty, BuildItems());
+
+    private List<ReplacePlaylistItem> BuildItems() =>
+        (Items ?? new List<PlaylistItemRequest>())
+        .Select((item, index) => item.ToReplaceCommand(index))
+        .ToList();
+}

ErsatzTV/Controllers/Api/Requests/UpdatePlaylistGroupRequest.cs

@@ -0,0 +1,9 @@
+#nullable enable
+using ErsatzTV.Application.MediaCollections;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record UpdatePlaylistGroupRequest(string? Name)
+{
+    public RenamePlaylistGroup ToCommand(int id) => new(id, Name ?? string.Empty);
+}