@babav/knowledge-core-client 0.23.3 → 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;
@@ -498,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;

package/dist/index.js

@@ -283,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) {

package/package.json

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