Feature/api key usage analytics and coverage (#734)

* feat: add per-key API usage analytics

Adds a new /api/api-keys/[id]/usage route, mock usage generator, client
hook, and a /dashboard/api-keys/[id]/usage page rendering per-key request
totals and a 14-day volume chart. Follows the existing production-safety
rule: proxies to the configured mux-backend when NEXT_PUBLIC_API_URL is
set, and returns 503 instead of mock data in production when no backend
is configured. Closes the "Per-key usage analytics" roadmap item.

* test: add extended coverage config for recovery, login, transactions-table, middleware

vitest.config.ts's coverage.include omits /recovery, /login,
/transactions-table, src/middleware.ts, and most src/app/api/** routes,
even though tests already exist for all of them — so regressions there
don't show up as a coverage drop. Adds a standalone
vitest.coverage.full.config.ts (kept separate rather than editing the
default config) that extends coverage to include those paths, plus
docs/vitest-coverage-expansion.md documenting the gap and how to run it.

---------

Co-authored-by: josunday002 <josunday002@users.noreply.github.com>

Author: josunday002

docs/api-key-usage-analytics.md

@@ -0,0 +1,46 @@
+# Per-key API usage analytics
+
+Implements the "Per-key usage analytics" roadmap item from `README.md`.
+
+## What this adds
+
+* `GET /api/api-keys/[id]/usage` — proxies to `${NEXT_PUBLIC_API_URL}/api-keys/:id/usage`
+  (or its legacy aliases) when a backend is configured. Returns `503
+  backend_unavailable` instead of mock data when no backend is configured in
+  a production build (`NODE_ENV=production`), matching the "no silent mock
+  success in production" rule documented in the root `README.md` and
+  enforced by `isMockFallbackAllowed()` in `src/lib/api/config.ts`.
+* `src/mock-data/api-key-usage.ts` — dev/CI-only mock usage generator, used
+  only as a fallback outside production when no backend is configured.
+* `src/hooks/useApiKeyUsage.ts` — client hook with the same
+  loading/error/refetch shape as `useApiKeys`/`useWallets`.
+* `src/components/dashboard/ApiKeyUsageAnalytics.tsx` — renders total
+  requests, requests in the last 24h, last-used timestamp, and a 14-day
+  request volume chart for one API key.
+* `src/app/dashboard/api-keys/[id]/usage/page.tsx` — a new page at
+  `/dashboard/api-keys/<id>/usage` that renders the analytics for a given
+  key id (protected by the existing `/dashboard` auth middleware).
+
+## Data source
+
+Same rule as the rest of the app: when `NEXT_PUBLIC_API_URL` (or a legacy
+alias) is set, usage data comes from the real mux-backend
+(`GET {backend}/api-keys/:id/usage`) via server-side credentials
+(`MUX_API_KEY`/`MUX_API_SECRET`, attached server-side only — never exposed
+to the browser). No client-visible Mux credential is introduced by this
+feature, and no data is written to `localStorage`.
+
+## Backend contract expected
+
+`GET {backend}/api-keys/:id/usage` should return a JSON body shaped like
+`ApiKeyUsageSummary` in `src/mock-data/api-key-usage.ts`:
+
+```ts
+{
+  apiKeyId: string;
+  totalRequests: number;
+  requestsLast24h: number;
+  lastUsedAt: string | null; // ISO timestamp
+  dailyRequests: { date: string; requests: number }[]; // last 14 days, oldest first
+}
+```

docs/vitest-coverage-expansion.md

@@ -0,0 +1,57 @@
+# Vitest coverage expansion (recovery, login, transactions-table, middleware)
+
+## Gap
+
+`vitest.config.ts`'s `coverage.include` list only covers a subset of the app:
+
+```
+src/components/wallet/**
+src/components/analytics/**
+src/components/ui/**
+src/components/transactions/**
+src/lib/**
+src/utils/**
+src/hooks/**
+src/mock-data/**
+src/services/**
+src/app/**/wallets/**
+src/app/**/analytics/**
+```
+
+It omits `/recovery`, `/login`, `/transactions-table`, `src/middleware.ts`,
+and most of `src/app/api/**`. Tests already exist for all of these areas —
+see:
+
+* `src/app/recovery/__tests__/page.test.tsx`
+* `src/app/login/__tests__/*.test.tsx`
+* `src/app/transactions-table/page.test.tsx`
+* `src/test/middleware.test.ts`, `src/__tests__/middleware.test.ts`
+* `src/app/api/**/*.test.ts` (every route under `src/app/api` has a
+  matching `route.test.ts`)
+
+— they just aren't reflected in the coverage report, so a regression in
+any of these areas wouldn't show up as a coverage drop and could go
+unnoticed.
+
+## Fix
+
+`vitest.coverage.full.config.ts` (repo root) is an additive, standalone
+Vitest config — kept separate from `vitest.config.ts` rather than editing
+it in place — that extends the same coverage setup with:
+
+```
+src/app/recovery/**
+src/app/login/**
+src/app/transactions-table/**
+src/middleware.ts
+src/app/api/**
+```
+
+Run it with:
+
+```bash
+pnpm exec vitest run --config vitest.coverage.full.config.ts --coverage
+```
+
+This uses the same test files, setup, and alias resolution as
+`vitest.config.ts` — only the reported coverage surface is wider.

src/app/api/api-keys/[id]/usage/route.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { GET } from "@/app/api/api-keys/[id]/usage/route";
+
+function paramsFor(id: string) {
+	return { params: { id } };
+}
+
+describe("GET /api/api-keys/[id]/usage", () => {
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it("returns deterministic mock usage analytics for a key", async () => {
+		const res = await GET(
+			new Request("http://localhost/api/api-keys/1/usage"),
+			paramsFor("1"),
+		);
+		const json = await res.json();
+
+		expect(res.status).toBe(200);
+		expect(json.data).toEqual(
+			expect.objectContaining({
+				apiKeyId: "1",
+				totalRequests: expect.any(Number),
+				requestsLast24h: expect.any(Number),
+				dailyRequests: expect.any(Array),
+			}),
+		);
+		expect(json.data.dailyRequests).toHaveLength(14);
+	});
+
+	it("returns the same totals for the same key id (stable mock data)", async () => {
+		const first = await GET(
+			new Request("http://localhost/api/api-keys/2/usage"),
+			paramsFor("2"),
+		);
+		const second = await GET(
+			new Request("http://localhost/api/api-keys/2/usage"),
+			paramsFor("2"),
+		);
+
+		const firstJson = await first.json();
+		const secondJson = await second.json();
+
+		expect(firstJson.data.dailyRequests).toEqual(secondJson.data.dailyRequests);
+	});
+
+	it("rejects a blank id", async () => {
+		const res = await GET(
+			new Request("http://localhost/api/api-keys/%20/usage"),
+			paramsFor("  "),
+		);
+		expect(res.status).toBe(400);
+	});
+
+	it("returns 503 instead of mock data when no backend is configured in production", async () => {
+		vi.stubEnv("NODE_ENV", "production");
+
+		const res = await GET(
+			new Request("http://localhost/api/api-keys/1/usage"),
+			paramsFor("1"),
+		);
+		const json = await res.json();
+
+		expect(res.status).toBe(503);
+		expect(json.error).toBe("backend_unavailable");
+	});
+});

src/app/api/api-keys/[id]/usage/route.ts

@@ -0,0 +1,91 @@
+import { NextResponse } from "next/server";
+import {
+	getApiBaseUrl,
+	getUpstreamAuthHeaders,
+	isMockFallbackAllowed,
+} from "@/lib/api/config";
+import { getApiKeyUsage } from "@/mock-data/api-key-usage";
+
+/** 503 returned instead of mock data when no backend is configured in production. */
+function backendUnavailableResponse() {
+	return NextResponse.json(
+		{
+			error: "backend_unavailable",
+			message:
+				"No API key usage backend is configured for this production deployment. Set NEXT_PUBLIC_API_URL.",
+		},
+		{ status: 503 },
+	);
+}
+
+type RouteContext = {
+	params:
+		| {
+				id: string;
+		  }
+		| Promise<{
+				id: string;
+		  }>;
+};
+
+function backendHeaders(): Record<string, string> {
+	return {
+		"content-type": "application/json",
+		...getUpstreamAuthHeaders(),
+	};
+}
+
+/**
+ * GET /api/api-keys/[id]/usage
+ *
+ * Per-key usage analytics (roadmap item: "Per-key usage analytics").
+ * Proxies to the configured backend's real usage metrics
+ * (NEXT_PUBLIC_API_URL or legacy aliases). Falls back to the local mock
+ * generator only outside production and only when no backend is configured,
+ * so local dev/CI keeps working without a running API server — mirrors the
+ * production-safety rule used by `/api/api-keys` and `/api/wallets/[id]`.
+ */
+export async function GET(request: Request, { params }: RouteContext) {
+	const { id } = await params;
+	const apiKeyId = id.trim();
+
+	if (!apiKeyId) {
+		return NextResponse.json({ error: "invalid_id" }, { status: 400 });
+	}
+
+	const backendUrl = getApiBaseUrl();
+
+	if (backendUrl) {
+		try {
+			const upstream = await fetch(
+				`${backendUrl}/api-keys/${encodeURIComponent(apiKeyId)}/usage`,
+				{
+					headers: backendHeaders(),
+					cache: "no-store",
+				},
+			);
+			const data = await upstream.json().catch(() => null);
+
+			if (!upstream.ok || data === null) {
+				return NextResponse.json(
+					{ error: "Unable to load API key usage from the backend" },
+					{ status: upstream.status || 502 },
+				);
+			}
+
+			return NextResponse.json({ data });
+		} catch {
+			return NextResponse.json(
+				{ error: "Unable to reach the API key usage backend" },
+				{ status: 502 },
+			);
+		}
+	}
+
+	if (!isMockFallbackAllowed()) {
+		return backendUnavailableResponse();
+	}
+
+	// --- Mock fallback (no NEXT_PUBLIC_API_URL set, non-production only) ---
+	return NextResponse.json({ data: getApiKeyUsage(apiKeyId) });
+}

src/app/dashboard/api-keys/[id]/usage/page.tsx

@@ -0,0 +1,29 @@
+import Link from "next/link";
+import { ApiKeyUsageAnalytics } from "@/components/dashboard/ApiKeyUsageAnalytics";
+import { PageHeader } from "@/components/ui/PageHeader";
+
+export default async function ApiKeyUsagePage({
+	params,
+}: {
+	params: Promise<{ id: string }>;
+}) {
+	const { id } = await params;
+
+	return (
+		<div className="space-y-6">
+			<PageHeader
+				title="API Key Usage"
+				description="Per-key request volume and activity"
+				actions={
+					<Link
+						href="/dashboard/api-keys"
+						className="text-sm font-medium text-blue-700 hover:underline dark:text-blue-400"
+					>
+						← Back to API keys
+					</Link>
+				}
+			/>
+			<ApiKeyUsageAnalytics apiKeyId={id} />
+		</div>
+	);
+}

src/components/dashboard/ApiKeyUsageAnalytics.test.tsx

@@ -0,0 +1,62 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ApiKeyUsageAnalytics } from "@/components/dashboard/ApiKeyUsageAnalytics";
+import type { ApiKeyUsageSummary } from "@/mock-data/api-key-usage";
+
+const mockUsage: ApiKeyUsageSummary = {
+	apiKeyId: "1",
+	totalRequests: 1200,
+	requestsLast24h: 42,
+	lastUsedAt: "2024-01-20T00:00:00Z",
+	dailyRequests: [
+		{ date: "2024-01-19", requests: 10 },
+		{ date: "2024-01-20", requests: 42 },
+	],
+};
+
+afterEach(() => {
+	vi.restoreAllMocks();
+	vi.unstubAllGlobals();
+});
+
+describe("ApiKeyUsageAnalytics", () => {
+	it("shows a loading state before data resolves", () => {
+		vi.stubGlobal("fetch", vi.fn(() => new Promise(() => {})));
+
+		render(<ApiKeyUsageAnalytics apiKeyId="1" />);
+		expect(screen.getByRole("status", { name: /loading api key usage/i })).toBeInTheDocument();
+	});
+
+	it("renders usage totals once loaded", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue({
+				ok: true,
+				json: () => Promise.resolve({ data: mockUsage }),
+			}),
+		);
+
+		render(<ApiKeyUsageAnalytics apiKeyId="1" apiKeyName="Production" />);
+
+		await waitFor(() =>
+			expect(screen.getByText(/usage analytics/i)).toBeInTheDocument(),
+		);
+		expect(screen.getByText("1,200")).toBeInTheDocument();
+		expect(screen.getByText("42")).toBeInTheDocument();
+	});
+
+	it("renders an error state with a retry action on failure", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue({ ok: false, status: 502 }),
+		);
+
+		render(<ApiKeyUsageAnalytics apiKeyId="1" />);
+
+		await waitFor(() =>
+			expect(
+				screen.getByText(/unable to load usage analytics/i),
+			).toBeInTheDocument(),
+		);
+	});
+});