feat(opportunities): add verified opportunities API

alembic/versions/20260803_0002_create_opportunities.py

@@ -0,0 +1,343 @@
+"""Create sources and opportunities tables.
+
+Revision ID: 20260803_0002
+Revises: 20260803_0001
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "20260803_0002"
+down_revision: str | None = "20260803_0001"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "sources",
+        sa.Column(
+            "id",
+            postgresql.UUID(as_uuid=True),
+            nullable=False,
+        ),
+        sa.Column(
+            "name",
+            sa.String(length=180),
+            nullable=False,
+        ),
+        sa.Column(
+            "slug",
+            sa.String(length=180),
+            nullable=False,
+        ),
+        sa.Column(
+            "organization_type",
+            sa.String(length=50),
+            server_default="organization",
+            nullable=False,
+        ),
+        sa.Column(
+            "base_url",
+            sa.Text(),
+            nullable=False,
+        ),
+        sa.Column(
+            "opportunities_url",
+            sa.Text(),
+            nullable=True,
+        ),
+        sa.Column(
+            "feed_url",
+            sa.Text(),
+            nullable=True,
+        ),
+        sa.Column(
+            "logo_url",
+            sa.Text(),
+            nullable=True,
+        ),
+        sa.Column(
+            "country_code",
+            sa.String(length=2),
+            nullable=True,
+        ),
+        sa.Column(
+            "source_tier",
+            sa.String(length=1),
+            server_default="B",
+            nullable=False,
+        ),
+        sa.Column(
+            "is_official",
+            sa.Boolean(),
+            server_default=sa.true(),
+            nullable=False,
+        ),
+        sa.Column(
+            "is_active",
+            sa.Boolean(),
+            server_default=sa.true(),
+            nullable=False,
+        ),
+        sa.Column(
+            "last_checked_at",
+            sa.DateTime(timezone=True),
+            nullable=True,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "name",
+            name="uq_sources_name",
+        ),
+        sa.UniqueConstraint(
+            "slug",
+            name="uq_sources_slug",
+        ),
+    )
+
+    op.create_index(
+        "ix_sources_slug",
+        "sources",
+        ["slug"],
+        unique=False,
+    )
+
+    op.create_index(
+        "ix_sources_active_official",
+        "sources",
+        ["is_active", "is_official"],
+        unique=False,
+    )
+
+    op.create_table(
+        "opportunities",
+        sa.Column(
+            "id",
+            postgresql.UUID(as_uuid=True),
+            nullable=False,
+        ),
+        sa.Column(
+            "source_id",
+            postgresql.UUID(as_uuid=True),
+            nullable=False,
+        ),
+        sa.Column(
+            "title",
+            sa.String(length=250),
+            nullable=False,
+        ),
+        sa.Column(
+            "slug",
+            sa.String(length=280),
+            nullable=False,
+        ),
+        sa.Column(
+            "summary",
+            sa.String(length=500),
+            nullable=False,
+        ),
+        sa.Column(
+            "description",
+            sa.Text(),
+            nullable=True,
+        ),
+        sa.Column(
+            "category",
+            sa.String(length=50),
+            nullable=False,
+        ),
+        sa.Column(
+            "organization_name",
+            sa.String(length=180),
+            nullable=False,
+        ),
+        sa.Column(
+            "country_code",
+            sa.String(length=2),
+            nullable=True,
+        ),
+        sa.Column(
+            "location",
+            sa.String(length=180),
+            nullable=True,
+        ),
+        sa.Column(
+            "target_countries",
+            postgresql.JSONB(),
+            server_default=sa.text("'[]'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column(
+            "study_levels",
+            postgresql.JSONB(),
+            server_default=sa.text("'[]'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column(
+            "eligibility",
+            postgresql.JSONB(),
+            server_default=sa.text("'{}'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column(
+            "language",
+            sa.String(length=10),
+            nullable=True,
+        ),
+        sa.Column(
+            "publication_date",
+            sa.Date(),
+            nullable=True,
+        ),
+        sa.Column(
+            "deadline",
+            sa.Date(),
+            nullable=True,
+        ),
+        sa.Column(
+            "official_url",
+            sa.Text(),
+            nullable=False,
+        ),
+        sa.Column(
+            "application_url",
+            sa.Text(),
+            nullable=True,
+        ),
+        sa.Column(
+            "image_url",
+            sa.Text(),
+            nullable=True,
+        ),
+        sa.Column(
+            "status",
+            sa.String(length=30),
+            server_default="draft",
+            nullable=False,
+        ),
+        sa.Column(
+            "is_featured",
+            sa.Boolean(),
+            server_default=sa.false(),
+            nullable=False,
+        ),
+        sa.Column(
+            "is_source_verified",
+            sa.Boolean(),
+            server_default=sa.false(),
+            nullable=False,
+        ),
+        sa.Column(
+            "verified_at",
+            sa.DateTime(timezone=True),
+            nullable=True,
+        ),
+        sa.Column(
+            "collected_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["source_id"],
+            ["sources.id"],
+            name="fk_opportunities_source_id",
+            ondelete="RESTRICT",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "slug",
+            name="uq_opportunities_slug",
+        ),
+        sa.UniqueConstraint(
+            "official_url",
+            name="uq_opportunities_official_url",
+        ),
+    )
+
+    op.create_index(
+        "ix_opportunities_slug",
+        "opportunities",
+        ["slug"],
+        unique=False,
+    )
+
+    op.create_index(
+        "ix_opportunities_category_status",
+        "opportunities",
+        ["category", "status"],
+        unique=False,
+    )
+
+    op.create_index(
+        "ix_opportunities_deadline",
+        "opportunities",
+        ["deadline"],
+        unique=False,
+    )
+
+    op.create_index(
+        "ix_opportunities_featured",
+        "opportunities",
+        ["is_featured"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_opportunities_featured",
+        table_name="opportunities",
+    )
+    op.drop_index(
+        "ix_opportunities_deadline",
+        table_name="opportunities",
+    )
+    op.drop_index(
+        "ix_opportunities_category_status",
+        table_name="opportunities",
+    )
+    op.drop_index(
+        "ix_opportunities_slug",
+        table_name="opportunities",
+    )
+    op.drop_table("opportunities")
+
+    op.drop_index(
+        "ix_sources_active_official",
+        table_name="sources",
+    )
+    op.drop_index(
+        "ix_sources_slug",
+        table_name="sources",
+    )
+    op.drop_table("sources")

app/api/v1/endpoints/opportunities.py

@@ -0,0 +1,110 @@
+from typing import Annotated
+
+from fastapi import (
+    APIRouter,
+    Depends,
+    HTTPException,
+    Query,
+    status,
+)
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.session import get_database_session
+from app.schemas.opportunity import (
+    OpportunityCategory,
+    OpportunityCategoryResponse,
+    OpportunityDetail,
+    OpportunityListResponse,
+    OpportunitySort,
+)
+from app.services.opportunity import (
+    OpportunityNotFoundError,
+    OpportunityService,
+)
+
+
+router = APIRouter()
+
+
+@router.get(
+    "",
+    response_model=OpportunityListResponse,
+    summary="Lister les opportunités vérifiées",
+)
+async def list_opportunities(
+    session: Annotated[
+        AsyncSession,
+        Depends(get_database_session),
+    ],
+    page: Annotated[int, Query(ge=1)] = 1,
+    page_size: Annotated[
+        int,
+        Query(ge=1, le=100),
+    ] = 12,
+    search: Annotated[
+        str | None,
+        Query(min_length=2, max_length=100),
+    ] = None,
+    category: OpportunityCategory | None = None,
+    country: Annotated[
+        str | None,
+        Query(min_length=2, max_length=2),
+    ] = None,
+    featured: bool | None = None,
+    sort: OpportunitySort = OpportunitySort.RECENT,
+) -> OpportunityListResponse:
+    service = OpportunityService(session)
+
+    return await service.list_opportunities(
+        page=page,
+        page_size=page_size,
+        search=search,
+        category=category,
+        country=country,
+        featured=featured,
+        sort=sort,
+    )
+
+
+@router.get(
+    "/categories",
+    response_model=list[OpportunityCategoryResponse],
+    summary="Lister les catégories d’opportunités",
+)
+async def list_opportunity_categories(
+    session: Annotated[
+        AsyncSession,
+        Depends(get_database_session),
+    ],
+) -> list[OpportunityCategoryResponse]:
+    service = OpportunityService(session)
+    return service.list_categories()
+
+
+@router.get(
+    "/{slug}",
+    response_model=OpportunityDetail,
+    summary="Consulter une opportunité vérifiée",
+)
+async def get_opportunity(
+    slug: str,
+    session: Annotated[
+        AsyncSession,
+        Depends(get_database_session),
+    ],
+) -> OpportunityDetail:
+    service = OpportunityService(session)
+
+    try:
+        opportunity = await service.get_by_slug(slug)
+
+    except OpportunityNotFoundError as error:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=(
+                "Cette opportunité est introuvable, "
+                "expirée ou non publiée."
+            ),
+        ) from error
+
+    return OpportunityDetail.model_validate(opportunity)

app/api/v1/router.py

@@ -1,11 +1,16 @@
 from fastapi import APIRouter
 
-from app.api.v1.endpoints import health
+from app.api.v1.endpoints import health, opportunities
+
 
 api_router = APIRouter()
 
 api_router.include_router(
     health.router,
-    prefix="/health",
-    tags=["Health"],
+)
+
+api_router.include_router(
+    opportunities.router,
+    prefix="/opportunities",
+    tags=["Opportunities"],
 )

app/models/__init__.py

@@ -1,3 +1,9 @@
+from app.models.opportunity import Opportunity
+from app.models.source import Source
 from app.models.user import User
 
-__all__ = ["User"]
+__all__ = [
+    "Opportunity",
+    "Source",
+    "User",
+]

app/models/opportunity.py

@@ -0,0 +1,198 @@
+import uuid
+from datetime import date, datetime
+
+from sqlalchemy import (
+    Boolean,
+    Date,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    func,
+    text,
+)
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.db.base import Base
+
+
+class Opportunity(Base):
+    __tablename__ = "opportunities"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4,
+    )
+
+    source_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey(
+            "sources.id",
+            ondelete="RESTRICT",
+        ),
+        nullable=False,
+    )
+
+    title: Mapped[str] = mapped_column(
+        String(250),
+        nullable=False,
+    )
+
+    slug: Mapped[str] = mapped_column(
+        String(280),
+        nullable=False,
+        unique=True,
+    )
+
+    summary: Mapped[str] = mapped_column(
+        String(500),
+        nullable=False,
+    )
+
+    description: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=True,
+    )
+
+    category: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+    )
+
+    organization_name: Mapped[str] = mapped_column(
+        String(180),
+        nullable=False,
+    )
+
+    country_code: Mapped[str | None] = mapped_column(
+        String(2),
+        nullable=True,
+    )
+
+    location: Mapped[str | None] = mapped_column(
+        String(180),
+        nullable=True,
+    )
+
+    target_countries: Mapped[list[str]] = mapped_column(
+        JSONB,
+        nullable=False,
+        default=list,
+        server_default=text("'[]'::jsonb"),
+    )
+
+    study_levels: Mapped[list[str]] = mapped_column(
+        JSONB,
+        nullable=False,
+        default=list,
+        server_default=text("'[]'::jsonb"),
+    )
+
+    eligibility: Mapped[dict] = mapped_column(
+        JSONB,
+        nullable=False,
+        default=dict,
+        server_default=text("'{}'::jsonb"),
+    )
+
+    language: Mapped[str | None] = mapped_column(
+        String(10),
+        nullable=True,
+    )
+
+    publication_date: Mapped[date | None] = mapped_column(
+        Date,
+        nullable=True,
+    )
+
+    deadline: Mapped[date | None] = mapped_column(
+        Date,
+        nullable=True,
+    )
+
+    official_url: Mapped[str] = mapped_column(
+        Text,
+        nullable=False,
+        unique=True,
+    )
+
+    application_url: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=True,
+    )
+
+    image_url: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=True,
+    )
+
+    status: Mapped[str] = mapped_column(
+        String(30),
+        nullable=False,
+        default="draft",
+        server_default="draft",
+    )
+
+    is_featured: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=False,
+        server_default="false",
+    )
+
+    is_source_verified: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=False,
+        server_default="false",
+    )
+
+    verified_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+
+    collected_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+    )
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+    )
+
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+    source = relationship(
+        "Source",
+        back_populates="opportunities",
+        lazy="joined",
+    )
+
+    __table_args__ = (
+        Index("ix_opportunities_slug", "slug"),
+        Index(
+            "ix_opportunities_category_status",
+            "category",
+            "status",
+        ),
+        Index(
+            "ix_opportunities_deadline",
+            "deadline",
+        ),
+        Index(
+            "ix_opportunities_featured",
+            "is_featured",
+        ),
+    )

app/models/source.py

@@ -0,0 +1,123 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    Index,
+    String,
+    Text,
+    func,
+)
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.db.base import Base
+
+
+class Source(Base):
+    __tablename__ = "sources"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4,
+    )
+
+    name: Mapped[str] = mapped_column(
+        String(180),
+        nullable=False,
+        unique=True,
+    )
+
+    slug: Mapped[str] = mapped_column(
+        String(180),
+        nullable=False,
+        unique=True,
+    )
+
+    organization_type: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+        default="organization",
+        server_default="organization",
+    )
+
+    base_url: Mapped[str] = mapped_column(
+        Text,
+        nullable=False,
+    )
+
+    opportunities_url: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=True,
+    )
+
+    feed_url: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=True,
+    )
+
+    logo_url: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=True,
+    )
+
+    country_code: Mapped[str | None] = mapped_column(
+        String(2),
+        nullable=True,
+    )
+
+    source_tier: Mapped[str] = mapped_column(
+        String(1),
+        nullable=False,
+        default="B",
+        server_default="B",
+    )
+
+    is_official: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=True,
+        server_default="true",
+    )
+
+    is_active: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=True,
+        server_default="true",
+    )
+
+    last_checked_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+    )
+
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+    opportunities = relationship(
+        "Opportunity",
+        back_populates="source",
+        lazy="selectin",
+    )
+
+    __table_args__ = (
+        Index("ix_sources_slug", "slug"),
+        Index(
+            "ix_sources_active_official",
+            "is_active",
+            "is_official",
+        ),
+    )

app/repositories/opportunity.py

@@ -0,0 +1,120 @@
+from datetime import date
+
+from sqlalchemy import func, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.models.opportunity import Opportunity
+from app.schemas.opportunity import OpportunitySort
+
+
+class OpportunityRepository:
+    def __init__(self, session: AsyncSession) -> None:
+        self.session = session
+
+    def _public_query(self):
+        return (
+            select(Opportunity)
+            .options(selectinload(Opportunity.source))
+            .where(
+                Opportunity.status == "published",
+                Opportunity.is_source_verified.is_(True),
+                or_(
+                    Opportunity.deadline.is_(None),
+                    Opportunity.deadline >= date.today(),
+                ),
+            )
+        )
+
+    async def list_public(
+        self,
+        *,
+        page: int,
+        page_size: int,
+        search: str | None = None,
+        category: str | None = None,
+        country: str | None = None,
+        featured: bool | None = None,
+        sort: OpportunitySort = OpportunitySort.RECENT,
+    ) -> tuple[list[Opportunity], int]:
+        query = self._public_query()
+
+        if search:
+            pattern = f"%{search.strip()}%"
+
+            query = query.where(
+                or_(
+                    Opportunity.title.ilike(pattern),
+                    Opportunity.summary.ilike(pattern),
+                    Opportunity.organization_name.ilike(pattern),
+                )
+            )
+
+        if category:
+            query = query.where(
+                Opportunity.category == category
+            )
+
+        if country:
+            normalized_country = country.strip().upper()
+
+            query = query.where(
+                or_(
+                    Opportunity.country_code
+                    == normalized_country,
+                    Opportunity.target_countries.contains(
+                        [normalized_country]
+                    ),
+                )
+            )
+
+        if featured is not None:
+            query = query.where(
+                Opportunity.is_featured.is_(featured)
+            )
+
+        count_query = select(
+            func.count()
+        ).select_from(query.order_by(None).subquery())
+
+        total_result = await self.session.execute(
+            count_query
+        )
+        total_items = total_result.scalar_one()
+
+        if sort == OpportunitySort.DEADLINE:
+            query = query.order_by(
+                Opportunity.deadline.asc().nullslast(),
+                Opportunity.created_at.desc(),
+            )
+
+        elif sort == OpportunitySort.FEATURED:
+            query = query.order_by(
+                Opportunity.is_featured.desc(),
+                Opportunity.deadline.asc().nullslast(),
+                Opportunity.created_at.desc(),
+            )
+
+        else:
+            query = query.order_by(
+                Opportunity.created_at.desc()
+            )
+
+        query = query.offset(
+            (page - 1) * page_size
+        ).limit(page_size)
+
+        result = await self.session.execute(query)
+
+        return list(result.scalars().all()), total_items
+
+    async def get_public_by_slug(
+        self,
+        slug: str,
+    ) -> Opportunity | None:
+        query = self._public_query().where(
+            Opportunity.slug == slug
+        )
+
+        result = await self.session.execute(query)
+        return result.scalar_one_or_none()

app/schemas/opportunity.py

@@ -0,0 +1,103 @@
+import uuid
+from datetime import date, datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    HttpUrl,
+)
+
+
+class OpportunityCategory(StrEnum):
+    SCHOLARSHIP = "scholarship"
+    INTERNSHIP = "internship"
+    FELLOWSHIP = "fellowship"
+    TRAINING = "training"
+    COMPETITION = "competition"
+    HACKATHON = "hackathon"
+    GRANT = "grant"
+    JOB = "job"
+    OTHER = "other"
+
+
+class OpportunityStatus(StrEnum):
+    DRAFT = "draft"
+    PUBLISHED = "published"
+    EXPIRED = "expired"
+    ARCHIVED = "archived"
+    REJECTED = "rejected"
+class OpportunitySort(StrEnum):
+    RECENT = "recent"
+    DEADLINE = "deadline"
+    FEATURED = "featured"
+
+class SourceRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    slug: str
+    organization_type: str
+    base_url: HttpUrl
+    logo_url: HttpUrl | None
+    country_code: str | None
+    source_tier: str
+    is_official: bool
+    last_checked_at: datetime | None
+
+
+class OpportunityListItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    title: str
+    slug: str
+    summary: str
+    category: OpportunityCategory
+    organization_name: str
+    country_code: str | None
+    location: str | None
+    target_countries: list[str]
+    deadline: date | None
+    official_url: HttpUrl
+    image_url: HttpUrl | None
+    is_featured: bool
+    is_source_verified: bool
+    verified_at: datetime | None
+    source: SourceRead
+
+
+class OpportunityDetail(OpportunityListItem):
+    description: str | None
+    study_levels: list[str]
+    eligibility: dict[str, Any]
+    language: str | None
+    publication_date: date | None
+    application_url: HttpUrl | None
+    status: OpportunityStatus
+    collected_at: datetime
+    created_at: datetime
+    updated_at: datetime
+
+
+class OpportunityPagination(BaseModel):
+    page: int = Field(ge=1)
+    page_size: int = Field(ge=1, le=100)
+    total_items: int = Field(ge=0)
+    total_pages: int = Field(ge=0)
+    has_next: bool
+    has_previous: bool
+
+
+class OpportunityListResponse(BaseModel):
+    items: list[OpportunityListItem]
+    pagination: OpportunityPagination
+
+
+class OpportunityCategoryResponse(BaseModel):
+    value: OpportunityCategory
+    label_fr: str
+    label_en: str

app/services/opportunity.py

@@ -0,0 +1,133 @@
+from math import ceil
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.opportunity import Opportunity
+from app.repositories.opportunity import (
+    OpportunityRepository,
+)
+from app.schemas.opportunity import (
+    OpportunityCategory,
+    OpportunityCategoryResponse,
+    OpportunityListResponse,
+    OpportunityPagination,
+    OpportunitySort,
+)
+
+
+class OpportunityNotFoundError(Exception):
+    pass
+
+
+class OpportunityService:
+    def __init__(self, session: AsyncSession) -> None:
+        self.repository = OpportunityRepository(session)
+
+    async def list_opportunities(
+        self,
+        *,
+        page: int,
+        page_size: int,
+        search: str | None,
+        category: OpportunityCategory | None,
+        country: str | None,
+        featured: bool | None,
+        sort: OpportunitySort,
+    ) -> OpportunityListResponse:
+        opportunities, total_items = (
+            await self.repository.list_public(
+                page=page,
+                page_size=page_size,
+                search=search,
+                category=(
+                    category.value if category else None
+                ),
+                country=country,
+                featured=featured,
+                sort=sort,
+            )
+        )
+
+        total_pages = (
+            ceil(total_items / page_size)
+            if total_items
+            else 0
+        )
+
+        return OpportunityListResponse.model_validate(
+            {
+                "items": opportunities,
+                "pagination": OpportunityPagination(
+                    page=page,
+                    page_size=page_size,
+                    total_items=total_items,
+                    total_pages=total_pages,
+                    has_next=page < total_pages,
+                    has_previous=page > 1,
+                ),
+            }
+        )
+
+    async def get_by_slug(
+        self,
+        slug: str,
+    ) -> Opportunity:
+        opportunity = (
+            await self.repository.get_public_by_slug(slug)
+        )
+
+        if opportunity is None:
+            raise OpportunityNotFoundError
+
+        return opportunity
+
+    def list_categories(
+        self,
+    ) -> list[OpportunityCategoryResponse]:
+        labels = {
+            OpportunityCategory.SCHOLARSHIP: (
+                "Bourses",
+                "Scholarships",
+            ),
+            OpportunityCategory.INTERNSHIP: (
+                "Stages",
+                "Internships",
+            ),
+            OpportunityCategory.FELLOWSHIP: (
+                "Programmes de fellowship",
+                "Fellowships",
+            ),
+            OpportunityCategory.TRAINING: (
+                "Formations",
+                "Training",
+            ),
+            OpportunityCategory.COMPETITION: (
+                "Concours",
+                "Competitions",
+            ),
+            OpportunityCategory.HACKATHON: (
+                "Hackathons",
+                "Hackathons",
+            ),
+            OpportunityCategory.GRANT: (
+                "Financements",
+                "Grants",
+            ),
+            OpportunityCategory.JOB: (
+                "Emplois",
+                "Jobs",
+            ),
+            OpportunityCategory.OTHER: (
+                "Autres",
+                "Other",
+            ),
+        }
+
+        return [
+            OpportunityCategoryResponse(
+                value=category,
+                label_fr=labels[category][0],
+                label_en=labels[category][1],
+            )
+            for category in OpportunityCategory
+        ]