@vibescope/mcp-server 0.4.9 → 0.5.1

package/src/api-client.test.ts

@@ -1,847 +1,847 @@
-/**
- * API Client Tests
- *
- * Tests for the VibescopeApiClient class that handles all HTTP communication
- * with the Vibescope API.
- */
-
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-
-// Unmock the api-client module so we test the real implementation
-vi.unmock('./api-client.js');
-vi.unmock('../api-client.js');
-
-// Import after unmocking
-import { VibescopeApiClient } from './api-client.js';
-
-// ============================================================================
-// Test Setup
-// ============================================================================
-
-// Mock fetch globally
-const mockFetch = vi.fn();
-global.fetch = mockFetch;
-
-// Helper to create mock response
-function createMockResponse(data: unknown, ok = true, status = 200, headers?: Record<string, string>) {
-	return {
-		ok,
-		status,
-		json: vi.fn().mockResolvedValue(data),
-		headers: {
-			get: (name: string) => headers?.[name] ?? null,
-		},
-	};
-}
-
-// Helper to create network error
-function createNetworkError(message: string) {
-	return new Error(message);
-}
-
-// Fast retry config for tests (1ms delays instead of 1000ms)
-const FAST_RETRY_CONFIG = {
-	maxRetries: 3,
-	baseDelayMs: 1,
-	maxDelayMs: 10,
-	retryStatusCodes: [429, 503, 504],
-};
-
-describe('VibescopeApiClient', () => {
-	let client: VibescopeApiClient;
-
-	beforeEach(() => {
-		vi.clearAllMocks();
-		// Use fast retry config so tests don't take forever
-		client = new VibescopeApiClient({ apiKey: 'test-api-key', retry: FAST_RETRY_CONFIG });
-	});
-
-	afterEach(() => {
-		vi.resetAllMocks();
-	});
-
-	// ============================================================================
-	// Constructor Tests
-	// ============================================================================
-
-	describe('constructor', () => {
-		it('should use default API URL when not provided', () => {
-			const c = new VibescopeApiClient({ apiKey: 'test-key' });
-			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
-
-			// Trigger a request to verify the URL
-			c.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('https://vibescope.dev'),
-				expect.any(Object)
-			);
-		});
-
-		it('should use custom baseUrl when provided', () => {
-			const c = new VibescopeApiClient({
-				apiKey: 'test-key',
-				baseUrl: 'https://custom.api.com',
-			});
-			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
-
-			c.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('https://custom.api.com'),
-				expect.any(Object)
-			);
-		});
-
-		it('should use VIBESCOPE_API_URL env var when set', () => {
-			const originalEnv = process.env.VIBESCOPE_API_URL;
-			process.env.VIBESCOPE_API_URL = 'https://env-api.com';
-
-			const c = new VibescopeApiClient({ apiKey: 'test-key' });
-			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
-
-			c.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('https://env-api.com'),
-				expect.any(Object)
-			);
-
-			// Restore
-			if (originalEnv !== undefined) {
-				process.env.VIBESCOPE_API_URL = originalEnv;
-			} else {
-				delete process.env.VIBESCOPE_API_URL;
-			}
-		});
-	});
-
-	// ============================================================================
-	// Request Method Tests (via validateAuth)
-	// ============================================================================
-
-	describe('request method', () => {
-		it('should send correct headers', async () => {
-			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
-
-			await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.any(String),
-				expect.objectContaining({
-					method: 'POST',
-					headers: {
-						'Content-Type': 'application/json',
-						'X-API-Key': 'test-api-key',
-					},
-				})
-			);
-		});
-
-		it('should return success response on 2xx status', async () => {
-			const responseData = { valid: true, user_id: 'user-123' };
-			mockFetch.mockResolvedValue(createMockResponse(responseData, true, 200));
-
-			const result = await client.validateAuth();
-
-			expect(result).toEqual({
-				ok: true,
-				status: 200,
-				data: responseData,
-			});
-		});
-
-		it('should return error response on 4xx status', async () => {
-			const errorData = { error: 'Invalid API key' };
-			mockFetch.mockResolvedValue(createMockResponse(errorData, false, 401));
-
-			const result = await client.validateAuth();
-
-			expect(result).toEqual({
-				ok: false,
-				status: 401,
-				error: 'Invalid API key',
-				data: errorData,
-			});
-		});
-
-		it('should return error response on 5xx status', async () => {
-			const errorData = { error: 'Internal server error' };
-			mockFetch.mockResolvedValue(createMockResponse(errorData, false, 500));
-
-			const result = await client.validateAuth();
-
-			expect(result).toEqual({
-				ok: false,
-				status: 500,
-				error: 'Internal server error',
-				data: errorData,
-			});
-		});
-
-		it('should handle missing error field in error response', async () => {
-			const errorData = { message: 'Something went wrong' };
-			mockFetch.mockResolvedValue(createMockResponse(errorData, false, 400));
-
-			const result = await client.validateAuth();
-
-			expect(result).toEqual({
-				ok: false,
-				status: 400,
-				error: 'HTTP 400',
-				data: errorData,
-			});
-		});
-
-		it('should handle network errors after retries', async () => {
-			mockFetch.mockRejectedValue(createNetworkError('Network request failed'));
-
-			const result = await client.validateAuth();
-
-			// Network errors are retried, so 4 attempts total (1 initial + 3 retries)
-			expect(mockFetch).toHaveBeenCalledTimes(4);
-			expect(result).toEqual({
-				ok: false,
-				status: 0,
-				error: 'Network request failed',
-			});
-		}, 30000);
-
-		it('should handle non-Error exceptions after retries', async () => {
-			mockFetch.mockRejectedValue('String error');
-
-			const result = await client.validateAuth();
-
-			// Non-Error exceptions are converted to Error('Network error') and retried
-			expect(mockFetch).toHaveBeenCalledTimes(4);
-			expect(result).toEqual({
-				ok: false,
-				status: 0,
-				error: 'Network error',
-			});
-		}, 30000);
-	});
-
-	// ============================================================================
-	// Auth Endpoints
-	// ============================================================================
-
-	describe('validateAuth', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
-
-			await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/auth/validate'),
-				expect.objectContaining({
-					method: 'POST',
-					body: JSON.stringify({ api_key: 'test-api-key' }),
-				})
-			);
-		});
-	});
-
-	// ============================================================================
-	// Session Endpoints
-	// ============================================================================
-
-	describe('startSession', () => {
-		it('should call correct endpoint with params', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ session_started: true, session_id: 'session-123' })
-			);
-
-			await client.startSession({
-				project_id: 'proj-123',
-				mode: 'lite',
-				model: 'opus',
-			});
-
-			const [url, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
-			const body = JSON.parse(opts.body as string);
-			expect(url).toContain('/api/mcp/sessions/start');
-			expect(opts.method).toBe('POST');
-			expect(body).toMatchObject({
-				project_id: 'proj-123',
-				mode: 'lite',
-				model: 'opus',
-			});
-			expect(body.instance_id).toBeDefined();
-		});
-
-		it('should support git_url param', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ session_started: true })
-			);
-
-			await client.startSession({
-				git_url: 'https://github.com/org/repo',
-			});
-
-			const [, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
-			const body = JSON.parse(opts.body as string);
-			expect(body).toMatchObject({
-				git_url: 'https://github.com/org/repo',
-			});
-			expect(body.instance_id).toBeDefined();
-		});
-	});
-
-	describe('heartbeat', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ timestamp: '2026-01-14T10:00:00Z' })
-			);
-
-			await client.heartbeat('session-123');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/sessions/heartbeat'),
-				expect.objectContaining({
-					method: 'POST',
-					body: JSON.stringify({ session_id: 'session-123' }),
-				})
-			);
-		});
-
-		it('should pass worktree path option', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ timestamp: '2026-01-14T10:00:00Z' })
-			);
-
-			await client.heartbeat('session-123', {
-				current_worktree_path: '../project-task-abc',
-			});
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.any(String),
-				expect.objectContaining({
-					body: JSON.stringify({
-						session_id: 'session-123',
-						current_worktree_path: '../project-task-abc',
-					}),
-				})
-			);
-		});
-	});
-
-	describe('endSession', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ success: true })
-			);
-
-			await client.endSession('session-123');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/sessions/end'),
-				expect.objectContaining({
-					method: 'POST',
-					body: JSON.stringify({ session_id: 'session-123' }),
-				})
-			);
-		});
-	});
-
-	// ============================================================================
-	// Project Endpoints
-	// ============================================================================
-
-	describe('listProjects', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ projects: [] })
-			);
-
-			await client.listProjects();
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/projects'),
-				expect.objectContaining({ method: 'GET' })
-			);
-		});
-	});
-
-	describe('getProject', () => {
-		it('should call correct endpoint with project ID', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ project: { id: 'proj-123', name: 'Test' } })
-			);
-
-			await client.getProject('proj-123');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/projects/proj-123'),
-				expect.objectContaining({ method: 'GET' })
-			);
-		});
-
-		it('should include git_url param when provided', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ project: { id: 'proj-123' } })
-			);
-
-			await client.getProject('proj-123', 'https://github.com/org/repo');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('git_url=https'),
-				expect.any(Object)
-			);
-		});
-	});
-
-	describe('createProject', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ project: { id: 'new-proj' } })
-			);
-
-			await client.createProject({
-				name: 'New Project',
-				description: 'Test description',
-			});
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/projects'),
-				expect.objectContaining({
-					method: 'POST',
-					body: JSON.stringify({
-						name: 'New Project',
-						description: 'Test description',
-					}),
-				})
-			);
-		});
-	});
-
-	describe('updateProject', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ success: true })
-			);
-
-			await client.updateProject('proj-123', {
-				name: 'Updated Name',
-				status: 'active',
-			});
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/projects/proj-123'),
-				expect.objectContaining({
-					method: 'PATCH',
-					body: JSON.stringify({
-						name: 'Updated Name',
-						status: 'active',
-					}),
-				})
-			);
-		});
-	});
-
-	// ============================================================================
-	// Task Endpoints
-	// ============================================================================
-
-	describe('getTasks', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ tasks: [] })
-			);
-
-			await client.getTasks('proj-123');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/projects/proj-123/tasks'),
-				expect.objectContaining({ method: 'GET' })
-			);
-		});
-
-		it('should include filter params', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ tasks: [] })
-			);
-
-			await client.getTasks('proj-123', {
-				status: 'in_progress',
-				limit: 10,
-			});
-
-			const url = mockFetch.mock.calls[0][0] as string;
-			expect(url).toContain('status=in_progress');
-			expect(url).toContain('limit=10');
-		});
-	});
-
-	describe('createTask', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ task: { id: 'task-123' } })
-			);
-
-			await client.createTask('proj-123', {
-				title: 'New Task',
-				priority: 2,
-			});
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/projects/proj-123/tasks'),
-				expect.objectContaining({
-					method: 'POST',
-					body: JSON.stringify({
-						title: 'New Task',
-						priority: 2,
-					}),
-				})
-			);
-		});
-	});
-
-	describe('updateTask', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ success: true })
-			);
-
-			await client.updateTask('task-123', {
-				status: 'in_progress',
-				progress_percentage: 50,
-			});
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/tasks/task-123'),
-				expect.objectContaining({
-					method: 'PATCH',
-					body: JSON.stringify({
-						status: 'in_progress',
-						progress_percentage: 50,
-					}),
-				})
-			);
-		});
-	});
-
-	describe('completeTask', () => {
-		it('should call proxy endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ success: true })
-			);
-
-			await client.completeTask('task-123', {
-				summary: 'Task completed successfully',
-			});
-
-			// completeTask uses proxy endpoint for consistency (direct endpoint had Vercel routing issues)
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/proxy'),
-				expect.objectContaining({
-					method: 'POST',
-					body: JSON.stringify({
-						operation: 'complete_task',
-						args: {
-							task_id: 'task-123',
-							summary: 'Task completed successfully',
-						},
-					}),
-				})
-			);
-		});
-	});
-
-	describe('deleteTask', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ success: true })
-			);
-
-			await client.deleteTask('task-123');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/tasks/task-123'),
-				expect.objectContaining({ method: 'DELETE' })
-			);
-		});
-	});
-
-	describe('getNextTask', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ task: { id: 'task-123', title: 'Next task' } })
-			);
-
-			await client.getNextTask('proj-123');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/projects/proj-123/next-task'),
-				expect.objectContaining({ method: 'GET' })
-			);
-		});
-
-		it('should include session_id when provided', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ task: null })
-			);
-
-			await client.getNextTask('proj-123', 'session-456');
-
-			const url = mockFetch.mock.calls[0][0] as string;
-			expect(url).toContain('session_id=session-456');
-		});
-	});
-
-	// ============================================================================
-	// Blocker Endpoints
-	// ============================================================================
-
-	describe('getBlockers', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ blockers: [] })
-			);
-
-			await client.getBlockers('proj-123');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/proxy'),
-				expect.objectContaining({ method: 'POST' })
-			);
-		});
-	});
-
-	describe('addBlocker', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ blocker_id: 'blocker-123' })
-			);
-
-			await client.addBlocker('proj-123', 'Blocked by dependency');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/proxy'),
-				expect.objectContaining({ method: 'POST' })
-			);
-		});
-	});
-
-	// ============================================================================
-	// Validation Endpoints
-	// ============================================================================
-
-	describe('getTasksAwaitingValidation', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ tasks: [] })
-			);
-
-			await client.getTasksAwaitingValidation('proj-123');
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/proxy'),
-				expect.objectContaining({ method: 'POST' })
-			);
-		});
-	});
-
-	describe('validateTask', () => {
-		it('should call correct endpoint', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ success: true })
-			);
-
-			await client.validateTask('task-123', {
-				approved: true,
-				validation_notes: 'All tests pass',
-			});
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/proxy'),
-				expect.objectContaining({ method: 'POST' })
-			);
-		});
-	});
-
-	// ============================================================================
-	// Proxy Endpoint
-	// ============================================================================
-
-	describe('proxy', () => {
-		it('should call proxy endpoint with operation', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ result: 'success' })
-			);
-
-			await client.proxy('custom_operation', { param1: 'value1' });
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.stringContaining('/api/mcp/proxy'),
-				expect.objectContaining({
-					method: 'POST',
-					body: expect.stringContaining('custom_operation'),
-				})
-			);
-		});
-
-		it('should pass session context when provided', async () => {
-			mockFetch.mockResolvedValue(
-				createMockResponse({ result: 'success' })
-			);
-
-			await client.proxy(
-				'operation',
-				{ arg: 'value' },
-				{ sessionId: 'session-123', persona: 'Wave' }
-			);
-
-			expect(mockFetch).toHaveBeenCalledWith(
-				expect.any(String),
-				expect.objectContaining({
-					body: expect.stringContaining('session-123'),
-				})
-			);
-		});
-	});
-
-	// ============================================================================
-	// Error Handling Edge Cases
-	// ============================================================================
-
-	describe('error handling edge cases', () => {
-		it('should handle JSON parse error in response after retries', async () => {
-			mockFetch.mockResolvedValue({
-				ok: true,
-				status: 200,
-				json: vi.fn().mockRejectedValue(new SyntaxError('Invalid JSON')),
-				headers: { get: () => null },
-			});
-
-			const result = await client.validateAuth();
-
-			// JSON parse errors are treated as network errors and retried
-			expect(mockFetch).toHaveBeenCalledTimes(4);
-			expect(result.ok).toBe(false);
-			expect(result.error).toContain('Invalid JSON');
-		}, 30000);
-
-		it('should handle timeout errors after retries', async () => {
-			const timeoutError = new Error('Request timeout');
-			timeoutError.name = 'AbortError';
-			mockFetch.mockRejectedValue(timeoutError);
-
-			const result = await client.validateAuth();
-
-			// Timeout errors are retried
-			expect(mockFetch).toHaveBeenCalledTimes(4);
-			expect(result).toEqual({
-				ok: false,
-				status: 0,
-				error: 'Request timeout',
-			});
-		}, 30000);
-	});
-
-	// ============================================================================
-	// Retry Logic Tests
-	// ============================================================================
-
-	describe('retry logic', () => {
-		it('should retry on 429 status code', async () => {
-			// First two calls return 429, third succeeds
-			mockFetch
-				.mockResolvedValueOnce(createMockResponse({ error: 'Rate limited' }, false, 429))
-				.mockResolvedValueOnce(createMockResponse({ error: 'Rate limited' }, false, 429))
-				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(3);
-			expect(result.ok).toBe(true);
-		});
-
-		it('should retry on 503 status code', async () => {
-			mockFetch
-				.mockResolvedValueOnce(createMockResponse({ error: 'Service unavailable' }, false, 503))
-				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(2);
-			expect(result.ok).toBe(true);
-		});
-
-		it('should retry on 504 status code', async () => {
-			mockFetch
-				.mockResolvedValueOnce(createMockResponse({ error: 'Gateway timeout' }, false, 504))
-				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(2);
-			expect(result.ok).toBe(true);
-		});
-
-		it('should not retry on non-retryable status codes (400)', async () => {
-			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Bad request' }, false, 400));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(1);
-			expect(result.ok).toBe(false);
-			expect(result.status).toBe(400);
-		});
-
-		it('should not retry on non-retryable status codes (401)', async () => {
-			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Unauthorized' }, false, 401));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(1);
-			expect(result.ok).toBe(false);
-			expect(result.status).toBe(401);
-		});
-
-		it('should not retry on non-retryable status codes (500)', async () => {
-			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Server error' }, false, 500));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(1);
-			expect(result.ok).toBe(false);
-			expect(result.status).toBe(500);
-		});
-
-		it('should stop after max retries (3)', async () => {
-			// All 4 attempts (1 initial + 3 retries) return 429
-			mockFetch.mockResolvedValue(createMockResponse({ error: 'Rate limited' }, false, 429));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(4); // 1 initial + 3 retries
-			expect(result.ok).toBe(false);
-			expect(result.status).toBe(429);
-			// API error message takes precedence over generic retry message
-			expect(result.error).toBe('Rate limited');
-		}, 30000);
-
-		it('should retry on network errors', async () => {
-			mockFetch
-				.mockRejectedValueOnce(new Error('Network error'))
-				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(2);
-			expect(result.ok).toBe(true);
-		}, 10000);
-
-		it('should return last error after all retries exhausted on network failure', async () => {
-			mockFetch.mockRejectedValue(new Error('Connection refused'));
-
-			const result = await client.validateAuth();
-
-			expect(mockFetch).toHaveBeenCalledTimes(4);
-			expect(result.ok).toBe(false);
-			expect(result.status).toBe(0);
-			expect(result.error).toBe('Connection refused');
-		}, 30000);
-	});
-});
+/**
+ * API Client Tests
+ *
+ * Tests for the VibescopeApiClient class that handles all HTTP communication
+ * with the Vibescope API.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Unmock the api-client module so we test the real implementation
+vi.unmock('./api-client.js');
+vi.unmock('../api-client.js');
+
+// Import after unmocking
+import { VibescopeApiClient } from './api-client.js';
+
+// ============================================================================
+// Test Setup
+// ============================================================================
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+// Helper to create mock response
+function createMockResponse(data: unknown, ok = true, status = 200, headers?: Record<string, string>) {
+	return {
+		ok,
+		status,
+		json: vi.fn().mockResolvedValue(data),
+		headers: {
+			get: (name: string) => headers?.[name] ?? null,
+		},
+	};
+}
+
+// Helper to create network error
+function createNetworkError(message: string) {
+	return new Error(message);
+}
+
+// Fast retry config for tests (1ms delays instead of 1000ms)
+const FAST_RETRY_CONFIG = {
+	maxRetries: 3,
+	baseDelayMs: 1,
+	maxDelayMs: 10,
+	retryStatusCodes: [429, 503, 504],
+};
+
+describe('VibescopeApiClient', () => {
+	let client: VibescopeApiClient;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		// Use fast retry config so tests don't take forever
+		client = new VibescopeApiClient({ apiKey: 'test-api-key', retry: FAST_RETRY_CONFIG });
+	});
+
+	afterEach(() => {
+		vi.resetAllMocks();
+	});
+
+	// ============================================================================
+	// Constructor Tests
+	// ============================================================================
+
+	describe('constructor', () => {
+		it('should use default API URL when not provided', () => {
+			const c = new VibescopeApiClient({ apiKey: 'test-key' });
+			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
+
+			// Trigger a request to verify the URL
+			c.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('https://vibescope.dev'),
+				expect.any(Object)
+			);
+		});
+
+		it('should use custom baseUrl when provided', () => {
+			const c = new VibescopeApiClient({
+				apiKey: 'test-key',
+				baseUrl: 'https://custom.api.com',
+			});
+			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
+
+			c.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('https://custom.api.com'),
+				expect.any(Object)
+			);
+		});
+
+		it('should use VIBESCOPE_API_URL env var when set', () => {
+			const originalEnv = process.env.VIBESCOPE_API_URL;
+			process.env.VIBESCOPE_API_URL = 'https://env-api.com';
+
+			const c = new VibescopeApiClient({ apiKey: 'test-key' });
+			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
+
+			c.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('https://env-api.com'),
+				expect.any(Object)
+			);
+
+			// Restore
+			if (originalEnv !== undefined) {
+				process.env.VIBESCOPE_API_URL = originalEnv;
+			} else {
+				delete process.env.VIBESCOPE_API_URL;
+			}
+		});
+	});
+
+	// ============================================================================
+	// Request Method Tests (via validateAuth)
+	// ============================================================================
+
+	describe('request method', () => {
+		it('should send correct headers', async () => {
+			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
+
+			await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.any(String),
+				expect.objectContaining({
+					method: 'POST',
+					headers: {
+						'Content-Type': 'application/json',
+						'X-API-Key': 'test-api-key',
+					},
+				})
+			);
+		});
+
+		it('should return success response on 2xx status', async () => {
+			const responseData = { valid: true, user_id: 'user-123' };
+			mockFetch.mockResolvedValue(createMockResponse(responseData, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(result).toEqual({
+				ok: true,
+				status: 200,
+				data: responseData,
+			});
+		});
+
+		it('should return error response on 4xx status', async () => {
+			const errorData = { error: 'Invalid API key' };
+			mockFetch.mockResolvedValue(createMockResponse(errorData, false, 401));
+
+			const result = await client.validateAuth();
+
+			expect(result).toEqual({
+				ok: false,
+				status: 401,
+				error: 'Invalid API key',
+				data: errorData,
+			});
+		});
+
+		it('should return error response on 5xx status', async () => {
+			const errorData = { error: 'Internal server error' };
+			mockFetch.mockResolvedValue(createMockResponse(errorData, false, 500));
+
+			const result = await client.validateAuth();
+
+			expect(result).toEqual({
+				ok: false,
+				status: 500,
+				error: 'Internal server error',
+				data: errorData,
+			});
+		});
+
+		it('should handle missing error field in error response', async () => {
+			const errorData = { message: 'Something went wrong' };
+			mockFetch.mockResolvedValue(createMockResponse(errorData, false, 400));
+
+			const result = await client.validateAuth();
+
+			expect(result).toEqual({
+				ok: false,
+				status: 400,
+				error: 'HTTP 400',
+				data: errorData,
+			});
+		});
+
+		it('should handle network errors after retries', async () => {
+			mockFetch.mockRejectedValue(createNetworkError('Network request failed'));
+
+			const result = await client.validateAuth();
+
+			// Network errors are retried, so 4 attempts total (1 initial + 3 retries)
+			expect(mockFetch).toHaveBeenCalledTimes(4);
+			expect(result).toEqual({
+				ok: false,
+				status: 0,
+				error: 'Network request failed',
+			});
+		}, 30000);
+
+		it('should handle non-Error exceptions after retries', async () => {
+			mockFetch.mockRejectedValue('String error');
+
+			const result = await client.validateAuth();
+
+			// Non-Error exceptions are converted to Error('Network error') and retried
+			expect(mockFetch).toHaveBeenCalledTimes(4);
+			expect(result).toEqual({
+				ok: false,
+				status: 0,
+				error: 'Network error',
+			});
+		}, 30000);
+	});
+
+	// ============================================================================
+	// Auth Endpoints
+	// ============================================================================
+
+	describe('validateAuth', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(createMockResponse({ valid: true }));
+
+			await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/auth/validate'),
+				expect.objectContaining({
+					method: 'POST',
+					body: JSON.stringify({ api_key: 'test-api-key' }),
+				})
+			);
+		});
+	});
+
+	// ============================================================================
+	// Session Endpoints
+	// ============================================================================
+
+	describe('startSession', () => {
+		it('should call correct endpoint with params', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ session_started: true, session_id: 'session-123' })
+			);
+
+			await client.startSession({
+				project_id: 'proj-123',
+				mode: 'lite',
+				model: 'opus',
+			});
+
+			const [url, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
+			const body = JSON.parse(opts.body as string);
+			expect(url).toContain('/api/mcp/sessions/start');
+			expect(opts.method).toBe('POST');
+			expect(body).toMatchObject({
+				project_id: 'proj-123',
+				mode: 'lite',
+				model: 'opus',
+			});
+			expect(body.instance_id).toBeDefined();
+		});
+
+		it('should support git_url param', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ session_started: true })
+			);
+
+			await client.startSession({
+				git_url: 'https://github.com/org/repo',
+			});
+
+			const [, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
+			const body = JSON.parse(opts.body as string);
+			expect(body).toMatchObject({
+				git_url: 'https://github.com/org/repo',
+			});
+			expect(body.instance_id).toBeDefined();
+		});
+	});
+
+	describe('heartbeat', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ timestamp: '2026-01-14T10:00:00Z' })
+			);
+
+			await client.heartbeat('session-123');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/sessions/heartbeat'),
+				expect.objectContaining({
+					method: 'POST',
+					body: JSON.stringify({ session_id: 'session-123' }),
+				})
+			);
+		});
+
+		it('should pass worktree path option', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ timestamp: '2026-01-14T10:00:00Z' })
+			);
+
+			await client.heartbeat('session-123', {
+				current_worktree_path: '../project-task-abc',
+			});
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.any(String),
+				expect.objectContaining({
+					body: JSON.stringify({
+						session_id: 'session-123',
+						current_worktree_path: '../project-task-abc',
+					}),
+				})
+			);
+		});
+	});
+
+	describe('endSession', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ success: true })
+			);
+
+			await client.endSession('session-123');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/sessions/end'),
+				expect.objectContaining({
+					method: 'POST',
+					body: JSON.stringify({ session_id: 'session-123' }),
+				})
+			);
+		});
+	});
+
+	// ============================================================================
+	// Project Endpoints
+	// ============================================================================
+
+	describe('listProjects', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ projects: [] })
+			);
+
+			await client.listProjects();
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/projects'),
+				expect.objectContaining({ method: 'GET' })
+			);
+		});
+	});
+
+	describe('getProject', () => {
+		it('should call correct endpoint with project ID', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ project: { id: 'proj-123', name: 'Test' } })
+			);
+
+			await client.getProject('proj-123');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/projects/proj-123'),
+				expect.objectContaining({ method: 'GET' })
+			);
+		});
+
+		it('should include git_url param when provided', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ project: { id: 'proj-123' } })
+			);
+
+			await client.getProject('proj-123', 'https://github.com/org/repo');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('git_url=https'),
+				expect.any(Object)
+			);
+		});
+	});
+
+	describe('createProject', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ project: { id: 'new-proj' } })
+			);
+
+			await client.createProject({
+				name: 'New Project',
+				description: 'Test description',
+			});
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/projects'),
+				expect.objectContaining({
+					method: 'POST',
+					body: JSON.stringify({
+						name: 'New Project',
+						description: 'Test description',
+					}),
+				})
+			);
+		});
+	});
+
+	describe('updateProject', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ success: true })
+			);
+
+			await client.updateProject('proj-123', {
+				name: 'Updated Name',
+				status: 'active',
+			});
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/projects/proj-123'),
+				expect.objectContaining({
+					method: 'PATCH',
+					body: JSON.stringify({
+						name: 'Updated Name',
+						status: 'active',
+					}),
+				})
+			);
+		});
+	});
+
+	// ============================================================================
+	// Task Endpoints
+	// ============================================================================
+
+	describe('getTasks', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ tasks: [] })
+			);
+
+			await client.getTasks('proj-123');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/projects/proj-123/tasks'),
+				expect.objectContaining({ method: 'GET' })
+			);
+		});
+
+		it('should include filter params', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ tasks: [] })
+			);
+
+			await client.getTasks('proj-123', {
+				status: 'in_progress',
+				limit: 10,
+			});
+
+			const url = mockFetch.mock.calls[0][0] as string;
+			expect(url).toContain('status=in_progress');
+			expect(url).toContain('limit=10');
+		});
+	});
+
+	describe('createTask', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ task: { id: 'task-123' } })
+			);
+
+			await client.createTask('proj-123', {
+				title: 'New Task',
+				priority: 2,
+			});
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/projects/proj-123/tasks'),
+				expect.objectContaining({
+					method: 'POST',
+					body: JSON.stringify({
+						title: 'New Task',
+						priority: 2,
+					}),
+				})
+			);
+		});
+	});
+
+	describe('updateTask', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ success: true })
+			);
+
+			await client.updateTask('task-123', {
+				status: 'in_progress',
+				progress_percentage: 50,
+			});
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/tasks/task-123'),
+				expect.objectContaining({
+					method: 'PATCH',
+					body: JSON.stringify({
+						status: 'in_progress',
+						progress_percentage: 50,
+					}),
+				})
+			);
+		});
+	});
+
+	describe('completeTask', () => {
+		it('should call proxy endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ success: true })
+			);
+
+			await client.completeTask('task-123', {
+				summary: 'Task completed successfully',
+			});
+
+			// completeTask uses proxy endpoint for consistency (direct endpoint had Vercel routing issues)
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/proxy'),
+				expect.objectContaining({
+					method: 'POST',
+					body: JSON.stringify({
+						operation: 'complete_task',
+						args: {
+							task_id: 'task-123',
+							summary: 'Task completed successfully',
+						},
+					}),
+				})
+			);
+		});
+	});
+
+	describe('deleteTask', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ success: true })
+			);
+
+			await client.deleteTask('task-123');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/tasks/task-123'),
+				expect.objectContaining({ method: 'DELETE' })
+			);
+		});
+	});
+
+	describe('getNextTask', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ task: { id: 'task-123', title: 'Next task' } })
+			);
+
+			await client.getNextTask('proj-123');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/projects/proj-123/next-task'),
+				expect.objectContaining({ method: 'GET' })
+			);
+		});
+
+		it('should include session_id when provided', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ task: null })
+			);
+
+			await client.getNextTask('proj-123', 'session-456');
+
+			const url = mockFetch.mock.calls[0][0] as string;
+			expect(url).toContain('session_id=session-456');
+		});
+	});
+
+	// ============================================================================
+	// Blocker Endpoints
+	// ============================================================================
+
+	describe('getBlockers', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ blockers: [] })
+			);
+
+			await client.getBlockers('proj-123');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/proxy'),
+				expect.objectContaining({ method: 'POST' })
+			);
+		});
+	});
+
+	describe('addBlocker', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ blocker_id: 'blocker-123' })
+			);
+
+			await client.addBlocker('proj-123', 'Blocked by dependency');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/proxy'),
+				expect.objectContaining({ method: 'POST' })
+			);
+		});
+	});
+
+	// ============================================================================
+	// Validation Endpoints
+	// ============================================================================
+
+	describe('getTasksAwaitingValidation', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ tasks: [] })
+			);
+
+			await client.getTasksAwaitingValidation('proj-123');
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/proxy'),
+				expect.objectContaining({ method: 'POST' })
+			);
+		});
+	});
+
+	describe('validateTask', () => {
+		it('should call correct endpoint', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ success: true })
+			);
+
+			await client.validateTask('task-123', {
+				approved: true,
+				validation_notes: 'All tests pass',
+			});
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/proxy'),
+				expect.objectContaining({ method: 'POST' })
+			);
+		});
+	});
+
+	// ============================================================================
+	// Proxy Endpoint
+	// ============================================================================
+
+	describe('proxy', () => {
+		it('should call proxy endpoint with operation', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ result: 'success' })
+			);
+
+			await client.proxy('custom_operation', { param1: 'value1' });
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.stringContaining('/api/mcp/proxy'),
+				expect.objectContaining({
+					method: 'POST',
+					body: expect.stringContaining('custom_operation'),
+				})
+			);
+		});
+
+		it('should pass session context when provided', async () => {
+			mockFetch.mockResolvedValue(
+				createMockResponse({ result: 'success' })
+			);
+
+			await client.proxy(
+				'operation',
+				{ arg: 'value' },
+				{ sessionId: 'session-123', persona: 'Wave' }
+			);
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				expect.any(String),
+				expect.objectContaining({
+					body: expect.stringContaining('session-123'),
+				})
+			);
+		});
+	});
+
+	// ============================================================================
+	// Error Handling Edge Cases
+	// ============================================================================
+
+	describe('error handling edge cases', () => {
+		it('should handle JSON parse error in response after retries', async () => {
+			mockFetch.mockResolvedValue({
+				ok: true,
+				status: 200,
+				json: vi.fn().mockRejectedValue(new SyntaxError('Invalid JSON')),
+				headers: { get: () => null },
+			});
+
+			const result = await client.validateAuth();
+
+			// JSON parse errors are treated as network errors and retried
+			expect(mockFetch).toHaveBeenCalledTimes(4);
+			expect(result.ok).toBe(false);
+			expect(result.error).toContain('Invalid JSON');
+		}, 30000);
+
+		it('should handle timeout errors after retries', async () => {
+			const timeoutError = new Error('Request timeout');
+			timeoutError.name = 'AbortError';
+			mockFetch.mockRejectedValue(timeoutError);
+
+			const result = await client.validateAuth();
+
+			// Timeout errors are retried
+			expect(mockFetch).toHaveBeenCalledTimes(4);
+			expect(result).toEqual({
+				ok: false,
+				status: 0,
+				error: 'Request timeout',
+			});
+		}, 30000);
+	});
+
+	// ============================================================================
+	// Retry Logic Tests
+	// ============================================================================
+
+	describe('retry logic', () => {
+		it('should retry on 429 status code', async () => {
+			// First two calls return 429, third succeeds
+			mockFetch
+				.mockResolvedValueOnce(createMockResponse({ error: 'Rate limited' }, false, 429))
+				.mockResolvedValueOnce(createMockResponse({ error: 'Rate limited' }, false, 429))
+				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(3);
+			expect(result.ok).toBe(true);
+		});
+
+		it('should retry on 503 status code', async () => {
+			mockFetch
+				.mockResolvedValueOnce(createMockResponse({ error: 'Service unavailable' }, false, 503))
+				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(2);
+			expect(result.ok).toBe(true);
+		});
+
+		it('should retry on 504 status code', async () => {
+			mockFetch
+				.mockResolvedValueOnce(createMockResponse({ error: 'Gateway timeout' }, false, 504))
+				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(2);
+			expect(result.ok).toBe(true);
+		});
+
+		it('should not retry on non-retryable status codes (400)', async () => {
+			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Bad request' }, false, 400));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(1);
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(400);
+		});
+
+		it('should not retry on non-retryable status codes (401)', async () => {
+			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Unauthorized' }, false, 401));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(1);
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(401);
+		});
+
+		it('should not retry on non-retryable status codes (500)', async () => {
+			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Server error' }, false, 500));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(1);
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(500);
+		});
+
+		it('should stop after max retries (3)', async () => {
+			// All 4 attempts (1 initial + 3 retries) return 429
+			mockFetch.mockResolvedValue(createMockResponse({ error: 'Rate limited' }, false, 429));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(4); // 1 initial + 3 retries
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(429);
+			// API error message takes precedence over generic retry message
+			expect(result.error).toBe('Rate limited');
+		}, 30000);
+
+		it('should retry on network errors', async () => {
+			mockFetch
+				.mockRejectedValueOnce(new Error('Network error'))
+				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(2);
+			expect(result.ok).toBe(true);
+		}, 10000);
+
+		it('should return last error after all retries exhausted on network failure', async () => {
+			mockFetch.mockRejectedValue(new Error('Connection refused'));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(4);
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(0);
+			expect(result.error).toBe('Connection refused');
+		}, 30000);
+	});
+});