Add GET /companies browse/discover endpoint

Completes the browse/discover set across all four entity types.
Companies have no popularity or date field, so unlike movies/series/
people there's no sort_by choice -- always alphabetical by name.
Filters are company_type (validated against the enum) and country
(a plain ISO 3166-1 code comparison, nothing to validate).

build_company_summary refactored to share row-to-summary logic with
the new list path, same pattern used for movies/series/people.

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

app/services/company_service.py

@@ -7,10 +7,11 @@ import uuid
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.ids import aurora_id, parse_aurora_id
-from app.models.enums import ArtworkType
+from app.models.company import Company
+from app.models.enums import ArtworkType, CompanyType
 from app.repositories import company_repository, polymorphic
 from app.schemas.common import CompanyBriefOut
-from app.schemas.company import CompanyDetailOut
+from app.schemas.company import CompanyDetailOut, CompanyListOut
 from app.services.common import primary_artwork_path
 from app.services.movie_service import build_movie_summaries
 from app.services.tv_service import build_series_summaries
@@ -20,6 +21,10 @@ class CompanyNotFoundError(Exception):
     pass
 
 
+class InvalidCompanyFilterError(Exception):
+    pass
+
+
 def _resolve_company_id(aid: str) -> uuid.UUID:
     try:
         return uuid.UUID(parse_aurora_id(aid, expected_type="company"))
@@ -60,13 +65,8 @@ async def get_company_detail(session: AsyncSession, company_aurora_id: str) -> C
     )
 
 
-async def build_company_summary(
-    session: AsyncSession, company_id: uuid.UUID
-) -> CompanyBriefOut | None:
-    company = await company_repository.get_company_by_id(session, company_id)
-    if company is None:
-        return None
-    logos = await polymorphic.get_artwork(session, "company", company_id, ArtworkType.LOGO)
+async def _company_summary_from_row(session: AsyncSession, company: 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,
@@ -75,6 +75,15 @@ async def build_company_summary(
     )
 
 
+async def build_company_summary(
+    session: AsyncSession, company_id: uuid.UUID
+) -> CompanyBriefOut | None:
+    company = await company_repository.get_company_by_id(session, company_id)
+    if company is None:
+        return None
+    return await _company_summary_from_row(session, company)
+
+
 async def build_company_summaries(
     session: AsyncSession, company_ids: list[uuid.UUID]
 ) -> list[CompanyBriefOut]:
@@ -84,3 +93,33 @@ async def build_company_summaries(
         if summary is not None:
             out.append(summary)
     return out
+
+
+async def list_companies(
+    session: AsyncSession,
+    *,
+    company_type: str | None,
+    country: str | None,
+    page: int,
+    page_size: int,
+) -> CompanyListOut:
+    company_type_enum: CompanyType | None = None
+    if company_type is not None:
+        try:
+            company_type_enum = CompanyType(company_type)
+        except ValueError as exc:
+            raise InvalidCompanyFilterError(f"unknown company type: {company_type!r}") from exc
+
+    companies, total = await company_repository.list_companies(
+        session,
+        company_type=company_type_enum,
+        country_code=country,
+        limit=page_size,
+        offset=(page - 1) * page_size,
+    )
+    results = [await _company_summary_from_row(session, c) for c in companies]
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return CompanyListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )