@ekodb/ekodb-client 0.24.0 → 0.26.0

package/README.md

@@ -308,8 +308,11 @@ const joinResults = await client.find("users", multiQuery);
 
 #### Chat Models
 
-- `getChatModels(): Promise<Record<string, string[]>>` - Get all available chat
-  models by provider
+- `getChatModels(): Promise<ChatModels>` - Get all available chat models by
+  provider (`openai`, `anthropic`, `perplexity`, `gemini`), plus a per-provider
+  `providers` status map (`ok`, `not_configured`, `auth_failed`,
+  `permission_denied`, `billing`, `rate_limited`, `unavailable`, `unreachable`,
+  `request_error`) so a rejected key is distinguishable from a missing one
 - `getChatModel(provider: string): Promise<string[]>` - Get models for a
   specific provider
 

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;
@@ -277,12 +326,45 @@ export interface MergeSessionsRequest {
     bypass_ripple?: boolean;
 }
 /**
- * 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;
+    };
 }
 /**
  * Request to compact a chat session's history on demand.
@@ -861,9 +943,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.
      *
@@ -1328,6 +1422,19 @@ export type ChatStreamEvent = {
 } | {
     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;
 };
 /** Definition for a client-side tool the LLM can call. */
 export interface ClientToolDefinition {

package/dist/client.js

@@ -2,41 +2,9 @@
 /**
  * ekoDB TypeScript Client
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 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 +39,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 +1157,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 ==========
@@ -1367,7 +1421,22 @@ class EkoDBClient {
                     stream.close();
                     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) => {
+                    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();
@@ -1375,10 +1444,16 @@ class EkoDBClient {
                         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),
                             });
                         }
                         else if (eventData.content && eventData.message_id) {
@@ -1414,20 +1489,29 @@ class EkoDBClient {
                             break;
                         buffer += decoder.decode(value, { stream: true });
                         let nl;
-                        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"))
+                    for (const line of body.split("\n")) {
                         emitLine(line);
+                        if (stopped)
+                            break;
+                    }
                 }
                 stream.close();
             }
@@ -2129,6 +2213,32 @@ class EkoDBClient {
     }
 }
 exports.EkoDBClient = EkoDBClient;
+/**
+ * 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) {
+    const text = (value) => 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) {
+    const fields = {};
+    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;
+}
 /** EventEmitter-like interface for subscriptions and chat streams. */
 class EventStream {
     constructor() {
@@ -2342,7 +2452,7 @@ class WebSocketClient {
         return this.connectPromise;
     }
     async openSocket() {
-        const WebSocket = (await Promise.resolve().then(() => __importStar(require("ws")))).default;
+        const WebSocket = (await import("ws")).default;
         let url = this.wsURL;
         if (!url.endsWith("/api/ws")) {
             url += "/api/ws";
@@ -2674,9 +2784,12 @@ 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),
                     });
                     this.chatStreams.delete(chatId);
                     stream.close();