AgentHub/server/routes/analytics.js

/**
 * @file Express router for analytics endpoints, providing aggregated statistics on token usage, tool usage, daily events/sessions, agent types, and more, narrowed by data scope, AI tool and an optional `from`/`to` date range. `computeAnalytics` is the same bundle for scheduled reports.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const { Router } = require("express");
const { stmts, db } = require("../db");
const {
  parseScope,
  parseTool,
  BAD_TOOL,
  parseRange,
  inRange,
  BAD_RANGE,
} = require("../lib/source-filter");
const scoped = require("../lib/scoped-stats");

const { calculateCost, dailyTokenRows, costWhere } = require("./pricing");

const router = Router();

// Every session, for the scoped path when only a date range narrows.
const ALL = { where: "1=1", params: [] };
const USAGE_TOKEN_COLS = {
  total_input: "input_tokens",
  total_output: "output_tokens",
  total_cache_read: "cache_read_tokens",
  total_cache_write: "cache_write_tokens",
};

/**
 * The analytics bundle for a data scope (`parseScope`'s predicate or null) and
 * a date range (`parseRange`'s result or null). Also used by scheduled reports.
 * With a range, counts follow it and tokens/cost come from the cost rows of the
 * days in it (`token_usage` has no date); the daily charts keep 365 days.
 */
function computeAnalytics({ scope = null, range = null, tzModifier = "+0 minutes" } = {}) {
  const sc = scope || (range ? ALL : null);
  const toolUsage = sc ? scoped.toolUsageCounts(db, sc, range) : stmts.toolUsageCounts.all();
  const dailyEvents = sc
    ? scoped.dailyEventCounts(db, sc, tzModifier)
    : stmts.dailyEventCounts.all(tzModifier);
  const dailySessions = sc
    ? scoped.dailySessionCounts(db, sc, tzModifier)
    : stmts.dailySessionCounts.all(tzModifier);
  const agentTypes = sc
    ? scoped.agentTypeDistribution(db, sc, range)
    : stmts.agentTypeDistribution.all();
  const overview = sc ? scoped.statsOverview(db, sc, range) : stmts.stats.get();
  const agentsByStatus = sc
    ? scoped.agentStatusCounts(db, sc, range)
    : stmts.agentStatusCounts.all();
  const sessionsByStatus = sc
    ? scoped.sessionStatusCounts(db, sc, range)
    : stmts.sessionStatusCounts.all();
  const totalSubagents = sc
    ? scoped.totalSubagentCount(db, sc, range)
    : stmts.totalSubagentCount.get();
  const eventTypes = sc ? scoped.eventTypeCounts(db, sc, range) : stmts.eventTypeCounts.all();
  const avgEvents = sc
    ? scoped.avgEventsPerSession(db, sc, range)
    : stmts.avgEventsPerSession.get();

  // Total cost exactly as GET /api/pricing/cost computes it (baselines, the
  // per-day rate, the same scope and range), so the two numbers always agree.
  // A session that started after the range cannot have spent in it.
  const extra = range?.end ? [{ clause: "s.started_at < ?", params: [range.end] }] : [];
  const where = costWhere({ scope, extra });
  const rows = dailyTokenRows(tzModifier, where.whereClause, where.params).filter((r) =>
    inRange(range, r.date)
  );
  const totalCost = calculateCost(rows, stmts.listPricing.all()).total_cost;
  let tokens;
  if (range) {
    tokens = {};
    for (const [k, c] of Object.entries(USAGE_TOKEN_COLS)) {
      tokens[k] = Math.round(rows.reduce((n, r) => n + r[c], 0));
    }
  } else {
    const t = scope ? scoped.tokenTotals(db, scope) : stmts.getTokenTotals.get();
    tokens = Object.fromEntries(Object.keys(USAGE_TOKEN_COLS).map((k) => [k, t?.[k] ?? 0]));
  }

  return {
    tokens,
    total_cost: totalCost,
    tool_usage: toolUsage,
    daily_events: dailyEvents,
    daily_sessions: dailySessions,
    agent_types: agentTypes,
    event_types: eventTypes,
    avg_events_per_session: avgEvents?.avg ?? 0,
    total_subagents: totalSubagents?.count ?? 0,
    overview,
    agents_by_status: Object.fromEntries(agentsByStatus.map((r) => [r.status, r.count])),
    sessions_by_status: Object.fromEntries(sessionsByStatus.map((r) => [r.status, r.count])),
  };
}

router.get("/", (req, res) => {
  // Client sends tz_offset (minutes from getTimezoneOffset(), e.g. 420 for PDT)
  // Negate it to get the SQLite modifier: 420 → '-420 minutes'
  const rawOffset = parseInt(req.query.tz_offset, 10);
  const tzModifier = Number.isFinite(rawOffset) ? `${-rawOffset} minutes` : "+0 minutes";

  // Data-scope: restrict every metric to a subset of source machines and/or one
  // AI tool when the user has chosen one, and to `?from=&to=` (local dates).
  if (parseTool(req) === false) return res.status(400).json(BAD_TOOL);
  const range = parseRange(req);
  if (range === false) return res.status(400).json(BAD_RANGE);
  res.json(computeAnalytics({ scope: parseScope(req), range, tzModifier }));
});

module.exports = router;
module.exports.computeAnalytics = computeAnalytics;