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.
TypeScript ai-agentai-resume-analyzerapplication-trackerapplication-tracking-systematscareerjob-applicationjob-automationjob-huntingjob-searchjob-seeker-toolsjob-trackerjob-trackingjobsearchjobseekersmcpollamaresumeresume-reviewself-hosted
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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,+ };+}