feat(api): establish stable HTTP contract — uniform {success,data} envelope, status codes, /api/v1

Point 1 of the v1.0 lock-in: commit to a stable HTTP API (the cleanest, fullest form).

Core (centralized):
- Every JSON /api response now uses ONE envelope via a Fastify preSerialization hook (src/web/server.ts): success -> { success:true, data:<payload> }; error -> { success:false, error, errorCode } with a conventional HTTP status. Non-JSON routes (file-raw, tail-file SSE, download, screenshots, /q redirect, WS) are skipped.
- Error-code -> HTTP status is a single source of truth (httpStatusForErrorCode in src/types/api.ts): 400/401/404/409/422/429/500. Expanded ApiErrorCode (added UNAUTHORIZED, CONFLICT, RATE_LIMITED). Errors are no longer HTTP 200.
- Versioned alias: /api/v1/* rewrites to /api/* (rewriteApiV1Url), so external clients pin to a stable surface while the bundled UI keeps using /api/*.
- Handlers stripped of manual 'success:true' (50 across 14 route files) so they return bare payloads the hook wraps uniformly; fixed the mux DELETE {success:<bool>} envelope collision (-> {killed}).

Frontend (48 call sites across 10 files):
- _apiJson() auto-unwraps { success:true, data } -> data (null on error), so most bare-shape readers are transparent. Raw-fetch sites relocate payload reads under .data; success/res.ok/error checks unchanged.

Docs: new docs/api-reference.md (envelope, status table, error codes, /api/v1, SSE); versioning-policy.md flipped — the HTTP/SSE API is now part of the stable, SemVer-covered surface.

Verification: full unit/route suite green (2680 passed) incl. ~166 updated assertions across 24 test files; typecheck/lint/format/frontend-syntax clean; a headless-chromium smoke loaded the migrated UI and drove the panels with 0 console/page errors; /api/status and /api/v1/status confirmed returning the uniform envelope live.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
arkon
2026-06-10 01:30:43 +02:00
co-authored by Claude Opus 4.8
parent 5b3024b327
commit 458fb81cbe
49 changed files with 929 additions and 554 deletions
+10 -1
View File
@@ -44,11 +44,20 @@ Object.assign(CodemanApp.prototype, {
async _apiJson(path, opts = {}) {
const res = await this._api(path, opts);
if (!res || !res.ok) return null;
let body;
try {
return await res.json();
body = await res.json();
} catch {
return null;
}
// Uniform API envelope (stable HTTP contract): unwrap { success:true, data } → data;
// { success:false } → null (errors also surface as a non-ok HTTP status above).
// Legacy/bare bodies pass through unchanged.
if (body && typeof body === 'object') {
if (body.success === false) return null;
if (body.success === true && 'data' in body) return body.data;
}
return body;
},
/**
+8 -8
View File
@@ -597,7 +597,7 @@ class CodemanApp {
// Fetch tunnel status for header indicator (desktop only)
this.loadTunnelStatus();
// Share a single settings fetch between both consumers
const settingsPromise = fetch('/api/settings').then(r => r.ok ? r.json() : null).catch(() => null);
const settingsPromise = fetch('/api/settings').then(r => r.ok ? r.json() : null).then(env => env?.data ?? null).catch(() => null);
this.loadQuickStartCases(null, settingsPromise);
this._initRunMode();
this.setupEventListeners();
@@ -1531,13 +1531,13 @@ class CodemanApp {
try {
// Source 1: Transcript JSONL (best quality — clean structured text from Claude)
const res = await fetch(`/api/sessions/${this.activeSessionId}/last-response`);
const data = await res.json();
const data = (await res.json())?.data ?? {};
let lastResponse = data.text || '';
// Source 2: Terminal buffer fallback — strip ANSI, drop Claude CLI chrome
if (!lastResponse) {
const termRes = await fetch(`/api/sessions/${this.activeSessionId}/terminal`);
const termData = await termRes.json();
const termData = (await termRes.json())?.data ?? {};
if (termData.terminalBuffer) {
lastResponse = this._cleanTerminalBuffer(termData.terminalBuffer);
}
@@ -1567,7 +1567,7 @@ class CodemanApp {
if (moreBtn) moreBtn.textContent = '...';
try {
const res = await fetch(`/api/sessions/${this.activeSessionId}/last-response?context=full`);
const data = await res.json();
const data = (await res.json())?.data ?? {};
const messages = data.messages || [];
const body = document.getElementById('responseViewerBody');
const title = document.getElementById('responseViewerTitle');
@@ -1618,7 +1618,7 @@ class CodemanApp {
if (this._isLoadingBuffer) return;
try {
const res = await fetch(`/api/sessions/${this.activeSessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
const data = await res.json();
const data = (await res.json())?.data ?? {};
if (data.terminalBuffer) {
this.terminal.clear();
this.terminal.reset();
@@ -1648,7 +1648,7 @@ class CodemanApp {
// Fetch buffer, clear terminal, write buffer, resize (no Ctrl+L needed)
try {
const res = await fetch(`/api/sessions/${data.id}/terminal`);
const termData = await res.json();
const termData = (await res.json())?.data ?? {};
this.terminal.clear();
this.terminal.reset();
@@ -2254,7 +2254,7 @@ class CodemanApp {
try {
const res = await fetch('/api/status');
const data = await res.json();
this.handleInit(data);
this.handleInit(data?.data ?? {});
} catch (err) {
console.error('Failed to load state:', err);
}
@@ -2938,7 +2938,7 @@ class CodemanApp {
_crashDiag.log('FETCH_START');
const res = await fetch(`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
if (this._isStaleSelect(selectGen)) return;
const data = await res.json();
const data = (await res.json())?.data ?? {};
_crashDiag.log(`FETCH_DONE: ${data.terminalBuffer ? (data.terminalBuffer.length/1024).toFixed(0) + 'KB' : 'empty'} truncated=${data.truncated}`);
if (data.terminalBuffer) {
+1 -1
View File
@@ -149,7 +149,7 @@ Object.assign(CodemanApp.prototype, {
}
const data = await resp.json();
return data.path;
return data.data.path;
},
// Decode an image File through the browser and re-encode it to a format the
+3 -3
View File
@@ -182,7 +182,7 @@ Object.assign(CodemanApp.prototype, {
body: JSON.stringify({ goal, config }),
});
const data = await res.json();
if (data.ok) {
if (data.data?.ok) {
this.orchestratorState = { state: 'planning', plan: null };
this.showOrchestratorPanel();
this.renderOrchestratorPanel();
@@ -259,8 +259,8 @@ Object.assign(CodemanApp.prototype, {
try {
const res = await fetch('/api/orchestrator/status');
const data = await res.json();
if (data.ok) {
this.orchestratorState = data;
if (data.data?.ok) {
this.orchestratorState = data.data;
this.renderOrchestratorPanel();
}
} catch (err) {
+5 -5
View File
@@ -251,7 +251,7 @@ Object.assign(CodemanApp.prototype, {
const response = await fetch('/api/token-stats');
const data = await response.json();
if (data.success) {
this.renderTokenStats(data);
this.renderTokenStats(data.data);
document.getElementById('tokenStatsModal').classList.add('active');
} else {
this.showToast('Failed to load token stats', 'error');
@@ -2881,7 +2881,7 @@ Object.assign(CodemanApp.prototype, {
try {
const res = await fetch('/api/mux-sessions');
const data = await res.json();
this.muxSessions = data.sessions || [];
this.muxSessions = data.data?.sessions || [];
this.renderMuxSessions();
} catch (err) {
console.error('Failed to load mux sessions:', err);
@@ -3109,8 +3109,8 @@ Object.assign(CodemanApp.prototype, {
const res = await fetch('/api/mux-sessions/reconcile', { method: 'POST' });
const data = await res.json();
if (data.dead && data.dead.length > 0) {
this.showToast(`Found ${data.dead.length} dead mux session(s)`, 'warning');
if (data.data?.dead && data.data.dead.length > 0) {
this.showToast(`Found ${data.data.dead.length} dead mux session(s)`, 'warning');
await this.loadMuxSessions();
} else {
this.showToast('All mux sessions are alive', 'success');
@@ -3220,7 +3220,7 @@ Object.assign(CodemanApp.prototype, {
try {
const res = await fetch('/api/system/stats');
const stats = await res.json();
this.updateSystemStatsDisplay(stats);
this.updateSystemStatsDisplay(stats.data);
} catch (err) {
// Silently fail - system stats are not critical
}
+2 -2
View File
@@ -996,14 +996,14 @@ Object.assign(CodemanApp.prototype, {
return;
}
const history = data.history || [];
const history = data.data.history || [];
if (history.length === 0) {
this.showToast('No plan history available', 'info');
return;
}
// Show history dropdown modal
this.showPlanHistoryModal(history, data.currentVersion);
this.showPlanHistoryModal(history, data.data.currentVersion);
} catch (err) {
this.showToast('Failed to load plan history: ' + err.message, 'error');
}
+6 -6
View File
@@ -151,11 +151,11 @@ Object.assign(CodemanApp.prototype, {
const res = await fetch(`/api/cases/${encodeURIComponent(caseName)}/fix-plan`);
const data = await res.json();
if (data.success && data.exists && data.todos?.length > 0) {
if (data.success && data.data.exists && data.data.todos?.length > 0) {
this.ralphWizardConfig.existingPlan = {
todos: data.todos,
stats: data.stats,
content: data.content,
todos: data.data.todos,
stats: data.data.stats,
content: data.data.content,
};
this.updateExistingPlanUI();
} else {
@@ -1054,8 +1054,8 @@ Object.assign(CodemanApp.prototype, {
this.showToast(data.error || 'Failed to start', 'error');
return;
}
this.ralphClosedSessions.delete(data.sessionId);
await this.selectSession(data.sessionId);
this.ralphClosedSessions.delete(data.data.sessionId);
await this.selectSession(data.data.sessionId);
this.showToast(`Ralph Loop started in ${config.caseName}`, 'success');
} catch (err) {
console.error('Failed to start Ralph loop:', err);
+1 -1
View File
@@ -1041,7 +1041,7 @@ Object.assign(CodemanApp.prototype, {
return;
}
this.runSummaryData = data.summary;
this.runSummaryData = data.data.summary;
this.renderRunSummary();
} catch (err) {
console.error('Failed to load run summary:', err);
+13 -13
View File
@@ -50,15 +50,15 @@ Object.assign(CodemanApp.prototype, {
let lastUsedCase = null;
try {
const settings = settingsPromise ? await settingsPromise : await fetch('/api/settings').then(r => r.ok ? r.json() : null);
if (settings) {
lastUsedCase = settings.lastUsedCase || null;
if (settings && settings.data) {
lastUsedCase = settings.data.lastUsedCase || null;
}
} catch {
// Ignore settings load errors
}
const res = await fetch('/api/cases');
const cases = await res.json();
const cases = (await res.json()).data;
this.cases = cases;
console.log('[loadQuickStartCases] Loaded cases:', cases.map(c => c.name), 'lastUsedCase:', lastUsedCase);
@@ -125,7 +125,7 @@ Object.assign(CodemanApp.prototype, {
async updateDirDisplayForCase(caseName) {
try {
const res = await fetch(`/api/cases/${caseName}`);
const data = await res.json();
const data = (await res.json()).data;
if (data.path) {
document.getElementById('dirDisplay').textContent = data.path;
document.getElementById('dirInput').value = data.path;
@@ -304,7 +304,7 @@ Object.assign(CodemanApp.prototype, {
try {
// Get case path first
const caseRes = await fetch(`/api/cases/${caseName}`);
let caseData = await caseRes.json();
let caseData = (await caseRes.json()).data;
// Create the case if it doesn't exist
if (!caseData.path) {
@@ -373,7 +373,7 @@ Object.assign(CodemanApp.prototype, {
const sessionIds = [];
for (const result of createResults) {
if (!result.success) throw new Error(result.error);
sessionIds.push(result.session.id);
sessionIds.push(result.data.session.id);
}
firstSessionId = sessionIds[0];
@@ -452,7 +452,7 @@ Object.assign(CodemanApp.prototype, {
try {
// Get the case path
const caseRes = await fetch(`/api/cases/${caseName}`);
let caseData = await caseRes.json();
let caseData = (await caseRes.json()).data;
// Create the case if it doesn't exist
if (!caseData.path) {
@@ -501,7 +501,7 @@ Object.assign(CodemanApp.prototype, {
const sessionIds = [];
for (const result of createResults) {
if (!result.success) throw new Error(result.error);
sessionIds.push(result.session.id);
sessionIds.push(result.data.session.id);
}
// Step 2: Start all shells in parallel
@@ -545,7 +545,7 @@ Object.assign(CodemanApp.prototype, {
try {
// Check if OpenCode is available
const statusRes = await fetch('/api/opencode/status');
const status = await statusRes.json();
const status = (await statusRes.json()).data;
if (!status.available) {
this.terminal.writeln('\x1b[1;31m OpenCode CLI not found.\x1b[0m');
this.terminal.writeln('\x1b[90m Install with: curl -fsSL https://opencode.ai/install | bash\x1b[0m');
@@ -570,8 +570,8 @@ Object.assign(CodemanApp.prototype, {
// Switch to the new session (don't pre-set activeSessionId — selectSession
// early-returns when IDs match, skipping buffer load and sendResize)
if (data.sessionId) {
await this.selectSession(data.sessionId);
if (data.data.sessionId) {
await this.selectSession(data.data.sessionId);
}
this.terminal.focus();
@@ -789,8 +789,8 @@ Object.assign(CodemanApp.prototype, {
try {
const res = await fetch(`/api/sessions/${sessionId}/respawn/config`);
const data = await res.json();
if (data.success && data.config) {
const c = data.config;
if (data.success && data.data && data.data.config) {
const c = data.data.config;
document.getElementById('modalRespawnPrompt').value = c.updatePrompt || 'update all the docs and CLAUDE.md';
document.getElementById('modalRespawnSendClear').checked = c.sendClear ?? true;
document.getElementById('modalRespawnSendInit').checked = c.sendInit ?? true;
+31 -18
View File
@@ -185,9 +185,9 @@ Object.assign(CodemanApp.prototype, {
try {
// Get VAPID public key from server
const keyData = await this._apiJson('/api/push/vapid-key');
if (!keyData?.success) throw new Error('Failed to get VAPID key');
if (!keyData) throw new Error('Failed to get VAPID key');
const applicationServerKey = urlBase64ToUint8Array(keyData.data.publicKey);
const applicationServerKey = urlBase64ToUint8Array(keyData.publicKey);
const subscription = await this._swRegistration.pushManager.subscribe({
userVisibleOnly: true,
applicationServerKey,
@@ -204,11 +204,11 @@ Object.assign(CodemanApp.prototype, {
pushPreferences: this._buildPushPreferences(),
},
});
if (!data?.success) throw new Error('Failed to register subscription');
if (!data) throw new Error('Failed to register subscription');
this._pushSubscription = subscription;
this._pushSubscriptionId = data.data.id;
localStorage.setItem('codeman-push-subscription-id', data.data.id);
this._pushSubscriptionId = data.id;
localStorage.setItem('codeman-push-subscription-id', data.id);
this._updatePushUI(true);
this.showToast('Push notifications enabled', 'success');
} catch (err) {
@@ -598,7 +598,10 @@ Object.assign(CodemanApp.prototype, {
let data = null;
try {
const res = await fetch('/api/system/update/status');
if (res.ok) data = await res.json();
if (res.ok) {
const env = await res.json();
data = env && env.success === true ? env.data : env;
}
} catch { /* server restarting — keep polling */ }
if (!data) {
@@ -652,7 +655,8 @@ Object.assign(CodemanApp.prototype, {
async loadTunnelStatus() {
try {
const res = await fetch('/api/tunnel/status');
const status = await res.json();
const env = await res.json();
const status = env?.success === true ? env.data : env;
const active = status.running && status.url;
this._tunnelUrl = active ? status.url : null;
this._updateTunnelUrlDisplay(this._tunnelUrl);
@@ -721,7 +725,8 @@ Object.assign(CodemanApp.prototype, {
if (!res.ok) throw new Error('Tunnel not running');
return res.json();
})
.then(data => {
.then(env => {
const data = env?.success === true ? env.data : env;
const container = document.getElementById('tunnelQrContainer');
if (container && data.svg) container.innerHTML = data.svg;
// Show auth badge, countdown, and regenerate button when auth is enabled
@@ -754,7 +759,8 @@ Object.assign(CodemanApp.prototype, {
// Fetch URL for display
fetch('/api/tunnel/status')
.then(r => r.json())
.then(status => {
.then(env => {
const status = env?.success === true ? env.data : env;
const urlEl = document.getElementById('tunnelQrUrl');
if (urlEl && status.url) {
urlEl.textContent = status.url;
@@ -786,7 +792,8 @@ Object.assign(CodemanApp.prototype, {
_refreshTunnelQrFromApi() {
fetch('/api/tunnel/qr')
.then(res => res.ok ? res.json() : null)
.then(data => {
.then(env => {
const data = env?.success === true ? env.data : env;
if (!data?.svg) return;
const container = document.getElementById('tunnelQrContainer');
if (container) container.innerHTML = data.svg;
@@ -901,7 +908,8 @@ Object.assign(CodemanApp.prototype, {
this._tunnelPollTimer = setTimeout(async () => {
try {
const res = await fetch('/api/tunnel/status');
const status = await res.json();
const env = await res.json();
const status = env?.success === true ? env.data : env;
if (status.running && status.url) {
// Tunnel is up — update UI
this._dismissTunnelConnecting();
@@ -960,7 +968,7 @@ Object.assign(CodemanApp.prototype, {
}
fetch('/api/tunnel/qr')
.then(r => { if (!r.ok) throw new Error(); return r.json(); })
.then(data => { if (data.svg) qrInner.innerHTML = data.svg; })
.then(env => { const data = env?.success === true ? env.data : env; if (data.svg) qrInner.innerHTML = data.svg; })
.catch(() => { qrInner.innerHTML = '<div style="color:#999;font-size:11px;padding:20px">QR unavailable</div>'; });
} else {
clearTimeout(this._welcomeQrShrinkTimer);
@@ -1032,7 +1040,8 @@ Object.assign(CodemanApp.prototype, {
// Fetch tunnel info
try {
const res = await fetch('/api/tunnel/info');
const info = await res.json();
const env = await res.json();
const info = env?.success === true ? env.data : env;
this._renderTunnelPanel(info);
} catch {
const body = document.getElementById('tunnelPanelBody');
@@ -1166,7 +1175,8 @@ Object.assign(CodemanApp.prototype, {
this.showToast('All sessions revoked', 'success');
// Refresh panel
const res = await fetch('/api/tunnel/info');
const info = await res.json();
const env = await res.json();
const info = env?.success === true ? env.data : env;
this._renderTunnelPanel(info);
} catch {
this.showToast('Failed to revoke sessions', 'error');
@@ -1261,7 +1271,8 @@ Object.assign(CodemanApp.prototype, {
try {
const res = await fetch(`/api/session-lifecycle?${params}`);
const data = await res.json();
const env = await res.json();
const data = env?.success === true ? env.data : env;
const tbody = document.getElementById('lifecycleTableBody');
const empty = document.getElementById('lifecycleEmpty');
@@ -1850,7 +1861,7 @@ Object.assign(CodemanApp.prototype, {
async loadAppSettingsFromServer(settingsPromise = null) {
try {
const settings = settingsPromise ? await settingsPromise : await fetch('/api/settings').then(r => r.ok ? r.json() : null);
const settings = settingsPromise ? await settingsPromise : await fetch('/api/settings').then(r => r.ok ? r.json() : null).then(env => env?.success === true ? env.data : env);
if (settings) {
// Extract notification prefs before merging app settings
const { notificationPreferences, voiceSettings, respawnPresets, runMode, ...appSettings } = settings;
@@ -1942,7 +1953,8 @@ Object.assign(CodemanApp.prototype, {
try {
const res = await fetch('/api/subagent-window-states');
if (res.ok) {
states = await res.json();
const env = await res.json();
states = env?.success === true ? env.data : env;
// Also update localStorage
localStorage.setItem('codeman-subagent-window-states', JSON.stringify(states));
}
@@ -2009,7 +2021,8 @@ Object.assign(CodemanApp.prototype, {
try {
const res = await fetch('/api/subagent-parents');
if (res.ok) {
mapData = await res.json();
const env = await res.json();
mapData = env?.success === true ? env.data : env;
// Update localStorage as cache
localStorage.setItem('codeman-subagent-parents', JSON.stringify(mapData));
}
+5 -5
View File
@@ -868,7 +868,7 @@ Object.assign(CodemanApp.prototype, {
async _fetchHistorySessions() {
const res = await fetch('/api/history/sessions');
const data = await res.json();
const sessions = data.sessions || [];
const sessions = data.data?.sessions || [];
if (sessions.length === 0) return [];
const byProject = new Map();
@@ -1046,7 +1046,7 @@ Object.assign(CodemanApp.prototype, {
// Prefer already-loaded this.cases to avoid an extra request.
const casesPromise = Array.isArray(this.cases) && this.cases.length > 0
? Promise.resolve(this.cases)
: fetch('/api/cases').then((r) => (r.ok ? r.json() : [])).catch(() => []);
: fetch('/api/cases').then((r) => (r.ok ? r.json() : null)).then((d) => d?.data || []).catch(() => []);
const [allSessions, cases] = await Promise.all([
this._fetchHistorySessions(30),
casesPromise,
@@ -1173,8 +1173,8 @@ Object.assign(CodemanApp.prototype, {
const url = `/api/history/sessions?projectKey=${encodeURIComponent(projectKey)}&offset=${offset}&limit=${limit}`;
const res = await fetch(url);
const data = await res.json();
const sessions = data.sessions || [];
state.total = typeof data.total === 'number' ? data.total : sessions.length + offset;
const sessions = data.data?.sessions || [];
state.total = typeof data.data?.total === 'number' ? data.data.total : sessions.length + offset;
if (offset === 0 && sessions.length === 0) {
const empty = document.createElement('div');
@@ -1261,7 +1261,7 @@ Object.assign(CodemanApp.prototype, {
const createData = await createRes.json();
if (!createData.success) throw new Error(createData.error);
const newSessionId = createData.session.id;
const newSessionId = createData.data.session.id;
// Start interactive
await fetch(`/api/sessions/${newSessionId}/interactive`, { method: 'POST' });