@opensecret/react 1.3.7 → 1.4.0

package/dist/index.d.ts

@@ -47,7 +47,12 @@ declare namespace api {
         requestAccountDeletion,
         confirmAccountDeletion,
         fetchModels,
+        createApiKey,
+        listApiKeys,
+        deleteApiKey,
         uploadDocument,
+        checkDocumentStatus,
+        uploadDocumentWithPolling,
         LoginResponse,
         UserResponse,
         KVListItem,
@@ -67,7 +72,13 @@ declare namespace api {
         EncryptDataResponse,
         DecryptDataRequest,
         DocumentUploadRequest,
-        DocumentResponse
+        DocumentResponse,
+        DocumentUploadInitResponse,
+        ApiKey,
+        ApiKeyCreateResponse,
+        ApiKeyListResponse,
+        DocumentStatusRequest,
+        DocumentStatusResponse
     }
 }
 
@@ -119,6 +130,17 @@ export declare interface ApiEndpoint {
     context: ApiContext;
 }
 
+export declare type ApiKey = {
+    name: string;
+    created_at: string;
+};
+
+export declare type ApiKeyCreateResponse = ApiKey & {
+    key: string;
+};
+
+export declare type ApiKeyListResponse = ApiKey[];
+
 /**
  * Response from initiating Apple OAuth authentication
  * @property auth_url - The Apple authorization URL to redirect the user to
@@ -209,6 +231,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
@@ -248,12 +297,40 @@ declare function confirmPlatformPasswordReset(email: string, alphanumericCode: s
 
 declare function convertGuestToEmailAccount(email: string, password: string, name?: string | null): Promise<void>;
 
+/**
+ * Creates a new API key for the authenticated user
+ * @param name - A descriptive name for the API key
+ * @returns A promise resolving to the API key details with the key value (only shown once)
+ * @throws {Error} If:
+ * - The user is not authenticated
+ * - The name is invalid
+ * - The request fails
+ *
+ * @description
+ * IMPORTANT: The `key` field is only returned once during creation and cannot be retrieved again.
+ * The SDK consumer should prompt users to save the key immediately.
+ *
+ * Example usage:
+ * ```typescript
+ * const apiKey = await createApiKey("Production Key");
+ * console.log(apiKey.key); // UUID format: 550e8400-e29b-41d4-a716-446655440000
+ * // Save this key securely - it won't be shown again!
+ * ```
+ */
+export declare function createApiKey(name: string): Promise<ApiKeyCreateResponse>;
+
+export declare function createCustomFetch(options?: CustomFetchOptions): (url: RequestInfo, init?: RequestInit) => Promise<Response>;
+
 declare function createOrganization(name: string): Promise<Organization>;
 
 declare function createProject(orgId: string, name: string, description?: string): Promise<Project>;
 
 declare function createProjectSecret(orgId: string, projectId: string, keyName: string, secret: string): Promise<ProjectSecret>;
 
+export declare interface CustomFetchOptions {
+    apiKey?: string;
+}
+
 /**
  * Decrypts data that was previously encrypted with the user's key
  * @param encryptedData - Base64-encoded encrypted data string
@@ -298,6 +375,29 @@ declare type DecryptDataRequest = {
     };
 };
 
+/**
+ * Deletes an API key by its name
+ * @param name - The name of the API key to delete
+ * @returns A promise resolving to void
+ * @throws {Error} If:
+ * - The user is not authenticated
+ * - The API key with this name is not found
+ * - The user doesn't own the API key
+ * - The request fails
+ *
+ * @description
+ * Permanently deletes an API key. This action cannot be undone.
+ * Any requests using the deleted key will immediately fail with 401 Unauthorized.
+ * Names are unique per user, so this uniquely identifies the key to delete.
+ *
+ * Example usage:
+ * ```typescript
+ * await deleteApiKey("Production Key");
+ * console.log("API key deleted successfully");
+ * ```
+ */
+export declare function deleteApiKey(name: string): Promise<void>;
+
 declare function deleteOrganization(orgId: string): Promise<void>;
 
 declare function deleteOrganizationInvite(orgId: string, inviteCode: string): Promise<{
@@ -320,6 +420,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;
@@ -398,13 +515,14 @@ declare function fetchLogout(refresh_token: string): Promise<void>;
 
 /**
  * Fetches available AI models from the OpenAI-compatible API
+ * @param apiKey - Optional API key to use instead of JWT token
  * @returns A promise resolving to an array of Model objects
  * @throws {Error} If:
- * - The user is not authenticated
+ * - The user is not authenticated (no JWT token or API key)
  * - The request fails
  * - The response format is invalid
  */
-declare function fetchModels(): Promise<Model[]>;
+declare function fetchModels(apiKey?: string): Promise<Model[]>;
 
 /**
  * Fetches the private key as a mnemonic phrase with optional derivation paths
@@ -627,6 +745,30 @@ export declare type KVListItem = {
     updated_at: number;
 };
 
+/**
+ * Lists all API keys for the authenticated user
+ * @returns A promise resolving to an object containing an array of API key metadata (without the actual keys)
+ * @throws {Error} If:
+ * - The user is not authenticated
+ * - The request fails
+ *
+ * @description
+ * Returns metadata about all API keys associated with the user's account.
+ * Note that the actual key values are never returned - they are only shown once during creation.
+ * The keys are sorted by created_at in descending order (newest first).
+ *
+ * Example usage:
+ * ```typescript
+ * const response = await listApiKeys();
+ * response.keys.forEach(key => {
+ *   console.log(`${key.name} created at ${key.created_at}`);
+ * });
+ * ```
+ */
+export declare function listApiKeys(): Promise<{
+    keys: ApiKeyListResponse;
+}>;
+
 declare function listOrganizationInvites(orgId: string): Promise<OrganizationInvite[]>;
 
 declare function listOrganizationMembers(orgId: string): Promise<OrganizationMember[]>;
@@ -684,6 +826,16 @@ export declare type OpenSecretContextType = {
      * A UUID that identifies which project/tenant this instance belongs to.
      */
     clientId: string;
+    /**
+     * Optional API key for OpenAI endpoints.
+     * When set, this will be used instead of JWT for /v1/* endpoints.
+     */
+    apiKey?: string;
+    /**
+     * Sets the API key to use for OpenAI endpoints.
+     * @param key - The API key (UUID format) or undefined to clear
+     */
+    setApiKey: (key: string | undefined) => void;
     /**
      * Authenticates a user with email and password.
      *
@@ -1118,7 +1270,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 +1279,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 +1290,102 @@ 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);
+     * }
      * ```
      */
-    uploadDocument: (file: File | Blob) => Promise<DocumentResponse>;
+    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>;
+    /**
+     * Creates a new API key for the authenticated user
+     * @param name - A descriptive name for the API key
+     * @returns A promise resolving to the API key details with the key value (only shown once)
+     * @throws {Error} If the user is not authenticated or the request fails
+     *
+     * IMPORTANT: The `key` field is only returned once during creation and cannot be retrieved again.
+     * The SDK consumer should prompt users to save the key immediately.
+     */
+    createApiKey: typeof api.createApiKey;
+    /**
+     * Lists all API keys for the authenticated user
+     * @returns A promise resolving to an object containing an array of API key metadata (without the actual keys)
+     * @throws {Error} If the user is not authenticated or the request fails
+     *
+     * Returns metadata about all API keys associated with the user's account.
+     * Note that the actual key values are never returned - they are only shown once during creation.
+     * The keys are sorted by created_at in descending order (newest first).
+     */
+    listApiKeys: typeof api.listApiKeys;
+    /**
+     * Deletes an API key by its name
+     * @param name - The name of the API key to delete
+     * @returns A promise that resolves when the key is deleted
+     * @throws {Error} If the user is not authenticated or the API key is not found
+     *
+     * Permanently deletes an API key. This action cannot be undone.
+     * Any requests using the deleted key will immediately fail with 401 Unauthorized.
+     * Names are unique per user, so this uniquely identifies the key to delete.
+     */
+    deleteApiKey: typeof api.deleteApiKey;
 };
 
 /**
@@ -1901,7 +2145,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 +2155,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 +2166,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;