@ekodb/ekodb-client 0.25.0 → 0.26.1

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

@@ -326,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.
@@ -1213,9 +1246,21 @@ export declare class EkoDBClient {
     agentsByDeployment(deploymentId: string): Promise<Record>;
     /** Get documents linked to a KV key */
     kvGetLinks(key: string): Promise<Record>;
-    /** Link a document to a KV key */
-    kvLink(key: string, collection: string, documentId: string): Promise<Record>;
-    /** Unlink a document from 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".
+     */
+    kvLink(key: string, collection: string, documentId: string, linkData?: {
+        keys?: string[];
+        field_path?: string;
+        metadata?: {
+            [key: string]: string;
+        };
+    }): Promise<Record>;
+    /** Unlink a document from a KV key. DELETE, with the triple in the path. */
     kvUnlink(key: string, collection: string, documentId: string): Promise<Record>;
     /** Create a new schedule */
     createSchedule(data: Record): Promise<Record>;
@@ -1227,10 +1272,25 @@ export declare class EkoDBClient {
     updateSchedule(id: string, data: Record): Promise<Record>;
     /** Delete a schedule */
     deleteSchedule(id: string): Promise<void>;
-    /** 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.
+     */
     pauseSchedule(id: string): Promise<Record>;
-    /** Resume a schedule */
+    /**
+     * Resume a paused schedule. See {@link pauseSchedule} for why this is an
+     * update rather than its own endpoint.
+     */
     resumeSchedule(id: string): Promise<Record>;
+    /**
+     * 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 setScheduleEnabled;
     /**
      * Check if a collection exists
      * @param collection - Collection name to check
@@ -1389,6 +1449,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,39 +2,6 @@
 /**
  * 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.HealthStatus = exports.HealthUnknown = exports.HealthDegraded = exports.HealthOK = exports.RateLimitError = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.SerializationFormat = void 0;
 exports.parseHealthStatus = parseHealthStatus;
@@ -360,11 +327,11 @@ 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
         for (const prefix of msgpackPaths) {
@@ -1454,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();
@@ -1462,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) {
@@ -1501,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();
             }
@@ -1913,15 +1910,21 @@ class EkoDBClient {
     // ========================================================================
     /** Get documents linked to a KV key */
     async kvGetLinks(key) {
-        return this.makeRequest("GET", `/api/kv/links/${encodeURIComponent(key)}`, undefined, 0, true);
+        return this.makeRequest("GET", `/api/kv/${encodeURIComponent(key)}/links`, undefined, 0, true);
     }
-    /** Link a document to a KV key */
-    async kvLink(key, collection, documentId) {
-        return this.makeRequest("POST", `/api/kv/link`, { key, collection, document_id: documentId }, 0, true);
+    /**
+     * 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, collection, documentId, linkData = {}) {
+        return this.makeRequest("POST", `/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, collection, documentId) {
-        return this.makeRequest("POST", `/api/kv/unlink`, { key, collection, document_id: documentId }, 0, true);
+        return this.makeRequest("DELETE", `/api/kv/${encodeURIComponent(key)}/links/${encodeURIComponent(collection)}/${encodeURIComponent(documentId)}`, undefined, 0, true);
     }
     // ========================================================================
     // SCHEDULE MANAGEMENT
@@ -1946,13 +1949,30 @@ class EkoDBClient {
     async deleteSchedule(id) {
         await this.makeRequest("DELETE", `/api/schedules/${encodeURIComponent(id)}`, undefined, 0, true);
     }
-    /** 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) {
-        return this.makeRequest("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) {
-        return this.makeRequest("POST", `/api/schedules/${encodeURIComponent(id)}/resume`, undefined, 0, true);
+        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.
+     */
+    async setScheduleEnabled(id, enabled) {
+        return this.makeRequest("PUT", `/api/schedules/${encodeURIComponent(id)}`, { enabled }, 0, true);
     }
     // ========================================================================
     // COLLECTION UTILITIES
@@ -2216,6 +2236,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() {
@@ -2429,7 +2475,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";
@@ -2761,9 +2807,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();