@babav/knowledge-core-client 0.23.2 → 0.23.3

package/dist/index.d.ts

@@ -398,7 +398,9 @@ 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. */
+    /** Streaming query (SSE). Resolves when the stream ends (the Promise resolving is normal, not an
+     *  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>;
     /** 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
@@ -519,7 +521,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). */
+        /** Live ingestion-status stream for ONE folder. Same contract AND lifecycle rules as
+         *  `documents.events` (abort on unmount, one per view, open lazily, don't reopen on complete). */
         events: (folderId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) => Promise<void>;
     };
     documents: {
@@ -540,9 +543,25 @@ export declare class KnowledgeCoreClient extends HttpBase {
             deleting: UUID[];
             count: number;
         }>;
-        /** 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. */
+        /** Live ingestion-status stream for a corpus (SSE PUSH — replaces polling count). On connect:
+         *  `onSnapshot` (current state), then `onDocument` deltas as docs transition (pending → ingesting
+         *  → indexed | failed, and deleting → deleted), then `onComplete` when nothing is in-flight.
+         *  501 (onError) if the env has no doc-status bus — fall back to polling countDocuments().
+         *
+         *  A watcher is a held connection — manage its lifecycle:
+         *  1. ALWAYS abort on unmount/navigation via `signal` (else it stays open until the ~30-min cap):
+         *       const c = new AbortController();
+         *       kc.documents.events(id, handlers, c.signal).catch(()=>{});
+         *       return () => c.abort();          // e.g. React useEffect cleanup
+         *  2. ONE watcher per view — never one per document/row.
+         *  3. Open lazily — only while the view has in-flight docs, or right after an upload. If nothing
+         *     is in-flight the server sends `complete` and closes immediately (nothing to hold).
+         *  4. Do NOT reopen on `onComplete` — that's a permanent connection. Reopen only on NEW work
+         *     (another upload) or an unexpected disconnect while work remains.
+         *  5. De-dupe — keep the AbortController in a ref and abort the previous before opening a new one
+         *     (guards against re-renders / StrictMode double-mount).
+         *  6. On a network drop, reconnect with backoff and rebuild from the fresh `snapshot` (authoritative).
+         *  7. The Promise RESOLVING is normal (stream ended: complete or the cap) — only onError is a failure. */
         events: (corpusId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) => Promise<void>;
     };
     conversations: {

package/dist/index.js

@@ -151,7 +151,9 @@ export class KnowledgeCoreClient extends HttpBase {
     query(agentId, body) {
         return this.request("POST", `/v1/agents/${agentId}/query`, { json: body });
     }
-    /** Streaming query (SSE). Resolves when the stream ends. */
+    /** Streaming query (SSE). Resolves when the stream ends (the Promise resolving is normal, not an
+     *  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. */
     async queryStream(agentId, body, handlers, signal) {
         const res = await this.raw("POST", `/v1/agents/${agentId}/query/stream`, { json: body, signal });
         if (!res.ok || !res.body) {
@@ -301,7 +303,8 @@ export class KnowledgeCoreClient extends HttpBase {
         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). */
+        /** Live ingestion-status stream for ONE folder. Same contract AND lifecycle rules as
+         *  `documents.events` (abort on unmount, one per view, open lazily, don't reopen on complete). */
         events: (folderId, handlers, signal) => this._streamDocEvents(`/v1/folders/${folderId}/documents/events`, handlers, signal),
     };
     // --- documents ---
@@ -317,9 +320,25 @@ export class KnowledgeCoreClient extends HttpBase {
          *  one request. IDs not in the corpus are skipped. Completion observable via documents.events /
          *  documents.get() → 404. Returns { deleting: ids, count }. */
         deleteMany: (corpusId, documentIds) => this.request("POST", `/v1/corpora/${corpusId}/documents/batch-delete`, { json: { document_ids: documentIds } }),
-        /** 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. */
+        /** Live ingestion-status stream for a corpus (SSE PUSH — replaces polling count). On connect:
+         *  `onSnapshot` (current state), then `onDocument` deltas as docs transition (pending → ingesting
+         *  → indexed | failed, and deleting → deleted), then `onComplete` when nothing is in-flight.
+         *  501 (onError) if the env has no doc-status bus — fall back to polling countDocuments().
+         *
+         *  A watcher is a held connection — manage its lifecycle:
+         *  1. ALWAYS abort on unmount/navigation via `signal` (else it stays open until the ~30-min cap):
+         *       const c = new AbortController();
+         *       kc.documents.events(id, handlers, c.signal).catch(()=>{});
+         *       return () => c.abort();          // e.g. React useEffect cleanup
+         *  2. ONE watcher per view — never one per document/row.
+         *  3. Open lazily — only while the view has in-flight docs, or right after an upload. If nothing
+         *     is in-flight the server sends `complete` and closes immediately (nothing to hold).
+         *  4. Do NOT reopen on `onComplete` — that's a permanent connection. Reopen only on NEW work
+         *     (another upload) or an unexpected disconnect while work remains.
+         *  5. De-dupe — keep the AbortController in a ref and abort the previous before opening a new one
+         *     (guards against re-renders / StrictMode double-mount).
+         *  6. On a network drop, reconnect with backoff and rebuild from the fresh `snapshot` (authoritative).
+         *  7. The Promise RESOLVING is normal (stream ended: complete or the cap) — only onError is a failure. */
         events: (corpusId, handlers, signal) => this._streamDocEvents(`/v1/corpora/${corpusId}/documents/events`, handlers, signal),
     };
     // --- conversations ---

package/package.json

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

@@ -525,7 +525,9 @@ export class KnowledgeCoreClient extends HttpBase {
     return this.request("POST", `/v1/agents/${agentId}/query`, { json: body });
   }
 
-  /** Streaming query (SSE). Resolves when the stream ends. */
+  /** Streaming query (SSE). Resolves when the stream ends (the Promise resolving is normal, not an
+   *  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. */
   async queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void> {
     const res = await this.raw("POST", `/v1/agents/${agentId}/query/stream`, { json: body, signal });
     if (!res.ok || !res.body) {
@@ -693,7 +695,8 @@ 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). */
+    /** Live ingestion-status stream for ONE folder. Same contract AND lifecycle rules as
+     *  `documents.events` (abort on unmount, one per view, open lazily, don't reopen on complete). */
     events: (folderId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) =>
       this._streamDocEvents(`/v1/folders/${folderId}/documents/events`, handlers, signal),
   };
@@ -715,9 +718,25 @@ export class KnowledgeCoreClient extends HttpBase {
     deleteMany: (corpusId: UUID, documentIds: UUID[]) =>
       this.request<{ deleting: UUID[]; count: number }>(
         "POST", `/v1/corpora/${corpusId}/documents/batch-delete`, { json: { document_ids: documentIds } }),
-    /** 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. */
+    /** Live ingestion-status stream for a corpus (SSE PUSH — replaces polling count). On connect:
+     *  `onSnapshot` (current state), then `onDocument` deltas as docs transition (pending → ingesting
+     *  → indexed | failed, and deleting → deleted), then `onComplete` when nothing is in-flight.
+     *  501 (onError) if the env has no doc-status bus — fall back to polling countDocuments().
+     *
+     *  A watcher is a held connection — manage its lifecycle:
+     *  1. ALWAYS abort on unmount/navigation via `signal` (else it stays open until the ~30-min cap):
+     *       const c = new AbortController();
+     *       kc.documents.events(id, handlers, c.signal).catch(()=>{});
+     *       return () => c.abort();          // e.g. React useEffect cleanup
+     *  2. ONE watcher per view — never one per document/row.
+     *  3. Open lazily — only while the view has in-flight docs, or right after an upload. If nothing
+     *     is in-flight the server sends `complete` and closes immediately (nothing to hold).
+     *  4. Do NOT reopen on `onComplete` — that's a permanent connection. Reopen only on NEW work
+     *     (another upload) or an unexpected disconnect while work remains.
+     *  5. De-dupe — keep the AbortController in a ref and abort the previous before opening a new one
+     *     (guards against re-renders / StrictMode double-mount).
+     *  6. On a network drop, reconnect with backoff and rebuild from the fresh `snapshot` (authoritative).
+     *  7. The Promise RESOLVING is normal (stream ended: complete or the cap) — only onError is a failure. */
     events: (corpusId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) =>
       this._streamDocEvents(`/v1/corpora/${corpusId}/documents/events`, handlers, signal),
   };