fix: trim API key whitespace, handle non-JSON 200s, improve timeout errors

- Trim leading/trailing whitespace from VALIDKIT_API_KEY (prevents
  silent 401s from copy-paste errors)
- Return ok:false when response.json() fails, even on 200 status
  (prevents CDN challenge pages being serialized as success)
- Extract formatCatchError() helper with DOMException TimeoutError
  detection — shows "timed out after 30 seconds" instead of
  "operation was aborted"
- Add 3 new tests (37 total, 100% coverage)

Author: jesse-validkit

src/index.test.ts

@@ -565,5 +565,64 @@ describe('ValidKit MCP Server', () => {
       expect(result.isError).toBe(true);
       expect(getText(result)).toContain('VALIDKIT_API_KEY');
     });
+
+    it('trims whitespace from API key', async () => {
+      process.env.VALIDKIT_API_KEY = '  vk_test_padded  ';
+      const { client } = await createTestClient();
+      mockFetchResponse(200, { email: 'a@b.com', valid: true });
+
+      await client.callTool({
+        name: 'validate_email',
+        arguments: { email: 'a@b.com' },
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            'X-API-Key': 'vk_test_padded',
+          }),
+        })
+      );
+    });
+
+    it('handles non-JSON response on 200 as error', async () => {
+      const { client } = await createTestClient();
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => {
+          throw new SyntaxError('Unexpected token <');
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'validate_email',
+        arguments: { email: 'test@gmail.com' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(getText(result)).toContain('Non-JSON response');
+      expect(getText(result)).toContain('200');
+    });
+
+    it('shows user-friendly timeout error message', async () => {
+      const { client } = await createTestClient();
+      const timeoutError = new DOMException(
+        'The operation was aborted',
+        'TimeoutError'
+      );
+      mockFetch.mockRejectedValueOnce(timeoutError);
+
+      const result = await client.callTool({
+        name: 'validate_email',
+        arguments: { email: 'test@gmail.com' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(getText(result)).toContain('timed out');
+      expect(getText(result)).toContain('30 seconds');
+      expect(getText(result)).not.toContain('was aborted');
+    });
   });
 });

src/index.ts

@@ -8,6 +8,14 @@ import { z } from 'zod';
 export const VERSION = '1.1.0';
 const REQUEST_TIMEOUT_MS = 30_000;
 
+export function formatCatchError(error: unknown, prefix: string): string {
+  if (error instanceof DOMException && error.name === 'TimeoutError') {
+    return `${prefix}: Request timed out after ${REQUEST_TIMEOUT_MS / 1000} seconds. The ValidKit API may be slow or unreachable. Try again.`;
+  }
+  const message = error instanceof Error ? error.message : 'Unknown error';
+  return `${prefix}: ${message}`;
+}
+
 export function getApiBaseUrl(): string {
   const url = process.env.VALIDKIT_API_URL || 'https://api.validkit.com';
   if (!url.startsWith('https://')) {
@@ -25,7 +33,7 @@ export function getApiKey(): string {
       'VALIDKIT_API_KEY environment variable is required. Get your free API key at https://validkit.com/get-started'
     );
   }
-  return key;
+  return key.trim();
 }
 
 export async function callApi(
@@ -50,9 +58,13 @@ export async function callApi(
   try {
     data = await response.json();
   } catch {
-    data = {
-      error: {
-        message: `Non-JSON response (HTTP ${response.status})`,
+    return {
+      ok: false,
+      status: response.status,
+      data: {
+        error: {
+          message: `Non-JSON response (HTTP ${response.status})`,
+        },
       },
     };
   }
@@ -128,13 +140,11 @@ export function createServer(): McpServer {
           ],
         };
       } catch (error) {
-        const message =
-          error instanceof Error ? error.message : 'Unknown error';
         return {
           content: [
             {
               type: 'text' as const,
-              text: `Failed to validate email: ${message}`,
+              text: formatCatchError(error, 'Failed to validate email'),
             },
           ],
           isError: true,
@@ -179,13 +189,11 @@ export function createServer(): McpServer {
           ],
         };
       } catch (error) {
-        const message =
-          error instanceof Error ? error.message : 'Unknown error';
         return {
           content: [
             {
               type: 'text' as const,
-              text: `Failed to validate emails: ${message}`,
+              text: formatCatchError(error, 'Failed to validate emails'),
             },
           ],
           isError: true,
@@ -219,13 +227,11 @@ export function createServer(): McpServer {
           ],
         };
       } catch (error) {
-        const message =
-          error instanceof Error ? error.message : 'Unknown error';
         return {
           content: [
             {
               type: 'text' as const,
-              text: `Failed to check usage: ${message}`,
+              text: formatCatchError(error, 'Failed to check usage'),
             },
           ],
           isError: true,