feat(api): media detail + info + image-folder endpoints (#141/#161)

Add REST endpoints backing the SPA media detail pages and image browser:

- GET /api/movies/{id}, /api/shows/{id}, /api/seasons/{id}, /api/artists/{id}
  wrapping the existing detail queries; 404 on None.
- GET /api/media-items/{id}/info wrapping GetMediaItemInfo; UnableToLocateMediaItem
  -> 404, other errors -> 422.
- GET /api/images/folders?parentId= and PUT /api/images/folders/{id}/duration
  (validates null-or-positive -> 400; existence guard via new ImageFolderExists
  query -> 404).
- Extend GetLibraryBrowseItems parentId drill-in to Episode (episodes of a season,
  episode-number order) and MusicVideo (an artist's music videos, album/track order),
  alongside the existing TelevisionSeason branch.

Response DTOs live in ErsatzTV.Core/Api/* and never expose Application VMs. Artwork
values are rooted for the SPA via a shared ErsatzTV.Core/Api/ApiArtwork helper
(mirrors the #180/#181 browse-handler logic; handles jellyfin/emby proxy prefixes,
http passthrough, empty). Regenerated OpenAPI v1.json + web v1.d.ts. New controllers
registered in ApiControllerSecurityTests.

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

ErsatzTV/Controllers/Api/ArtistsController.cs

@@ -0,0 +1,39 @@
+using ErsatzTV.Application.Artists;
+using ErsatzTV.Core.Api;
+using ErsatzTV.Core.Api.Artists;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Extensions;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ErsatzTV.Controllers.Api;
+
+[ApiController]
+public class ArtistsController(IMediator mediator) : ControllerBase
+{
+    [HttpGet("/api/artists/{id:int}", Name = "GetArtistById")]
+    [Tags("Artists")]
+    [EndpointSummary("Get an artist by id")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(ArtistDetailResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
+    {
+        Option<ArtistViewModel> result = await mediator.Send(new GetArtistById(id), cancellationToken);
+        return result.Map(vm => Project(id, vm)).ToGetResult();
+    }
+
+    private static ArtistDetailResponseModel Project(int id, ArtistViewModel vm) =>
+        new(
+            id,
+            vm.Name,
+            string.IsNullOrWhiteSpace(vm.Disambiguation) ? null : vm.Disambiguation,
+            string.IsNullOrWhiteSpace(vm.Biography) ? null : vm.Biography,
+            ApiArtwork.Root(vm.Thumbnail, ArtworkKind.Thumbnail),
+            ApiArtwork.Root(vm.FanArt, ArtworkKind.FanArt),
+            vm.Genres,
+            vm.Styles,
+            vm.Moods,
+            vm.Languages.Map(c => c.EnglishName).ToList());
+}

ErsatzTV/Controllers/Api/ImagesController.cs

@@ -0,0 +1,81 @@
+using System.ComponentModel;
+using System.ComponentModel.DataAnnotations;
+using ErsatzTV.Application.Images;
+using ErsatzTV.Controllers.Api.Requests;
+using ErsatzTV.Core;
+using ErsatzTV.Core.Api.Images;
+using ErsatzTV.Extensions;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ErsatzTV.Controllers.Api;
+
+[ApiController]
+public class ImagesController(IMediator mediator) : ControllerBase
+{
+    [HttpGet("/api/images/folders", Name = "GetImageFolders")]
+    [Tags("Images")]
+    [EndpointSummary("List image library folders")]
+    [EndpointDescription("Omit parentId for the top-level folders; pass a folder id to list that folder's children.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<ImageFolderResponseModel>), StatusCodes.Status200OK)]
+    public async Task<List<ImageFolderResponseModel>> GetFolders(
+        [FromQuery]
+        [Description("Parent image library-folder id; omit for the top-level folders")]
+        int? parentId = null,
+        CancellationToken cancellationToken = default)
+    {
+        Option<int> maybeParentId = parentId ?? Option<int>.None;
+        List<ImageFolderViewModel> folders = await mediator.Send(new GetImageFolders(maybeParentId), cancellationToken);
+        return folders.Map(Project).ToList();
+    }
+
+    [HttpPut("/api/images/folders/{id:int}/duration", Name = "UpdateImageFolderDuration")]
+    [Tags("Images")]
+    [EndpointSummary("Set or clear an image folder's playout duration")]
+    [EndpointDescription(
+        "Pass a positive durationSeconds to set the per-image duration for this folder (cascades to descendant " +
+        "images that don't override it); pass null to clear it and inherit from an ancestor.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(UpdateImageFolderDurationResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> UpdateDuration(
+        int id,
+        [Required] [FromBody] UpdateImageFolderDurationRequest request,
+        CancellationToken cancellationToken)
+    {
+        if (request.DurationSeconds is <= 0)
+        {
+            return BadRequest(
+                new ProblemDetails
+                {
+                    Status = StatusCodes.Status400BadRequest,
+                    Title = "Validation failed",
+                    Detail = "durationSeconds must be greater than zero, or null to clear"
+                });
+        }
+
+        bool exists = await mediator.Send(new ImageFolderExists(id), cancellationToken);
+        if (!exists)
+        {
+            return ApiResults.NotFoundProblem("Image folder not found");
+        }
+
+        double? duration = await mediator.Send(
+            new UpdateImageFolderDuration(id, request.DurationSeconds),
+            cancellationToken);
+
+        return Ok(new UpdateImageFolderDurationResponseModel(duration));
+    }
+
+    private static ImageFolderResponseModel Project(ImageFolderViewModel vm) =>
+        new(
+            vm.LibraryFolderId,
+            vm.Name,
+            vm.FullPath,
+            vm.SubfolderCount,
+            vm.ImageCount,
+            vm.DurationSeconds.ToNullable());
+}

ErsatzTV/Controllers/Api/LibraryBrowseController.cs

@@ -24,7 +24,7 @@ public class LibraryBrowseController(IMediator mediator) : ControllerBase
         [FromQuery] int pageNum = 0,
         [FromQuery] int pageSize = 100,
         [FromQuery]
-        [Description("Parent television show id; only used with mediaType=TelevisionSeason (lists that show's seasons), ignored otherwise")]
+        [Description("Parent id for a drill-in listing; only used with mediaType=TelevisionSeason (that show's seasons), mediaType=Episode (that season's episodes) or mediaType=MusicVideo (that artist's music videos), ignored otherwise")]
         int? parentId = null,
         CancellationToken cancellationToken = default)
     {

ErsatzTV/Controllers/Api/MediaItemsController.cs

@@ -1,6 +1,9 @@
 using System.ComponentModel.DataAnnotations;
+using ErsatzTV.Application.MediaItems;
 using ErsatzTV.Controllers.Api.Requests;
 using ErsatzTV.Core;
+using ErsatzTV.Core.Api.MediaItems;
+using ErsatzTV.Core.Errors;
 using ErsatzTV.Extensions;
 using MediatR;
 using Microsoft.AspNetCore.Http;
@@ -29,4 +32,66 @@ public class MediaItemsController(IMediator mediator) : ControllerBase
         Either<BaseError, Unit> result = await mediator.Send(request.ToCommand(), cancellationToken);
         return result.ToDeletedResult();
     }
+
+    [HttpGet("/api/media-items/{id:int}/info", Name = "GetMediaItemInfo")]
+    [Tags("Media Items")]
+    [EndpointSummary("Get technical media info for a media item")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(MediaItemInfoResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
+    public async Task<IActionResult> GetInfo(int id, CancellationToken cancellationToken)
+    {
+        Either<BaseError, MediaItemInfo> result = await mediator.Send(new GetMediaItemInfo(id), cancellationToken);
+        return result.Match(
+            Left: error => error is UnableToLocateMediaItem
+                ? ApiResults.NotFoundProblem(error.Value)
+                : error.ToErrorResult(),
+            Right: info => (IActionResult)new OkObjectResult(Project(info)));
+    }
+
+    private static MediaItemInfoResponseModel Project(MediaItemInfo info) =>
+        new(
+            info.Id,
+            info.Title,
+            info.Kind,
+            info.LibraryKind,
+            string.IsNullOrWhiteSpace(info.ServerName) ? null : info.ServerName,
+            info.LibraryName,
+            info.State,
+            info.Duration,
+            string.IsNullOrWhiteSpace(info.SampleAspectRatio) ? null : info.SampleAspectRatio,
+            string.IsNullOrWhiteSpace(info.DisplayAspectRatio) ? null : info.DisplayAspectRatio,
+            string.IsNullOrWhiteSpace(info.RFrameRate) ? null : info.RFrameRate,
+            info.VideoScanKind,
+            info.InterlacedRatio,
+            info.Width,
+            info.Height,
+            info.Streams.Map(Project).ToList(),
+            info.Chapters.Map(Project).ToList());
+
+    private static MediaItemInfoStreamResponseModel Project(MediaItemInfoStream stream) =>
+        new(
+            stream.Index,
+            stream.Kind,
+            stream.Title,
+            stream.Codec,
+            stream.Profile,
+            stream.Language,
+            stream.Channels,
+            stream.Default,
+            stream.Forced,
+            stream.AttachedPic,
+            stream.PixelFormat,
+            stream.ColorRange,
+            stream.ColorSpace,
+            stream.ColorTransfer,
+            stream.ColorPrimaries,
+            stream.BitsPerRawSample,
+            stream.MimeType,
+            stream.FileName,
+            stream.IsExtracted);
+
+    private static MediaItemInfoChapterResponseModel Project(MediaItemInfoChapter chapter) =>
+        new(chapter.Title, chapter.StartTime, chapter.EndTime);
 }

ErsatzTV/Controllers/Api/MoviesController.cs

@@ -0,0 +1,47 @@
+using ErsatzTV.Application.Movies;
+using ErsatzTV.Core.Api;
+using ErsatzTV.Core.Api.Media;
+using ErsatzTV.Core.Api.Movies;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Extensions;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ErsatzTV.Controllers.Api;
+
+[ApiController]
+public class MoviesController(IMediator mediator) : ControllerBase
+{
+    [HttpGet("/api/movies/{id:int}", Name = "GetMovieById")]
+    [Tags("Movies")]
+    [EndpointSummary("Get a movie by id")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(MovieDetailResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
+    {
+        Option<MovieViewModel> result = await mediator.Send(new GetMovieById(id), cancellationToken);
+        return result.Map(vm => Project(id, vm)).ToGetResult();
+    }
+
+    private static MovieDetailResponseModel Project(int id, MovieViewModel vm) =>
+        new(
+            id,
+            vm.Title,
+            vm.Year,
+            vm.Plot,
+            vm.Genres,
+            vm.Tags,
+            vm.Studios,
+            vm.ContentRatings,
+            vm.Languages,
+            vm.Actors.Map(a => new ActorResponseModel(a.Id, a.Name, a.Role, ApiArtwork.Root(a.Thumb, ArtworkKind.Thumbnail))).ToList(),
+            vm.Directors,
+            vm.Writers,
+            vm.Path,
+            vm.LocalPath,
+            vm.MediaItemState,
+            ApiArtwork.Root(vm.Poster, ArtworkKind.Poster),
+            ApiArtwork.Root(vm.FanArt, ArtworkKind.FanArt));
+}

ErsatzTV/Controllers/Api/Requests/UpdateImageFolderDurationRequest.cs

@@ -0,0 +1,3 @@
+namespace ErsatzTV.Controllers.Api.Requests;
+
+public record UpdateImageFolderDurationRequest(double? DurationSeconds);

ErsatzTV/Controllers/Api/SeasonsController.cs

@@ -0,0 +1,37 @@
+using ErsatzTV.Application.Television;
+using ErsatzTV.Core.Api;
+using ErsatzTV.Core.Api.Television;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Extensions;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ErsatzTV.Controllers.Api;
+
+[ApiController]
+public class SeasonsController(IMediator mediator) : ControllerBase
+{
+    [HttpGet("/api/seasons/{id:int}", Name = "GetSeasonById")]
+    [Tags("Television")]
+    [EndpointSummary("Get a television season by id")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(SeasonDetailResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
+    {
+        Option<TelevisionSeasonViewModel> result =
+            await mediator.Send(new GetTelevisionSeasonById(id), cancellationToken);
+        return result.Map(Project).ToGetResult();
+    }
+
+    private static SeasonDetailResponseModel Project(TelevisionSeasonViewModel vm) =>
+        new(
+            vm.Id,
+            vm.ShowId,
+            vm.Title,
+            string.IsNullOrWhiteSpace(vm.Year) ? null : vm.Year,
+            vm.Name,
+            ApiArtwork.Root(vm.Poster, ArtworkKind.Poster),
+            ApiArtwork.Root(vm.FanArt, ArtworkKind.FanArt));
+}

ErsatzTV/Controllers/Api/ShowsController.cs

@@ -0,0 +1,45 @@
+using ErsatzTV.Application.Television;
+using ErsatzTV.Core.Api;
+using ErsatzTV.Core.Api.Media;
+using ErsatzTV.Core.Api.Television;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Extensions;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ErsatzTV.Controllers.Api;
+
+[ApiController]
+public class ShowsController(IMediator mediator) : ControllerBase
+{
+    [HttpGet("/api/shows/{id:int}", Name = "GetShowById")]
+    [Tags("Television")]
+    [EndpointSummary("Get a television show by id")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(ShowDetailResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
+    {
+        Option<TelevisionShowViewModel> result = await mediator.Send(new GetTelevisionShowById(id), cancellationToken);
+        return result.Map(Project).ToGetResult();
+    }
+
+    private static ShowDetailResponseModel Project(TelevisionShowViewModel vm) =>
+        new(
+            vm.Id,
+            vm.LibraryId,
+            vm.MediaSourceKind,
+            vm.Title,
+            string.IsNullOrWhiteSpace(vm.Year) ? null : vm.Year,
+            string.IsNullOrWhiteSpace(vm.Plot) ? null : vm.Plot,
+            ApiArtwork.Root(vm.Poster, ArtworkKind.Poster),
+            ApiArtwork.Root(vm.FanArt, ArtworkKind.FanArt),
+            vm.Genres,
+            vm.Tags,
+            vm.Studios,
+            vm.Networks,
+            vm.ContentRatings,
+            vm.Languages.Map(c => c.EnglishName).ToList(),
+            vm.Actors.Map(a => new ActorResponseModel(a.Id, a.Name, a.Role, ApiArtwork.Root(a.Thumb, ArtworkKind.Thumbnail))).ToList());
+}