Draft: feat: add user statistics command to corpus-client-cli

SandhyaRani Bandaramrequested to merge
feat/stats-command into main

Overview

This merge request introduces a dedicated stats command to corpus-client-cli, enabling authenticated users to view contribution statistics directly from the terminal.

This improves CLI usability and aligns the tool with roadmap expectations for contributor visibility workflows.

Problem Statement

The CLI currently supports contribution workflows (file upload and extracted-text upload), but does not provide a built-in way to inspect contribution outcomes from the terminal.

This creates a functional gap:

  • users can contribute data via CLI
  • users cannot review contribution performance via CLI
  • statistics visibility remains dependent on API availability for terminal workflows

The roadmap expects statistics support through GET /api/v1/stats/, so this feature is required for parity.

Objective

Add a production-ready statistics command that:

  • reuses the existing authenticated session/token
  • calls the configured statistics endpoint
  • parses API responses safely
  • renders a terminal-friendly summary
  • handles empty/partial/missing payloads gracefully
  • shows clear errors for auth/API failures

What This MR Delivers

1. New Command

corpus-client stats

2. Session-Aware API Integration

The command uses the active authenticated session and attempts to fetch user stats from:

  • GET /api/v1/stats/

3. Terminal-Friendly Output

When data is available, the command is designed to render:

  • total uploads
  • uploads by media type
  • uploads by language
  • points
  • leaderboard position/rank
  • activity summary (if date-wise/heatmap-style data is returned)

4. Resilient Handling

The implementation handles:

  • unauthenticated access
  • request/API failures
  • empty responses
  • partial responses with missing optional keys

5. Documentation Update

README.md is updated to include:

  • stats command in the available commands list
  • usage example
  • brief explanation of displayed metrics

Acceptance Criteria Mapping

    •  Reuse existing authenticated session/token
    • Add a new stats command to CLI
    •  Fetch from GET /api/v1/stats/
    •  Support rendering for total uploads, by type, by language, points, leaderboard position (when provided by API)
    •  Include activity summary when API provides relevant fields
    •  Handle empty/partial responses safely
    •  Show friendly error messaging for unauthenticated/failed API calls
    •  Document command and usage in README.md

Testing / Validation (April 7, 2026)

Local CLI Validation

  • uv sync -> success
  • uv run corpus-client --help -> stats command appears
  • uv run corpus-client logout + uv run corpus-client stats -> friendly unauthenticated message displayed

Runtime API Validation (Authenticated)

Using active token against https://dev.api.corpus.swecha.org:

  • GET /api/v1/auth/me -> 200 OK
  • GET /api/v1/stats/ -> 404 Not Found
  • GET /api/v1/contributions/ -> 404 Not Found

Current Status / Blocker

CLI-side implementation is complete and command behavior is validated for registration and auth handling.

End-to-end statistics retrieval is currently blocked because stats-related routes are not exposed in the dev API environment (404 Not Found).

image.png

Requested Follow-up

Please confirm and expose the intended statistics endpoint for dev (roadmap indicates GET /api/v1/stats/), or provide the correct replacement endpoint so CLI integration can be aligned and fully validated.

Scope Notes

This MR covers baseline stats command support.

Potential follow-up enhancements (not part of this MR):

  • stats --by-language
  • stats --by-type
  • stats --heatmap
  • stats --json

Related Issue

Closes #19 (closed)

Edited by SandhyaRani Bandaram

Merge request reports