"""``youtube.comments`` I/O contracts.

A lean surface over the Apify-compatible ``YouTubeCommentsInput``; the actor's
``CommentItem`` is reused verbatim as the output element for parity.
"""

from __future__ import annotations

from typing import Literal

from pydantic import BaseModel, Field

from app.proprietary.platforms.youtube import CommentItem

MAX_COMMENT_VIDEOS = 20
"""Per-call cap on how many video URLs one request may harvest comments from."""


class CommentsInput(BaseModel):
    urls: list[str] = Field(
        min_length=1,
        max_length=MAX_COMMENT_VIDEOS,
        description="YouTube video URLs to fetch comments (and replies) for (1-20).",
    )
    max_comments: int = Field(
        default=20,
        ge=1,
        le=100_000,
        description=(
            "Max items returned per video, counting both top-level comments and "
            "their replies."
        ),
    )
    sort_by: Literal["TOP_COMMENTS", "NEWEST_FIRST"] = Field(
        default="NEWEST_FIRST",
        description="Comment ordering: most-liked first, or most-recent first.",
    )


class CommentsOutput(BaseModel):
    items: list[CommentItem] = Field(
        default_factory=list,
        description="One item per comment or reply, in the scraper's emission order.",
    )