[Feature] Build Token Usage Analytics Endpoint for Operator Dashboards

[anshul23102]

Summary

TokenFirewall collects usage data but provides no way to query it. An analytics endpoint exposing time-series usage would let operators build dashboards or integrate with monitoring tools.

Problem Statement

Operators can enforce limits but cannot answer: "Which endpoint consumes the most tokens?", "What is the p95 token count per request?", or "How does today compare to last week?" These require queryable aggregated data.

Proposed Solution

Add GET /tokenfirewall/analytics mountable as Express middleware:

{
  "period": { "from": "2026-06-01T00:00:00Z", "to": "2026-06-28T23:59:59Z" },
  "totals": {
    "requests": 4821,
    "inputTokens": 2341000,
    "outputTokens": 891000,
    "estimatedCostUsd": 12.47
  },
  "byEndpoint": [
    { "path": "/api/chat", "requests": 3100, "inputTokens": 1800000 }
  ],
  "timeSeries": {
    "resolution": "1h",
    "data": [
      { "timestamp": "2026-06-28T00:00:00Z", "inputTokens": 45000, "requests": 89 }
    ]
  }
}

Query parameters: from, to (ISO timestamps), resolution (1h, 1d, 1w), groupBy (endpoint, model, userId).

The endpoint is protected by an adminSecret header. Aggregation is backed by bucketed counters in the storage adapter (one bucket per hour, incremented atomically on each request).

Acceptance Criteria

• The analytics endpoint requires a correct adminSecret header.
• Time-series data matches the sum of per-bucket counters for the requested range.
• groupBy=userId requires userBudget to be configured; returns 400 otherwise.
• Response time is under 200 ms for a 30-day query with 1-hour resolution.
• Unit tests cover: correct aggregation, empty range, authorization failure.