synthos 0.10.0 → 0.11.0

package/src/service/useConnectorRoutes.ts

@@ -1,3 +1,5 @@
+import path from 'path';
+import crypto from 'crypto';
 import { Application } from 'express';
 import { SynthOSConfig } from '../init';
 import { loadSettings, saveSettings } from '../settings';
@@ -6,10 +8,87 @@ import {
     ConnectorSummary,
     ConnectorDetail,
     ConnectorCallRequest,
+    ConnectorDefinition,
     ConnectorOAuthConfig
 } from '../connectors';
+import { createMediaCache } from './mediaCache';
+
+function base64url(buf: Buffer): string {
+    return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function generateCodeVerifier(): string {
+    return base64url(crypto.randomBytes(32));
+}
+
+function generateCodeChallenge(verifier: string): string {
+    return base64url(crypto.createHash('sha256').update(verifier).digest());
+}
+
+interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    token_type?: string;
+    expires_in?: number;
+    scope?: string;
+}
+
+/**
+ * RFC 6749 §4.1.3 / §6: token endpoint requires application/x-www-form-urlencoded POST.
+ * Public clients (no client_secret) authenticate via PKCE alone; confidential clients send both.
+ */
+async function exchangeOAuthToken(
+    tokenUrl: string,
+    params: Record<string, string | undefined>
+): Promise<{ ok: boolean; data?: TokenResponse; errorText?: string }> {
+    const body = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (typeof v === 'string' && v.length > 0) body.set(k, v);
+    }
+    const res = await fetch(tokenUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },
+        body: body.toString()
+    });
+    if (!res.ok) {
+        return { ok: false, errorText: await res.text() };
+    }
+    return { ok: true, data: await res.json() as TokenResponse };
+}
+
+/**
+ * Refresh an expired access token. Buffer rotates refresh tokens — always save the latest.
+ * Returns the updated config slice (caller persists). Returns null on failure.
+ */
+async function refreshAccessToken(
+    def: ConnectorDefinition,
+    cfg: ConnectorOAuthConfig
+): Promise<Partial<ConnectorOAuthConfig> | null> {
+    if (!def.tokenUrl || !cfg.refreshToken || !cfg.clientId) return null;
+    const result = await exchangeOAuthToken(def.tokenUrl, {
+        grant_type: 'refresh_token',
+        refresh_token: cfg.refreshToken,
+        client_id: cfg.clientId,
+        client_secret: cfg.clientSecret
+    });
+    if (!result.ok || !result.data) {
+        console.error(`Token refresh failed for "${def.id}":`, result.errorText);
+        return null;
+    }
+    const data = result.data;
+    return {
+        accessToken: data.access_token,
+        apiKey: data.access_token,
+        refreshToken: data.refresh_token ?? cfg.refreshToken,
+        expiresAt: data.expires_in ? Date.now() + data.expires_in * 1000 : 0
+    };
+}
 
 export function useConnectorRoutes(config: SynthOSConfig, app: Application): void {
+    const mediaCache = createMediaCache({
+        storage: config.storageProvider,
+        cacheRoot: path.join(config.pagesFolder, 'cache'),
+    });
 
     // GET /api/connectors — List connectors (minimal summaries)
     // Also handles POST /api/connectors — Proxy call (see below)
@@ -172,8 +251,14 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
 
             const settings = await loadSettings(config);
             const cfg = (settings.connectors ?? {})[id] as ConnectorOAuthConfig | undefined;
-            if (!cfg?.clientId || !cfg?.clientSecret) {
-                res.status(400).json({ error: 'Client ID and Client Secret must be saved before authorizing' });
+            // PKCE-only public clients may register without a client_secret. Require clientId always;
+            // require clientSecret only for non-PKCE flows.
+            if (!cfg?.clientId) {
+                res.status(400).json({ error: 'Client ID must be saved before authorizing' });
+                return;
+            }
+            if (!def.usePkce && !cfg.clientSecret) {
+                res.status(400).json({ error: 'Client Secret must be saved before authorizing' });
                 return;
             }
 
@@ -183,10 +268,22 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
             const authUrl = new URL(def.authorizationUrl!);
             authUrl.searchParams.set('client_id', cfg.clientId);
             authUrl.searchParams.set('redirect_uri', redirectUri);
-            authUrl.searchParams.set('scope', (def.scopes ?? []).join(','));
+            authUrl.searchParams.set('scope', (def.scopes ?? []).join(def.scopeSeparator ?? ','));
             authUrl.searchParams.set('state', state);
             authUrl.searchParams.set('response_type', 'code');
 
+            // PKCE: generate verifier+challenge, persist verifier for the /callback step
+            if (def.usePkce) {
+                const codeVerifier = generateCodeVerifier();
+                const codeChallenge = generateCodeChallenge(codeVerifier);
+                authUrl.searchParams.set('code_challenge', codeChallenge);
+                authUrl.searchParams.set('code_challenge_method', 'S256');
+
+                const existing = settings.connectors ?? {};
+                const updated = { ...existing, [id]: { ...cfg, codeVerifier } };
+                await saveSettings(config, { connectors: updated as typeof existing });
+            }
+
             res.redirect(authUrl.toString());
         } catch (err: unknown) {
             console.error(err);
@@ -222,38 +319,45 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
 
             const settings = await loadSettings(config);
             const cfg = (settings.connectors ?? {})[connectorId] as ConnectorOAuthConfig | undefined;
-            if (!cfg?.clientId || !cfg?.clientSecret) {
+            if (!cfg?.clientId) {
+                res.status(400).json({ error: 'Client credentials not found' });
+                return;
+            }
+            if (!def.usePkce && !cfg.clientSecret) {
                 res.status(400).json({ error: 'Client credentials not found' });
                 return;
             }
 
             const redirectUri = `${req.protocol}://${req.get('host')}/api/connectors/callback`;
 
-            // Step 1: Exchange code for short-lived token
-            const tokenUrl = new URL(def.tokenUrl!);
-            tokenUrl.searchParams.set('client_id', cfg.clientId);
-            tokenUrl.searchParams.set('client_secret', cfg.clientSecret);
-            tokenUrl.searchParams.set('redirect_uri', redirectUri);
-            tokenUrl.searchParams.set('code', code);
-            tokenUrl.searchParams.set('grant_type', 'authorization_code');
-
-            const tokenRes = await fetch(tokenUrl.toString());
-            if (!tokenRes.ok) {
-                const text = await tokenRes.text();
-                console.error('Token exchange failed:', text);
+            // Step 1: Exchange code for short-lived token (RFC 6749 §4.1.3 — POST + form body)
+            const tokenResult = await exchangeOAuthToken(def.tokenUrl!, {
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: redirectUri,
+                client_id: cfg.clientId,
+                // Public PKCE clients omit client_secret; confidential clients send both.
+                client_secret: cfg.clientSecret,
+                // PKCE: include verifier when one was stored at /authorize
+                code_verifier: def.usePkce ? cfg.codeVerifier : undefined
+            });
+            if (!tokenResult.ok || !tokenResult.data) {
+                console.error('Token exchange failed:', tokenResult.errorText);
                 res.redirect(`/settings?tab=connectors&error=${encodeURIComponent('Token exchange failed')}`);
                 return;
             }
-            const tokenData = await tokenRes.json() as { access_token: string; token_type?: string; expires_in?: number };
+            const tokenData = tokenResult.data;
             let accessToken = tokenData.access_token;
+            let refreshToken = tokenData.refresh_token;
             let expiresAt = tokenData.expires_in ? Date.now() + tokenData.expires_in * 1000 : 0;
 
-            // Step 2: For Instagram — exchange for long-lived token
+            // Step 2: For Instagram — exchange for long-lived token (Facebook is non-PKCE,
+            // so clientSecret is guaranteed by the earlier non-PKCE branch validation)
             if (connectorId === 'instagram') {
                 const llUrl = new URL('https://graph.facebook.com/v21.0/oauth/access_token');
                 llUrl.searchParams.set('grant_type', 'fb_exchange_token');
                 llUrl.searchParams.set('client_id', cfg.clientId);
-                llUrl.searchParams.set('client_secret', cfg.clientSecret);
+                llUrl.searchParams.set('client_secret', cfg.clientSecret!);
                 llUrl.searchParams.set('fb_exchange_token', accessToken);
 
                 const llRes = await fetch(llUrl.toString());
@@ -292,22 +396,22 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
                 }
             }
 
-            // Step 4: Save tokens to settings
+            // Step 4: Save tokens to settings. Drop codeVerifier — it's single-use per RFC 7636.
             const existing = settings.connectors ?? {};
             const prev = (existing[connectorId] as ConnectorOAuthConfig) ?? { apiKey: '', enabled: false };
-            const updated = {
-                ...existing,
-                [connectorId]: {
-                    ...prev,
-                    apiKey: prev.apiKey || accessToken,
-                    accessToken,
-                    expiresAt,
-                    userId,
-                    accountName,
-                    enabled: true
-                }
+            const next: ConnectorOAuthConfig = {
+                ...prev,
+                apiKey: prev.apiKey || accessToken,
+                accessToken,
+                expiresAt,
+                userId,
+                accountName,
+                enabled: true
             };
-            await saveSettings(config, { connectors: updated });
+            if (refreshToken) next.refreshToken = refreshToken;
+            delete next.codeVerifier;
+            const updatedConnectors = { ...existing, [connectorId]: next };
+            await saveSettings(config, { connectors: updatedConnectors as typeof existing });
 
             res.redirect(`/settings?tab=connectors&connected=${encodeURIComponent(connectorId)}`);
         } catch (err: unknown) {
@@ -341,8 +445,22 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
                     res.status(400).json({ error: `Connector "${request.connector}" is not configured or not enabled` });
                     return;
                 }
-                // Check token expiry
-                if (oauthCfg.expiresAt && oauthCfg.expiresAt < Date.now()) {
+                // Auto-refresh if expired (or expiring within 60s) and a refresh_token is available.
+                // Skip for connectors without a refresh_token (e.g. Instagram long-lived) — fall through to the 401.
+                const expiringSoon = oauthCfg.expiresAt && oauthCfg.expiresAt < Date.now() + 60_000;
+                if (expiringSoon && oauthCfg.refreshToken) {
+                    const refreshed = await refreshAccessToken(def, oauthCfg);
+                    if (refreshed) {
+                        const existing = settings.connectors ?? {};
+                        const merged = { ...oauthCfg, ...refreshed };
+                        const updated = { ...existing, [request.connector]: merged };
+                        await saveSettings(config, { connectors: updated as typeof existing });
+                        Object.assign(oauthCfg, refreshed);
+                    } else {
+                        res.status(401).json({ error: `Access token for "${request.connector}" expired and refresh failed. Please re-authorize in Settings > Connectors.` });
+                        return;
+                    }
+                } else if (expiringSoon) {
                     res.status(401).json({ error: `Access token for "${request.connector}" has expired. Please re-authorize in Settings > Connectors.` });
                     return;
                 }
@@ -353,6 +471,29 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
                 }
             }
 
+            // Detect TTS calls eligible for audio caching
+            const isTts = request.connector === 'elevenlabs'
+                && request.method.toUpperCase() === 'POST'
+                && request.path.startsWith('/v1/text-to-speech/');
+            const cacheEnabled = settings.cache?.enabled !== false;
+            const noCache = req.headers['x-no-cache'] === 'true' || req.query.nocache === '1';
+
+            // Check audio cache for TTS requests
+            if (isTts && cacheEnabled && !noCache) {
+                const voiceId = request.path.split('/v1/text-to-speech/')[1]?.split('?')[0] ?? '';
+                const outputFormat = (request.query?.output_format) ?? 'mp3_44100_128';
+                const text = typeof request.body === 'object' && request.body !== null
+                    ? (request.body as Record<string, unknown>).text ?? ''
+                    : '';
+                const cacheKey = `audio:v1:${request.connector}:${voiceId}:${outputFormat}:${text}`;
+                const cached = await mediaCache.get('audio', cacheKey);
+                if (cached.hit) {
+                    res.set('Content-Type', cached.contentType);
+                    res.send(cached.buffer);
+                    return;
+                }
+            }
+
             // Build URL — join baseUrl path with request path to avoid
             // absolute paths (e.g. "/me/accounts") replacing the base path.
             // Split path from inline query string first — assigning a '?' to
@@ -428,6 +569,20 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
                 // Forward content-disposition if present (e.g. file downloads)
                 const cd = upstream.headers.get('content-disposition');
                 if (cd) res.set('Content-Disposition', cd);
+
+                // Cache TTS audio responses
+                if (isTts && cacheEnabled) {
+                    const voiceId = request.path.split('/v1/text-to-speech/')[1]?.split('?')[0] ?? '';
+                    const outputFormat = (request.query?.output_format) ?? 'mp3_44100_128';
+                    const text = typeof request.body === 'object' && request.body !== null
+                        ? (request.body as Record<string, unknown>).text ?? ''
+                        : '';
+                    const cacheKey = `audio:v1:${request.connector}:${voiceId}:${outputFormat}:${text}`;
+                    await mediaCache.put('audio', cacheKey, buffer, ct || 'audio/mpeg', {
+                        connector: request.connector, voiceId, outputFormat, text,
+                    });
+                }
+
                 res.send(buffer);
             }
         } catch (err: unknown) {

package/src/service/useDataRoutes.ts

@@ -1,116 +1,198 @@
-import { Application, Response } from 'express';
-import { SynthOSConfig } from "../init";
-import path from "path";
-import { v4 } from "uuid";
-import { clearCachedScripts } from '../scripts';
-
-export function useDataRoutes(config: SynthOSConfig, app: Application): void {
-    app.get('/api/data/:page/:table', (req, res) => handleList(config, req.params.page, req.params.table, req.query, res));
-    app.get('/api/data/:page/:table/:id', (req, res) => handleGet(config, req.params.page, req.params.table, req.params.id, res));
-    app.post('/api/data/:page/:table', (req, res) => handleUpsert(config, req.params.page, req.params.table, req.body, res));
-    app.delete('/api/data/:page/:table/:id', (req, res) => handleDelete(config, req.params.page, req.params.table, req.params.id, res));
-}
-
-// ---------------------------------------------------------------------------
-// Route handlers
-// ---------------------------------------------------------------------------
-
-async function handleList(config: SynthOSConfig, page: string, table: string, query: Record<string, any>, res: Response): Promise<void> {
-    const sp = config.storageProvider;
-    const folder = tableFolder(config, page, table);
-    if (!(await sp.checkIfExists(folder))) {
-        res.status(404).json({ error: 'table_not_found', page, table });
-        return;
-    }
-
-    const ids = (await sp.listFiles(folder)).filter(f => f.endsWith('.json')).map(f => f.replace('.json', ''));
-
-    const rows: Record<string, any>[] = [];
-    for (const id of ids) {
-        const file = recordFile(folder, id);
-        try {
-            const row = JSON.parse(await sp.loadFile(file));
-            row.id = id;
-            rows.push(row);
-        } catch (err: unknown) {
-            console.error(err);
-        }
-    }
-
-    // Paginate when limit is provided
-    const limitParam = typeof query.limit === 'string' ? parseInt(query.limit, 10) : NaN;
-    if (!isNaN(limitParam) && limitParam > 0) {
-        const offset = Math.max(0, typeof query.offset === 'string' ? parseInt(query.offset, 10) || 0 : 0);
-        const items = rows.slice(offset, offset + limitParam);
-        res.json({ items, total: rows.length, offset, limit: limitParam, hasMore: offset + limitParam < rows.length });
-    } else {
-        res.json(rows);
-    }
-}
-
-async function handleGet(config: SynthOSConfig, page: string, table: string, id: string, res: Response): Promise<void> {
-    const sp = config.storageProvider;
-    const folder = tableFolder(config, page, table);
-    if (!(await sp.checkIfExists(folder))) {
-        res.status(404).json({ error: 'table_not_found', page, table });
-        return;
-    }
-
-    const file = recordFile(folder, id);
-    try {
-        const row = JSON.parse(await sp.loadFile(file));
-        row.id = id;
-        res.json(row);
-    } catch (err: unknown) {
-        res.json({});
-    }
-}
-
-async function handleUpsert(config: SynthOSConfig, page: string, table: string, body: any, res: Response): Promise<void> {
-    const sp = config.storageProvider;
-    const id = body.id ?? v4();
-    const folder = tableFolder(config, page, table);
-    const file = recordFile(folder, id);
-    try {
-        const row = { ...body, id };
-        await sp.ensureFolderExists(folder);
-        await sp.saveFile(file, JSON.stringify(row, null, 4));
-        if (table === 'scripts') {
-            clearCachedScripts();
-        }
-        res.json(row);
-    } catch (err: unknown) {
-        console.error(err);
-        res.status(500).send((err as Error).message);
-    }
-}
-
-async function handleDelete(config: SynthOSConfig, page: string, table: string, id: string, res: Response): Promise<void> {
-    const sp = config.storageProvider;
-    const folder = tableFolder(config, page, table);
-    const file = recordFile(folder, id);
-    try {
-        if (await sp.checkIfExists(file)) {
-            await sp.deleteFile(file);
-            if (table === 'scripts') {
-                clearCachedScripts();
-            }
-        }
-        res.json({ success: true });
-    } catch (err: unknown) {
-        console.error(err);
-        res.status(500).send((err as Error).message);
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function tableFolder(config: SynthOSConfig, page: string, table: string): string {
-    return path.join(config.pagesFolder, 'pages', page, table);
-}
-
-function recordFile(folder: string, id: string): string {
-    return path.join(folder, `${id}.json`);
-}
+import { Application, Response } from 'express';
+import { SynthOSConfig } from "../init";
+import path from "path";
+import { v4 } from "uuid";
+import { clearCachedScripts } from '../scripts';
+import {
+    deleteSchema,
+    isValidSchemaPayload,
+    listTables,
+    loadSchema,
+    mergeSchema,
+    newSchemaWrapper,
+    saveSchema,
+    updateSchemaWrapper,
+    MergeMode,
+} from "./sharedTableSchema";
+
+export function useDataRoutes(config: SynthOSConfig, app: Application): void {
+    // Schema sidecar + table-list endpoints registered before the generic
+    // table/record routes so the literal `_schema` / `_tables` segments
+    // aren't captured by `:table` / `:table/:id`.
+    app.get('/api/data/:page/_tables', (req, res) => handleListTables(config, req.params.page, res));
+    app.get('/api/data/:page/:table/_schema', (req, res) => handleGetSchema(config, req.params.page, req.params.table, res));
+    app.put('/api/data/:page/:table/_schema', (req, res) => handlePutSchema(config, req.params.page, req.params.table, req.query, req.body, res));
+    app.delete('/api/data/:page/:table/_schema', (req, res) => handleDeleteSchema(config, req.params.page, req.params.table, res));
+
+    app.get('/api/data/:page/:table', (req, res) => handleList(config, req.params.page, req.params.table, req.query, res));
+    app.get('/api/data/:page/:table/:id', (req, res) => handleGet(config, req.params.page, req.params.table, req.params.id, res));
+    app.post('/api/data/:page/:table', (req, res) => handleUpsert(config, req.params.page, req.params.table, req.body, res));
+    app.delete('/api/data/:page/:table/:id', (req, res) => handleDelete(config, req.params.page, req.params.table, req.params.id, res));
+}
+
+// ---------------------------------------------------------------------------
+// Route handlers — records
+// ---------------------------------------------------------------------------
+
+async function handleList(config: SynthOSConfig, page: string, table: string, query: Record<string, any>, res: Response): Promise<void> {
+    const sp = config.storageProvider;
+    const folder = tableFolder(config, page, table);
+    if (!(await sp.checkIfExists(folder))) {
+        res.status(404).json({ error: 'table_not_found', page, table });
+        return;
+    }
+
+    const ids = (await sp.listFiles(folder)).filter(f => f.endsWith('.json')).map(f => f.replace('.json', ''));
+
+    const rows: Record<string, any>[] = [];
+    for (const id of ids) {
+        const file = recordFile(folder, id);
+        try {
+            const row = JSON.parse(await sp.loadFile(file));
+            row.id = id;
+            rows.push(row);
+        } catch (err: unknown) {
+            console.error(err);
+        }
+    }
+
+    // Paginate when limit is provided
+    const limitParam = typeof query.limit === 'string' ? parseInt(query.limit, 10) : NaN;
+    if (!isNaN(limitParam) && limitParam > 0) {
+        const offset = Math.max(0, typeof query.offset === 'string' ? parseInt(query.offset, 10) || 0 : 0);
+        const items = rows.slice(offset, offset + limitParam);
+        res.json({ items, total: rows.length, offset, limit: limitParam, hasMore: offset + limitParam < rows.length });
+    } else {
+        res.json(rows);
+    }
+}
+
+async function handleGet(config: SynthOSConfig, page: string, table: string, id: string, res: Response): Promise<void> {
+    const sp = config.storageProvider;
+    const folder = tableFolder(config, page, table);
+    if (!(await sp.checkIfExists(folder))) {
+        res.status(404).json({ error: 'table_not_found', page, table });
+        return;
+    }
+
+    const file = recordFile(folder, id);
+    try {
+        const row = JSON.parse(await sp.loadFile(file));
+        row.id = id;
+        res.json(row);
+    } catch (err: unknown) {
+        res.json({});
+    }
+}
+
+async function handleUpsert(config: SynthOSConfig, page: string, table: string, body: any, res: Response): Promise<void> {
+    const sp = config.storageProvider;
+    const id = body.id ?? v4();
+    const folder = tableFolder(config, page, table);
+    const file = recordFile(folder, id);
+    try {
+        const row = { ...body, id };
+        await sp.ensureFolderExists(folder);
+        await sp.saveFile(file, JSON.stringify(row, null, 4));
+        if (table === 'scripts') {
+            clearCachedScripts();
+        }
+        res.json(row);
+    } catch (err: unknown) {
+        console.error(err);
+        res.status(500).send((err as Error).message);
+    }
+}
+
+async function handleDelete(config: SynthOSConfig, page: string, table: string, id: string, res: Response): Promise<void> {
+    const sp = config.storageProvider;
+    const folder = tableFolder(config, page, table);
+    const file = recordFile(folder, id);
+    try {
+        if (await sp.checkIfExists(file)) {
+            await sp.deleteFile(file);
+            if (table === 'scripts') {
+                clearCachedScripts();
+            }
+        }
+        res.json({ success: true });
+    } catch (err: unknown) {
+        console.error(err);
+        res.status(500).send((err as Error).message);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Route handlers — schema sidecar
+// ---------------------------------------------------------------------------
+
+async function handleGetSchema(config: SynthOSConfig, page: string, table: string, res: Response): Promise<void> {
+    const wrapper = await loadSchema(config, pageNamespace(config, page), table);
+    if (!wrapper) {
+        res.status(404).json({ error: 'schema_not_found', page, table });
+        return;
+    }
+    res.json(wrapper);
+}
+
+async function handlePutSchema(
+    config: SynthOSConfig,
+    page: string,
+    table: string,
+    query: Record<string, any>,
+    body: any,
+    res: Response,
+): Promise<void> {
+    const incoming = body && typeof body === 'object' && body.schema ? body.schema : body;
+    if (!isValidSchemaPayload(incoming)) {
+        res.status(400).json({ error: 'invalid_schema', message: 'Body must be a JSON Schema object (or { schema: ... } wrapper).' });
+        return;
+    }
+    const merge: MergeMode = query.merge === 'replace' ? 'replace' : 'additive';
+    const definedBy = typeof body?.definedBy === 'string' ? body.definedBy : undefined;
+    const namespace = pageNamespace(config, page);
+    const existing = await loadSchema(config, namespace, table);
+    const { merged, conflicts } = mergeSchema(existing?.schema, incoming, merge);
+    if (conflicts.length > 0) {
+        res.status(409).json({ error: 'schema_conflict', conflicts });
+        return;
+    }
+    const now = new Date().toISOString();
+    const wrapper = existing
+        ? updateSchemaWrapper(existing, merged, now, definedBy)
+        : newSchemaWrapper(merged, now, definedBy);
+    await saveSchema(config, namespace, table, wrapper);
+    res.json(wrapper);
+}
+
+async function handleDeleteSchema(config: SynthOSConfig, page: string, table: string, res: Response): Promise<void> {
+    await deleteSchema(config, pageNamespace(config, page), table);
+    res.status(204).end();
+}
+
+/**
+ * Subfolders under `<pagesFolder>/pages/<page>/` that are NOT data tables.
+ * `files` is the synthos.files namespace; it must not appear in the table list.
+ */
+const RESERVED_PAGE_SUBDIRS: ReadonlySet<string> = new Set(['files']);
+
+async function handleListTables(config: SynthOSConfig, page: string, res: Response): Promise<void> {
+    const tables = await listTables(config, pageNamespace(config, page), RESERVED_PAGE_SUBDIRS);
+    res.json({ tables });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function pageNamespace(config: SynthOSConfig, page: string): string {
+    return path.join(config.pagesFolder, 'pages', page);
+}
+
+function tableFolder(config: SynthOSConfig, page: string, table: string): string {
+    return path.join(pageNamespace(config, page), table);
+}
+
+function recordFile(folder: string, id: string): string {
+    return path.join(folder, `${id}.json`);
+}