@uploadista/client-core 0.0.3

package/dist/client/create-uploadista-client.js

@@ -0,0 +1,518 @@
+import { DirectAuthManager, NoAuthManager, SaasAuthManager } from "../auth";
+import { createLogger } from "../logger";
+import { defaultClientCapabilities } from "../mock-data-store";
+import { NetworkMonitor } from "../network-monitor";
+import { SmartChunker } from "../smart-chunker";
+import { performFlowUpload, startFlowUpload } from "../upload/flow-upload";
+import { startParallelUpload } from "../upload/parallel-upload";
+import { performUpload, startSingleUpload, } from "../upload/single-upload";
+import { abort, terminate } from "../upload/upload-manager";
+import { UploadMetrics, } from "../upload/upload-metrics";
+import { findPreviousUploads, resumeFromPreviousUpload, } from "../upload/upload-storage";
+import { negotiateUploadStrategy, validateAndThrow, validateConfiguration, } from "../upload/upload-strategy";
+import { calculateFileSize } from "../upload/upload-utils";
+import { createUploadistaApi } from "./uploadista-api";
+import { UploadistaWebSocketManager, } from "./uploadista-websocket-manager";
+/**
+ * Default connection pooling configuration with health monitoring.
+ *
+ * Optimized for typical upload scenarios with support for HTTP/2 multiplexing,
+ * connection reuse, and automatic retry on connection errors.
+ */
+export const defaultConnectionPoolingConfig = {
+    /** Maximum concurrent connections per host */
+    maxConnectionsPerHost: 8,
+    /** Timeout for establishing new connections in milliseconds */
+    connectionTimeout: 20000,
+    /** Keep-alive timeout for idle connections in milliseconds */
+    keepAliveTimeout: 90000,
+    /** Enable HTTP/2 for connection multiplexing */
+    enableHttp2: true,
+    /** Automatically retry requests on connection errors */
+    retryOnConnectionError: true,
+};
+/**
+ * Creates a unified Uploadista client for file uploads and flow processing.
+ *
+ * This is the primary factory function for creating an Uploadista client instance.
+ * It configures all upload capabilities including:
+ * - Resumable chunked uploads with automatic retry
+ * - Parallel upload streams for large files
+ * - Smart chunking based on network conditions
+ * - Flow-based file processing pipelines
+ * - WebSocket support for real-time progress
+ * - Authentication (direct, SaaS, or no-auth modes)
+ *
+ * The client automatically:
+ * - Fetches server capabilities and adapts upload strategy
+ * - Monitors network performance for optimal chunking
+ * - Stores upload state for resumption across sessions
+ * - Manages WebSocket connections for progress tracking
+ *
+ * @template UploadInput - Platform-specific file type (File, Blob, Buffer, etc.)
+ * @param options - Comprehensive client configuration
+ * @returns Uploadista client instance with upload and flow methods
+ *
+ * @example Basic browser setup
+ * ```typescript
+ * import { createUploadistaClient } from '@uploadista/client-core';
+ * import { browserServices } from '@uploadista/client-browser';
+ *
+ * const client = createUploadistaClient({
+ *   baseUrl: 'https://upload.example.com',
+ *   storageId: 'my-storage',
+ *   chunkSize: 5 * 1024 * 1024, // 5MB chunks
+ *   ...browserServices,
+ * });
+ *
+ * // Upload a file
+ * const { abort } = await client.upload(file, {
+ *   onProgress: (progress) => console.log(`${progress}% complete`),
+ *   onSuccess: (result) => console.log('Upload complete:', result),
+ * });
+ * ```
+ *
+ * @example Upload with flow processing
+ * ```typescript
+ * const client = createUploadistaClient(config);
+ *
+ * // Upload and process through a flow
+ * const { abort, jobId } = await client.uploadWithFlow(file, {
+ *   flowId: 'image-optimization-flow',
+ *   storageId: 'images',
+ *   outputNodeId: 'optimized-output',
+ * }, {
+ *   onProgress: (progress) => console.log(`${progress}%`),
+ *   onSuccess: (result) => console.log('Processed:', result),
+ * });
+ *
+ * // Monitor job status
+ * const status = await client.getJobStatus(jobId);
+ * ```
+ *
+ * @example Parallel uploads for large files
+ * ```typescript
+ * const client = createUploadistaClient({
+ *   baseUrl: 'https://upload.example.com',
+ *   storageId: 'large-files',
+ *   chunkSize: 10 * 1024 * 1024, // 10MB
+ *   parallelUploads: 4, // 4 concurrent streams
+ *   parallelChunkSize: 5 * 1024 * 1024, // 5MB per stream
+ *   ...browserServices,
+ * });
+ *
+ * await client.upload(largeFile);
+ * ```
+ *
+ * @example With authentication
+ * ```typescript
+ * const client = createUploadistaClient({
+ *   baseUrl: 'https://upload.example.com',
+ *   storageId: 'protected',
+ *   chunkSize: 5 * 1024 * 1024,
+ *   auth: {
+ *     mode: 'direct',
+ *     getCredentials: async () => ({
+ *       headers: {
+ *         'Authorization': `Bearer ${await getToken()}`,
+ *       },
+ *     }),
+ *   },
+ *   ...browserServices,
+ * });
+ * ```
+ *
+ * @example Smart chunking with network monitoring
+ * ```typescript
+ * const client = createUploadistaClient({
+ *   baseUrl: 'https://upload.example.com',
+ *   storageId: 'adaptive',
+ *   chunkSize: 1 * 1024 * 1024, // Fallback: 1MB
+ *   smartChunking: {
+ *     enabled: true,
+ *     minChunkSize: 256 * 1024, // 256KB min
+ *     maxChunkSize: 10 * 1024 * 1024, // 10MB max
+ *   },
+ *   networkMonitoring: {
+ *     slowThreshold: 50 * 1024, // 50 KB/s
+ *     fastThreshold: 5 * 1024 * 1024, // 5 MB/s
+ *   },
+ *   ...browserServices,
+ * });
+ *
+ * // Monitor network conditions
+ * const condition = client.getNetworkCondition();
+ * console.log(`Network: ${condition.type} (confidence: ${condition.confidence})`);
+ * ```
+ *
+ * @see {@link UploadistaClientOptions} for full configuration options
+ * @see {@link UploadistaUploadOptions} for per-upload options
+ */
+export function createUploadistaClient({ baseUrl: _baseUrl, uploadistaBasePath = "uploadista", storageId, retryDelays = [1000, 3000, 5000], chunkSize, parallelUploads = 1, parallelChunkSize, uploadStrategy, smartChunking, networkMonitoring, uploadMetrics, checksumService, onEvent, generateId, httpClient, logger = createLogger(true), fileReader, fingerprintService, clientStorage, storeFingerprintForResuming = true, webSocketFactory, abortControllerFactory, platformService, auth, }) {
+    const baseUrl = _baseUrl.replace(/\/$/, "");
+    // Create auth manager based on configuration
+    const authManager = auth
+        ? auth.mode === "direct"
+            ? new DirectAuthManager(auth, platformService, logger)
+            : new SaasAuthManager(auth, httpClient)
+        : new NoAuthManager();
+    // Log auth mode for debugging (without exposing credentials)
+    if (auth) {
+        logger.log(`Authentication enabled in ${auth.mode} mode${auth.mode === "saas" ? ` (server: ${auth.authServerUrl})` : ""}`);
+    }
+    // Create the unified API with auth support
+    const uploadistaApi = createUploadistaApi(baseUrl, uploadistaBasePath, {
+        logger,
+        httpClient,
+        authManager,
+        webSocketFactory,
+    });
+    // Initialize smart chunking components
+    const networkMonitor = new NetworkMonitor(networkMonitoring);
+    const metrics = new UploadMetrics(uploadMetrics);
+    // Cache for server capabilities
+    let cachedCapabilities = null;
+    const getCapabilities = async () => {
+        if (cachedCapabilities) {
+            return cachedCapabilities;
+        }
+        cachedCapabilities = await uploadistaApi.getCapabilities(storageId);
+        return cachedCapabilities;
+    };
+    // Initialize smart chunker with datastore constraints from server capabilities
+    let smartChunker;
+    const initializeSmartChunker = async () => {
+        if (smartChunker)
+            return smartChunker;
+        const capabilities = await getCapabilities();
+        const datastoreConstraints = capabilities.minChunkSize &&
+            capabilities.maxChunkSize &&
+            capabilities.optimalChunkSize
+            ? {
+                minChunkSize: capabilities.minChunkSize,
+                maxChunkSize: capabilities.maxChunkSize,
+                optimalChunkSize: capabilities.optimalChunkSize,
+                requiresOrderedChunks: capabilities.requiresOrderedChunks,
+            }
+            : undefined;
+        smartChunker = new SmartChunker(networkMonitor, {
+            enabled: true,
+            ...smartChunking,
+            fallbackChunkSize: chunkSize,
+            datastoreConstraints,
+        });
+        logger.log(`Smart chunker initialized with datastore constraints: ${JSON.stringify(datastoreConstraints)}`);
+        return smartChunker;
+    };
+    // WebSocket management (uses uploadistaApi for both upload and flow websockets)
+    const wsManager = new UploadistaWebSocketManager(uploadistaApi, logger, onEvent);
+    /**
+     * Upload a file
+     */
+    const upload = async (file, { uploadLengthDeferred = false, uploadSize, onProgress, onChunkComplete, onSuccess, onShouldRetry, onError, } = {}) => {
+        let uploadId = null;
+        let uploadIdStorageKey = null;
+        const fingerprint = await fingerprintService.computeFingerprint(file, `${baseUrl}/${uploadistaBasePath}/api/upload`);
+        logger.log(`fingerprint: ${fingerprint}`);
+        if (!fingerprint) {
+            throw new Error("unable calculate fingerprint for this input file");
+        }
+        const previousUploads = await findPreviousUploads(clientStorage, fingerprint);
+        if (previousUploads.length > 0 && previousUploads[0] != null) {
+            const previousUpload = resumeFromPreviousUpload(previousUploads[0]);
+            uploadIdStorageKey = previousUpload.clientStorageKey;
+            uploadId = previousUpload.uploadId;
+        }
+        const source = await fileReader.openFile(file, chunkSize);
+        const size = calculateFileSize(source.size, {
+            uploadLengthDeferred,
+            uploadSize,
+        });
+        source.size = size;
+        const initializedSmartChunker = await initializeSmartChunker();
+        const isSmartChunkingEnabled = smartChunking?.enabled !== false;
+        if (isSmartChunkingEnabled) {
+            metrics.startSession(fingerprint, size || 0, true);
+        }
+        const capabilities = await getCapabilities();
+        const negotiatedStrategy = negotiateUploadStrategy({
+            capabilities,
+            fileSize: size,
+            chunkSize,
+            parallelUploads,
+            uploadLengthDeferred,
+            strategyConfig: uploadStrategy,
+            logger,
+        });
+        if (negotiatedStrategy.strategy === "parallel") {
+            logger.log(`Using parallel upload with ${negotiatedStrategy.parallelUploads} streams`);
+            const parallelResult = await startParallelUpload({
+                checksumService,
+                source,
+                storageId,
+                fingerprint,
+                uploadLengthDeferred,
+                parallelUploads: negotiatedStrategy.parallelUploads,
+                parallelChunkSize,
+                retryDelays,
+                smartChunker: initializedSmartChunker,
+                uploadistaApi,
+                logger,
+                smartChunking,
+                metrics,
+                clientStorage,
+                generateId,
+                storeFingerprintForResuming,
+                abortControllerFactory,
+                platformService,
+                openWebSocket: (id) => {
+                    wsManager.openUploadWebSocket(id);
+                    // Note: WebSocket opening is now async due to auth, but this callback is sync
+                    // The WebSocket will be opened in the background
+                    return null;
+                },
+                closeWebSocket: (id) => wsManager.closeUploadWebSocket(id),
+                terminate: (id) => terminate(id, uploadistaApi, platformService, retryDelays),
+                onProgress,
+                onChunkComplete,
+                onSuccess,
+                onError,
+            });
+            if (parallelResult) {
+                return {
+                    abort: async () => {
+                        await parallelResult.abort();
+                    },
+                };
+            }
+            logger.log("Parallel upload failed, falling back to single upload");
+        }
+        // Single upload path
+        const result = await startSingleUpload({
+            source,
+            storageId,
+            uploadId,
+            platformService,
+            uploadIdStorageKey,
+            checksumService,
+            fingerprint,
+            uploadLengthDeferred,
+            uploadistaApi,
+            logger,
+            clientStorage,
+            generateId,
+            storeFingerprintForResuming,
+            openWebSocket: (id) => {
+                wsManager.openUploadWebSocket(id);
+                // Note: WebSocket opening is now async due to auth, but this callback is sync
+                // The WebSocket will be opened in the background
+                return null;
+            },
+            closeWebSocket: (id) => wsManager.closeUploadWebSocket(id),
+            onProgress,
+            onChunkComplete,
+            onSuccess,
+            onError,
+        });
+        if (result) {
+            const abortController = abortControllerFactory.create();
+            const { uploadId, uploadIdStorageKey, offset } = result;
+            let timeoutId = null;
+            performUpload({
+                platformService,
+                uploadId,
+                offset,
+                source,
+                uploadLengthDeferred,
+                retryDelays,
+                smartChunker: initializedSmartChunker,
+                uploadistaApi,
+                logger,
+                smartChunking,
+                metrics,
+                abortController,
+                onProgress,
+                onChunkComplete,
+                onSuccess,
+                onShouldRetry,
+                onRetry: (timeout) => {
+                    timeoutId = timeout;
+                },
+                onError,
+            });
+            return {
+                abort: () => {
+                    abort({
+                        platformService,
+                        uploadId,
+                        uploadIdStorageKey,
+                        retryTimeout: timeoutId,
+                        shouldTerminate: true,
+                        abortController,
+                        uploadistaApi,
+                        retryDelays,
+                        clientStorage,
+                    });
+                },
+            };
+        }
+        return {
+            abort: () => { },
+        };
+    };
+    // Run validation on client creation
+    validateAndThrow({
+        baseUrl,
+        storageId,
+        chunkSize,
+        parallelUploads,
+        parallelChunkSize,
+        uploadStrategy,
+    }, logger);
+    /**
+     * Upload a file through a flow (using streaming-input-node)
+     */
+    const uploadWithFlow = async (file, flowConfig, { onProgress, onChunkComplete, onSuccess, onShouldRetry, onJobStart, onError, } = {}) => {
+        const source = await fileReader.openFile(file, chunkSize);
+        const initializedSmartChunker = await initializeSmartChunker();
+        const isSmartChunkingEnabled = smartChunking?.enabled !== false;
+        if (isSmartChunkingEnabled) {
+            const fingerprint = await fingerprintService.computeFingerprint(file, `${baseUrl}/${uploadistaBasePath}/api/flow`);
+            metrics.startSession(fingerprint || "unknown", source.size || 0, true);
+        }
+        const result = await startFlowUpload({
+            source,
+            flowConfig,
+            uploadistaApi,
+            logger,
+            platformService,
+            openWebSocket: (id) => wsManager.openFlowWebSocket(id),
+            closeWebSocket: (id) => wsManager.closeWebSocket(id),
+            onProgress,
+            onChunkComplete,
+            onSuccess,
+            onJobStart,
+            onError,
+        });
+        if (!result) {
+            return {
+                abort: () => { },
+                jobId: "",
+            };
+        }
+        const { jobId, uploadFile, inputNodeId } = result;
+        const abortController = abortControllerFactory.create();
+        // Open upload WebSocket to receive upload progress events
+        await wsManager.openUploadWebSocket(uploadFile.id);
+        let timeoutId = null;
+        performFlowUpload({
+            jobId,
+            uploadFile,
+            inputNodeId,
+            offset: uploadFile.offset,
+            source,
+            retryDelays,
+            smartChunker: initializedSmartChunker,
+            uploadistaApi,
+            logger,
+            smartChunking,
+            metrics,
+            platformService,
+            abortController,
+            onProgress,
+            onChunkComplete,
+            onSuccess,
+            onShouldRetry,
+            onRetry: (timeout) => {
+                timeoutId = timeout;
+            },
+            onError,
+        });
+        return {
+            abort: () => {
+                abortController.abort();
+                if (timeoutId) {
+                    platformService.clearTimeout(timeoutId);
+                }
+                // Close both flow and upload WebSockets
+                wsManager.closeWebSocket(jobId);
+                wsManager.closeUploadWebSocket(uploadFile.id);
+            },
+            jobId,
+        };
+    };
+    return {
+        // Upload operations
+        upload,
+        uploadWithFlow,
+        abort: (params) => abort(params),
+        // Flow operations
+        getFlow: async (flowId) => {
+            const { status, flow } = await uploadistaApi.getFlow(flowId);
+            return { status, flow };
+        },
+        runFlow: async ({ flowId, inputs, storageId: flowStorageId, }) => {
+            const { status, job } = await uploadistaApi.runFlow(flowId, flowStorageId || storageId, inputs);
+            return { status, job };
+        },
+        continueFlow: async ({ jobId, nodeId, newData, contentType, }) => {
+            return uploadistaApi.continueFlow(jobId, nodeId, newData, {
+                contentType,
+            });
+        },
+        // Job operations (unified for both uploads and flows)
+        getJobStatus: async (jobId) => {
+            return uploadistaApi.getJobStatus(jobId);
+        },
+        // WebSocket management methods
+        openUploadWebSocket: (uploadId) => wsManager.openUploadWebSocket(uploadId),
+        openFlowWebSocket: (jobId) => wsManager.openFlowWebSocket(jobId),
+        openWebSocket: (id) => wsManager.openWebSocket(id),
+        closeWebSocket: (id) => wsManager.closeWebSocket(id),
+        closeAllWebSockets: () => wsManager.closeAll(),
+        sendPing: (jobId) => wsManager.sendPing(jobId),
+        isWebSocketConnected: (id) => wsManager.isConnected(id),
+        getWebSocketConnectionCount: () => wsManager.getConnectionCount(),
+        getWebSocketConnectionCountByType: () => wsManager.getConnectionCountByType(),
+        // Smart chunking utilities
+        getNetworkMetrics: () => networkMonitor.getCurrentMetrics(),
+        getNetworkCondition: () => networkMonitor.getNetworkCondition(),
+        getChunkingInsights: () => metrics.getPerformanceInsights(),
+        exportMetrics: () => metrics.exportMetrics(),
+        // Connection pooling utilities
+        getConnectionMetrics: () => uploadistaApi.getConnectionMetrics(),
+        getDetailedConnectionMetrics: () => uploadistaApi.getDetailedConnectionMetrics(),
+        warmupConnections: (urls) => uploadistaApi.warmupConnections(urls),
+        // Smart chunking insights
+        getConnectionPoolingInsights: async () => {
+            const chunker = await initializeSmartChunker();
+            return chunker.getConnectionPoolingInsights();
+        },
+        resetMetrics: async () => {
+            networkMonitor.reset();
+            const chunker = await initializeSmartChunker();
+            chunker.reset();
+            metrics.reset();
+        },
+        // Configuration validation
+        validateConfiguration: (options) => {
+            return validateConfiguration(options, defaultClientCapabilities, logger);
+        },
+        validateConfigurationAsync: async (options) => {
+            const errors = [];
+            const warnings = [];
+            // Fetch capabilities using the authenticated HTTP client
+            const capabilities = await uploadistaApi.getCapabilities(options.storageId);
+            const validation = validateConfiguration(options, capabilities, logger);
+            errors.push(...validation.errors);
+            warnings.push(...validation.warnings);
+            return {
+                valid: errors.length === 0,
+                errors,
+                warnings,
+                capabilities,
+            };
+        },
+        getCapabilities,
+    };
+}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./create-uploadista-client";
+export * from "./uploadista-api";
+export * from "./uploadista-websocket-manager";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,gCAAgC,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,3 @@
+export * from "./create-uploadista-client";
+export * from "./uploadista-api";
+export * from "./uploadista-websocket-manager";