@uploadista/client-core 0.0.3

package/src/client/uploadista-websocket-manager.ts

@@ -0,0 +1,275 @@
+import type { FlowEvent } from "@uploadista/core/flow";
+import type { UploadEvent } from "@uploadista/core/types";
+import { webSocketMessageSchema } from "@uploadista/core/types";
+import type { Logger } from "../logger";
+import type { WebSocketLike } from "../services/websocket-service";
+import type { UploadistaApi } from "./uploadista-api";
+
+export type UploadistaEvent = UploadEvent | FlowEvent;
+
+export type UploadistaWebSocketEventHandler = (event: UploadistaEvent) => void;
+
+export 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
+ */
+export class UploadistaWebSocketManager {
+  private uploadWebsockets = new Map<string, WebSocketLike>();
+  private flowWebsockets = new Map<string, WebSocketLike>();
+
+  constructor(
+    private uploadistaApi: UploadistaApi,
+    private logger: Logger,
+    private onEvent?: UploadistaWebSocketEventHandler,
+  ) {}
+
+  /**
+   * Open a WebSocket connection for upload events
+   */
+  async openUploadWebSocket(uploadId: string): Promise<WebSocketLike> {
+    // Close existing connection if any
+    this.closeUploadWebSocket(uploadId);
+
+    const ws = await this.uploadistaApi.openUploadWebSocket(uploadId);
+    this.uploadWebsockets.set(uploadId, ws);
+
+    ws.onmessage = (event) => {
+      try {
+        const parsedEvent = webSocketMessageSchema.safeParse(
+          JSON.parse(event.data),
+        );
+
+        if (parsedEvent.success) {
+          if (parsedEvent.data.type === "upload_event") {
+            this.onEvent?.(parsedEvent.data.payload);
+          }
+        } else {
+          this.logger.error(
+            `Error parsing upload event: ${parsedEvent.error.message}`,
+          );
+        }
+      } catch (error) {
+        this.logger.error(`Error parsing upload event: ${error}`);
+      }
+    };
+
+    ws.onerror = (error) => {
+      this.logger.error(`Upload WebSocket error for ${uploadId}: ${error}`);
+    };
+
+    ws.onclose = (event) => {
+      this.logger.log(
+        `Upload WebSocket closed for ${uploadId}, \n code: ${event.code as number}, reason: ${event.reason as string}`,
+      );
+      this.uploadWebsockets.delete(uploadId);
+    };
+
+    return ws;
+  }
+
+  /**
+   * Open a WebSocket connection for flow/job events
+   */
+  async openFlowWebSocket(jobId: string): Promise<WebSocketLike> {
+    // Close existing connection if any
+    this.closeFlowWebSocket(jobId);
+
+    const ws = await this.uploadistaApi.openFlowWebSocket(jobId);
+    this.flowWebsockets.set(jobId, ws);
+
+    ws.onmessage = (event) => {
+      try {
+        const message = JSON.parse(event.data) as UploadistaWebSocketMessage;
+
+        switch (message.type) {
+          case "connection":
+            this.logger.log(`Flow WebSocket connected for job: ${message.id}`);
+            break;
+          case "subscribed":
+            this.logger.log(
+              `Flow WebSocket subscribed for job: ${message.payload.jobId}`,
+            );
+            break;
+          case "error":
+            this.logger.error(
+              `Flow WebSocket error: ${message.message} for job ${jobId} with code ${message.code}`,
+            );
+            break;
+          case "pong":
+            this.logger.log(`Flow WebSocket pong received for job: ${jobId}`);
+            break;
+          case "flow_event":
+            this.onEvent?.(message.payload);
+            break;
+          default:
+            this.logger.warn(
+              `Unknown flow WebSocket message type: ${message.type}`,
+            );
+        }
+      } catch (error) {
+        this.logger.error(`Error parsing flow WebSocket message:${error}`);
+      }
+    };
+
+    ws.onerror = (error) => {
+      this.logger.error(`Flow WebSocket error for job ${jobId}: ${error}`);
+    };
+
+    ws.onclose = (event) => {
+      this.logger.log(
+        `Flow WebSocket closed for job ${jobId}, \n code: ${event.code as number}, reason: ${event.reason as string}`,
+      );
+      this.flowWebsockets.delete(jobId);
+    };
+
+    return ws;
+  }
+
+  /**
+   * 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-')
+   */
+  async openWebSocket(id: string): Promise<WebSocketLike> {
+    // Heuristic: if ID starts with 'upload-' or contains upload-related patterns, treat as upload
+    // Otherwise, treat as flow/job
+    if (id.startsWith("upload-") || id.includes("upload")) {
+      return await this.openUploadWebSocket(id);
+    }
+    return await this.openFlowWebSocket(id);
+  }
+
+  /**
+   * Close upload WebSocket connection
+   */
+  closeUploadWebSocket(uploadId: string): void {
+    const ws = this.uploadWebsockets.get(uploadId);
+    if (ws) {
+      this.uploadistaApi.closeWebSocket(ws);
+      this.uploadWebsockets.delete(uploadId);
+    }
+  }
+
+  /**
+   * Close flow WebSocket connection
+   */
+  closeFlowWebSocket(jobId: string): void {
+    const ws = this.flowWebsockets.get(jobId);
+    if (ws) {
+      this.uploadistaApi.closeWebSocket(ws);
+      this.flowWebsockets.delete(jobId);
+    }
+  }
+
+  /**
+   * Close WebSocket connection by ID (auto-detects type)
+   */
+  closeWebSocket(id: string): void {
+    // Try both maps
+    this.closeUploadWebSocket(id);
+    this.closeFlowWebSocket(id);
+  }
+
+  /**
+   * Close all WebSocket connections (both upload and flow)
+   */
+  closeAll(): void {
+    // Close all upload websockets
+    for (const [uploadId, ws] of this.uploadWebsockets.entries()) {
+      this.uploadistaApi.closeWebSocket(ws);
+      this.uploadWebsockets.delete(uploadId);
+    }
+
+    // Close all flow websockets
+    for (const [jobId, ws] of this.flowWebsockets.entries()) {
+      this.uploadistaApi.closeWebSocket(ws);
+      this.flowWebsockets.delete(jobId);
+    }
+  }
+
+  /**
+   * Send ping to flow WebSocket
+   */
+  sendPing(jobId: string): boolean {
+    const ws = this.flowWebsockets.get(jobId);
+    if (ws && ws.readyState === ws.OPEN) {
+      ws.send(
+        JSON.stringify({
+          type: "ping",
+          timestamp: new Date().toISOString(),
+        }),
+      );
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get upload WebSocket by ID
+   */
+  getUploadWebSocket(uploadId: string): WebSocketLike | undefined {
+    return this.uploadWebsockets.get(uploadId);
+  }
+
+  /**
+   * Get flow WebSocket by ID
+   */
+  getFlowWebSocket(jobId: string): WebSocketLike | undefined {
+    return this.flowWebsockets.get(jobId);
+  }
+
+  /**
+   * Check if upload WebSocket is connected
+   */
+  isUploadConnected(uploadId: string): boolean {
+    const ws = this.uploadWebsockets.get(uploadId);
+    return ws?.readyState === ws?.OPEN;
+  }
+
+  /**
+   * Check if flow WebSocket is connected
+   */
+  isFlowConnected(jobId: string): boolean {
+    const ws = this.flowWebsockets.get(jobId);
+    return ws?.readyState === ws?.OPEN;
+  }
+
+  /**
+   * Check if WebSocket is connected (auto-detects type)
+   */
+  isConnected(id: string): boolean {
+    return this.isUploadConnected(id) || this.isFlowConnected(id);
+  }
+
+  /**
+   * Get total number of active WebSocket connections
+   */
+  getConnectionCount(): number {
+    return this.uploadWebsockets.size + this.flowWebsockets.size;
+  }
+
+  /**
+   * Get connection counts by type
+   */
+  getConnectionCountByType(): {
+    upload: number;
+    flow: number;
+    total: number;
+  } {
+    return {
+      upload: this.uploadWebsockets.size,
+      flow: this.flowWebsockets.size,
+      total: this.uploadWebsockets.size + this.flowWebsockets.size,
+    };
+  }
+}

package/src/error.ts

@@ -0,0 +1,149 @@
+/**
+ * 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');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export 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));
+ *   }
+ * }
+ * ```
+ */
+export 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;
+  }) {
+    super();
+    this.name = name;
+    this.cause = cause;
+    this.message = message;
+    this.status = status;
+  }
+
+  /**
+   * 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 {
+    return (
+      this.name === "NETWORK_ERROR" ||
+      this.name === "NETWORK_UNEXPECTED_RESPONSE"
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// Service interfaces
+
+export * from "./chunk-buffer";
+export * from "./client";
+export * from "./error";
+export * from "./logger";
+// Utilities
+export * from "./network-monitor";
+export * from "./services";
+// Storage
+export * from "./storage";
+// Core types
+export * from "./types";

package/src/logger.ts

@@ -0,0 +1,104 @@
+/**
+ * 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');
+ * ```
+ */
+export 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.
+ */
+export type LogFunction = (message: string) => void;
+
+/**
+ * Default no-op logger function.
+ *
+ * Used when no custom logging function is provided.
+ * Platform implementations should provide their own (e.g., console.log).
+ */
+const noopLog: LogFunction = () => {
+  // No-op by default - platforms will override
+};
+
+/**
+ * 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);
+ * ```
+ */
+export function createLogger(
+  enabled: boolean,
+  logFn: LogFunction = noopLog,
+): Logger {
+  return {
+    log: (message: string) => {
+      if (enabled) {
+        logFn(message);
+      }
+    },
+    warn: (message: string) => {
+      if (enabled) {
+        logFn(message);
+      }
+    },
+    error: (message: string) => {
+      if (enabled) {
+        logFn(message);
+      }
+    },
+  };
+}

package/src/mock-data-store.ts

@@ -0,0 +1,97 @@
+import type {
+  DataStoreCapabilities,
+  UploadStrategy,
+} from "@uploadista/core/types";
+
+/**
+ * Mock data store implementation for client-side capability negotiation.
+ * This doesn't perform actual data store operations but provides capability information
+ * for upload strategy decisions.
+ */
+export class MockClientDataStore {
+  constructor(private capabilities: DataStoreCapabilities) {}
+
+  getCapabilities(): DataStoreCapabilities {
+    return this.capabilities;
+  }
+
+  validateUploadStrategy(strategy: UploadStrategy): boolean {
+    switch (strategy) {
+      case "parallel":
+        return this.capabilities.supportsParallelUploads;
+      case "single":
+        return true;
+      default:
+        return false;
+    }
+  }
+}
+
+/**
+ * Default capabilities that assume basic parallel upload support
+ * (conservative defaults that work with most backends)
+ */
+export const defaultClientCapabilities: DataStoreCapabilities = {
+  supportsParallelUploads: true,
+  supportsConcatenation: true,
+  supportsDeferredLength: true,
+  supportsResumableUploads: true,
+  supportsTransactionalUploads: false,
+  maxConcurrentUploads: 6, // Browser-safe default
+  minChunkSize: 64 * 1024, // 64KB
+  maxChunkSize: 100 * 1024 * 1024, // 100MB
+  maxParts: 10000,
+  optimalChunkSize: 8 * 1024 * 1024, // 8MB
+  requiresOrderedChunks: false,
+};
+
+/**
+ * Capabilities for S3-compatible backends
+ */
+export const s3LikeCapabilities: DataStoreCapabilities = {
+  supportsParallelUploads: true,
+  supportsConcatenation: true,
+  supportsDeferredLength: true,
+  supportsResumableUploads: true,
+  supportsTransactionalUploads: true,
+  maxConcurrentUploads: 60,
+  minChunkSize: 5 * 1024 * 1024, // 5MiB S3 minimum
+  maxChunkSize: 5 * 1024 * 1024 * 1024, // 5GiB S3 maximum
+  maxParts: 10000,
+  optimalChunkSize: 8 * 1024 * 1024, // 8MB
+  requiresOrderedChunks: false,
+};
+
+/**
+ * Capabilities for GCS-compatible backends
+ */
+export const gcsLikeCapabilities: DataStoreCapabilities = {
+  supportsParallelUploads: false, // GCS doesn't have native multipart
+  supportsConcatenation: true, // Can combine files
+  supportsDeferredLength: true,
+  supportsResumableUploads: true,
+  supportsTransactionalUploads: false,
+  maxConcurrentUploads: 1,
+  minChunkSize: undefined,
+  maxChunkSize: undefined,
+  maxParts: undefined,
+  optimalChunkSize: 8 * 1024 * 1024, // 8MB
+  requiresOrderedChunks: true,
+};
+
+/**
+ * Capabilities for filesystem-based backends
+ */
+export const filesystemLikeCapabilities: DataStoreCapabilities = {
+  supportsParallelUploads: false, // Sequential operations
+  supportsConcatenation: false,
+  supportsDeferredLength: false,
+  supportsResumableUploads: true,
+  supportsTransactionalUploads: false,
+  maxConcurrentUploads: 1,
+  minChunkSize: undefined,
+  maxChunkSize: undefined,
+  maxParts: undefined,
+  optimalChunkSize: 1024 * 1024, // 1MB
+  requiresOrderedChunks: true,
+};