@ekodb/ekodb-client 0.25.0 → 0.26.1

package/src/client.test.ts

@@ -13,6 +13,7 @@ import {
   DEFAULT_REQUEST_TIMEOUT_MS,
   parseHealthStatus,
 } from "./client";
+import type { ChatModels } from "./client";
 import { SearchQueryBuilder } from "./search";
 
 // Mock fetch globally
@@ -1436,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();
 
@@ -2572,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();
@@ -2597,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();
@@ -2802,6 +3021,16 @@ describe("EkoDBClient schedules", () => {
 
     const result = await client.pauseSchedule("sched_1");
     expect(result).toHaveProperty("status", "paused");
+
+    // Assert the REQUEST. There is no /pause route; pausing is a partial
+    // update of `enabled`. A response-only assertion passed for as long as
+    // this method POSTed to a route that does not exist.
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1]; // calls[0] is the token exchange
+    expect(dataCall[0]).toContain("/api/schedules/sched_1");
+    expect(dataCall[0]).not.toContain("/pause");
+    expect(dataCall[1]?.method).toBe("PUT");
+    expect(JSON.parse(dataCall[1]?.body as string)).toEqual({ enabled: false });
   });
 
   it("resumes a schedule", async () => {
@@ -2811,6 +3040,13 @@ describe("EkoDBClient schedules", () => {
 
     const result = await client.resumeSchedule("sched_1");
     expect(result).toHaveProperty("status", "active");
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/schedules/sched_1");
+    expect(dataCall[0]).not.toContain("/resume");
+    expect(dataCall[1]?.method).toBe("PUT");
+    expect(JSON.parse(dataCall[1]?.body as string)).toEqual({ enabled: true });
   });
 });
 
@@ -2831,6 +3067,15 @@ describe("EkoDBClient kv links", () => {
 
     const result = await client.kvGetLinks("session:user123");
     expect(result).toHaveProperty("links");
+
+    // Assert the REQUEST, not just the mocked response. These three methods
+    // shipped pointing at routes that do not exist, and every one of these
+    // tests passed the whole time, because a mocked response says nothing
+    // about the URL the client actually asked for.
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1]; // calls[0] is the token exchange
+    expect(dataCall[0]).toContain("/api/kv/session%3Auser123/links");
+    expect(dataCall[1]?.method).toBe("GET");
   });
 
   it("links a document to a KV key", async () => {
@@ -2840,6 +3085,32 @@ describe("EkoDBClient kv links", () => {
 
     const result = await client.kvLink("session:user123", "users", "user_1");
     expect(result).toHaveProperty("status", "linked");
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    // The identifying triple belongs in the PATH, not the body.
+    expect(dataCall[0]).toContain(
+      "/api/kv/session%3Auser123/links/users/user_1",
+    );
+    expect(dataCall[1]?.method).toBe("POST");
+  });
+
+  it("passes optional link data in the body", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ status: "linked" });
+
+    await client.kvLink("session:user123", "users", "user_1", {
+      field_path: "profile.avatar",
+      metadata: { source: "signup" },
+    });
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const body = JSON.parse(calls[1][1]?.body as string);
+    expect(body).toEqual({
+      field_path: "profile.avatar",
+      metadata: { source: "signup" },
+    });
   });
 
   it("unlinks a document from a KV key", async () => {
@@ -2849,6 +3120,14 @@ describe("EkoDBClient kv links", () => {
 
     const result = await client.kvUnlink("session:user123", "users", "user_1");
     expect(result).toHaveProperty("status", "unlinked");
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain(
+      "/api/kv/session%3Auser123/links/users/user_1",
+    );
+    // DELETE, not POST — the previous implementation used POST and 404'd.
+    expect(dataCall[1]?.method).toBe("DELETE");
   });
 });
 
@@ -2874,7 +3153,7 @@ describe("EkoDBClient text and hybrid search", () => {
         },
       ],
       total: 2,
-      took_ms: 12,
+      execution_time_ms: 12,
     });
 
     const result = await client.textSearch("documents", "ownership", {
@@ -2899,7 +3178,7 @@ describe("EkoDBClient text and hybrid search", () => {
         },
       ],
       total: 1,
-      took_ms: 25,
+      execution_time_ms: 25,
     });
 
     const queryVector = [0.1, 0.2, 0.3, 0.4, 0.5];

package/src/client.ts

@@ -416,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 };
 }
 
 /**
@@ -739,11 +782,11 @@ export class EkoDBClient {
     // ONLY these operations support MessagePack
     const msgpackPaths = [
       "/api/insert/",
-      "/api/batch_insert/",
+      "/api/batch/insert/",
       "/api/update/",
-      "/api/batch_update/",
+      "/api/batch/update/",
       "/api/delete/",
-      "/api/batch_delete/",
+      "/api/batch/delete/",
     ];
 
     // Check if path starts with any MessagePack-supported operation
@@ -2263,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
@@ -2305,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) {
@@ -3158,38 +3231,49 @@ export class EkoDBClient {
   async kvGetLinks(key: string): Promise<Record> {
     return this.makeRequest<Record>(
       "GET",
-      `/api/kv/links/${encodeURIComponent(key)}`,
+      `/api/kv/${encodeURIComponent(key)}/links`,
       undefined,
       0,
       true,
     );
   }
 
-  /** Link a document to a KV key */
+  /**
+   * Link a document to a KV key.
+   *
+   * The identifying triple goes in the path; the body carries the optional
+   * link payload (`keys`, `field_path`, `metadata`), and an empty object means
+   * "no extra link data".
+   */
   async kvLink(
     key: string,
     collection: string,
     documentId: string,
+    linkData: {
+      keys?: string[];
+      field_path?: string;
+      metadata?: { [key: string]: string };
+    } = {},
   ): Promise<Record> {
     return this.makeRequest<Record>(
       "POST",
-      `/api/kv/link`,
-      { key, collection, document_id: documentId },
+      `/api/kv/${encodeURIComponent(key)}/links/${encodeURIComponent(collection)}/${encodeURIComponent(documentId)}`,
+      linkData,
       0,
       true,
     );
   }
 
-  /** Unlink a document from a KV key */
+  /** Unlink a document from a KV key. DELETE, with the triple in the path. */
   async kvUnlink(
     key: string,
     collection: string,
     documentId: string,
   ): Promise<Record> {
     return this.makeRequest<Record>(
-      "POST",
-      `/api/kv/unlink`,
-      { key, collection, document_id: documentId },
+      "DELETE",
+      `/api/kv/${encodeURIComponent(key)}/links/${encodeURIComponent(collection)}/${encodeURIComponent(documentId)}`,
+      undefined,
       0,
       true,
     );
@@ -3248,23 +3332,38 @@ export class EkoDBClient {
     );
   }
 
-  /** Pause a schedule */
+  /**
+   * Pause a schedule.
+   *
+   * There is no `/pause` endpoint — pausing is a partial update of the
+   * schedule's `enabled` flag. This previously POSTed to
+   * `/api/schedules/{id}/pause`, which has never existed and always 404'd.
+   */
   async pauseSchedule(id: string): Promise<Record> {
-    return this.makeRequest<Record>(
-      "POST",
-      `/api/schedules/${encodeURIComponent(id)}/pause`,
-      undefined,
-      0,
-      true,
-    );
+    return this.setScheduleEnabled(id, false);
   }
 
-  /** Resume a schedule */
+  /**
+   * Resume a paused schedule. See {@link pauseSchedule} for why this is an
+   * update rather than its own endpoint.
+   */
   async resumeSchedule(id: string): Promise<Record> {
+    return this.setScheduleEnabled(id, true);
+  }
+
+  /**
+   * Shared implementation for pause/resume: a partial update carrying only
+   * `enabled`. The server recomputes the next execution time when `enabled`
+   * changes, so nothing else needs sending.
+   */
+  private async setScheduleEnabled(
+    id: string,
+    enabled: boolean,
+  ): Promise<Record> {
     return this.makeRequest<Record>(
-      "POST",
-      `/api/schedules/${encodeURIComponent(id)}/resume`,
-      undefined,
+      "PUT",
+      `/api/schedules/${encodeURIComponent(id)}`,
+      { enabled },
       0,
       true,
     );
@@ -3601,7 +3700,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 {
@@ -4285,9 +4442,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();