@ekodb/ekodb-client 0.24.0 → 0.26.0

package/src/client.test.ts

@@ -11,7 +11,9 @@ import {
   SerializationFormat,
   extractRecordId,
   DEFAULT_REQUEST_TIMEOUT_MS,
+  parseHealthStatus,
 } from "./client";
+import type { ChatModels } from "./client";
 import { SearchQueryBuilder } from "./search";
 
 // Mock fetch globally
@@ -1435,6 +1437,55 @@ describe("EkoDBClient chat models", () => {
     expect(result.perplexity).toHaveLength(1);
   });
 
+  it("carries gemini and the per-provider status from the server", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      openai: [],
+      anthropic: ["claude-sonnet-4-5"],
+      perplexity: ["sonar"],
+      gemini: ["gemini-2.5-flash"],
+      providers: {
+        anthropic: { status: "ok", verified: true, model_count: 1 },
+        gemini: { status: "ok", verified: true, model_count: 1 },
+        openai: {
+          status: "auth_failed",
+          verified: true,
+          http_status: 401,
+          message: "Failed to fetch OpenAI models: 401 Unauthorized",
+        },
+        perplexity: {
+          status: "ok",
+          verified: false,
+          message: "static model list; key not verified",
+        },
+      },
+    });
+
+    const result: ChatModels = await client.getChatModels();
+
+    expect(result.gemini).toEqual(["gemini-2.5-flash"]);
+    expect(result.providers?.openai.status).toBe("auth_failed");
+    expect(result.providers?.openai.http_status).toBe(401);
+    expect(result.providers?.openai.verified).toBe(true);
+    expect(result.providers?.perplexity.verified).toBe(false);
+    expect(result.providers?.anthropic.model_count).toBe(1);
+  });
+
+  it("tolerates a server that predates gemini and providers", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ openai: ["gpt-4o"], anthropic: [], perplexity: [] });
+
+    const result: ChatModels = await client.getChatModels();
+
+    expect(result.openai).toEqual(["gpt-4o"]);
+    expect(result.gemini).toBeUndefined();
+    expect(result.providers).toBeUndefined();
+  });
+
   it("gets models for specific provider", async () => {
     const client = createTestClient();
 
@@ -2571,6 +2622,138 @@ describe("EkoDBClient chatMessageStream", () => {
     expect(events[2].executionTimeMs).toBe(42);
   });
 
+  it("treats a frame named error as an error even when its payload says message", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      'event: token\ndata: {"token":"Hel"}\n\nevent: error\ndata: {"message":"boom"}\n\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([
+      { type: "chunk", content: "Hel" },
+      { type: "error", error: "boom" },
+    ]);
+  });
+
+  it("stops reading after an error frame and emits nothing that follows it", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      'event: error\ndata: {"message":"boom"}\n\nevent: token\ndata: {"token":"late"}\n\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([{ type: "error", error: "boom" }]);
+  });
+
+  it("cancels the body reader after an error frame instead of waiting for the server to close", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const encoder = new TextEncoder();
+    const chunks = [
+      encoder.encode('event: error\ndata: {"message":"boom"}\n\n'),
+      encoder.encode('event: token\ndata: {"token":"late"}\n\n'),
+    ];
+    const cancel = vi.fn(async () => {});
+    let reads = 0;
+    const reader = {
+      read: vi.fn(async () => {
+        // A server (or proxy) that does not close after the error frame: it
+        // keeps sending frames. Bounded so a client that never stops fails
+        // the assertions below instead of looping forever.
+        if (reads >= 50) return { done: true, value: undefined };
+        const value = chunks[Math.min(reads, chunks.length - 1)];
+        reads += 1;
+        return { done: false, value };
+      }),
+      cancel,
+    };
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: { getReader: () => reader },
+      text: async () => "",
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([{ type: "error", error: "boom" }]);
+    // One read delivered the error frame; the reader was cancelled rather
+    // than read until the server closed.
+    expect(reader.read).toHaveBeenCalledTimes(1);
+    expect(cancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the error text a string when the server sends a structured error", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      'event: error\ndata: {"error":{"code":"upstream_down","status":503},"error_kind":"provider_unavailable","provider":"openai"}\n\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([
+      {
+        type: "error",
+        error: "Unknown error",
+        errorKind: "provider_unavailable",
+        provider: "openai",
+      },
+    ]);
+  });
+
   it("emits error event on SSE error", async () => {
     const client = createTestClient();
     mockTokenResponse();
@@ -2596,6 +2779,43 @@ describe("EkoDBClient chatMessageStream", () => {
     expect(events[0]).toEqual({ type: "error", error: "LLM timeout" });
   });
 
+  it("carries the provider failure classification on an error event", async () => {
+    // The deployment classifies a provider failure (`error_kind`, `provider`,
+    // `provider_status`, `retry_after_secs` on the wire); the event carries
+    // every one of them, in this shape's camelCase, so a consumer can act on
+    // it without string-matching.
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      'data: {"error":"OpenAI API error: Incorrect API key provided","error_kind":"provider_auth_failed","provider":"openai","provider_status":401}\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([
+      {
+        type: "error",
+        error: "OpenAI API error: Incorrect API key provided",
+        errorKind: "provider_auth_failed",
+        provider: "openai",
+        providerStatus: 401,
+      },
+    ]);
+  });
+
   it("emits error event on non-200 HTTP response", async () => {
     const client = createTestClient();
     mockTokenResponse();
@@ -3518,3 +3738,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;
@@ -328,12 +416,55 @@ export interface MergeSessionsRequest {
 }
 
 /**
- * Available chat models by provider
+ * A provider's state on `GET /api/chat_models`. The union lists the states
+ * this client knows; the `string` escape keeps a newer server's status from
+ * failing to type-check.
+ */
+export type ChatProviderState =
+  | "ok"
+  | "not_configured"
+  | "auth_failed"
+  | "permission_denied"
+  | "billing"
+  | "rate_limited"
+  | "unavailable"
+  | "unreachable"
+  | "request_error"
+  | (string & {});
+
+/**
+ * One provider's row in `ChatModels.providers`.
+ */
+export interface ChatProviderStatus {
+  status: ChatProviderState;
+  /**
+   * True when the status is the provider's own answer about the configured
+   * key. A 5xx, a refused connection, or a missing key says nothing about it.
+   */
+  verified: boolean;
+  /** The provider's own HTTP status, when it answered. */
+  http_status?: number;
+  /** The provider's own message, when it answered. */
+  message?: string;
+  /** How many models were listed, when the status is `ok`. */
+  model_count?: number;
+}
+
+/**
+ * Available chat models by provider, and why each list looks the way it does.
  */
 export interface ChatModels {
   openai: string[];
   anthropic: string[];
   perplexity: string[];
+  /** Google Gemini models. Absent from a server that predates the field. */
+  gemini?: string[];
+  /**
+   * Per-provider status keyed by provider name. A rejected key reports
+   * `auth_failed` where a missing one reports `not_configured`, so an empty
+   * list is never ambiguous. Absent from a server that predates the map.
+   */
+  providers?: { [provider: string]: ChatProviderStatus };
 }
 
 /**
@@ -1827,20 +1958,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,
+      });
     }
   }
 
@@ -2156,16 +2306,37 @@ export class EkoDBClient {
           return;
         }
 
+        // The `event:` name applies to the data lines that follow it, until
+        // the blank line that ends the frame. An error frame ends the stream:
+        // nothing after it is surfaced and the body is not read to the end,
+        // so a server or proxy that keeps the connection open after an error
+        // cannot hang the caller (the Rust and Go clients stop the same way).
+        let eventName = "";
+        let stopped = false;
         const emitLine = (line: string) => {
+          if (line.startsWith("event:")) {
+            eventName = line.slice(6).trim();
+            return;
+          }
+          if (line.trim() === "") {
+            eventName = "";
+            return;
+          }
           if (!line.startsWith("data:")) return;
           const dataStr = line.slice(5).trim();
           if (!dataStr) return;
           try {
             const eventData = JSON.parse(dataStr);
-            if (eventData.error) {
+            // An error frame is one the server names `error`, or whose
+            // payload carries an `error`; a `message`-only payload is still
+            // the error rather than a frame to skip, and the text is always a
+            // string (`streamErrorText`).
+            if (eventData.error != null || eventName === "error") {
+              stopped = true;
               stream.emit("event", {
                 type: "error",
-                error: eventData.error,
+                error: streamErrorText(eventData),
+                ...providerFailureFields(eventData),
               } as ChatStreamEvent);
             } else if (eventData.content && eventData.message_id) {
               // Done event — has full content + message_id
@@ -2198,17 +2369,26 @@ export class EkoDBClient {
             if (done) break;
             buffer += decoder.decode(value, { stream: true });
             let nl: number;
-            while ((nl = buffer.indexOf("\n")) >= 0) {
+            while (!stopped && (nl = buffer.indexOf("\n")) >= 0) {
               emitLine(buffer.slice(0, nl));
               buffer = buffer.slice(nl + 1);
             }
+            if (stopped) {
+              await reader.cancel?.()?.catch?.(() => {});
+              break;
+            }
+          }
+          if (!stopped) {
+            buffer += decoder.decode();
+            if (buffer) emitLine(buffer);
           }
-          buffer += decoder.decode();
-          if (buffer) emitLine(buffer);
         } else {
           // Fallback for environments/tests without a readable body stream.
           const body = await response.text();
-          for (const line of body.split("\n")) emitLine(line);
+          for (const line of body.split("\n")) {
+            emitLine(line);
+            if (stopped) break;
+          }
         }
         stream.close();
       } catch (err: any) {
@@ -3494,7 +3674,65 @@ export type ChatStreamEvent =
       toolName: string;
       arguments: any;
     }
-  | { type: "error"; error: string };
+  | {
+      type: "error";
+      error: string;
+      /**
+       * The provider-failure classification (`provider_auth_failed`,
+       * `provider_permission_denied`, `provider_billing`,
+       * `provider_rate_limited`, `provider_unavailable`,
+       * `provider_unreachable`, `provider_not_configured`,
+       * `provider_request_error`), when the failure was the LLM provider's
+       * answer. Absent for a transport failure or a plain server error.
+       */
+      errorKind?: string;
+      provider?: string;
+      /** The provider's own HTTP status. */
+      providerStatus?: number;
+      retryAfterSecs?: number;
+    };
+
+/**
+ * The text of a stream error frame: the first of `error` / `message` that is
+ * a non-empty string, else a fixed fallback — a structured `error` object is
+ * still an error, never a non-string `error` on the event. Shared by the SSE
+ * and WebSocket routes so the two cannot drift.
+ */
+function streamErrorText(payload: {
+  error?: unknown;
+  message?: unknown;
+}): string {
+  const text = (value: unknown): string | undefined =>
+    typeof value === "string" && value ? value : undefined;
+  return text(payload.error) ?? text(payload.message) ?? "Unknown error";
+}
+
+/**
+ * The classification fields of a stream error frame, only those present, so
+ * a plain error stays `{ type, error }`.
+ */
+function providerFailureFields(eventData: {
+  error_kind?: unknown;
+  provider?: unknown;
+  provider_status?: unknown;
+  retry_after_secs?: unknown;
+}): {
+  errorKind?: string;
+  provider?: string;
+  providerStatus?: number;
+  retryAfterSecs?: number;
+} {
+  const fields: ReturnType<typeof providerFailureFields> = {};
+  if (typeof eventData.error_kind === "string")
+    fields.errorKind = eventData.error_kind;
+  if (typeof eventData.provider === "string")
+    fields.provider = eventData.provider;
+  if (typeof eventData.provider_status === "number")
+    fields.providerStatus = eventData.provider_status;
+  if (typeof eventData.retry_after_secs === "number")
+    fields.retryAfterSecs = eventData.retry_after_secs;
+  return fields;
+}
 
 /** Definition for a client-side tool the LLM can call. */
 export interface ClientToolDefinition {
@@ -4178,9 +4416,12 @@ export class WebSocketClient {
         const chatId = msg.payload?.chat_id || msg.payload?.chatId;
         const stream = this.chatStreams.get(chatId);
         if (stream) {
+          // The text guard and the classification are the SSE route's,
+          // so the two routes emit the same shape.
           stream.emit("event", {
             type: "error",
-            error: msg.payload.error || msg.payload.message || "Unknown error",
+            error: streamErrorText(msg.payload),
+            ...providerFailureFields(msg.payload),
           } as ChatStreamEvent);
           this.chatStreams.delete(chatId);
           stream.close();