Expose certifications and per-country release dates

TMDb's release_dates/content_ratings blocks were already fetched via
append_to_response but discarded at normalization -- every downstream
layer (ingestion write, repository read, schema, service) was unbuilt.
Adds the full pipeline: NormalizedReleaseDate + get_or_create_certification,
a shared polymorphic sync/read (movie and series both use it), and
MovieDetailOut/SeriesDetailOut certification + release_dates fields.

Series content_ratings has no date of its own, so each rating is anchored
to the show's first_air_date with release_type="tv".

Co-Authored-By: Claude Sonnet 5 <[email protected]>

app/services/common.py

@@ -6,13 +6,16 @@ from app.core.ids import aurora_id
 from app.models.artwork import Artwork
 from app.models.credit import Credit
 from app.models.enums import ArtworkType
+from app.models.movie import ReleaseDate
 from app.models.video import Video
 from app.schemas.common import (
     ArtworkOut,
     CastCreditOut,
+    CertificationOut,
     CrewCreditOut,
     ImagesOut,
     PersonBriefOut,
+    ReleaseDateOut,
     VideoOut,
 )
 
@@ -70,6 +73,37 @@ def to_video_out(video: Video) -> VideoOut:
     )
 
 
+def to_release_date_out(release_date: ReleaseDate) -> ReleaseDateOut:
+    certification = None
+    if release_date.certification is not None:
+        certification = CertificationOut(
+            system=release_date.certification.system, rating=release_date.certification.rating
+        )
+    return ReleaseDateOut(
+        country_code=release_date.country_code,
+        release_date=release_date.release_date,
+        release_type=release_date.release_type,
+        certification=certification,
+        note=release_date.note,
+    )
+
+
+def pick_certification(release_dates: list[ReleaseDate], *, preferred_country: str = "US") -> str | None:
+    """The single rating a client wants when it isn't picking a country
+    itself -- TMDb's own site defaults to the US rating badge, so this
+    does too, falling back to the first country that has one at all."""
+
+    fallback: str | None = None
+    for rd in release_dates:
+        if rd.certification is None:
+            continue
+        if rd.country_code == preferred_country:
+            return rd.certification.rating
+        if fallback is None:
+            fallback = rd.certification.rating
+    return fallback
+
+
 def split_credits(
     credits_: list[Credit], profile_paths: dict | None = None
 ) -> tuple[list[CastCreditOut], list[CrewCreditOut]]:

app/services/ingestion/movie_ingestion.py

@@ -249,6 +249,9 @@ async def ingest_movie(
         artwork_list=normalized.artwork,
     )
     await _replace_movie_videos(session, movie.id, tmdb_provider.id, normalized.videos)
+    await polymorphic.sync_release_dates(
+        session, entity_type="movie", entity_id=movie.id, release_dates=normalized.release_dates
+    )
     await _link_external_ids(session, movie.id, tmdb_provider.id, normalized)
 
     await session.execute(

app/services/ingestion/series_ingestion.py

@@ -244,6 +244,9 @@ async def ingest_series(
         artwork_list=normalized.artwork,
     )
     await _replace_entity_videos(session, "series", series.id, tmdb_provider.id, normalized.videos)
+    await polymorphic.sync_release_dates(
+        session, entity_type="series", entity_id=series.id, release_dates=normalized.release_dates
+    )
 
     for stub in normalized.seasons:
         season = await tv_repository.get_or_create_season(session, series.id, stub.season_number)

app/services/metadata/normalizer.py

@@ -96,6 +96,95 @@ def company_logo_artwork(logo_path: str | None) -> NormalizedArtwork | None:
     )
 
 
+# TMDb's per-country rating body isn't returned alongside a release_dates
+# certification or a content_ratings rating -- only the country and the
+# rating string itself are. This maps the handful of markets Aurora can
+# name with confidence; everywhere else falls back to the country code
+# itself (see NormalizedReleaseDate.certification) rather than fabricating
+# a body name TMDb never told us.
+_CERTIFICATION_SYSTEMS = {
+    "US": "MPA",
+    "GB": "BBFC",
+    "DE": "FSK",
+    "FR": "CNC",
+    "JP": "Eirin",
+    "AU": "ACB",
+    "CA": "CHVRS",
+    "KR": "KMRB",
+    "BR": "ANCINE",
+    "ES": "ICAA",
+    "IT": "MiC",
+    "NZ": "OFLC",
+    "IE": "IFCO",
+    "IN": "CBFC",
+}
+
+# TMDb's release_dates[].type: 1=Premiere, 2=Theatrical (limited),
+# 3=Theatrical, 4=Digital, 5=Physical, 6=TV -- collapsed onto the five
+# release_type values ReleaseDate.release_type documents.
+_RELEASE_TYPE_MAP = {1: "premiere", 2: "theatrical", 3: "theatrical", 4: "digital", 5: "physical", 6: "tv"}
+
+
+@dataclass
+class NormalizedReleaseDate:
+    country_code: str
+    release_date: date
+    release_type: str | None
+    certification: tuple[str, str] | None = None  # (system, rating)
+    note: str | None = None
+
+
+def _movie_release_dates(raw: dict) -> list[NormalizedReleaseDate]:
+    out: list[NormalizedReleaseDate] = []
+    for country_block in (raw.get("release_dates") or {}).get("results", []):
+        country_code = country_block.get("iso_3166_1")
+        if not country_code:
+            continue
+        for entry in country_block.get("release_dates", []):
+            release_date = _parse_date((entry.get("release_date") or "")[:10] or None)
+            if release_date is None:
+                continue
+            rating = entry.get("certification")
+            certification = (
+                (_CERTIFICATION_SYSTEMS.get(country_code, country_code), rating) if rating else None
+            )
+            out.append(
+                NormalizedReleaseDate(
+                    country_code=country_code,
+                    release_date=release_date,
+                    release_type=_RELEASE_TYPE_MAP.get(entry.get("type")),
+                    certification=certification,
+                    note=entry.get("note") or None,
+                )
+            )
+    return out
+
+
+def _series_release_dates(raw: dict, first_air_date: date | None) -> list[NormalizedReleaseDate]:
+    # Unlike /movie's release_dates, TMDb's /tv content_ratings has no date
+    # at all -- just a country and a rating. ReleaseDate.release_date is
+    # required, so each rating is anchored to the show's own first_air_date
+    # (release_type="tv") rather than left dateless; a show with no
+    # first_air_date yet has nothing to anchor to and is skipped.
+    if first_air_date is None:
+        return []
+    out: list[NormalizedReleaseDate] = []
+    for entry in (raw.get("content_ratings") or {}).get("results", []):
+        country_code = entry.get("iso_3166_1")
+        rating = entry.get("rating")
+        if not country_code or not rating:
+            continue
+        out.append(
+            NormalizedReleaseDate(
+                country_code=country_code,
+                release_date=first_air_date,
+                release_type="tv",
+                certification=(_CERTIFICATION_SYSTEMS.get(country_code, country_code), rating),
+            )
+        )
+    return out
+
+
 @dataclass
 class NormalizedVideo:
     video_type: str
@@ -136,6 +225,7 @@ class NormalizedMovie:
     external_ids: dict[str, str] = field(default_factory=dict)
     collection: tuple[str, str] | None = None  # (external_id, name)
     recommendation_external_ids: list[str] = field(default_factory=list)
+    release_dates: list[NormalizedReleaseDate] = field(default_factory=list)
 
 
 @dataclass
@@ -338,6 +428,7 @@ def normalize_movie(raw: dict) -> NormalizedMovie:
         external_ids=external_ids,
         collection=(str(collection["id"]), collection["name"]) if collection else None,
         recommendation_external_ids=[str(m["id"]) for m in recommendations],
+        release_dates=_movie_release_dates(raw),
     )
 
 
@@ -486,6 +577,7 @@ class NormalizedSeries:
     videos: list[NormalizedVideo] = field(default_factory=list)
     external_ids: dict[str, str] = field(default_factory=dict)
     seasons: list[NormalizedSeasonStub] = field(default_factory=list)
+    release_dates: list[NormalizedReleaseDate] = field(default_factory=list)
 
 
 def normalize_series(raw: dict) -> NormalizedSeries:
@@ -637,6 +729,8 @@ def normalize_series(raw: dict) -> NormalizedSeries:
         if s.get("season_number") is not None
     ]
 
+    first_air_date = _parse_date(raw.get("first_air_date"))
+
     return NormalizedSeries(
         external_id=str(raw["id"]),
         title=raw.get("name") or raw.get("original_name") or "",
@@ -645,7 +739,7 @@ def normalize_series(raw: dict) -> NormalizedSeries:
         tagline=raw.get("tagline") or None,
         status=_SERIES_STATUS_MAP.get(raw.get("status", "Returning Series"), "returning_series"),
         original_language=raw.get("original_language"),
-        first_air_date=_parse_date(raw.get("first_air_date")),
+        first_air_date=first_air_date,
         last_air_date=_parse_date(raw.get("last_air_date")),
         number_of_seasons=raw.get("number_of_seasons"),
         number_of_episodes=raw.get("number_of_episodes"),
@@ -664,6 +758,7 @@ def normalize_series(raw: dict) -> NormalizedSeries:
         videos=normalized_videos,
         external_ids=external_ids,
         seasons=seasons,
+        release_dates=_series_release_dates(raw, first_air_date),
     )
 
 

app/services/movie_service.py

@@ -20,7 +20,14 @@ from app.schemas.movie import (
     MovieSummaryOut,
     MovieVideosOut,
 )
-from app.services.common import primary_artwork_path, split_credits, to_images_out, to_video_out
+from app.services.common import (
+    pick_certification,
+    primary_artwork_path,
+    split_credits,
+    to_images_out,
+    to_release_date_out,
+    to_video_out,
+)
 
 
 class MovieNotFoundError(Exception):
@@ -50,6 +57,7 @@ async def get_movie_detail(session: AsyncSession, movie_aurora_id: str) -> Movie
     credits_ = await polymorphic.get_credits(session, "movie", movie_id)
     artwork = await polymorphic.get_artwork(session, "movie", movie_id)
     videos = await polymorphic.get_videos(session, "movie", movie_id)
+    release_dates = await polymorphic.get_release_dates(session, "movie", movie_id)
     external_ids = await polymorphic.get_external_ids(session, "movie", movie_id)
 
     cast, crew = split_credits(credits_)
@@ -93,6 +101,7 @@ async def get_movie_detail(session: AsyncSession, movie_aurora_id: str) -> Movie
         vote_average=movie.vote_average,
         vote_count=movie.vote_count,
         adult=movie.adult,
+        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],
         cast=cast,
@@ -101,6 +110,7 @@ async def get_movie_detail(session: AsyncSession, movie_aurora_id: str) -> Movie
         collection=collection_out,
         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],
         external_ids=external_ids,
         created_at=movie.created_at,
         updated_at=movie.updated_at,

app/services/tv_service.py

@@ -25,7 +25,14 @@ from app.schemas.tv import (
     SeriesSummaryOut,
     SeriesVideosOut,
 )
-from app.services.common import primary_artwork_path, split_credits, to_images_out, to_video_out
+from app.services.common import (
+    pick_certification,
+    primary_artwork_path,
+    split_credits,
+    to_images_out,
+    to_release_date_out,
+    to_video_out,
+)
 
 
 class SeriesNotFoundError(Exception):
@@ -99,6 +106,7 @@ async def get_series_detail(session: AsyncSession, series_aurora_id: str) -> Ser
     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)
     external_ids = await polymorphic.get_external_ids(session, "series", series_id)
 
     cast, crew, creators = _split_series_credits(credits_)
@@ -122,6 +130,7 @@ async def get_series_detail(session: AsyncSession, series_aurora_id: str) -> Ser
         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],
         creators=creators,
@@ -132,6 +141,7 @@ async def get_series_detail(session: AsyncSession, series_aurora_id: str) -> Ser
         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],
         external_ids=external_ids,
         created_at=series.created_at,
         updated_at=series.updated_at,