@uploadista/client-browser 0.0.3

package/src/services/websocket-factory.ts

@@ -0,0 +1,212 @@
+import type { WebSocketFactory, WebSocketLike } from "@uploadista/client-core";
+
+/**
+ * Browser implementation of WebSocket that wraps the native WebSocket API.
+ *
+ * This class provides a minimal wrapper around the browser's native WebSocket
+ * to ensure compatibility with the Uploadista client's WebSocketLike interface.
+ * It's used for real-time communication features like:
+ * - Upload progress streaming
+ * - Flow execution status updates
+ * - Real-time error notifications
+ * - Live event feeds
+ *
+ * The wrapper preserves all WebSocket states and properly proxies all events
+ * while maintaining the standard WebSocket lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const ws = new BrowserWebSocket('wss://api.example.com/ws');
+ *
+ * ws.onopen = () => {
+ *   console.log('Connected');
+ *   ws.send('Hello server');
+ * };
+ *
+ * ws.onmessage = (event) => {
+ *   console.log('Message:', event.data);
+ * };
+ *
+ * ws.onerror = (event) => {
+ *   console.error('Error:', event.message);
+ * };
+ *
+ * ws.onclose = (event) => {
+ *   console.log('Closed:', event.code, event.reason);
+ * };
+ * ```
+ */
+class BrowserWebSocket implements WebSocketLike {
+  /** WebSocket is currently connecting (readyState = 0) */
+  readonly CONNECTING = 0;
+  /** WebSocket connection is open and ready (readyState = 1) */
+  readonly OPEN = 1;
+  /** WebSocket is closing (readyState = 2) */
+  readonly CLOSING = 2;
+  /** WebSocket connection is closed (readyState = 3) */
+  readonly CLOSED = 3;
+
+  /**
+   * Current state of the WebSocket connection.
+   *
+   * Possible values:
+   * - 0 (CONNECTING): Connection is being established
+   * - 1 (OPEN): Connection is open and ready for communication
+   * - 2 (CLOSING): Connection is closing
+   * - 3 (CLOSED): Connection is closed or couldn't be opened
+   */
+  readyState: number;
+
+  /** Event handler called when the connection is established */
+  onopen: (() => void) | null = null;
+
+  /** Event handler called when the connection is closed */
+  onclose: ((event: { code: number; reason: string }) => void) | null = null;
+
+  /** Event handler called when an error occurs */
+  onerror: ((event: { message: string }) => void) | null = null;
+
+  /** Event handler called when a message is received */
+  onmessage: ((event: { data: string }) => void) | null = null;
+
+  private native: WebSocket;
+
+  /**
+   * Creates a new BrowserWebSocket instance.
+   *
+   * Initializes a native WebSocket connection to the specified URL and sets up
+   * event handler proxying to convert native events to the WebSocketLike format.
+   *
+   * @param url - WebSocket URL to connect to (must use ws:// or wss:// protocol)
+   *
+   * @example
+   * ```typescript
+   * const ws = new BrowserWebSocket('wss://api.example.com/upload/progress');
+   * ```
+   */
+  constructor(url: string) {
+    this.native = new WebSocket(url);
+    this.readyState = this.native.readyState;
+
+    // Proxy event handlers to convert native events to WebSocketLike format
+    this.native.onopen = () => {
+      this.readyState = this.native.readyState;
+      this.onopen?.();
+    };
+
+    this.native.onclose = (event) => {
+      this.readyState = this.native.readyState;
+      const closeEvent = event as CloseEvent;
+      this.onclose?.({ code: closeEvent.code, reason: closeEvent.reason });
+    };
+
+    this.native.onerror = (_event) => {
+      this.onerror?.({ message: "WebSocket error" });
+    };
+
+    this.native.onmessage = (event) => {
+      const messageEvent = event as MessageEvent;
+      this.onmessage?.({ data: messageEvent.data });
+    };
+  }
+
+  /**
+   * Sends data through the WebSocket connection.
+   *
+   * The data can be either a string (text message) or a Uint8Array (binary message).
+   * The connection must be in the OPEN state before sending data.
+   *
+   * @param data - String or binary data to send
+   *
+   * @throws {Error} If the connection is not open
+   *
+   * @example
+   * ```typescript
+   * // Send text message
+   * ws.send('{"type": "subscribe", "channel": "uploads"}');
+   *
+   * // Send binary data
+   * const buffer = new Uint8Array([1, 2, 3, 4]);
+   * ws.send(buffer);
+   * ```
+   */
+  send(data: string | Uint8Array): void {
+    this.native.send(data);
+  }
+
+  /**
+   * Closes the WebSocket connection.
+   *
+   * Optionally accepts a close code and reason that will be sent to the server.
+   * Standard close codes include:
+   * - 1000: Normal closure
+   * - 1001: Going away (e.g., page navigation)
+   * - 1002: Protocol error
+   * - 1003: Unsupported data
+   *
+   * @param code - Optional close code (default: 1000 for normal closure)
+   * @param reason - Optional human-readable reason for closing
+   *
+   * @example
+   * ```typescript
+   * // Normal close
+   * ws.close();
+   *
+   * // Close with reason
+   * ws.close(1000, 'Upload completed');
+   *
+   * // Close due to error
+   * ws.close(1011, 'Internal error during upload');
+   * ```
+   */
+  close(code?: number, reason?: string): void {
+    this.native.close(code, reason);
+  }
+}
+
+/**
+ * Creates a factory for browser WebSocket connections.
+ *
+ * This factory is used by the Uploadista client to create WebSocket connections
+ * for real-time features. It wraps the browser's native WebSocket API and provides
+ * a consistent interface for the client.
+ *
+ * The factory creates WebSockets that support:
+ * - Real-time upload progress updates
+ * - Flow execution status streaming
+ * - Live error and event notifications
+ * - Bidirectional client-server communication
+ *
+ * @returns A WebSocketFactory that creates browser-compatible WebSocket connections
+ *
+ * @example
+ * ```typescript
+ * import { createBrowserWebSocketFactory } from '@uploadista/client-browser';
+ *
+ * const factory = createBrowserWebSocketFactory();
+ *
+ * // Create a WebSocket connection
+ * const ws = factory.create('wss://api.example.com/ws/upload/123');
+ *
+ * // Set up event handlers
+ * ws.onmessage = (event) => {
+ *   const data = JSON.parse(event.data);
+ *   if (data.type === 'progress') {
+ *     console.log('Upload progress:', data.progress);
+ *   }
+ * };
+ *
+ * ws.onopen = () => {
+ *   console.log('WebSocket connected');
+ * };
+ *
+ * ws.onclose = (event) => {
+ *   console.log('WebSocket closed:', event.code, event.reason);
+ * };
+ * ```
+ *
+ * @see {@link BrowserWebSocket} for the WebSocket implementation details
+ */
+export const createBrowserWebSocketFactory = (): WebSocketFactory => ({
+  create: (url: string): WebSocketLike => new BrowserWebSocket(url),
+});

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from "./upload-input";

package/src/types/upload-input.ts

@@ -0,0 +1,25 @@
+/**
+ * Browser-specific upload input types that can be used with the Uploadista client.
+ *
+ * In the browser environment, files can be provided as either:
+ * - `File` objects from file input elements or drag-and-drop
+ * - `Blob` objects created programmatically or from other sources
+ *
+ * Both types use the browser's File API and can be chunked for upload.
+ *
+ * @example
+ * ```typescript
+ * // From file input
+ * const fileInput = document.querySelector<HTMLInputElement>('input[type="file"]');
+ * const file: BrowserUploadInput = fileInput.files[0];
+ *
+ * // From drag and drop
+ * element.addEventListener('drop', (e) => {
+ *   const file: BrowserUploadInput = e.dataTransfer.files[0];
+ * });
+ *
+ * // From Blob
+ * const blob: BrowserUploadInput = new Blob(['content'], { type: 'text/plain' });
+ * ```
+ */
+export type BrowserUploadInput = Blob | File;

package/src/utils/hash-util.ts

@@ -0,0 +1,79 @@
+/**
+ * Computes the SHA-256 checksum of a Blob using the Web Crypto API.
+ *
+ * This utility function provides a browser-native way to compute cryptographic
+ * hashes of file data. It uses the SubtleCrypto API (part of Web Crypto) which
+ * provides hardware-accelerated cryptographic operations when available.
+ *
+ * The SHA-256 algorithm produces a 256-bit (32-byte) hash value, typically
+ * rendered as a 64-character hexadecimal string. SHA-256 is widely used for:
+ * - File integrity verification
+ * - Content deduplication
+ * - File fingerprinting
+ * - Checksum validation
+ *
+ * **Performance note:** For large files (>100MB), this function loads the entire
+ * file into memory before hashing. For extremely large files, consider chunked
+ * hashing approaches if memory is a concern.
+ *
+ * @param blob - The Blob or File to hash
+ * @returns Promise resolving to the hex-encoded SHA-256 hash
+ *
+ * @throws {Error} When the hash computation fails (e.g., out of memory, crypto API unavailable)
+ *
+ * @example
+ * ```typescript
+ * import { computeblobSha256 } from '@uploadista/client-browser';
+ *
+ * // Hash a File from input
+ * const fileInput = document.querySelector('input[type="file"]');
+ * const file = fileInput.files[0];
+ * const hash = await computeblobSha256(file);
+ * console.log('File SHA-256:', hash);
+ * // Output: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ *
+ * // Hash a Blob
+ * const blob = new Blob(['Hello, World!'], { type: 'text/plain' });
+ * const hash = await computeblobSha256(blob);
+ * console.log('Blob SHA-256:', hash);
+ *
+ * // Verify file integrity
+ * const expectedHash = 'abc123...';
+ * const actualHash = await computeblobSha256(file);
+ * if (actualHash === expectedHash) {
+ *   console.log('File integrity verified');
+ * } else {
+ *   console.error('File has been modified or corrupted');
+ * }
+ *
+ * // Check for duplicate files
+ * const file1Hash = await computeblobSha256(file1);
+ * const file2Hash = await computeblobSha256(file2);
+ * if (file1Hash === file2Hash) {
+ *   console.log('Files are identical (same content)');
+ * }
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest} for SubtleCrypto.digest API
+ */
+export async function computeblobSha256(blob: Blob): Promise<string> {
+  try {
+    // Read blob as ArrayBuffer
+    const arrayBuffer = await blob.arrayBuffer();
+
+    // Compute SHA-256 hash using Web Crypto API
+    const hashBuffer = await crypto.subtle.digest("SHA-256", arrayBuffer);
+
+    // Convert hash to hex string
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray
+      .map((byte) => byte.toString(16).padStart(2, "0"))
+      .join("");
+
+    return hashHex;
+  } catch (error) {
+    throw new Error(
+      `Failed to compute file checksum: ${error instanceof Error ? error.message : "Unknown error"}`,
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "@uploadista/typescript-config/base.json",
+  "compilerOptions": {
+    "lib": ["ES2020", "DOM"],
+    "baseUrl": "./",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "typeRoots": ["../../node_modules/@types"],
+    "types": [],
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/__tests__/**",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/framework-utils.ts","./src/http-client.ts","./src/index.ts","./src/client/create-uploadista-client.ts","./src/client/index.ts","./src/services/abort-controller-factory.ts","./src/services/checksum-service.ts","./src/services/create-browser-services.ts","./src/services/file-reader.ts","./src/services/fingerprint-service.ts","./src/services/platform-service.ts","./src/services/websocket-factory.ts","./src/services/id-generation/id-generation.ts","./src/services/storage/local-storage-service.ts","./src/services/storage/session-storage-service.ts","./src/types/index.ts","./src/types/upload-input.ts","./src/utils/hash-util.ts"],"version":"5.9.3"}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    exclude: ['node_modules', 'dist'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'dist/', '**/*.d.ts', '**/*.test.ts', '**/*.spec.ts']
+    }
+  }
+});