feat(fc3c): /api/downloads blueprint (list + detail w/ keyset pagination)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/app/api/__init__.py

@@ -20,6 +20,7 @@ def all_blueprints() -> list[Blueprint]:
     from .artists import artists_bp
     from .attachments import attachments_bp
     from .credentials import credentials_bp
+    from .downloads import downloads_bp
     from .gallery import gallery_bp
     from .import_admin import import_admin_bp
     from .ml_admin import ml_admin_bp
@@ -48,4 +49,5 @@ def all_blueprints() -> list[Blueprint]:
         sources_bp,
         platforms_bp,
         credentials_bp,
+        downloads_bp,
     ]

backend/app/api/downloads.py

@@ -0,0 +1,110 @@
+"""FC-3c: GET /api/downloads (list) + GET /api/downloads/<id> (detail).
+
+List view: keyset-paginated, newest first, optional filtering by
+status/source/artist. Returns slim records.
+Detail view: full DownloadEvent including the metadata JSONB.
+"""
+
+from quart import Blueprint, jsonify, request
+from sqlalchemy import select
+
+from ..extensions import get_session
+from ..models import Artist, DownloadEvent, Source
+
+downloads_bp = Blueprint("downloads", __name__, url_prefix="/api/downloads")
+
+_ALLOWED_STATUSES = frozenset({"pending", "running", "ok", "error", "skipped"})
+
+
+def _summary_from_metadata(metadata: dict | None) -> dict:
+    metadata = metadata or {}
+    run_stats = metadata.get("run_stats") or {}
+    return {
+        "downloaded": int(run_stats.get("downloaded_count", 0)),
+        "skipped": int(run_stats.get("skipped_count", 0)),
+        "quarantined": int(run_stats.get("quarantined_count", 0)),
+        "duration_seconds": metadata.get("duration_seconds"),
+        "error_type": metadata.get("error_type"),
+    }
+
+
+def _list_record(event: DownloadEvent, source: Source | None, artist: Artist | None) -> dict:
+    return {
+        "id": event.id,
+        "source_id": event.source_id,
+        "artist_name": artist.name if artist else None,
+        "artist_slug": artist.slug if artist else None,
+        "platform": source.platform if source else None,
+        "status": event.status,
+        "started_at": event.started_at.isoformat() if event.started_at else None,
+        "finished_at": event.finished_at.isoformat() if event.finished_at else None,
+        "files_count": event.files_count,
+        "bytes_downloaded": event.bytes_downloaded,
+        "error": event.error,
+        "summary": _summary_from_metadata(event.metadata_),
+    }
+
+
+def _detail_record(event: DownloadEvent, source: Source | None, artist: Artist | None) -> dict:
+    base = _list_record(event, source, artist)
+    base["metadata"] = event.metadata_ or {}
+    return base
+
+
+@downloads_bp.route("", methods=["GET"])
+async def list_downloads():
+    status = request.args.get("status")
+    if status and status not in _ALLOWED_STATUSES:
+        return jsonify({"error": "invalid_status"}), 400
+    try:
+        limit = int(request.args.get("limit", "50"))
+    except ValueError:
+        return jsonify({"error": "invalid_limit"}), 400
+    limit = max(1, min(200, limit))
+    before_raw = request.args.get("before")
+    before = None
+    if before_raw is not None:
+        try:
+            before = int(before_raw)
+        except ValueError:
+            return jsonify({"error": "invalid_before"}), 400
+    try:
+        source_id = int(request.args["source_id"]) if "source_id" in request.args else None
+        artist_id = int(request.args["artist_id"]) if "artist_id" in request.args else None
+    except (ValueError, KeyError):
+        return jsonify({"error": "invalid_filter"}), 400
+
+    async with get_session() as session:
+        stmt = (
+            select(DownloadEvent, Source, Artist)
+            .outerjoin(Source, Source.id == DownloadEvent.source_id)
+            .outerjoin(Artist, Artist.id == Source.artist_id)
+            .order_by(DownloadEvent.id.desc())
+            .limit(limit)
+        )
+        if status:
+            stmt = stmt.where(DownloadEvent.status == status)
+        if source_id is not None:
+            stmt = stmt.where(DownloadEvent.source_id == source_id)
+        if artist_id is not None:
+            stmt = stmt.where(Source.artist_id == artist_id)
+        if before is not None:
+            stmt = stmt.where(DownloadEvent.id < before)
+        rows = (await session.execute(stmt)).all()
+
+    return jsonify([_list_record(e, s, a) for e, s, a in rows])
+
+
+@downloads_bp.route("/<int:event_id>", methods=["GET"])
+async def get_download(event_id: int):
+    async with get_session() as session:
+        row = (await session.execute(
+            select(DownloadEvent, Source, Artist)
+            .outerjoin(Source, Source.id == DownloadEvent.source_id)
+            .outerjoin(Artist, Artist.id == Source.artist_id)
+            .where(DownloadEvent.id == event_id)
+        )).first()
+        if row is None:
+            return jsonify({"error": "not_found"}), 404
+        event, source, artist = row
+    return jsonify(_detail_record(event, source, artist))