@ekodb/ekodb-client 0.24.0 → 0.26.0

package/dist/client.test.js

@@ -1045,6 +1045,47 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(result.anthropic).toHaveLength(2);
         (0, vitest_1.expect)(result.perplexity).toHaveLength(1);
     });
+    (0, vitest_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 = await client.getChatModels();
+        (0, vitest_1.expect)(result.gemini).toEqual(["gemini-2.5-flash"]);
+        (0, vitest_1.expect)(result.providers?.openai.status).toBe("auth_failed");
+        (0, vitest_1.expect)(result.providers?.openai.http_status).toBe(401);
+        (0, vitest_1.expect)(result.providers?.openai.verified).toBe(true);
+        (0, vitest_1.expect)(result.providers?.perplexity.verified).toBe(false);
+        (0, vitest_1.expect)(result.providers?.anthropic.model_count).toBe(1);
+    });
+    (0, vitest_1.it)("tolerates a server that predates gemini and providers", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ openai: ["gpt-4o"], anthropic: [], perplexity: [] });
+        const result = await client.getChatModels();
+        (0, vitest_1.expect)(result.openai).toEqual(["gpt-4o"]);
+        (0, vitest_1.expect)(result.gemini).toBeUndefined();
+        (0, vitest_1.expect)(result.providers).toBeUndefined();
+    });
     (0, vitest_1.it)("gets models for specific provider", async () => {
         const client = createTestClient();
         mockTokenResponse();
@@ -1909,6 +1950,112 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(events[2].messageId).toBe("msg_1");
         (0, vitest_1.expect)(events[2].executionTimeMs).toBe(42);
     });
+    (0, vitest_1.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 = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([
+            { type: "chunk", content: "Hel" },
+            { type: "error", error: "boom" },
+        ]);
+    });
+    (0, vitest_1.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 = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([{ type: "error", error: "boom" }]);
+    });
+    (0, vitest_1.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 = vitest_1.vi.fn(async () => { });
+        let reads = 0;
+        const reader = {
+            read: vitest_1.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 = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([{ type: "error", error: "boom" }]);
+        // One read delivered the error frame; the reader was cancelled rather
+        // than read until the server closed.
+        (0, vitest_1.expect)(reader.read).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(cancel).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_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 = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([
+            {
+                type: "error",
+                error: "Unknown error",
+                errorKind: "provider_unavailable",
+                provider: "openai",
+            },
+        ]);
+    });
     (0, vitest_1.it)("emits error event on SSE error", async () => {
         const client = createTestClient();
         mockTokenResponse();
@@ -1928,6 +2075,36 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(events).toHaveLength(1);
         (0, vitest_1.expect)(events[0]).toEqual({ type: "error", error: "LLM timeout" });
     });
+    (0, vitest_1.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 = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([
+            {
+                type: "error",
+                error: "OpenAI API error: Incorrect API key provided",
+                errorKind: "provider_auth_failed",
+                provider: "openai",
+                providerStatus: 401,
+            },
+        ]);
+    });
     (0, vitest_1.it)("emits error event on non-200 HTTP response", async () => {
         const client = createTestClient();
         mockTokenResponse();
@@ -2671,3 +2848,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";
@@ -12,4 +13,4 @@ export type { Schema, FieldTypeSchema, IndexConfig, CollectionMetadata, } from "
 export type { JoinConfig } from "./join";
 export type { UserFunction, ParameterDefinition, FunctionStageConfig, GroupFunctionConfig, SortFieldConfig, FunctionResult, FunctionStats, StageStats, } from "./functions";
 export type { MutationNotification, ChatStreamEvent, ClientToolDefinition, ChatSendOptions, SubscribeOptions, } from "./client";
-export type { Record, Query, BatchOperationResult, ClientConfig, RateLimitInfo, CollectionConfig, ChatRequest, CreateChatSessionRequest, ChatMessageRequest, TokenUsage, ChatResponse, ChatSession, ChatSessionResponse, ListSessionsQuery, ListSessionsResponse, GetMessagesQuery, GetMessagesResponse, UpdateSessionRequest, MergeSessionsRequest, ChatModels, CompactChatRequest, CompactChatResponse, EmbedRequest, EmbedResponse, RawCompletionRequest, RawCompletionResponse, ToolChoice, ToolConfig, } from "./client";
+export type { Record, Query, BatchOperationResult, ClientConfig, RateLimitInfo, CollectionConfig, ChatRequest, CreateChatSessionRequest, ChatMessageRequest, TokenUsage, ChatResponse, ChatSession, ChatSessionResponse, ListSessionsQuery, ListSessionsResponse, GetMessagesQuery, GetMessagesResponse, UpdateSessionRequest, MergeSessionsRequest, ChatModels, ChatProviderState, ChatProviderStatus, CompactChatRequest, CompactChatResponse, EmbedRequest, EmbedResponse, RawCompletionRequest, RawCompletionResponse, ToolChoice, ToolConfig, } from "./client";

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/dist/websocket.test.js

@@ -300,6 +300,72 @@ function waitForMessage(ws) {
             (0, vitest_1.expect)(stream.closed).toBe(true);
             client.close();
         });
+        // The WebSocket route carries the provider-failure classification like
+        // the SSE route does, in the event's camelCase shape.
+        (0, vitest_1.it)("carries the provider failure classification on a chat stream error", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const streamPromise = client.chatSend("chat-4", "test");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws);
+            const stream = await streamPromise;
+            const events = [];
+            stream.on("event", (e) => events.push(e));
+            ws.send(JSON.stringify({
+                type: "ChatStreamError",
+                payload: {
+                    chat_id: "chat-4",
+                    error: "OpenAI API error 429 Too Many Requests",
+                    error_kind: "provider_rate_limited",
+                    provider: "openai",
+                    provider_status: 429,
+                    retry_after_secs: 7,
+                },
+            }));
+            await new Promise((r) => stream.on("close", r));
+            (0, vitest_1.expect)(events).toEqual([
+                {
+                    type: "error",
+                    error: "OpenAI API error 429 Too Many Requests",
+                    errorKind: "provider_rate_limited",
+                    provider: "openai",
+                    providerStatus: 429,
+                    retryAfterSecs: 7,
+                },
+            ]);
+            client.close();
+        });
+        // A structured `error` value is still an error, with string text — the
+        // WebSocket route guards the shape exactly as the SSE route does.
+        (0, vitest_1.it)("keeps the error text a string when the payload's error is an object", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const streamPromise = client.chatSend("chat-5", "test");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws);
+            const stream = await streamPromise;
+            const events = [];
+            stream.on("event", (e) => events.push(e));
+            ws.send(JSON.stringify({
+                type: "ChatStreamError",
+                payload: {
+                    chat_id: "chat-5",
+                    error: { code: "upstream_down", status: 503 },
+                    error_kind: "provider_unavailable",
+                    provider: "gemini",
+                },
+            }));
+            await new Promise((r) => stream.on("close", r));
+            (0, vitest_1.expect)(events).toEqual([
+                {
+                    type: "error",
+                    error: "Unknown error",
+                    errorKind: "provider_unavailable",
+                    provider: "gemini",
+                },
+            ]);
+            client.close();
+        });
         (0, vitest_1.it)("sends options with ChatSend", async () => {
             const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
             const streamPromise = client.chatSend("chat-3", "Hello", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,7 +22,7 @@
   "devDependencies": {
     "@types/node": "^24.13.2",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.0.18"
   },
   "dependencies": {