feat: add GET /v1/usage/me endpoint for user-facing usage stats

src/__tests__/usage-me.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import request from "supertest";
+
+import { isProKey, isValidKey, getKeyInfo } from "../services/keys.js";
+import { getUsageForKey } from "../middleware/usage.js";
+import { app } from "../index.js";
+
+describe("GET /v1/usage/me", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns 401 without auth", async () => {
+    const res = await request(app).get("/v1/usage/me");
+    expect(res.status).toBe(401);
+  });
+
+  it("returns usage for authenticated Pro key", async () => {
+    vi.mocked(isProKey).mockReturnValue(true);
+    vi.mocked(isValidKey).mockReturnValue(true);
+    vi.mocked(getKeyInfo).mockReturnValue({
+      key: "test-key", tier: "pro", email: "test@docfast.dev", createdAt: new Date().toISOString(),
+    } as any);
+    vi.mocked(getUsageForKey).mockReturnValue({ count: 142, monthKey: "2026-03" });
+
+    const res = await request(app)
+      .get("/v1/usage/me")
+      .set("X-API-Key", "test-key");
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      used: 142,
+      limit: 5000,
+      plan: "pro",
+      month: "2026-03",
+    });
+  });
+
+  it("returns count 0 for authenticated key with no usage this month", async () => {
+    vi.mocked(isProKey).mockReturnValue(true);
+    vi.mocked(isValidKey).mockReturnValue(true);
+    vi.mocked(getKeyInfo).mockReturnValue({
+      key: "test-key", tier: "pro", email: "test@docfast.dev", createdAt: new Date().toISOString(),
+    } as any);
+    vi.mocked(getUsageForKey).mockReturnValue({ count: 0, monthKey: "2026-03" });
+
+    const res = await request(app)
+      .get("/v1/usage/me")
+      .set("X-API-Key", "test-key");
+
+    expect(res.status).toBe(200);
+    expect(res.body.used).toBe(0);
+    expect(res.body.limit).toBe(5000);
+    expect(res.body.plan).toBe("pro");
+  });
+
+  it("returns correct month string", async () => {
+    vi.mocked(isValidKey).mockReturnValue(true);
+    vi.mocked(isProKey).mockReturnValue(true);
+    vi.mocked(getKeyInfo).mockReturnValue({
+      key: "test-key", tier: "pro", email: "test@docfast.dev", createdAt: new Date().toISOString(),
+    } as any);
+    vi.mocked(getUsageForKey).mockReturnValue({ count: 5, monthKey: "2026-03" });
+
+    const res = await request(app)
+      .get("/v1/usage/me")
+      .set("X-API-Key", "test-key");
+
+    expect(res.body.month).toBe("2026-03");
+  });
+
+  it("returns demo plan for non-pro keys", async () => {
+    vi.mocked(isProKey).mockReturnValue(false);
+    vi.mocked(isValidKey).mockReturnValue(true);
+    vi.mocked(getKeyInfo).mockReturnValue({
+      key: "test-key", tier: "free", email: "test@docfast.dev", createdAt: new Date().toISOString(),
+    } as any);
+    vi.mocked(getUsageForKey).mockReturnValue({ count: 50, monthKey: "2026-03" });
+
+    const res = await request(app)
+      .get("/v1/usage/me")
+      .set("X-API-Key", "test-key");
+
+    expect(res.status).toBe(200);
+    expect(res.body.plan).toBe("demo");
+    expect(res.body.limit).toBe(100);
+    expect(res.body.used).toBe(50);
+  });
+});