@uploadista/client-core 0.0.13 → 0.0.15-beta.1

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { UploadStrategyNegotiator } from "@uploadista/core/upload";
 import { DataStoreCapabilities, InputFile, UploadEvent, UploadFile } from "@uploadista/core/types";
 import z from "zod";
+import { FlowData, FlowEvent, FlowJob, TypedOutput } from "@uploadista/core/flow";
 import * as _uploadista_core0 from "@uploadista/core";
 import { UploadFile as UploadFile$1 } from "@uploadista/core";
-import { FlowData, FlowEvent, FlowJob } from "@uploadista/core/flow";
 
 //#region src/types/buffered-chunk.d.ts
 interface BufferedChunk {
@@ -1076,11 +1076,11 @@ interface FileSource {
   slice: (start: number, end: number) => Promise<SliceResult>;
   close: () => void;
 }
-interface FileReaderService<UploadInput> {
+interface FileReaderService<UploadInput$1> {
   /**
    * Open a file for reading
    */
-  openFile(input: UploadInput, chunkSize: number): Promise<FileSource>;
+  openFile(input: UploadInput$1, chunkSize: number): Promise<FileSource>;
 }
 interface Base64Service {
   /**
@@ -1094,8 +1094,8 @@ interface Base64Service {
 }
 //#endregion
 //#region src/services/fingerprint-service.d.ts
-interface FingerprintService<UploadInput> {
-  computeFingerprint(file: UploadInput, endpoint: string): Promise<string | null>;
+interface FingerprintService<UploadInput$1> {
+  computeFingerprint(file: UploadInput$1, endpoint: string): Promise<string | null>;
 }
 //#endregion
 //#region src/services/id-generation-service.d.ts
@@ -1836,19 +1836,221 @@ declare class UploadistaError extends Error {
 //#endregion
 //#region src/services/service-container.d.ts
 /**
- * Service container for dependency injection
+ * Service container for dependency injection in the Uploadista client.
+ *
+ * This container provides all platform-specific services needed by the upload client.
+ * Different platforms (browser, React Native, Node.js) provide their own implementations
+ * of these services to handle platform-specific APIs and behaviors.
+ *
+ * @template UploadInput - The type of input accepted by the file reader (e.g., File, Blob, string path)
+ *
+ * @example Browser implementation
+ * ```typescript
+ * const services: ServiceContainer<File | Blob> = {
+ *   storage: new LocalStorageService(),
+ *   idGeneration: new BrowserIdGenerationService(),
+ *   httpClient: new FetchHttpClient(),
+ *   fileReader: new BrowserFileReaderService(),
+ *   base64: new BrowserBase64Service(),
+ *   websocket: new BrowserWebSocketFactory(),
+ *   abortController: new BrowserAbortControllerFactory(),
+ *   platform: new BrowserPlatformService(),
+ *   checksumService: new WebCryptoChecksumService(),
+ *   fingerprintService: new BrowserFingerprintService(),
+ * };
+ * ```
+ *
+ * @example React Native implementation
+ * ```typescript
+ * const services: ServiceContainer<FilePickResult> = {
+ *   storage: new AsyncStorageService(),
+ *   idGeneration: new ReactNativeIdGenerationService(),
+ *   httpClient: new FetchHttpClient(),
+ *   fileReader: new ReactNativeFileReaderService(),
+ *   websocket: new ReactNativeWebSocketFactory(),
+ *   abortController: new ReactNativeAbortControllerFactory(),
+ *   platform: new ReactNativePlatformService(),
+ *   checksumService: new ReactNativeChecksumService(),
+ *   fingerprintService: new ReactNativeFingerprintService(),
+ * };
+ * ```
  */
-interface ServiceContainer<UploadInput> {
+interface ServiceContainer<UploadInput$1> {
+  /**
+   * Storage service for persisting upload state and metadata.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Storing upload progress for resumption
+   * - Caching upload fingerprints
+   * - Persisting partial upload state across sessions
+   *
+   * **Platform implementations**:
+   * - Browser: `localStorage`, `IndexedDB`
+   * - React Native: `AsyncStorage`, `MMKV`
+   * - Node.js: File system, Redis
+   */
   storage: StorageService;
+  /**
+   * ID generation service for creating unique identifiers.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Generating upload IDs
+   * - Creating request correlation IDs
+   * - Generating chunk identifiers
+   *
+   * **Platform implementations**:
+   * - Browser: `crypto.randomUUID()` or fallback
+   * - React Native: UUID libraries
+   * - Node.js: `crypto.randomUUID()`
+   */
   idGeneration: IdGenerationService;
+  /**
+   * HTTP client for making upload requests.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Uploading file chunks
+   * - Making API calls to the upload server
+   * - Fetching upload metadata
+   *
+   * **Platform implementations**:
+   * - Browser: `fetch()` with connection pooling
+   * - React Native: `fetch()` or `XMLHttpRequest`
+   * - Node.js: `node:http`, `node:https`, or libraries like `undici`
+   *
+   * **Important**: Should support connection pooling for optimal performance
+   */
   httpClient: HttpClient;
-  fileReader: FileReaderService<UploadInput>;
+  /**
+   * File reader service for reading file contents.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Reading file data for upload
+   * - Slicing files into chunks
+   * - Computing file checksums and fingerprints
+   *
+   * **Platform implementations**:
+   * - Browser: `FileReader` API, `Blob.slice()`
+   * - React Native: Native file system modules, `react-native-fs`
+   * - Node.js: `fs.createReadStream()`, `fs.promises.open()`
+   *
+   * **Generic type**: Accepts platform-specific input types (File, Blob, path string)
+   */
+  fileReader: FileReaderService<UploadInput$1>;
+  /**
+   * Base64 encoding/decoding service.
+   *
+   * **Required**: No (optional)
+   *
+   * **Used for**:
+   * - Encoding binary data for transport
+   * - Decoding server responses
+   * - Optional data transformations
+   *
+   * **Platform implementations**:
+   * - Browser: `btoa()`, `atob()`
+   * - React Native: `base64-js` or built-in
+   * - Node.js: `Buffer.from().toString('base64')`
+   *
+   * **Note**: Only needed for specific upload protocols that require base64 encoding
+   */
   base64?: Base64Service;
+  /**
+   * WebSocket factory for creating WebSocket connections.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Real-time upload progress updates
+   * - Server-side event notifications
+   * - Live upload status from server
+   *
+   * **Platform implementations**:
+   * - Browser: Native `WebSocket` API
+   * - React Native: `react-native-websocket` or polyfills
+   * - Node.js: `ws` library
+   *
+   * **Important**: Must support standard WebSocket protocol
+   */
   websocket: WebSocketFactory;
+  /**
+   * Abort controller factory for creating cancellation tokens.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Aborting in-flight upload requests
+   * - Cancelling file read operations
+   * - Implementing upload timeout logic
+   *
+   * **Platform implementations**:
+   * - Browser: Native `AbortController` API
+   * - React Native: `AbortController` polyfill
+   * - Node.js: Native `AbortController` (Node 15+)
+   */
   abortController: AbortControllerFactory;
+  /**
+   * Platform detection service.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Detecting runtime environment (browser, React Native, Node.js)
+   * - Applying platform-specific optimizations
+   * - Conditional feature availability
+   *
+   * **Platform implementations**:
+   * - Browser: Checks `window`, `document` availability
+   * - React Native: Checks `navigator.product === 'ReactNative'`
+   * - Node.js: Checks `process` availability
+   */
   platform: PlatformService;
+  /**
+   * Checksum service for computing file checksums.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Verifying upload integrity
+   * - Detecting corrupted uploads
+   * - Implementing upload deduplication
+   *
+   * **Platform implementations**:
+   * - Browser: `crypto.subtle` Web Crypto API
+   * - React Native: Native crypto modules or JavaScript implementations
+   * - Node.js: `crypto` module
+   *
+   * **Common algorithms**: SHA-256, MD5, CRC32
+   */
   checksumService: ChecksumService;
-  fingerprintService: FingerprintService<UploadInput>;
+  /**
+   * Fingerprint service for generating unique file identifiers.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Upload resumption (matching partial uploads)
+   * - Deduplication (detecting duplicate files)
+   * - Cache key generation
+   *
+   * **Platform implementations**:
+   * - Browser: Combines file metadata (size, name, modified date, first/last bytes)
+   * - React Native: Similar to browser but uses platform-specific file APIs
+   * - Node.js: File stat info + content sampling
+   *
+   * **Generic type**: Accepts platform-specific input types
+   *
+   * **Note**: Fingerprints should be stable (same file = same fingerprint) but
+   * fast to compute (avoid reading entire file if possible)
+   */
+  fingerprintService: FingerprintService<UploadInput$1>;
 }
 //#endregion
 //#region src/types/upload-response.d.ts
@@ -2123,7 +2325,7 @@ type UploadistaUploadOptions = {
  *
  * @template UploadInput - The platform-specific file/blob type (e.g., File, Blob, Buffer)
  */
-type UploadistaClientOptions<UploadInput> = {
+type UploadistaClientOptions<UploadInput$1> = {
   /** Base URL of the Uploadista server (e.g., "https://upload.example.com") */
   baseUrl: string;
   /** Base path for Uploadista endpoints. Defaults to "uploadista" */
@@ -2155,11 +2357,11 @@ type UploadistaClientOptions<UploadInput> = {
   /** Client-side storage for upload resumption data */
   clientStorage: ClientStorage;
   /** Platform-specific file reading service */
-  fileReader: FileReaderService<UploadInput>;
+  fileReader: FileReaderService<UploadInput$1>;
   /** Logger for debugging and monitoring */
   logger: Logger;
   /** Service for computing file fingerprints for resumption */
-  fingerprintService: FingerprintService<UploadInput>;
+  fingerprintService: FingerprintService<UploadInput$1>;
   /** Whether to store fingerprints for upload resumption. Defaults to true */
   storeFingerprintForResuming: boolean;
   /** Factory for creating WebSocket connections */
@@ -2325,7 +2527,7 @@ declare const defaultConnectionPoolingConfig: ConnectionPoolConfig;
  * @see {@link UploadistaClientOptions} for full configuration options
  * @see {@link UploadistaUploadOptions} for per-upload options
  */
-declare function createUploadistaClient<UploadInput>({
+declare function createUploadistaClient<UploadInput$1>({
   baseUrl: _baseUrl,
   uploadistaBasePath,
   storageId,
@@ -2350,8 +2552,8 @@ declare function createUploadistaClient<UploadInput>({
   abortControllerFactory,
   platformService,
   auth
-}: UploadistaClientOptions<UploadInput>): {
-  upload: (file: UploadInput, {
+}: UploadistaClientOptions<UploadInput$1>): {
+  upload: (file: UploadInput$1, {
     uploadLengthDeferred,
     uploadSize,
     onProgress,
@@ -2362,7 +2564,7 @@ declare function createUploadistaClient<UploadInput>({
   }?: UploadistaUploadOptions) => Promise<{
     abort: () => void;
   }>;
-  uploadWithFlow: (file: UploadInput, flowConfig: FlowUploadConfig, {
+  uploadWithFlow: (file: UploadInput$1, flowConfig: FlowUploadConfig, {
     onProgress,
     onChunkComplete,
     onSuccess,
@@ -2436,12 +2638,12 @@ declare function createUploadistaClient<UploadInput>({
     connectionOverhead: number;
   }>;
   resetMetrics: () => Promise<void>;
-  validateConfiguration: (options: UploadistaClientOptions<UploadInput>) => {
+  validateConfiguration: (options: UploadistaClientOptions<UploadInput$1>) => {
     valid: boolean;
     errors: string[];
     warnings: string[];
   };
-  validateConfigurationAsync: (options: UploadistaClientOptions<UploadInput>) => Promise<{
+  validateConfigurationAsync: (options: UploadistaClientOptions<UploadInput$1>) => Promise<{
     valid: boolean;
     errors: string[];
     warnings: string[];
@@ -2502,9 +2704,9 @@ type FlowResult<TOutput = UploadFile> = {
 /**
  * Flow upload item for multi-flow-upload tracking
  */
-interface FlowUploadItem<UploadInput> {
+interface FlowUploadItem<UploadInput$1> {
   id: string;
-  file: UploadInput;
+  file: UploadInput$1;
   status: "pending" | "uploading" | "success" | "error" | "aborted";
   progress: number;
   bytesUploaded: number;
@@ -2520,20 +2722,43 @@ interface FlowUploadOptions<TOutput = UploadFile> {
    * Flow configuration
    */
   flowConfig: FlowUploadConfig;
+  /**
+   * Called when the flow job starts
+   * @param jobId - The unique identifier for the flow job
+   */
+  onJobStart?: (jobId: string) => void;
   /**
    * Called when upload progress updates
+   *
+   * @param uploadId - The unique identifier for this upload
+   * @param bytesUploaded - Number of bytes uploaded so far
+   * @param totalBytes - Total bytes to upload, null if unknown/deferred
    */
-  onProgress?: (progress: number, bytesUploaded: number, totalBytes: number | null) => void;
+  onProgress?: (uploadId: string, bytesUploaded: number, totalBytes: number | null) => void;
   /**
    * Called when a chunk completes
    */
   onChunkComplete?: (chunkSize: number, bytesAccepted: number, bytesTotal: number | null) => void;
   /**
    * Called when the flow completes successfully (receives full flow outputs)
-   * This is the recommended callback for multi-output flows
-   * Format: { [outputNodeId]: result, ... }
+   * This is the recommended callback for multi-output flows.
+   * Each output includes nodeId, optional nodeType, data, and timestamp.
+   *
+   * @param outputs - Array of typed outputs from all output nodes
+   *
+   * @example
+   * ```typescript
+   * onFlowComplete: (outputs) => {
+   *   // Access all outputs with type information
+   *   for (const output of outputs) {
+   *     if (output.nodeType === 'storage-output-v1') {
+   *       console.log('Storage output:', output.data);
+   *     }
+   *   }
+   * }
+   * ```
    */
-  onFlowComplete?: (outputs: Record<string, unknown>) => void;
+  onFlowComplete?: (outputs: TypedOutput[]) => void;
   /**
    * Called when upload succeeds (legacy, single-output flows)
    * For single-output flows, receives the value from the specified outputNodeId
@@ -2555,7 +2780,7 @@ interface FlowUploadOptions<TOutput = UploadFile> {
 }
 //#endregion
 //#region src/types/multi-flow-upload-options.d.ts
-interface MultiFlowUploadOptions<UploadInput> {
+interface MultiFlowUploadOptions<UploadInput$1> {
   /**
    * Flow configuration
    */
@@ -2567,19 +2792,19 @@ interface MultiFlowUploadOptions<UploadInput> {
   /**
    * Called when an individual upload progresses
    */
-  onItemProgress?: (item: FlowUploadItem<UploadInput>) => void;
+  onItemProgress?: (item: FlowUploadItem<UploadInput$1>) => void;
   /**
    * Called when an individual upload succeeds
    */
-  onItemSuccess?: (item: FlowUploadItem<UploadInput>) => void;
+  onItemSuccess?: (item: FlowUploadItem<UploadInput$1>) => void;
   /**
    * Called when an individual upload fails
    */
-  onItemError?: (item: FlowUploadItem<UploadInput>, error: Error) => void;
+  onItemError?: (item: FlowUploadItem<UploadInput$1>, error: Error) => void;
   /**
    * Called when all uploads complete
    */
-  onComplete?: (items: FlowUploadItem<UploadInput>[]) => void;
+  onComplete?: (items: FlowUploadItem<UploadInput$1>[]) => void;
   /**
    * Custom retry logic
    */
@@ -2587,8 +2812,8 @@ interface MultiFlowUploadOptions<UploadInput> {
 }
 //#endregion
 //#region src/types/multi-flow-upload-state.d.ts
-interface MultiFlowUploadState<UploadInput> {
-  items: FlowUploadItem<UploadInput>[];
+interface MultiFlowUploadState<UploadInput$1> {
+  items: FlowUploadItem<UploadInput$1>[];
   totalProgress: number;
   activeUploads: number;
   completedUploads: number;
@@ -2611,18 +2836,30 @@ interface UploadOptions {
   uploadSize?: number;
   /**
    * Called when upload progress updates
+   *
+   * @param uploadId - The unique identifier for this upload
+   * @param bytesUploaded - Number of bytes uploaded so far
+   * @param totalBytes - Total bytes to upload, null if unknown/deferred
    */
-  onProgress?: (progress: number, bytesUploaded: number, totalBytes: number | null) => void;
+  onProgress?: (uploadId: string, bytesUploaded: number, totalBytes: number | null) => void;
   /**
    * Called when a chunk completes
+   *
+   * @param chunkSize - Size of the completed chunk in bytes
+   * @param bytesAccepted - Total bytes accepted by server so far
+   * @param bytesTotal - Total bytes to upload, null if unknown/deferred
    */
   onChunkComplete?: (chunkSize: number, bytesAccepted: number, bytesTotal: number | null) => void;
   /**
    * Called when upload succeeds
+   *
+   * @param result - The uploaded file result
    */
   onSuccess?: (result: UploadFile$1) => void;
   /**
    * Called when upload fails
+   *
+   * @param error - The error that caused the failure
    */
   onError?: (error: Error) => void;
   /**
@@ -2631,10 +2868,137 @@ interface UploadOptions {
   onAbort?: () => void;
   /**
    * Custom retry logic
+   *
+   * @param error - The error that triggered the retry check
+   * @param retryAttempt - The current retry attempt number (0-indexed)
+   * @returns true to retry, false to fail
    */
   onShouldRetry?: (error: Error, retryAttempt: number) => boolean;
 }
 //#endregion
+//#region src/types/upload-metrics.d.ts
+/**
+ * Comprehensive upload metrics interface
+ *
+ * Provides access to all performance metrics, insights, and network
+ * statistics for upload monitoring and optimization.
+ *
+ * This interface is implemented by all framework packages (React, Vue, React Native)
+ * to ensure consistent metrics API across platforms.
+ *
+ * @example React usage
+ * ```tsx
+ * const upload = useUpload();
+ * const insights = upload.metrics.getInsights();
+ * const metrics = upload.metrics.exportMetrics();
+ * ```
+ *
+ * @example Vue usage
+ * ```vue
+ * <script setup>
+ * const upload = useUpload();
+ * const insights = upload.metrics.getInsights();
+ * </script>
+ * ```
+ *
+ * @example React Native usage
+ * ```tsx
+ * const upload = useUpload();
+ * const networkMetrics = upload.metrics.getNetworkMetrics();
+ * ```
+ */
+interface UploadMetrics {
+  /**
+   * Get performance insights from the upload client
+   *
+   * Provides high-level analysis with recommendations for
+   * optimizing upload performance.
+   *
+   * @returns Performance insights including efficiency scores and recommendations
+   *
+   * @example
+   * ```typescript
+   * const insights = metrics.getInsights();
+   * console.log(`Efficiency: ${insights.overallEfficiency}%`);
+   * console.log(`Recommendations:`, insights.recommendations);
+   * ```
+   */
+  getInsights: () => PerformanceInsights;
+  /**
+   * Export detailed metrics from the upload client
+   *
+   * Returns comprehensive metrics including session data,
+   * per-chunk statistics, and performance insights.
+   *
+   * Useful for analytics, debugging, and performance monitoring.
+   *
+   * @returns Object containing session metrics, chunk metrics, and insights
+   *
+   * @example
+   * ```typescript
+   * const metrics = metrics.exportMetrics();
+   * console.log(`Uploaded ${metrics.session.totalBytesUploaded} bytes`);
+   * console.log(`Average speed: ${metrics.session.averageSpeed} B/s`);
+   * console.log(`Chunks: ${metrics.chunks.length}`);
+   * ```
+   */
+  exportMetrics: () => {
+    /** Session-level aggregated metrics */
+    session: Partial<UploadSessionMetrics>;
+    /** Per-chunk detailed metrics */
+    chunks: ChunkMetrics[];
+    /** Performance insights and recommendations */
+    insights: PerformanceInsights;
+  };
+  /**
+   * Get current network metrics
+   *
+   * Provides real-time network statistics including speed,
+   * errors, and network condition assessment.
+   *
+   * @returns Current network performance metrics
+   *
+   * @example
+   * ```typescript
+   * const network = metrics.getNetworkMetrics();
+   * console.log(`Speed: ${network.currentSpeed} B/s`);
+   * console.log(`Quality: ${network.condition.quality}`);
+   * ```
+   */
+  getNetworkMetrics: () => NetworkMetrics;
+  /**
+   * Get current network condition
+   *
+   * Provides assessment of current network quality with
+   * recommendations for adaptive upload strategies.
+   *
+   * @returns Network condition assessment
+   *
+   * @example
+   * ```typescript
+   * const condition = metrics.getNetworkCondition();
+   * if (condition.quality === 'poor') {
+   *   console.log('Consider reducing chunk size');
+   * }
+   * ```
+   */
+  getNetworkCondition: () => NetworkCondition;
+  /**
+   * Reset all metrics
+   *
+   * Clears all accumulated metrics and resets counters.
+   * Useful when starting a new upload session.
+   *
+   * @example
+   * ```typescript
+   * // Reset metrics before starting new upload
+   * metrics.resetMetrics();
+   * upload(newFile);
+   * ```
+   */
+  resetMetrics: () => void;
+}
+//#endregion
 //#region src/types/upload-result.d.ts
 /**
  * Discriminated union representing the result of an upload operation.
@@ -2692,5 +3056,580 @@ type UploadResult<TOutput = UploadFile$1> = {
   type: "cancelled";
 };
 //#endregion
-export { AbortControllerFactory, AbortControllerLike, AbortSignalLike, Base64Service, ChecksumService, ChunkBuffer, ChunkBufferConfig, ChunkMetrics, ClientStorage, ConnectionHealth, ConnectionMetrics, ConnectionPoolConfig, DetailedConnectionMetrics, FileReaderService, FileSource, FingerprintService, FlowResponse, FlowResult, FlowUploadConfig, FlowUploadItem, FlowUploadOptions, HeadersLike, Http2Info, HttpClient, HttpRequestOptions, HttpResponse, IdGenerationService, LogFunction, Logger, MultiFlowUploadOptions, MultiFlowUploadState, NetworkCondition, NetworkMetrics, NetworkMonitor, NetworkMonitorConfig, PerformanceInsights, PlatformService, PreviousUpload, RequestBody, ServiceContainer, SliceResult, StorageService, Timeout, UploadOptions, UploadResponse, UploadResult, UploadSample, UploadSessionMetrics, UploadistaApi, UploadistaClient, UploadistaClientOptions, UploadistaDeleteUploadResponse, UploadistaError, UploadistaErrorName, UploadistaEvent, UploadistaUploadOptions, UploadistaUploadResponse, UploadistaWebSocketEventHandler, UploadistaWebSocketManager, UploadistaWebSocketMessage, WebSocketEventMap, WebSocketFactory, WebSocketLike, createClientStorage, createInMemoryStorageService, createLogger, createUploadistaApi, createUploadistaClient, defaultConnectionPoolingConfig, previousUploadSchema, wait };
+//#region src/managers/event-subscription-manager.d.ts
+/**
+ * Generic event type that the subscription manager can handle
+ */
+interface GenericEvent {
+  type: string;
+  data?: unknown;
+}
+/**
+ * Event handler callback function
+ */
+type SubscriptionEventHandler<T = GenericEvent> = (event: T) => void;
+/**
+ * Unsubscribe function returned from subscriptions
+ */
+type UnsubscribeFunction = () => void;
+/**
+ * Event source that provides subscription capabilities
+ */
+interface EventSource<T = GenericEvent> {
+  /**
+   * Subscribe to events from this source
+   * @returns Unsubscribe function to clean up the subscription
+   */
+  subscribe(handler: SubscriptionEventHandler<T>): UnsubscribeFunction;
+}
+/**
+ * Options for event filtering
+ */
+interface EventFilterOptions {
+  /**
+   * Filter events by type (exact match)
+   */
+  eventType?: string;
+  /**
+   * Filter events by upload/job ID
+   * If provided, only events with matching ID will be passed to the handler
+   */
+  uploadId?: string | null;
+  /**
+   * Custom filter function for advanced filtering
+   * Return true to pass the event to the handler
+   */
+  customFilter?: (event: GenericEvent) => boolean;
+}
+/**
+ * Platform-agnostic event subscription manager that handles event filtering,
+ * subscription tracking, and automatic cleanup.
+ *
+ * This manager simplifies event handling by:
+ * - Filtering events by type and/or ID
+ * - Tracking all active subscriptions
+ * - Providing cleanup methods to unsubscribe from all events
+ * - Supporting custom filter functions for advanced scenarios
+ *
+ * @example Basic event subscription
+ * ```typescript
+ * const manager = new EventSubscriptionManager(eventSource);
+ *
+ * manager.subscribe(
+ *   (event) => console.log('Upload progress:', event),
+ *   { eventType: 'UPLOAD_PROGRESS', uploadId: 'abc123' }
+ * );
+ *
+ * // Clean up all subscriptions when done
+ * manager.cleanup();
+ * ```
+ *
+ * @example Multiple filtered subscriptions
+ * ```typescript
+ * const manager = new EventSubscriptionManager(eventSource);
+ *
+ * // Subscribe to progress events for specific upload
+ * manager.subscribe(
+ *   onProgress,
+ *   { eventType: 'UPLOAD_PROGRESS', uploadId: currentUploadId }
+ * );
+ *
+ * // Subscribe to error events for any upload
+ * manager.subscribe(
+ *   onError,
+ *   { eventType: 'UPLOAD_ERROR' }
+ * );
+ *
+ * // Subscribe to all events with custom filtering
+ * manager.subscribe(
+ *   onEvent,
+ *   { customFilter: (e) => e.data?.priority === 'high' }
+ * );
+ * ```
+ */
+declare class EventSubscriptionManager<T extends GenericEvent = GenericEvent> {
+  private readonly eventSource;
+  private subscriptions;
+  /**
+   * Create a new EventSubscriptionManager
+   *
+   * @param eventSource - Source to subscribe to for events
+   */
+  constructor(eventSource: EventSource<T>);
+  /**
+   * Subscribe to events with optional filtering
+   *
+   * @param handler - Callback function to invoke when matching events occur
+   * @param filter - Optional filter options to narrow down which events trigger the handler
+   * @returns Unsubscribe function to remove this specific subscription
+   *
+   * @example Subscribe to specific event type
+   * ```typescript
+   * const unsubscribe = manager.subscribe(
+   *   (event) => console.log('Progress:', event),
+   *   { eventType: 'UPLOAD_PROGRESS' }
+   * );
+   *
+   * // Later, unsubscribe
+   * unsubscribe();
+   * ```
+   */
+  subscribe(handler: SubscriptionEventHandler<T>, filter?: EventFilterOptions): UnsubscribeFunction;
+  /**
+   * Check if an event matches the filter criteria
+   *
+   * @param event - Event to check
+   * @param filter - Filter options to apply
+   * @returns True if the event passes all filters
+   */
+  private shouldHandleEvent;
+  /**
+   * Get the number of active subscriptions
+   *
+   * @returns Number of tracked subscriptions
+   */
+  getSubscriptionCount(): number;
+  /**
+   * Check if there are any active subscriptions
+   *
+   * @returns True if at least one subscription is active
+   */
+  hasSubscriptions(): boolean;
+  /**
+   * Unsubscribe from all tracked subscriptions and clear the subscription list
+   *
+   * This is typically called when disposing of a component or cleaning up resources.
+   *
+   * @example Cleanup in framework hooks
+   * ```typescript
+   * // React
+   * useEffect(() => {
+   *   const manager = new EventSubscriptionManager(eventSource);
+   *   manager.subscribe(handler, filter);
+   *
+   *   return () => manager.cleanup();
+   * }, []);
+   *
+   * // Vue
+   * onUnmounted(() => {
+   *   manager.cleanup();
+   * });
+   * ```
+   */
+  cleanup(): void;
+  /**
+   * Update the upload ID filter for all subscriptions that have an uploadId filter
+   *
+   * This is useful when the current upload changes and you want to update
+   * all subscriptions to listen for the new upload's events.
+   *
+   * @param newUploadId - New upload ID to filter events by
+   *
+   * @example Update upload ID when starting new upload
+   * ```typescript
+   * const manager = new EventSubscriptionManager(eventSource);
+   * manager.subscribe(onProgress, { eventType: 'UPLOAD_PROGRESS', uploadId: null });
+   *
+   * // When upload starts
+   * manager.updateUploadIdFilter(uploadId);
+   * ```
+   */
+  updateUploadIdFilter(newUploadId: string | null): void;
+}
+//#endregion
+//#region src/managers/flow-manager.d.ts
+/**
+ * Flow upload status representing the current state of 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)
+ */
+interface FlowUploadState<TOutput = UploadFile> {
+  /** Current upload status */
+  status: FlowUploadStatus;
+  /** Upload progress percentage (0-100) */
+  progress: number;
+  /** Number of bytes uploaded */
+  bytesUploaded: number;
+  /** Total bytes to upload, null if unknown */
+  totalBytes: number | null;
+  /** Error if upload or processing failed */
+  error: Error | null;
+  /** Final output from the flow (available when status is "success") */
+  result: TOutput | null;
+  /** Unique identifier for the flow execution job */
+  jobId: string | null;
+  /** Whether the flow processing has started */
+  flowStarted: boolean;
+  /** Name of the currently executing flow node */
+  currentNodeName: string | null;
+  /** Type of the currently executing flow node */
+  currentNodeType: string | null;
+  /**
+   * Complete typed outputs from all output nodes in the flow.
+   * Each output includes nodeId, optional nodeType, data, and timestamp.
+   * Available when status is "success".
+   */
+  flowOutputs: TypedOutput[] | null;
+}
+/**
+ * Callbacks that FlowManager invokes during the flow upload lifecycle
+ */
+interface FlowManagerCallbacks<TOutput = UploadFile> {
+  /**
+   * Called when the flow upload state changes
+   */
+  onStateChange: (state: FlowUploadState<TOutput>) => void;
+  /**
+   * Called when upload progress updates
+   * @param progress - Progress percentage (0-100)
+   * @param bytesUploaded - Number of bytes uploaded
+   * @param totalBytes - Total bytes to upload, null if unknown
+   */
+  onProgress?: (uploadId: string, bytesUploaded: number, totalBytes: number | null) => void;
+  /**
+   * Called when a chunk completes
+   * @param chunkSize - Size of the completed chunk
+   * @param bytesAccepted - Total bytes accepted so far
+   * @param bytesTotal - Total bytes to upload, null if unknown
+   */
+  onChunkComplete?: (chunkSize: number, bytesAccepted: number, bytesTotal: number | null) => void;
+  /**
+   * Called when the flow completes successfully (receives full flow outputs)
+   * Each output includes nodeId, optional nodeType (e.g., "storage-output-v1"), data, and timestamp.
+   *
+   * @param outputs - Array of typed outputs from all output nodes
+   *
+   * @example
+   * ```typescript
+   * onFlowComplete: (outputs) => {
+   *   for (const output of outputs) {
+   *     console.log(`${output.nodeId} (${output.nodeType}):`, output.data);
+   *   }
+   * }
+   * ```
+   */
+  onFlowComplete?: (outputs: TypedOutput[]) => void;
+  /**
+   * Called when upload succeeds (receives single extracted output)
+   * For single-output flows, receives the value from the specified outputNodeId
+   * or the first output node if outputNodeId is not specified
+   */
+  onSuccess?: (result: TOutput) => void;
+  /**
+   * Called when upload or flow processing fails with an error
+   * @param error - The error that occurred
+   */
+  onError?: (error: Error) => void;
+  /**
+   * Called when upload or flow is aborted
+   */
+  onAbort?: () => void;
+}
+/**
+ * Generic flow upload input type - can be any value that the upload client accepts
+ */
+type FlowUploadInput = unknown;
+/**
+ * Flow configuration for upload
+ */
+interface FlowConfig {
+  flowId: string;
+  storageId: string;
+  outputNodeId?: string;
+  metadata?: Record<string, string>;
+}
+/**
+ * Abort and pause controller interface for canceling/pausing flow uploads
+ */
+interface FlowUploadAbortController {
+  abort: () => void | Promise<void>;
+  pause: () => void | Promise<void>;
+}
+/**
+ * Internal upload options used by the flow upload function.
+ * The upload phase always returns UploadFile, regardless of the final TOutput type.
+ */
+interface InternalFlowUploadOptions {
+  onJobStart?: (jobId: string) => void;
+  onProgress?: (uploadId: string, bytesUploaded: number, totalBytes: number | null) => void;
+  onChunkComplete?: (chunkSize: number, bytesAccepted: number, bytesTotal: number | null) => void;
+  onSuccess?: (result: UploadFile) => void;
+  onError?: (error: Error) => void;
+  onAbort?: () => void;
+  onShouldRetry?: (error: Error, retryAttempt: number) => boolean;
+}
+/**
+ * Flow upload function that performs the actual upload with flow processing.
+ * Returns a promise that resolves to an abort controller with pause capability.
+ *
+ * Note: The upload phase onSuccess always receives UploadFile. The final TOutput
+ * result comes from the flow execution and is handled via FlowEnd events.
+ */
+type FlowUploadFunction<TInput = FlowUploadInput> = (input: TInput, flowConfig: FlowConfig, options: InternalFlowUploadOptions) => Promise<FlowUploadAbortController>;
+/**
+ * Platform-agnostic flow upload manager that handles flow upload state machine,
+ * progress tracking, flow event handling, error handling, abort, pause, reset, and retry logic.
+ *
+ * Framework packages (React, Vue, React Native) should wrap this manager
+ * with framework-specific hooks/composables.
+ *
+ * @example
+ * ```typescript
+ * const flowUploadFn = (input, options) => client.uploadWithFlow(input, options.flowConfig, options);
+ * const manager = new FlowManager(flowUploadFn, {
+ *   onStateChange: (state) => setState(state),
+ *   onProgress: (progress, bytes, total) => console.log(`${progress}%`),
+ *   onSuccess: (result) => console.log('Flow complete:', result),
+ *   onError: (error) => console.error('Flow failed:', error),
+ * }, {
+ *   flowConfig: { flowId: 'my-flow', storageId: 'storage1' }
+ * });
+ *
+ * // Subscribe to events and forward them to the manager
+ * const unsubscribe = client.subscribeToEvents((event) => {
+ *   if (isFlowEvent(event)) {
+ *     manager.handleFlowEvent(event);
+ *   } else if (isUploadProgress(event)) {
+ *     manager.handleUploadProgress(event);
+ *   }
+ * });
+ *
+ * await manager.upload(file);
+ * ```
+ */
+declare class FlowManager<TInput = FlowUploadInput, TOutput = UploadFile> {
+  private readonly flowUploadFn;
+  private readonly callbacks;
+  private readonly options;
+  private state;
+  private abortController;
+  /**
+   * Create a new FlowManager
+   *
+   * @param flowUploadFn - Flow upload function to use for uploads
+   * @param callbacks - Callbacks to invoke during flow upload lifecycle
+   * @param options - Flow upload configuration options
+   */
+  constructor(flowUploadFn: FlowUploadFunction<TInput>, callbacks: FlowManagerCallbacks<TOutput>, options: FlowUploadOptions<TOutput>);
+  /**
+   * Get the current flow upload state
+   */
+  getState(): FlowUploadState<TOutput>;
+  /**
+   * Check if an upload or flow is currently active
+   */
+  isUploading(): boolean;
+  /**
+   * Check if file upload is in progress
+   */
+  isUploadingFile(): boolean;
+  /**
+   * Check if flow processing is in progress
+   */
+  isProcessing(): boolean;
+  /**
+   * Get the current job ID
+   */
+  getJobId(): string | null;
+  /**
+   * Update the internal state and notify callbacks
+   */
+  private updateState;
+  /**
+   * Handle flow events from the event subscription
+   * This method should be called by the framework wrapper when it receives flow events
+   *
+   * @param event - Flow event to process
+   */
+  handleFlowEvent(event: FlowEvent): void;
+  /**
+   * Handle upload progress events from the event subscription
+   * This method should be called by the framework wrapper when it receives upload progress events
+   *
+   * @param uploadId - The unique identifier for this upload
+   * @param bytesUploaded - Number of bytes uploaded
+   * @param totalBytes - Total bytes to upload, null if unknown
+   */
+  handleUploadProgress(uploadId: string, bytesUploaded: number, totalBytes: number | null): void;
+  /**
+   * Start uploading a file through the flow
+   *
+   * @param input - File or input to upload (type depends on platform)
+   */
+  upload(input: TInput): Promise<void>;
+  /**
+   * Abort the current flow upload
+   */
+  abort(): void;
+  /**
+   * Pause the current flow upload
+   */
+  pause(): void;
+  /**
+   * Reset the flow upload state to idle
+   */
+  reset(): void;
+  /**
+   * Clean up resources (call when disposing the manager)
+   */
+  cleanup(): void;
+}
+//#endregion
+//#region src/managers/upload-manager.d.ts
+/**
+ * Upload status representing the current state of an upload
+ */
+type UploadStatus = "idle" | "uploading" | "success" | "error" | "aborted";
+/**
+ * Complete upload state
+ */
+interface UploadState {
+  /** Current status of the upload */
+  status: UploadStatus;
+  /** Upload progress percentage (0-100) */
+  progress: number;
+  /** Number of bytes uploaded */
+  bytesUploaded: number;
+  /** Total bytes to upload, null if unknown/deferred */
+  totalBytes: number | null;
+  /** Error if upload failed */
+  error: Error | null;
+  /** Result if upload succeeded */
+  result: UploadFile | null;
+}
+/**
+ * Callbacks that UploadManager invokes during the upload lifecycle
+ */
+interface UploadManagerCallbacks {
+  /**
+   * Called when the upload state changes
+   */
+  onStateChange: (state: UploadState) => void;
+  /**
+   * Called when upload progress updates
+   * @param uploadId - The unique identifier for this upload
+   * @param bytesUploaded - Number of bytes uploaded
+   * @param totalBytes - Total bytes to upload, null if unknown
+   */
+  onProgress?: (uploadId: string, bytesUploaded: number, totalBytes: number | null) => void;
+  /**
+   * Called when a chunk completes
+   * @param chunkSize - Size of the completed chunk
+   * @param bytesAccepted - Total bytes accepted so far
+   * @param bytesTotal - Total bytes to upload, null if unknown
+   */
+  onChunkComplete?: (chunkSize: number, bytesAccepted: number, bytesTotal: number | null) => void;
+  /**
+   * Called when upload completes successfully
+   * @param result - The uploaded file result
+   */
+  onSuccess?: (result: UploadFile) => void;
+  /**
+   * Called when upload fails with an error
+   * @param error - The error that occurred
+   */
+  onError?: (error: Error) => void;
+  /**
+   * Called when upload is aborted
+   */
+  onAbort?: () => void;
+}
+/**
+ * Generic upload input type - can be any value that the upload client accepts
+ */
+type UploadInput = unknown;
+/**
+ * Abort controller interface for canceling uploads
+ */
+interface UploadAbortController {
+  abort: () => void;
+}
+/**
+ * Upload function that performs the actual upload.
+ * Returns a promise that resolves to an abort controller.
+ */
+type UploadFunction<TInput = UploadInput, TOptions extends UploadOptions = UploadOptions> = (input: TInput, options: TOptions) => Promise<UploadAbortController>;
+/**
+ * Platform-agnostic upload manager that handles upload state machine,
+ * progress tracking, error handling, abort, reset, and retry logic.
+ *
+ * Framework packages (React, Vue, React Native) should wrap this manager
+ * with framework-specific hooks/composables.
+ *
+ * @example
+ * ```typescript
+ * const uploadFn = (input, options) => client.upload(input, options);
+ * const manager = new UploadManager(uploadFn, {
+ *   onStateChange: (state) => setState(state),
+ *   onProgress: (progress) => console.log(`${progress}%`),
+ *   onSuccess: (result) => console.log('Upload complete:', result),
+ *   onError: (error) => console.error('Upload failed:', error),
+ * });
+ *
+ * await manager.upload(file);
+ * ```
+ */
+declare class UploadManager<TInput = UploadInput, TOptions extends UploadOptions = UploadOptions> {
+  private readonly uploadFn;
+  private readonly callbacks;
+  private readonly options?;
+  private state;
+  private abortController;
+  private lastInput;
+  private uploadId;
+  /**
+   * Create a new UploadManager
+   *
+   * @param uploadFn - Upload function to use for uploads
+   * @param callbacks - Callbacks to invoke during upload lifecycle
+   * @param options - Upload configuration options
+   */
+  constructor(uploadFn: UploadFunction<TInput, TOptions>, callbacks: UploadManagerCallbacks, options?: TOptions | undefined);
+  /**
+   * Get the current upload state
+   */
+  getState(): UploadState;
+  /**
+   * Check if an upload is currently active
+   */
+  isUploading(): boolean;
+  /**
+   * Check if the upload can be retried
+   */
+  canRetry(): boolean;
+  /**
+   * Update the internal state and notify callbacks
+   */
+  private updateState;
+  /**
+   * Start uploading a file or input
+   *
+   * @param input - File or input to upload (type depends on platform)
+   */
+  upload(input: TInput): Promise<void>;
+  /**
+   * Abort the current upload
+   */
+  abort(): void;
+  /**
+   * Reset the upload state to idle
+   */
+  reset(): void;
+  /**
+   * Retry the last failed or aborted upload
+   */
+  retry(): void;
+  /**
+   * Clean up resources (call when disposing the manager)
+   */
+  cleanup(): void;
+}
+//#endregion
+export { AbortControllerFactory, AbortControllerLike, AbortSignalLike, Base64Service, ChecksumService, ChunkBuffer, ChunkBufferConfig, ChunkMetrics, ClientStorage, ConnectionHealth, ConnectionMetrics, ConnectionPoolConfig, DetailedConnectionMetrics, type EventFilterOptions, type EventSource, EventSubscriptionManager, FileReaderService, FileSource, FingerprintService, type FlowConfig, FlowManager, type FlowManagerCallbacks, FlowResponse, FlowResult, type FlowUploadAbortController, FlowUploadConfig, type FlowUploadFunction, type FlowUploadInput, FlowUploadItem, FlowUploadOptions, type FlowUploadState, type FlowUploadStatus, type GenericEvent, HeadersLike, Http2Info, HttpClient, HttpRequestOptions, HttpResponse, IdGenerationService, type InternalFlowUploadOptions, LogFunction, Logger, MultiFlowUploadOptions, MultiFlowUploadState, NetworkCondition, NetworkMetrics, NetworkMonitor, NetworkMonitorConfig, PerformanceInsights, PlatformService, PreviousUpload, RequestBody, ServiceContainer, SliceResult, StorageService, type SubscriptionEventHandler, Timeout, type UnsubscribeFunction, type UploadAbortController, type UploadFunction, type UploadInput, UploadManager, type UploadManagerCallbacks, UploadMetrics, UploadOptions, UploadResponse, UploadResult, UploadSample, UploadSessionMetrics, type UploadState, type UploadStatus, UploadistaApi, UploadistaClient, UploadistaClientOptions, UploadistaDeleteUploadResponse, UploadistaError, UploadistaErrorName, UploadistaEvent, UploadistaUploadOptions, UploadistaUploadResponse, UploadistaWebSocketEventHandler, UploadistaWebSocketManager, UploadistaWebSocketMessage, WebSocketEventMap, WebSocketFactory, WebSocketLike, createClientStorage, createInMemoryStorageService, createLogger, createUploadistaApi, createUploadistaClient, defaultConnectionPoolingConfig, previousUploadSchema, wait };
 //# sourceMappingURL=index.d.mts.map