:param category_id: Filter by category ID; ``0`` means all categories.
    Default ``0``.
:type category_id: int
:param page: Page number. Default ``1``.
:type page: int
:param country_id: Filter by country ID; omit for all countries.
:type country_id: int | None
:param order_type: Sort order, e.g. ``"promotedAt"``. Default
    ``"promotedAt"``.
:type order_type: str
:param only_available: Show only groups with free slots. Default
    ``False``.
:type only_available: bool
:param only_open: Show only open groups. Default ``False``.
:type only_open: bool
:param only_cam: Show only groups with camera verification. Default
    ``False``.
:type only_cam: bool
:returns: List of group mappings with ``id``, ``title``, ``category``,
    ``owner``, ``slogan`` and ``member_count``.
:rtype: list[dict[str, Any]]
:raises RuntimeError: If YPT credentials are not configured.

:param date: Date in YYYY-MM-DD format, e.g. ``"2026-09-12"``.
:type date: str
:returns: Mapping with ``date``, ``study_ms``/``study_hours``,
    ``rest_ms``/``rest_hours``, ``max_study_ms``/``max_study_hours``,
    ``added_ms``/``added_hours`` and a ``subjects`` list of
    ``{subject_id, subject_title, study_ms, study_hours}``.
:rtype: dict[str, Any]
:raises RuntimeError: If YPT credentials are not configured.

:param group_id: Study group ID, e.g. from ``get_my_groups``.
:type group_id: int
:param country_id: Country ID, as returned by ``get_profile``.
:type country_id: int
:returns: List of member mappings with ``user_id``, ``nickname``,
    ``category``, ``study_ms``/``study_hours`` and ``studying``
    (bool, whether the member is currently studying).
:rtype: list[dict[str, Any]]
:raises RuntimeError: If YPT credentials are not configured.

:param category_id: Category ID, as returned by ``get_profile``.
:type category_id: int
:param country_id: Country ID, as returned by ``get_profile``.
:type country_id: int
:param date: Leaderboard date in YYYY-MM-DD format.
:type date: str
:param page: Page number, 20 entries per page. Default ``1``.
:type page: int
:param rank_type: Ranking period, ``"day"`` or ``"week"``. Default
    ``"day"``.
:type rank_type: str
:param limit: Maximum number of members to return. Default ``20``.
:type limit: int
:returns: Mapping with ``total_count`` and the ``members`` list of
    ``{nickname, user_id, study_ms, study_hours, studicon_id}``.
:rtype: dict[str, Any]
:raises RuntimeError: If YPT credentials are not configured.

:returns: List of group mappings with ``id``, ``title``, ``category``,
    ``owner``, ``slogan`` and ``member_count``.
:rtype: list[dict[str, Any]]
:raises RuntimeError: If YPT credentials are not configured.

:param category_id: Category ID, as returned by ``get_profile``.
:type category_id: int
:param country_id: Country ID, as returned by ``get_profile``.
:type country_id: int
:returns: Your 1-based rank as ``int``, or ``None`` when no rank is
    available for the category.
:rtype: int | None
:raises RuntimeError: If YPT credentials are not configured.

:returns: Mapping with ``nickname``, ``email``, ``category_code``,
    ``category_id``, ``country_id``, the ``subjects`` list
    (``id``, ``title``, ``study_ms``/``study_hours``, ``archived``) and
    the ``day_log`` for today (see the day-log shape in
    ``get_day_log``).
:rtype: dict[str, Any]
:raises RuntimeError: If YPT credentials are not configured.

The session start timestamp is stored on disk (so ``stop_study`` can be
called without arguments) and also returned as ``started_at`` for the
caller to keep.

:param subject: Subject title to start studying, e.g. ``"Матеша"``.
:type subject: str
:param device_model: Device model reported to the YPT API. Defaults to
    ``"ypt-mcp"``.
:type device_model: str
:returns: Mapping with ``started_at`` (epoch ms) plus the full day-log
    shape described in ``get_day_log``.
:rtype: dict[str, Any]
:raises RuntimeError: If YPT credentials are not configured.

If ``started_at`` is omitted the timestamp recorded by :func:`start_study`
is used; the recorded value is cleared after a successful stop.

:param started_at: Session start time in epoch milliseconds, as returned
    by ``start_study``. Optional; defaults to the recorded session.
:type started_at: int | None
:param device_model: Device model reported to the YPT API. Defaults to
    ``"ypt-mcp"``.
:type device_model: str
:returns: The full day-log shape described in ``get_day_log``.
:rtype: dict[str, Any]
:raises RuntimeError: If there is no recorded session and ``started_at``
    is not provided, or if YPT credentials are not configured.