@babav/knowledge-core-client 0.29.0 → 0.31.0

package/dist/index.d.ts

@@ -95,7 +95,15 @@ export interface QueryRequest {
  * registers). */
 export type VisualLayout = "linear-flow" | "ring-cycle" | "nesting" | "radial-hub" | "side-by-side" | "stacked-layers" | "two-state" | "free";
 /** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
- * system as citations). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
+ * system as citations).
+ *
+ * UNIFORM DELIVERY: every register (chart / structural / conceptual / scenic) carries `image` — a
+ * PNG served BY KC. To display it, GET `image.url` (resolve a relative path against your KC base
+ * URL) with your normal API key; the response body is the PNG bytes. The URL is a stable, non-
+ * expiring KC endpoint for persisted/conversational visuals (`expires_at` absent), so it works on
+ * reload/copy/export and on later conversation retrieval — the client never fetches GCS and never
+ * parses inline SVG. `rendered_svg` appears ONLY as a rare fail-soft fallback (server rasterization
+ * failed); prefer `image` and treat `rendered_svg` as a last resort. */
 export interface Visual {
     id: string;
     anchor: {
@@ -107,13 +115,15 @@ export interface Visual {
     payload: Record<string, unknown>;
     /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
     layout: VisualLayout;
-    rendered_svg?: string;
+    /** PRIMARY: GET this (relative to your KC base, with your API key) -> PNG bytes. */
     image?: {
         url: string;
-        expires_at: number;
         width: number;
         height: number;
+        expires_at?: number;
     };
+    /** Fail-soft fallback only (rasterize/store failed); normally absent. */
+    rendered_svg?: string;
 }
 /** Visual stage (streaming): generation has started. MAY be emitted twice — first with
  *  `pending: null` (started, count unknown), then again with the ACCURATE post-vet count before
@@ -531,6 +541,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. */
@@ -896,3 +916,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. */
@@ -460,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.29.0",
+  "version": "0.31.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

@@ -129,7 +129,15 @@ export type VisualLayout =
   | "free";
 
 /** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
- * system as citations). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
+ * system as citations).
+ *
+ * UNIFORM DELIVERY: every register (chart / structural / conceptual / scenic) carries `image` — a
+ * PNG served BY KC. To display it, GET `image.url` (resolve a relative path against your KC base
+ * URL) with your normal API key; the response body is the PNG bytes. The URL is a stable, non-
+ * expiring KC endpoint for persisted/conversational visuals (`expires_at` absent), so it works on
+ * reload/copy/export and on later conversation retrieval — the client never fetches GCS and never
+ * parses inline SVG. `rendered_svg` appears ONLY as a rare fail-soft fallback (server rasterization
+ * failed); prefer `image` and treat `rendered_svg` as a last resort. */
 export interface Visual {
   id: string;
   anchor: { start: number; end: number };
@@ -138,8 +146,10 @@ export interface Visual {
   payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"svg"|"image", ...}
   /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
   layout: VisualLayout;
+  /** PRIMARY: GET this (relative to your KC base, with your API key) -> PNG bytes. */
+  image?: { url: string; width: number; height: number; expires_at?: number };
+  /** Fail-soft fallback only (rasterize/store failed); normally absent. */
   rendered_svg?: string;
-  image?: { url: string; expires_at: number; width: number; height: number };
 }
 
 /** Visual stage (streaming): generation has started. MAY be emitted twice — first with
@@ -645,6 +655,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. */
@@ -1001,6 +1022,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
 // ---------------------------------------------------------------------------