@babav/knowledge-core-client 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -73,7 +73,6 @@ export interface QueryResponse {
     groundedness: Groundedness | null;
     usage: Record<string, number | null>;
     standalone_query: string | null;
-    hops: string[];
 }
 export interface Citation {
     quote: string;
@@ -124,6 +123,14 @@ export interface DocumentCount {
     in_flight: number;
     failed: number;
 }
+/** A signed PUT URL for uploading a large file straight to GCS + the pre-allocated
+ *  document id to reference on from-upload. */
+export interface UploadUrl {
+    upload_url: string;
+    document_id: UUID;
+    gcs_uri: string;
+    expires_in: number;
+}
 export interface Conversation {
     id: UUID;
     title: string | null;
@@ -233,12 +240,6 @@ declare class HttpBase {
     protected pageAll<T>(path: string, query?: RequestOpts["query"]): Promise<T[]>;
 }
 export interface StreamHandlers {
-    onHop?: (d: {
-        n: number;
-        subquery: string;
-        status: string;
-        retrieval_contents?: number;
-    }) => void;
     onSources?: (d: {
         retrieval_contents: RetrievalContent[];
     }) => void;
@@ -304,6 +305,32 @@ export declare class KnowledgeCoreClient extends HttpBase {
             folder_id?: UUID;
             custom_metadata?: Record<string, unknown>;
         }) => Promise<Document>;
+        /** 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;
+        }) => Promise<UploadUrl>;
+        /** Ingest a file already PUT to GCS via uploadUrl. Resolves with the `pending`
+         *  document (202); track via documents.get() / webhook. */
+        ingestFromUpload: (id: UUID, a: {
+            document_id: UUID;
+            filename: string;
+            content_type?: string;
+            visibility?: Visibility;
+            folder_id?: UUID;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<Document>;
+        /** Convenience for LARGE files: uploadUrl → PUT the bytes to GCS → ingestFromUpload.
+         *  Use this instead of ingestDocument when the file may exceed ~32 MB. */
+        uploadDocument: (id: UUID, a: {
+            file: FileData;
+            filename: string;
+            content_type?: string;
+            visibility?: Visibility;
+            folder_id?: UUID;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<Document>;
     };
     parse(a: {
         file: FileData;

package/dist/index.js

@@ -217,6 +217,29 @@ export class KnowledgeCoreClient extends HttpBase {
                 fd.append("folder_id", a.folder_id);
             return this.request("POST", `/v1/corpora/${id}/documents`, { body: fd });
         },
+        /** 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 }),
+        /** Ingest a file already PUT to GCS via uploadUrl. Resolves with the `pending`
+         *  document (202); track via documents.get() / webhook. */
+        ingestFromUpload: (id, a) => this.request("POST", `/v1/corpora/${id}/documents/from-upload`, { json: a }),
+        /** Convenience for LARGE files: uploadUrl → PUT the bytes to GCS → ingestFromUpload.
+         *  Use this instead of ingestDocument when the file may exceed ~32 MB. */
+        uploadDocument: async (id, a) => {
+            const u = await this.corpora.uploadUrl(id, { filename: a.filename, content_type: a.content_type });
+            const put = await this._fetch(u.upload_url, {
+                method: "PUT",
+                body: toBlob(a.file, a.content_type),
+                headers: a.content_type ? { "content-type": a.content_type } : {},
+            });
+            if (!put.ok) {
+                throw new KnowledgeCoreError(put.status, safeJson(await put.text()), u.upload_url);
+            }
+            return this.corpora.ingestFromUpload(id, {
+                document_id: u.document_id, filename: a.filename, content_type: a.content_type,
+                visibility: a.visibility, folder_id: a.folder_id, custom_metadata: a.custom_metadata,
+            });
+        },
     };
     // --- parsing (utility: file -> text, stores nothing) ---
     parse(a) {
@@ -331,9 +354,6 @@ function dispatchSse(frame, h) {
     const data = safeJson(dataLines.join("\n"));
     h.onEvent?.(event, data);
     switch (event) {
-        case "hop":
-            h.onHop?.(data);
-            break;
         case "retrieval_contents":
             h.onSources?.(data);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -85,7 +85,6 @@ export interface QueryResponse {
   groundedness: Groundedness | null;
   usage: Record<string, number | null>;
   standalone_query: string | null;
-  hops: string[];
 }
 
 export interface Citation {
@@ -138,6 +137,14 @@ export interface DocumentCount {
   in_flight: number;
   failed: number;
 }
+/** A signed PUT URL for uploading a large file straight to GCS + the pre-allocated
+ *  document id to reference on from-upload. */
+export interface UploadUrl {
+  upload_url: string;
+  document_id: UUID;
+  gcs_uri: string;
+  expires_in: number;
+}
 export interface Conversation {
   id: UUID;
   title: string | null;
@@ -360,7 +367,6 @@ function toBlob(data: FileData, contentType?: string): Blob {
 // SSE handlers
 // ---------------------------------------------------------------------------
 export interface StreamHandlers {
-  onHop?: (d: { n: number; subquery: string; status: string; retrieval_contents?: number }) => void;
   onSources?: (d: { retrieval_contents: RetrievalContent[] }) => void;
   onToken?: (text: string) => void;
   onFinal?: (d: QueryResponse) => void;
@@ -443,6 +449,31 @@ export class KnowledgeCoreClient extends HttpBase {
       if (a.folder_id) fd.append("folder_id", a.folder_id);
       return this.request<Document>("POST", `/v1/corpora/${id}/documents`, { body: fd });
     },
+    /** 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 }) =>
+      this.request<UploadUrl>("POST", `/v1/corpora/${id}/documents/upload-url`, { json: a }),
+    /** Ingest a file already PUT to GCS via uploadUrl. Resolves with the `pending`
+     *  document (202); track via documents.get() / webhook. */
+    ingestFromUpload: (id: UUID, a: { document_id: UUID; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }) =>
+      this.request<Document>("POST", `/v1/corpora/${id}/documents/from-upload`, { json: a }),
+    /** Convenience for LARGE files: uploadUrl → PUT the bytes to GCS → ingestFromUpload.
+     *  Use this instead of ingestDocument when the file may exceed ~32 MB. */
+    uploadDocument: async (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }): Promise<Document> => {
+      const u = await this.corpora.uploadUrl(id, { filename: a.filename, content_type: a.content_type });
+      const put = await this._fetch(u.upload_url, {
+        method: "PUT",
+        body: toBlob(a.file, a.content_type),
+        headers: a.content_type ? { "content-type": a.content_type } : {},
+      });
+      if (!put.ok) {
+        throw new KnowledgeCoreError(put.status, safeJson(await put.text()), u.upload_url);
+      }
+      return this.corpora.ingestFromUpload(id, {
+        document_id: u.document_id, filename: a.filename, content_type: a.content_type,
+        visibility: a.visibility, folder_id: a.folder_id, custom_metadata: a.custom_metadata,
+      });
+    },
   };
 
   // --- parsing (utility: file -> text, stores nothing) ---
@@ -579,7 +610,6 @@ function dispatchSse(frame: string, h: StreamHandlers): void {
   const data = safeJson(dataLines.join("\n"));
   h.onEvent?.(event, data);
   switch (event) {
-    case "hop": h.onHop?.(data as never); break;
     case "retrieval_contents": h.onSources?.(data as never); break;
     case "token": h.onToken?.((data as { text: string }).text); break;
     case "final": h.onFinal?.(data as QueryResponse); break;