@babav/knowledge-core-client 0.23.2 → 0.24.0

package/dist/index.d.ts

@@ -224,6 +224,24 @@ export interface BatchUploadUrls {
     }>;
     expires_in: number;
 }
+/** One RESUMABLE GCS upload session (corpora.createUploadSessions). Hand `upload_url` to the
+ *  browser: it PUTs bytes straight to GCS there, needing NO KC/tenant credential (the URI is the
+ *  per-object write capability). Resumable → a dropped connection resumes, not restarts. */
+export interface UploadSession {
+    filename: string;
+    document_id: UUID;
+    upload_url: string;
+    gcs_uri: string;
+    method: "PUT";
+    headers: Record<string, string>;
+    expires_at: string;
+}
+/** Per-item result of corpora.finalizeUploads (idempotent registration). */
+export interface FinalizeResult {
+    document_id: UUID;
+    status: "ingesting" | "failed";
+    error?: string;
+}
 export interface Conversation {
     id: UUID;
     title: string | null;
@@ -398,7 +416,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
@@ -496,6 +516,43 @@ export declare class KnowledgeCoreClient extends HttpBase {
             custom_metadata?: Record<string, unknown>;
             concurrency?: number;
         }) => Promise<Document[]>;
+        /** (server-side) Mint one RESUMABLE GCS upload session per file. Return only the sessions to the
+         *  browser; the browser PUTs bytes to each `upload_url` and needs NO KC/tenant credential (the
+         *  session URI IS the per-object write capability). `origin` = the browser app origin (scopes the
+         *  session; the bucket CORS must allow PUT/POST from it). */
+        createUploadSessions: (id: UUID, files: Array<{
+            filename: string;
+            content_type?: string;
+            size?: number;
+        }>, opts?: {
+            origin?: string;
+        }) => Promise<{
+            items: UploadSession[];
+        }>;
+        /** (server-side) Register documents whose bytes the browser already PUT to GCS. IDEMPOTENT +
+         *  PER-ITEM — safe to retry; each result is { document_id, status: 'ingesting' | 'failed' }. Call
+         *  after the browser reports its PUTs done. folder_id/visibility/custom_metadata apply to all
+         *  items. `document_id` is stable from createUploadSessions, so documents.events (SSE) tracks it. */
+        finalizeUploads: (id: UUID, items: Array<{
+            document_id: UUID;
+            filename: string;
+            content_type?: string;
+        }>, opts?: {
+            folder_id?: UUID;
+            visibility?: Visibility;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<{
+            results: FinalizeResult[];
+        }>;
+        /** (server-side) Cancel upload sessions the browser gave up on (idempotent cleanup). Pass the
+         *  `upload_url` from createUploadSessions so the resumable session is dropped; any pending row is
+         *  removed too. Safe to call repeatedly. */
+        abortUploadSessions: (id: UUID, items: Array<{
+            document_id: UUID;
+            upload_url?: string;
+        }>) => Promise<{
+            aborted: UUID[];
+        }>;
     };
     parse(a: {
         file: FileData;
@@ -519,7 +576,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 +598,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) {
@@ -281,6 +283,33 @@ export class KnowledgeCoreClient extends HttpBase {
                 } });
             return res.documents;
         },
+        // --- browser direct-to-GCS uploads (ANY size; the browser NEVER needs an API key) ---
+        // Split flow so the browser uploads bytes ITSELF while the tenant key stays server-side:
+        //   1. (server) createUploadSessions -> returns a resumable GCS session URI per file
+        //   2. (browser) PUT the bytes straight to each session URI (resumable; no credential)
+        //   3. (server) finalizeUploads -> register + enqueue; or abortUploadSessions to cancel
+        // Use this instead of uploadMany when bytes must not pass through your worker (browser -> GCS
+        // direct), e.g. multi-GB files or a browser that can't hold the tenant key.
+        /** (server-side) Mint one RESUMABLE GCS upload session per file. Return only the sessions to the
+         *  browser; the browser PUTs bytes to each `upload_url` and needs NO KC/tenant credential (the
+         *  session URI IS the per-object write capability). `origin` = the browser app origin (scopes the
+         *  session; the bucket CORS must allow PUT/POST from it). */
+        createUploadSessions: (id, files, opts) => this.request("POST", `/v1/corpora/${id}/documents/upload-sessions`, { json: {
+                items: files.map((f) => ({ filename: f.filename, content_type: f.content_type })),
+                origin: opts?.origin,
+            } }),
+        /** (server-side) Register documents whose bytes the browser already PUT to GCS. IDEMPOTENT +
+         *  PER-ITEM — safe to retry; each result is { document_id, status: 'ingesting' | 'failed' }. Call
+         *  after the browser reports its PUTs done. folder_id/visibility/custom_metadata apply to all
+         *  items. `document_id` is stable from createUploadSessions, so documents.events (SSE) tracks it. */
+        finalizeUploads: (id, items, opts) => this.request("POST", `/v1/corpora/${id}/documents/finalize`, { json: {
+                items, folder_id: opts?.folder_id, visibility: opts?.visibility,
+                custom_metadata: opts?.custom_metadata,
+            } }),
+        /** (server-side) Cancel upload sessions the browser gave up on (idempotent cleanup). Pass the
+         *  `upload_url` from createUploadSessions so the resumable session is dropped; any pending row is
+         *  removed too. Safe to call repeatedly. */
+        abortUploadSessions: (id, items) => this.request("POST", `/v1/corpora/${id}/documents/abort-uploads`, { json: { items } }),
     };
     // --- parsing (utility: file -> text, stores nothing) ---
     parse(a) {
@@ -301,7 +330,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 +347,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.24.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

@@ -240,6 +240,24 @@ export interface BatchUploadUrls {
   items: Array<{ filename: string; document_id: UUID; upload_url: string; gcs_uri: string }>;
   expires_in: number;
 }
+/** One RESUMABLE GCS upload session (corpora.createUploadSessions). Hand `upload_url` to the
+ *  browser: it PUTs bytes straight to GCS there, needing NO KC/tenant credential (the URI is the
+ *  per-object write capability). Resumable → a dropped connection resumes, not restarts. */
+export interface UploadSession {
+  filename: string;
+  document_id: UUID;
+  upload_url: string;
+  gcs_uri: string;
+  method: "PUT";
+  headers: Record<string, string>;
+  expires_at: string;
+}
+/** Per-item result of corpora.finalizeUploads (idempotent registration). */
+export interface FinalizeResult {
+  document_id: UUID;
+  status: "ingesting" | "failed";
+  error?: string;
+}
 export interface Conversation {
   id: UUID;
   title: string | null;
@@ -525,7 +543,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) {
@@ -667,6 +687,58 @@ export class KnowledgeCoreClient extends HttpBase {
       );
       return res.documents;
     },
+
+    // --- browser direct-to-GCS uploads (ANY size; the browser NEVER needs an API key) ---
+    // Split flow so the browser uploads bytes ITSELF while the tenant key stays server-side:
+    //   1. (server) createUploadSessions -> returns a resumable GCS session URI per file
+    //   2. (browser) PUT the bytes straight to each session URI (resumable; no credential)
+    //   3. (server) finalizeUploads -> register + enqueue; or abortUploadSessions to cancel
+    // Use this instead of uploadMany when bytes must not pass through your worker (browser -> GCS
+    // direct), e.g. multi-GB files or a browser that can't hold the tenant key.
+
+    /** (server-side) Mint one RESUMABLE GCS upload session per file. Return only the sessions to the
+     *  browser; the browser PUTs bytes to each `upload_url` and needs NO KC/tenant credential (the
+     *  session URI IS the per-object write capability). `origin` = the browser app origin (scopes the
+     *  session; the bucket CORS must allow PUT/POST from it). */
+    createUploadSessions: (
+      id: UUID,
+      files: Array<{ filename: string; content_type?: string; size?: number }>,
+      opts?: { origin?: string },
+    ): Promise<{ items: UploadSession[] }> =>
+      this.request<{ items: UploadSession[] }>(
+        "POST", `/v1/corpora/${id}/documents/upload-sessions`,
+        { json: {
+            items: files.map((f) => ({ filename: f.filename, content_type: f.content_type })),
+            origin: opts?.origin,
+        } },
+      ),
+
+    /** (server-side) Register documents whose bytes the browser already PUT to GCS. IDEMPOTENT +
+     *  PER-ITEM — safe to retry; each result is { document_id, status: 'ingesting' | 'failed' }. Call
+     *  after the browser reports its PUTs done. folder_id/visibility/custom_metadata apply to all
+     *  items. `document_id` is stable from createUploadSessions, so documents.events (SSE) tracks it. */
+    finalizeUploads: (
+      id: UUID,
+      items: Array<{ document_id: UUID; filename: string; content_type?: string }>,
+      opts?: { folder_id?: UUID; visibility?: Visibility; custom_metadata?: Record<string, unknown> },
+    ): Promise<{ results: FinalizeResult[] }> =>
+      this.request<{ results: FinalizeResult[] }>(
+        "POST", `/v1/corpora/${id}/documents/finalize`,
+        { json: {
+            items, folder_id: opts?.folder_id, visibility: opts?.visibility,
+            custom_metadata: opts?.custom_metadata,
+        } },
+      ),
+
+    /** (server-side) Cancel upload sessions the browser gave up on (idempotent cleanup). Pass the
+     *  `upload_url` from createUploadSessions so the resumable session is dropped; any pending row is
+     *  removed too. Safe to call repeatedly. */
+    abortUploadSessions: (
+      id: UUID,
+      items: Array<{ document_id: UUID; upload_url?: string }>,
+    ): Promise<{ aborted: UUID[] }> =>
+      this.request<{ aborted: UUID[] }>(
+        "POST", `/v1/corpora/${id}/documents/abort-uploads`, { json: { items } }),
   };
 
   // --- parsing (utility: file -> text, stores nothing) ---
@@ -693,7 +765,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 +788,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),
   };