@uploadista/client-core 0.0.3 → 0.0.4

package/dist/index.d.ts

@@ -1,9 +1,2675 @@
-export * from "./chunk-buffer";
-export * from "./client";
-export * from "./error";
-export * from "./logger";
-export * from "./network-monitor";
-export * from "./services";
-export * from "./storage";
-export * from "./types";
+import { UploadStrategyNegotiator } from "@uploadista/core/upload";
+import { DataStoreCapabilities, InputFile, UploadEvent, UploadFile } from "@uploadista/core/types";
+import z from "zod";
+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 {
+  data: Uint8Array;
+  size: number;
+  timestamp: number;
+}
+//#endregion
+//#region src/chunk-buffer.d.ts
+/**
+ * Configuration options for ChunkBuffer.
+ *
+ * Controls how the buffer accumulates chunks before flushing them to the datastore.
+ * This is essential for datastores with minimum chunk size requirements (e.g., AWS S3's 5MB minimum).
+ */
+interface ChunkBufferConfig {
+  /**
+   * Minimum chunk size required by the datastore before flushing (in bytes).
+   * For example, AWS S3 requires a minimum of 5MB per multipart upload part.
+   */
+  minThreshold: number;
+  /**
+   * Maximum buffer size before forcing a flush (in bytes).
+   * Defaults to 2x minThreshold. Prevents memory issues with very slow uploads.
+   */
+  maxBufferSize?: number;
+  /**
+   * Maximum time to wait before flushing pending data (in milliseconds).
+   * Defaults to 30000ms (30 seconds). Ensures timely uploads even with slow data arrival.
+   */
+  timeoutMs?: number;
+}
+/**
+ * ChunkBuffer accumulates small chunks until they meet the minimum threshold
+ * required by the datastore (e.g., S3's 5MB minimum part size).
+ *
+ * This prevents inefficient upload/download cycles of incomplete parts by buffering
+ * small chunks in memory until they reach the datastore's minimum size requirement.
+ * The buffer automatically flushes when the threshold is met, the maximum buffer
+ * size is exceeded, or a timeout occurs.
+ *
+ * @example Basic usage with S3's 5MB minimum
+ * ```typescript
+ * const buffer = new ChunkBuffer({
+ *   minThreshold: 5 * 1024 * 1024, // 5MB
+ *   maxBufferSize: 10 * 1024 * 1024, // 10MB
+ *   timeoutMs: 30000, // 30 seconds
+ * });
+ *
+ * // Add chunks as they arrive
+ * const chunk1 = new Uint8Array(2 * 1024 * 1024); // 2MB
+ * buffer.add(chunk1); // Returns null (below threshold)
+ *
+ * const chunk2 = new Uint8Array(3 * 1024 * 1024); // 3MB
+ * const buffered = buffer.add(chunk2); // Returns combined 5MB chunk
+ * ```
+ *
+ * @example Handling incomplete uploads
+ * ```typescript
+ * const buffer = new ChunkBuffer({ minThreshold: 5 * 1024 * 1024 });
+ *
+ * // After adding several small chunks
+ * buffer.add(smallChunk1);
+ * buffer.add(smallChunk2);
+ *
+ * // Force flush remaining data at end of upload
+ * if (buffer.hasPendingData()) {
+ *   const finalChunk = buffer.flush();
+ *   await uploadFinalChunk(finalChunk);
+ * }
+ * ```
+ */
+declare class ChunkBuffer {
+  private buffer;
+  private currentSize;
+  private config;
+  private lastAddTime;
+  /**
+   * Creates a new ChunkBuffer instance.
+   *
+   * @param config - Buffer configuration including thresholds and timeout
+   */
+  constructor(config: ChunkBufferConfig);
+  /**
+   * Adds a chunk to the buffer and returns the accumulated chunk if the flush threshold is met.
+   *
+   * The buffer will automatically flush (return the combined chunk) when:
+   * - The total buffered size meets or exceeds minThreshold
+   * - The total buffered size exceeds maxBufferSize
+   * - The time since the last chunk exceeds timeoutMs
+   *
+   * @param chunk - The chunk data to add to the buffer
+   * @returns The combined buffered chunk if flush conditions are met, null otherwise
+   *
+   * @example Progressive buffering
+   * ```typescript
+   * const buffer = new ChunkBuffer({ minThreshold: 1024 * 1024 }); // 1MB
+   *
+   * // First chunk doesn't meet threshold
+   * const result1 = buffer.add(new Uint8Array(512 * 1024)); // 512KB
+   * console.log(result1); // null
+   *
+   * // Second chunk triggers flush
+   * const result2 = buffer.add(new Uint8Array(512 * 1024)); // 512KB
+   * console.log(result2?.size); // 1048576 (1MB total)
+   * ```
+   */
+  add(chunk: Uint8Array): BufferedChunk | null;
+  /**
+   * Forces the buffer to flush immediately, returning all accumulated data.
+   *
+   * This is typically called at the end of an upload to ensure any remaining
+   * buffered data is sent, even if it hasn't reached the minimum threshold.
+   *
+   * @returns The combined buffered chunk, or null if the buffer is empty
+   *
+   * @example Flushing at upload completion
+   * ```typescript
+   * const buffer = new ChunkBuffer({ minThreshold: 5 * 1024 * 1024 });
+   *
+   * // Upload file in chunks
+   * for (const chunk of fileChunks) {
+   *   const buffered = buffer.add(chunk);
+   *   if (buffered) await uploadChunk(buffered);
+   * }
+   *
+   * // Upload any remaining data
+   * const final = buffer.flush();
+   * if (final) await uploadChunk(final);
+   * ```
+   */
+  flush(): BufferedChunk | null;
+  /**
+   * Checks if the buffer should be flushed based on size, max buffer, or timeout conditions.
+   *
+   * Returns true if any of these conditions are met:
+   * - Current size >= minThreshold
+   * - Current size >= maxBufferSize
+   * - Time since last add > timeoutMs
+   *
+   * @returns True if the buffer should be flushed
+   *
+   * @example Manual flush control
+   * ```typescript
+   * const buffer = new ChunkBuffer({ minThreshold: 1024 * 1024 });
+   *
+   * buffer.add(smallChunk);
+   *
+   * if (buffer.shouldFlush()) {
+   *   const data = buffer.flush();
+   *   await upload(data);
+   * }
+   * ```
+   */
+  shouldFlush(): boolean;
+  /**
+   * Returns the current buffer state without flushing.
+   *
+   * Useful for monitoring buffer status and making informed decisions
+   * about when to manually flush or adjust upload strategies.
+   *
+   * @returns Object containing buffer metrics
+   *
+   * @example Monitoring buffer state
+   * ```typescript
+   * const buffer = new ChunkBuffer({ minThreshold: 1024 * 1024 });
+   * buffer.add(chunk);
+   *
+   * const info = buffer.getBufferInfo();
+   * console.log(`Buffered: ${info.size} bytes in ${info.chunkCount} chunks`);
+   * console.log(`Ready to flush: ${info.isReadyToFlush}`);
+   * console.log(`Time since last add: ${info.timeSinceLastAdd}ms`);
+   * ```
+   */
+  getBufferInfo(): {
+    size: number;
+    chunkCount: number;
+    isReadyToFlush: boolean;
+    timeSinceLastAdd: number;
+  };
+  /**
+   * Checks if the buffer has any pending data that hasn't been flushed.
+   *
+   * Useful for determining if a final flush is needed at upload completion.
+   *
+   * @returns True if there are chunks waiting in the buffer
+   *
+   * @example Ensuring complete upload
+   * ```typescript
+   * // Upload all chunks
+   * for (const chunk of chunks) {
+   *   const buffered = buffer.add(chunk);
+   *   if (buffered) await upload(buffered);
+   * }
+   *
+   * // Don't forget the last partial chunk!
+   * if (buffer.hasPendingData()) {
+   *   await upload(buffer.flush());
+   * }
+   * ```
+   */
+  hasPendingData(): boolean;
+  /**
+   * Clears the buffer without returning data.
+   *
+   * This discards all buffered chunks and resets the buffer state.
+   * Use with caution as this will lose any pending data.
+   */
+  reset(): void;
+  /**
+   * Returns the minimum threshold this buffer is configured for.
+   *
+   * @returns Minimum chunk size in bytes before flushing
+   */
+  getMinThreshold(): number;
+}
+//#endregion
+//#region src/services/abort-controller-service.d.ts
+/**
+ * Platform-agnostic AbortController interface
+ */
+interface AbortControllerLike {
+  readonly signal: AbortSignalLike;
+  abort(reason?: unknown): void;
+}
+interface AbortSignalLike {
+  readonly aborted: boolean;
+  addEventListener(type: "abort", listener: () => void): void;
+  removeEventListener(type: "abort", listener: () => void): void;
+}
+interface AbortControllerFactory {
+  /**
+   * Create a new AbortController instance
+   */
+  create(): AbortControllerLike;
+}
+//#endregion
+//#region src/services/http-client.d.ts
+/**
+ * Platform-agnostic request body type.
+ *
+ * Supports various data formats for HTTP request bodies across different platforms.
+ */
+type RequestBody = string | Uint8Array | ArrayBuffer | null | undefined;
+/**
+ * Platform-agnostic HTTP headers interface.
+ *
+ * Provides a subset of the Web Headers API that works across platforms.
+ */
+interface HeadersLike {
+  /** Retrieves a header value by name, or null if not found */
+  get(name: string): string | null;
+  /** Checks if a header exists */
+  has(name: string): boolean;
+  /** Iterates over all headers */
+  forEach(callback: (value: string, name: string) => void): void;
+}
+/**
+ * Options for HTTP requests.
+ *
+ * Platform-agnostic configuration for making HTTP requests with support
+ * for headers, body data, abort signals, timeouts, and credentials.
+ */
+interface HttpRequestOptions {
+  /** HTTP method (GET, POST, PATCH, DELETE, etc.) */
+  method?: string;
+  /** Request headers as key-value pairs */
+  headers?: Record<string, string>;
+  /** Request body data */
+  body?: unknown;
+  /** Abort signal for cancelling the request */
+  signal?: AbortSignalLike;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** Credentials mode for cross-origin requests */
+  credentials?: "include" | "omit" | "same-origin";
+}
+/**
+ * Platform-agnostic HTTP response interface.
+ *
+ * Provides a subset of the Web Response API that works across platforms.
+ */
+interface HttpResponse {
+  /** HTTP status code (200, 404, 500, etc.) */
+  status: number;
+  /** HTTP status text (OK, Not Found, etc.) */
+  statusText: string;
+  /** Response headers */
+  headers: HeadersLike;
+  /** True if status is in the 200-299 range */
+  ok: boolean;
+  /** Parses response body as JSON */
+  json(): Promise<unknown>;
+  /** Reads response body as text */
+  text(): Promise<string>;
+  /** Reads response body as ArrayBuffer */
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Configuration for HTTP connection pooling.
+ *
+ * Controls how connections are managed, reused, and maintained for optimal
+ * upload performance. Properly configured connection pooling can significantly
+ * improve upload speeds by reusing existing connections.
+ */
+interface ConnectionPoolConfig {
+  /** Maximum number of concurrent connections per host. Defaults to 8. */
+  maxConnectionsPerHost?: number;
+  /** Timeout for establishing new connections in milliseconds. Defaults to 20000. */
+  connectionTimeout?: number;
+  /** How long to keep idle connections alive in milliseconds. Defaults to 90000. */
+  keepAliveTimeout?: number;
+  /** Enable HTTP/2 for connection multiplexing. Defaults to true. */
+  enableHttp2?: boolean;
+  /** Automatically retry requests on connection errors. Defaults to true. */
+  retryOnConnectionError?: boolean;
+}
+/**
+ * Basic connection pool metrics.
+ *
+ * Provides insight into connection pool performance and efficiency.
+ */
+interface ConnectionMetrics {
+  /** Number of currently active connections */
+  activeConnections: number;
+  /** Total connections created since pool initialization */
+  totalConnections: number;
+  /** Ratio of connection reuse (0-1, higher is better) */
+  reuseRate: number;
+  /** Average time to establish connections in milliseconds */
+  averageConnectionTime: number;
+}
+/**
+ * Connection pool health assessment.
+ *
+ * Provides diagnostic information about connection pool health
+ * and recommendations for optimization.
+ */
+interface ConnectionHealth {
+  /** Overall health status */
+  status: "healthy" | "degraded" | "poor";
+  /** Health score from 0-100 (higher is better) */
+  score: number;
+  /** List of identified issues affecting performance */
+  issues: string[];
+  /** Recommendations for improving connection pool performance */
+  recommendations: string[];
+}
+/**
+ * HTTP/2 support and status information.
+ *
+ * Indicates whether HTTP/2 is available and being used,
+ * which can significantly improve upload performance through multiplexing.
+ */
+interface Http2Info {
+  /** Whether HTTP/2 is supported by the platform */
+  supported: boolean;
+  /** Whether HTTP/2 was detected on the server */
+  detected: boolean;
+  /** HTTP version being used (e.g., "2.0", "1.1") */
+  version: string;
+  /** Whether HTTP/2 multiplexing is actively being used */
+  multiplexingActive: boolean;
+}
+/**
+ * Detailed connection pool metrics with health diagnostics.
+ *
+ * Extends basic metrics with comprehensive diagnostic information
+ * for troubleshooting performance issues.
+ */
+interface DetailedConnectionMetrics extends ConnectionMetrics {
+  /** Connection pool health assessment */
+  health: ConnectionHealth;
+  /** Average requests per second */
+  requestsPerSecond: number;
+  /** Ratio of failed requests (0-1) */
+  errorRate: number;
+  /** Number of requests that timed out */
+  timeouts: number;
+  /** Number of requests that were retried */
+  retries: number;
+  /** Number of fast connections (likely reused) */
+  fastConnections: number;
+  /** Number of slow connections (likely new) */
+  slowConnections: number;
+  /** HTTP/2 support and usage information */
+  http2Info: Http2Info;
+}
+/**
+ * HTTP client interface that provides connection pooling capabilities
+ * for optimized upload performance.
+ */
+interface HttpClient {
+  /**
+   * Make an HTTP request using connection pooling
+   */
+  request(url: string, options?: HttpRequestOptions): Promise<HttpResponse>;
+  /**
+   * Get current connection pool metrics
+   */
+  getMetrics(): ConnectionMetrics;
+  /**
+   * Get detailed connection metrics with health diagnostics
+   */
+  getDetailedMetrics(): DetailedConnectionMetrics;
+  /**
+   * Reset connection pool and metrics
+   */
+  reset(): void;
+  /**
+   * Gracefully close all connections
+   */
+  close(): Promise<void>;
+  /**
+   * Warm up connections by making preflight requests
+   */
+  warmupConnections(urls: string[]): Promise<void>;
+}
+//#endregion
+//#region src/logger.d.ts
+/**
+ * Logger interface for Uploadista client operations.
+ *
+ * Provides structured logging capabilities for debugging upload progress,
+ * flow execution, and client operations. Platform implementations should
+ * provide their own logging functions (e.g., console.log, custom loggers).
+ *
+ * @example Using with console
+ * ```typescript
+ * const logger = createLogger(true, console.log);
+ * logger.log('Upload started');
+ * logger.warn('Retrying failed chunk');
+ * logger.error('Upload failed');
+ * ```
+ */
+type Logger = {
+  /**
+   * Log informational messages (e.g., upload progress, state changes)
+   */
+  log: (message: string) => void;
+  /**
+   * Log warning messages (e.g., retry attempts, degraded performance)
+   */
+  warn: (message: string) => void;
+  /**
+   * Log error messages (e.g., upload failures, network errors)
+   */
+  error: (message: string) => void;
+};
+/**
+ * Platform-specific logging function type.
+ *
+ * Accepts a message string and outputs it to the appropriate logging destination.
+ * This abstraction allows the client to work across different platforms
+ * (browser, Node.js, React Native) with their own logging mechanisms.
+ */
+type LogFunction = (message: string) => void;
+/**
+ * Creates a Logger instance with configurable output.
+ *
+ * This factory function creates a logger that can be enabled/disabled
+ * and customized with a platform-specific logging function.
+ *
+ * @param enabled - Whether logging is enabled. When false, all log calls are no-ops
+ * @param logFn - Optional custom logging function. Defaults to no-op. Pass console.log for browser/Node.js
+ * @returns A Logger instance with log, warn, and error methods
+ *
+ * @example Basic usage with console
+ * ```typescript
+ * const logger = createLogger(true, console.log);
+ * logger.log('Upload started');
+ * ```
+ *
+ * @example Disabled logger (no output)
+ * ```typescript
+ * const logger = createLogger(false);
+ * logger.log('This will not be logged');
+ * ```
+ *
+ * @example Custom logging function
+ * ```typescript
+ * const customLog = (msg: string) => {
+ *   // Send to analytics service
+ *   analytics.track('upload_log', { message: msg });
+ * };
+ * const logger = createLogger(true, customLog);
+ * ```
+ */
+declare function createLogger(enabled: boolean, logFn?: LogFunction): Logger;
+//#endregion
+//#region src/services/platform-service.d.ts
+/**
+ * Platform-agnostic service for platform-specific APIs
+ * Provides abstraction for timer functions and platform detection
+ */
+type Timeout = unknown;
+interface PlatformService {
+  /**
+   * Schedule a callback to run after a delay
+   */
+  setTimeout: (callback: () => void, ms: number | undefined) => Timeout;
+  /**
+   * Cancel a scheduled callback
+   */
+  clearTimeout: (id: Timeout) => void;
+  /**
+   * Check if we're in a browser environment
+   */
+  isBrowser: () => boolean;
+  /**
+   * Check if network is online
+   */
+  isOnline: () => boolean;
+  /**
+   * Check if a value is a File-like object
+   */
+  isFileLike: (value: unknown) => boolean;
+  /**
+   * Get file name from File-like object
+   */
+  getFileName: (file: unknown) => string | undefined;
+  /**
+   * Get file type from File-like object
+   */
+  getFileType: (file: unknown) => string | undefined;
+  /**
+   * Get file size from File-like object
+   */
+  getFileSize: (file: unknown) => number | undefined;
+  /**
+   * Get file last modified timestamp from File-like object
+   */
+  getFileLastModified: (file: unknown) => number | undefined;
+}
+/**
+ * Simple async wait utility
+ */
+declare function wait(platformService: PlatformService, ms: number): Promise<void>;
+//#endregion
+//#region src/auth/types.d.ts
+declare class BaseAuthManager {
+  private type;
+  constructor(type: "direct" | "saas" | "no-auth");
+  getType(): "direct" | "saas" | "no-auth";
+}
+/**
+ * Credentials that can be attached to HTTP requests.
+ * Supports headers and cookies for maximum flexibility.
+ */
+type RequestCredentials = {
+  /** HTTP headers to attach (e.g., Authorization, X-API-Key) */
+  headers?: Record<string, string>;
+  /** Cookies to attach (primarily for browser environments) */
+  cookies?: Record<string, string>;
+};
+/**
+ * Direct auth mode configuration.
+ * Users provide a function that returns credentials to attach to every request.
+ * This mode supports any authentication protocol (OAuth, JWT, sessions, API keys, etc.)
+ *
+ * @example Bearer token
+ * ```typescript
+ * {
+ *   mode: 'direct',
+ *   getCredentials: async () => ({
+ *     headers: {
+ *       'Authorization': `Bearer ${await getAccessToken()}`
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * @example API key
+ * ```typescript
+ * {
+ *   mode: 'direct',
+ *   getCredentials: () => ({
+ *     headers: {
+ *       'X-API-Key': process.env.API_KEY
+ *     }
+ *   })
+ * }
+ * ```
+ */
+type DirectAuthConfig = {
+  mode: "direct";
+  /**
+   * Function called before each HTTP request to obtain credentials.
+   * Can be async to support token refresh or other async operations.
+   * Should not throw - return empty object if credentials unavailable.
+   */
+  getCredentials?: () => RequestCredentials | Promise<RequestCredentials>;
+};
+/**
+ * SaaS auth mode configuration.
+ * Client requests JWT tokens from a user-controlled auth server,
+ * which validates credentials and issues tokens using a secure API key.
+ *
+ * Token exchange flow:
+ * 1. Client calls getCredentials() to get user credentials
+ * 2. Client sends credentials to authServerUrl
+ * 3. Auth server validates and returns JWT token
+ * 4. Client attaches token to uploadista engine requests
+ *
+ * @example
+ * ```typescript
+ * {
+ *   mode: 'saas',
+ *   authServerUrl: 'https://auth.myapp.com/token',
+ *   getCredentials: async () => ({
+ *     username: await getUsername(),
+ *     password: await getPassword()
+ *   })
+ * }
+ * ```
+ */
+type SaasAuthConfig = {
+  mode: "saas";
+  /**
+   * URL of the user's auth server that issues JWT tokens.
+   * Should be a GET endpoint that accepts client id and returns { token, expiresIn }.
+   */
+  authServerUrl: string;
+  /**
+   * Function that returns user credentials to send to the auth server.
+   * The auth server will validate these credentials before issuing a token.
+   * Credentials format is client id
+   */
+  clientId: string;
+};
+/**
+ * Authentication configuration for the uploadista client.
+ * Supports two modes:
+ * - Direct: Bring your own auth (any protocol)
+ * - SaaS: Standard JWT token exchange with auth server
+ *
+ * Use a discriminated union to ensure type safety - TypeScript will
+ * enforce that the correct fields are present for each mode.
+ */
+type AuthConfig = DirectAuthConfig | SaasAuthConfig;
+//#endregion
+//#region src/auth/direct-auth.d.ts
+/**
+ * Direct auth manager - handles credential attachment for "bring your own auth" mode.
+ *
+ * This manager calls the user-provided getCredentials() function before each request
+ * and attaches the returned credentials (headers, cookies) to the HTTP request.
+ *
+ * Supports any authentication protocol: OAuth, JWT, API keys, session cookies, etc.
+ */
+declare class DirectAuthManager extends BaseAuthManager {
+  private config;
+  private platformService;
+  private logger;
+  constructor(config: DirectAuthConfig, platformService: PlatformService, logger: Logger);
+  /**
+   * Attach credentials to an HTTP request by calling getCredentials() and
+   * merging the returned headers/cookies with the request.
+   *
+   * @param headers - Existing request headers
+   * @returns Updated headers with credentials attached
+   * @throws Error if getCredentials() throws or returns invalid data
+   */
+  attachCredentials(headers?: Record<string, string>): Promise<Record<string, string>>;
+  /**
+   * Validate that headers is a valid object with string keys and values
+   */
+  private validateHeaders;
+  /**
+   * Attach cookies to request headers.
+   * In browser environments, cookies are automatically handled by fetch().
+   * In Node.js, we need to manually add them to the Cookie header.
+   */
+  private attachCookies;
+}
+//#endregion
+//#region src/auth/no-auth.d.ts
+/**
+ * No-auth manager - pass-through implementation for backward compatibility.
+ *
+ * When no auth configuration is provided, this manager is used to maintain
+ * a consistent interface without adding any authentication to requests.
+ */
+declare class NoAuthManager extends BaseAuthManager {
+  constructor();
+  /**
+   * Pass through headers without modification.
+   *
+   * @param headers - Existing request headers
+   * @returns Same headers unchanged
+   */
+  attachCredentials(headers?: Record<string, string>): Promise<Record<string, string>>;
+  /**
+   * No-op for clearing tokens (NoAuthManager doesn't cache anything)
+   */
+  clearToken(_jobId: string): void;
+  /**
+   * No-op for clearing all tokens
+   */
+  clearAllTokens(): void;
+}
+//#endregion
+//#region src/auth/saas-auth.d.ts
+/**
+ * Token response from the auth server
+ */
+type TokenResponse = {
+  /** JWT token to use for authentication */
+  token: string;
+  /** Token expiration time in seconds (optional) */
+  expiresIn?: number;
+};
+/**
+ * SaaS auth manager - handles JWT token exchange with an auth server.
+ *
+ * Token exchange flow:
+ * 1. Client calls getCredentials() to get user credentials
+ * 2. Manager sends credentials to authServerUrl
+ * 3. Auth server validates credentials and returns JWT token
+ * 4. Manager caches token and attaches it to uploadista requests
+ * 5. Token is cached per job to minimize auth overhead
+ *
+ * Security: API keys are kept server-side in the auth server, never exposed to clients.
+ */
+declare class SaasAuthManager extends BaseAuthManager {
+  private config;
+  private httpClient;
+  /** Token cache: maps job ID to cached token */
+  private tokenCache;
+  /** Global token for requests without a specific job ID */
+  private globalToken;
+  constructor(config: SaasAuthConfig, httpClient: HttpClient);
+  /**
+   * Fetch a JWT token from the auth server using user credentials.
+   *
+   * @returns Token response with JWT and optional expiry
+   * @throws Error if auth server is unreachable or returns an error
+   */
+  fetchToken(): Promise<TokenResponse>;
+  /**
+   * Get a cached token for a specific job, or fetch a new one if not cached.
+   *
+   * @param jobId - Optional job ID to cache token for specific job
+   * @returns Cached or newly fetched token
+   */
+  private getOrFetchToken;
+  /**
+   * Check if a cached token is expired.
+   * Adds a 60-second buffer to avoid using tokens that are about to expire.
+   */
+  private isTokenExpired;
+  /**
+   * Attach JWT token to an HTTP request as Authorization Bearer header.
+   *
+   * @param headers - Existing request headers
+   * @param jobId - Optional job ID to use cached token for specific job
+   * @returns Updated headers with Authorization header
+   * @throws Error if token fetch fails
+   */
+  attachToken(headers?: Record<string, string>, jobId?: string): Promise<Record<string, string>>;
+  /**
+   * Clear cached token for a specific job.
+   * Should be called when a job completes to free memory.
+   *
+   * @param jobId - Job ID to clear token for
+   */
+  clearToken(jobId: string): void;
+  /**
+   * Clear all cached tokens.
+   * Useful for logout or when switching users.
+   */
+  clearAllTokens(): void;
+  /**
+   * Get cache statistics for debugging and monitoring.
+   */
+  getCacheStats(): {
+    cachedJobCount: number;
+    hasGlobalToken: boolean;
+  };
+}
+//#endregion
+//#region src/auth/auth-http-client.d.ts
+/**
+ * Union type of all auth managers
+ */
+type AuthManager = DirectAuthManager | SaasAuthManager | NoAuthManager;
+//#endregion
+//#region src/network-monitor.d.ts
+/**
+ * Assessment of current network conditions based on upload performance.
+ *
+ * Used by smart chunking algorithms to adapt chunk sizes based on network quality.
+ */
+interface NetworkCondition {
+  /**
+   * Classification of network speed and stability:
+   * - "slow": Average speed below slowThreshold (default 50 KB/s)
+   * - "fast": Average speed above fastThreshold (default 5 MB/s)
+   * - "unstable": High variance in upload speeds
+   * - "unknown": Insufficient data to determine condition
+   */
+  type: "slow" | "fast" | "unstable" | "unknown";
+  /**
+   * Confidence level in the assessment (0-1).
+   * Higher values indicate more samples and more reliable assessment.
+   */
+  confidence: number;
+}
+/**
+ * Aggregated network performance metrics.
+ *
+ * Provides a comprehensive view of upload performance over time,
+ * useful for debugging connectivity issues and optimizing upload strategies.
+ */
+interface NetworkMetrics {
+  /** Average upload speed in bytes per second */
+  averageSpeed: number;
+  /** Average network latency in milliseconds */
+  latency: number;
+  /** Ratio of successful uploads (0-1) */
+  successRate: number;
+  /** Ratio of failed uploads (0-1) */
+  errorRate: number;
+  /** Total number of upload requests made */
+  totalRequests: number;
+  /** Total bytes uploaded successfully */
+  totalBytes: number;
+  /** Total time spent uploading in milliseconds */
+  totalTime: number;
+}
+/**
+ * Individual upload sample for network analysis.
+ *
+ * Each successful or failed upload is recorded as a sample,
+ * which is used to calculate network metrics and conditions.
+ */
+interface UploadSample {
+  /** Size of the uploaded chunk in bytes */
+  size: number;
+  /** Time taken to upload in milliseconds */
+  duration: number;
+  /** Whether the upload succeeded */
+  success: boolean;
+  /** Unix timestamp when the upload occurred */
+  timestamp: number;
+  /** Optional network latency measurement in milliseconds */
+  latency?: number;
+}
+/**
+ * Configuration options for NetworkMonitor.
+ *
+ * Controls how network conditions are assessed and how upload samples
+ * are analyzed to determine optimal chunking strategies.
+ */
+interface NetworkMonitorConfig {
+  /** Maximum number of samples to keep in memory. Defaults to 100. */
+  maxSamples?: number;
+  /** Smoothing factor for exponential moving average (0-1). Defaults to 0.1. */
+  smoothingFactor?: number;
+  /** Minimum samples required before assessing network condition. Defaults to 5. */
+  minSamplesForCondition?: number;
+  /** Upload speed threshold for "slow" classification in bytes/second. Defaults to 50 KB/s. */
+  slowThreshold?: number;
+  /** Upload speed threshold for "fast" classification in bytes/second. Defaults to 5 MB/s. */
+  fastThreshold?: number;
+  /** Coefficient of variation threshold for "unstable" classification. Defaults to 0.5. */
+  unstableThreshold?: number;
+}
+/**
+ * Monitors network performance during uploads to enable adaptive chunking.
+ *
+ * Tracks upload samples over time and analyzes them to determine network conditions
+ * (slow, fast, unstable). This information is used by smart chunking algorithms to
+ * dynamically adjust chunk sizes for optimal upload performance.
+ *
+ * The monitor maintains a rolling window of recent samples and calculates various
+ * metrics including average speed, latency, success rate, and throughput stability.
+ *
+ * @example Basic usage with smart chunking
+ * ```typescript
+ * const monitor = new NetworkMonitor({
+ *   maxSamples: 100,
+ *   slowThreshold: 50 * 1024, // 50 KB/s
+ *   fastThreshold: 5 * 1024 * 1024, // 5 MB/s
+ * });
+ *
+ * // Record each upload
+ * monitor.recordUpload(
+ *   chunkSize,    // bytes
+ *   duration,     // milliseconds
+ *   true,         // success
+ *   latency       // optional latency
+ * );
+ *
+ * // Get current network condition
+ * const condition = monitor.getNetworkCondition();
+ * if (condition.type === 'slow') {
+ *   // Use smaller chunks
+ *   chunkSize = 256 * 1024;
+ * } else if (condition.type === 'fast') {
+ *   // Use larger chunks
+ *   chunkSize = 5 * 1024 * 1024;
+ * }
+ * ```
+ *
+ * @example Monitoring network metrics
+ * ```typescript
+ * const monitor = new NetworkMonitor();
+ *
+ * // After some uploads
+ * const metrics = monitor.getCurrentMetrics();
+ * console.log(`Average speed: ${metrics.averageSpeed / 1024} KB/s`);
+ * console.log(`Success rate: ${metrics.successRate * 100}%`);
+ * console.log(`Average latency: ${metrics.latency}ms`);
+ * ```
+ */
+declare class NetworkMonitor {
+  private samples;
+  private config;
+  private _currentMetrics;
+  /**
+   * Creates a new NetworkMonitor instance.
+   *
+   * @param config - Optional configuration for thresholds and sample management
+   */
+  constructor(config?: NetworkMonitorConfig);
+  /**
+   * Adds a raw upload sample to the monitor.
+   *
+   * This is called internally by recordUpload but can also be used
+   * to add pre-constructed samples for testing or custom tracking.
+   *
+   * @param sample - The upload sample to add
+   */
+  addSample(sample: UploadSample): void;
+  /**
+   * Records an upload operation for network analysis.
+   *
+   * This is the primary method for tracking upload performance. Each chunk upload
+   * should be recorded to build an accurate picture of network conditions.
+   *
+   * @param size - Size of the uploaded chunk in bytes
+   * @param duration - Time taken to upload in milliseconds
+   * @param success - Whether the upload succeeded
+   * @param latency - Optional network latency measurement in milliseconds
+   *
+   * @example Recording successful upload
+   * ```typescript
+   * const startTime = Date.now();
+   * await uploadChunk(data);
+   * const duration = Date.now() - startTime;
+   * monitor.recordUpload(data.length, duration, true);
+   * ```
+   *
+   * @example Recording failed upload
+   * ```typescript
+   * try {
+   *   const startTime = Date.now();
+   *   await uploadChunk(data);
+   *   monitor.recordUpload(data.length, Date.now() - startTime, true);
+   * } catch (error) {
+   *   monitor.recordUpload(data.length, Date.now() - startTime, false);
+   * }
+   * ```
+   */
+  recordUpload(size: number, duration: number, success: boolean, latency?: number): void;
+  /**
+   * Returns the current network metrics.
+   *
+   * Provides aggregated statistics about all recorded uploads including
+   * average speed, latency, success rate, and totals.
+   *
+   * @returns A snapshot of current network performance metrics
+   *
+   * @example
+   * ```typescript
+   * const metrics = monitor.getCurrentMetrics();
+   * console.log(`Speed: ${(metrics.averageSpeed / 1024).toFixed(2)} KB/s`);
+   * console.log(`Success: ${(metrics.successRate * 100).toFixed(1)}%`);
+   * console.log(`Latency: ${metrics.latency.toFixed(0)}ms`);
+   * ```
+   */
+  getCurrentMetrics(): NetworkMetrics;
+  /**
+   * Analyzes recent upload samples to determine current network condition.
+   *
+   * Uses statistical analysis (coefficient of variation, average speed) to classify
+   * the network as slow, fast, unstable, or unknown. The confidence level indicates
+   * how reliable the assessment is based on the number of samples collected.
+   *
+   * @returns Current network condition with confidence level
+   *
+   * @example Adaptive chunking based on network condition
+   * ```typescript
+   * const condition = monitor.getNetworkCondition();
+   *
+   * if (condition.confidence > 0.7) {
+   *   switch (condition.type) {
+   *     case 'fast':
+   *       chunkSize = 10 * 1024 * 1024; // 10MB
+   *       break;
+   *     case 'slow':
+   *       chunkSize = 256 * 1024; // 256KB
+   *       break;
+   *     case 'unstable':
+   *       chunkSize = 1 * 1024 * 1024; // 1MB, conservative
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  getNetworkCondition(): NetworkCondition;
+  /**
+   * Calculates the optimal upload throughput based on recent successful uploads.
+   *
+   * Uses a weighted average that gives more weight to recent samples,
+   * providing a responsive measure of current network capacity.
+   *
+   * @returns Optimal throughput in bytes per second, or 0 if no successful samples
+   *
+   * @example Using for chunk size calculation
+   * ```typescript
+   * const throughput = monitor.getOptimalThroughput();
+   * // Target 1 second per chunk
+   * const optimalChunkSize = Math.min(throughput, MAX_CHUNK_SIZE);
+   * ```
+   */
+  getOptimalThroughput(): number;
+  /**
+   * Resets all samples and metrics to initial state.
+   *
+   * Useful when network conditions change significantly or when
+   * starting a new upload session.
+   *
+   * @example Resetting between uploads
+   * ```typescript
+   * // Complete first upload
+   * await uploadFile1();
+   *
+   * // Reset metrics before starting a new upload
+   * monitor.reset();
+   * await uploadFile2();
+   * ```
+   */
+  reset(): void;
+  private getRecentSuccessfulSamples;
+  private updateMetrics;
+  private createEmptyMetrics;
+}
+//#endregion
+//#region src/services/checksum-service.d.ts
+interface ChecksumService {
+  computeChecksum(data: Uint8Array): Promise<string>;
+}
+//#endregion
+//#region src/services/file-reader-service.d.ts
+/**
+ * Platform-agnostic file reader service
+ */
+type SliceResult = {
+  done: true;
+  value: null;
+  size: null;
+} | {
+  done: boolean;
+  value: Uint8Array;
+  size: number;
+};
+interface FileSource {
+  input: unknown;
+  size: number | null;
+  name: string | null;
+  type: string | null;
+  lastModified: number | null;
+  slice: (start: number, end: number) => Promise<SliceResult>;
+  close: () => void;
+}
+interface FileReaderService<UploadInput> {
+  /**
+   * Open a file for reading
+   */
+  openFile(input: UploadInput, chunkSize: number): Promise<FileSource>;
+}
+interface Base64Service {
+  /**
+   * Encode data to base64
+   */
+  toBase64(data: ArrayBuffer): string;
+  /**
+   * Decode base64 to data
+   */
+  fromBase64(data: string): ArrayBuffer;
+}
+//#endregion
+//#region src/services/fingerprint-service.d.ts
+interface FingerprintService<UploadInput> {
+  computeFingerprint(file: UploadInput, endpoint: string): Promise<string | null>;
+}
+//#endregion
+//#region src/services/id-generation-service.d.ts
+/**
+ * Platform-agnostic ID generation service
+ */
+interface IdGenerationService {
+  /**
+   * Generate a unique identifier
+   */
+  generate(): string;
+}
+//#endregion
+//#region src/services/websocket-service.d.ts
+/**
+ * Platform-agnostic WebSocket interface
+ */
+interface WebSocketEventMap {
+  open: unknown;
+  close: unknown;
+  error: unknown;
+  message: unknown;
+}
+interface WebSocketLike {
+  readyState: number;
+  readonly CONNECTING: number;
+  readonly OPEN: number;
+  readonly CLOSING: number;
+  readonly CLOSED: number;
+  onopen: (() => void) | null;
+  onclose: ((event: {
+    code: number;
+    reason: string;
+  }) => void) | null;
+  onerror: ((event: {
+    message: string;
+  }) => void) | null;
+  onmessage: ((event: {
+    data: string;
+  }) => void) | null;
+  send(data: string | Uint8Array): void;
+  close(code?: number, reason?: string): void;
+}
+interface WebSocketFactory {
+  /**
+   * Create a WebSocket connection to the given URL
+   */
+  create(url: string): WebSocketLike;
+}
+//#endregion
+//#region src/smart-chunker.d.ts
+interface DatastoreConstraints {
+  minChunkSize: number;
+  maxChunkSize: number;
+  optimalChunkSize: number;
+  requiresOrderedChunks?: boolean;
+}
+interface SmartChunkerConfig {
+  enabled?: boolean;
+  fallbackChunkSize?: number;
+  minChunkSize?: number;
+  maxChunkSize?: number;
+  initialChunkSize?: number;
+  targetUtilization?: number;
+  adaptationRate?: number;
+  conservativeMode?: boolean;
+  connectionPoolingAware?: boolean;
+  datastoreConstraints?: DatastoreConstraints;
+}
+//#endregion
+//#region src/services/storage-service.d.ts
+/**
+ * Platform-agnostic storage service for persisting upload state
+ */
+interface StorageService {
+  /**
+   * Get an item from storage
+   */
+  getItem(key: string): Promise<string | null>;
+  /**
+   * Set an item in storage
+   */
+  setItem(key: string, value: string): Promise<void>;
+  /**
+   * Remove an item from storage
+   */
+  removeItem(key: string): Promise<void>;
+  /**
+   * Get all items in storage
+   */
+  findAll(): Promise<Record<string, string>>;
+  /**
+   * Find items by prefix
+   */
+  find(prefix: string): Promise<Record<string, string>>;
+}
+//#endregion
+//#region src/types/previous-upload.d.ts
+type PreviousUpload = {
+  size: number | null;
+  metadata: {
+    [key: string]: string | number | boolean;
+  };
+  creationTime: string;
+  uploadId?: string;
+  parallelUploadUrls?: string[];
+  clientStorageKey: string;
+};
+declare const previousUploadSchema: z.ZodObject<{
+  size: z.ZodNullable<z.ZodNumber>;
+  metadata: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  creationTime: z.ZodString;
+  uploadId: z.ZodOptional<z.ZodString>;
+  parallelUploadUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  clientStorageKey: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+//#region src/storage/client-storage.d.ts
+/**
+ * Client-side storage interface for managing upload resumption data.
+ *
+ * Provides methods to store, retrieve, and manage previous upload information,
+ * enabling the client to resume interrupted uploads from where they left off.
+ * This is essential for implementing reliable upload resumption across sessions.
+ *
+ * Storage keys are namespaced with "uploadista::" prefix and organized by
+ * file fingerprint to allow quick lookup of resumable uploads.
+ *
+ * @example Finding resumable uploads
+ * ```typescript
+ * const storage = createClientStorage(localStorage);
+ *
+ * // Find all previous uploads
+ * const allUploads = await storage.findAllUploads();
+ *
+ * // Find uploads for a specific file
+ * const fingerprint = await computeFingerprint(file);
+ * const matches = await storage.findUploadsByFingerprint(fingerprint);
+ *
+ * if (matches.length > 0) {
+ *   // Resume from the most recent upload
+ *   const uploadId = matches[0].uploadId;
+ *   await resumeUpload(uploadId);
+ * }
+ * ```
+ */
+type ClientStorage = {
+  /**
+   * Retrieves all stored upload records from client storage.
+   *
+   * Useful for debugging or displaying a list of resumable uploads to the user.
+   *
+   * @returns Array of all previous upload records
+   */
+  findAllUploads: () => Promise<PreviousUpload[]>;
+  /**
+   * Finds previous upload records matching a specific file fingerprint.
+   *
+   * This is the primary method for discovering resumable uploads.
+   * Returns uploads sorted by most recent first.
+   *
+   * @param fingerprint - The file fingerprint to search for
+   * @returns Array of matching upload records, or empty array if none found
+   *
+   * @example
+   * ```typescript
+   * const fingerprint = await computeFingerprint(file);
+   * const previous = await storage.findUploadsByFingerprint(fingerprint);
+   *
+   * if (previous.length > 0) {
+   *   console.log(`Found ${previous.length} resumable uploads`);
+   *   console.log(`Last upload was ${previous[0].offset} bytes`);
+   * }
+   * ```
+   */
+  findUploadsByFingerprint: (fingerprint: string) => Promise<PreviousUpload[]>;
+  /**
+   * Removes an upload record from client storage.
+   *
+   * Called after an upload completes successfully or is explicitly cancelled
+   * to clean up storage and prevent stale resumption attempts.
+   *
+   * @param clientStorageKey - The storage key returned by addUpload
+   *
+   * @example Cleanup after successful upload
+   * ```typescript
+   * await uploadFile(file);
+   * await storage.removeUpload(storageKey);
+   * ```
+   */
+  removeUpload: (clientStorageKey: string) => Promise<void>;
+  /**
+   * Stores an upload record in client storage for future resumption.
+   *
+   * Creates a namespaced storage key that includes the file fingerprint,
+   * making it easy to find resumable uploads later.
+   *
+   * @param fingerprint - File fingerprint for organizing uploads
+   * @param upload - Upload metadata to store (uploadId, offset, etc.)
+   * @param options - Options object containing ID generation service
+   * @returns The storage key that can be used to remove this upload later, or undefined if storage failed
+   *
+   * @example Storing upload progress
+   * ```typescript
+   * const fingerprint = await computeFingerprint(file);
+   * const key = await storage.addUpload(
+   *   fingerprint,
+   *   { uploadId: 'abc123', offset: 1024000 },
+   *   { generateId: idService }
+   * );
+   *
+   * // Later, remove when complete
+   * if (key) await storage.removeUpload(key);
+   * ```
+   */
+  addUpload: (fingerprint: string, upload: PreviousUpload, {
+    generateId
+  }: {
+    generateId: IdGenerationService;
+  }) => Promise<string | undefined>;
+};
+/**
+ * Creates a ClientStorage instance using the provided storage service.
+ *
+ * This factory function wraps a platform-specific StorageService (e.g., localStorage,
+ * AsyncStorage) with the ClientStorage interface, providing a consistent API
+ * for upload resumption across different platforms.
+ *
+ * @param storageService - Platform-specific storage implementation
+ * @returns ClientStorage instance for managing upload records
+ *
+ * @example Browser with localStorage
+ * ```typescript
+ * const storage = createClientStorage({
+ *   find: async (prefix) => {
+ *     const items: Record<string, string> = {};
+ *     for (let i = 0; i < localStorage.length; i++) {
+ *       const key = localStorage.key(i);
+ *       if (key?.startsWith(prefix)) {
+ *         items[key] = localStorage.getItem(key) || '';
+ *       }
+ *     }
+ *     return items;
+ *   },
+ *   setItem: async (key, value) => localStorage.setItem(key, value),
+ *   removeItem: async (key) => localStorage.removeItem(key),
+ * });
+ * ```
+ *
+ * @example React Native with AsyncStorage
+ * ```typescript
+ * const storage = createClientStorage({
+ *   find: async (prefix) => {
+ *     const keys = await AsyncStorage.getAllKeys();
+ *     const matching = keys.filter(k => k.startsWith(prefix));
+ *     const pairs = await AsyncStorage.multiGet(matching);
+ *     return Object.fromEntries(pairs);
+ *   },
+ *   setItem: async (key, value) => AsyncStorage.setItem(key, value),
+ *   removeItem: async (key) => AsyncStorage.removeItem(key),
+ * });
+ * ```
+ */
+declare function createClientStorage(storageService: StorageService): ClientStorage;
+//#endregion
+//#region src/types/flow-upload-config.d.ts
+/**
+ * Configuration for uploading a file through a flow pipeline.
+ *
+ * Flows enable processing uploaded files through a sequence of transformation
+ * nodes (e.g., image resize, format conversion, validation) before final storage.
+ *
+ * @example Basic flow upload
+ * ```typescript
+ * const config: FlowUploadConfig = {
+ *   flowId: 'image-optimization',
+ *   storageId: 'processed-images',
+ * };
+ *
+ * await client.uploadWithFlow(file, config, {
+ *   onProgress: (progress) => console.log(`${progress}%`),
+ *   onSuccess: (result) => console.log('Processed:', result),
+ * });
+ * ```
+ *
+ * @example With specific output node
+ * ```typescript
+ * const config: FlowUploadConfig = {
+ *   flowId: 'multi-format-conversion',
+ *   storageId: 'images',
+ *   outputNodeId: 'webp-output', // Get WebP version instead of first output
+ *   metadata: {
+ *     userId: '123',
+ *     album: 'vacation-2024',
+ *   },
+ * };
+ * ```
+ */
+type FlowUploadConfig = {
+  /** Unique identifier of the flow to execute */
+  flowId: string;
+  /** Storage backend where flow outputs will be saved */
+  storageId: string;
+  /**
+   * Specify which output node to use for single-value callbacks like onSuccess.
+   *
+   * For flows with multiple output nodes, this determines which output
+   * is passed to the onSuccess callback. If not specified, uses the first
+   * output node. The onFlowComplete callback receives all outputs regardless.
+   */
+  outputNodeId?: string;
+  /**
+   * Additional metadata to attach to the upload and flow execution.
+   *
+   * This metadata is stored with the upload and can be used for tracking,
+   * filtering, or providing context to flow nodes.
+   */
+  metadata?: Record<string, string>;
+};
+//#endregion
+//#region src/client/uploadista-api.d.ts
+/**
+ * Response from upload-related API calls.
+ *
+ * Contains the upload metadata and HTTP status code.
+ */
+type UploadistaUploadResponse = {
+  /** Upload file metadata, undefined if request failed */
+  upload?: UploadFile;
+  /** HTTP status code */
+  status: number;
+};
+/**
+ * Response from delete upload API call.
+ */
+type UploadistaDeleteUploadResponse = {
+  /** Successfully deleted (no content) */
+  status: 204;
+} | {
+  /** Other status codes (e.g., 404, 500) */
+  status: number;
+};
+/**
+ * Response from flow retrieval API call.
+ */
+type FlowResponse = {
+  /** HTTP status code */
+  status: number;
+  /** Flow configuration and metadata */
+  flow: FlowData;
+};
+/**
+ * Unified Uploadista API interface combining upload and flow operations.
+ *
+ * This low-level API provides direct access to server endpoints for:
+ * - Upload CRUD operations (create, get, delete, patch chunks)
+ * - Flow operations (get, run, continue)
+ * - Job status tracking
+ * - WebSocket connections for real-time updates
+ * - Server capabilities discovery
+ * - Connection pooling metrics
+ *
+ * Most applications should use the higher-level {@link UploadistaClient} instead,
+ * which provides a more convenient interface with automatic retry, resumption,
+ * and smart chunking.
+ *
+ * @example Direct API usage (advanced)
+ * ```typescript
+ * const api = createUploadistaApi(baseUrl, basePath, {
+ *   httpClient,
+ *   logger,
+ *   authManager,
+ *   webSocketFactory,
+ * });
+ *
+ * // Create an upload
+ * const { upload } = await api.createUpload({
+ *   storageId: 'my-storage',
+ *   size: 1024000,
+ *   metadata: { filename: 'test.txt' },
+ * });
+ *
+ * // Upload a chunk
+ * const chunk = new Uint8Array(1024);
+ * await api.uploadChunk(upload.id, chunk, {});
+ *
+ * // Check status
+ * const { upload: updated } = await api.getUpload(upload.id);
+ * console.log(`Progress: ${updated.offset}/${updated.size}`);
+ * ```
+ *
+ * @see {@link createUploadistaApi} for creating an instance
+ */
+type UploadistaApi = {
+  /**
+   * Retrieves upload metadata and current status.
+   *
+   * @param uploadId - Unique upload identifier
+   * @returns Upload metadata including current offset and status
+   * @throws {UploadistaError} If upload not found or request fails
+   */
+  getUpload: (uploadId: string) => Promise<UploadistaUploadResponse>;
+  /**
+   * Deletes an upload and its associated data.
+   *
+   * @param uploadId - Unique upload identifier
+   * @returns Response with status 204 on success
+   * @throws {UploadistaError} If upload not found or deletion fails
+   */
+  deleteUpload: (uploadId: string) => Promise<UploadistaDeleteUploadResponse>;
+  /**
+   * Creates a new upload on the server.
+   *
+   * @param body - Upload configuration including storageId, size, and metadata
+   * @returns Created upload metadata with unique ID
+   * @throws {UploadistaError} If creation fails or validation errors occur
+   */
+  createUpload: (body: InputFile) => Promise<UploadistaUploadResponse>;
+  /**
+   * Uploads a chunk of data to an existing upload.
+   *
+   * @param uploadId - Upload identifier to append data to
+   * @param data - Chunk data bytes, or null to finalize without data
+   * @param options - Upload options including abort controller and progress callback
+   * @returns Updated upload metadata with new offset
+   * @throws {UploadistaError} If chunk upload fails or upload is locked
+   */
+  uploadChunk: (uploadId: string, data: Uint8Array | null, options: {
+    abortController?: AbortControllerLike;
+    onProgress?: (bytes: number, total: number) => void;
+  }) => Promise<UploadistaUploadResponse>;
+  /**
+   * Retrieves flow configuration and metadata.
+   *
+   * @param flowId - Unique flow identifier
+   * @returns Flow configuration including nodes and edges
+   * @throws {UploadistaError} If flow not found
+   */
+  getFlow: (flowId: string) => Promise<FlowResponse>;
+  /**
+   * Executes a flow with the provided inputs.
+   *
+   * @param flowId - Flow to execute
+   * @param storageId - Storage backend to use for flow outputs
+   * @param inputs - Input data for flow nodes (keyed by node ID)
+   * @returns Job metadata including job ID and initial state
+   * @throws {UploadistaError} If flow execution fails or inputs are invalid
+   */
+  runFlow: (flowId: string, storageId: string, inputs: Record<string, unknown>) => Promise<{
+    status: number;
+    job: FlowJob;
+  }>;
+  /**
+   * Continues a paused flow execution with new data.
+   *
+   * Used for interactive flows that wait for user input or external data.
+   *
+   * @param jobId - Job identifier for the paused flow
+   * @param nodeId - Node ID where execution should continue
+   * @param newData - Data to provide to the node
+   * @param options - Options including content type for binary data
+   * @returns Updated job metadata
+   * @throws {UploadistaError} If job not found or continuation fails
+   */
+  continueFlow: (jobId: string, nodeId: string, newData: unknown, options?: {
+    contentType?: "application/json" | "application/octet-stream";
+  }) => Promise<FlowJob>;
+  /**
+   * Retrieves current job status and outputs.
+   *
+   * Works for both upload and flow jobs.
+   *
+   * @param jobId - Job identifier
+   * @returns Job metadata including state, progress, and outputs
+   * @throws {UploadistaError} If job not found
+   */
+  getJobStatus: (jobId: string) => Promise<FlowJob>;
+  /**
+   * Opens a WebSocket connection for upload progress events.
+   *
+   * @param uploadId - Upload to monitor
+   * @returns WebSocket instance for receiving real-time updates
+   */
+  openUploadWebSocket: (uploadId: string) => Promise<WebSocketLike>;
+  /**
+   * Opens a WebSocket connection for flow job events.
+   *
+   * @param jobId - Flow job to monitor
+   * @returns WebSocket instance for receiving real-time updates
+   */
+  openFlowWebSocket: (jobId: string) => Promise<WebSocketLike>;
+  /**
+   * Closes a WebSocket connection.
+   *
+   * @param ws - WebSocket instance to close
+   */
+  closeWebSocket: (ws: WebSocketLike) => void;
+  /**
+   * Returns current connection pool metrics.
+   *
+   * @returns Basic metrics including active connections and reuse rate
+   */
+  getConnectionMetrics: () => ConnectionMetrics;
+  /**
+   * Returns detailed connection pool metrics with health diagnostics.
+   *
+   * @returns Comprehensive metrics including health status and recommendations
+   */
+  getDetailedConnectionMetrics: () => DetailedConnectionMetrics;
+  /**
+   * Pre-warms connections to the specified URLs.
+   *
+   * Useful for reducing latency on first upload by establishing
+   * connections ahead of time.
+   *
+   * @param urls - URLs to pre-connect to
+   */
+  warmupConnections: (urls: string[]) => Promise<void>;
+  /**
+   * Fetches server capabilities for the specified storage backend.
+   *
+   * Returns information about chunk size constraints, supported features,
+   * and storage-specific requirements. Falls back to default capabilities
+   * if the request fails.
+   *
+   * @param storageId - Storage backend identifier
+   * @returns Storage capabilities including chunk size limits
+   */
+  getCapabilities: (storageId: string) => Promise<DataStoreCapabilities>;
+};
+/**
+ * Creates an Uploadista API instance for direct server communication.
+ *
+ * This factory creates a low-level API client that handles:
+ * - HTTP requests to upload and flow endpoints
+ * - Authentication via AuthManager (optional)
+ * - WebSocket connections for real-time updates
+ * - Error mapping from server to client error types
+ * - Connection pooling and metrics
+ *
+ * Most applications should use {@link createUploadistaClient} instead,
+ * which wraps this API with higher-level features like automatic retry,
+ * resumption, and smart chunking.
+ *
+ * @param baseURL - Base URL of the Uploadista server (e.g., "https://upload.example.com")
+ * @param uploadistBasePath - Base path for endpoints, typically "uploadista"
+ * @param options - Configuration object
+ * @param options.httpClient - HTTP client for making requests
+ * @param options.logger - Optional logger for debugging
+ * @param options.authManager - Optional authentication manager
+ * @param options.webSocketFactory - Factory for creating WebSocket connections
+ * @returns UploadistaApi instance
+ *
+ * @example Basic API instance
+ * ```typescript
+ * import { createUploadistaApi } from '@uploadista/client-core';
+ *
+ * const api = createUploadistaApi(
+ *   'https://upload.example.com',
+ *   'uploadista',
+ *   {
+ *     httpClient: myHttpClient,
+ *     logger: console,
+ *     webSocketFactory: {
+ *       create: (url) => new WebSocket(url),
+ *     },
+ *   }
+ * );
+ *
+ * // Use the API directly
+ * const { upload } = await api.createUpload({
+ *   storageId: 'my-storage',
+ *   size: 1024,
+ * });
+ * ```
+ *
+ * @example With authentication
+ * ```typescript
+ * const authManager = new DirectAuthManager(authConfig, platformService, logger);
+ *
+ * const api = createUploadistaApi(baseUrl, 'uploadista', {
+ *   httpClient,
+ *   logger,
+ *   authManager, // Automatically adds auth headers to requests
+ *   webSocketFactory,
+ * });
+ * ```
+ *
+ * @see {@link UploadistaApi} for the API interface
+ * @see {@link createUploadistaClient} for the high-level client
+ */
+declare function createUploadistaApi(baseURL: string, uploadistBasePath: string, {
+  httpClient: baseHttpClient,
+  logger,
+  authManager,
+  webSocketFactory
+}: {
+  httpClient: HttpClient;
+  logger?: Logger;
+  authManager?: AuthManager;
+  webSocketFactory: WebSocketFactory;
+}): UploadistaApi;
+//#endregion
+//#region src/error.d.ts
+/**
+ * Specific error types that can occur during upload and flow operations.
+ *
+ * These error names provide fine-grained categorization of failures,
+ * allowing applications to implement targeted error handling and recovery strategies.
+ *
+ * @example Error handling by type
+ * ```typescript
+ * try {
+ *   await client.upload(file);
+ * } catch (error) {
+ *   if (error instanceof UploadistaError) {
+ *     if (error.isNetworkError()) {
+ *       // Retry network-related failures
+ *       console.log('Network issue, retrying...');
+ *     } else if (error.name === 'UPLOAD_NOT_FOUND') {
+ *       // Handle missing upload
+ *       console.log('Upload not found, starting fresh');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type UploadistaErrorName = "UPLOAD_SIZE_NOT_SPECIFIED" | "NETWORK_ERROR" | "NETWORK_UNEXPECTED_RESPONSE" | "UPLOAD_CHUNK_FAILED" | "WRONG_UPLOAD_SIZE" | "UPLOAD_LOCKED" | "UPLOAD_NOT_FOUND" | "CREATE_UPLOAD_FAILED" | "DELETE_UPLOAD_FAILED" | "PARALLEL_SEGMENT_CREATION_FAILED" | "PARALLEL_SEGMENT_UPLOAD_FAILED" | "FLOW_NOT_FOUND" | "FLOW_INIT_FAILED" | "FLOW_RUN_FAILED" | "FLOW_CONTINUE_FAILED" | "FLOW_UNEXPECTED_STATE" | "FLOW_INCOMPATIBLE" | "FLOW_NO_UPLOAD_ID" | "FLOW_TIMEOUT" | "FLOW_FINALIZE_FAILED" | "JOB_NOT_FOUND" | "WEBSOCKET_AUTH_FAILED";
+/**
+ * Custom error class for all Uploadista client operations.
+ *
+ * Extends the standard Error class with additional context including
+ * typed error names, HTTP status codes, and underlying error causes.
+ * This allows for precise error handling and debugging.
+ *
+ * @example Basic error handling
+ * ```typescript
+ * try {
+ *   await client.upload(file);
+ * } catch (error) {
+ *   if (error instanceof UploadistaError) {
+ *     console.log(`Error: ${error.name} - ${error.message}`);
+ *     console.log(`HTTP Status: ${error.status}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Network error detection
+ * ```typescript
+ * try {
+ *   await client.upload(file);
+ * } catch (error) {
+ *   if (error instanceof UploadistaError && error.isNetworkError()) {
+ *     // Implement retry logic for network failures
+ *     await retryWithBackoff(() => client.upload(file));
+ *   }
+ * }
+ * ```
+ */
+declare class UploadistaError extends Error {
+  /**
+   * Typed error name indicating the specific type of failure
+   */
+  name: UploadistaErrorName;
+  /**
+   * Human-readable error message describing what went wrong
+   */
+  message: string;
+  /**
+   * The underlying error that caused this failure, if any
+   */
+  cause: Error | undefined;
+  /**
+   * HTTP status code from the server response, if applicable
+   */
+  status: number | undefined;
+  /**
+   * Creates a new UploadistaError instance.
+   *
+   * @param options - Error configuration
+   * @param options.name - Typed error name for categorization
+   * @param options.message - Descriptive error message
+   * @param options.cause - Optional underlying error that caused this failure
+   * @param options.status - Optional HTTP status code from server response
+   */
+  constructor({
+    name,
+    message,
+    cause,
+    status
+  }: {
+    name: UploadistaErrorName;
+    message: string;
+    cause?: Error;
+    status?: number;
+  });
+  /**
+   * Checks if this error is related to network connectivity issues.
+   *
+   * Network errors are typically transient and may succeed on retry,
+   * making them good candidates for automatic retry logic.
+   *
+   * @returns True if this is a network-related error
+   *
+   * @example
+   * ```typescript
+   * if (error.isNetworkError()) {
+   *   // Safe to retry
+   *   await retry(() => uploadChunk());
+   * }
+   * ```
+   */
+  isNetworkError(): boolean;
+}
+//#endregion
+//#region src/services/service-container.d.ts
+/**
+ * Service container for dependency injection
+ */
+interface ServiceContainer<UploadInput> {
+  storage: StorageService;
+  idGeneration: IdGenerationService;
+  httpClient: HttpClient;
+  fileReader: FileReaderService<UploadInput>;
+  base64?: Base64Service;
+  websocket: WebSocketFactory;
+  abortController: AbortControllerFactory;
+  platform: PlatformService;
+  checksumService: ChecksumService;
+  fingerprintService: FingerprintService<UploadInput>;
+}
+//#endregion
+//#region src/types/upload-response.d.ts
+type UploadResponse = {
+  upload?: UploadFile$1;
+  status: number;
+};
+//#endregion
+//#region src/upload/chunk-upload.d.ts
+type OnProgress = (uploadId: string, bytesSent: number, bytesTotal: number | null) => void;
+type OnShouldRetry = (error: UploadistaError, retryAttempt: number) => boolean;
+//#endregion
+//#region src/types/chunk-metrics.d.ts
+interface ChunkMetrics {
+  chunkIndex: number;
+  size: number;
+  duration: number;
+  speed: number;
+  success: boolean;
+  retryCount: number;
+  timestamp: number;
+  networkCondition?: string;
+  chunkingStrategy?: string;
+}
+//#endregion
+//#region src/types/performance-insights.d.ts
+interface PerformanceInsights {
+  overallEfficiency: number;
+  chunkingEffectiveness: number;
+  networkStability: number;
+  recommendations: string[];
+  optimalChunkSizeRange: {
+    min: number;
+    max: number;
+  };
+}
+//#endregion
+//#region src/types/upload-session-metrics.d.ts
+interface UploadSessionMetrics {
+  uploadId: string;
+  totalSize: number;
+  totalDuration: number;
+  chunksCompleted: number;
+  chunksTotal: number;
+  averageSpeed: number;
+  peakSpeed: number;
+  minSpeed: number;
+  totalRetries: number;
+  successRate: number;
+  adaptiveChunkingEnabled: boolean;
+  startTime: number;
+  endTime?: number;
+}
+//#endregion
+//#region src/upload/upload-metrics.d.ts
+interface UploadMetricsConfig {
+  maxChunkHistory?: number;
+  enableDetailedMetrics?: boolean;
+  performanceThresholds?: {
+    slowSpeed: number;
+    fastSpeed: number;
+    highRetryRate: number;
+  };
+}
+//#endregion
+//#region src/upload/single-upload.d.ts
+type Callbacks = {
+  onProgress?: OnProgress;
+  onChunkComplete?: (chunkSize: number, bytesAccepted: number, bytesTotal: number | null) => void;
+  onSuccess?: (payload: UploadFile) => void;
+  onError?: (error: Error | UploadistaError) => void;
+  onStart?: (file: {
+    uploadId: string;
+    size: number | null;
+  }) => void;
+  onJobStart?: (jobId: string) => void;
+  onShouldRetry?: OnShouldRetry;
+};
+//#endregion
+//#region src/upload/upload-manager.d.ts
+/**
+ * Abort any running request and stop the current upload. After abort is called, no event
+ * handler will be invoked anymore. You can use the `start` method to resume the upload
+ * again.
+ * If `shouldTerminate` is true, the `terminate` function will be called to remove the
+ * current upload from the server.
+ */
+declare function abort({
+  uploadId,
+  uploadIdStorageKey,
+  retryTimeout,
+  shouldTerminate,
+  abortController,
+  uploadistaApi,
+  platformService,
+  retryDelays,
+  clientStorage
+}: {
+  uploadId: string;
+  uploadIdStorageKey: string | undefined;
+  retryTimeout: Timeout | null;
+  shouldTerminate: boolean;
+  abortController: AbortControllerLike;
+  uploadistaApi: UploadistaApi;
+  platformService: PlatformService;
+  retryDelays?: number[];
+  clientStorage: ClientStorage;
+}): Promise<void>;
+//#endregion
+//#region src/upload/upload-strategy.d.ts
+type UploadStrategyConfig = {
+  preferredStrategy?: "single" | "parallel" | "auto";
+  minFileSizeForParallel?: number;
+  enableCapabilityNegotiation?: boolean;
+  onStrategySelected?: (strategy: {
+    chosen: "single" | "parallel";
+    chunkSize: number;
+    parallelUploads: number;
+    reasoning: string[];
+    warnings: string[];
+  }) => void;
+};
+//#endregion
+//#region src/client/uploadista-websocket-manager.d.ts
+type UploadistaEvent = UploadEvent | FlowEvent;
+type UploadistaWebSocketEventHandler = (event: UploadistaEvent) => void;
+type UploadistaWebSocketMessage = {
+  type: "connection";
+  message: string;
+  id: string;
+  timestamp: string;
+} | {
+  type: "subscribed";
+  payload: {
+    uploadId?: string;
+    jobId?: string;
+  };
+  timestamp: string;
+} | {
+  type: "error";
+  message: string;
+  code?: string;
+} | {
+  type: "pong";
+  timestamp: string;
+} | {
+  type: "upload_event";
+  payload: UploadEvent;
+} | {
+  type: "flow_event";
+  payload: FlowEvent;
+};
+/**
+ * Unified WebSocket management for both upload and flow events
+ */
+declare class UploadistaWebSocketManager {
+  private uploadistaApi;
+  private logger;
+  private onEvent?;
+  private uploadWebsockets;
+  private flowWebsockets;
+  constructor(uploadistaApi: UploadistaApi, logger: Logger, onEvent?: UploadistaWebSocketEventHandler | undefined);
+  /**
+   * Open a WebSocket connection for upload events
+   */
+  openUploadWebSocket(uploadId: string): Promise<WebSocketLike>;
+  /**
+   * Open a WebSocket connection for flow/job events
+   */
+  openFlowWebSocket(jobId: string): Promise<WebSocketLike>;
+  /**
+   * Open a unified WebSocket connection - automatically determines if it's for upload or flow
+   * based on the ID format (upload IDs typically start with 'upload-', job IDs start with 'job-')
+   */
+  openWebSocket(id: string): Promise<WebSocketLike>;
+  /**
+   * Close upload WebSocket connection
+   */
+  closeUploadWebSocket(uploadId: string): void;
+  /**
+   * Close flow WebSocket connection
+   */
+  closeFlowWebSocket(jobId: string): void;
+  /**
+   * Close WebSocket connection by ID (auto-detects type)
+   */
+  closeWebSocket(id: string): void;
+  /**
+   * Close all WebSocket connections (both upload and flow)
+   */
+  closeAll(): void;
+  /**
+   * Send ping to flow WebSocket
+   */
+  sendPing(jobId: string): boolean;
+  /**
+   * Get upload WebSocket by ID
+   */
+  getUploadWebSocket(uploadId: string): WebSocketLike | undefined;
+  /**
+   * Get flow WebSocket by ID
+   */
+  getFlowWebSocket(jobId: string): WebSocketLike | undefined;
+  /**
+   * Check if upload WebSocket is connected
+   */
+  isUploadConnected(uploadId: string): boolean;
+  /**
+   * Check if flow WebSocket is connected
+   */
+  isFlowConnected(jobId: string): boolean;
+  /**
+   * Check if WebSocket is connected (auto-detects type)
+   */
+  isConnected(id: string): boolean;
+  /**
+   * Get total number of active WebSocket connections
+   */
+  getConnectionCount(): number;
+  /**
+   * Get connection counts by type
+   */
+  getConnectionCountByType(): {
+    upload: number;
+    flow: number;
+    total: number;
+  };
+}
+//#endregion
+//#region src/client/create-uploadista-client.d.ts
+/**
+ * Options for individual upload operations.
+ *
+ * Extends the base upload callbacks with configuration for deferred length,
+ * size overrides, metadata, and checksum computation.
+ */
+type UploadistaUploadOptions = {
+  /**
+   * Whether to defer specifying the upload size until later.
+   * Useful for streaming uploads where size isn't known upfront.
+   * Defaults to false.
+   */
+  uploadLengthDeferred?: boolean;
+  /**
+   * Manual override for upload size in bytes.
+   * If not provided, size is determined from the file/blob.
+   */
+  uploadSize?: number;
+  /**
+   * Custom metadata to attach to the upload.
+   * Stored as key-value pairs on the server.
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Whether to compute checksums for uploaded chunks.
+   * Enables integrity verification but adds computational overhead.
+   * Defaults to false.
+   */
+  computeChecksum?: boolean;
+  /**
+   * Checksum algorithm to use (e.g., "sha256", "md5").
+   * Only relevant if computeChecksum is true.
+   */
+  checksumAlgorithm?: string;
+} & Callbacks;
+/**
+ * Configuration options for creating an Uploadista client.
+ *
+ * This comprehensive configuration object allows customization of all aspects
+ * of upload behavior including chunking, retries, authentication, storage,
+ * network monitoring, and platform-specific services.
+ *
+ * @template UploadInput - The platform-specific file/blob type (e.g., File, Blob, Buffer)
+ */
+type UploadistaClientOptions<UploadInput> = {
+  /** Base URL of the Uploadista server (e.g., "https://upload.example.com") */
+  baseUrl: string;
+  /** Base path for Uploadista endpoints. Defaults to "uploadista" */
+  uploadistaBasePath?: string;
+  /** Storage backend identifier configured on the server */
+  storageId: string;
+  /** Retry delay intervals in milliseconds. Defaults to [1000, 3000, 5000] */
+  retryDelays?: number[];
+  /** Default chunk size in bytes for uploads */
+  chunkSize: number;
+  /** Number of parallel upload streams. Defaults to 1 (sequential) */
+  parallelUploads?: number;
+  /** Chunk size for parallel uploads. Required if parallelUploads > 1 */
+  parallelChunkSize?: number;
+  /** Service for computing checksums of uploaded chunks */
+  checksumService: ChecksumService;
+  /** Strategy configuration for determining upload approach (single/parallel/chunked) */
+  uploadStrategy?: UploadStrategyConfig;
+  /** Smart chunking configuration for adaptive chunk sizes based on network conditions */
+  smartChunking?: SmartChunkerConfig;
+  /** Network monitoring configuration for tracking upload performance */
+  networkMonitoring?: NetworkMonitorConfig;
+  /** Upload metrics configuration for performance insights */
+  uploadMetrics?: UploadMetricsConfig;
+  /** HTTP client with connection pooling support */
+  httpClient: HttpClient;
+  /** Service for generating unique IDs */
+  generateId: IdGenerationService;
+  /** Client-side storage for upload resumption data */
+  clientStorage: ClientStorage;
+  /** Platform-specific file reading service */
+  fileReader: FileReaderService<UploadInput>;
+  /** Logger for debugging and monitoring */
+  logger: Logger;
+  /** Service for computing file fingerprints for resumption */
+  fingerprintService: FingerprintService<UploadInput>;
+  /** Whether to store fingerprints for upload resumption. Defaults to true */
+  storeFingerprintForResuming: boolean;
+  /** Factory for creating WebSocket connections */
+  webSocketFactory: WebSocketFactory;
+  /** Factory for creating abort controllers */
+  abortControllerFactory: AbortControllerFactory;
+  /** Platform-specific service for timers and async operations */
+  platformService: PlatformService;
+  /** Global error handler for all upload operations */
+  onError?: (error: Error) => void;
+  /** WebSocket event handler for real-time upload/flow events */
+  onEvent?: UploadistaWebSocketEventHandler;
+  /**
+   * Optional authentication configuration.
+   * Supports two modes:
+   * - Direct: Bring your own auth (headers, cookies, custom tokens)
+   * - SaaS: Standard JWT token exchange with auth server
+   *
+   * If omitted, client operates in no-auth mode (backward compatible).
+   *
+   * @example Direct mode with Bearer token
+   * ```typescript
+   * auth: {
+   *   mode: 'direct',
+   *   getCredentials: () => ({
+   *     headers: { 'Authorization': 'Bearer token123' }
+   *   })
+   * }
+   * ```
+   *
+   * @example SaaS mode with auth server
+   * ```typescript
+   * auth: {
+   *   mode: 'saas',
+   *   authServerUrl: 'https://auth.myapp.com/token',
+   *   getCredentials: () => ({ username: 'user', password: 'pass' })
+   * }
+   * ```
+   */
+  auth?: AuthConfig;
+};
+/**
+ * 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.
+ */
+declare const defaultConnectionPoolingConfig: ConnectionPoolConfig;
+/**
+ * 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
+ */
+declare function createUploadistaClient<UploadInput>({
+  baseUrl: _baseUrl,
+  uploadistaBasePath,
+  storageId,
+  retryDelays,
+  chunkSize,
+  parallelUploads,
+  parallelChunkSize,
+  uploadStrategy,
+  smartChunking,
+  networkMonitoring,
+  uploadMetrics,
+  checksumService,
+  onEvent,
+  generateId,
+  httpClient,
+  logger,
+  fileReader,
+  fingerprintService,
+  clientStorage,
+  storeFingerprintForResuming,
+  webSocketFactory,
+  abortControllerFactory,
+  platformService,
+  auth
+}: UploadistaClientOptions<UploadInput>): {
+  upload: (file: UploadInput, {
+    uploadLengthDeferred,
+    uploadSize,
+    onProgress,
+    onChunkComplete,
+    onSuccess,
+    onShouldRetry,
+    onError
+  }?: UploadistaUploadOptions) => Promise<{
+    abort: () => void;
+  }>;
+  uploadWithFlow: (file: UploadInput, flowConfig: FlowUploadConfig, {
+    onProgress,
+    onChunkComplete,
+    onSuccess,
+    onShouldRetry,
+    onJobStart,
+    onError
+  }?: Omit<UploadistaUploadOptions, "uploadLengthDeferred" | "uploadSize" | "metadata">) => Promise<{
+    abort: () => void;
+    jobId: string;
+  }>;
+  abort: (params: Parameters<typeof abort>[0]) => Promise<void>;
+  getFlow: (flowId: string) => Promise<{
+    status: number;
+    flow: _uploadista_core0.FlowData;
+  }>;
+  runFlow: ({
+    flowId,
+    inputs,
+    storageId: flowStorageId
+  }: {
+    flowId: string;
+    inputs: Record<string, unknown>;
+    storageId?: string;
+  }) => Promise<{
+    status: number;
+    job: _uploadista_core0.FlowJob;
+  }>;
+  continueFlow: ({
+    jobId,
+    nodeId,
+    newData,
+    contentType
+  }: {
+    jobId: string;
+    nodeId: string;
+    newData: unknown;
+    contentType?: "application/json" | "application/octet-stream";
+  }) => Promise<_uploadista_core0.FlowJob>;
+  getJobStatus: (jobId: string) => Promise<_uploadista_core0.FlowJob>;
+  openUploadWebSocket: (uploadId: string) => Promise<WebSocketLike>;
+  openFlowWebSocket: (jobId: string) => Promise<WebSocketLike>;
+  openWebSocket: (id: string) => Promise<WebSocketLike>;
+  closeWebSocket: (id: string) => void;
+  closeAllWebSockets: () => void;
+  sendPing: (jobId: string) => boolean;
+  isWebSocketConnected: (id: string) => boolean;
+  getWebSocketConnectionCount: () => number;
+  getWebSocketConnectionCountByType: () => {
+    upload: number;
+    flow: number;
+    total: number;
+  };
+  getNetworkMetrics: () => NetworkMetrics;
+  getNetworkCondition: () => NetworkCondition;
+  getChunkingInsights: () => PerformanceInsights;
+  exportMetrics: () => {
+    session: Partial<UploadSessionMetrics>;
+    chunks: ChunkMetrics[];
+    insights: PerformanceInsights;
+  };
+  getConnectionMetrics: () => ConnectionMetrics;
+  getDetailedConnectionMetrics: () => DetailedConnectionMetrics;
+  warmupConnections: (urls: string[]) => Promise<void>;
+  getConnectionPoolingInsights: () => Promise<{
+    isOptimized: boolean;
+    reuseRate: number;
+    recommendedMinChunkSize: number;
+    connectionOverhead: number;
+  }>;
+  resetMetrics: () => Promise<void>;
+  validateConfiguration: (options: UploadistaClientOptions<UploadInput>) => {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+  };
+  validateConfigurationAsync: (options: UploadistaClientOptions<UploadInput>) => Promise<{
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    capabilities: DataStoreCapabilities;
+  }>;
+  getCapabilities: () => Promise<DataStoreCapabilities>;
+};
+/**
+ * Uploadista client instance type.
+ *
+ * The client provides methods for:
+ * - **Upload operations**: upload(), uploadWithFlow()
+ * - **Flow operations**: getFlow(), runFlow(), continueFlow()
+ * - **Job management**: getJobStatus()
+ * - **WebSocket management**: openUploadWebSocket(), openFlowWebSocket(), closeWebSocket()
+ * - **Metrics and diagnostics**: getNetworkMetrics(), getChunkingInsights(), exportMetrics()
+ * - **Connection pooling**: getConnectionMetrics(), warmupConnections()
+ * - **Configuration validation**: validateConfiguration(), validateConfigurationAsync()
+ *
+ * @example Basic usage
+ * ```typescript
+ * const client = createUploadistaClient(config);
+ *
+ * // Upload a file
+ * await client.upload(file, {
+ *   onProgress: (progress) => console.log(`${progress}%`),
+ *   onSuccess: (result) => console.log('Done:', result.id),
+ * });
+ *
+ * // Get network metrics
+ * const metrics = client.getNetworkMetrics();
+ * console.log(`Speed: ${metrics.averageSpeed / 1024} KB/s`);
+ * ```
+ *
+ * @see {@link createUploadistaClient} for creating an instance
+ */
+type UploadistaClient = ReturnType<typeof createUploadistaClient>;
+//#endregion
+//#region src/storage/in-memory-storage-service.d.ts
+/**
+ * In-memory fallback storage service for Expo
+ * Used when AsyncStorage is not available or for testing
+ */
+declare function createInMemoryStorageService(): StorageService;
+//#endregion
+//#region src/types/flow-result.d.ts
+type FlowResult<TOutput = UploadFile> = {
+  type: "success";
+  value: TOutput;
+} | {
+  type: "error";
+  error: Error;
+} | {
+  type: "cancelled";
+};
+//#endregion
+//#region src/types/flow-upload-item.d.ts
+/**
+ * Flow upload item for multi-flow-upload tracking
+ */
+interface FlowUploadItem<UploadInput> {
+  id: string;
+  file: UploadInput;
+  status: "pending" | "uploading" | "success" | "error" | "aborted";
+  progress: number;
+  bytesUploaded: number;
+  totalBytes: number;
+  error: Error | null;
+  result: UploadFile$1 | null;
+  jobId: string | null;
+}
+//#endregion
+//#region src/types/flow-upload-options.d.ts
+interface FlowUploadOptions<TOutput = UploadFile> {
+  /**
+   * Flow configuration
+   */
+  flowConfig: FlowUploadConfig;
+  /**
+   * 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 the flow completes successfully (receives full flow outputs)
+   * This is the recommended callback for multi-output flows
+   * Format: { [outputNodeId]: result, ... }
+   */
+  onFlowComplete?: (outputs: Record<string, unknown>) => void;
+  /**
+   * Called when upload succeeds (legacy, single-output flows)
+   * 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 fails
+   */
+  onError?: (error: Error) => void;
+  /**
+   * Called when upload is aborted
+   */
+  onAbort?: () => void;
+  /**
+   * Custom retry logic
+   */
+  onShouldRetry?: (error: Error, retryAttempt: number) => boolean;
+}
+//#endregion
+//#region src/types/multi-flow-upload-options.d.ts
+interface MultiFlowUploadOptions<UploadInput> {
+  /**
+   * Flow configuration
+   */
+  flowConfig: FlowUploadConfig;
+  /**
+   * Maximum number of concurrent uploads (default: 3)
+   */
+  maxConcurrent?: number;
+  /**
+   * Called when an individual upload progresses
+   */
+  onItemProgress?: (item: FlowUploadItem<UploadInput>) => void;
+  /**
+   * Called when an individual upload succeeds
+   */
+  onItemSuccess?: (item: FlowUploadItem<UploadInput>) => void;
+  /**
+   * Called when an individual upload fails
+   */
+  onItemError?: (item: FlowUploadItem<UploadInput>, error: Error) => void;
+  /**
+   * Called when all uploads complete
+   */
+  onComplete?: (items: FlowUploadItem<UploadInput>[]) => void;
+  /**
+   * Custom retry logic
+   */
+  onShouldRetry?: (error: Error, retryAttempt: number) => boolean;
+}
+//#endregion
+//#region src/types/multi-flow-upload-state.d.ts
+interface MultiFlowUploadState<UploadInput> {
+  items: FlowUploadItem<UploadInput>[];
+  totalProgress: number;
+  activeUploads: number;
+  completedUploads: number;
+  failedUploads: number;
+}
+//#endregion
+//#region src/types/upload-options.d.ts
+interface UploadOptions {
+  /**
+   * 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$1) => 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;
+}
+//#endregion
+//#region src/types/upload-result.d.ts
+/**
+ * Discriminated union representing the result of an upload operation.
+ *
+ * Provides a type-safe way to handle the three possible outcomes of an upload:
+ * success, error, or cancellation. This pattern enables exhaustive checking
+ * of all cases at compile time.
+ *
+ * @template TOutput - The type of the successful result value. Defaults to UploadFile
+ *
+ * @example Handling upload results
+ * ```typescript
+ * function handleUploadResult(result: UploadResult) {
+ *   switch (result.type) {
+ *     case 'success':
+ *       console.log('Upload complete:', result.value.id);
+ *       break;
+ *     case 'error':
+ *       console.error('Upload failed:', result.error.message);
+ *       break;
+ *     case 'cancelled':
+ *       console.log('Upload was cancelled by user');
+ *       break;
+ *   }
+ * }
+ * ```
+ *
+ * @example With custom output type
+ * ```typescript
+ * interface ProcessedImage {
+ *   url: string;
+ *   width: number;
+ *   height: number;
+ * }
+ *
+ * const result: UploadResult<ProcessedImage> = await uploadAndProcess(file);
+ *
+ * if (result.type === 'success') {
+ *   console.log(`Image processed: ${result.value.width}x${result.value.height}`);
+ * }
+ * ```
+ */
+type UploadResult<TOutput = UploadFile$1> = {
+  /** Indicates the upload completed successfully */
+  type: "success";
+  /** The successful result value (e.g., upload metadata or processed output) */
+  value: TOutput;
+} | {
+  /** Indicates the upload failed with an error */
+  type: "error";
+  /** The error that caused the upload to fail */
+  error: Error;
+} | {
+  /** Indicates the upload was cancelled by the user or application */
+  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 };
 //# sourceMappingURL=index.d.ts.map