feat(api): REST endpoints for decos, deco groups, playout default deco (#144 S3 (#162))

Adds DecoController (groups + decos CRUD + full-state PUT), playlist and
artist/multi-collection search picker wrappers, a PlaylistController for the
break-content playlist cascade, and PUT /api/playouts/{id}/deco. Fixes the
CreateDecoHandler missing deco-group existence check (FK 500 -> 422), matching
the CreateBlock/CreateTemplate precedent. ReplaceDecoRequest.ToCommand rejects
Merge on the non-mergeable sections (422).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ErsatzTV/Controllers/Api/DecoController.cs

@@ -0,0 +1,237 @@
+using System.ComponentModel.DataAnnotations;
+using ErsatzTV.Application.Scheduling;
+using ErsatzTV.Controllers.Api.Requests;
+using ErsatzTV.Core;
+using ErsatzTV.Core.Api.Scheduling;
+using ErsatzTV.Extensions;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ErsatzTV.Controllers.Api;
+
+[ApiController]
+public class DecoController(IMediator mediator) : ControllerBase
+{
+    [HttpGet("/api/decos/groups", Name = "GetDecoGroups")]
+    [Tags("Decos")]
+    [EndpointSummary("Get all deco groups")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<DecoGroupResponseModel>), StatusCodes.Status200OK)]
+    public async Task<List<DecoGroupResponseModel>> GetGroups(CancellationToken cancellationToken)
+    {
+        List<DecoGroupViewModel> groups = await mediator.Send(new GetAllDecoGroups(), cancellationToken);
+        return groups.Map(ProjectToResponseModel).ToList();
+    }
+
+    [HttpPost("/api/decos/groups")]
+    [Tags("Decos")]
+    [EndpointSummary("Create a deco group")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(DecoGroupResponseModel), StatusCodes.Status201Created)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> CreateGroup(
+        [Required] [FromBody] CreateDecoGroupRequest request,
+        CancellationToken cancellationToken)
+    {
+        Either<BaseError, DecoGroupViewModel> result =
+            await mediator.Send(request.ToCommand(), cancellationToken);
+        return result.ToCreatedResult(
+            vm => $"/api/decos/groups/{vm.Id}",
+            vm => ProjectToResponseModel(vm));
+    }
+
+    [HttpDelete("/api/decos/groups/{id:int}")]
+    [Tags("Decos")]
+    [EndpointSummary("Delete a deco group")]
+    [EndpointDescription(
+        "Deletes the deco group. The database cascade removes every deco in the group (and each deco's break " +
+        "content and watermark/graphics-element assignments); any playout that used a removed deco has its " +
+        "default deco cleared.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> DeleteGroup(int id, CancellationToken cancellationToken)
+    {
+        List<DecoGroupViewModel> groups = await mediator.Send(new GetAllDecoGroups(), cancellationToken);
+        if (groups.All(g => g.Id != id))
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        Option<BaseError> result = await mediator.Send(new DeleteDecoGroup(id), cancellationToken);
+        return result.Match<IActionResult>(
+            Some: error => error.ToErrorResult(),
+            None: () => new NoContentResult());
+    }
+
+    [HttpGet("/api/decos")]
+    [Tags("Decos")]
+    [EndpointSummary("Get all decos")]
+    [EndpointDescription("Returns every deco as a flat list, ordered by group name then deco name.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<DecoListItemResponseModel>), StatusCodes.Status200OK)]
+    public async Task<List<DecoListItemResponseModel>> GetAll(CancellationToken cancellationToken)
+    {
+        List<DecoGroupViewModel> groups = await mediator.Send(new GetAllDecoGroups(), cancellationToken);
+        var result = new List<DecoListItemResponseModel>();
+        foreach (DecoGroupViewModel group in groups)
+        {
+            List<DecoViewModel> decos = await mediator.Send(new GetDecosByDecoGroupId(group.Id), cancellationToken);
+            result.AddRange(decos.Map(d => new DecoListItemResponseModel(d.Id, d.DecoGroupId, d.DecoGroupName, d.Name)));
+        }
+
+        return result;
+    }
+
+    [HttpGet("/api/decos/{id:int}", Name = "GetDecoById")]
+    [Tags("Decos")]
+    [EndpointSummary("Get a deco by id")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(DecoResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
+    {
+        Option<DecoViewModel> result = await mediator.Send(new GetDecoById(id), cancellationToken);
+        return result.Map(ProjectToResponseModel).ToGetResult();
+    }
+
+    [HttpPost("/api/decos")]
+    [Tags("Decos")]
+    [EndpointSummary("Create a deco")]
+    [EndpointDescription("Creates a deco in the given deco group. The deco inherits everything by default.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(DecoResponseModel), StatusCodes.Status201Created)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> Create(
+        [Required] [FromBody] CreateDecoRequest request,
+        CancellationToken cancellationToken)
+    {
+        Either<BaseError, DecoViewModel> result = await mediator.Send(request.ToCommand(), cancellationToken);
+        return result.ToCreatedResult(
+            vm => $"/api/decos/{vm.Id}",
+            vm => ProjectToResponseModel(vm));
+    }
+
+    [HttpDelete("/api/decos/{id:int}")]
+    [Tags("Decos")]
+    [EndpointSummary("Delete a deco")]
+    [EndpointDescription(
+        "Deletes the deco. Any playout that used it as its default deco has that default cleared.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> Delete(int id, CancellationToken cancellationToken)
+    {
+        Option<DecoViewModel> existing = await mediator.Send(new GetDecoById(id), cancellationToken);
+        if (existing.IsNone)
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        Option<BaseError> result = await mediator.Send(new DeleteDeco(id), cancellationToken);
+        return result.Match<IActionResult>(
+            Some: error => error.ToErrorResult(),
+            None: () => new NoContentResult());
+    }
+
+    [HttpPut("/api/decos/{id:int}")]
+    [Tags("Decos")]
+    [EndpointSummary("Replace a deco")]
+    [EndpointDescription(
+        "Replaces the full state of the deco (name and all six sections). Send the entire desired state, including " +
+        "unchanged sections. Merge is only valid for the watermark and graphics-element modes. Break content allows " +
+        "at most one item per placement.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(DecoResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> Replace(
+        int id,
+        [Required] [FromBody] ReplaceDecoRequest request,
+        CancellationToken cancellationToken)
+    {
+        Option<DecoViewModel> maybeDeco = await mediator.Send(new GetDecoById(id), cancellationToken);
+        if (maybeDeco.IsNone)
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        int decoGroupId = maybeDeco.Map(d => d.DecoGroupId).IfNone(0);
+
+        Either<BaseError, UpdateDeco> commandOrError = request.ToCommand(decoGroupId, id);
+        return await commandOrError.Match(
+            Left: error => Task.FromResult(error.ToErrorResult()),
+            Right: async command =>
+            {
+                Either<BaseError, Unit> result = await mediator.Send(command, cancellationToken);
+                return await result.Match(
+                    Left: error => Task.FromResult(error.ToErrorResult()),
+                    Right: async _ =>
+                    {
+                        Option<DecoViewModel> refreshed = await mediator.Send(new GetDecoById(id), cancellationToken);
+                        return refreshed.Match(
+                            Some: vm => (IActionResult)new OkObjectResult(ProjectToResponseModel(vm)),
+                            None: () => ApiResults.NotFoundProblem());
+                    });
+            });
+    }
+
+    private static DecoGroupResponseModel ProjectToResponseModel(DecoGroupViewModel vm) =>
+        new(vm.Id, vm.Name, vm.DecoCount);
+
+    private static DecoResponseModel ProjectToResponseModel(DecoViewModel vm) =>
+        new(
+            vm.Id,
+            vm.DecoGroupId,
+            vm.DecoGroupName,
+            vm.Name,
+            vm.WatermarkMode,
+            vm.Watermarks.Map(w => w.Id).ToList(),
+            vm.UseWatermarkDuringFiller,
+            vm.GraphicsElementsMode,
+            vm.GraphicsElements.Map(g => g.Id).ToList(),
+            vm.UseGraphicsElementsDuringFiller,
+            vm.BreakContentMode,
+            vm.BreakContent.Map(ProjectToResponseModel).ToList(),
+            vm.DefaultFillerMode,
+            vm.DefaultFillerCollectionType,
+            vm.DefaultFillerCollection?.Id,
+            vm.DefaultFillerMediaItem?.MediaItemId,
+            vm.DefaultFillerMultiCollection?.Id,
+            vm.DefaultFillerSmartCollection?.Id,
+            vm.DefaultFillerCollection?.Name
+            ?? vm.DefaultFillerMediaItem?.Name
+            ?? vm.DefaultFillerMultiCollection?.Name
+            ?? vm.DefaultFillerSmartCollection?.Name,
+            vm.DefaultFillerTrimToFit,
+            vm.DeadAirFallbackMode,
+            vm.DeadAirFallbackCollectionType,
+            vm.DeadAirFallbackCollection?.Id,
+            vm.DeadAirFallbackMediaItem?.MediaItemId,
+            vm.DeadAirFallbackMultiCollection?.Id,
+            vm.DeadAirFallbackSmartCollection?.Id,
+            vm.DeadAirFallbackCollection?.Name
+            ?? vm.DeadAirFallbackMediaItem?.Name
+            ?? vm.DeadAirFallbackMultiCollection?.Name
+            ?? vm.DeadAirFallbackSmartCollection?.Name);
+
+    private static DecoBreakContentResponseModel ProjectToResponseModel(DecoBreakContentViewModel vm) =>
+        new(
+            vm.Id,
+            vm.CollectionType,
+            vm.Collection?.Id,
+            vm.MediaItem?.MediaItemId,
+            vm.MultiCollection?.Id,
+            vm.SmartCollection?.Id,
+            vm.Playlist?.Id,
+            vm.Playlist?.PlaylistGroupId,
+            vm.Collection?.Name
+            ?? vm.MediaItem?.Name
+            ?? vm.MultiCollection?.Name
+            ?? vm.SmartCollection?.Name
+            ?? vm.Playlist?.Name,
+            vm.Placement);
+}

ErsatzTV/Controllers/Api/PlaylistController.cs

@@ -0,0 +1,37 @@
+using ErsatzTV.Application.MediaCollections;
+using ErsatzTV.Core.Api.MediaCollections;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ErsatzTV.Controllers.Api;
+
+[ApiController]
+public class PlaylistController(IMediator mediator) : ControllerBase
+{
+    [HttpGet("/api/playlists/groups", Name = "GetPlaylistGroups")]
+    [Tags("Playlists")]
+    [EndpointSummary("Get all playlist groups")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<PlaylistGroupResponseModel>), StatusCodes.Status200OK)]
+    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();
+    }
+
+    [HttpGet("/api/playlists", Name = "GetPlaylists")]
+    [Tags("Playlists")]
+    [EndpointSummary("Get playlists in a playlist group")]
+    [EndpointDescription("Returns the playlists in the given playlist group.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<PlaylistResponseModel>), StatusCodes.Status200OK)]
+    public async Task<List<PlaylistResponseModel>> GetAll(
+        [FromQuery] int playlistGroupId,
+        CancellationToken cancellationToken)
+    {
+        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();
+    }
+}

ErsatzTV/Controllers/Api/PlayoutController.cs

@@ -1,5 +1,6 @@
 using System.ComponentModel.DataAnnotations;
 using ErsatzTV.Application.Playouts;
+using ErsatzTV.Application.Scheduling;
 using ErsatzTV.Controllers.Api.Requests;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Api.Playouts;
@@ -190,6 +191,49 @@ public class PlayoutController(IMediator mediator) : ControllerBase
             _ => BaseError.New("[ScheduleFile] is only valid for Sequential, Scripted, or ExternalJson playouts")
         };
 
+    [HttpPut("/api/playouts/{id:int}/deco")]
+    [Tags("Playouts")]
+    [EndpointSummary("Set (or clear) a playout's default deco")]
+    [EndpointDescription("Assigns the default deco for a block playout. Send a null decoId to clear it.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(PlayoutResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> UpdateDefaultDeco(
+        int id,
+        [Required] [FromBody] UpdateDefaultDecoRequest request,
+        CancellationToken cancellationToken)
+    {
+        Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
+        if (maybePlayout.IsNone)
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        if (request.DecoId is { } decoId)
+        {
+            Option<DecoViewModel> maybeDeco = await mediator.Send(new GetDecoById(decoId), cancellationToken);
+            if (maybeDeco.IsNone)
+            {
+                return BaseError.New("Deco does not exist").ToErrorResult();
+            }
+        }
+
+        Option<BaseError> result = await mediator.Send(request.ToCommand(id), cancellationToken);
+        if (result.IsSome)
+        {
+            foreach (BaseError error in result)
+            {
+                return error.ToErrorResult();
+            }
+        }
+
+        Option<PlayoutNameViewModel> refreshed = await mediator.Send(new GetPlayoutById(id), cancellationToken);
+        return refreshed.Match(
+            Some: vm => (IActionResult)new OkObjectResult(ToResponse(vm)),
+            None: () => ApiResults.NotFoundProblem());
+    }
+
     [HttpPost("/api/playouts/reset-all", Name = "ResetAllPlayouts")]
     [Tags("Playouts")]
     [EndpointSummary("Reset all playouts")]

ErsatzTV/Controllers/Api/Requests/CreateDecoGroupRequest.cs

@@ -0,0 +1,8 @@
+using ErsatzTV.Application.Scheduling;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record CreateDecoGroupRequest(string Name)
+{
+    public CreateDecoGroup ToCommand() => new(Name);
+}

ErsatzTV/Controllers/Api/Requests/CreateDecoRequest.cs

@@ -0,0 +1,8 @@
+using ErsatzTV.Application.Scheduling;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record CreateDecoRequest(int DecoGroupId, string Name)
+{
+    public CreateDeco ToCommand() => new(DecoGroupId, Name);
+}

ErsatzTV/Controllers/Api/Requests/ReplaceDecoRequest.cs

@@ -0,0 +1,91 @@
+using ErsatzTV.Application.Scheduling;
+using ErsatzTV.Core;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Domain.Scheduling;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record DecoBreakContentRequest(
+    int Id,
+    CollectionType CollectionType,
+    int? CollectionId,
+    int? MediaItemId,
+    int? MultiCollectionId,
+    int? SmartCollectionId,
+    int? PlaylistId,
+    DecoBreakPlacement Placement)
+{
+    public UpdateDecoBreakContent ToUpdateItem() =>
+        new(Id, CollectionType, CollectionId, MediaItemId, MultiCollectionId, SmartCollectionId, PlaylistId, Placement);
+}
+
+public record ReplaceDecoRequest(
+    string Name,
+    DecoMode WatermarkMode,
+    List<int> WatermarkIds,
+    bool UseWatermarkDuringFiller,
+    DecoMode GraphicsElementsMode,
+    List<int> GraphicsElementIds,
+    bool UseGraphicsElementsDuringFiller,
+    DecoMode BreakContentMode,
+    List<DecoBreakContentRequest> BreakContent,
+    DecoMode DefaultFillerMode,
+    CollectionType DefaultFillerCollectionType,
+    int? DefaultFillerCollectionId,
+    int? DefaultFillerMediaItemId,
+    int? DefaultFillerMultiCollectionId,
+    int? DefaultFillerSmartCollectionId,
+    bool DefaultFillerTrimToFit,
+    DecoMode DeadAirFallbackMode,
+    CollectionType DeadAirFallbackCollectionType,
+    int? DeadAirFallbackCollectionId,
+    int? DeadAirFallbackMediaItemId,
+    int? DeadAirFallbackMultiCollectionId,
+    int? DeadAirFallbackSmartCollectionId)
+{
+    public Either<BaseError, UpdateDeco> ToCommand(int decoGroupId, int decoId)
+    {
+        // Merge is only valid for the watermark and graphics-element sections; the handler treats
+        // Merge on the other sections as "not overridden" (silently ignored), so reject it here.
+        if (BreakContentMode is DecoMode.Merge)
+        {
+            return BaseError.New("[BreakContentMode] does not support Merge; use Inherit, Disable, or Override");
+        }
+
+        if (DefaultFillerMode is DecoMode.Merge)
+        {
+            return BaseError.New("[DefaultFillerMode] does not support Merge; use Inherit, Disable, or Override");
+        }
+
+        if (DeadAirFallbackMode is DecoMode.Merge)
+        {
+            return BaseError.New("[DeadAirFallbackMode] does not support Merge; use Inherit, Disable, or Override");
+        }
+
+        return new UpdateDeco(
+            decoId,
+            decoGroupId,
+            Name,
+            WatermarkMode,
+            WatermarkIds ?? [],
+            UseWatermarkDuringFiller,
+            GraphicsElementsMode,
+            GraphicsElementIds ?? [],
+            UseGraphicsElementsDuringFiller,
+            BreakContentMode,
+            (BreakContent ?? []).Select(bc => bc.ToUpdateItem()).ToList(),
+            DefaultFillerMode,
+            DefaultFillerCollectionType,
+            DefaultFillerCollectionId,
+            DefaultFillerMediaItemId,
+            DefaultFillerMultiCollectionId,
+            DefaultFillerSmartCollectionId,
+            DefaultFillerTrimToFit,
+            DeadAirFallbackMode,
+            DeadAirFallbackCollectionType,
+            DeadAirFallbackCollectionId,
+            DeadAirFallbackMediaItemId,
+            DeadAirFallbackMultiCollectionId,
+            DeadAirFallbackSmartCollectionId);
+    }
+}

ErsatzTV/Controllers/Api/Requests/UpdateDefaultDecoRequest.cs

@@ -0,0 +1,8 @@
+using ErsatzTV.Application.Scheduling;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record UpdateDefaultDecoRequest(int? DecoId)
+{
+    public UpdateDefaultDeco ToCommand(int playoutId) => new(playoutId, DecoId);
+}

ErsatzTV/Controllers/Api/SearchController.cs

@@ -102,4 +102,36 @@ public class SearchController(IMediator mediator) : ControllerBase
             cancellationToken);
         return results.Map(c => new SchedulingPickerOptionResponseModel(c.Id, c.Name)).ToList();
     }
+
+    [HttpGet("/api/search/artists", Name = "SearchArtists")]
+    [Tags("Search")]
+    [EndpointSummary("Search artists by name")]
+    [EndpointDescription("Returns matching artists as {id, name} options for scheduling editors.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<SchedulingPickerOptionResponseModel>), StatusCodes.Status200OK)]
+    public async Task<List<SchedulingPickerOptionResponseModel>> SearchArtists(
+        [FromQuery] string query = "",
+        CancellationToken cancellationToken = default)
+    {
+        List<NamedMediaItemViewModel> results = await mediator.Send(
+            new SearchArtists(query ?? string.Empty),
+            cancellationToken);
+        return results.Map(a => new SchedulingPickerOptionResponseModel(a.MediaItemId, a.Name)).ToList();
+    }
+
+    [HttpGet("/api/search/multi-collections", Name = "SearchMultiCollections")]
+    [Tags("Search")]
+    [EndpointSummary("Search multi collections by name")]
+    [EndpointDescription("Returns matching multi collections as {id, name} options for scheduling editors.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<SchedulingPickerOptionResponseModel>), StatusCodes.Status200OK)]
+    public async Task<List<SchedulingPickerOptionResponseModel>> SearchMultiCollections(
+        [FromQuery] string query = "",
+        CancellationToken cancellationToken = default)
+    {
+        List<MultiCollectionViewModel> results = await mediator.Send(
+            new SearchMultiCollections(query ?? string.Empty),
+            cancellationToken);
+        return results.Map(c => new SchedulingPickerOptionResponseModel(c.Id, c.Name)).ToList();
+    }
 }