@ekodb/ekodb-client 0.23.1 → 0.25.0

package/dist/client.d.ts

@@ -94,6 +94,55 @@ export interface UpsertOptions {
     transactionId?: string;
     bypassCache?: boolean;
 }
+/**
+ * A health status value. Like the Go client's `HealthState` (a string type), an
+ * off-contract status reported by the server is preserved verbatim.
+ */
+export type HealthState = string;
+/** Canonical {@link HealthStatus.status} values. */
+export declare const HealthOK = "ok";
+export declare const HealthDegraded = "degraded";
+export declare const HealthUnknown = "unknown";
+/**
+ * A snapshot of an ekoDB /api/health probe.
+ *
+ * It is degraded-tolerant: a reachable server that reports `degraded` is a
+ * successful snapshot (`reachable: true`, `status: "degraded"`), NOT an error.
+ * An unreachable/unparseable probe yields `{ reachable: false, status: "unknown" }`.
+ *
+ * Consumers base liveness on `reachable` and treat `degraded` as a warning,
+ * never as a fatal. `detail` (the full admin body, which includes internal
+ * metrics and collection names) is excluded from JSON via `toJSON()` so
+ * surfacing the snapshot cannot leak internals; read it in-process when needed.
+ */
+export declare class HealthStatus {
+    reachable: boolean;
+    status: HealthState;
+    integrityOk: boolean;
+    detail?: {
+        [key: string]: any;
+    };
+    constructor(init: {
+        reachable: boolean;
+        status: HealthState;
+        integrityOk: boolean;
+        detail?: {
+            [key: string]: any;
+        };
+    });
+    toJSON(): {
+        reachable: boolean;
+        status: HealthState;
+        integrity_ok: boolean;
+    };
+}
+/**
+ * Interprets a parsed /api/health body per the shared health contract. A
+ * missing/odd `status` on a reachable body fails safe to `degraded`; a
+ * non-object body yields an unreachable `unknown` snapshot. `integrity_ok` is
+ * read from the top-level field (public) or nested `integrity.healthy` (admin).
+ */
+export declare function parseHealthStatus(body: any): HealthStatus;
 export interface FindOptions {
     filter?: any;
     sort?: any;
@@ -861,9 +910,21 @@ export declare class EkoDBClient {
      */
     distinctValues(collection: string, field: string, options?: DistinctValuesOptions): Promise<DistinctValuesResponse>;
     /**
-     * Health check - verify the ekoDB server is responding
+     * Health check - reports whether the ekoDB server is reachable.
+     *
+     * Returns `true` whenever the server responds (INCLUDING when it reports
+     * `degraded`) and `false` only when it is unreachable. The ekoDB server
+     * returns HTTP 200 while degraded on purpose, so gating on `status === "ok"`
+     * would treat a degraded-but-serving server as down. Use {@link healthStatus}
+     * for the ok/degraded distinction.
      */
     health(): Promise<boolean>;
+    /**
+     * Structured, degraded-tolerant health. Returns a {@link HealthStatus}
+     * snapshot; an unreachable server yields `{ reachable: false, status:
+     * "unknown" }` rather than throwing.
+     */
+    healthStatus(): Promise<HealthStatus>;
     /**
      * Execute a tool via ekoDB's server-side tool pipeline.
      *

package/dist/client.js

@@ -36,7 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = exports.SchemaCache = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.SerializationFormat = void 0;
+exports.WebSocketClient = exports.SchemaCache = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.HealthStatus = exports.HealthUnknown = exports.HealthDegraded = exports.HealthOK = exports.RateLimitError = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.SerializationFormat = void 0;
+exports.parseHealthStatus = parseHealthStatus;
 exports.extractRecordId = extractRecordId;
 const msgpack_1 = require("@msgpack/msgpack");
 const query_builder_1 = require("./query-builder");
@@ -71,6 +72,74 @@ class RateLimitError extends Error {
     }
 }
 exports.RateLimitError = RateLimitError;
+/** Canonical {@link HealthStatus.status} values. */
+exports.HealthOK = "ok";
+exports.HealthDegraded = "degraded";
+exports.HealthUnknown = "unknown";
+/**
+ * A snapshot of an ekoDB /api/health probe.
+ *
+ * It is degraded-tolerant: a reachable server that reports `degraded` is a
+ * successful snapshot (`reachable: true`, `status: "degraded"`), NOT an error.
+ * An unreachable/unparseable probe yields `{ reachable: false, status: "unknown" }`.
+ *
+ * Consumers base liveness on `reachable` and treat `degraded` as a warning,
+ * never as a fatal. `detail` (the full admin body, which includes internal
+ * metrics and collection names) is excluded from JSON via `toJSON()` so
+ * surfacing the snapshot cannot leak internals; read it in-process when needed.
+ */
+class HealthStatus {
+    constructor(init) {
+        this.reachable = init.reachable;
+        this.status = init.status;
+        this.integrityOk = init.integrityOk;
+        this.detail = init.detail;
+    }
+    toJSON() {
+        return {
+            reachable: this.reachable,
+            status: this.status,
+            integrity_ok: this.integrityOk,
+        };
+    }
+}
+exports.HealthStatus = HealthStatus;
+/**
+ * Interprets a parsed /api/health body per the shared health contract. A
+ * missing/odd `status` on a reachable body fails safe to `degraded`; a
+ * non-object body yields an unreachable `unknown` snapshot. `integrity_ok` is
+ * read from the top-level field (public) or nested `integrity.healthy` (admin).
+ */
+function parseHealthStatus(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return new HealthStatus({
+            reachable: false,
+            status: exports.HealthUnknown,
+            integrityOk: false,
+        });
+    }
+    // Default to degraded; a non-empty string status is kept verbatim (matches
+    // the Go client). A missing/non-string status fails safe to degraded.
+    let status = exports.HealthDegraded;
+    if (typeof body.status === "string" && body.status !== "") {
+        status = body.status;
+    }
+    let integrityOk = false;
+    if (typeof body.integrity_ok === "boolean") {
+        integrityOk = body.integrity_ok;
+    }
+    else if (body.integrity &&
+        typeof body.integrity === "object" &&
+        typeof body.integrity.healthy === "boolean") {
+        integrityOk = body.integrity.healthy;
+    }
+    return new HealthStatus({
+        reachable: true,
+        status,
+        integrityOk,
+        detail: body,
+    });
+}
 var MergeStrategy;
 (function (MergeStrategy) {
     MergeStrategy["Chronological"] = "Chronological";
@@ -1121,15 +1190,33 @@ class EkoDBClient {
         return this.makeRequest("POST", `/api/distinct/${encodeURIComponent(collection)}/${encodeURIComponent(field)}`, body, 0, true);
     }
     /**
-     * Health check - verify the ekoDB server is responding
+     * Health check - reports whether the ekoDB server is reachable.
+     *
+     * Returns `true` whenever the server responds (INCLUDING when it reports
+     * `degraded`) and `false` only when it is unreachable. The ekoDB server
+     * returns HTTP 200 while degraded on purpose, so gating on `status === "ok"`
+     * would treat a degraded-but-serving server as down. Use {@link healthStatus}
+     * for the ok/degraded distinction.
      */
     async health() {
+        return (await this.healthStatus()).reachable;
+    }
+    /**
+     * Structured, degraded-tolerant health. Returns a {@link HealthStatus}
+     * snapshot; an unreachable server yields `{ reachable: false, status:
+     * "unknown" }` rather than throwing.
+     */
+    async healthStatus() {
         try {
-            const result = await this.makeRequest("GET", "/api/health", undefined, 0, true);
-            return result.status === "ok";
+            const body = await this.makeRequest("GET", "/api/health", undefined, 0, true);
+            return parseHealthStatus(body);
         }
         catch {
-            return false;
+            return new HealthStatus({
+                reachable: false,
+                status: exports.HealthUnknown,
+                integrityOk: false,
+            });
         }
     }
     // ========== Chat Methods ==========

package/dist/client.test.js

@@ -2671,3 +2671,90 @@ function mockErrorResponse(status, message) {
         await (0, vitest_1.expect)(client.find("users")).rejects.toThrow(/timed out after 20ms/);
     });
 });
+// ============================================================================
+// Health Contract Tests
+// ============================================================================
+(0, vitest_1.describe)("health / healthStatus", () => {
+    (0, vitest_1.it)("health() returns true for a reachable degraded server (bug fix)", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ status: "degraded", integrity_ok: false });
+        (0, vitest_1.expect)(await client.health()).toBe(true);
+    });
+    (0, vitest_1.it)("health() returns false when unreachable", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockErrorResponse(503, "unavailable");
+        (0, vitest_1.expect)(await client.health()).toBe(false);
+    });
+    (0, vitest_1.it)("healthStatus() surfaces degraded without erroring", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ status: "degraded", integrity_ok: false });
+        const hs = await client.healthStatus();
+        (0, vitest_1.expect)(hs.reachable).toBe(true);
+        (0, vitest_1.expect)(hs.status).toBe("degraded");
+        (0, vitest_1.expect)(hs.integrityOk).toBe(false);
+    });
+    (0, vitest_1.it)("healthStatus() unreachable -> reachable=false, status=unknown", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockErrorResponse(503, "unavailable");
+        const hs = await client.healthStatus();
+        (0, vitest_1.expect)(hs.reachable).toBe(false);
+        (0, vitest_1.expect)(hs.status).toBe("unknown");
+    });
+    (0, vitest_1.it)("healthStatus() reads integrity from the admin nested shape", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({
+            status: "ok",
+            integrity: { healthy: true, manifest_load_failed: [] },
+        });
+        const hs = await client.healthStatus();
+        (0, vitest_1.expect)(hs.status).toBe("ok");
+        (0, vitest_1.expect)(hs.integrityOk).toBe(true);
+    });
+    (0, vitest_1.it)("parseHealthStatus fails safe to degraded on a missing status", () => {
+        const hs = (0, client_1.parseHealthStatus)({ integrity_ok: true });
+        (0, vitest_1.expect)(hs.reachable).toBe(true);
+        (0, vitest_1.expect)(hs.status).toBe("degraded");
+    });
+    (0, vitest_1.it)("parseHealthStatus yields an unknown snapshot for a non-object body", () => {
+        const hs = (0, client_1.parseHealthStatus)("not json");
+        (0, vitest_1.expect)(hs.reachable).toBe(false);
+        (0, vitest_1.expect)(hs.status).toBe("unknown");
+    });
+    (0, vitest_1.it)("JSON serialization is a safe summary that excludes detail", () => {
+        const hs = (0, client_1.parseHealthStatus)({
+            status: "degraded",
+            integrity: {
+                healthy: false,
+                manifest_load_failed: ["secret_collection"],
+            },
+        });
+        const json = JSON.stringify(hs);
+        (0, vitest_1.expect)(json).not.toContain("detail");
+        (0, vitest_1.expect)(json).not.toContain("secret_collection");
+        const parsed = JSON.parse(json);
+        (0, vitest_1.expect)(parsed).toEqual({
+            reachable: true,
+            status: "degraded",
+            integrity_ok: false,
+        });
+        // detail is still readable in-process
+        (0, vitest_1.expect)(hs.detail).toBeDefined();
+    });
+    (0, vitest_1.it)("parseHealthStatus preserves a raw off-contract status (matches Go)", () => {
+        (0, vitest_1.expect)((0, client_1.parseHealthStatus)({ status: "healthy" }).status).toBe("healthy");
+        (0, vitest_1.expect)((0, client_1.parseHealthStatus)({ status: "ok" }).status).toBe("ok");
+        (0, vitest_1.expect)((0, client_1.parseHealthStatus)({ status: "degraded" }).status).toBe("degraded");
+    });
+    (0, vitest_1.it)("parseHealthStatus fails safe to degraded on a non-string status", () => {
+        (0, vitest_1.expect)((0, client_1.parseHealthStatus)({ status: { nested: 1 } }).status).toBe("degraded");
+    });
+    (0, vitest_1.it)("parseHealthStatus treats a non-object (array) body as unknown", () => {
+        (0, vitest_1.expect)((0, client_1.parseHealthStatus)([1, 2, 3]).reachable).toBe(false);
+        (0, vitest_1.expect)((0, client_1.parseHealthStatus)([1, 2, 3]).status).toBe("unknown");
+    });
+});

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { EkoDBClient, WebSocketClient, EventStream, SerializationFormat, MergeStrategy, RateLimitError, SchemaCache, extractRecordId, } from "./client";
+export { EkoDBClient, WebSocketClient, EventStream, SerializationFormat, MergeStrategy, RateLimitError, SchemaCache, extractRecordId, HealthStatus, parseHealthStatus, HealthOK, HealthDegraded, HealthUnknown, } from "./client";
+export type { HealthState } from "./client";
 export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";
 export { SchemaBuilder, FieldTypeSchemaBuilder, VectorIndexAlgorithm, DistanceMetric, } from "./schema";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.parameterRef = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.extractRecordId = exports.SchemaCache = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.EventStream = exports.WebSocketClient = exports.EkoDBClient = void 0;
+exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.parameterRef = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.HealthUnknown = exports.HealthDegraded = exports.HealthOK = exports.parseHealthStatus = exports.HealthStatus = exports.extractRecordId = exports.SchemaCache = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.EventStream = exports.WebSocketClient = exports.EkoDBClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "EkoDBClient", { enumerable: true, get: function () { return client_1.EkoDBClient; } });
 Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return client_1.WebSocketClient; } });
@@ -10,6 +10,11 @@ Object.defineProperty(exports, "MergeStrategy", { enumerable: true, get: functio
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return client_1.RateLimitError; } });
 Object.defineProperty(exports, "SchemaCache", { enumerable: true, get: function () { return client_1.SchemaCache; } });
 Object.defineProperty(exports, "extractRecordId", { enumerable: true, get: function () { return client_1.extractRecordId; } });
+Object.defineProperty(exports, "HealthStatus", { enumerable: true, get: function () { return client_1.HealthStatus; } });
+Object.defineProperty(exports, "parseHealthStatus", { enumerable: true, get: function () { return client_1.parseHealthStatus; } });
+Object.defineProperty(exports, "HealthOK", { enumerable: true, get: function () { return client_1.HealthOK; } });
+Object.defineProperty(exports, "HealthDegraded", { enumerable: true, get: function () { return client_1.HealthDegraded; } });
+Object.defineProperty(exports, "HealthUnknown", { enumerable: true, get: function () { return client_1.HealthUnknown; } });
 var query_builder_1 = require("./query-builder");
 Object.defineProperty(exports, "QueryBuilder", { enumerable: true, get: function () { return query_builder_1.QueryBuilder; } });
 Object.defineProperty(exports, "SortOrder", { enumerable: true, get: function () { return query_builder_1.SortOrder; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
   "author": "ekoDB",
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^25.3.5",
+    "@types/node": "^24.13.2",
     "@types/ws": "^8.18.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/src/client.test.ts

@@ -11,6 +11,7 @@ import {
   SerializationFormat,
   extractRecordId,
   DEFAULT_REQUEST_TIMEOUT_MS,
+  parseHealthStatus,
 } from "./client";
 import { SearchQueryBuilder } from "./search";
 
@@ -3518,3 +3519,104 @@ describe("request timeout", () => {
     await expect(client.find("users")).rejects.toThrow(/timed out after 20ms/);
   });
 });
+
+// ============================================================================
+// Health Contract Tests
+// ============================================================================
+
+describe("health / healthStatus", () => {
+  it("health() returns true for a reachable degraded server (bug fix)", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ status: "degraded", integrity_ok: false });
+    expect(await client.health()).toBe(true);
+  });
+
+  it("health() returns false when unreachable", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockErrorResponse(503, "unavailable");
+    expect(await client.health()).toBe(false);
+  });
+
+  it("healthStatus() surfaces degraded without erroring", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ status: "degraded", integrity_ok: false });
+    const hs = await client.healthStatus();
+    expect(hs.reachable).toBe(true);
+    expect(hs.status).toBe("degraded");
+    expect(hs.integrityOk).toBe(false);
+  });
+
+  it("healthStatus() unreachable -> reachable=false, status=unknown", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockErrorResponse(503, "unavailable");
+    const hs = await client.healthStatus();
+    expect(hs.reachable).toBe(false);
+    expect(hs.status).toBe("unknown");
+  });
+
+  it("healthStatus() reads integrity from the admin nested shape", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      status: "ok",
+      integrity: { healthy: true, manifest_load_failed: [] },
+    });
+    const hs = await client.healthStatus();
+    expect(hs.status).toBe("ok");
+    expect(hs.integrityOk).toBe(true);
+  });
+
+  it("parseHealthStatus fails safe to degraded on a missing status", () => {
+    const hs = parseHealthStatus({ integrity_ok: true });
+    expect(hs.reachable).toBe(true);
+    expect(hs.status).toBe("degraded");
+  });
+
+  it("parseHealthStatus yields an unknown snapshot for a non-object body", () => {
+    const hs = parseHealthStatus("not json");
+    expect(hs.reachable).toBe(false);
+    expect(hs.status).toBe("unknown");
+  });
+
+  it("JSON serialization is a safe summary that excludes detail", () => {
+    const hs = parseHealthStatus({
+      status: "degraded",
+      integrity: {
+        healthy: false,
+        manifest_load_failed: ["secret_collection"],
+      },
+    });
+    const json = JSON.stringify(hs);
+    expect(json).not.toContain("detail");
+    expect(json).not.toContain("secret_collection");
+    const parsed = JSON.parse(json);
+    expect(parsed).toEqual({
+      reachable: true,
+      status: "degraded",
+      integrity_ok: false,
+    });
+    // detail is still readable in-process
+    expect(hs.detail).toBeDefined();
+  });
+
+  it("parseHealthStatus preserves a raw off-contract status (matches Go)", () => {
+    expect(parseHealthStatus({ status: "healthy" }).status).toBe("healthy");
+    expect(parseHealthStatus({ status: "ok" }).status).toBe("ok");
+    expect(parseHealthStatus({ status: "degraded" }).status).toBe("degraded");
+  });
+
+  it("parseHealthStatus fails safe to degraded on a non-string status", () => {
+    expect(parseHealthStatus({ status: { nested: 1 } }).status).toBe(
+      "degraded",
+    );
+  });
+
+  it("parseHealthStatus treats a non-object (array) body as unknown", () => {
+    expect(parseHealthStatus([1, 2, 3]).reachable).toBe(false);
+    expect(parseHealthStatus([1, 2, 3]).status).toBe("unknown");
+  });
+});

package/src/client.ts

@@ -119,6 +119,94 @@ export interface UpsertOptions {
   bypassCache?: boolean;
 }
 
+/**
+ * A health status value. Like the Go client's `HealthState` (a string type), an
+ * off-contract status reported by the server is preserved verbatim.
+ */
+export type HealthState = string;
+
+/** Canonical {@link HealthStatus.status} values. */
+export const HealthOK = "ok";
+export const HealthDegraded = "degraded";
+export const HealthUnknown = "unknown";
+
+/**
+ * A snapshot of an ekoDB /api/health probe.
+ *
+ * It is degraded-tolerant: a reachable server that reports `degraded` is a
+ * successful snapshot (`reachable: true`, `status: "degraded"`), NOT an error.
+ * An unreachable/unparseable probe yields `{ reachable: false, status: "unknown" }`.
+ *
+ * Consumers base liveness on `reachable` and treat `degraded` as a warning,
+ * never as a fatal. `detail` (the full admin body, which includes internal
+ * metrics and collection names) is excluded from JSON via `toJSON()` so
+ * surfacing the snapshot cannot leak internals; read it in-process when needed.
+ */
+export class HealthStatus {
+  reachable: boolean;
+  status: HealthState;
+  integrityOk: boolean;
+  detail?: { [key: string]: any };
+
+  constructor(init: {
+    reachable: boolean;
+    status: HealthState;
+    integrityOk: boolean;
+    detail?: { [key: string]: any };
+  }) {
+    this.reachable = init.reachable;
+    this.status = init.status;
+    this.integrityOk = init.integrityOk;
+    this.detail = init.detail;
+  }
+
+  toJSON(): { reachable: boolean; status: HealthState; integrity_ok: boolean } {
+    return {
+      reachable: this.reachable,
+      status: this.status,
+      integrity_ok: this.integrityOk,
+    };
+  }
+}
+
+/**
+ * Interprets a parsed /api/health body per the shared health contract. A
+ * missing/odd `status` on a reachable body fails safe to `degraded`; a
+ * non-object body yields an unreachable `unknown` snapshot. `integrity_ok` is
+ * read from the top-level field (public) or nested `integrity.healthy` (admin).
+ */
+export function parseHealthStatus(body: any): HealthStatus {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return new HealthStatus({
+      reachable: false,
+      status: HealthUnknown,
+      integrityOk: false,
+    });
+  }
+  // Default to degraded; a non-empty string status is kept verbatim (matches
+  // the Go client). A missing/non-string status fails safe to degraded.
+  let status: HealthState = HealthDegraded;
+  if (typeof body.status === "string" && body.status !== "") {
+    status = body.status;
+  }
+  let integrityOk = false;
+  if (typeof body.integrity_ok === "boolean") {
+    integrityOk = body.integrity_ok;
+  } else if (
+    body.integrity &&
+    typeof body.integrity === "object" &&
+    typeof body.integrity.healthy === "boolean"
+  ) {
+    integrityOk = body.integrity.healthy;
+  }
+  return new HealthStatus({
+    reachable: true,
+    status,
+    integrityOk,
+    detail: body,
+  });
+}
+
 export interface FindOptions {
   filter?: any;
   sort?: any;
@@ -1827,20 +1915,39 @@ export class EkoDBClient {
   }
 
   /**
-   * Health check - verify the ekoDB server is responding
+   * Health check - reports whether the ekoDB server is reachable.
+   *
+   * Returns `true` whenever the server responds (INCLUDING when it reports
+   * `degraded`) and `false` only when it is unreachable. The ekoDB server
+   * returns HTTP 200 while degraded on purpose, so gating on `status === "ok"`
+   * would treat a degraded-but-serving server as down. Use {@link healthStatus}
+   * for the ok/degraded distinction.
    */
   async health(): Promise<boolean> {
+    return (await this.healthStatus()).reachable;
+  }
+
+  /**
+   * Structured, degraded-tolerant health. Returns a {@link HealthStatus}
+   * snapshot; an unreachable server yields `{ reachable: false, status:
+   * "unknown" }` rather than throwing.
+   */
+  async healthStatus(): Promise<HealthStatus> {
     try {
-      const result = await this.makeRequest<{ status: string }>(
+      const body = await this.makeRequest<any>(
         "GET",
         "/api/health",
         undefined,
         0,
         true,
       );
-      return result.status === "ok";
+      return parseHealthStatus(body);
     } catch {
-      return false;
+      return new HealthStatus({
+        reachable: false,
+        status: HealthUnknown,
+        integrityOk: false,
+      });
     }
   }
 

package/src/index.ts

@@ -7,7 +7,13 @@ export {
   RateLimitError,
   SchemaCache,
   extractRecordId,
+  HealthStatus,
+  parseHealthStatus,
+  HealthOK,
+  HealthDegraded,
+  HealthUnknown,
 } from "./client";
+export type { HealthState } from "./client";
 export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";
 export {