@babav/knowledge-core-client 0.22.3 → 0.22.5

package/dist/index.d.ts

@@ -359,12 +359,41 @@ export interface StreamHandlers {
     /** Catch-all for any event (incl. unknown ones). */
     onEvent?: (event: string, data: unknown) => void;
 }
+/** A live document status transition pushed over the ingestion-status SSE stream
+ *  (documents.events / folders.events). Replaces polling GET /documents/count. */
+export interface DocumentStatusEvent {
+    document_id: string;
+    corpus_id?: string | null;
+    folder_id?: string | null;
+    status: string;
+    filename?: string | null;
+    chunk_count?: number | null;
+    error?: string | null;
+    counts?: DocumentCount;
+}
+export interface DocumentEventsSnapshot {
+    documents: DocumentStatusEvent[];
+    counts: DocumentCount;
+}
+export interface DocumentEventHandlers {
+    /** Current state on connect (one query) — render the list from this. */
+    onSnapshot?: (s: DocumentEventsSnapshot) => void;
+    /** A single document's status changed (the moment it happened). Update that row + counts. */
+    onDocument?: (e: DocumentStatusEvent) => void;
+    /** Nothing is in-flight anymore — the stream is about to close. Authoritative final counts. */
+    onComplete?: (counts: DocumentCount) => void;
+    onError?: (err: unknown) => void;
+}
 export declare class KnowledgeCoreClient extends HttpBase {
     /** @param opts.apiKey a TENANT key, supplied by the caller. */
     constructor(opts: ClientOptions);
     query(agentId: UUID, body: QueryRequest): Promise<QueryResponse>;
     /** Streaming query (SSE). Resolves when the stream ends. */
     queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
+    /** 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. */
+    _streamDocEvents(path: string, handlers: DocumentEventHandlers, signal?: AbortSignal): Promise<void>;
     retrieve(body: {
         query: string;
         corpus_ids: UUID[];
@@ -454,7 +483,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
     folders: {
         create: (corpusId: UUID, name: string) => Promise<Folder>;
         rename: (folderId: UUID, name: string) => Promise<Folder>;
-        delete: (folderId: UUID) => Promise<void>;
+        delete: (folderId: UUID, confirmName?: string) => Promise<void>;
         listDocuments: (folderId: UUID, q?: {
             limit?: number;
             cursor?: string;
@@ -466,6 +495,8 @@ export declare class KnowledgeCoreClient extends HttpBase {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Document>>;
+        /** Live ingestion-status stream for ONE folder (same contract as documents.events). */
+        events: (folderId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) => Promise<void>;
     };
     documents: {
         get: (id: UUID) => Promise<Document>;
@@ -478,6 +509,10 @@ export declare class KnowledgeCoreClient extends HttpBase {
         }) => Promise<Document>;
         contentUrl: (id: UUID, disposition?: "inline" | "attachment") => Promise<ContentUrl>;
         delete: (id: UUID) => Promise<void>;
+        /** Live ingestion-status stream for a corpus (SSE PUSH — replaces polling count). Snapshot on
+         *  connect, then a delta per transition, then `complete` when nothing is in-flight. Abort via
+         *  the signal. 501 (onError) if the environment has no doc-status bus — fall back to polling. */
+        events: (corpusId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) => Promise<void>;
     };
     conversations: {
         create: (b?: {

package/dist/index.js

@@ -176,6 +176,38 @@ export class KnowledgeCoreClient extends HttpBase {
         if (buf.trim())
             dispatchSse(buf, handlers);
     }
+    /** 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. */
+    async _streamDocEvents(path, handlers, signal) {
+        const res = await this.raw("GET", path, { signal });
+        if (!res.ok || !res.body) {
+            const t = await res.text();
+            const err = new KnowledgeCoreError(res.status, safeJson(t), path);
+            if (handlers.onError) {
+                handlers.onError(err);
+                return;
+            }
+            throw err;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buf.indexOf("\n\n")) !== -1) {
+                const frame = buf.slice(0, idx);
+                buf = buf.slice(idx + 2);
+                dispatchDocEvent(frame, handlers);
+            }
+        }
+        if (buf.trim())
+            dispatchDocEvent(buf, handlers);
+    }
     // --- retrieve (cross-corpus primitive, no generation) ---
     retrieve(body) {
         return this.request("POST", "/v1/retrieve", { json: body });
@@ -246,12 +278,17 @@ export class KnowledgeCoreClient extends HttpBase {
     folders = {
         create: (corpusId, name) => this.request("POST", `/v1/corpora/${corpusId}/folders`, { json: { name } }),
         rename: (folderId, name) => this.request("PATCH", `/v1/folders/${folderId}`, { json: { name } }),
-        delete: (folderId) => this.request("DELETE", `/v1/folders/${folderId}`),
+        // Plain delete requires the folder to be EMPTY (else 409). Pass `confirmName` (the folder's
+        // name) to CASCADE — delete the folder AND every document in it (async, 202). The default
+        // folder cannot be deleted either way.
+        delete: (folderId, confirmName) => this.request("DELETE", `/v1/folders/${folderId}`, confirmName ? { query: { confirm: confirmName } } : undefined),
         listDocuments: (folderId, q) => this.request("GET", `/v1/folders/${folderId}/documents`, { query: q }),
         /** Count documents in the folder: { total, indexed, in_flight, failed }. */
         countDocuments: (folderId) => this.request("GET", `/v1/folders/${folderId}/documents/count`),
         /** Documents in the folder whose filename contains `q` (case-insensitive), paginated. */
         searchDocuments: (folderId, q, opts) => this.request("GET", `/v1/folders/${folderId}/documents/search`, { query: { q, ...opts } }),
+        /** Live ingestion-status stream for ONE folder (same contract as documents.events). */
+        events: (folderId, handlers, signal) => this._streamDocEvents(`/v1/folders/${folderId}/documents/events`, handlers, signal),
     };
     // --- documents ---
     documents = {
@@ -262,6 +299,10 @@ export class KnowledgeCoreClient extends HttpBase {
         update: (id, b) => this.request("PATCH", `/v1/documents/${id}`, { json: b }),
         contentUrl: (id, disposition = "inline") => this.request("GET", `/v1/documents/${id}/content-url`, { query: { disposition } }),
         delete: (id) => this.request("DELETE", `/v1/documents/${id}`),
+        /** Live ingestion-status stream for a corpus (SSE PUSH — replaces polling count). Snapshot on
+         *  connect, then a delta per transition, then `complete` when nothing is in-flight. Abort via
+         *  the signal. 501 (onError) if the environment has no doc-status bus — fall back to polling. */
+        events: (corpusId, handlers, signal) => this._streamDocEvents(`/v1/corpora/${corpusId}/documents/events`, handlers, signal),
     };
     // --- conversations ---
     conversations = {
@@ -381,3 +422,27 @@ function dispatchSse(frame, h) {
             break;
     }
 }
+function dispatchDocEvent(frame, h) {
+    let event = "message";
+    const dataLines = [];
+    for (const line of frame.split("\n")) {
+        if (line.startsWith("event:"))
+            event = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            dataLines.push(line.slice(5).trim());
+    }
+    if (dataLines.length === 0)
+        return; // heartbeat / comment frame
+    const data = safeJson(dataLines.join("\n"));
+    switch (event) {
+        case "snapshot":
+            h.onSnapshot?.(data);
+            break;
+        case "document":
+            h.onDocument?.(data);
+            break;
+        case "complete":
+            h.onComplete?.(data);
+            break;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.22.3",
+  "version": "0.22.5",
   "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

@@ -480,6 +480,32 @@ export interface StreamHandlers {
   onEvent?: (event: string, data: unknown) => void;
 }
 
+/** A live document status transition pushed over the ingestion-status SSE stream
+ *  (documents.events / folders.events). Replaces polling GET /documents/count. */
+export interface DocumentStatusEvent {
+  document_id: string;
+  corpus_id?: string | null;
+  folder_id?: string | null;
+  status: string;              // pending | ingesting | indexed | failed | deleting
+  filename?: string | null;
+  chunk_count?: number | null;
+  error?: string | null;
+  counts?: DocumentCount;      // running aggregate, included on each `document` delta
+}
+export interface DocumentEventsSnapshot {
+  documents: DocumentStatusEvent[];  // current state of every doc in the corpus/folder
+  counts: DocumentCount;
+}
+export interface DocumentEventHandlers {
+  /** Current state on connect (one query) — render the list from this. */
+  onSnapshot?: (s: DocumentEventsSnapshot) => void;
+  /** A single document's status changed (the moment it happened). Update that row + counts. */
+  onDocument?: (e: DocumentStatusEvent) => void;
+  /** Nothing is in-flight anymore — the stream is about to close. Authoritative final counts. */
+  onComplete?: (counts: DocumentCount) => void;
+  onError?: (err: unknown) => void;
+}
+
 // ---------------------------------------------------------------------------
 // Tenant client (data ops) — use a TENANT key
 // ---------------------------------------------------------------------------
@@ -518,6 +544,34 @@ export class KnowledgeCoreClient extends HttpBase {
     if (buf.trim()) dispatchSse(buf, handlers);
   }
 
+  /** 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. */
+  async _streamDocEvents(path: string, handlers: DocumentEventHandlers, signal?: AbortSignal): Promise<void> {
+    const res = await this.raw("GET", path, { signal });
+    if (!res.ok || !res.body) {
+      const t = await res.text();
+      const err = new KnowledgeCoreError(res.status, safeJson(t), path);
+      if (handlers.onError) { handlers.onError(err); return; }
+      throw err;
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let idx: number;
+      while ((idx = buf.indexOf("\n\n")) !== -1) {
+        const frame = buf.slice(0, idx);
+        buf = buf.slice(idx + 2);
+        dispatchDocEvent(frame, handlers);
+      }
+    }
+    if (buf.trim()) dispatchDocEvent(buf, handlers);
+  }
+
   // --- retrieve (cross-corpus primitive, no generation) ---
   retrieve(body: { query: string; corpus_ids: UUID[]; top_k_retrieved_chunks?: number; top_k_reranked_chunks?: number; rerank?: boolean; instruction?: string; filter?: MetadataFilter; }): Promise<{ retrieval_contents: RetrievalContent[] }> {
     return this.request("POST", "/v1/retrieve", { json: body });
@@ -594,7 +648,11 @@ export class KnowledgeCoreClient extends HttpBase {
   folders = {
     create: (corpusId: UUID, name: string) => this.request<Folder>("POST", `/v1/corpora/${corpusId}/folders`, { json: { name } }),
     rename: (folderId: UUID, name: string) => this.request<Folder>("PATCH", `/v1/folders/${folderId}`, { json: { name } }),
-    delete: (folderId: UUID) => this.request<void>("DELETE", `/v1/folders/${folderId}`),
+    // Plain delete requires the folder to be EMPTY (else 409). Pass `confirmName` (the folder's
+    // name) to CASCADE — delete the folder AND every document in it (async, 202). The default
+    // folder cannot be deleted either way.
+    delete: (folderId: UUID, confirmName?: string) =>
+      this.request<void>("DELETE", `/v1/folders/${folderId}`, confirmName ? { query: { confirm: confirmName } } : undefined),
     listDocuments: (folderId: UUID, q?: { limit?: number; cursor?: string }) =>
       this.request<Page<Document>>("GET", `/v1/folders/${folderId}/documents`, { query: q }),
     /** Count documents in the folder: { total, indexed, in_flight, failed }. */
@@ -603,6 +661,9 @@ export class KnowledgeCoreClient extends HttpBase {
     /** Documents in the folder whose filename contains `q` (case-insensitive), paginated. */
     searchDocuments: (folderId: UUID, q: string, opts?: { limit?: number; cursor?: string }) =>
       this.request<Page<Document>>("GET", `/v1/folders/${folderId}/documents/search`, { query: { q, ...opts } }),
+    /** Live ingestion-status stream for ONE folder (same contract as documents.events). */
+    events: (folderId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) =>
+      this._streamDocEvents(`/v1/folders/${folderId}/documents/events`, handlers, signal),
   };
 
   // --- documents ---
@@ -616,6 +677,11 @@ export class KnowledgeCoreClient extends HttpBase {
     contentUrl: (id: UUID, disposition: "inline" | "attachment" = "inline") =>
       this.request<ContentUrl>("GET", `/v1/documents/${id}/content-url`, { query: { disposition } }),
     delete: (id: UUID) => this.request<void>("DELETE", `/v1/documents/${id}`),
+    /** Live ingestion-status stream for a corpus (SSE PUSH — replaces polling count). Snapshot on
+     *  connect, then a delta per transition, then `complete` when nothing is in-flight. Abort via
+     *  the signal. 501 (onError) if the environment has no doc-status bus — fall back to polling. */
+    events: (corpusId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) =>
+      this._streamDocEvents(`/v1/corpora/${corpusId}/documents/events`, handlers, signal),
   };
 
   // --- conversations ---
@@ -729,3 +795,19 @@ function dispatchSse(frame: string, h: StreamHandlers): void {
     case "done": h.onDone?.(); break;
   }
 }
+
+function dispatchDocEvent(frame: string, h: DocumentEventHandlers): void {
+  let event = "message";
+  const dataLines: string[] = [];
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) dataLines.push(line.slice(5).trim());
+  }
+  if (dataLines.length === 0) return;  // heartbeat / comment frame
+  const data = safeJson(dataLines.join("\n"));
+  switch (event) {
+    case "snapshot": h.onSnapshot?.(data as DocumentEventsSnapshot); break;
+    case "document": h.onDocument?.(data as DocumentStatusEvent); break;
+    case "complete": h.onComplete?.(data as DocumentCount); break;
+  }
+}