@opensecret/react 1.3.7 → 1.3.8

package/dist/index.d.ts

@@ -48,6 +48,8 @@ declare namespace api {
         confirmAccountDeletion,
         fetchModels,
         uploadDocument,
+        checkDocumentStatus,
+        uploadDocumentWithPolling,
         LoginResponse,
         UserResponse,
         KVListItem,
@@ -67,7 +69,10 @@ declare namespace api {
         EncryptDataResponse,
         DecryptDataRequest,
         DocumentUploadRequest,
-        DocumentResponse
+        DocumentResponse,
+        DocumentUploadInitResponse,
+        DocumentStatusRequest,
+        DocumentStatusResponse
     }
 }
 
@@ -209,6 +214,33 @@ declare function changePlatformPassword(currentPassword: string, newPassword: st
     message: string;
 }>;
 
+/**
+ * Checks the status of a document processing task
+ * @param taskId - The task ID returned from uploadDocument
+ * @returns A promise resolving to the current status and optionally the processed document
+ * @throws {Error} If:
+ * - The user is not authenticated
+ * - The task ID is not found (404)
+ * - The user doesn't have access to the task (403)
+ *
+ * @description
+ * This function checks the status of an async document processing task.
+ * Status values include:
+ * - "pending": Document is queued for processing
+ * - "started": Document processing has begun
+ * - "success": Processing completed successfully (document field will be populated)
+ * - "failure": Processing failed (error field will contain details)
+ *
+ * Example usage:
+ * ```typescript
+ * const status = await checkDocumentStatus(taskId);
+ * if (status.status === "success" && status.document) {
+ *   console.log(status.document.text);
+ * }
+ * ```
+ */
+declare function checkDocumentStatus(taskId: string): Promise<DocumentStatusResponse>;
+
 /**
  * Confirms and completes the account deletion process
  * @param confirmationCode - The confirmation code from the verification email
@@ -320,6 +352,23 @@ export declare type DocumentResponse = {
     size: number;
 };
 
+export declare type DocumentStatusRequest = {
+    task_id: string;
+};
+
+export declare type DocumentStatusResponse = {
+    status: string;
+    progress?: number;
+    error?: string;
+    document?: DocumentResponse;
+};
+
+export declare type DocumentUploadInitResponse = {
+    task_id: string;
+    filename: string;
+    size: number;
+};
+
 declare type DocumentUploadRequest = {
     filename: string;
     content_base64: string;
@@ -1118,7 +1167,7 @@ export declare type OpenSecretContextType = {
     /**
      * Uploads a document for text extraction and processing
      * @param file - The file to upload (File or Blob object)
-     * @returns A promise resolving to the extracted document text and metadata
+     * @returns A promise resolving to the task ID and initial metadata
      * @throws {Error} If:
      * - The file exceeds 10MB size limit
      * - The user is not authenticated (or is a guest user)
@@ -1127,8 +1176,8 @@ export declare type OpenSecretContextType = {
      *
      * @description
      * This function uploads a document to the Tinfoil processing service which:
-     * 1. Extracts text from various document formats (PDF, DOCX, TXT, etc.)
-     * 2. Returns the extracted text ready for use in chat prompts
+     * 1. Accepts the document and returns a task ID immediately
+     * 2. Processes the document asynchronously in the background
      * 3. Maintains end-to-end encryption using session keys
      *
      * Common supported formats include PDF, DOCX, XLSX, PPTX, TXT, RTF, and more.
@@ -1138,10 +1187,71 @@ export declare type OpenSecretContextType = {
      * ```typescript
      * const file = new File(["content"], "document.pdf", { type: "application/pdf" });
      * const result = await context.uploadDocument(file);
-     * console.log(result.text); // Extracted text from the document
+     * console.log(result.task_id); // Task ID to check status
+     * ```
+     */
+    uploadDocument: (file: File | Blob) => Promise<api.DocumentUploadInitResponse>;
+    /**
+     * Checks the status of a document processing task
+     * @param taskId - The task ID returned from uploadDocument
+     * @returns A promise resolving to the current status and optionally the processed document
+     * @throws {Error} If:
+     * - The user is not authenticated
+     * - The task ID is not found (404)
+     * - The user doesn't have access to the task (403)
+     *
+     * @description
+     * This function checks the status of an async document processing task.
+     * Status values include:
+     * - "pending": Document is queued for processing
+     * - "started": Document processing has begun
+     * - "success": Processing completed successfully (document field will be populated)
+     * - "failure": Processing failed (error field will contain details)
+     *
+     * Example usage:
+     * ```typescript
+     * const status = await context.checkDocumentStatus(taskId);
+     * if (status.status === "success" && status.document) {
+     *   console.log(status.document.text);
+     * }
+     * ```
+     */
+    checkDocumentStatus: (taskId: string) => Promise<api.DocumentStatusResponse>;
+    /**
+     * Uploads a document and polls for completion
+     * @param file - The file to upload (File or Blob object)
+     * @param options - Optional configuration for polling behavior
+     * @returns A promise resolving to the processed document
+     * @throws {Error} If:
+     * - Upload fails (see uploadDocument errors)
+     * - Processing fails (error from server)
+     * - Processing times out (exceeds maxAttempts)
+     *
+     * @description
+     * This is a convenience function that combines uploadDocument and checkDocumentStatus
+     * to provide a simple interface that handles the async processing automatically.
+     *
+     * Options:
+     * - pollInterval: Time between status checks in milliseconds (default: 2000)
+     * - maxAttempts: Maximum number of status checks before timeout (default: 150 = 5 minutes)
+     * - onProgress: Callback function called on each status update
+     *
+     * Example usage:
+     * ```typescript
+     * const file = new File(["content"], "document.pdf", { type: "application/pdf" });
+     * const result = await context.uploadDocumentWithPolling(file, {
+     *   onProgress: (status, progress) => {
+     *     console.log(`Status: ${status}, Progress: ${progress || 0}%`);
+     *   }
+     * });
+     * console.log(result.text);
      * ```
      */
-    uploadDocument: (file: File | Blob) => Promise<DocumentResponse>;
+    uploadDocumentWithPolling: (file: File | Blob, options?: {
+        pollInterval?: number;
+        maxAttempts?: number;
+        onProgress?: (status: string, progress?: number) => void;
+    }) => Promise<DocumentResponse>;
 };
 
 /**
@@ -1901,7 +2011,7 @@ declare function updateProject(orgId: string, projectId: string, updates: {
 /**
  * Uploads a document for text extraction and processing
  * @param file - The file to upload (File or Blob object)
- * @returns A promise resolving to the extracted document text and metadata
+ * @returns A promise resolving to the task ID and initial metadata
  * @throws {Error} If:
  * - The file exceeds 10MB size limit
  * - The user is not authenticated
@@ -1911,8 +2021,8 @@ declare function updateProject(orgId: string, projectId: string, updates: {
  *
  * @description
  * This function uploads a document to the Tinfoil processing service which:
- * 1. Extracts text from various document formats (PDF, DOCX, TXT, etc.)
- * 2. Returns the extracted text ready for use in chat prompts
+ * 1. Accepts the document and returns a task ID immediately
+ * 2. Processes the document asynchronously in the background
  * 3. Maintains end-to-end encryption using session keys
  *
  * The file is converted to base64 before upload due to encryption requirements.
@@ -1922,10 +2032,47 @@ declare function updateProject(orgId: string, projectId: string, updates: {
  * ```typescript
  * const file = new File(["content"], "document.pdf", { type: "application/pdf" });
  * const result = await uploadDocument(file);
- * console.log(result.text); // Extracted text from the document
+ * console.log(result.task_id); // Task ID to check status
+ * ```
+ */
+declare function uploadDocument(file: File | Blob): Promise<DocumentUploadInitResponse>;
+
+/**
+ * Uploads a document and polls for completion
+ * @param file - The file to upload (File or Blob object)
+ * @param options - Optional configuration for polling behavior
+ * @returns A promise resolving to the processed document
+ * @throws {Error} If:
+ * - Upload fails (see uploadDocument errors)
+ * - Processing fails (error from server)
+ * - Processing times out (exceeds maxAttempts)
+ *
+ * @description
+ * This is a convenience function that combines uploadDocument and checkDocumentStatus
+ * to provide a simple interface that handles the async processing automatically.
+ * It uploads the document, then polls the status endpoint until processing completes.
+ *
+ * Options:
+ * - pollInterval: Time between status checks in milliseconds (default: 2000)
+ * - maxAttempts: Maximum number of status checks before timeout (default: 150 = 5 minutes)
+ * - onProgress: Callback function called on each status update
+ *
+ * Example usage:
+ * ```typescript
+ * const file = new File(["content"], "document.pdf", { type: "application/pdf" });
+ * const result = await uploadDocumentWithPolling(file, {
+ *   onProgress: (status, progress) => {
+ *     console.log(`Status: ${status}, Progress: ${progress || 0}%`);
+ *   }
+ * });
+ * console.log(result.text);
  * ```
  */
-declare function uploadDocument(file: File | Blob): Promise<DocumentResponse>;
+declare function uploadDocumentWithPolling(file: File | Blob, options?: {
+    pollInterval?: number;
+    maxAttempts?: number;
+    onProgress?: (status: string, progress?: number) => void;
+}): Promise<DocumentResponse>;
 
 export declare function useOpenSecret(): OpenSecretContextType;