Skip to content

download endpoints — Overview

This router implements the high-level orchestration for monthly invoice downloads and related utilities. It coordinates Sheets_Manager (to read invoices) and Gmail_Manager (to download attachments) and reports progress over WebSocket via Connection_Manager.

Main routes

  • WebSocket: GET /ws
  • Purpose: keep an open connection to receive progress updates (type: progress, status).

  • Messages received from server: JSON { type: "progress", progress: 42, message: "...", stats: {...} }.

  • Start download: POST /start

  • Body: StartDownloadRequest (JSON) — fields year (int), month (int).
  • Behavior: validates that no download is currently running, resets download_state, then starts download_process(year, month) in a background task using a new SessionLocal() DB session.
  • Response: { "message": "Download process started", "status": "running" }.

  • Notes: the background task uses connection_manager.send_progress_update() callbacks to stream progress updates to connected WebSocket clients.

  • Stop download: POST /stop

  • Behavior: sets connection_manager.download_state["is_running"] = False and sends a status update; returns { "message": "Download process stopped", "status": "stopped" }.

  • Status: GET /status

  • Returns: current download_state with keys is_running, progress, status, message, stats.

  • Download ZIP: GET /zip?month={m}&year={y}

  • Streams a ZIP archive containing all invoice files under invoices/{year}/{month:02d} as a StreamingResponse (application/zip).

  • Errors: 404 if folder or files not present.

  • Available ZIPs: GET /available_zips

  • Returns: list of available year/month combos with file_count and zip_filename.

  • Health: GET /health

  • Returns a small health JSON and number of active WebSocket connections.

Operational details

  • download_process(year, month, db):
  • Steps: authenticate all active Google credentials, for each credential fetch invoices via get_invoices_for_month, filter already-confirmed invoices, download attachments using gmail_manager.download_invoices_async(invoices, progress_callback), write eval_{year}_{month}.json, and bulk-update confirmations in Sheets.
  • Progress: progress is reported in ranges (initialization → sheets retrieval → gmail download → file organization → completion) and sent via Connection_Manager.broadcast().

  • Error handling: exceptions broadcast an error message and set is_running False in download_state.

  • Background DB sessions: a dedicated DB session is created inside the background coroutine and closed when finished to prevent session lifetime issues.

Examples

  • Start a month download (curl):
curl -X POST "http://localhost:8000/api/v1/invoice/start" \
  -H "Content-Type: application/json" \
  -d '{"year":2024, "month":3}'
  • WebSocket message format (progress):
{
  "type": "progress",
  "progress": 55,
  "message": "Gmail download: 120/200 invoices",
  "stats": { "processedEmails": 120, "totalEmails": 200 }
}