@babav/knowledge-core-client 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -124,6 +124,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;
@@ -304,6 +312,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) {

package/package.json

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

@@ -138,6 +138,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;
@@ -443,6 +451,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) ---