Merge pull request #839 from mogbonjubolaolasunkanmi-art/feature/cli-error-handling-setup

Add CLI timeout/JSON error handling, CHANGELOG, and Vitest coverage setup

Author: Tinna23

packages/cli/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-07-29
+
+### Added
+
+- Initial release of `@stellar-explain/cli`
+- `tx <hash>` command — explain a Stellar transaction by hash
+- `account <address>` command — explain a Stellar account by address
+- `health` command — check backend API health
+- `batch <file>` command — process a batch of lookups from a JSON file
+- `cache clear` command — clear local response cache
+- `version` command — show CLI and API versions
+- `--url` option — configure a custom backend URL
+- `--no-update-check` option — disable background update check
+- Local disk cache with in-memory fallback (`~/.stellar-explain/`)
+- Background update check on startup
+- Colored error output formatting

packages/cli/package.json

@@ -15,6 +15,8 @@
     "build:watch": "tsc --watch",
     "dev": "tsc --watch",
     "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "generate:man": "bash scripts/generate-man.sh",
@@ -29,6 +31,7 @@
   "devDependencies": {
     "typescript": "^5.5.0",
     "vitest": "^2.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
     "@types/node": "^20.0.0",
     "@changesets/cli": "^2.27.0"
   }

packages/cli/src/client/api.ts

@@ -5,20 +5,33 @@ export interface ApiResponse<T> {
   data: T;
 }
 
+const DEFAULT_TIMEOUT_MS = 30_000;
+
 export class ApiClient {
   private baseUrl: string;
+  private timeoutMs: number;
 
-  constructor(baseUrl: string) {
+  constructor(baseUrl: string, timeoutMs: number = DEFAULT_TIMEOUT_MS) {
     this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.timeoutMs = timeoutMs;
     warnInsecureUrl(this.baseUrl);
   }
 
   async get<T>(endpoint: string): Promise<T> {
     const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
     let response: Response;
     try {
-      response = await fetch(url);
+      response = await fetch(url, { signal: controller.signal });
     } catch (err: unknown) {
+      clearTimeout(timer);
+      if (err instanceof DOMException && err.name === 'AbortError') {
+        throw new Error(
+          `Request timed out after ${this.timeoutMs / 1000}s. Check your connection or try --timeout to increase the limit.`
+        );
+      }
       if (err instanceof TypeError) {
         const msg = String(err.message);
         if (msg.includes('ECONNREFUSED')) {
@@ -30,13 +43,25 @@ export class ApiClient {
       }
       throw err;
     }
+    clearTimeout(timer);
 
     if (!response.ok) {
-      throw new Error(`API error: ${response.status} ${response.statusText}`);
+      const bodyText = await response.text();
+      throw new Error(
+        `API error: ${response.status} ${response.statusText} — ${bodyText.slice(0, 200)}`
+      );
     }
 
-    const body = (await response.json()) as ApiResponse<T>;
-    return body.data;
+    const raw = await response.text();
+    let parsed: ApiResponse<T>;
+    try {
+      parsed = JSON.parse(raw) as ApiResponse<T>;
+    } catch {
+      throw new Error(
+        `Unexpected response from API at ${url}. Expected JSON but received:\n${raw.slice(0, 300)}`
+      );
+    }
+    return parsed.data;
   }
 
   async health(): Promise<{ status: string; horizon_reachable: boolean; version: string }> {

packages/cli/tests/client/api.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ApiClient } from '../../src/client/api.js';
+
+const BASE_URL = 'https://stellar-explain-core.onrender.com';
+
+describe('ApiClient', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('throws a friendly message when API returns non-JSON response', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response('<html>502 Bad Gateway</html>', {
+        status: 502,
+        statusText: 'Bad Gateway',
+        headers: { 'content-type': 'text/html' },
+      })
+    );
+
+    const client = new ApiClient(BASE_URL, 10_000);
+    await expect(client.health()).rejects.toThrow('Unexpected response from API');
+  });
+
+  it('throws a friendly message on network timeout', async () => {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(
+      () =>
+        new Promise((_, reject) => {
+          const err = new DOMException('The operation was aborted', 'AbortError');
+          reject(err);
+        })
+    );
+
+    const client = new ApiClient(BASE_URL, 100);
+    await expect(client.health()).rejects.toThrow('Request timed out after');
+  });
+
+  it('throws a friendly message on connection refused', async () => {
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(
+      new TypeError('fetch failed: reason: ECONNREFUSED')
+    );
+
+    const client = new ApiClient('http://localhost:1');
+    await expect(client.health()).rejects.toThrow('Connection refused');
+  });
+
+  it('throws a friendly message on DNS failure', async () => {
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(
+      new TypeError('fetch failed: ENOTFOUND nonexistent.example.com')
+    );
+
+    const client = new ApiClient('http://nonexistent.example.com');
+    await expect(client.health()).rejects.toThrow('Cannot reach');
+  });
+
+  it('includes response body text in API error messages', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response('Service Unavailable', {
+        status: 503,
+        statusText: 'Service Unavailable',
+      })
+    );
+
+    const client = new ApiClient(BASE_URL, 10_000);
+    await expect(client.health()).rejects.toThrow('API error: 503');
+  });
+});