feat(api): library browse + search endpoints (#65) #130

Merged
timothy merged 2 commits from feat/65-library-browse into main 2026-07-06 07:53:40 +02:00
Owner

Summary

Closes #65.

Adds the backend library browse/search API for the Channel Builder and schedule editor picker prerequisites.

Endpoints

Method Route Operation Notes
GET /api/library/browse BrowseLibrary Paged browse/search across media and collection-like picker targets. Query params: query, libraryId, mediaType, pageNum, pageSize.
GET /api/media-sources GetMediaSources Existing #103 read model remains the source for library filter chips; no duplicate library-list endpoint added.

Projection Decisions

  • Reuses ISearchIndex.Search(...) / Lucene for media candidates (movie, show, season, artist), title search, library filter, media type filter, paging, and total count.
  • Hydrates only returned media ids with EF to add title, existing artwork references, duration, library, episode/item counts, and picker id slots.
  • Adds LibraryBrowseMediaType and LibraryBrowseItemResponseModel with normalized picker ids: collectionId, multiCollectionId, smartCollectionId, rerunCollectionId, mediaItemId, playlistId.
  • Collection-like targets (Collection, SmartCollection, MultiCollection, RerunCollection, Playlist) use narrow EF projections because collections are not first-class Lucene documents today.
  • Paging is clamped in the controller: page number >= 0, page size 1..100.
  • Regenerated ErsatzTV/wwwroot/openapi/v1.json and web/src/api/generated/v1.d.ts.

Verification

  • TZ=UTC dotnet build ErsatzTV/ErsatzTV.csproj passed.
  • ./scripts/update-openapi.sh initially hung in dotnet build -t:GenerateOpenApiDocuments; killed the stuck process and reran the equivalent target with normal verbosity: TZ=UTC dotnet build ErsatzTV.csproj -t:GenerateOpenApiDocuments -v normal from ErsatzTV/, passed and regenerated v1.json.
  • TZ=UTC dotnet build ErsatzTV.sln passed.
  • TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj -v minimal passed: 374 passed.
  • TZ=UTC dotnet test ErsatzTV.Core.Tests/ErsatzTV.Core.Tests.csproj -v minimal passed: 493 passed, 1 skipped.
  • cd web && npm ci passed.
  • cd web && npm run generate:api passed.
  • cd web && npm run typecheck passed.

Deferred / Uncertain

  • Exact aggregate duration/artwork for smart/multi/rerun collections is intentionally limited in this slice. Those targets are not Lucene documents and exact expansion can become expensive; this PR exposes typed picker targets and cheap counts where available without adding broad graph loads or schema changes.
  • Existing NuGet vulnerability warnings remain present for Scriban.Signed and Microsoft.OpenApi; no dependency changes in this PR.

Review Notes

A review subagent was attempted after implementation but hit the account usage limit before returning findings; I completed an in-session review and replaced member-list includes for collection counts with grouped count queries.

## Summary Closes #65. Adds the backend library browse/search API for the Channel Builder and schedule editor picker prerequisites. ## Endpoints | Method | Route | Operation | Notes | |---|---|---|---| | GET | `/api/library/browse` | `BrowseLibrary` | Paged browse/search across media and collection-like picker targets. Query params: `query`, `libraryId`, `mediaType`, `pageNum`, `pageSize`. | | GET | `/api/media-sources` | `GetMediaSources` | Existing #103 read model remains the source for library filter chips; no duplicate library-list endpoint added. | ## Projection Decisions - Reuses `ISearchIndex.Search(...)` / Lucene for media candidates (`movie`, `show`, `season`, `artist`), title search, library filter, media type filter, paging, and total count. - Hydrates only returned media ids with EF to add title, existing artwork references, duration, library, episode/item counts, and picker id slots. - Adds `LibraryBrowseMediaType` and `LibraryBrowseItemResponseModel` with normalized picker ids: `collectionId`, `multiCollectionId`, `smartCollectionId`, `rerunCollectionId`, `mediaItemId`, `playlistId`. - Collection-like targets (`Collection`, `SmartCollection`, `MultiCollection`, `RerunCollection`, `Playlist`) use narrow EF projections because collections are not first-class Lucene documents today. - Paging is clamped in the controller: page number >= 0, page size 1..100. - Regenerated `ErsatzTV/wwwroot/openapi/v1.json` and `web/src/api/generated/v1.d.ts`. ## Verification - `TZ=UTC dotnet build ErsatzTV/ErsatzTV.csproj` passed. - `./scripts/update-openapi.sh` initially hung in `dotnet build -t:GenerateOpenApiDocuments`; killed the stuck process and reran the equivalent target with normal verbosity: `TZ=UTC dotnet build ErsatzTV.csproj -t:GenerateOpenApiDocuments -v normal` from `ErsatzTV/`, passed and regenerated `v1.json`. - `TZ=UTC dotnet build ErsatzTV.sln` passed. - `TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj -v minimal` passed: 374 passed. - `TZ=UTC dotnet test ErsatzTV.Core.Tests/ErsatzTV.Core.Tests.csproj -v minimal` passed: 493 passed, 1 skipped. - `cd web && npm ci` passed. - `cd web && npm run generate:api` passed. - `cd web && npm run typecheck` passed. ## Deferred / Uncertain - Exact aggregate duration/artwork for smart/multi/rerun collections is intentionally limited in this slice. Those targets are not Lucene documents and exact expansion can become expensive; this PR exposes typed picker targets and cheap counts where available without adding broad graph loads or schema changes. - Existing NuGet vulnerability warnings remain present for `Scriban.Signed` and `Microsoft.OpenApi`; no dependency changes in this PR. ## Review Notes A review subagent was attempted after implementation but hit the account usage limit before returning findings; I completed an in-session review and replaced member-list includes for collection counts with grouped count queries.
timothy added 1 commit 2026-07-06 00:01:37 +02:00
feat(api): add library browse endpoint
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 4m10s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 4m47s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
127a130737
refs #65
timothy added 1 commit 2026-07-06 07:45:46 +02:00
fix(api): address library browse review findings
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 4m3s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 4m36s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
630119f382
refs #65

refs PR #130
Author
Owner

Review fixes for Fable

Head SHA: 630119f382385040d77cd68b63b1ceb6fb88464b

S1 manual collection artwork + total duration: fixed. Manual collection pages now run bounded aggregate queries over only the page's collection ids/member media ids. Item counts remain grouped by CollectionItems; duration sums known non-zero durations from concrete media items with MediaVersions; artwork chooses the first poster-bearing member deterministically by custom index then media item id and reuses the existing Artwork(...) helper, including Jellyfin/Emby proxy conventions. Smart/multi/rerun aggregate duration/artwork remain deferred as previously documented.

S2 test coverage: fixed with new handler tests:

  • Handle_Should_Page_Across_Media_Manual_Collections_And_Smart_Collections
  • Handle_Should_Hydrate_Manual_Collection_Artwork_And_Total_Duration
  • Handle_Should_Hydrate_Seasons_With_Composed_Titles_And_Episode_Counts
  • Handle_Should_Hydrate_Artists_With_Music_Video_Counts
  • Handle_Should_Apply_Library_Filter_To_Manual_Collections_Only

N1 stale-index paging drift: fixed with an inline comment at collectionSkip explaining the accepted async-rescan stale-index window.

N2 metadata multiplicity: fixed. Movie/show/season/artist hydration now groups by logical media id and chooses the lowest metadata id deterministically before projection.

N3 OpenAPI tag: fixed. Controller tag is now Libraries; v1.json regenerated. Generated TS types did not change because this is tag-only metadata.

N4 LIKE wildcard escaping: fixed. Collection-side name filtering now escapes \, %, and _ and uses the EF Like(..., escapeCharacter) overload.

N5 duration helper: fixed. BestDuration now uses deterministic max non-zero duration instead of first non-zero version in unspecified order.

N6 rerun addressing comment: fixed with an inline note that RerunFirstRun is the default browse picker address and the SPA can substitute RerunRerun for rerun schedule items.

Files changed in this review-fix commit:

  • ErsatzTV.Application/LibraryBrowse/Queries/GetLibraryBrowseItemsHandler.cs
  • ErsatzTV.Tests/Application/LibraryBrowse/GetLibraryBrowseItemsHandlerTests.cs
  • ErsatzTV/Controllers/Api/LibraryBrowseController.cs
  • ErsatzTV/wwwroot/openapi/v1.json

Verification:

  • Focused red/green: new manual collection metadata test failed on existing code, then passed after fix; focused FullyQualifiedName~LibraryBrowse passed 11/11.
  • TZ=UTC dotnet build ErsatzTV/ErsatzTV.csproj passed.
  • ./scripts/update-openapi.sh was run after the successful app build but locally returned Build FAILED after a silent 24m31s with 0 warnings/0 errors. The equivalent OpenAPI target was rerun directly: TZ=UTC dotnet build ErsatzTV.csproj -t:GenerateOpenApiDocuments -v normal from ErsatzTV/, passed and regenerated v1.json.
  • cd web && npm ci passed.
  • cd web && npm run generate:api passed.
  • cd web && npm run typecheck passed.
  • TZ=UTC dotnet build ErsatzTV.sln passed.
  • TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj -v minimal passed: 379 passed.
  • TZ=UTC dotnet test ErsatzTV.Core.Tests/ErsatzTV.Core.Tests.csproj -v minimal passed: 493 passed, 1 skipped.

Deferred/unchanged:

  • Smart/multi/rerun exact aggregate duration/artwork remains deferred because exact expansion is the expensive graph walk called out in the original implementation notes.
  • Playlist remains count-only as accepted.
  • Existing NU1903 warnings for Scriban.Signed/Microsoft.OpenApi remain unrelated to this PR.
## Review fixes for Fable Head SHA: `630119f382385040d77cd68b63b1ceb6fb88464b` **S1 manual collection artwork + total duration**: fixed. Manual collection pages now run bounded aggregate queries over only the page's collection ids/member media ids. Item counts remain grouped by `CollectionItems`; duration sums known non-zero durations from concrete media items with `MediaVersions`; artwork chooses the first poster-bearing member deterministically by custom index then media item id and reuses the existing `Artwork(...)` helper, including Jellyfin/Emby proxy conventions. Smart/multi/rerun aggregate duration/artwork remain deferred as previously documented. **S2 test coverage**: fixed with new handler tests: - `Handle_Should_Page_Across_Media_Manual_Collections_And_Smart_Collections` - `Handle_Should_Hydrate_Manual_Collection_Artwork_And_Total_Duration` - `Handle_Should_Hydrate_Seasons_With_Composed_Titles_And_Episode_Counts` - `Handle_Should_Hydrate_Artists_With_Music_Video_Counts` - `Handle_Should_Apply_Library_Filter_To_Manual_Collections_Only` **N1 stale-index paging drift**: fixed with an inline comment at `collectionSkip` explaining the accepted async-rescan stale-index window. **N2 metadata multiplicity**: fixed. Movie/show/season/artist hydration now groups by logical media id and chooses the lowest metadata id deterministically before projection. **N3 OpenAPI tag**: fixed. Controller tag is now `Libraries`; `v1.json` regenerated. Generated TS types did not change because this is tag-only metadata. **N4 LIKE wildcard escaping**: fixed. Collection-side name filtering now escapes `\`, `%`, and `_` and uses the EF `Like(..., escapeCharacter)` overload. **N5 duration helper**: fixed. `BestDuration` now uses deterministic max non-zero duration instead of first non-zero version in unspecified order. **N6 rerun addressing comment**: fixed with an inline note that `RerunFirstRun` is the default browse picker address and the SPA can substitute `RerunRerun` for rerun schedule items. Files changed in this review-fix commit: - `ErsatzTV.Application/LibraryBrowse/Queries/GetLibraryBrowseItemsHandler.cs` - `ErsatzTV.Tests/Application/LibraryBrowse/GetLibraryBrowseItemsHandlerTests.cs` - `ErsatzTV/Controllers/Api/LibraryBrowseController.cs` - `ErsatzTV/wwwroot/openapi/v1.json` Verification: - Focused red/green: new manual collection metadata test failed on existing code, then passed after fix; focused `FullyQualifiedName~LibraryBrowse` passed 11/11. - `TZ=UTC dotnet build ErsatzTV/ErsatzTV.csproj` passed. - `./scripts/update-openapi.sh` was run after the successful app build but locally returned `Build FAILED` after a silent 24m31s with 0 warnings/0 errors. The equivalent OpenAPI target was rerun directly: `TZ=UTC dotnet build ErsatzTV.csproj -t:GenerateOpenApiDocuments -v normal` from `ErsatzTV/`, passed and regenerated `v1.json`. - `cd web && npm ci` passed. - `cd web && npm run generate:api` passed. - `cd web && npm run typecheck` passed. - `TZ=UTC dotnet build ErsatzTV.sln` passed. - `TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj -v minimal` passed: 379 passed. - `TZ=UTC dotnet test ErsatzTV.Core.Tests/ErsatzTV.Core.Tests.csproj -v minimal` passed: 493 passed, 1 skipped. Deferred/unchanged: - Smart/multi/rerun exact aggregate duration/artwork remains deferred because exact expansion is the expensive graph walk called out in the original implementation notes. - Playlist remains count-only as accepted. - Existing NU1903 warnings for `Scriban.Signed`/`Microsoft.OpenApi` remain unrelated to this PR.
timothy merged commit c4007293bf into main 2026-07-06 07:53:40 +02:00
Sign in to join this conversation.