fix(sdk): reject malformed JSON from successful status responses (#242)

Throw StatusJsonParseError for empty or invalid JSON on 2xx keeper status
responses while preserving existing StatusApiError handling for non-2xx
bodies. Add focused status-client tests and export the new error type.

Closes #242

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: CemAyyildiz

packages/sdk/package.json

@@ -24,7 +24,7 @@
     ".": "./src/index.ts"
   },
   "scripts": {
-    "test": "node --import tsx --test src/asset-config.test.ts src/client.test.ts src/encoding.test.ts src/encrypted-blob.test.ts src/errors.test.ts src/export-receipt.test.ts src/ids.test.ts src/mainnet-readiness.test.ts src/network.test.ts src/preflight.test.ts src/public-api-snapshot.test.ts src/receipt.test.ts src/redact.test.ts src/verify.test.ts",
+    "test": "node --import tsx --test src/asset-config.test.ts src/client.test.ts src/encoding.test.ts src/encrypted-blob.test.ts src/errors.test.ts src/export-receipt.test.ts src/ids.test.ts src/mainnet-readiness.test.ts src/network.test.ts src/preflight.test.ts src/public-api-snapshot.test.ts src/receipt.test.ts src/redact.test.ts src/status-client.test.ts src/verify.test.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {

packages/sdk/src/index.ts

@@ -126,6 +126,7 @@ export {
 export {
   KeeperStatusClient,
   StatusApiError,
+  StatusJsonParseError,
   type StatusClientOptions,
   fetchKeeperStatus,
 } from "./status-client.js";

packages/sdk/src/public-api-snapshot.test.ts

@@ -17,6 +17,7 @@ const EXPECTED_EXPORTS = [
   "RoundContract",
   "RoundErrors",
   "StatusApiError",
+  "StatusJsonParseError",
   "SubRosaClient",
   "SubRosaClientConfigError",
   "SubRosaMissingReturnValueError",

packages/sdk/src/status-client.test.ts

@@ -0,0 +1,105 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  KeeperStatusClient,
+  StatusApiError,
+  StatusJsonParseError,
+} from "./status-client.js";
+import type { KeeperStatusResponse } from "./status.js";
+
+const SAMPLE_STATUS: KeeperStatusResponse = {
+  contractId: "C123",
+  network: "testnet",
+  uptimeSeconds: 42,
+  rounds: [],
+  health: {
+    rpc: "ok",
+    drand: "ok",
+    checkedAt: "2026-01-01T00:00:00.000Z",
+  },
+  now: "2026-01-01T00:00:00.000Z",
+};
+
+function mockFetch(body: string, status = 200): typeof fetch {
+  return async () =>
+    new Response(body, {
+      status,
+      headers: { "content-type": "application/json" },
+    });
+}
+
+describe("KeeperStatusClient successful JSON parsing", () => {
+  it("returns valid successful JSON unchanged", async () => {
+    const client = new KeeperStatusClient({
+      baseURL: "http://keeper.test",
+      fetchImpl: mockFetch(JSON.stringify(SAMPLE_STATUS)),
+    });
+    const status = await client.getStatus();
+    assert.deepEqual(status, SAMPLE_STATUS);
+  });
+
+  it("rejects empty successful JSON bodies", async () => {
+    const client = new KeeperStatusClient({
+      baseURL: "http://keeper.test",
+      fetchImpl: mockFetch("   "),
+    });
+    await assert.rejects(
+      () => client.getStatus(),
+      (error: unknown) => {
+        assert.ok(error instanceof StatusJsonParseError);
+        assert.equal(error.status, 200);
+        return true;
+      },
+    );
+  });
+
+  it("rejects malformed successful JSON bodies", async () => {
+    const client = new KeeperStatusClient({
+      baseURL: "http://keeper.test",
+      fetchImpl: mockFetch("{not-json"),
+    });
+    await assert.rejects(
+      () => client.getStatus(),
+      (error: unknown) => {
+        assert.ok(error instanceof StatusJsonParseError);
+        assert.match(error.message, /invalid JSON/i);
+        return true;
+      },
+    );
+  });
+});
+
+describe("KeeperStatusClient non-success responses", () => {
+  it("preserves typed StatusApiError for non-2xx JSON errors", async () => {
+    const client = new KeeperStatusClient({
+      baseURL: "http://keeper.test",
+      fetchImpl: mockFetch(JSON.stringify({ error: "round not found" }), 404),
+    });
+    await assert.rejects(
+      () => client.getRound(7),
+      (error: unknown) => {
+        assert.ok(error instanceof StatusApiError);
+        assert.equal(error.status, 404);
+        assert.equal(error.data.error, "round not found");
+        return true;
+      },
+    );
+  });
+
+  it("preserves StatusApiError when non-2xx bodies are malformed JSON", async () => {
+    const client = new KeeperStatusClient({
+      baseURL: "http://keeper.test",
+      fetchImpl: mockFetch("not-json", 503),
+    });
+    await assert.rejects(
+      () => client.getHealth(),
+      (error: unknown) => {
+        assert.ok(error instanceof StatusApiError);
+        assert.equal(error.status, 503);
+        assert.equal(error.data.error, "invalid JSON body");
+        return true;
+      },
+    );
+  });
+});

packages/sdk/src/status-client.ts

@@ -27,19 +27,42 @@ export class StatusApiError extends Error {
   }
 }
 
+/** Raised when a successful HTTP response body is empty or not valid JSON. */
+export class StatusJsonParseError extends Error {
+  readonly name = "StatusJsonParseError";
+  readonly status: number;
+
+  constructor(status: number, options?: ErrorOptions) {
+    super(`status api returned ${status} with invalid JSON body`, options);
+    this.status = status;
+  }
+}
+
 function fullURL(base: string, path: string): string {
   const trimmed = base.replace(/\/+$/, "");
   const clean = path.startsWith("/") ? path : `/${path}`;
   return `${trimmed}${clean}`;
 }
 
-async function asJson<T>(res: Response): Promise<T> {
+async function parseErrorBody(res: Response): Promise<ApiError> {
   const text = await res.text();
-  if (!text.trim()) return {} as T;
+  if (!text.trim()) return { error: `status api returned ${res.status}` };
   try {
-    return JSON.parse(text) as T;
+    return JSON.parse(text) as ApiError;
   } catch {
-    return { error: "invalid JSON body" } as T;
+    return { error: "invalid JSON body" };
+  }
+}
+
+async function parseSuccessBody<T>(res: Response): Promise<T> {
+  const text = await res.text();
+  if (!text.trim()) {
+    throw new StatusJsonParseError(res.status);
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch (cause) {
+    throw new StatusJsonParseError(res.status, { cause });
   }
 }
 
@@ -82,10 +105,10 @@ export class KeeperStatusClient {
       headers: { Accept: "application/json", ...this.headers },
     });
     if (!res.ok) {
-      const body = await asJson<ApiError>(res);
+      const body = await parseErrorBody(res);
       throw new StatusApiError(res.status, body);
     }
-    return asJson<T>(res);
+    return parseSuccessBody<T>(res);
   }
 }