feat: implement 1B domain entities/repos + 1H library API routes

1B — domain layer:
- New entities: Album, Playlist, Like, PlayHistoryEntry
- Track entity extended with album_id, genre, year fields
- New protocols: AlbumRepository, PlaylistRepository, LikeRepository, HistoryRepository
- ArtistRepository / TrackRepository protocols extended (list, count, update, get_many, etc.)
- New repos: SqlAlchemyAlbum/Playlist/Like/HistoryRepository
- Artist and track repos updated to match extended protocols

1H — library API:
- Pagination: PagedResponse[T] generic, offset-based, limit default 50 max 200
- Schemas: TrackOut, AlbumOut, ArtistOut, PlaylistOut/Create/Update,
  LikeEvent/State, HistoryIn/Out, LibrarySearchResponse
- GET/PATCH/DELETE /tracks with filters, sort, pagination
- GET /albums, /albums/{id}, /albums/{id}/tracks
- GET /artists, /artists/{id}, /artists/{id}/albums, /artists/{id}/tracks
- GET /search/library (ILIKE across tracks/albums/artists)
- Full /playlists CRUD + track add/remove (append-only version bump)
- POST /likes (append-only event log), GET /likes, GET /likes/state
- POST /history (scrobble), GET /history
- deps.py: TrackRepoDep, ArtistRepoDep, AlbumRepoDep, PlaylistRepoDep,
  LikeRepoDep, HistoryRepoDep

ruff ✅  mypy ✅  pytest 45/45 ✅

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/api/v1/tracks.py

@@ -1,48 +1,158 @@
-"""Track endpoints (library CRUD, similarity, optimization, cover, metadata, streaming)."""
+"""Track endpoints."""
 
 import uuid
 from typing import Any
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Query, Response
+
+from app.api.deps import AlbumRepoDep, ArtistRepoDep, CurrentUser, FileStorageDep, TrackRepoDep
+from app.api.schemas.pagination import PagedResponse
+from app.api.schemas.track import TrackOut, TrackUpdate
+from app.domain.entities.album import Album
+from app.domain.entities.track import Artist, Track
+from app.domain.errors import NotFoundError
 
 router = APIRouter(prefix="/tracks", tags=["tracks"])
 
 
+async def _build_track_out(
+    tracks: list[Track],
+    artists: dict[uuid.UUID, Artist],
+    albums: dict[uuid.UUID, Album],
+) -> list[TrackOut]:
+    return [
+        TrackOut(
+            id=t.id,
+            title=t.title,
+            artist_id=t.artist_id,
+            artist_name=artists[t.artist_id].name if t.artist_id in artists else "Unknown Artist",
+            album_id=t.album_id,
+            album_title=albums[t.album_id].title if t.album_id and t.album_id in albums else None,
+            duration_seconds=t.duration_seconds,
+            file_format=t.file_format,
+            file_size=t.file_size,
+            metadata_status=t.metadata_status,
+            source=t.source,
+            created_at=t.created_at,
+        )
+        for t in tracks
+    ]
+
+
 @router.get("")
-async def list_tracks() -> Any: ...
+async def list_tracks(
+    track_repo: TrackRepoDep,
+    artist_repo: ArtistRepoDep,
+    album_repo: AlbumRepoDep,
+    _: CurrentUser,
+    artist_id: uuid.UUID | None = None,
+    album_id: uuid.UUID | None = None,
+    q: str | None = None,
+    sort_by: str = Query("created_at", pattern="^(title|created_at|artist)$"),
+    order: str = Query("desc", pattern="^(asc|desc)$"),
+    limit: int = Query(50, ge=1, le=200),
+    offset: int = Query(0, ge=0),
+) -> PagedResponse[TrackOut]:
+    tracks = await track_repo.list(
+        artist_id=artist_id,
+        album_id=album_id,
+        q=q,
+        sort_by=sort_by,
+        order=order,
+        limit=limit,
+        offset=offset,
+    )
+    total = await track_repo.count(artist_id=artist_id, album_id=album_id, q=q)
+
+    artist_ids = list({t.artist_id for t in tracks})
+    album_ids = list({t.album_id for t in tracks if t.album_id is not None})
+    artists = {a.id: a for a in await artist_repo.get_many(artist_ids)}
+    albums = {a.id: a for a in await album_repo.get_many(album_ids)}
+
+    items = await _build_track_out(tracks, artists, albums)
+    return PagedResponse(items=items, total=total, limit=limit, offset=offset)
 
 
 @router.get("/{track_id}")
-async def get_track(track_id: uuid.UUID) -> Any: ...
+async def get_track(
+    track_id: uuid.UUID,
+    track_repo: TrackRepoDep,
+    artist_repo: ArtistRepoDep,
+    album_repo: AlbumRepoDep,
+    _: CurrentUser,
+) -> TrackOut:
+    track = await track_repo.get_by_id(track_id)
+    if track is None:
+        raise NotFoundError(f"Track {track_id} not found.")
+
+    artist_ids = [track.artist_id]
+    album_ids = [track.album_id] if track.album_id else []
+    artists = {a.id: a for a in await artist_repo.get_many(artist_ids)}
+    albums = {a.id: a for a in await album_repo.get_many(album_ids)}
+
+    items = await _build_track_out([track], artists, albums)
+    return items[0]
 
 
 @router.patch("/{track_id}")
-async def update_track(track_id: uuid.UUID) -> Any: ...
+async def update_track(
+    track_id: uuid.UUID,
+    body: TrackUpdate,
+    track_repo: TrackRepoDep,
+    artist_repo: ArtistRepoDep,
+    album_repo: AlbumRepoDep,
+    _: CurrentUser,
+) -> TrackOut:
+    track = await track_repo.update(
+        track_id,
+        title=body.title,
+        genre=body.genre,
+        year=body.year,
+    )
+
+    artist_ids = [track.artist_id]
+    album_ids = [track.album_id] if track.album_id else []
+    artists = {a.id: a for a in await artist_repo.get_many(artist_ids)}
+    albums = {a.id: a for a in await album_repo.get_many(album_ids)}
+
+    items = await _build_track_out([track], artists, albums)
+    return items[0]
 
 
-@router.delete("/{track_id}")
-async def delete_track(track_id: uuid.UUID) -> Any: ...
+@router.delete("/{track_id}", status_code=204)
+async def delete_track(
+    track_id: uuid.UUID,
+    track_repo: TrackRepoDep,
+    storage: FileStorageDep,
+    _: CurrentUser,
+) -> Response:
+    track = await track_repo.get_by_id(track_id)
+    if track is None:
+        raise NotFoundError(f"Track {track_id} not found.")
+    await track_repo.delete(track_id)
+    await storage.delete(track.file_path)
+    return Response(status_code=204)
 
 
 @router.get("/{track_id}/similar")
-async def get_similar_tracks(track_id: uuid.UUID) -> Any: ...
+async def get_similar_tracks(track_id: uuid.UUID, _: CurrentUser) -> Any: ...
 
 
 @router.post("/{track_id}/optimize")
-async def optimize_track(track_id: uuid.UUID) -> Any: ...
+async def optimize_track(track_id: uuid.UUID, _: CurrentUser) -> Any: ...
 
 
 @router.get("/{track_id}/cover")
-async def get_track_cover(track_id: uuid.UUID) -> Any: ...
+async def get_track_cover(track_id: uuid.UUID, _: CurrentUser) -> Any: ...
 
 
 @router.post("/{track_id}/metadata/enrich")
-async def enrich_metadata(track_id: uuid.UUID) -> Any: ...
+async def enrich_metadata(track_id: uuid.UUID, _: CurrentUser) -> Any: ...
 
 
 @router.get("/{track_id}/metadata/matches")
-async def get_metadata_matches(track_id: uuid.UUID) -> Any: ...
+async def get_metadata_matches(track_id: uuid.UUID, _: CurrentUser) -> Any: ...
 
 
 @router.put("/{track_id}/metadata")
-async def set_metadata(track_id: uuid.UUID) -> Any: ...
+async def set_metadata(track_id: uuid.UUID, _: CurrentUser) -> Any: ...