From 5b59a7a01078ad1f296feb80a8feddd149e8e6a1 Mon Sep 17 00:00:00 2001 From: Hoid Date: Wed, 25 Feb 2026 14:06:07 +0000 Subject: [PATCH] feat: add usage dashboard (GET /v1/usage endpoint + usage.html page) --- public/index.html | 3 + public/usage.html | 146 +++++++++++++++++++++++++ src/docs/openapi.ts | 1 + src/index.ts | 5 +- src/routes/__tests__/usage.test.ts | 168 +++++++++++++++++++++++++++++ src/routes/usage.ts | 64 +++++++++++ 6 files changed, 386 insertions(+), 1 deletion(-) create mode 100644 public/usage.html create mode 100644 src/routes/__tests__/usage.test.ts create mode 100644 src/routes/usage.ts diff --git a/public/index.html b/public/index.html index 1f2f71e..05e8c11 100644 --- a/public/index.html +++ b/public/index.html @@ -243,6 +243,7 @@ footer{border-top:1px solid var(--border);padding:48px 24px 32px;background:var( Pricing API Docs Swagger + Usage Get API Key @@ -702,12 +703,14 @@ screenshot = snap.capture( Pricing Playground API Docs + Check Usage
Developers
Swagger / OpenAPI Quick Start Status + Usage Dashboard
Legal
diff --git a/public/usage.html b/public/usage.html new file mode 100644 index 0000000..4d27a1e --- /dev/null +++ b/public/usage.html @@ -0,0 +1,146 @@ + + + + + +Usage Dashboard — SnapAPI + + + + + + + + +
+

Usage Dashboard

+

Check your API usage for the current billing month.

+ + +
+ + +
+ + + +
+
+
+
Used / Limit
+
—
+
+
+
Plan
+
—
+
+
+ +
+
+ Monthly Usage + 0% +
+
+
+
+ +
+ ← Home + API Docs +
+
+
+ + + + + + diff --git a/src/docs/openapi.ts b/src/docs/openapi.ts index ca9884d..06cf1e5 100644 --- a/src/docs/openapi.ts +++ b/src/docs/openapi.ts @@ -34,6 +34,7 @@ const options: swaggerJsdoc.Options = { { name: "Playground", description: "Free demo (no auth, watermarked)" }, { name: "Signup", description: "Account creation" }, { name: "Billing", description: "Subscription and payment management" }, + { name: "Usage", description: "API usage tracking" }, { name: "System", description: "Health and status endpoints" }, ], components: { diff --git a/src/index.ts b/src/index.ts index 1ffb5cc..738ad30 100644 --- a/src/index.ts +++ b/src/index.ts @@ -17,6 +17,7 @@ import { initDatabase, pool } from "./services/db.js"; import { billingRouter } from "./routes/billing.js"; import { statusRouter } from "./routes/status.js"; import { signupRouter } from "./routes/signup.js"; +import { usageRouter } from "./routes/usage.js"; import { openapiSpec } from "./docs/openapi.js"; const app = express(); @@ -98,6 +99,7 @@ app.use("/v1/playground", playgroundRouter); app.use("/v1/signup", signupRouter); // Authenticated routes +app.use("/v1/usage", usageRouter); app.use("/v1/screenshot", authMiddleware, usageMiddleware, screenshotRouter); // API info @@ -108,6 +110,7 @@ app.get("/api", (_req, res) => { endpoints: [ "POST /v1/playground — Try the API (no auth, watermarked, 5 req/hr)", "POST /v1/screenshot — Take a screenshot (requires API key)", + "GET /v1/usage — Usage statistics (requires API key)", "GET /health — Health check", ], }); @@ -123,7 +126,7 @@ app.get("/docs", (_req, res) => { res.sendFile(path.join(__dirname, "../public/docs.html")); }); // Clean URLs for legal pages (redirect /privacy → /privacy.html, etc.) -for (const page of ["privacy", "terms", "impressum", "status"]) { +for (const page of ["privacy", "terms", "impressum", "status", "usage"]) { app.get(`/${page}`, (_req, res) => res.redirect(301, `/${page}.html`)); } diff --git a/src/routes/__tests__/usage.test.ts b/src/routes/__tests__/usage.test.ts new file mode 100644 index 0000000..0262539 --- /dev/null +++ b/src/routes/__tests__/usage.test.ts @@ -0,0 +1,168 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +// Mock dependencies before imports +vi.mock('../../services/keys.js', () => ({ + isValidKey: vi.fn(), + getKeyInfo: vi.fn(), + getTierLimit: vi.fn(), +})) + +vi.mock('../../middleware/usage.js', () => ({ + getUsageForKey: vi.fn(), +})) + +const { isValidKey, getKeyInfo, getTierLimit } = await import('../../services/keys.js') +const { getUsageForKey } = await import('../../middleware/usage.js') +const mockIsValidKey = vi.mocked(isValidKey) +const mockGetKeyInfo = vi.mocked(getKeyInfo) +const mockGetTierLimit = vi.mocked(getTierLimit) +const mockGetUsageForKey = vi.mocked(getUsageForKey) + +// Import after mocks +const { usageRouter } = await import('../usage.js') + +function createMockRequest(overrides: any = {}): any { + return { method: 'GET', headers: {}, query: {}, ...overrides } +} + +function createMockResponse(): any { + const res: any = { + status: vi.fn().mockReturnThis(), + json: vi.fn().mockReturnThis(), + } + return res +} + +function getHandler() { + return usageRouter.stack.find((layer: any) => + layer.route?.methods.get && layer.route.path === '/' + )?.route.stack +} + +describe('GET /v1/usage', () => { + beforeEach(() => { vi.clearAllMocks() }) + afterEach(() => { vi.restoreAllMocks() }) + + it('returns 401 without API key', async () => { + const req = createMockRequest() + const res = createMockResponse() + const stack = getHandler()! + // First handler is auth middleware + const authHandler = stack[0].handle + await authHandler(req, res, vi.fn()) + expect(res.status).toHaveBeenCalledWith(401) + }) + + it('returns usage data with valid key', async () => { + const now = new Date() + const monthKey = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}` + + mockIsValidKey.mockResolvedValue(true) + mockGetKeyInfo.mockResolvedValue({ + key: 'snap_test123', + tier: 'starter', + email: 'test@example.com', + createdAt: '2026-01-01T00:00:00Z', + }) + mockGetTierLimit.mockReturnValue(1000) + mockGetUsageForKey.mockReturnValue({ count: 42, monthKey }) + + const req = createMockRequest({ headers: { authorization: 'Bearer snap_test123' } }) + const res = createMockResponse() + + // Run through all handlers in the stack + const stack = getHandler()! + let idx = 0 + const runNext = async () => { + if (idx < stack.length) { + const handler = stack[idx++].handle + await handler(req, res, runNext) + } + } + await runNext() + + expect(res.json).toHaveBeenCalledWith({ + used: 42, + limit: 1000, + plan: 'starter', + month: monthKey, + remaining: 958, + percentUsed: 4.2, + }) + }) + + it('returns 0 usage for key with no records', async () => { + const now = new Date() + const monthKey = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}` + + mockIsValidKey.mockResolvedValue(true) + mockGetKeyInfo.mockResolvedValue({ + key: 'snap_newkey', + tier: 'free', + email: 'new@example.com', + createdAt: '2026-01-01T00:00:00Z', + }) + mockGetTierLimit.mockReturnValue(100) + mockGetUsageForKey.mockReturnValue(undefined) + + const req = createMockRequest({ headers: { authorization: 'Bearer snap_newkey' } }) + const res = createMockResponse() + + const stack = getHandler()! + let idx = 0 + const runNext = async () => { + if (idx < stack.length) { + const handler = stack[idx++].handle + await handler(req, res, runNext) + } + } + await runNext() + + expect(res.json).toHaveBeenCalledWith({ + used: 0, + limit: 100, + plan: 'free', + month: monthKey, + remaining: 100, + percentUsed: 0, + }) + }) + + it('includes all required fields', async () => { + const now = new Date() + const monthKey = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}` + + mockIsValidKey.mockResolvedValue(true) + mockGetKeyInfo.mockResolvedValue({ + key: 'snap_abc', + tier: 'pro', + email: 'pro@example.com', + createdAt: '2026-01-01T00:00:00Z', + }) + mockGetTierLimit.mockReturnValue(5000) + mockGetUsageForKey.mockReturnValue({ count: 2500, monthKey }) + + const req = createMockRequest({ headers: { authorization: 'Bearer snap_abc' } }) + const res = createMockResponse() + + const stack = getHandler()! + let idx = 0 + const runNext = async () => { + if (idx < stack.length) { + const handler = stack[idx++].handle + await handler(req, res, runNext) + } + } + await runNext() + + const data = res.json.mock.calls[0][0] + expect(data).toHaveProperty('used') + expect(data).toHaveProperty('limit') + expect(data).toHaveProperty('plan') + expect(data).toHaveProperty('month') + expect(data).toHaveProperty('remaining') + expect(data).toHaveProperty('percentUsed') + expect(typeof data.used).toBe('number') + expect(typeof data.percentUsed).toBe('number') + }) +}) diff --git a/src/routes/usage.ts b/src/routes/usage.ts new file mode 100644 index 0000000..5b7dfc7 --- /dev/null +++ b/src/routes/usage.ts @@ -0,0 +1,64 @@ +import { Router } from "express"; +import { authMiddleware } from "../middleware/auth.js"; +import { getUsageForKey } from "../middleware/usage.js"; +import { getTierLimit } from "../services/keys.js"; + +export const usageRouter = Router(); + +/** + * @openapi + * /v1/usage: + * get: + * tags: [Usage] + * summary: Get current usage for your API key + * description: Returns usage statistics for the authenticated API key in the current billing month. + * operationId: getUsage + * security: + * - BearerAuth: [] + * - ApiKeyAuth: [] + * - QueryKeyAuth: [] + * responses: + * 200: + * description: Usage statistics + * content: + * application/json: + * schema: + * type: object + * properties: + * used: + * type: integer + * description: Screenshots used this month + * limit: + * type: integer + * description: Monthly screenshot limit for your plan + * plan: + * type: string + * description: Current plan name + * month: + * type: string + * description: Current billing month (YYYY-MM) + * remaining: + * type: integer + * description: Screenshots remaining this month + * percentUsed: + * type: number + * description: Percentage of limit used + * 401: + * description: Missing API key + * 403: + * description: Invalid API key + */ +usageRouter.get("/", authMiddleware, (req, res) => { + const keyInfo = (req as any).apiKeyInfo; + const limit = getTierLimit(keyInfo.tier); + + const now = new Date(); + const monthKey = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}`; + + const record = getUsageForKey(keyInfo.key); + const used = record && record.monthKey === monthKey ? record.count : 0; + const remaining = Math.max(0, limit - used); + const percentUsed = limit > 0 ? Math.round((used / limit) * 1000) / 10 : 0; + + res.json({ used, limit, plan: keyInfo.tier, month: monthKey, remaining, percentUsed }); +});