Skip to content

Job application tracker and AI-powered job search assistant. Helps job seekers manage their search journey with AI resume review, job matching, task logging, and application analytics, all while keeping your data private.

feat(ai-usage): add getAiUsage with calendar-day buckets in the viewer's timezone, per-provider/model/feature totals, completed-call percentiles, near-context counts and the last 50 calls

Khuram Niaz850507263b55
diff --git a/__tests__/aiUsage.actions.spec.ts b/__tests__/aiUsage.actions.spec.ts
new file mode 100644
index 0000000..308b24f
--- /dev/null
+++ b/__tests__/aiUsage.actions.spec.ts
@@ -0,0 +1,61 @@
+import { getAiUsage } from "@/actions/aiUsage.actions";
+import prisma from "@/lib/db";
+import { requireUser } from "@/actions/shared";
+
+vi.mock("@/lib/db", () => ({
+ default: { aiCall: { findMany: vi.fn(), count: vi.fn() } },
+}));
+vi.mock("@/actions/shared", () => ({ requireUser: vi.fn() }));
+
+const db = prisma as any;
+const since = new Date("2026-09-22T04:00:00Z");
+
+describe("getAiUsage", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-09-28T12:00:00Z"));
+ (requireUser as any).mockResolvedValue({ id: "user-1" });
+ db.aiCall.findMany.mockResolvedValue([]);
+ db.aiCall.count.mockResolvedValue(3);
+ });
+ afterEach(() => vi.useRealTimers());
+
+ it("scopes every query to the user", async () => {
+ await getAiUsage({ rangeDays: 7, since, timeZone: "America/Toronto" });
+ for (const [arg] of [...db.aiCall.findMany.mock.calls, ...db.aiCall.count.mock.calls]) {
+ expect(arg.where.userId).toBe("user-1");
+ }
+ });
+
+ it("counts the previous period immediately before since", async () => {
+ const res = await getAiUsage({ rangeDays: 7, since, timeZone: "America/Toronto" });
+ expect(db.aiCall.count).toHaveBeenCalledWith({
+ where: { userId: "user-1", startedAt: { gte: new Date("2026-09-15T04:00:00Z"), lt: since } },
+ });
+ expect(res.success && res.data.totals.previousCalls).toBe(3);
+ });
+
+ it("reads the last 50 within retention for Recent calls", async () => {
+ await getAiUsage({ rangeDays: 30, since, timeZone: "UTC" });
+ const recentCall = db.aiCall.findMany.mock.calls.find(([a]: any) => a.take === 50);
+ expect(recentCall[0].orderBy).toEqual({ startedAt: "desc" });
+ expect(recentCall[0].where.startedAt.gte).toEqual(new Date("2026-06-30T12:00:00Z"));
+ });
+
+ it("rejects a range other than 7 or 30 and an unknown timezone falls back to UTC", async () => {
+ expect((await getAiUsage({ rangeDays: 90 as any, since, timeZone: "UTC" })).success).toBe(false);
+ expect((await getAiUsage({ rangeDays: 7, since, timeZone: "Not/AZone" })).success).toBe(true);
+ });
+
+ it("clamps a since further back than the range allows", async () => {
+ await getAiUsage({ rangeDays: 7, since: new Date("2020-01-01T00:00:00Z"), timeZone: "UTC" });
+ const rangeCall = db.aiCall.findMany.mock.calls.find(([a]: any) => a.take === undefined);
+ expect(rangeCall[0].where.startedAt.gte.getTime()).toBeGreaterThan(new Date("2026-09-20T00:00:00Z").getTime());
+ });
+
+ it("returns the not-authenticated failure", async () => {
+ (requireUser as any).mockRejectedValue(new Error("Not authenticated"));
+ expect(await getAiUsage({ rangeDays: 7, since, timeZone: "UTC" })).toEqual({ success: false, message: "Not authenticated" });
+ });
+});
diff --git a/__tests__/aiUsageSummarize.spec.ts b/__tests__/aiUsageSummarize.spec.ts
new file mode 100644
index 0000000..11768ae
--- /dev/null
+++ b/__tests__/aiUsageSummarize.spec.ts
@@ -0,0 +1,106 @@
+import {
+ dayKey,
+ percentile,
+ rangeDayKeys,
+ summarizeAiUsage,
+ type AiCallRecord,
+} from "@/lib/aiUsage/summarize";
+
+const row = (over: Partial<AiCallRecord> = {}): AiCallRecord => ({
+ startedAt: new Date("2026-09-27T15:00:00Z"),
+ feature: "agent_chat",
+ provider: "ollama",
+ model: "qwen3.5:9b",
+ status: "ok",
+ inputTokens: 1000,
+ outputTokens: 100,
+ durationMs: 5000,
+ firstTokenMs: 1000,
+ numCtx: 16384,
+ ...over,
+});
+
+const opts = {
+ rangeDays: 7 as const,
+ since: new Date("2026-09-22T04:00:00Z"), // Sep 22 00:00 in Toronto
+ timeZone: "America/Toronto",
+ previousCalls: 0,
+};
+
+describe("percentile", () => {
+ it("uses nearest rank", () => {
+ expect(percentile([5, 1, 3, 2, 4], 50)).toBe(3);
+ expect(percentile([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20], 95)).toBe(19);
+ });
+ it("is null for no values", () => {
+ expect(percentile([], 50)).toBeNull();
+ });
+});
+
+describe("days", () => {
+ it("buckets by the viewer's calendar day", () => {
+ expect(dayKey(new Date("2026-09-28T03:30:00Z"), "America/Toronto")).toBe("2026-09-27");
+ });
+
+ it("lists one key per day, oldest first, across a DST change", () => {
+ const keys = rangeDayKeys(new Date("2026-10-29T04:00:00Z"), 7, "America/Toronto");
+ expect(keys).toEqual(["2026-10-29", "2026-10-30", "2026-10-31", "2026-11-01", "2026-11-02", "2026-11-03", "2026-11-04"]);
+ });
+});
+
+describe("summarizeAiUsage", () => {
+ it("totals tokens, calls, failures and stopped", () => {
+ const s = summarizeAiUsage(
+ [
+ row(),
+ row({ status: "error", inputTokens: null, outputTokens: null, durationMs: 400, firstTokenMs: null }),
+ row({ status: "timed_out" }),
+ row({ status: "stopped" }),
+ ],
+ opts,
+ );
+ expect(s.totals).toMatchObject({ inputTokens: 3000, outputTokens: 300, calls: 4, failures: 2, stopped: 1 });
+ expect(s.failuresByStatus).toEqual({ error: 1, truncated: 0, interrupted: 0, timed_out: 1 });
+ });
+
+ it("computes response times over completed calls only", () => {
+ const s = summarizeAiUsage(
+ [row({ durationMs: 8000 }), row({ status: "truncated", durationMs: 60000 }), row({ status: "error", durationMs: 100 })],
+ opts,
+ );
+ expect(s.totals.medianMs).toBe(8000);
+ expect(s.totals.p95Ms).toBe(60000);
+ });
+
+ it("buckets daily tokens by provider in the viewer's timezone", () => {
+ const s = summarizeAiUsage(
+ [row({ startedAt: new Date("2026-09-28T03:30:00Z") }), row({ provider: "deepseek", numCtx: null })],
+ opts,
+ );
+ const sep27 = s.days.find((d) => d.date === "2026-09-27")!;
+ expect(sep27.tokensByProvider).toEqual({ ollama: 1100, deepseek: 1100 });
+ expect(s.days).toHaveLength(7);
+ });
+
+ it("groups providers and models, largest first, and flags near-limit Ollama calls", () => {
+ const s = summarizeAiUsage(
+ [
+ row({ inputTokens: 15000 }), // 15000 >= 0.9 * 16384
+ row(),
+ row({ provider: "deepseek", model: "deepseek-chat", numCtx: null, inputTokens: 50 }),
+ ],
+ opts,
+ );
+ expect(s.providers.map((p) => p.provider)).toEqual(["ollama", "deepseek"]);
+ expect(s.providers[0].models[0]).toMatchObject({ model: "qwen3.5:9b", calls: 2, nearContextLimit: 1 });
+ });
+
+ it("orders features by tokens and omits unused ones", () => {
+ const s = summarizeAiUsage([row({ feature: "automations", inputTokens: 5000 }), row()], opts);
+ expect(s.features.map((f) => f.feature)).toEqual(["automations", "agent_chat"]);
+ });
+
+ it("passes the previous period's count through", () => {
+ expect(summarizeAiUsage([], { ...opts, previousCalls: 12 }).totals.previousCalls).toBe(12);
+ });
+});
diff --git a/src/actions/aiUsage.actions.ts b/src/actions/aiUsage.actions.ts
new file mode 100644
index 0000000..cb61886
--- /dev/null
+++ b/src/actions/aiUsage.actions.ts
@@ -0,0 +1,114 @@
+"use server";
+
+import db from "@/lib/db";
+import { requireUser } from "./shared";
+import { handleError } from "@/lib/utils";
+import { AI_USAGE_CONSTANTS } from "@/lib/constants";
+import { aiUsageCutoff } from "@/lib/aiUsage/prune";
+import { summarizeAiUsage } from "@/lib/aiUsage/summarize";
+import type {
+ AiCallRow,
+ AiCallStatus,
+ AiUsageFeature,
+ AiUsageRange,
+ AiUsageSummary,
+} from "@/models/aiUsage.model";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function validTimeZone(timeZone: string): string {
+ try {
+ new Intl.DateTimeFormat("en-CA", { timeZone });
+ return timeZone;
+ } catch {
+ return "UTC";
+ }
+}
+
+// since is the viewer's local midnight rangeDays - 1 days ago, computed on the
+// client because only the client knows its calendar.
+export async function getAiUsage(input: {
+ rangeDays: AiUsageRange;
+ since: Date;
+ timeZone: string;
+}): Promise<
+ | { success: true; data: AiUsageSummary }
+ | { success: false; message: string }
+> {
+ try {
+ const user = await requireUser();
+ if (input.rangeDays !== 7 && input.rangeDays !== 30) {
+ return { success: false, message: "Invalid range" };
+ }
+ const now = new Date();
+ const timeZone = validTimeZone(input.timeZone);
+ // A day of slack covers the viewer's offset from UTC.
+ const earliest = new Date(now.getTime() - (input.rangeDays + 1) * DAY_MS);
+ const since = new Date(
+ Math.max(new Date(input.since).getTime(), earliest.getTime()),
+ );
+ const previousSince = new Date(since.getTime() - input.rangeDays * DAY_MS);
+
+ const [rows, previousCalls, recent] = await Promise.all([
+ db.aiCall.findMany({
+ where: { userId: user.id, startedAt: { gte: since } },
+ select: {
+ startedAt: true,
+ feature: true,
+ provider: true,
+ model: true,
+ status: true,
+ inputTokens: true,
+ outputTokens: true,
+ durationMs: true,
+ firstTokenMs: true,
+ numCtx: true,
+ },
+ }),
+ db.aiCall.count({
+ where: {
+ userId: user.id,
+ startedAt: { gte: previousSince, lt: since },
+ },
+ }),
+ db.aiCall.findMany({
+ where: { userId: user.id, startedAt: { gte: aiUsageCutoff(now) } },
+ orderBy: { startedAt: "desc" },
+ take: AI_USAGE_CONSTANTS.RECENT_LIMIT,
+ select: {
+ id: true,
+ startedAt: true,
+ feature: true,
+ provider: true,
+ model: true,
+ status: true,
+ inputTokens: true,
+ outputTokens: true,
+ durationMs: true,
+ firstTokenMs: true,
+ },
+ }),
+ ]);
+
+ return {
+ success: true,
+ data: {
+ ...summarizeAiUsage(rows, {
+ rangeDays: input.rangeDays,
+ since,
+ timeZone,
+ previousCalls,
+ }),
+ recent: recent.map((r) => ({
+ ...r,
+ feature: r.feature as AiUsageFeature,
+ status: r.status as AiCallStatus,
+ })) satisfies AiCallRow[],
+ },
+ };
+ } catch (error) {
+ // handleError types success as boolean; re-wrap to keep the union narrow.
+ const { message } = handleError(error, "Failed to load AI usage.");
+ return { success: false, message };
+ }
+}
diff --git a/src/lib/aiUsage/summarize.ts b/src/lib/aiUsage/summarize.ts
new file mode 100644
index 0000000..8d7bc23
--- /dev/null
+++ b/src/lib/aiUsage/summarize.ts
@@ -0,0 +1,164 @@
+import { AI_USAGE_CONSTANTS } from "@/lib/constants";
+import {
+ AI_FAILURE_STATUSES,
+ type AiFailureStatus,
+ type AiModelUsage,
+ type AiUsageFeature,
+ type AiUsageRange,
+ type AiUsageSummary,
+} from "@/models/aiUsage.model";
+
+export type AiCallRecord = {
+ startedAt: Date;
+ feature: string;
+ provider: string;
+ model: string;
+ status: string;
+ inputTokens: number | null;
+ outputTokens: number | null;
+ durationMs: number;
+ firstTokenMs: number | null;
+ numCtx: number | null;
+};
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+// Nearest rank, in JS: SQLite has no percentile function.
+export function percentile(values: number[], p: number): number | null {
+ if (values.length === 0) return null;
+ const sorted = [...values].sort((a, b) => a - b);
+ const rank = Math.ceil((p / 100) * sorted.length);
+ return sorted[Math.min(sorted.length, Math.max(1, rank)) - 1];
+}
+
+export function dayKey(date: Date, timeZone: string): string {
+ // en-CA formats as YYYY-MM-DD.
+ return new Intl.DateTimeFormat("en-CA", {
+ timeZone,
+ year: "numeric",
+ month: "2-digit",
+ day: "2-digit",
+ }).format(date);
+}
+
+export function rangeDayKeys(
+ since: Date,
+ rangeDays: number,
+ timeZone: string,
+): string[] {
+ // Noon offsets keep a 23h or 25h DST day from skipping or repeating a key.
+ return Array.from({ length: rangeDays }, (_, i) =>
+ dayKey(new Date(since.getTime() + i * DAY_MS + DAY_MS / 2), timeZone),
+ );
+}
+
+const tokensOf = (r: AiCallRecord) =>
+ (r.inputTokens ?? 0) + (r.outputTokens ?? 0);
+
+// Completed calls only, so an instant connection error can't drag a median.
+const isCompleted = (r: AiCallRecord) =>
+ r.status === "ok" || r.status === "truncated";
+
+function timings(rows: AiCallRecord[]) {
+ const done = rows.filter(isCompleted);
+ const durations = done.map((r) => r.durationMs);
+ const firstTokens = done.flatMap((r) =>
+ r.firstTokenMs === null ? [] : [r.firstTokenMs],
+ );
+ return {
+ medianMs: percentile(durations, 50),
+ p95Ms: percentile(durations, 95),
+ medianFirstTokenMs: percentile(firstTokens, 50),
+ };
+}
+
+function groupBy<T>(rows: T[], key: (row: T) => string): Map<string, T[]> {
+ const groups = new Map<string, T[]>();
+ for (const row of rows) {
+ const k = key(row);
+ groups.set(k, [...(groups.get(k) ?? []), row]);
+ }
+ return groups;
+}
+
+const sumTokens = (rows: AiCallRecord[]) =>
+ rows.reduce((n, r) => n + tokensOf(r), 0);
+
+export function summarizeAiUsage(
+ rows: AiCallRecord[],
+ opts: {
+ rangeDays: AiUsageRange;
+ since: Date;
+ timeZone: string;
+ previousCalls: number;
+ },
+): Omit<AiUsageSummary, "recent"> {
+ const failuresByStatus = Object.fromEntries(
+ AI_FAILURE_STATUSES.map((s) => [
+ s,
+ rows.filter((r) => r.status === s).length,
+ ]),
+ ) as Record<AiFailureStatus, number>;
+
+ const days = rangeDayKeys(opts.since, opts.rangeDays, opts.timeZone).map(
+ (date) => ({ date, tokensByProvider: {} as Record<string, number> }),
+ );
+ const dayIndex = new Map(days.map((d, i) => [d.date, i]));
+ for (const r of rows) {
+ const i = dayIndex.get(dayKey(r.startedAt, opts.timeZone));
+ if (i === undefined) continue;
+ const bucket = days[i].tokensByProvider;
+ bucket[r.provider] = (bucket[r.provider] ?? 0) + tokensOf(r);
+ }
+
+ const providers = [...groupBy(rows, (r) => r.provider)]
+ .map(([provider, providerRows]) => ({
+ provider,
+ tokens: sumTokens(providerRows),
+ calls: providerRows.length,
+ models: [...groupBy(providerRows, (r) => r.model)]
+ .map(
+ ([model, modelRows]): AiModelUsage => ({
+ model,
+ tokens: sumTokens(modelRows),
+ calls: modelRows.length,
+ ...timings(modelRows),
+ nearContextLimit: modelRows.filter(
+ (r) =>
+ r.numCtx !== null &&
+ r.inputTokens !== null &&
+ r.inputTokens >=
+ r.numCtx * AI_USAGE_CONSTANTS.CONTEXT_WARN_RATIO,
+ ).length,
+ }),
+ )
+ .sort((a, b) => b.tokens - a.tokens),
+ }))
+ .sort((a, b) => b.tokens - a.tokens);
+
+ const features = [...groupBy(rows, (r) => r.feature)]
+ .map(([feature, featureRows]) => ({
+ feature: feature as AiUsageFeature,
+ tokens: sumTokens(featureRows),
+ calls: featureRows.length,
+ medianMs: timings(featureRows).medianMs,
+ }))
+ .sort((a, b) => b.tokens - a.tokens);
+
+ return {
+ rangeDays: opts.rangeDays,
+ totals: {
+ inputTokens: rows.reduce((n, r) => n + (r.inputTokens ?? 0), 0),
+ outputTokens: rows.reduce((n, r) => n + (r.outputTokens ?? 0), 0),
+ calls: rows.length,
+ previousCalls: opts.previousCalls,
+ failures: Object.values(failuresByStatus).reduce((a, b) => a + b, 0),
+ stopped: rows.filter((r) => r.status === "stopped").length,
+ ...timings(rows),
+ },
+ failuresByStatus,
+ days,
+ providers,
+ features,
+ };
+}