Squash merge feature/library-reorganization

backend/app/routes/__init__.py

@@ -0,0 +1,2 @@
+"""API routes."""
+

backend/app/routes/auth.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import secrets
+import time
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response, status
+from fastapi.responses import JSONResponse, RedirectResponse
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from ..auth import (
+    build_teamsnap_authorize_url,
+    clear_session_cookie,
+    create_session_token,
+    exchange_code_for_token,
+    fetch_teamsnap_user_id,
+    get_current_session,
+    refresh_access_token,
+    require_admin,
+    require_session,
+    set_session_cookie,
+    update_session_tokens,
+)
+from ..config import settings
+from ..database import get_db
+from ..models import UserSession
+from .teamsnap import build_proxy_api_root
+from ..schemas import (
+    AdminLoginRequest,
+    SessionResponse,
+    TeamSnapTokenResponse,
+    WalkupSessionSelectionUpdate,
+)
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+def normalize_return_to(return_to: str | None) -> str:
+    if not return_to or not return_to.startswith("/") or return_to.startswith("//"):
+        return "/"
+    return return_to
+
+
+@router.get("/teamsnap/start")
+def teamsnap_start(return_to: str | None = Query(default="/")) -> Response:
+    if not settings.teamsnap_client_id:
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="TeamSnap is not configured")
+    state = secrets.token_urlsafe(24)
+    response = JSONResponse({"authorize_url": build_teamsnap_authorize_url(state), "state": state})
+    response.set_cookie(
+        settings.auth_return_cookie_name,
+        normalize_return_to(return_to),
+        httponly=True,
+        secure=settings.session_cookie_secure,
+        samesite="lax",
+        max_age=60 * 10,
+    )
+    return response
+
+
+@router.get("/teamsnap/callback")
+async def teamsnap_callback(
+    request: Request,
+    code: str = Query(...),
+    db: Session = Depends(get_db),
+) -> Response:
+    token_payload = await exchange_code_for_token(code)
+    session = UserSession(session_token=create_session_token(), provider="teamsnap")
+    update_session_tokens(session, token_payload)
+    if session.access_token:
+        session.external_user_id = await fetch_teamsnap_user_id(session.access_token)
+    db.add(session)
+    db.commit()
+    redirect_target = normalize_return_to(request.cookies.get(settings.auth_return_cookie_name))
+    redirect = RedirectResponse(url=redirect_target, status_code=status.HTTP_303_SEE_OTHER)
+    set_session_cookie(redirect, session.session_token)
+    redirect.delete_cookie(settings.auth_return_cookie_name)
+    return redirect
+
+
+@router.get("/session", response_model=SessionResponse)
+def session_status(session: UserSession | None = Depends(get_current_session)) -> SessionResponse:
+    if session is None:
+        return SessionResponse(authenticated=False)
+    return SessionResponse(
+        authenticated=True,
+        provider=session.provider,
+        is_admin=session.is_admin,
+        external_user_id=session.external_user_id,
+        external_team_id=session.external_team_id,
+        external_player_id=session.external_player_id,
+        token_expires_at=session.token_expires_at,
+    )
+
+
+@router.post("/teamsnap/token", response_model=TeamSnapTokenResponse)
+async def teamsnap_token(
+    request: Request,
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> TeamSnapTokenResponse:
+    if session.provider != "teamsnap":
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Session is not TeamSnap-backed")
+
+    if not session.access_token:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing TeamSnap access token")
+
+    expires_soon = session.token_expires_at is None or session.token_expires_at.timestamp() <= (time.time() + 60)
+    if expires_soon and session.refresh_token:
+        token_payload = await refresh_access_token(session.refresh_token)
+        update_session_tokens(session, token_payload)
+        if not session.external_user_id and session.access_token:
+            session.external_user_id = await fetch_teamsnap_user_id(session.access_token)
+        db.add(session)
+        db.commit()
+        db.refresh(session)
+
+    return TeamSnapTokenResponse(
+        access_token=session.access_token,
+        expires_at=session.token_expires_at,
+        api_root=build_proxy_api_root(request),
+        auth_url=settings.teamsnap_auth_url.removesuffix("/oauth/authorize"),
+    )
+
+
+@router.post("/session/walkup", response_model=SessionResponse)
+def update_walkup_session_selection(
+    payload: WalkupSessionSelectionUpdate,
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> SessionResponse:
+    if session.provider != "teamsnap":
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Session is not TeamSnap-backed")
+
+    session.external_team_id = payload.external_team_id
+    session.external_player_id = payload.external_player_id
+    db.add(session)
+    db.commit()
+    db.refresh(session)
+    return SessionResponse(
+        authenticated=True,
+        provider=session.provider,
+        is_admin=session.is_admin,
+        external_user_id=session.external_user_id,
+        external_team_id=session.external_team_id,
+        external_player_id=session.external_player_id,
+        token_expires_at=session.token_expires_at,
+    )
+
+
+@router.post("/admin/login", response_model=SessionResponse)
+def admin_login(payload: AdminLoginRequest, response: Response, db: Session = Depends(get_db)) -> SessionResponse:
+    if payload.username != settings.local_admin_username or payload.password != settings.local_admin_password:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials")
+    session = UserSession(session_token=create_session_token(), provider="local", is_admin=True)
+    db.add(session)
+    db.commit()
+    set_session_cookie(response, session.session_token)
+    return SessionResponse(authenticated=True, provider="local", is_admin=True)
+
+
+@router.post("/logout")
+def logout(
+    response: Response,
+    session: UserSession | None = Depends(get_current_session),
+    db: Session = Depends(get_db),
+) -> dict[str, bool]:
+    if session is not None:
+        db.delete(session)
+        db.commit()
+    clear_session_cookie(response)
+    return {"ok": True}
+
+
+@router.get("/admin/check", response_model=SessionResponse)
+def admin_check(_: UserSession = Depends(require_admin)) -> SessionResponse:
+    return SessionResponse(authenticated=True, provider="local", is_admin=True)

backend/app/routes/games.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from ..auth import require_session
+from ..database import get_db
+from ..models import AudioClip, GameAssignment, PlaybackSession, UserSession
+from ..schemas import (
+    GameAssignmentCreate,
+    GameAssignmentResponse,
+    GamePrepResponse,
+    PlaybackAction,
+    PlaybackSessionCreate,
+    PlaybackSessionResponse,
+)
+
+router = APIRouter(prefix="/games", tags=["games"])
+
+
+def assignment_to_response(assignment: GameAssignment) -> GameAssignmentResponse:
+    normalized_url = f"/media/files/{assignment.clip.normalized_path}" if assignment.clip.normalized_path else None
+    return GameAssignmentResponse(
+        id=assignment.id,
+        external_team_id=assignment.external_team_id,
+        external_game_id=assignment.external_game_id,
+        external_player_id=assignment.external_player_id,
+        clip_id=assignment.clip_id,
+        clip_label=assignment.clip.label,
+        asset_title=assignment.clip.asset.title,
+        start_ms=assignment.clip.start_ms,
+        end_ms=assignment.clip.end_ms,
+        batting_slot=assignment.batting_slot,
+        status=assignment.status,
+        normalized_url=normalized_url,
+        updated_at=assignment.updated_at,
+    )
+
+
+@router.get("/{external_game_id}/assignments", response_model=list[GameAssignmentResponse])
+def list_assignments(
+    external_game_id: str,
+    external_player_id: str | None = Query(default=None),
+    _: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> list[GameAssignmentResponse]:
+    query = select(GameAssignment).where(GameAssignment.external_game_id == external_game_id)
+    if external_player_id:
+        query = query.where(GameAssignment.external_player_id == external_player_id)
+    assignments = db.scalars(query.order_by(GameAssignment.batting_slot, GameAssignment.updated_at.desc())).all()
+    return [assignment_to_response(assignment) for assignment in assignments]
+
+
+@router.post("/{external_game_id}/assignments", response_model=GameAssignmentResponse)
+def create_assignment(
+    external_game_id: str,
+    payload: GameAssignmentCreate,
+    _: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> GameAssignmentResponse:
+    clip = db.get(AudioClip, payload.clip_id)
+    if clip is None or clip.normalization_status != "ready":
+        raise HTTPException(status_code=422, detail="Clip is not ready")
+    if clip.asset.external_team_id != payload.external_team_id:
+        raise HTTPException(status_code=422, detail="Clip does not belong to this team")
+    if clip.asset.owner_external_player_id != payload.external_player_id:
+        raise HTTPException(status_code=403, detail="You can only attach clips owned by that player")
+
+    assignment = db.scalar(
+        select(GameAssignment).where(
+            GameAssignment.external_game_id == external_game_id,
+            GameAssignment.external_player_id == payload.external_player_id,
+            GameAssignment.clip_id == payload.clip_id,
+        )
+    )
+    if assignment is None:
+        assignment = GameAssignment(
+            external_team_id=payload.external_team_id,
+            external_game_id=external_game_id,
+            external_player_id=payload.external_player_id,
+            clip_id=payload.clip_id,
+            batting_slot=payload.batting_slot,
+            status=payload.status,
+        )
+        db.add(assignment)
+    else:
+        assignment.external_team_id = payload.external_team_id
+        assignment.clip_id = payload.clip_id
+        assignment.batting_slot = payload.batting_slot
+        assignment.status = payload.status
+    db.commit()
+    db.refresh(assignment)
+    return assignment_to_response(assignment)
+
+
+@router.get("/{external_game_id}/prep", response_model=GamePrepResponse)
+def prepare_game(
+    external_game_id: str,
+    _: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> GamePrepResponse:
+    assignments = db.scalars(
+        select(GameAssignment)
+        .where(GameAssignment.external_game_id == external_game_id)
+        .order_by(GameAssignment.batting_slot, GameAssignment.updated_at.desc())
+    ).all()
+    external_team_id = assignments[0].external_team_id if assignments else ""
+    return GamePrepResponse(
+        external_game_id=external_game_id,
+        external_team_id=external_team_id,
+        prepared_at=datetime.now(timezone.utc),
+        assignments=[assignment_to_response(assignment) for assignment in assignments],
+    )
+
+
+@router.post("/{external_game_id}/operator/session", response_model=PlaybackSessionResponse)
+def create_playback_session(
+    external_game_id: str,
+    payload: PlaybackSessionCreate,
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> PlaybackSessionResponse:
+    playback = PlaybackSession(
+        external_team_id=payload.external_team_id,
+        external_game_id=external_game_id,
+        operator_session_id=session.id,
+        state="idle",
+    )
+    db.add(playback)
+    db.commit()
+    db.refresh(playback)
+    return PlaybackSessionResponse.model_validate(playback, from_attributes=True)
+
+
+@router.post("/{external_game_id}/operator/session/{playback_session_id}/trigger", response_model=PlaybackSessionResponse)
+def trigger_playback(
+    external_game_id: str,
+    playback_session_id: int,
+    payload: PlaybackAction,
+    _: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> PlaybackSessionResponse:
+    playback = db.get(PlaybackSession, playback_session_id)
+    if playback is None or playback.external_game_id != external_game_id:
+        raise HTTPException(status_code=404, detail="Playback session not found")
+
+    if payload.assignment_id is None and payload.clip_id is None:
+        raise HTTPException(status_code=422, detail="Provide an assignment or clip to trigger")
+
+    if payload.assignment_id is not None:
+        assignment = db.get(GameAssignment, payload.assignment_id)
+        if assignment is None or assignment.external_game_id != external_game_id:
+            raise HTTPException(status_code=404, detail="Assignment not found")
+        playback.current_assignment_id = assignment.id
+    else:
+        clip = db.get(AudioClip, payload.clip_id)
+        if clip is None or clip.asset.external_team_id != playback.external_team_id:
+            raise HTTPException(status_code=404, detail="Clip not found")
+        if payload.external_player_id and clip.asset.owner_external_player_id != payload.external_player_id:
+            raise HTTPException(status_code=403, detail="Clip does not belong to that player")
+        playback.current_assignment_id = None
+
+    playback.state = payload.state
+    playback.last_triggered_at = datetime.now(timezone.utc)
+    db.commit()
+    db.refresh(playback)
+    return PlaybackSessionResponse.model_validate(playback, from_attributes=True)

backend/app/routes/health.py

@@ -0,0 +1,9 @@
+from fastapi import APIRouter
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+def healthcheck() -> dict[str, str]:
+    return {"status": "ok"}
+

backend/app/routes/media.py

@@ -0,0 +1,373 @@
+from __future__ import annotations
+
+import secrets
+import shutil
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+from sqlalchemy import delete, select, update
+from sqlalchemy.orm import Session
+
+from ..auth import require_session
+from ..database import get_db
+from ..models import AudioAsset, AudioClip, GameAssignment, PlaybackSession, UserSession
+from ..schemas import (
+    AudioAssetImportCreate,
+    AudioAssetResponse,
+    AudioAssetUpdate,
+    AudioClipCreate,
+    AudioClipResponse,
+    AudioClipUpdate,
+)
+from ..storage import storage
+
+router = APIRouter(prefix="/media", tags=["media"])
+
+DEFAULT_CLIP_LENGTH_MS = 30_000
+
+
+def clip_to_response(clip: AudioClip) -> AudioClipResponse:
+    normalized_url = f"/media/files/{clip.normalized_path}" if clip.normalized_path else None
+    waveform = storage.load_or_generate_waveform(clip.asset.storage_path)
+    return AudioClipResponse(
+        id=clip.id,
+        asset_id=clip.asset_id,
+        external_team_id=clip.asset.external_team_id,
+        owner_external_player_id=clip.asset.owner_external_player_id,
+        asset_title=clip.asset.title,
+        label=clip.label,
+        start_ms=clip.start_ms,
+        end_ms=clip.end_ms,
+        normalization_status=clip.normalization_status,
+        normalized_url=normalized_url,
+        waveform_duration_ms=waveform["duration_ms"] if waveform else None,
+        waveform_peaks=waveform["peaks"] if waveform else None,
+        created_at=clip.created_at,
+    )
+
+
+def can_manage_asset(session: UserSession, asset: AudioAsset, owner_external_player_id: str | None = None) -> bool:
+    if session.is_admin or asset.uploaded_by_session_id == session.id:
+        return True
+    return owner_external_player_id is not None and asset.owner_external_player_id == owner_external_player_id
+
+
+def create_asset_with_default_clip(
+    *,
+    db: Session,
+    session: UserSession,
+    external_team_id: str,
+    owner_external_player_id: str,
+    title: str,
+    original_filename: str,
+    mime_type: str,
+    size_bytes: int,
+    storage_path: str,
+) -> AudioAssetResponse:
+    asset = AudioAsset(
+        external_team_id=external_team_id,
+        owner_external_player_id=owner_external_player_id,
+        uploaded_by_session_id=session.id,
+        title=title,
+        original_filename=original_filename,
+        mime_type=mime_type,
+        size_bytes=size_bytes,
+        storage_path=storage_path,
+    )
+    db.add(asset)
+    db.flush()
+
+    clip = AudioClip(
+        asset_id=asset.id,
+        label=asset.title,
+        start_ms=0,
+        end_ms=DEFAULT_CLIP_LENGTH_MS,
+        normalization_status="processing",
+    )
+    db.add(clip)
+    db.flush()
+
+    normalized_name = f"clip-{clip.id}-{secrets.token_hex(6)}{Path(asset.storage_path).suffix or '.bin'}"
+    clip.normalized_path = storage.normalize_clip(asset.storage_path, normalized_name)
+    clip.normalization_status = "ready"
+    storage.generate_waveform(asset.storage_path)
+
+    db.commit()
+    db.refresh(asset)
+    return AudioAssetResponse.model_validate(asset, from_attributes=True)
+
+
+def download_media_to_storage(url: str) -> tuple[str, int, str, str]:
+    try:
+        from yt_dlp import YoutubeDL
+        from yt_dlp.utils import DownloadError
+    except ImportError as exc:  # pragma: no cover - guarded by dependency install
+        raise HTTPException(status_code=500, detail="yt-dlp is not installed") from exc
+
+    storage_name = f"{secrets.token_hex(16)}.%(ext)s"
+    outtmpl = str(storage.uploads_dir / storage_name)
+    options = {
+        "format": "bestaudio/best",
+        "noplaylist": True,
+        "quiet": True,
+        "no_warnings": True,
+        "outtmpl": outtmpl,
+        "restrictfilenames": True,
+        "extractor_args": {"youtube": {"player_client": ["android"]}},
+    }
+    node_path = shutil.which("node")
+    if node_path:
+        options["js_runtimes"] = {"node": {"path": node_path}}
+
+    try:
+        with YoutubeDL(options) as ydl:
+            info = ydl.extract_info(url, download=True)
+            downloaded_path = Path(ydl.prepare_filename(info))
+    except DownloadError as exc:  # pragma: no cover - exercised via HTTP behavior
+        message = str(exc).strip() or "Could not download media from that URL"
+        raise HTTPException(status_code=422, detail=f"Could not download media from that URL: {message}") from exc
+    except Exception as exc:  # pragma: no cover - exercised via HTTP behavior
+        message = str(exc).strip() or "Could not download media from that URL"
+        raise HTTPException(status_code=422, detail=f"Could not download media from that URL: {message}") from exc
+
+    if not downloaded_path.exists():
+        raise HTTPException(status_code=502, detail="Downloaded file was not created")
+
+    size_bytes = downloaded_path.stat().st_size
+    original_filename = downloaded_path.name
+    source_title = str(info.get("title") or downloaded_path.stem)
+    return str(downloaded_path.relative_to(storage.root)), size_bytes, original_filename, source_title
+
+
+@router.post("/uploads", response_model=AudioAssetResponse)
+async def upload_audio(
+    external_team_id: str = Form(...),
+    owner_external_player_id: str = Form(...),
+    title: str = Form(...),
+    file: UploadFile = File(...),
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> AudioAssetResponse:
+    extension = Path(file.filename or "upload.bin").suffix or ".bin"
+    storage_name = f"{secrets.token_hex(16)}{extension}"
+    relative_path, size = storage.save_upload(file, storage_name)
+    return create_asset_with_default_clip(
+        db=db,
+        session=session,
+        external_team_id=external_team_id,
+        owner_external_player_id=owner_external_player_id,
+        title=title,
+        original_filename=file.filename or storage_name,
+        mime_type=file.content_type or "application/octet-stream",
+        size_bytes=size,
+        storage_path=relative_path,
+    )
+
+
+@router.post("/imports", response_model=AudioAssetResponse)
+def import_audio(
+    payload: AudioAssetImportCreate,
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> AudioAssetResponse:
+    relative_path, size_bytes, original_filename, source_title = download_media_to_storage(payload.url)
+    title = payload.title.strip() if payload.title else ""
+    if not title:
+        title = source_title
+
+    return create_asset_with_default_clip(
+        db=db,
+        session=session,
+        external_team_id=payload.external_team_id,
+        owner_external_player_id=payload.owner_external_player_id,
+        title=title,
+        original_filename=original_filename,
+        mime_type="application/octet-stream",
+        size_bytes=size_bytes,
+        storage_path=relative_path,
+    )
+
+
+@router.get("/assets", response_model=list[AudioAssetResponse])
+def list_assets(
+    external_team_id: str,
+    owner_external_player_id: str | None = None,
+    _: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> list[AudioAssetResponse]:
+    query = select(AudioAsset).where(AudioAsset.external_team_id == external_team_id)
+    if owner_external_player_id:
+        query = query.where(AudioAsset.owner_external_player_id == owner_external_player_id)
+    assets = db.scalars(query.order_by(AudioAsset.created_at.desc())).all()
+    return [AudioAssetResponse.model_validate(asset, from_attributes=True) for asset in assets]
+
+
+@router.delete("/assets/{asset_id}", status_code=204)
+def delete_asset(
+    asset_id: int,
+    owner_external_player_id: str | None = None,
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> None:
+    asset = db.get(AudioAsset, asset_id)
+    if asset is None:
+        raise HTTPException(status_code=404, detail="Asset not found")
+    if not can_manage_asset(session, asset, owner_external_player_id):
+        raise HTTPException(status_code=403, detail="You can only delete your own uploads")
+
+    clips = db.scalars(select(AudioClip).where(AudioClip.asset_id == asset.id)).all()
+    clip_ids = [clip.id for clip in clips]
+    if clip_ids:
+        assignment_ids = db.scalars(select(GameAssignment.id).where(GameAssignment.clip_id.in_(clip_ids))).all()
+        db.execute(delete(GameAssignment).where(GameAssignment.clip_id.in_(clip_ids)))
+        if assignment_ids:
+            db.execute(
+                update(PlaybackSession)
+                .where(PlaybackSession.current_assignment_id.in_(assignment_ids))
+                .values(current_assignment_id=None)
+            )
+    for clip in clips:
+        if clip.normalized_path:
+            storage.delete_relative_path(clip.normalized_path)
+        db.delete(clip)
+
+    storage.delete_relative_path(asset.storage_path)
+    db.delete(asset)
+    db.commit()
+
+
+@router.patch("/assets/{asset_id}", response_model=AudioAssetResponse)
+def update_asset(
+    asset_id: int,
+    payload: AudioAssetUpdate,
+    owner_external_player_id: str | None = None,
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> AudioAssetResponse:
+    asset = db.get(AudioAsset, asset_id)
+    if asset is None:
+        raise HTTPException(status_code=404, detail="Asset not found")
+    if not can_manage_asset(session, asset, owner_external_player_id):
+        raise HTTPException(status_code=403, detail="You can only update your own uploads")
+
+    title = payload.title.strip()
+    if not title:
+        raise HTTPException(status_code=422, detail="File name cannot be blank")
+
+    asset.title = title
+    db.commit()
+    db.refresh(asset)
+    return AudioAssetResponse.model_validate(asset, from_attributes=True)
+
+
+@router.post("/clips", response_model=AudioClipResponse)
+def create_clip(
+    payload: AudioClipCreate,
+    _: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> AudioClipResponse:
+    asset = db.get(AudioAsset, payload.asset_id)
+    if asset is None:
+        raise HTTPException(status_code=404, detail="Asset not found")
+    if asset.external_team_id != payload.external_team_id:
+        raise HTTPException(status_code=422, detail="Clip does not belong to this team")
+    if asset.owner_external_player_id != payload.owner_external_player_id:
+        raise HTTPException(status_code=403, detail="You can only create clips for that player")
+    if payload.end_ms <= payload.start_ms:
+        raise HTTPException(status_code=422, detail="Clip end must be greater than start")
+
+    clip = AudioClip(
+        asset_id=asset.id,
+        label=payload.label,
+        start_ms=payload.start_ms,
+        end_ms=payload.end_ms,
+        normalization_status="processing",
+    )
+    db.add(clip)
+    db.flush()
+
+    normalized_name = f"clip-{clip.id}-{secrets.token_hex(6)}{Path(asset.storage_path).suffix or '.bin'}"
+    clip.normalized_path = storage.normalize_clip(asset.storage_path, normalized_name)
+    clip.normalization_status = "ready"
+    db.commit()
+    db.refresh(clip)
+    return clip_to_response(clip)
+
+
+@router.patch("/clips/{clip_id}", response_model=AudioClipResponse)
+def update_clip(
+    clip_id: int,
+    payload: AudioClipUpdate,
+    owner_external_player_id: str | None = None,
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> AudioClipResponse:
+    clip = db.get(AudioClip, clip_id)
+    if clip is None:
+        raise HTTPException(status_code=404, detail="Clip not found")
+    if not can_manage_asset(session, clip.asset, owner_external_player_id):
+        raise HTTPException(status_code=403, detail="You can only update clips from your own uploads")
+    if payload.end_ms <= payload.start_ms:
+        raise HTTPException(status_code=422, detail="Clip end must be greater than start")
+
+    clip.label = payload.label or clip.label
+    clip.start_ms = payload.start_ms
+    clip.end_ms = payload.end_ms
+    db.commit()
+    db.refresh(clip)
+    return clip_to_response(clip)
+
+
+@router.delete("/clips/{clip_id}", status_code=204)
+def delete_clip(
+    clip_id: int,
+    owner_external_player_id: str | None = None,
+    session: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> None:
+    clip = db.get(AudioClip, clip_id)
+    if clip is None:
+        raise HTTPException(status_code=404, detail="Clip not found")
+    if not can_manage_asset(session, clip.asset, owner_external_player_id):
+        raise HTTPException(status_code=403, detail="You can only delete clips from your own uploads")
+
+    assignment_ids = db.scalars(select(GameAssignment.id).where(GameAssignment.clip_id == clip.id)).all()
+    db.execute(delete(GameAssignment).where(GameAssignment.clip_id == clip.id))
+    if assignment_ids:
+        db.execute(
+            update(PlaybackSession)
+            .where(PlaybackSession.current_assignment_id.in_(assignment_ids))
+            .values(current_assignment_id=None)
+        )
+    if clip.normalized_path:
+        storage.delete_relative_path(clip.normalized_path)
+    db.delete(clip)
+    db.commit()
+
+
+@router.get("/clips", response_model=list[AudioClipResponse])
+def list_clips(
+    external_team_id: str,
+    owner_external_player_id: str | None = None,
+    _: UserSession = Depends(require_session),
+    db: Session = Depends(get_db),
+) -> list[AudioClipResponse]:
+    query = (
+        select(AudioClip)
+        .join(AudioClip.asset)
+        .where(AudioAsset.external_team_id == external_team_id)
+        .order_by(AudioClip.created_at.desc())
+    )
+    if owner_external_player_id:
+        query = query.where(AudioAsset.owner_external_player_id == owner_external_player_id)
+    clips = db.scalars(query).all()
+    return [clip_to_response(clip) for clip in clips]
+
+
+@router.get("/files/{relative_path:path}")
+def media_file(relative_path: str) -> FileResponse:
+    path = storage.absolute_path(relative_path)
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="File not found")
+    return FileResponse(path)

backend/app/routes/teamsnap.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+import json
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+
+from ..auth import require_session
+from ..models import UserSession
+
+router = APIRouter(prefix="/teamsnap", tags=["teamsnap"])
+
+
+def build_proxy_api_root(request: Request) -> str:
+    scheme = request.headers.get("x-forwarded-proto", request.url.scheme)
+    host = request.headers.get("x-forwarded-host", request.headers.get("host", request.url.netloc))
+    return f"{scheme}://{host}/api/teamsnap"
+
+
+def rewrite_teamsnap_urls(value: object, upstream_root: str, proxy_root: str) -> object:
+    if isinstance(value, str):
+        return value.replace(upstream_root, proxy_root)
+    if isinstance(value, Mapping):
+        return {key: rewrite_teamsnap_urls(item, upstream_root, proxy_root) for key, item in value.items()}
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return [rewrite_teamsnap_urls(item, upstream_root, proxy_root) for item in value]
+    return value
+
+
+def build_upstream_url(request: Request, proxy_path: str) -> str:
+    base = request.app.state.settings.teamsnap_api_root.rstrip("/")
+    if not proxy_path:
+        return base
+    return f"{base}/{proxy_path.lstrip('/')}"
+
+
+@router.api_route("/{proxy_path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"])
+@router.api_route("", methods=["GET", "POST", "PUT", "PATCH", "DELETE"])
+async def teamsnap_proxy(
+    request: Request,
+    session: UserSession = Depends(require_session),
+    proxy_path: str = "",
+) -> Response:
+    if session.provider != "teamsnap":
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Session is not TeamSnap-backed")
+    if not session.access_token:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing TeamSnap access token")
+
+    upstream_url = build_upstream_url(request, proxy_path)
+    outgoing_headers = {
+        "Accept": request.headers.get("accept", "application/vnd.collection+json"),
+        "Authorization": f"Bearer {session.access_token}",
+    }
+    if request.headers.get("content-type"):
+        outgoing_headers["Content-Type"] = request.headers["content-type"]
+
+    body = await request.body()
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        upstream = await client.request(
+            request.method,
+            upstream_url,
+            params=request.query_params,
+            content=body or None,
+            headers=outgoing_headers,
+        )
+
+    content_type = upstream.headers.get("content-type", "")
+    if "json" not in content_type.lower():
+        response = Response(content=upstream.content, status_code=upstream.status_code)
+        if content_type:
+            response.headers["Content-Type"] = content_type
+        return response
+
+    proxy_root = build_proxy_api_root(request)
+    rewritten = rewrite_teamsnap_urls(upstream.json(), request.app.state.settings.teamsnap_api_root, proxy_root)
+    return Response(
+        content=json.dumps(rewritten),
+        status_code=upstream.status_code,
+        media_type=content_type or "application/json",
+    )