@uploadista/react 0.0.3 → 0.0.6

package/dist/use-uploadista-client-CeFo4wuV.d.ts

@@ -0,0 +1,772 @@
+import { BrowserUploadInput, ChunkMetrics, FlowUploadOptions, PerformanceInsights, UploadSessionMetrics, UploadistaClientOptions, createUploadistaClient } from "@uploadista/client-browser";
+import { UploadFile } from "@uploadista/core/types";
+
+//#region src/hooks/use-drag-drop.d.ts
+interface DragDropOptions {
+  /**
+   * Accept specific file types (MIME types or file extensions)
+   */
+  accept?: string[];
+  /**
+   * Maximum number of files allowed
+   */
+  maxFiles?: number;
+  /**
+   * Maximum file size in bytes
+   */
+  maxFileSize?: number;
+  /**
+   * Whether to allow multiple files
+   */
+  multiple?: boolean;
+  /**
+   * Custom validation function for files
+   */
+  validator?: (files: File[]) => string[] | null;
+  /**
+   * Called when files are dropped or selected
+   */
+  onFilesReceived?: (files: File[]) => void;
+  /**
+   * Called when validation fails
+   */
+  onValidationError?: (errors: string[]) => void;
+  /**
+   * Called when drag state changes
+   */
+  onDragStateChange?: (isDragging: boolean) => void;
+}
+interface DragDropState {
+  /**
+   * Whether files are currently being dragged over the drop zone
+   */
+  isDragging: boolean;
+  /**
+   * Whether the drag is currently over the drop zone
+   */
+  isOver: boolean;
+  /**
+   * Whether the dragged items are valid files
+   */
+  isValid: boolean;
+  /**
+   * Current validation errors
+   */
+  errors: string[];
+}
+interface UseDragDropReturn {
+  /**
+   * Current drag and drop state
+   */
+  state: DragDropState;
+  /**
+   * Event handlers for the drop zone element
+   */
+  dragHandlers: {
+    onDragEnter: (event: React.DragEvent) => void;
+    onDragOver: (event: React.DragEvent) => void;
+    onDragLeave: (event: React.DragEvent) => void;
+    onDrop: (event: React.DragEvent) => void;
+  };
+  /**
+   * Props for a file input element
+   */
+  inputProps: {
+    type: "file";
+    multiple: boolean;
+    accept?: string;
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    style: {
+      display: "none";
+    };
+  };
+  /**
+   * Open file picker dialog
+   */
+  openFilePicker: () => void;
+  /**
+   * Manually process files (useful for programmatic file handling)
+   */
+  processFiles: (files: File[]) => void;
+  /**
+   * Reset drag state
+   */
+  reset: () => void;
+}
+/**
+ * React hook for handling drag and drop file uploads with validation.
+ * Provides drag state management, file validation, and file picker integration.
+ *
+ * @param options - Configuration and event handlers
+ * @returns Drag and drop state and handlers
+ *
+ * @example
+ * ```tsx
+ * const dragDrop = useDragDrop({
+ *   accept: ['image/*', '.pdf'],
+ *   maxFiles: 5,
+ *   maxFileSize: 10 * 1024 * 1024, // 10MB
+ *   multiple: true,
+ *   onFilesReceived: (files) => {
+ *     console.log('Received files:', files);
+ *     // Process files with upload hooks
+ *   },
+ *   onValidationError: (errors) => {
+ *     console.error('Validation errors:', errors);
+ *   },
+ * });
+ *
+ * return (
+ *   <div>
+ *     <div
+ *       {...dragDrop.dragHandlers}
+ *       style={{
+ *         border: dragDrop.state.isDragging ? '2px dashed #007bff' : '2px dashed #ccc',
+ *         backgroundColor: dragDrop.state.isOver ? '#f8f9fa' : 'transparent',
+ *         padding: '2rem',
+ *         textAlign: 'center',
+ *         cursor: 'pointer',
+ *       }}
+ *       onClick={dragDrop.openFilePicker}
+ *     >
+ *       {dragDrop.state.isDragging ? (
+ *         <p>Drop files here...</p>
+ *       ) : (
+ *         <p>Drag files here or click to select</p>
+ *       )}
+ *
+ *       {dragDrop.state.errors.length > 0 && (
+ *         <div style={{ color: 'red', marginTop: '1rem' }}>
+ *           {dragDrop.state.errors.map((error, index) => (
+ *             <p key={index}>{error}</p>
+ *           ))}
+ *         </div>
+ *       )}
+ *     </div>
+ *
+ *     <input {...dragDrop.inputProps} />
+ *   </div>
+ * );
+ * ```
+ */
+declare function useDragDrop(options?: DragDropOptions): UseDragDropReturn;
+//#endregion
+//#region src/hooks/use-flow-upload.d.ts
+/**
+ * Possible states for a flow upload lifecycle.
+ * Flow uploads progress through: idle → uploading → processing → success/error/aborted
+ */
+type FlowUploadStatus = "idle" | "uploading" | "processing" | "success" | "error" | "aborted";
+/**
+ * Complete state information for a flow upload operation.
+ * Tracks both the upload phase (file transfer) and processing phase (flow execution).
+ *
+ * @template TOutput - Type of the final output from the flow (defaults to UploadFile)
+ *
+ * @property status - Current upload status (idle, uploading, processing, success, error, aborted)
+ * @property progress - Upload progress percentage (0-100)
+ * @property bytesUploaded - Number of bytes successfully uploaded
+ * @property totalBytes - Total file size in bytes (null if unknown)
+ * @property error - Error object if upload or processing failed
+ * @property result - Final output from the flow (available when status is "success")
+ * @property jobId - Unique identifier for the flow execution job
+ * @property flowStarted - Whether the flow processing has started
+ * @property currentNodeName - Name of the currently executing flow node
+ * @property currentNodeType - Type of the currently executing flow node
+ * @property flowOutputs - Complete outputs from all output nodes in the flow
+ */
+interface FlowUploadState<TOutput = UploadFile> {
+  status: FlowUploadStatus;
+  progress: number;
+  bytesUploaded: number;
+  totalBytes: number | null;
+  error: Error | null;
+  result: TOutput | null;
+  jobId: string | null;
+  flowStarted: boolean;
+  currentNodeName: string | null;
+  currentNodeType: string | null;
+  flowOutputs: Record<string, unknown> | null;
+}
+/**
+ * Return value from the useFlowUpload hook with upload control methods and state.
+ *
+ * @template TOutput - Type of the final output from the flow (defaults to UploadFile)
+ *
+ * @property state - Complete flow upload state with progress and outputs
+ * @property upload - Function to initiate file upload through the flow
+ * @property abort - Cancel the current upload and flow execution
+ * @property reset - Reset state to idle (clears all data)
+ * @property isUploading - True when upload or processing is active
+ * @property isUploadingFile - True only during file upload phase
+ * @property isProcessing - True only during flow processing phase
+ */
+interface UseFlowUploadReturn<TOutput = UploadFile> {
+  /**
+   * Current upload state
+   */
+  state: FlowUploadState<TOutput>;
+  /**
+   * Upload a file through the flow
+   */
+  upload: (file: File | Blob) => Promise<void>;
+  /**
+   * Abort the current upload
+   */
+  abort: () => void;
+  /**
+   * Reset the upload state
+   */
+  reset: () => void;
+  /**
+   * Whether an upload or flow execution is in progress (uploading OR processing)
+   */
+  isUploading: boolean;
+  /**
+   * Whether the file is currently being uploaded (chunks being sent)
+   */
+  isUploadingFile: boolean;
+  /**
+   * Whether the flow is currently processing (after upload completes)
+   */
+  isProcessing: boolean;
+}
+/**
+ * React hook for uploading files through a flow with automatic flow execution.
+ * Handles both the file upload phase and the flow processing phase, providing
+ * real-time progress updates and flow node execution tracking.
+ *
+ * The flow engine processes the uploaded file through a DAG of nodes, which can
+ * perform operations like image optimization, storage saving, webhooks, etc.
+ *
+ * Must be used within an UploadistaProvider. Flow events (node start/end, flow complete)
+ * are automatically subscribed through the provider context.
+ *
+ * @template TOutput - Type of the final result from the flow (defaults to UploadFile)
+ * @param options - Flow upload configuration including flow ID and event handlers
+ * @returns Flow upload state and control methods
+ *
+ * @example
+ * ```tsx
+ * // Basic flow upload with progress tracking
+ * function ImageUploader() {
+ *   const flowUpload = useFlowUpload({
+ *     flowConfig: {
+ *       flowId: "image-optimization-flow",
+ *       storageId: "s3-images",
+ *       outputNodeId: "optimized-output", // Optional: specify which output to use
+ *     },
+ *     onSuccess: (result) => {
+ *       console.log("Image optimized and saved:", result);
+ *     },
+ *     onFlowComplete: (outputs) => {
+ *       console.log("All flow outputs:", outputs);
+ *       // outputs might include: { thumbnail: {...}, optimized: {...}, original: {...} }
+ *     },
+ *     onError: (error) => {
+ *       console.error("Upload or processing failed:", error);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="file"
+ *         accept="image/*"
+ *         onChange={(e) => {
+ *           const file = e.target.files?.[0];
+ *           if (file) flowUpload.upload(file);
+ *         }}
+ *       />
+ *
+ *       {flowUpload.isUploadingFile && (
+ *         <div>Uploading... {flowUpload.state.progress}%</div>
+ *       )}
+ *
+ *       {flowUpload.isProcessing && (
+ *         <div>
+ *           Processing...
+ *           {flowUpload.state.currentNodeName && (
+ *             <span>Current step: {flowUpload.state.currentNodeName}</span>
+ *           )}
+ *         </div>
+ *       )}
+ *
+ *       {flowUpload.state.status === "success" && (
+ *         <div>
+ *           <p>Upload complete!</p>
+ *           {flowUpload.state.result && (
+ *             <img src={flowUpload.state.result.url} alt="Uploaded" />
+ *           )}
+ *         </div>
+ *       )}
+ *
+ *       {flowUpload.state.status === "error" && (
+ *         <div>
+ *           <p>Error: {flowUpload.state.error?.message}</p>
+ *           <button onClick={flowUpload.reset}>Try Again</button>
+ *         </div>
+ *       )}
+ *
+ *       {flowUpload.isUploading && (
+ *         <button onClick={flowUpload.abort}>Cancel</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useMultiFlowUpload} for uploading multiple files through a flow
+ * @see {@link useUpload} for simple uploads without flow processing
+ */
+declare function useFlowUpload<TOutput = UploadFile>(options: FlowUploadOptions<TOutput>): UseFlowUploadReturn<TOutput>;
+//#endregion
+//#region src/hooks/use-upload.d.ts
+type UploadStatus = "idle" | "uploading" | "success" | "error" | "aborted";
+interface UploadState {
+  status: UploadStatus;
+  progress: number;
+  bytesUploaded: number;
+  totalBytes: number | null;
+  error: Error | null;
+  result: UploadFile | null;
+}
+interface UseUploadOptions {
+  /**
+   * Upload metadata to attach to the file
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Whether to defer the upload size calculation
+   */
+  uploadLengthDeferred?: boolean;
+  /**
+   * Manual upload size override
+   */
+  uploadSize?: number;
+  /**
+   * Called when upload progress updates
+   */
+  onProgress?: (progress: number, bytesUploaded: number, totalBytes: number | null) => void;
+  /**
+   * Called when a chunk completes
+   */
+  onChunkComplete?: (chunkSize: number, bytesAccepted: number, bytesTotal: number | null) => void;
+  /**
+   * Called when upload succeeds
+   */
+  onSuccess?: (result: UploadFile) => void;
+  /**
+   * Called when upload fails
+   */
+  onError?: (error: Error) => void;
+  /**
+   * Called when upload is aborted
+   */
+  onAbort?: () => void;
+  /**
+   * Custom retry logic
+   */
+  onShouldRetry?: (error: Error, retryAttempt: number) => boolean;
+}
+interface UploadMetrics {
+  /**
+   * Get performance insights from the upload client
+   */
+  getInsights: () => PerformanceInsights;
+  /**
+   * Export detailed metrics from the upload client
+   */
+  exportMetrics: () => {
+    session: Partial<UploadSessionMetrics>;
+    chunks: ChunkMetrics[];
+    insights: PerformanceInsights;
+  };
+  /**
+   * Get current network metrics
+   */
+  getNetworkMetrics: () => unknown;
+  /**
+   * Get current network condition
+   */
+  getNetworkCondition: () => unknown;
+  /**
+   * Reset all metrics
+   */
+  resetMetrics: () => void;
+}
+interface UseUploadReturn {
+  /**
+   * Current upload state
+   */
+  state: UploadState;
+  /**
+   * Start uploading a file
+   */
+  upload: (file: BrowserUploadInput) => void;
+  /**
+   * Abort the current upload
+   */
+  abort: () => void;
+  /**
+   * Reset the upload state to idle
+   */
+  reset: () => void;
+  /**
+   * Retry the last failed upload
+   */
+  retry: () => void;
+  /**
+   * Whether an upload is currently active
+   */
+  isUploading: boolean;
+  /**
+   * Whether the upload can be retried
+   */
+  canRetry: boolean;
+  /**
+   * Upload metrics and performance insights from the client
+   */
+  metrics: UploadMetrics;
+}
+/**
+ * React hook for managing individual file uploads with full state management.
+ * Provides upload progress tracking, error handling, abort functionality, and retry logic.
+ *
+ * Must be used within an UploadistaProvider.
+ *
+ * @param options - Upload configuration and event handlers
+ * @returns Upload state and control methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const upload = useUpload({
+ *     onSuccess: (result) => console.log('Upload complete:', result),
+ *     onError: (error) => console.error('Upload failed:', error),
+ *     onProgress: (progress) => console.log('Progress:', progress + '%'),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="file"
+ *         onChange={(e) => {
+ *           const file = e.target.files?.[0];
+ *           if (file) upload.upload(file);
+ *         }}
+ *       />
+ *       {upload.isUploading && <div>Progress: {upload.state.progress}%</div>}
+ *       {upload.state.error && <div>Error: {upload.state.error.message}</div>}
+ *       {upload.canRetry && <button onClick={upload.retry}>Retry</button>}
+ *       <button onClick={upload.abort} disabled={!upload.isUploading}>Abort</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useUpload(options?: UseUploadOptions): UseUploadReturn;
+//#endregion
+//#region src/hooks/use-multi-upload.d.ts
+interface UploadItem {
+  id: string;
+  file: BrowserUploadInput;
+  state: UploadState;
+}
+interface MultiUploadOptions extends Omit<UseUploadOptions, "onSuccess" | "onError" | "onProgress"> {
+  /**
+   * Maximum number of concurrent uploads
+   */
+  maxConcurrent?: number;
+  /**
+   * Called when an individual file upload starts
+   */
+  onUploadStart?: (item: UploadItem) => void;
+  /**
+   * Called when an individual file upload progresses
+   */
+  onUploadProgress?: (item: UploadItem, progress: number, bytesUploaded: number, totalBytes: number | null) => void;
+  /**
+   * Called when an individual file upload succeeds
+   */
+  onUploadSuccess?: (item: UploadItem, result: UploadFile) => void;
+  /**
+   * Called when an individual file upload fails
+   */
+  onUploadError?: (item: UploadItem, error: Error) => void;
+  /**
+   * Called when all uploads complete (successfully or with errors)
+   */
+  onComplete?: (results: {
+    successful: UploadItem[];
+    failed: UploadItem[];
+    total: number;
+  }) => void;
+}
+interface MultiUploadState {
+  /**
+   * Total number of uploads
+   */
+  total: number;
+  /**
+   * Number of completed uploads (successful + failed)
+   */
+  completed: number;
+  /**
+   * Number of successful uploads
+   */
+  successful: number;
+  /**
+   * Number of failed uploads
+   */
+  failed: number;
+  /**
+   * Number of currently uploading files
+   */
+  uploading: number;
+  /**
+   * Overall progress as a percentage (0-100)
+   */
+  progress: number;
+  /**
+   * Total bytes uploaded across all files
+   */
+  totalBytesUploaded: number;
+  /**
+   * Total bytes to upload across all files
+   */
+  totalBytes: number;
+  /**
+   * Whether any uploads are currently active
+   */
+  isUploading: boolean;
+  /**
+   * Whether all uploads have completed
+   */
+  isComplete: boolean;
+}
+interface UseMultiUploadReturn {
+  /**
+   * Current multi-upload state
+   */
+  state: MultiUploadState;
+  /**
+   * Array of all upload items
+   */
+  items: UploadItem[];
+  /**
+   * Add files to the upload queue
+   */
+  addFiles: (files: BrowserUploadInput[]) => void;
+  /**
+   * Remove an item from the queue (only if not currently uploading)
+   */
+  removeItem: (id: string) => void;
+  /**
+   * Remove a file from the queue (alias for removeItem)
+   */
+  removeFile: (id: string) => void;
+  /**
+   * Start all pending uploads
+   */
+  startAll: () => void;
+  /**
+   * Abort a specific upload by ID
+   */
+  abortUpload: (id: string) => void;
+  /**
+   * Abort all active uploads
+   */
+  abortAll: () => void;
+  /**
+   * Retry a specific failed upload by ID
+   */
+  retryUpload: (id: string) => void;
+  /**
+   * Retry all failed uploads
+   */
+  retryFailed: () => void;
+  /**
+   * Clear all completed uploads (successful and failed)
+   */
+  clearCompleted: () => void;
+  /**
+   * Clear all items
+   */
+  clearAll: () => void;
+  /**
+   * Get items by status
+   */
+  getItemsByStatus: (status: UploadStatus) => UploadItem[];
+  /**
+   * Aggregated upload metrics and performance insights from the client
+   */
+  metrics: UploadMetrics;
+}
+/**
+ * React hook for managing multiple file uploads with queue management,
+ * concurrent upload limits, and batch operations.
+ *
+ * Must be used within an UploadistaProvider.
+ *
+ * @param options - Multi-upload configuration and event handlers
+ * @returns Multi-upload state and control methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const multiUpload = useMultiUpload({
+ *     maxConcurrent: 3,
+ *     onUploadSuccess: (item, result) => {
+ *       console.log(`${item.file.name} uploaded successfully`);
+ *     },
+ *     onComplete: (results) => {
+ *       console.log(`Upload batch complete: ${results.successful.length}/${results.total} successful`);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="file"
+ *         multiple
+ *         onChange={(e) => {
+ *           if (e.target.files) {
+ *             multiUpload.addFiles(Array.from(e.target.files));
+ *           }
+ *         }}
+ *       />
+ *
+ *       <div>Progress: {multiUpload.state.progress}%</div>
+ *       <div>
+ *         {multiUpload.state.uploading} uploading, {multiUpload.state.successful} successful,
+ *         {multiUpload.state.failed} failed
+ *       </div>
+ *
+ *       <button onClick={multiUpload.startAll} disabled={multiUpload.state.isUploading}>
+ *         Start All
+ *       </button>
+ *       <button onClick={multiUpload.abortAll} disabled={!multiUpload.state.isUploading}>
+ *         Abort All
+ *       </button>
+ *       <button onClick={multiUpload.retryFailed} disabled={multiUpload.state.failed === 0}>
+ *         Retry Failed
+ *       </button>
+ *
+ *       {multiUpload.items.map((item) => (
+ *         <div key={item.id}>
+ *           {item.file.name}: {item.state.status} ({item.state.progress}%)
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useMultiUpload(options?: MultiUploadOptions): UseMultiUploadReturn;
+//#endregion
+//#region src/hooks/use-uploadista-client.d.ts
+/**
+ * Configuration options for the uploadista client hook.
+ * Extends the base client options with React-specific behavior.
+ *
+ * @property onEvent - Global event handler for all upload and flow events
+ * @property baseUrl - API base URL for uploads
+ * @property storageId - Default storage identifier
+ * @property chunkSize - Size of upload chunks in bytes
+ * @property storeFingerprintForResuming - Enable resumable uploads
+ * @property retryDelays - Array of retry delays in milliseconds
+ * @property parallelUploads - Maximum number of parallel uploads
+ * @property uploadStrategy - Upload strategy (sequential, parallel, adaptive)
+ * @property smartChunking - Enable dynamic chunk size adjustment
+ * @property networkMonitoring - Enable network condition monitoring
+ */
+interface UseUploadistaClientOptions extends UploadistaClientOptions {
+  /**
+   * Global event handler for all upload and flow events from this client
+   */
+  onEvent?: UploadistaClientOptions["onEvent"];
+}
+/**
+ * Return value from the useUploadistaClient hook.
+ *
+ * @property client - Configured uploadista client instance (stable across re-renders)
+ * @property config - Current client configuration options
+ */
+interface UseUploadistaClientReturn {
+  /**
+   * The uploadista client instance
+   */
+  client: ReturnType<typeof createUploadistaClient>;
+  /**
+   * Current configuration of the client
+   */
+  config: UseUploadistaClientOptions;
+}
+/**
+ * React hook for creating and managing an uploadista client instance.
+ * The client instance is memoized and stable across re-renders, only being
+ * recreated when configuration options change.
+ *
+ * This hook is typically used internally by UploadistaProvider, but can be
+ * used directly for advanced use cases requiring multiple client instances.
+ *
+ * @param options - Upload client configuration options
+ * @returns Object containing the stable client instance and current configuration
+ *
+ * @example
+ * ```tsx
+ * // Basic client setup
+ * function MyUploadComponent() {
+ *   const { client, config } = useUploadistaClient({
+ *     baseUrl: 'https://api.example.com',
+ *     storageId: 'default-storage',
+ *     chunkSize: 1024 * 1024, // 1MB chunks
+ *     storeFingerprintForResuming: true,
+ *     onEvent: (event) => {
+ *       console.log('Upload event:', event);
+ *     }
+ *   });
+ *
+ *   // Use client directly
+ *   const handleUpload = async (file: File) => {
+ *     await client.upload(file, {
+ *       onSuccess: (result) => console.log('Uploaded:', result),
+ *       onError: (error) => console.error('Failed:', error),
+ *     });
+ *   };
+ *
+ *   return <FileUploader onUpload={handleUpload} />;
+ * }
+ *
+ * // Advanced: Multiple clients with different configurations
+ * function MultiClientComponent() {
+ *   // Client for image uploads
+ *   const imageClient = useUploadistaClient({
+ *     baseUrl: 'https://images.example.com',
+ *     storageId: 'images',
+ *     chunkSize: 2 * 1024 * 1024, // 2MB for images
+ *   });
+ *
+ *   // Client for document uploads
+ *   const docClient = useUploadistaClient({
+ *     baseUrl: 'https://docs.example.com',
+ *     storageId: 'documents',
+ *     chunkSize: 512 * 1024, // 512KB for documents
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <ImageUploader client={imageClient.client} />
+ *       <DocumentUploader client={docClient.client} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link UploadistaProvider} for the recommended way to provide client context
+ */
+declare function useUploadistaClient(options: UseUploadistaClientOptions): UseUploadistaClientReturn;
+//#endregion
+export { useFlowUpload as _, MultiUploadState as a, UseDragDropReturn as b, useMultiUpload as c, UseUploadOptions as d, UseUploadReturn as f, UseFlowUploadReturn as g, FlowUploadStatus as h, MultiUploadOptions as i, UploadState as l, FlowUploadState as m, UseUploadistaClientReturn as n, UploadItem as o, useUpload as p, useUploadistaClient as r, UseMultiUploadReturn as s, UseUploadistaClientOptions as t, UploadStatus as u, DragDropOptions as v, useDragDrop as x, DragDropState as y };
+//# sourceMappingURL=use-uploadista-client-CeFo4wuV.d.ts.map