@opensecret/react 1.3.6 → 1.3.8

package/dist/index.d.ts

@@ -47,6 +47,9 @@ declare namespace api {
         requestAccountDeletion,
         confirmAccountDeletion,
         fetchModels,
+        uploadDocument,
+        checkDocumentStatus,
+        uploadDocumentWithPolling,
         LoginResponse,
         UserResponse,
         KVListItem,
@@ -64,7 +67,12 @@ declare namespace api {
         ThirdPartyTokenResponse,
         EncryptDataRequest,
         EncryptDataResponse,
-        DecryptDataRequest
+        DecryptDataRequest,
+        DocumentUploadRequest,
+        DocumentResponse,
+        DocumentUploadInitResponse,
+        DocumentStatusRequest,
+        DocumentStatusResponse
     }
 }
 
@@ -206,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
@@ -311,6 +346,34 @@ declare type DeveloperResponse = PlatformUser & {
 
 export declare type DeveloperRole = "owner" | "admin" | "developer" | "viewer";
 
+export declare type DocumentResponse = {
+    text: string;
+    filename: string;
+    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;
+};
+
 declare type EmailSettings = {
     provider: string;
     send_from: string;
@@ -1101,6 +1164,94 @@ export declare type OpenSecretContextType = {
      * - Requires an active authentication session
      */
     fetchModels: () => Promise<Model[]>;
+    /**
+     * Uploads a document for text extraction and processing
+     * @param file - The file to upload (File or Blob object)
+     * @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)
+     * - Usage limits are exceeded (403)
+     * - Processing fails (500)
+     *
+     * @description
+     * This function uploads a document to the Tinfoil processing service which:
+     * 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.
+     * Guest users will receive a 401 Unauthorized error.
+     *
+     * Example usage:
+     * ```typescript
+     * const file = new File(["content"], "document.pdf", { type: "application/pdf" });
+     * const result = await context.uploadDocument(file);
+     * 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);
+     * ```
+     */
+    uploadDocumentWithPolling: (file: File | Blob, options?: {
+        pollInterval?: number;
+        maxAttempts?: number;
+        onProgress?: (status: string, progress?: number) => void;
+    }) => Promise<DocumentResponse>;
 };
 
 /**
@@ -1857,6 +2008,72 @@ declare function updateProject(orgId: string, projectId: string, updates: {
     status?: string;
 }): Promise<Project>;
 
+/**
+ * Uploads a document for text extraction and processing
+ * @param file - The file to upload (File or Blob object)
+ * @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
+ * - The user is a guest (401)
+ * - Usage limits are exceeded (403)
+ * - Processing fails (500)
+ *
+ * @description
+ * This function uploads a document to the Tinfoil processing service which:
+ * 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.
+ * Common supported formats include PDF, DOCX, XLSX, PPTX, TXT, RTF, and more.
+ *
+ * Example usage:
+ * ```typescript
+ * const file = new File(["content"], "document.pdf", { type: "application/pdf" });
+ * const result = await uploadDocument(file);
+ * 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 uploadDocumentWithPolling(file: File | Blob, options?: {
+    pollInterval?: number;
+    maxAttempts?: number;
+    onProgress?: (status: string, progress?: number) => void;
+}): Promise<DocumentResponse>;
+
 export declare function useOpenSecret(): OpenSecretContextType;
 
 export declare function useOpenSecretDeveloper(): OpenSecretDeveloperContextType;