Aurora-Core/app/services/tv_service.py

"""Assembles Series/Season/Episode API responses from repository data."""

from __future__ import annotations

import uuid

from sqlalchemy.ext.asyncio import AsyncSession

from app.core.ids import aurora_id, parse_aurora_id
from app.models.credit import Credit
from app.models.enums import ArtworkType, CompanyType, SeriesStatus
from app.models.tv import Series
from app.repositories import polymorphic, trending_repository, tv_repository
from app.schemas.common import CastCreditOut, CompanyBriefOut, CrewCreditOut, GenreOut, KeywordOut
from app.schemas.tv import (
    EpisodeBriefOut,
    EpisodeDetailOut,
    SeasonBriefOut,
    SeasonDetailOut,
    SeriesCreditsOut,
    SeriesDetailOut,
    SeriesImagesOut,
    SeriesListOut,
    SeriesSeasonsOut,
    SeriesSummaryOut,
    SeriesVideosOut,
    SeriesWatchProvidersOut,
)
from app.services.common import (
    build_watch_providers_out,
    pick_certification,
    primary_artwork_path,
    split_credits,
    to_alternate_title_out,
    to_images_out,
    to_release_date_out,
    to_video_out,
)


class SeriesNotFoundError(Exception):
    pass


class SeasonNotFoundError(Exception):
    pass


class EpisodeNotFoundError(Exception):
    pass


class InvalidSeriesFilterError(Exception):
    pass


def _resolve_id(aid: str, expected_type: str, error_cls: type[Exception]) -> uuid.UUID:
    try:
        return uuid.UUID(parse_aurora_id(aid, expected_type=expected_type))
    except ValueError as exc:
        raise error_cls(str(exc)) from exc


async def _season_brief(session: AsyncSession, season) -> SeasonBriefOut:
    posters = await polymorphic.get_artwork(session, "season", season.id, ArtworkType.POSTER)
    return SeasonBriefOut(
        id=aurora_id("season", str(season.id)),
        season_number=season.season_number,
        title=season.title,
        episode_count=season.episode_count,
        air_date=season.air_date,
        poster_path=primary_artwork_path(posters, ArtworkType.POSTER),
    )


async def _company_brief(session: AsyncSession, company) -> CompanyBriefOut:
    logos = await polymorphic.get_artwork(session, "company", company.id, ArtworkType.LOGO)
    return CompanyBriefOut(
        id=aurora_id("company", str(company.id)),
        name=company.name,
        company_type=company.company_type.value,
        logo_path=primary_artwork_path(logos, ArtworkType.LOGO),
    )


def _split_series_credits(
    credits_: list[Credit],
) -> tuple[list[CastCreditOut], list[CrewCreditOut], list[CrewCreditOut]]:
    # Series-level "Creator" credits are their own bucket (section 7),
    # neither cast nor regular crew.
    cast, crew = split_credits([c for c in credits_ if c.department != "Creator"])
    _, creators = split_credits([c for c in credits_ if c.department == "Creator"])
    return cast, crew, creators


async def get_series_detail(session: AsyncSession, series_aurora_id: str) -> SeriesDetailOut:
    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
    series = await tv_repository.get_series_by_id(session, series_id)
    if series is None:
        raise SeriesNotFoundError(series_aurora_id)

    genres = await tv_repository.get_series_genres(session, series_id)
    keywords = await tv_repository.get_series_keywords(session, series_id)
    alternate_titles = await tv_repository.get_series_alternate_titles(session, series_id)
    networks = await tv_repository.get_series_companies(session, series_id, CompanyType.NETWORK)
    companies = await tv_repository.get_series_companies(
        session, series_id, CompanyType.PRODUCTION_COMPANY
    )
    seasons = await tv_repository.get_seasons_for_series(session, series_id)
    credits_ = await polymorphic.get_credits(session, "series", series_id)
    artwork = await polymorphic.get_artwork(session, "series", series_id)
    videos = await polymorphic.get_videos(session, "series", series_id)
    release_dates = await polymorphic.get_release_dates(session, "series", series_id)
    watch_provider_rows = await polymorphic.get_watch_providers(session, "series", series_id)
    external_ids = await polymorphic.get_external_ids(session, "series", series_id)

    cast, crew, creators = _split_series_credits(credits_)

    season_briefs = [await _season_brief(session, s) for s in seasons]
    network_briefs = [await _company_brief(session, c) for c, _role in networks]
    company_briefs = [await _company_brief(session, c) for c, _role in companies]

    return SeriesDetailOut(
        id=aurora_id("series", str(series.id)),
        title=series.title,
        original_title=series.original_title,
        overview=series.overview,
        tagline=series.tagline,
        status=series.status.value,
        original_language=series.original_language_code,
        first_air_date=series.first_air_date,
        last_air_date=series.last_air_date,
        number_of_seasons=series.number_of_seasons,
        number_of_episodes=series.number_of_episodes,
        popularity=series.popularity,
        vote_average=series.vote_average,
        vote_count=series.vote_count,
        certification=pick_certification(release_dates),
        genres=[GenreOut(id=aurora_id("genre", str(g.id)), name=g.name) for g in genres],
        keywords=[KeywordOut(id=aurora_id("keyword", str(k.id)), name=k.name) for k in keywords],
        alternate_titles=[to_alternate_title_out(t) for t in alternate_titles],
        creators=creators,
        cast=cast,
        crew=crew,
        networks=network_briefs,
        companies=company_briefs,
        seasons=season_briefs,
        images=to_images_out(artwork),
        videos=[to_video_out(v) for v in videos],
        release_dates=[to_release_date_out(rd) for rd in release_dates],
        watch_providers=await build_watch_providers_out(session, watch_provider_rows),
        external_ids=external_ids,
        created_at=series.created_at,
        updated_at=series.updated_at,
    )


async def get_series_seasons(session: AsyncSession, series_aurora_id: str) -> SeriesSeasonsOut:
    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
    series = await tv_repository.get_series_by_id(session, series_id)
    if series is None:
        raise SeriesNotFoundError(series_aurora_id)
    seasons = await tv_repository.get_seasons_for_series(session, series_id)
    briefs = [await _season_brief(session, s) for s in seasons]
    return SeriesSeasonsOut(id=aurora_id("series", str(series.id)), seasons=briefs)


async def get_series_credits(session: AsyncSession, series_aurora_id: str) -> SeriesCreditsOut:
    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
    series = await tv_repository.get_series_by_id(session, series_id)
    if series is None:
        raise SeriesNotFoundError(series_aurora_id)
    credits_ = await polymorphic.get_credits(session, "series", series_id)
    cast, crew, creators = _split_series_credits(credits_)
    return SeriesCreditsOut(
        id=aurora_id("series", str(series.id)), cast=cast, crew=crew, creators=creators
    )


async def get_series_images(session: AsyncSession, series_aurora_id: str) -> SeriesImagesOut:
    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
    series = await tv_repository.get_series_by_id(session, series_id)
    if series is None:
        raise SeriesNotFoundError(series_aurora_id)
    artwork = await polymorphic.get_artwork(session, "series", series_id)
    return SeriesImagesOut(id=aurora_id("series", str(series.id)), images=to_images_out(artwork))


async def get_series_videos(session: AsyncSession, series_aurora_id: str) -> SeriesVideosOut:
    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
    series = await tv_repository.get_series_by_id(session, series_id)
    if series is None:
        raise SeriesNotFoundError(series_aurora_id)
    videos = await polymorphic.get_videos(session, "series", series_id)
    return SeriesVideosOut(
        id=aurora_id("series", str(series.id)), videos=[to_video_out(v) for v in videos]
    )


async def get_series_watch_providers(
    session: AsyncSession, series_aurora_id: str
) -> SeriesWatchProvidersOut:
    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
    series = await tv_repository.get_series_by_id(session, series_id)
    if series is None:
        raise SeriesNotFoundError(series_aurora_id)
    rows = await polymorphic.get_watch_providers(session, "series", series_id)
    return SeriesWatchProvidersOut(
        id=aurora_id("series", str(series.id)), results=await build_watch_providers_out(session, rows)
    )


async def get_season_detail(session: AsyncSession, season_aurora_id: str) -> SeasonDetailOut:
    season_id = _resolve_id(season_aurora_id, "season", SeasonNotFoundError)
    season = await tv_repository.get_season_by_id(session, season_id)
    if season is None:
        raise SeasonNotFoundError(season_aurora_id)

    episodes = await tv_repository.get_episodes_for_season(session, season_id)
    artwork = await polymorphic.get_artwork(session, "season", season_id)
    external_ids = await polymorphic.get_external_ids(session, "season", season_id)

    episode_briefs: list[EpisodeBriefOut] = []
    for ep in episodes:
        stills = await polymorphic.get_artwork(session, "episode", ep.id, ArtworkType.STILL)
        episode_briefs.append(
            EpisodeBriefOut(
                id=aurora_id("episode", str(ep.id)),
                episode_number=ep.episode_number,
                title=ep.title,
                air_date=ep.air_date,
                still_path=primary_artwork_path(stills, ArtworkType.STILL),
            )
        )

    return SeasonDetailOut(
        id=aurora_id("season", str(season.id)),
        series_id=aurora_id("series", str(season.series_id)),
        season_number=season.season_number,
        title=season.title,
        overview=season.overview,
        air_date=season.air_date,
        episode_count=season.episode_count,
        episodes=episode_briefs,
        images=to_images_out(artwork),
        external_ids=external_ids,
        created_at=season.created_at,
        updated_at=season.updated_at,
    )


async def get_episode_detail(session: AsyncSession, episode_aurora_id: str) -> EpisodeDetailOut:
    episode_id = _resolve_id(episode_aurora_id, "episode", EpisodeNotFoundError)
    episode = await tv_repository.get_episode_by_id(session, episode_id)
    if episode is None:
        raise EpisodeNotFoundError(episode_aurora_id)

    credits_ = await polymorphic.get_credits(session, "episode", episode_id)
    artwork = await polymorphic.get_artwork(session, "episode", episode_id)
    external_ids = await polymorphic.get_external_ids(session, "episode", episode_id)

    main_cast, crew = split_credits([c for c in credits_ if not c.is_guest])
    guest_cast, _ = split_credits([c for c in credits_ if c.is_guest])

    return EpisodeDetailOut(
        id=aurora_id("episode", str(episode.id)),
        series_id=aurora_id("series", str(episode.series_id)),
        season_id=aurora_id("season", str(episode.season_id)),
        season_number=episode.season_number,
        episode_number=episode.episode_number,
        title=episode.title,
        overview=episode.overview,
        air_date=episode.air_date,
        runtime=episode.runtime_minutes,
        cast=main_cast,
        guest_stars=guest_cast,
        crew=crew,
        images=to_images_out(artwork),
        external_ids=external_ids,
        created_at=episode.created_at,
        updated_at=episode.updated_at,
    )


async def _series_summary_from_row(session: AsyncSession, series: Series) -> SeriesSummaryOut:
    posters = await polymorphic.get_artwork(session, "series", series.id, ArtworkType.POSTER)
    return SeriesSummaryOut(
        id=aurora_id("series", str(series.id)),
        title=series.title,
        original_title=series.original_title,
        overview=series.overview,
        first_air_date=series.first_air_date,
        poster_path=primary_artwork_path(posters, ArtworkType.POSTER),
        popularity=series.popularity,
        vote_average=series.vote_average,
    )


async def build_series_summary(
    session: AsyncSession, series_id: uuid.UUID
) -> SeriesSummaryOut | None:
    series = await tv_repository.get_series_by_id(session, series_id)
    if series is None:
        return None
    return await _series_summary_from_row(session, series)


async def build_series_summaries(
    session: AsyncSession, series_ids: list[uuid.UUID]
) -> list[SeriesSummaryOut]:
    out: list[SeriesSummaryOut] = []
    for series_id in series_ids:
        summary = await build_series_summary(session, series_id)
        if summary is not None:
            out.append(summary)
    return out


_TRENDING_WINDOWS = ("day", "week")


async def list_trending(
    session: AsyncSession, *, time_window: str, page: int, page_size: int
) -> SeriesListOut:
    if time_window not in _TRENDING_WINDOWS:
        raise InvalidSeriesFilterError(f"unknown time_window: {time_window!r}")

    all_ids = await trending_repository.get_trending_entity_ids(
        session, entity_type="series", time_window=time_window
    )
    total = len(all_ids)
    start = (page - 1) * page_size
    page_ids = all_ids[start : start + page_size]
    series_rows = await tv_repository.get_series_by_ids(session, page_ids)
    results = [await _series_summary_from_row(session, s) for s in series_rows]
    total_pages = (total + page_size - 1) // page_size if total else 0

    return SeriesListOut(
        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
    )


async def list_series(
    session: AsyncSession,
    *,
    genre_aurora_id: str | None,
    keyword_aurora_id: str | None,
    year: int | None,
    status: str | None,
    sort_by: str,
    sort_dir: str,
    page: int,
    page_size: int,
) -> SeriesListOut:
    genre_id: uuid.UUID | None = None
    if genre_aurora_id is not None:
        try:
            genre_id = uuid.UUID(parse_aurora_id(genre_aurora_id, expected_type="genre"))
        except ValueError as exc:
            raise InvalidSeriesFilterError(f"invalid genre id: {genre_aurora_id!r}") from exc

    keyword_id: uuid.UUID | None = None
    if keyword_aurora_id is not None:
        try:
            keyword_id = uuid.UUID(parse_aurora_id(keyword_aurora_id, expected_type="keyword"))
        except ValueError as exc:
            raise InvalidSeriesFilterError(f"invalid keyword id: {keyword_aurora_id!r}") from exc

    status_enum: SeriesStatus | None = None
    if status is not None:
        try:
            status_enum = SeriesStatus(status)
        except ValueError as exc:
            raise InvalidSeriesFilterError(f"unknown series status: {status!r}") from exc

    series_rows, total = await tv_repository.list_series(
        session,
        genre_id=genre_id,
        keyword_id=keyword_id,
        year=year,
        status=status_enum,
        sort_by=sort_by,
        sort_dir=sort_dir,
        limit=page_size,
        offset=(page - 1) * page_size,
    )
    results = [await _series_summary_from_row(session, s) for s in series_rows]
    total_pages = (total + page_size - 1) // page_size if total else 0

    return SeriesListOut(
        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
    )