feat: nest API under /api/v1, structured error envelope, paged lists

Move every handler from /api/* to /api/v1/*. /api/* is now reserved for future versioning. Standardise the error response shape across the API as {"error": {"code": "snake_case", "message": "..."}}. AppError gains a `code()` whose top-level variants are matched exhaustively without a wildcard — new variants are a compile error until coded. 500-class responses always emit the fixed "internal error" string and log the real cause via tracing only. Lock in the list pagination envelope as {"items": [...], "page": { "limit", "offset", "total"}} and apply it to GET /api/v1/mangas. `total` serialises as null until feat/list-search-polish lands an indexed count. The frontend client parses the envelope into ApiError.code with an http_error fallback for non-JSON bodies. listMangas now returns the paged shape; the root route consumes .items. New client.test.ts covers envelope parsing and the fallback paths. Lockstep version bump to 0.2.0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-16 21:41:20 +02:00
parent 6c1d04aaf4
commit ce9a01793f
18 changed files with 6121 additions and 67 deletions
--- a/frontend/src/lib/api/client.test.ts
+++ b/frontend/src/lib/api/client.test.ts
@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
+import { ApiError } from './client';
+import { getManga } from './mangas';
+
+describe('request error envelope parsing', () => {
+    let fetchSpy: MockInstance<typeof globalThis.fetch>;
+
+    beforeEach(() => {
+        fetchSpy = vi.spyOn(globalThis, 'fetch');
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('parses {error:{code,message}} into ApiError.code and message', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            new Response(
+                JSON.stringify({ error: { code: 'invalid_input', message: 'title is required' } }),
+                { status: 400, headers: { 'content-type': 'application/json' } }
+            )
+        );
+        await expect(getManga('x')).rejects.toMatchObject({
+            status: 400,
+            code: 'invalid_input',
+            message: 'title is required'
+        });
+    });
+
+    it('falls back to http_error code when body is HTML (e.g. upstream proxy)', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            new Response('<html>upstream proxy bad</html>', {
+                status: 502,
+                headers: { 'content-type': 'text/html' }
+            })
+        );
+        const err = (await getManga('x').catch((e) => e)) as ApiError;
+        expect(err).toBeInstanceOf(ApiError);
+        expect(err.status).toBe(502);
+        expect(err.code).toBe('http_error');
+        expect(err.message).toContain('upstream proxy bad');
+    });
+
+    it('falls back to http_error code when body is empty', async () => {
+        fetchSpy.mockResolvedValueOnce(new Response('', { status: 500 }));
+        const err = (await getManga('x').catch((e) => e)) as ApiError;
+        expect(err).toBeInstanceOf(ApiError);
+        expect(err.status).toBe(500);
+        expect(err.code).toBe('http_error');
+    });
+
+    it('falls back to http_error code when JSON has no error envelope', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            new Response(JSON.stringify({ message: 'oops' }), {
+                status: 500,
+                headers: { 'content-type': 'application/json' }
+            })
+        );
+        const err = (await getManga('x').catch((e) => e)) as ApiError;
+        expect(err.code).toBe('http_error');
+    });
+});