Add watch providers (where to stream/rent/buy)

New TMDb integration end to end: append_to_response "watch/providers",
normalizer parsing grouped by country/monetization type, a WatchProvider
catalog entry (external-id keyed, same get_or_create pattern as Company/
Collection/Person) + polymorphic WatchProviderOffering table (new
migration 0002), ingestion write (including provider logos via the
existing Artwork table), and API exposure -- embedded on movie/series
detail plus a dedicated /watch-providers sub-route, shaped to mirror
TMDb's own response for easy porting.

Note: this data comes from JustWatch via TMDb and carries its own
attribution requirement separate from TMDb's general one -- flagged in
docs/api.md, must be satisfied before showing this in the frontend.

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

app/services/metadata/normalizer.py

@@ -202,6 +202,52 @@ def _series_release_dates(raw: dict, first_air_date: date | None) -> list[Normal
     return out
 
 
+_MONETIZATION_TYPES = ("flatrate", "rent", "buy", "ads", "free")
+
+
+@dataclass
+class NormalizedWatchProviderRef:
+    external_id: str
+    name: str
+    logo_path: str | None
+
+
+@dataclass
+class NormalizedWatchProviderOffering:
+    country_code: str
+    monetization_type: str  # one of _MONETIZATION_TYPES
+    provider: NormalizedWatchProviderRef
+    display_priority: int | None = None
+    link: str | None = None
+
+
+def _watch_providers(raw: dict) -> list[NormalizedWatchProviderOffering]:
+    # TMDb nests this appended resource under the literal key
+    # "watch/providers" (slash included), grouped by country then by
+    # monetization type -- this data comes from JustWatch via TMDb and
+    # carries its own separate attribution requirement, see docs/api.md.
+    out: list[NormalizedWatchProviderOffering] = []
+    results = (raw.get("watch/providers") or {}).get("results") or {}
+    for country_code, country_block in results.items():
+        link = country_block.get("link")
+        for monetization_type in _MONETIZATION_TYPES:
+            for entry in country_block.get(monetization_type, []):
+                out.append(
+                    NormalizedWatchProviderOffering(
+                        country_code=country_code,
+                        monetization_type=monetization_type,
+                        provider=NormalizedWatchProviderRef(
+                            external_id=str(entry["provider_id"]),
+                            name=entry["provider_name"],
+                            logo_path=entry.get("logo_path"),
+                        ),
+                        display_priority=entry.get("display_priority"),
+                        link=link,
+                    )
+                )
+    return out
+
+
 @dataclass
 class NormalizedVideo:
     video_type: str
@@ -243,6 +289,7 @@ class NormalizedMovie:
     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)
+    watch_providers: list[NormalizedWatchProviderOffering] = field(default_factory=list)
 
 
 @dataclass
@@ -446,6 +493,7 @@ def normalize_movie(raw: dict) -> NormalizedMovie:
         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),
+        watch_providers=_watch_providers(raw),
     )
 
 
@@ -595,6 +643,7 @@ class NormalizedSeries:
     external_ids: dict[str, str] = field(default_factory=dict)
     seasons: list[NormalizedSeasonStub] = field(default_factory=list)
     release_dates: list[NormalizedReleaseDate] = field(default_factory=list)
+    watch_providers: list[NormalizedWatchProviderOffering] = field(default_factory=list)
 
 
 def normalize_series(raw: dict) -> NormalizedSeries:
@@ -776,6 +825,7 @@ def normalize_series(raw: dict) -> NormalizedSeries:
         external_ids=external_ids,
         seasons=seasons,
         release_dates=_series_release_dates(raw, first_air_date),
+        watch_providers=_watch_providers(raw),
     )