@babav/knowledge-core-client 0.28.0 → 0.30.0

package/dist/index.d.ts

@@ -181,6 +181,7 @@ export interface Corpus {
     id: UUID;
     name: string;
     description: string | null;
+    custom_metadata: Record<string, unknown>;
 }
 export interface Folder {
     id: UUID;
@@ -530,6 +531,16 @@ export declare class KnowledgeCoreClient extends HttpBase {
      *  error). Pass `signal` and abort() on unmount / when the user cancels or navigates away so the
      *  connection doesn't linger. Transient (ends on `done`) — no reopen logic needed. */
     queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
+    /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
+     *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
+     *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
+     *    New chat:  const chat = kc.chat(agentId, corpusIds);
+     *    Resume:    const chat = kc.chat(agentId, corpusIds, { conversationId });
+     *  The conversation is created LAZILY on the first `send()` (opening a "new chat" and never
+     *  sending leaves nothing behind). See ChatSession.send. */
+    chat(agentId: UUID, corpusIds: UUID[], opts?: {
+        conversationId?: UUID;
+    }): ChatSession;
     /** Shared SSE reader for the document-status streams (documents.events / folders.events).
      *  Resolves when the stream ends (server sends `complete` once nothing is in-flight, or the
      *  cap is hit). Abort via the signal to stop watching. Throws 501 if the env has no bus. */
@@ -549,16 +560,25 @@ export declare class KnowledgeCoreClient extends HttpBase {
         create: (b: {
             name: string;
             description?: string;
+            custom_metadata?: Record<string, unknown>;
         }) => Promise<Corpus>;
         list: (q?: {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Corpus>>;
         listAll: () => Promise<Corpus[]>;
+        /** Filter corpora by custom_metadata using the same metadata filter as documents. */
+        search: (b: {
+            filter?: MetadataFilter;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Corpus>>;
         get: (id: UUID) => Promise<Corpus>;
+        /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
         update: (id: UUID, b: {
             name?: string;
             description?: string;
+            custom_metadata?: Record<string, unknown>;
         }) => Promise<Corpus>;
         delete: (id: UUID, confirmName: string) => Promise<void>;
         listFolders: (id: UUID) => Promise<Folder[]>;
@@ -886,3 +906,37 @@ export declare class AdminClient extends HttpBase {
         delete: (id: UUID) => Promise<void>;
     };
 }
+export interface ChatSendOptions extends StreamHandlers {
+    overrides?: QueryRequest["overrides"];
+    filter?: QueryRequest["filter"];
+    visual?: QueryRequest["visual"];
+    /** Abort on unmount / navigation so the SSE connection doesn't linger. */
+    signal?: AbortSignal;
+    /** Applied ONLY when the conversation is lazily created on the FIRST message. `title` defaults
+     *  to the message text (truncated) so a chat is never left untitled. */
+    title?: string;
+    customMetadata?: Record<string, unknown>;
+    ephemeral?: boolean;
+    /** Fired with the conversation id the moment it is created (first message) or resumed — use it to
+     *  update the sidebar/URL/route IMMEDIATELY, before the answer streams. */
+    onConversationId?: (id: UUID) => void;
+}
+/** A chat session bound to ONE conversation (created via `kc.chat(...)`). Every `send()` is ALWAYS
+ *  conversational: the conversation_id is attached for you, so a chat turn can never be a
+ *  non-persisted one-shot. Combined with server-side persist-on-close salvage + the orphan reaper,
+ *  a chat turn is never lost and a chat conversation is never left blank. */
+export declare class ChatSession {
+    #private;
+    /** The conversation id — null until the first `send()` (unless resumed). */
+    conversationId: UUID | null;
+    constructor(kc: KnowledgeCoreClient, agentId: UUID, corpusIds: UUID[], conversationId: UUID | null);
+    /** Send a chat message (streaming). Lazily creates the conversation on the first message and
+     *  ALWAYS passes conversation_id, so the turn is persisted. `onConversationId` fires before the
+     *  stream so you can show the conversation immediately. Pass `signal` to cancel on unmount. */
+    send(text: string, o?: ChatSendOptions): Promise<void>;
+    /** The conversation history (messages), once it exists. Empty page before the first send. */
+    messages(q?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Message>>;
+}

package/dist/index.js

@@ -178,6 +178,16 @@ export class KnowledgeCoreClient extends HttpBase {
         if (buf.trim())
             dispatchSse(buf, handlers);
     }
+    /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
+     *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
+     *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
+     *    New chat:  const chat = kc.chat(agentId, corpusIds);
+     *    Resume:    const chat = kc.chat(agentId, corpusIds, { conversationId });
+     *  The conversation is created LAZILY on the first `send()` (opening a "new chat" and never
+     *  sending leaves nothing behind). See ChatSession.send. */
+    chat(agentId, corpusIds, opts) {
+        return new ChatSession(this, agentId, corpusIds, opts?.conversationId ?? null);
+    }
     /** Shared SSE reader for the document-status streams (documents.events / folders.events).
      *  Resolves when the stream ends (server sends `complete` once nothing is in-flight, or the
      *  cap is hit). Abort via the signal to stop watching. Throws 501 if the env has no bus. */
@@ -219,7 +229,10 @@ export class KnowledgeCoreClient extends HttpBase {
         create: (b) => this.request("POST", "/v1/corpora", { json: b }),
         list: (q) => this.request("GET", "/v1/corpora", { query: q }),
         listAll: () => this.pageAll("/v1/corpora"),
+        /** Filter corpora by custom_metadata using the same metadata filter as documents. */
+        search: (b) => this.request("POST", "/v1/corpora/search", { json: b }),
         get: (id) => this.request("GET", `/v1/corpora/${id}`),
+        /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
         update: (id, b) => this.request("PATCH", `/v1/corpora/${id}`, { json: b }),
         delete: (id, confirmName) => this.request("DELETE", `/v1/corpora/${id}`, { query: { confirm: confirmName } }),
         listFolders: (id) => this.pageAll(`/v1/corpora/${id}/folders`),
@@ -457,6 +470,50 @@ export class AdminClient extends HttpBase {
         delete: (id) => this.request("DELETE", `/v1/agents/${id}`),
     };
 }
+/** A chat session bound to ONE conversation (created via `kc.chat(...)`). Every `send()` is ALWAYS
+ *  conversational: the conversation_id is attached for you, so a chat turn can never be a
+ *  non-persisted one-shot. Combined with server-side persist-on-close salvage + the orphan reaper,
+ *  a chat turn is never lost and a chat conversation is never left blank. */
+export class ChatSession {
+    #kc;
+    #agentId;
+    #corpusIds;
+    #creating = null;
+    /** The conversation id — null until the first `send()` (unless resumed). */
+    conversationId;
+    constructor(kc, agentId, corpusIds, conversationId) {
+        this.#kc = kc;
+        this.#agentId = agentId;
+        this.#corpusIds = corpusIds;
+        this.conversationId = conversationId;
+    }
+    /** Lazy create-once (concurrency-safe): the first send starts creation; a racing send awaits it. */
+    #ensure(o, text) {
+        if (this.conversationId)
+            return Promise.resolve(this.conversationId);
+        if (!this.#creating) {
+            this.#creating = this.#kc.conversations
+                .create({ title: o.title ?? text.slice(0, 80), custom_metadata: o.customMetadata, ephemeral: o.ephemeral })
+                .then((c) => { this.conversationId = c.id; return c.id; });
+        }
+        return this.#creating;
+    }
+    /** Send a chat message (streaming). Lazily creates the conversation on the first message and
+     *  ALWAYS passes conversation_id, so the turn is persisted. `onConversationId` fires before the
+     *  stream so you can show the conversation immediately. Pass `signal` to cancel on unmount. */
+    async send(text, o = {}) {
+        const convId = await this.#ensure(o, text);
+        o.onConversationId?.(convId);
+        await this.#kc.queryStream(this.#agentId, { corpus_ids: this.#corpusIds, query: text, conversation_id: convId,
+            overrides: o.overrides, filter: o.filter, visual: o.visual }, o, o.signal);
+    }
+    /** The conversation history (messages), once it exists. Empty page before the first send. */
+    messages(q) {
+        if (!this.conversationId)
+            return Promise.resolve({ items: [], next_cursor: null });
+        return this.#kc.conversations.listMessages(this.conversationId, q);
+    }
+}
 // ---------------------------------------------------------------------------
 // helpers
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps). Includes the babav.visual grammar TYPES at the ./visual subpath (types only; all visual rendering is server-side).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -211,6 +211,7 @@ export interface Corpus {
   id: UUID;
   name: string;
   description: string | null;
+  custom_metadata: Record<string, unknown>;
 }
 export interface Folder {
   id: UUID;
@@ -644,6 +645,17 @@ export class KnowledgeCoreClient extends HttpBase {
     if (buf.trim()) dispatchSse(buf, handlers);
   }
 
+  /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
+   *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
+   *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
+   *    New chat:  const chat = kc.chat(agentId, corpusIds);
+   *    Resume:    const chat = kc.chat(agentId, corpusIds, { conversationId });
+   *  The conversation is created LAZILY on the first `send()` (opening a "new chat" and never
+   *  sending leaves nothing behind). See ChatSession.send. */
+  chat(agentId: UUID, corpusIds: UUID[], opts?: { conversationId?: UUID }): ChatSession {
+    return new ChatSession(this, agentId, corpusIds, opts?.conversationId ?? null);
+  }
+
   /** Shared SSE reader for the document-status streams (documents.events / folders.events).
    *  Resolves when the stream ends (server sends `complete` once nothing is in-flight, or the
    *  cap is hit). Abort via the signal to stop watching. Throws 501 if the env has no bus. */
@@ -679,12 +691,16 @@ export class KnowledgeCoreClient extends HttpBase {
 
   // --- corpora ---
   corpora = {
-    create: (b: { name: string; description?: string }) =>
+    create: (b: { name: string; description?: string; custom_metadata?: Record<string, unknown> }) =>
       this.request<Corpus>("POST", "/v1/corpora", { json: b }),
     list: (q?: { limit?: number; cursor?: string }) => this.request<Page<Corpus>>("GET", "/v1/corpora", { query: q }),
     listAll: () => this.pageAll<Corpus>("/v1/corpora"),
+    /** Filter corpora by custom_metadata using the same metadata filter as documents. */
+    search: (b: { filter?: MetadataFilter; limit?: number; cursor?: string }) =>
+      this.request<Page<Corpus>>("POST", "/v1/corpora/search", { json: b }),
     get: (id: UUID) => this.request<Corpus>("GET", `/v1/corpora/${id}`),
-    update: (id: UUID, b: { name?: string; description?: string }) =>
+    /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
+    update: (id: UUID, b: { name?: string; description?: string; custom_metadata?: Record<string, unknown> }) =>
       this.request<Corpus>("PATCH", `/v1/corpora/${id}`, { json: b }),
     delete: (id: UUID, confirmName: string) => this.request<void>("DELETE", `/v1/corpora/${id}`, { query: { confirm: confirmName } }),
     listFolders: (id: UUID) => this.pageAll<Folder>(`/v1/corpora/${id}/folders`),
@@ -996,6 +1012,74 @@ export class AdminClient extends HttpBase {
   };
 }
 
+export interface ChatSendOptions extends StreamHandlers {
+  overrides?: QueryRequest["overrides"];
+  filter?: QueryRequest["filter"];
+  visual?: QueryRequest["visual"];
+  /** Abort on unmount / navigation so the SSE connection doesn't linger. */
+  signal?: AbortSignal;
+  /** Applied ONLY when the conversation is lazily created on the FIRST message. `title` defaults
+   *  to the message text (truncated) so a chat is never left untitled. */
+  title?: string;
+  customMetadata?: Record<string, unknown>;
+  ephemeral?: boolean;
+  /** Fired with the conversation id the moment it is created (first message) or resumed — use it to
+   *  update the sidebar/URL/route IMMEDIATELY, before the answer streams. */
+  onConversationId?: (id: UUID) => void;
+}
+
+/** A chat session bound to ONE conversation (created via `kc.chat(...)`). Every `send()` is ALWAYS
+ *  conversational: the conversation_id is attached for you, so a chat turn can never be a
+ *  non-persisted one-shot. Combined with server-side persist-on-close salvage + the orphan reaper,
+ *  a chat turn is never lost and a chat conversation is never left blank. */
+export class ChatSession {
+  #kc: KnowledgeCoreClient;
+  #agentId: UUID;
+  #corpusIds: UUID[];
+  #creating: Promise<UUID> | null = null;
+  /** The conversation id — null until the first `send()` (unless resumed). */
+  conversationId: UUID | null;
+
+  constructor(kc: KnowledgeCoreClient, agentId: UUID, corpusIds: UUID[], conversationId: UUID | null) {
+    this.#kc = kc;
+    this.#agentId = agentId;
+    this.#corpusIds = corpusIds;
+    this.conversationId = conversationId;
+  }
+
+  /** Lazy create-once (concurrency-safe): the first send starts creation; a racing send awaits it. */
+  #ensure(o: ChatSendOptions, text: string): Promise<UUID> {
+    if (this.conversationId) return Promise.resolve(this.conversationId);
+    if (!this.#creating) {
+      this.#creating = this.#kc.conversations
+        .create({ title: o.title ?? text.slice(0, 80), custom_metadata: o.customMetadata, ephemeral: o.ephemeral })
+        .then((c) => { this.conversationId = c.id; return c.id; });
+    }
+    return this.#creating;
+  }
+
+  /** Send a chat message (streaming). Lazily creates the conversation on the first message and
+   *  ALWAYS passes conversation_id, so the turn is persisted. `onConversationId` fires before the
+   *  stream so you can show the conversation immediately. Pass `signal` to cancel on unmount. */
+  async send(text: string, o: ChatSendOptions = {}): Promise<void> {
+    const convId = await this.#ensure(o, text);
+    o.onConversationId?.(convId);
+    await this.#kc.queryStream(
+      this.#agentId,
+      { corpus_ids: this.#corpusIds, query: text, conversation_id: convId,
+        overrides: o.overrides, filter: o.filter, visual: o.visual },
+      o,
+      o.signal,
+    );
+  }
+
+  /** The conversation history (messages), once it exists. Empty page before the first send. */
+  messages(q?: { limit?: number; cursor?: string }): Promise<Page<Message>> {
+    if (!this.conversationId) return Promise.resolve({ items: [], next_cursor: null });
+    return this.#kc.conversations.listMessages(this.conversationId, q);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // helpers
 // ---------------------------------------------------------------------------