refactor: Update response types to use common schemas across API endpoints

app/api/v1/main.py

@@ -3,6 +3,7 @@
 from fastapi import APIRouter
 
 from app.core.logging import get_logger
+from app.schemas.common import HealthResponse
 
 router = APIRouter()
 
@@ -10,7 +11,7 @@ logger = get_logger(__name__)
 
 
 @router.get("/")
-def health() -> dict[str, str]:
+def health() -> HealthResponse:
     """Health check endpoint."""
     logger.info("Health check endpoint accessed")
-    return {"status": "healthy"}
+    return HealthResponse(status="healthy")

app/api/v1/player.py

@@ -7,7 +7,13 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from app.core.dependencies import get_current_active_user_flexible
 from app.core.logging import get_logger
 from app.models.user import User
-from app.schemas.player import PlayerModeRequest, PlayerSeekRequest, PlayerVolumeRequest
+from app.schemas.common import MessageResponse
+from app.schemas.player import (
+    PlayerModeRequest,
+    PlayerSeekRequest,
+    PlayerStateResponse,
+    PlayerVolumeRequest,
+)
 from app.services.player import get_player_service
 
 logger = get_logger(__name__)
@@ -18,12 +24,12 @@ router = APIRouter(prefix="/player", tags=["player"])
 @router.post("/play")
 async def play(
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Play current sound."""
     try:
         player = get_player_service()
         await player.play()
-        return {"message": "Playback started"}
+        return MessageResponse(message="Playback started")
     except Exception as e:
         logger.exception("Error starting playback")
         raise HTTPException(
@@ -36,12 +42,12 @@ async def play(
 async def play_at_index(
     index: int,
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Play sound at specific index."""
     try:
         player = get_player_service()
         await player.play(index)
-        return {"message": f"Playing sound at index {index}"}
+        return MessageResponse(message=f"Playing sound at index {index}")
     except ValueError as e:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
@@ -58,12 +64,12 @@ async def play_at_index(
 @router.post("/pause")
 async def pause(
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Pause playback."""
     try:
         player = get_player_service()
         await player.pause()
-        return {"message": "Playback paused"}
+        return MessageResponse(message="Playback paused")
     except Exception as e:
         logger.exception("Error pausing playback")
         raise HTTPException(
@@ -75,12 +81,12 @@ async def pause(
 @router.post("/stop")
 async def stop(
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Stop playback."""
     try:
         player = get_player_service()
         await player.stop_playback()
-        return {"message": "Playback stopped"}
+        return MessageResponse(message="Playback stopped")
     except Exception as e:
         logger.exception("Error stopping playback")
         raise HTTPException(
@@ -92,12 +98,12 @@ async def stop(
 @router.post("/next")
 async def next_track(
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Skip to next track."""
     try:
         player = get_player_service()
         await player.next()
-        return {"message": "Skipped to next track"}
+        return MessageResponse(message="Skipped to next track")
     except Exception as e:
         logger.exception("Error skipping to next track")
         raise HTTPException(
@@ -109,12 +115,12 @@ async def next_track(
 @router.post("/previous")
 async def previous_track(
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Go to previous track."""
     try:
         player = get_player_service()
         await player.previous()
-        return {"message": "Went to previous track"}
+        return MessageResponse(message="Went to previous track")
     except Exception as e:
         logger.exception("Error going to previous track")
         raise HTTPException(
@@ -127,12 +133,12 @@ async def previous_track(
 async def seek(
     request: PlayerSeekRequest,
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Seek to specific position in current track."""
     try:
         player = get_player_service()
         await player.seek(request.position_ms)
-        return {"message": f"Seeked to position {request.position_ms}ms"}
+        return MessageResponse(message=f"Seeked to position {request.position_ms}ms")
     except Exception as e:
         logger.exception("Error seeking to position %s", request.position_ms)
         raise HTTPException(
@@ -145,12 +151,12 @@ async def seek(
 async def set_volume(
     request: PlayerVolumeRequest,
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Set playback volume."""
     try:
         player = get_player_service()
         await player.set_volume(request.volume)
-        return {"message": f"Volume set to {request.volume}"}
+        return MessageResponse(message=f"Volume set to {request.volume}")
     except Exception as e:
         logger.exception("Error setting volume to %s", request.volume)
         raise HTTPException(
@@ -163,12 +169,12 @@ async def set_volume(
 async def set_mode(
     request: PlayerModeRequest,
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Set playback mode."""
     try:
         player = get_player_service()
         await player.set_mode(request.mode)
-        return {"message": f"Mode set to {request.mode.value}"}
+        return MessageResponse(message=f"Mode set to {request.mode.value}")
     except Exception as e:
         logger.exception("Error setting mode to %s", request.mode)
         raise HTTPException(
@@ -180,12 +186,12 @@ async def set_mode(
 @router.post("/reload-playlist")
 async def reload_playlist(
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, str]:
+) -> MessageResponse:
     """Reload current playlist."""
     try:
         player = get_player_service()
         await player.reload_playlist()
-        return {"message": "Playlist reloaded"}
+        return MessageResponse(message="Playlist reloaded")
     except Exception as e:
         logger.exception("Error reloading playlist")
         raise HTTPException(
@@ -197,11 +203,12 @@ async def reload_playlist(
 @router.get("/state")
 async def get_state(
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],  # noqa: ARG001
-) -> dict[str, Any]:
+) -> PlayerStateResponse:
     """Get current player state."""
     try:
         player = get_player_service()
-        return player.get_state()
+        state = player.get_state()
+        return PlayerStateResponse(**state)
     except Exception as e:
         logger.exception("Error getting player state")
         raise HTTPException(

app/api/v1/playlists.py

@@ -8,6 +8,7 @@ from sqlmodel.ext.asyncio.session import AsyncSession
 from app.core.database import get_db
 from app.core.dependencies import get_current_active_user_flexible
 from app.models.user import User
+from app.schemas.common import MessageResponse
 from app.schemas.playlist import (
     PlaylistAddSoundRequest,
     PlaylistCreateRequest,
@@ -120,10 +121,10 @@ async def delete_playlist(
     playlist_id: int,
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],
     playlist_service: Annotated[PlaylistService, Depends(get_playlist_service)],
-) -> dict[str, str]:
+) -> MessageResponse:
     """Delete a playlist."""
     await playlist_service.delete_playlist(playlist_id, current_user.id)
-    return {"message": "Playlist deleted successfully"}
+    return MessageResponse(message="Playlist deleted successfully")
 
 
 @router.get("/search/{query}")
@@ -165,7 +166,7 @@ async def add_sound_to_playlist(
     request: PlaylistAddSoundRequest,
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],
     playlist_service: Annotated[PlaylistService, Depends(get_playlist_service)],
-) -> dict[str, str]:
+) -> MessageResponse:
     """Add a sound to a playlist."""
     await playlist_service.add_sound_to_playlist(
         playlist_id=playlist_id,
@@ -173,7 +174,7 @@ async def add_sound_to_playlist(
         user_id=current_user.id,
         position=request.position,
     )
-    return {"message": "Sound added to playlist successfully"}
+    return MessageResponse(message="Sound added to playlist successfully")
 
 
 @router.delete("/{playlist_id}/sounds/{sound_id}")
@@ -182,14 +183,14 @@ async def remove_sound_from_playlist(
     sound_id: int,
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],
     playlist_service: Annotated[PlaylistService, Depends(get_playlist_service)],
-) -> dict[str, str]:
+) -> MessageResponse:
     """Remove a sound from a playlist."""
     await playlist_service.remove_sound_from_playlist(
         playlist_id=playlist_id,
         sound_id=sound_id,
         user_id=current_user.id,
     )
-    return {"message": "Sound removed from playlist successfully"}
+    return MessageResponse(message="Sound removed from playlist successfully")
 
 
 @router.put("/{playlist_id}/sounds/reorder")
@@ -198,14 +199,14 @@ async def reorder_playlist_sounds(
     request: PlaylistReorderRequest,
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],
     playlist_service: Annotated[PlaylistService, Depends(get_playlist_service)],
-) -> dict[str, str]:
+) -> MessageResponse:
     """Reorder sounds in a playlist."""
     await playlist_service.reorder_playlist_sounds(
         playlist_id=playlist_id,
         user_id=current_user.id,
         sound_positions=request.sound_positions,
     )
-    return {"message": "Playlist sounds reordered successfully"}
+    return MessageResponse(message="Playlist sounds reordered successfully")
 
 
 @router.put("/{playlist_id}/set-current")
@@ -223,10 +224,10 @@ async def set_current_playlist(
 async def unset_current_playlist(
     current_user: Annotated[User, Depends(get_current_active_user_flexible)],
     playlist_service: Annotated[PlaylistService, Depends(get_playlist_service)],
-) -> dict[str, str]:
+) -> MessageResponse:
     """Unset the current playlist."""
     await playlist_service.unset_current_playlist(current_user.id)
-    return {"message": "Current playlist unset successfully"}
+    return MessageResponse(message="Current playlist unset successfully")
 
 
 @router.get("/{playlist_id}/stats")