Generalize YouTube-backed endpoints behind a source parameter

Removes the last YouTube-specific routes (/youtube/*) and merges them
into the general track/album/playlist endpoints, keyed by a `source`
string validated against TrackSource. This mirrors the earlier track
search merge for albums and playlist-track additions:

- GetAlbums now merges local albums with live YouTube Music search
  results, paginated via a youtubeContinuationToken, deduped against
  already-materialized ExternalAlbum rows.
- New GET /albums/external/{source}/{externalId} and
  GET /tracks/external/{source}/{externalId}/stream replace the
  YouTube-only equivalents.
- POST /playlists/{id}/tracks replaces the separate
  .../youtube-tracks endpoint, accepting an optional Source/ExternalId
  pair alongside TrackId.
- AlbumSearchItemResponse/AlbumsSearchResponse follow the same
  discriminated-union + trailing-HasNextPage-field pattern already
  used for track search, so HasNextPage stays a required field in the
  generated OpenAPI schema.
- Frontend routes renamed accordingly (/albums/youtube/[albumId] ->
  /albums/external/[source]/[externalId], etc.) with a single
  /api/thumbnail proxy replacing /api/youtube/thumbnail.

Musify.Api.Endpoints.YouTubeEndpoints and the standalone
SearchYouTubeAlbums query are removed as a result.

backend/Core/Musify.Application/Albums/GetAlbums.cs

@@ -1,23 +1,32 @@
 using ErrorOr;
 using Mediator;
 using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
 using Musify.Application.Albums.Responses;
 using Musify.Application.Contracts;
-using Musify.Application.Shared;
+using Musify.Domain.Entities;
+using Musify.Domain.ValueObjects;
 using X.PagedList;
 using X.PagedList.EF;
 
 namespace Musify.Application.Albums
 {
-    public record GetAlbumsQuery(string? Title, int PageNumber, int PageSize)
-        : IQuery<ErrorOr<PaginatedResponse<AlbumApplicationResponse>>>;
+    public record GetAlbumsQuery(string? Title, int PageNumber, int PageSize, string? YoutubeContinuationToken = null)
+        : IQuery<ErrorOr<AlbumsSearchResponse>>;
 
-    public class GetAlbumsQueryHandler(IDatabase database)
-        : IQueryHandler<GetAlbumsQuery, ErrorOr<PaginatedResponse<AlbumApplicationResponse>>>
+    public class GetAlbumsQueryHandler(
+        IDatabase database,
+        IYouTubeMusicService youTubeMusicService,
+        ILogger<GetAlbumsQueryHandler> logger)
+        : IQueryHandler<GetAlbumsQuery, ErrorOr<AlbumsSearchResponse>>
     {
-        public async ValueTask<ErrorOr<PaginatedResponse<AlbumApplicationResponse>>> Handle(GetAlbumsQuery request, CancellationToken cancellationToken)
+        // Mirrors GetTracksQueryHandler's threshold: a title shorter than this is too likely to
+        // still be mid-keystroke to justify a live call to the external search API.
+        private const int MinTitleLengthForYouTubeSearch = 2;
+
+        public async ValueTask<ErrorOr<AlbumsSearchResponse>> Handle(GetAlbumsQuery request, CancellationToken cancellationToken)
         {
-            var albumsQuery = database.UserAlbums
+            var albumsQuery = database.Albums
                 .AsNoTracking()
                 .AsQueryable();
 
@@ -43,11 +52,62 @@ namespace Musify.Application.Albums
                 })
                 .ToPagedListAsync(request.PageNumber, request.PageSize, totalCount, cancellationToken);
 
-            var pagedAlbums = new StaticPagedList<AlbumApplicationResponse>(
-                pagedEntities.Select(entry => AlbumApplicationResponse.FromEntity(entry.Album, entry.TrackCount, entry.CoverTrackIds)),
-                pagedEntities.PageNumber, pagedEntities.PageSize, pagedEntities.TotalItemCount);
+            var localItems = pagedEntities
+                .Select(entry => AlbumSearchItemResponse.FromAlbum(
+                    AlbumApplicationResponse.FromEntity(entry.Album, entry.TrackCount, entry.CoverTrackIds)))
+                .ToList();
 
-            return PaginatedResponse<AlbumApplicationResponse>.FromPagedList(pagedAlbums);
+            var knownExternalIds = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var entry in pagedEntities)
+            {
+                if (entry.Album is ExternalAlbum { Source: TrackSource.YouTube } external)
+                    knownExternalIds.Add(external.ExternalId);
+            }
+
+            var youtubeItems = new List<AlbumSearchItemResponse>();
+            string? nextContinuationToken = null;
+            var youtubeUnavailable = false;
+
+            if (request.Title?.Trim().Length >= MinTitleLengthForYouTubeSearch)
+                (youtubeItems, nextContinuationToken, youtubeUnavailable) =
+                    await SearchYouTubeAsync(request.Title, request.YoutubeContinuationToken, knownExternalIds, cancellationToken);
+
+            return AlbumsSearchResponse.Create(
+                [.. localItems, .. youtubeItems],
+                pagedEntities.PageNumber,
+                pagedEntities.PageSize,
+                pagedEntities.PageCount,
+                pagedEntities.TotalItemCount,
+                pagedEntities.HasPreviousPage,
+                pagedEntities.HasNextPage,
+                nextContinuationToken,
+                youtubeUnavailable);
+        }
+
+        private async Task<(List<AlbumSearchItemResponse> Items, string? NextContinuationToken, bool Unavailable)> SearchYouTubeAsync(
+            string title,
+            string? continuationToken,
+            HashSet<string> knownExternalIds,
+            CancellationToken cancellationToken)
+        {
+            var searchResult = await youTubeMusicService.SearchAlbumsAsync(title, continuationToken ?? string.Empty, cancellationToken);
+            if (searchResult.IsError)
+            {
+                logger.LogInformation(
+                    "YouTube album search unavailable while combining album results: {Error}", searchResult.FirstError.Description);
+                return ([], null, true);
+            }
+
+            var items = searchResult.Value.Items
+                .Where(album => knownExternalIds.Add(album.AlbumId))
+                .Select(AlbumSearchItemResponse.FromYouTubeAlbum)
+                .ToList();
+
+            var nextToken = string.IsNullOrEmpty(searchResult.Value.ContinuationToken)
+                ? null
+                : searchResult.Value.ContinuationToken;
+
+            return (items, nextToken, false);
         }
     }
 }