"""Общие схемы API: страница списка, параметры пагинации, тело доменной ошибки (spec directories-api)."""

from typing import Generic, TypeVar

from pydantic import BaseModel, Field

T = TypeVar("T")

DEFAULT_PAGE_LIMIT = 50
MAX_PAGE_LIMIT = 200


class Page(BaseModel, Generic[T]):
    """Страница списка: элементы, общее число записей по фильтру, запрошенные `limit`/`offset`."""

    items: list[T]
    total: int
    limit: int
    offset: int


class PageParams(BaseModel):
    """Параметры пагинации из query: `Annotated[PageParams, Query()]`."""

    limit: int = Field(DEFAULT_PAGE_LIMIT, ge=1, le=MAX_PAGE_LIMIT)
    offset: int = Field(0, ge=0)


class ErrorDetail(BaseModel):
    """Тело `detail` доменной ошибки (для `responses` в OpenAPI): `{"code": "...", "message": "..."}`."""

    code: str
    message: str