@babav/knowledge-core-client 0.22.4 → 0.23.0

package/dist/index.d.ts

@@ -214,6 +214,16 @@ export interface UploadUrl {
     gcs_uri: string;
     expires_in: number;
 }
+/** Batch of signed PUT URLs (corpora.uploadMany drives this). `items` is in request order. */
+export interface BatchUploadUrls {
+    items: Array<{
+        filename: string;
+        document_id: UUID;
+        upload_url: string;
+        gcs_uri: string;
+    }>;
+    expires_in: number;
+}
 export interface Conversation {
     id: UUID;
     title: string | null;
@@ -359,12 +369,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[];
@@ -404,11 +443,10 @@ export declare class KnowledgeCoreClient extends HttpBase {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Document>>;
-        /** Ingest a document ASYNCHRONOUSLY — resolves with the created document at
-         *  status `pending` (HTTP 202); track via documents.get() polling to
-         *  `indexed`/`failed`, or the tenant result webhook. Auto-routes by size: files
-         *  over ~30 MB go via the signed-URL upload path (Cloud Run caps requests at
-         *  ~32 MB), smaller files via one multipart request. One method, any size. */
+        /** Ingest ONE document ASYNCHRONOUSLY — resolves with the created document at status
+         *  `pending` (HTTP 202); track via documents.events()/get() or the tenant webhook.
+         *  ALWAYS uploads the bytes straight to GCS via a signed URL (uploadUrl → PUT → ingestFromUpload),
+         *  regardless of size — so there is NO request-size cap, ever. One method, any size. */
         ingestDocument: (id: UUID, a: {
             file: FileData;
             filename: string;
@@ -443,6 +481,21 @@ export declare class KnowledgeCoreClient extends HttpBase {
             folder_id?: UUID;
             custom_metadata?: Record<string, unknown>;
         }) => Promise<Document>;
+        /** Ingest MANY files in ONE go — any size, no 429, no client backoff. Mints all signed URLs in
+         *  one request, PUTs the bytes straight to GCS (bounded concurrency; never touches the KC), then
+         *  registers the whole batch in one request (N pending docs + N Cloud Tasks). `opts`
+         *  (folder_id / visibility / custom_metadata — the latter carries `owner`) applies to ALL files.
+         *  Resolves with the created `pending` documents. */
+        uploadMany: (id: UUID, files: Array<{
+            file: FileData;
+            filename: string;
+            content_type?: string;
+        }>, opts?: {
+            folder_id?: UUID;
+            visibility?: Visibility;
+            custom_metadata?: Record<string, unknown>;
+            concurrency?: number;
+        }) => Promise<Document[]>;
     };
     parse(a: {
         file: FileData;
@@ -466,6 +519,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 +533,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 });
@@ -194,24 +226,11 @@ export class KnowledgeCoreClient extends HttpBase {
         countDocuments: (id) => this.request("GET", `/v1/corpora/${id}/documents/count`),
         /** Documents in the corpus whose filename contains `q` (case-insensitive), paginated. */
         searchDocuments: (id, q, opts) => this.request("GET", `/v1/corpora/${id}/documents/search`, { query: { q, ...opts } }),
-        /** Ingest a document ASYNCHRONOUSLY — resolves with the created document at
-         *  status `pending` (HTTP 202); track via documents.get() polling to
-         *  `indexed`/`failed`, or the tenant result webhook. Auto-routes by size: files
-         *  over ~30 MB go via the signed-URL upload path (Cloud Run caps requests at
-         *  ~32 MB), smaller files via one multipart request. One method, any size. */
-        ingestDocument: (id, a) => {
-            if (fileSize(a.file) > MULTIPART_MAX_BYTES)
-                return this.corpora.uploadDocument(id, a);
-            const fd = new FormData();
-            fd.append("file", toBlob(a.file, a.content_type), a.filename);
-            if (a.custom_metadata)
-                fd.append("custom_metadata", JSON.stringify(a.custom_metadata));
-            if (a.visibility)
-                fd.append("visibility", a.visibility);
-            if (a.folder_id)
-                fd.append("folder_id", a.folder_id);
-            return this.request("POST", `/v1/corpora/${id}/documents`, { body: fd });
-        },
+        /** Ingest ONE document ASYNCHRONOUSLY — resolves with the created document at status
+         *  `pending` (HTTP 202); track via documents.events()/get() or the tenant webhook.
+         *  ALWAYS uploads the bytes straight to GCS via a signed URL (uploadUrl → PUT → ingestFromUpload),
+         *  regardless of size — so there is NO request-size cap, ever. One method, any size. */
+        ingestDocument: (id, a) => this.corpora.uploadDocument(id, a),
         /** Mint a signed PUT URL to upload a large file straight to GCS (bypasses the
          *  ~32 MB request limit). PUT the bytes to upload_url, then ingestFromUpload. */
         uploadUrl: (id, a) => this.request("POST", `/v1/corpora/${id}/documents/upload-url`, { json: a }),
@@ -235,6 +254,33 @@ export class KnowledgeCoreClient extends HttpBase {
                 visibility: a.visibility, folder_id: a.folder_id, custom_metadata: a.custom_metadata,
             });
         },
+        /** Ingest MANY files in ONE go — any size, no 429, no client backoff. Mints all signed URLs in
+         *  one request, PUTs the bytes straight to GCS (bounded concurrency; never touches the KC), then
+         *  registers the whole batch in one request (N pending docs + N Cloud Tasks). `opts`
+         *  (folder_id / visibility / custom_metadata — the latter carries `owner`) applies to ALL files.
+         *  Resolves with the created `pending` documents. */
+        uploadMany: async (id, files, opts) => {
+            if (files.length === 0)
+                return [];
+            const urls = await this.request("POST", `/v1/corpora/${id}/documents/upload-urls`, { json: { items: files.map((f) => ({ filename: f.filename, content_type: f.content_type })) } });
+            const items = urls.items; // same order as the request
+            await poolMap(files.length, opts?.concurrency ?? 6, async (i) => {
+                const f = files[i];
+                const it = items[i];
+                const put = await this._fetch(it.upload_url, {
+                    method: "PUT",
+                    body: toBlob(f.file, f.content_type),
+                    headers: f.content_type ? { "content-type": f.content_type } : {},
+                });
+                if (!put.ok)
+                    throw new KnowledgeCoreError(put.status, safeJson(await put.text()), it.upload_url);
+            });
+            const res = await this.request("POST", `/v1/corpora/${id}/documents/batch`, { json: {
+                    folder_id: opts?.folder_id, visibility: opts?.visibility, custom_metadata: opts?.custom_metadata,
+                    items: items.map((it) => ({ document_id: it.document_id, filename: it.filename })),
+                } });
+            return res.documents;
+        },
     };
     // --- parsing (utility: file -> text, stores nothing) ---
     parse(a) {
@@ -255,6 +301,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). */
+        events: (folderId, handlers, signal) => this._streamDocEvents(`/v1/folders/${folderId}/documents/events`, handlers, signal),
     };
     // --- documents ---
     documents = {
@@ -265,6 +313,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 = {
@@ -338,6 +390,15 @@ export class AdminClient extends HttpBase {
 // ---------------------------------------------------------------------------
 // helpers
 // ---------------------------------------------------------------------------
+/** Run fn(0..n-1) with bounded concurrency (used by uploadMany for the direct-to-GCS PUTs). */
+async function poolMap(n, concurrency, fn) {
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(concurrency, n)) }, async () => {
+        for (let i = next++; i < n; i = next++)
+            await fn(i);
+    });
+    await Promise.all(workers);
+}
 function dispatchSse(frame, h) {
     let event = "message";
     const dataLines = [];
@@ -384,3 +445,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.4",
+  "version": "0.23.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

@@ -235,6 +235,11 @@ export interface UploadUrl {
   gcs_uri: string;
   expires_in: number;
 }
+/** Batch of signed PUT URLs (corpora.uploadMany drives this). `items` is in request order. */
+export interface BatchUploadUrls {
+  items: Array<{ filename: string; document_id: UUID; upload_url: string; gcs_uri: string }>;
+  expires_in: number;
+}
 export interface Conversation {
   id: UUID;
   title: string | null;
@@ -480,6 +485,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 +549,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 });
@@ -542,20 +601,12 @@ export class KnowledgeCoreClient extends HttpBase {
     /** Documents in the corpus whose filename contains `q` (case-insensitive), paginated. */
     searchDocuments: (id: UUID, q: string, opts?: { limit?: number; cursor?: string }) =>
       this.request<Page<Document>>("GET", `/v1/corpora/${id}/documents/search`, { query: { q, ...opts } }),
-    /** Ingest a document ASYNCHRONOUSLY — resolves with the created document at
-     *  status `pending` (HTTP 202); track via documents.get() polling to
-     *  `indexed`/`failed`, or the tenant result webhook. Auto-routes by size: files
-     *  over ~30 MB go via the signed-URL upload path (Cloud Run caps requests at
-     *  ~32 MB), smaller files via one multipart request. One method, any size. */
-    ingestDocument: (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }) => {
-      if (fileSize(a.file) > MULTIPART_MAX_BYTES) return this.corpora.uploadDocument(id, a);
-      const fd = new FormData();
-      fd.append("file", toBlob(a.file, a.content_type), a.filename);
-      if (a.custom_metadata) fd.append("custom_metadata", JSON.stringify(a.custom_metadata));
-      if (a.visibility) fd.append("visibility", a.visibility);
-      if (a.folder_id) fd.append("folder_id", a.folder_id);
-      return this.request<Document>("POST", `/v1/corpora/${id}/documents`, { body: fd });
-    },
+    /** Ingest ONE document ASYNCHRONOUSLY — resolves with the created document at status
+     *  `pending` (HTTP 202); track via documents.events()/get() or the tenant webhook.
+     *  ALWAYS uploads the bytes straight to GCS via a signed URL (uploadUrl → PUT → ingestFromUpload),
+     *  regardless of size — so there is NO request-size cap, ever. One method, any size. */
+    ingestDocument: (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }) =>
+      this.corpora.uploadDocument(id, a),
     /** Mint a signed PUT URL to upload a large file straight to GCS (bypasses the
      *  ~32 MB request limit). PUT the bytes to upload_url, then ingestFromUpload. */
     uploadUrl: (id: UUID, a: { filename: string; content_type?: string }) =>
@@ -581,6 +632,41 @@ export class KnowledgeCoreClient extends HttpBase {
         visibility: a.visibility, folder_id: a.folder_id, custom_metadata: a.custom_metadata,
       });
     },
+    /** Ingest MANY files in ONE go — any size, no 429, no client backoff. Mints all signed URLs in
+     *  one request, PUTs the bytes straight to GCS (bounded concurrency; never touches the KC), then
+     *  registers the whole batch in one request (N pending docs + N Cloud Tasks). `opts`
+     *  (folder_id / visibility / custom_metadata — the latter carries `owner`) applies to ALL files.
+     *  Resolves with the created `pending` documents. */
+    uploadMany: async (
+      id: UUID,
+      files: Array<{ file: FileData; filename: string; content_type?: string }>,
+      opts?: { folder_id?: UUID; visibility?: Visibility; custom_metadata?: Record<string, unknown>; concurrency?: number },
+    ): Promise<Document[]> => {
+      if (files.length === 0) return [];
+      const urls = await this.request<BatchUploadUrls>(
+        "POST", `/v1/corpora/${id}/documents/upload-urls`,
+        { json: { items: files.map((f) => ({ filename: f.filename, content_type: f.content_type })) } },
+      );
+      const items = urls.items; // same order as the request
+      await poolMap(files.length, opts?.concurrency ?? 6, async (i) => {
+        const f = files[i]!;
+        const it = items[i]!;
+        const put = await this._fetch(it.upload_url, {
+          method: "PUT",
+          body: toBlob(f.file, f.content_type),
+          headers: f.content_type ? { "content-type": f.content_type } : {},
+        });
+        if (!put.ok) throw new KnowledgeCoreError(put.status, safeJson(await put.text()), it.upload_url);
+      });
+      const res = await this.request<{ documents: Document[] }>(
+        "POST", `/v1/corpora/${id}/documents/batch`,
+        { json: {
+            folder_id: opts?.folder_id, visibility: opts?.visibility, custom_metadata: opts?.custom_metadata,
+            items: items.map((it) => ({ document_id: it.document_id, filename: it.filename })),
+        } },
+      );
+      return res.documents;
+    },
   };
 
   // --- parsing (utility: file -> text, stores nothing) ---
@@ -607,6 +693,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 ---
@@ -620,6 +709,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 ---
@@ -710,6 +804,15 @@ export class AdminClient extends HttpBase {
 // ---------------------------------------------------------------------------
 // helpers
 // ---------------------------------------------------------------------------
+/** Run fn(0..n-1) with bounded concurrency (used by uploadMany for the direct-to-GCS PUTs). */
+async function poolMap(n: number, concurrency: number, fn: (i: number) => Promise<void>): Promise<void> {
+  let next = 0;
+  const workers = Array.from({ length: Math.max(1, Math.min(concurrency, n)) }, async () => {
+    for (let i = next++; i < n; i = next++) await fn(i);
+  });
+  await Promise.all(workers);
+}
+
 function dispatchSse(frame: string, h: StreamHandlers): void {
   let event = "message";
   const dataLines: string[] = [];
@@ -733,3 +836,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;
+  }
+}