import type { Document } from "@/types/knowledge-base"; import type { PaginatedData } from "@/types/api"; import { apiGet, apiPost, apiPut, apiDelete, apiUpload } from "./api-client"; export async function listDocuments( knowledgeBaseName: string, options?: { maxResults?: number; nextToken?: string; subspace?: string }, ): Promise> { const params = new URLSearchParams(); params.set("maxResults", String(options?.maxResults ?? 20)); if (options?.nextToken) { params.set("nextToken", options.nextToken); } if (options?.subspace) { params.set("subspace", options.subspace); } return apiGet>( `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents?${params.toString()}`, ); } export async function getDocument( knowledgeBaseName: string, docId: string, options?: { subspace?: string }, ): Promise { const params = new URLSearchParams(); if (options?.subspace) params.set("subspace", options.subspace); const query = params.toString(); return apiGet( `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents/${encodeURIComponent(docId)}${ query ? `?${query}` : "" }`, ); } export interface AddDocumentItem { ossKey: string; metadata?: Record; /** * Glob patterns the server uses to filter members of a folder ossKey * during recursive ingestion. Ignored when `ossKey` points at a single * file. Only one wildcard is allowed per pattern: `prefix*` (anchored at * the start) or `*suffix` (anchored at the end). */ inclusionFilters?: string[]; exclusionFilters?: string[]; } export interface AddDocumentsRequest { knowledgeBaseName: string; subspace?: string; documents: AddDocumentItem[]; } export interface DocumentOperationResult { docId?: string; ossKey: string; status: string; failureReason?: string; } export async function addDocuments( request: AddDocumentsRequest, options?: { timeoutMs?: number }, ): Promise<{ documentDetails: DocumentOperationResult[] }> { const { knowledgeBaseName, documents, ...rest } = request; const url = `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents`; if (documents.length <= BATCH_SIZE) { return apiPost<{ documentDetails: DocumentOperationResult[] }>( url, { documents, ...rest }, options?.timeoutMs, ); } const allResults: DocumentOperationResult[] = []; for (let i = 0; i < documents.length; i += BATCH_SIZE) { const batch = documents.slice(i, i + BATCH_SIZE); const resp = await apiPost<{ documentDetails: DocumentOperationResult[] }>( url, { documents: batch, ...rest }, options?.timeoutMs, ); allResults.push(...resp.documentDetails); } return { documentDetails: allResults }; } export async function uploadDocuments( knowledgeBaseName: string, files: File[], options?: { subspace?: string; metadata?: Record }, ): Promise<{ documentDetails: DocumentOperationResult[] }> { const formData = new FormData(); for (const file of files) { formData.append("files", file); } if (options?.subspace) { formData.append("subspace", options.subspace); } if (options?.metadata) { formData.append("metadata", JSON.stringify(options.metadata)); } return apiUpload<{ documentDetails: DocumentOperationResult[] }>( `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents/upload`, formData, ); } // --------------------------------------------------------------------------- // Batched upload // --------------------------------------------------------------------------- // Server-side limit for documents per request across all batch endpoints. const BATCH_SIZE = 10; export const UPLOAD_TIMEOUT_MS = 5 * 60 * 1000; // 5 min per batch export interface BatchUploadProgress { completedBatches: number; totalBatches: number; completedFiles: number; totalFiles: number; results: DocumentOperationResult[]; errors: string[]; } /** * Upload files in sequential batches of {@link BATCH_SIZE} to avoid * hitting the client-side timeout on large folder uploads. Each batch is * sent as a separate multipart request with an extended per-batch timeout. * * Progress is reported via the optional {@link options.onProgress} callback * after every completed (or failed) batch. */ export async function uploadDocumentsBatched( knowledgeBaseName: string, files: File[], options?: { subspace?: string; metadata?: Record; onProgress?: (progress: BatchUploadProgress) => void; }, ): Promise<{ documentDetails: DocumentOperationResult[] }> { const totalFiles = files.length; const batches: File[][] = []; for (let i = 0; i < totalFiles; i += BATCH_SIZE) { batches.push(files.slice(i, i + BATCH_SIZE)); } const allResults: DocumentOperationResult[] = []; const allErrors: string[] = []; const uploadPath = `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents/upload`; for (let batchIdx = 0; batchIdx < batches.length; batchIdx++) { const batch = batches[batchIdx]; const formData = new FormData(); for (const file of batch) { formData.append("files", file); } if (options?.subspace) { formData.append("subspace", options.subspace); } if (options?.metadata) { formData.append("metadata", JSON.stringify(options.metadata)); } try { const resp = await apiUpload<{ documentDetails: DocumentOperationResult[]; }>(uploadPath, formData, UPLOAD_TIMEOUT_MS); allResults.push(...resp.documentDetails); } catch (err) { const msg = err instanceof Error ? err.message : String(err); allErrors.push(`Batch ${batchIdx + 1}: ${msg}`); } options?.onProgress?.({ completedBatches: batchIdx + 1, totalBatches: batches.length, completedFiles: Math.min((batchIdx + 1) * BATCH_SIZE, totalFiles), totalFiles, results: allResults, errors: allErrors, }); } // If every batch failed, throw so the caller sees a mutation error. if (allResults.length === 0 && allErrors.length > 0) { throw new Error( `All ${allErrors.length} batch(es) failed: ${allErrors[0]}`, ); } return { documentDetails: allResults }; } export interface DeleteDocumentsRequest { knowledgeBaseName: string; subspace?: string; documents: Array<{ docId?: string; ossKey?: string; }>; } export async function deleteDocuments( request: DeleteDocumentsRequest, onProgress?: (completed: number, total: number) => void, ): Promise<{ documentDetails: DocumentOperationResult[] }> { const { knowledgeBaseName, documents, ...rest } = request; const url = `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents`; if (documents.length <= BATCH_SIZE) { const result = await apiDelete<{ documentDetails: DocumentOperationResult[]; }>(url, { documents, ...rest }); onProgress?.(documents.length, documents.length); return result; } const allResults: DocumentOperationResult[] = []; for (let i = 0; i < documents.length; i += BATCH_SIZE) { const batch = documents.slice(i, i + BATCH_SIZE); const resp = await apiDelete<{ documentDetails: DocumentOperationResult[]; }>(url, { documents: batch, ...rest }); allResults.push(...resp.documentDetails); onProgress?.(Math.min(i + BATCH_SIZE, documents.length), documents.length); } return { documentDetails: allResults }; } // --------------------------------------------------------------------------- // Update document metadata // --------------------------------------------------------------------------- export interface UpdateDocumentRequest { knowledgeBaseName: string; docId: string; subspace?: string; /** * Overwrite-update semantics: when provided, replaces the document's entire * metadata object. Omit to leave metadata untouched. The backend also accepts * an explicit `null` to clear all metadata, but this client does not expose * that path — clearing all schema fields one-by-one is equivalent. */ metadata?: Record; } export async function updateDocument( request: UpdateDocumentRequest, ): Promise<{ documentDetails?: DocumentOperationResult }> { const { knowledgeBaseName, docId, ...rest } = request; const url = `/api/v1/knowledge-bases/${encodeURIComponent( knowledgeBaseName, )}/documents/${encodeURIComponent(docId)}`; return apiPut(url, rest); }