Add favorite characters

Author: koldakov

futuramaapi/repositories/migrations/versions/8e79c0472843_add_favorite_character_model.py

@@ -0,0 +1,80 @@
+"""Add favorite character model
+
+Revision ID: 8e79c0472843
+Revises: ca664de1bf44
+Create Date: 2026-01-01 22:42:59.969711
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "8e79c0472843"
+down_revision: str | None = "ca664de1bf44"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "favorite_characters",
+        sa.Column(
+            "user_uuid",
+            sa.UUID(),
+            nullable=False,
+        ),
+        sa.Column(
+            "character_uuid",
+            sa.UUID(),
+            nullable=False,
+        ),
+        sa.Column(
+            "id",
+            sa.Integer(),
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(
+                timezone=True,
+            ),
+            server_default=sa.text(
+                "now()",
+            ),
+            nullable=False,
+        ),
+        sa.Column(
+            "uuid",
+            sa.UUID(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            [
+                "character_uuid",
+            ],
+            [
+                "characters.uuid",
+            ],
+        ),
+        sa.ForeignKeyConstraint(
+            [
+                "user_uuid",
+            ],
+            [
+                "users.uuid",
+            ],
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "user_uuid",
+            "character_uuid",
+            name="uniq_favorite_user_character",
+        ),
+        sa.UniqueConstraint("uuid"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("favorite_characters")

futuramaapi/repositories/models.py

@@ -1,3 +1,4 @@
+import uuid
 from datetime import UTC, datetime, timedelta
 from enum import Enum
 from functools import partial
@@ -18,6 +19,7 @@
     Result,
     Select,
     SmallInteger,
+    UniqueConstraint,
     Update,
     func,
     select,
@@ -169,6 +171,9 @@ class CharacterGender(Enum):
         secondary="episode_character_association",
         back_populates="characters",
     )
+    favorite_characters: Mapped[list["FavoriteCharacterModel"]] = relationship(
+        back_populates="character",
+    )
 
     @classmethod
     def get_cond_list(cls, **kwargs) -> list[BinaryExpression]:
@@ -249,6 +254,9 @@ class UserModel(Base):
     active_sessions: Mapped[list["AuthSessionModel"]] = relationship(
         back_populates="user",
     )
+    favorite_characters: Mapped[list["FavoriteCharacterModel"]] = relationship(
+        back_populates="user",
+    )
 
     @staticmethod
     def get_select_in_load() -> list[Load]:
@@ -498,3 +506,31 @@ class SystemMessage(Base):
         nullable=False,
         unique=True,
     )
+
+
+class FavoriteCharacterModel(Base):
+    __tablename__ = "favorite_characters"
+
+    user_uuid: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.uuid"),
+        nullable=False,
+    )
+    character_uuid: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("characters.uuid"),
+        nullable=False,
+    )
+
+    user: Mapped["UserModel"] = relationship(
+        back_populates="favorite_characters",
+    )
+    character: Mapped["CharacterModel"] = relationship(
+        back_populates="favorite_characters",
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "user_uuid",
+            "character_uuid",
+            name="uniq_favorite_user_character",
+        ),
+    )

futuramaapi/routers/__init__.py

@@ -5,6 +5,7 @@
 from .rest.characters import router as characters_router
 from .rest.crypto import router as crypto_router
 from .rest.episodes import router as episodes_router
+from .rest.favorites import router as favorites_router
 from .rest.notifications import router as notification_router
 from .rest.randoms import router as randoms_router
 from .rest.root import router as root_router
@@ -29,3 +30,4 @@
 api_router.include_router(seasons_router)
 api_router.include_router(tokens_router)
 api_router.include_router(users_router)
+api_router.include_router(favorites_router)

futuramaapi/routers/rest/favorites/__init__.py

@@ -0,0 +1,5 @@
+from .api import router
+
+__all__ = [
+    "router",
+]

futuramaapi/routers/rest/favorites/api.py

@@ -0,0 +1,112 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, status
+from fastapi_pagination import Page
+
+from futuramaapi.routers.exceptions import NotFoundResponse
+from futuramaapi.routers.rest.users.dependencies import _oauth2_scheme
+from futuramaapi.routers.services.favorites.create_favorite_character import CreateFavoriteCharacterService
+from futuramaapi.routers.services.favorites.delete_favorite_character import DeleteFavoriteCharacterService
+from futuramaapi.routers.services.favorites.list_favorite_characters import (
+    ListFavoriteCharacters,
+    ListFavoriteCharactersResponse,
+)
+
+router = APIRouter(
+    prefix="/favorites/characters",
+    tags=[
+        "Favorite Characters",
+    ],
+)
+
+
+@router.post(
+    "/{character_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    responses={
+        status.HTTP_404_NOT_FOUND: {
+            "model": NotFoundResponse,
+        },
+        status.HTTP_409_CONFLICT: {
+            "example": "Character is already in favorites",
+        },
+    },
+    name="create_favorite_character",
+)
+async def create_favorite_character(
+    character_id: int,
+    token: Annotated[str, Depends(_oauth2_scheme)],
+) -> None:
+    """
+    Add character to favorites.
+
+    Adds the specified character to the authenticated user's favorites list.
+
+    If the character is already present in favorites, the request will fail
+    with a conflict error.
+
+    This endpoint requires authentication.
+    """
+    service: CreateFavoriteCharacterService = CreateFavoriteCharacterService(
+        token=token,
+        character_id=character_id,
+    )
+    await service()
+
+
+@router.get(
+    "",
+    status_code=status.HTTP_200_OK,
+    response_model=Page[ListFavoriteCharactersResponse],
+    name="favorite_characters",
+)
+async def get_favorite_characters(
+    token: Annotated[str, Depends(_oauth2_scheme)],
+) -> Page[ListFavoriteCharactersResponse]:
+    """
+    Retrieve favorite characters.
+
+    Returns a paginated list of characters added to the current user's favorites.
+
+    You can use standard pagination parameters to control the size and order of the response.
+    This endpoint requires authentication and returns only the favorites of the authorized user.
+
+    Check the query parameters section for available pagination options.
+    """
+    service: ListFavoriteCharacters = ListFavoriteCharacters(token=token)
+    return await service()
+
+
+@router.delete(
+    "/{character_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    responses={
+        status.HTTP_404_NOT_FOUND: {
+            "model": NotFoundResponse,
+        },
+        status.HTTP_409_CONFLICT: {
+            "example": "Character is already in favorites",
+        },
+    },
+    name="create_favorite_character",
+)
+async def delete_favorite_character(
+    character_id: int,
+    token: Annotated[str, Depends(_oauth2_scheme)],
+) -> None:
+    """
+    Remove character from favorites.
+
+    Removes the specified character from the authenticated user's favorites list.
+
+    If the character does not exist or is not present in the user's favorites,
+    the request will fail with a not found error.
+
+    This endpoint requires authentication and performs a destructive operation
+    without returning a response body.
+    """
+    service: DeleteFavoriteCharacterService = DeleteFavoriteCharacterService(
+        token=token,
+        character_id=character_id,
+    )
+    await service()

futuramaapi/routers/services/__init__.py

@@ -1,5 +1,11 @@
-from ._base import BaseService
+from ._base import (
+    BaseService,
+    BaseSessionService,
+    BaseUserAuthenticatedService,
+)
 
 __all__ = [
     "BaseService",
+    "BaseSessionService",
+    "BaseUserAuthenticatedService",
 ]

futuramaapi/routers/services/_base.py

@@ -1,13 +1,89 @@
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from typing import Any
+from typing import Any, Generic, TypeVar
+
+from fastapi import HTTPException, status
+from fastapi_pagination import Page
+from sqlalchemy import Select, select
+from sqlalchemy.exc import NoResultFound
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from futuramaapi.helpers.pydantic import BaseModel
+from futuramaapi.mixins.pydantic import DecodedTokenError
+from futuramaapi.repositories.models import UserModel
+from futuramaapi.repositories.session import session_manager
+from futuramaapi.routers.rest.tokens.schemas import DecodedUserToken
+
+TResponse = TypeVar(
+    "TResponse",
+    bound=BaseModel | Sequence[BaseModel] | Page[BaseModel] | None,
+)
 
 
-class BaseService(BaseModel, ABC):
+class BaseService(BaseModel, ABC, Generic[TResponse]):
     context: dict[str, Any] | None = None
 
     @abstractmethod
-    async def __call__(self, *args, **kwargs) -> BaseModel | Sequence[BaseModel] | None:
+    async def __call__(self, *args, **kwargs) -> TResponse:
         pass
+
+
+class BaseSessionService(BaseService[TResponse], ABC, Generic[TResponse]):
+    def __init__(self, /, **data: Any) -> None:
+        super().__init__(**data)
+
+        self._session: AsyncSession | None = None
+
+    @property
+    def session(self) -> AsyncSession:
+        if self._session is None:
+            raise RuntimeError("Session is not initialized")
+
+        return self._session
+
+    @abstractmethod
+    async def process(self, *args, **kwargs) -> TResponse: ...
+
+    async def __call__(self, *args, **kwargs) -> TResponse:
+        async with session_manager.session() as session:
+            self._session = session
+
+            return await self.process(*args, **kwargs)
+
+
+class BaseUserAuthenticatedService(BaseSessionService[TResponse], ABC, Generic[TResponse]):
+    token: str
+
+    def __init__(self, /, **data: Any) -> None:
+        super().__init__(**data)
+
+        self._user: UserModel | None = None
+
+    @property
+    def user(self) -> UserModel:
+        if self._user is None:
+            raise RuntimeError("User is not initialized")
+
+        return self._user
+
+    @property
+    def __get_user_statement(self) -> Select[tuple[UserModel]]:
+        try:
+            decoded_token: DecodedUserToken = DecodedUserToken.decode(self.token, allowed_type="access")
+        except DecodedTokenError:
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) from None
+
+        return select(UserModel).where(UserModel.id == decoded_token.user.id)
+
+    async def __set_user(self) -> None:
+        try:
+            self._user = (await self.session.execute(self.__get_user_statement)).scalars().one()
+        except NoResultFound:
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) from None
+
+    async def __call__(self, *args, **kwargs) -> TResponse:
+        async with session_manager.session() as session:
+            self._session = session
+            await self.__set_user()
+
+            return await self.process(*args, **kwargs)