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>

lib/api/errors.js

@@ -0,0 +1,48 @@
+import { log } from '../log.js';
+
+export class ApiError extends Error {
+  constructor(code, message, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+}
+
+export class NotFoundError extends ApiError {
+  constructor(message = 'not found', details) {
+    super('not_found', message, 404, details);
+  }
+}
+
+export class ValidationError extends ApiError {
+  constructor(message = 'validation failed', details) {
+    super('validation_failed', message, 400, details);
+  }
+}
+
+export class ConflictError extends ApiError {
+  constructor(message = 'conflict', details) {
+    super('conflict', message, 409, details);
+  }
+}
+
+export class ForbiddenError extends ApiError {
+  constructor(message = 'forbidden', details) {
+    super('forbidden', message, 403, details);
+  }
+}
+
+export function asyncWrap(fn) {
+  return (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
+}
+
+export function errorMiddleware(err, _req, res, _next) {
+  if (err instanceof ApiError) {
+    const body = { error: { code: err.code, message: err.message } };
+    if (err.details !== undefined) body.error.details = err.details;
+    return res.status(err.status).json(body);
+  }
+  log.error({ err }, 'unhandled');
+  res.status(500).json({ error: { code: 'internal', message: err.message } });
+}

lib/api/index.js

@@ -0,0 +1,16 @@
+import { Router } from 'express';
+import { ownerOnly } from '../auth/owner.js';
+import { errorMiddleware, NotFoundError } from './errors.js';
+
+export function mountApi(app) {
+  const api = Router();
+  api.use(ownerOnly);
+
+  // route modules registered here as Plan 2 progresses
+
+  api.use((_req, _res, next) => next(new NotFoundError('route not found')));
+
+  api.use(errorMiddleware);
+  app.use('/api', api);
+  return api;
+}

lib/api/pagination.js

@@ -0,0 +1,14 @@
+import { ValidationError } from './errors.js';
+
+export function parsePagination(req, { defaultLimit = 50, max = 200 } = {}) {
+  const q = req.query || {};
+  const limit  = q.limit  === undefined ? defaultLimit : Number(q.limit);
+  const offset = q.offset === undefined ? 0            : Number(q.offset);
+  if (!Number.isFinite(limit) || limit < 1 || limit > max) {
+    throw new ValidationError(`limit must be 1..${max}`, { limit: q.limit });
+  }
+  if (!Number.isFinite(offset) || offset < 0) {
+    throw new ValidationError('offset must be >= 0', { offset: q.offset });
+  }
+  return { limit, offset };
+}

lib/api/validate.js

@@ -0,0 +1,15 @@
+import { ValidationError } from './errors.js';
+
+export function validate({ body, params, query } = {}) {
+  return (req, _res, next) => {
+    try {
+      if (body)   req.body   = body.parse(req.body);
+      if (params) req.params = params.parse(req.params);
+      if (query)  req.validatedQuery = query.parse(req.query);
+      next();
+    } catch (e) {
+      if (e?.issues) return next(new ValidationError('validation failed', e.issues));
+      next(e);
+    }
+  };
+}