feat(api): error + validate + pagination plumbing

Add lib/api/{errors,validate,pagination,index}.js: typed ApiError
subclasses, errorMiddleware, zod-backed validate(), parsePagination
with caps, and a mountApi() that owns /api routing + 404 + error tail.
server.js delegates /api to mountApi and drops the inline /api/spaces
smoke (returns in Task 2).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tests/api/errors.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import {
+  errorMiddleware,
+  NotFoundError, ValidationError, ConflictError, ForbiddenError,
+  asyncWrap, ApiError
+} from '../../lib/api/errors.js';
+
+function buildApp(handler) {
+  const app = express();
+  app.use(express.json());
+  app.get('/test', asyncWrap(handler));
+  app.use(errorMiddleware);
+  return app;
+}
+
+describe('api/errors', () => {
+  it('NotFoundError → 404 with code "not_found"', async () => {
+    const res = await request(buildApp(() => { throw new NotFoundError('missing'); }))
+      .get('/test');
+    expect(res.status).toBe(404);
+    expect(res.body).toEqual({ error: { code: 'not_found', message: 'missing' } });
+  });
+
+  it('ValidationError → 400 with details', async () => {
+    const res = await request(buildApp(() => { throw new ValidationError('bad', [{ path: 'name' }]); }))
+      .get('/test');
+    expect(res.status).toBe(400);
+    expect(res.body.error.code).toBe('validation_failed');
+    expect(res.body.error.details).toEqual([{ path: 'name' }]);
+  });
+
+  it('ConflictError → 409', async () => {
+    const res = await request(buildApp(() => { throw new ConflictError(); })).get('/test');
+    expect(res.status).toBe(409);
+    expect(res.body.error.code).toBe('conflict');
+  });
+
+  it('ForbiddenError → 403', async () => {
+    const res = await request(buildApp(() => { throw new ForbiddenError(); })).get('/test');
+    expect(res.status).toBe(403);
+    expect(res.body.error.code).toBe('forbidden');
+  });
+
+  it('unknown error → 500 with generic shape', async () => {
+    const res = await request(buildApp(() => { throw new Error('boom'); })).get('/test');
+    expect(res.status).toBe(500);
+    expect(res.body.error.code).toBe('internal');
+  });
+
+  it('asyncWrap forwards rejected promises', async () => {
+    const res = await request(buildApp(async () => { throw new NotFoundError(); }))
+      .get('/test');
+    expect(res.status).toBe(404);
+  });
+
+  it('ApiError exposes code, status, and details', () => {
+    const e = new ApiError('x', 'y', 418, { a: 1 });
+    expect(e.code).toBe('x');
+    expect(e.status).toBe(418);
+    expect(e.details).toEqual({ a: 1 });
+  });
+});

tests/api/helpers.js

@@ -0,0 +1,14 @@
+import { createApp } from '../../server.js';
+import { resetDb } from '../helpers/db.js';
+import { migrateUp } from '../../lib/db/migrate.js';
+
+const OWNER_TOKEN = 'test-token';
+
+export async function setup() {
+  await resetDb();
+  await migrateUp();
+  process.env.OWNER_TOKEN = OWNER_TOKEN;
+  const app = createApp();
+  const ownerHeaders = { Authorization: `Bearer ${OWNER_TOKEN}` };
+  return { app, ownerHeaders, OWNER_TOKEN };
+}

tests/api/validate.test.js

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { z } from 'zod';
+import { validate } from '../../lib/api/validate.js';
+import { errorMiddleware } from '../../lib/api/errors.js';
+import { parsePagination } from '../../lib/api/pagination.js';
+
+function buildApp() {
+  const app = express();
+  app.use(express.json());
+
+  app.post('/body',
+    validate({ body: z.object({ name: z.string().min(1) }) }),
+    (req, res) => res.json(req.body)
+  );
+
+  app.get('/params/:id',
+    validate({ params: z.object({ id: z.string().uuid() }) }),
+    (req, res) => res.json(req.params)
+  );
+
+  app.get('/page', (req, res) => {
+    try {
+      const p = parsePagination(req);
+      res.json(p);
+    } catch (e) { errorMiddleware(e, req, res, () => {}); }
+  });
+
+  app.use(errorMiddleware);
+  return app;
+}
+
+describe('api/validate', () => {
+  it('body schema parses and replaces req.body', async () => {
+    const res = await request(buildApp()).post('/body').send({ name: 'home' });
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ name: 'home' });
+  });
+
+  it('body schema failure → 400 with zod issues in details', async () => {
+    const res = await request(buildApp()).post('/body').send({ name: '' });
+    expect(res.status).toBe(400);
+    expect(res.body.error.code).toBe('validation_failed');
+    expect(Array.isArray(res.body.error.details)).toBe(true);
+    expect(res.body.error.details.length).toBeGreaterThan(0);
+  });
+
+  it('params schema failure → 400', async () => {
+    const res = await request(buildApp()).get('/params/not-a-uuid');
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('api/pagination', () => {
+  it('defaults to limit=50 offset=0', async () => {
+    const res = await request(buildApp()).get('/page');
+    expect(res.body).toEqual({ limit: 50, offset: 0 });
+  });
+
+  it('honors ?limit&offset', async () => {
+    const res = await request(buildApp()).get('/page?limit=10&offset=5');
+    expect(res.body).toEqual({ limit: 10, offset: 5 });
+  });
+
+  it('rejects negative offset', async () => {
+    const res = await request(buildApp()).get('/page?offset=-1');
+    expect(res.status).toBe(400);
+  });
+
+  it('rejects limit above max', async () => {
+    const res = await request(buildApp()).get('/page?limit=999');
+    expect(res.status).toBe(400);
+  });
+});

tests/server.test.js

@@ -25,16 +25,14 @@ describe('server', () => {
     expect(res.status).toBe(401);
   });
 
-  it('GET /api/spaces with token returns 200 and empty array', async () => {
-    const res = await request(app)
-      .get('/api/spaces')
-      .set('Authorization', 'Bearer test-token');
-    expect(res.status).toBe(200);
-    expect(res.body).toEqual([]);
+  it('unknown /api route returns 404 with structured error', async () => {
+    const res = await request(app).get('/api/nope').set('Authorization', 'Bearer test-token');
+    expect(res.status).toBe(404);
+    expect(res.body).toEqual({ error: { code: 'not_found', message: 'route not found' } });
   });
 
-  it('unknown route returns 404', async () => {
-    const res = await request(app).get('/api/nope').set('Authorization', 'Bearer test-token');
+  it('unknown non-api route returns 404', async () => {
+    const res = await request(app).get('/missing');
     expect(res.status).toBe(404);
   });
 });