@uploadista/client-browser 0.0.3

package/dist/services/storage/session-storage-service.js

@@ -0,0 +1,179 @@
+/**
+ * Creates a browser storage service using sessionStorage for temporary data storage.
+ *
+ * This service provides a key-value storage interface backed by the browser's
+ * sessionStorage API. Unlike localStorage, data stored with sessionStorage is
+ * only available for the duration of the page session and is cleared when the
+ * browser tab or window is closed.
+ *
+ * Use cases include:
+ * - Temporary upload state during a session
+ * - One-time authentication tokens
+ * - Transient UI state
+ * - Session-specific preferences
+ *
+ * **Key differences from localStorage:**
+ * - Data persists only for the current browser tab/window session
+ * - Each tab has its own isolated sessionStorage
+ * - Data is cleared when the tab/window is closed
+ * - Page reloads preserve sessionStorage (unlike in-memory storage)
+ * - Same storage quota limits as localStorage (5-10MB)
+ *
+ * @returns A StorageService backed by browser sessionStorage
+ *
+ * @example
+ * ```typescript
+ * import { createSessionStorageService } from '@uploadista/client-browser';
+ *
+ * const storage = createSessionStorageService();
+ *
+ * // Store temporary upload state
+ * await storage.setItem('temp-upload:abc', JSON.stringify({
+ *   fileId: 'abc',
+ *   started: Date.now()
+ * }));
+ *
+ * // Retrieve within same session
+ * const data = await storage.getItem('temp-upload:abc');
+ * if (data) {
+ *   const state = JSON.parse(data);
+ *   console.log('Upload started at', new Date(state.started));
+ * }
+ *
+ * // Find all temporary uploads
+ * const tempUploads = await storage.find('temp-upload:');
+ *
+ * // Clean up
+ * await storage.removeItem('temp-upload:abc');
+ * // OR: Close tab/window to clear all sessionStorage
+ * ```
+ *
+ * @see {@link createLocalStorageService} for persistent storage
+ */
+export function createSessionStorageService() {
+    /**
+     * Internal helper to find entries matching a prefix.
+     *
+     * Iterates through all sessionStorage keys and returns those that start
+     * with the specified prefix along with their values.
+     *
+     * @param prefix - Key prefix to filter by
+     * @returns Object mapping matching keys to their values
+     * @private
+     */
+    const findEntries = (prefix) => {
+        const results = {};
+        for (const key in sessionStorage) {
+            if (key.startsWith(prefix)) {
+                const item = sessionStorage.getItem(key);
+                if (item) {
+                    results[key] = item;
+                }
+            }
+        }
+        return results;
+    };
+    return {
+        /**
+         * Retrieves a value from sessionStorage by key.
+         *
+         * @param key - The key to retrieve
+         * @returns Promise resolving to the value, or null if the key doesn't exist
+         *
+         * @example
+         * ```typescript
+         * const token = await storage.getItem('session:auth-token');
+         * if (token) {
+         *   // Use token for requests
+         * }
+         * ```
+         */
+        async getItem(key) {
+            return sessionStorage.getItem(key);
+        },
+        /**
+         * Stores a value in sessionStorage.
+         *
+         * If the key already exists, its value will be overwritten.
+         * Values must be strings; use JSON.stringify() for objects.
+         * Data will be cleared when the browser tab/window is closed.
+         *
+         * @param key - The key to store under
+         * @param value - The string value to store
+         *
+         * @throws {QuotaExceededError} If sessionStorage quota is exceeded
+         *
+         * @example
+         * ```typescript
+         * // Store temporary state
+         * await storage.setItem('wizard:step', '2');
+         *
+         * // Store temporary object
+         * await storage.setItem('temp:upload', JSON.stringify({
+         *   progress: 50,
+         *   paused: false
+         * }));
+         * ```
+         */
+        async setItem(key, value) {
+            sessionStorage.setItem(key, value);
+        },
+        /**
+         * Removes a value from sessionStorage by key.
+         *
+         * If the key doesn't exist, this is a no-op (no error is thrown).
+         *
+         * @param key - The key to remove
+         *
+         * @example
+         * ```typescript
+         * // Clean up temporary data
+         * await storage.removeItem('temp:upload:123');
+         * ```
+         */
+        async removeItem(key) {
+            sessionStorage.removeItem(key);
+        },
+        /**
+         * Retrieves all entries from sessionStorage.
+         *
+         * Returns an object mapping every key in sessionStorage to its value.
+         * This only includes data for the current tab/window.
+         *
+         * @returns Promise resolving to object with all key-value pairs
+         *
+         * @example
+         * ```typescript
+         * const all = await storage.findAll();
+         * console.log('Session items:', Object.keys(all).length);
+         * ```
+         */
+        async findAll() {
+            return findEntries("");
+        },
+        /**
+         * Finds all entries with keys starting with a given prefix.
+         *
+         * Useful for querying related session data. For example, use "temp:"
+         * prefix to find all temporary entries.
+         *
+         * @param prefix - The key prefix to search for
+         * @returns Promise resolving to object with matching key-value pairs
+         *
+         * @example
+         * ```typescript
+         * // Find all temporary uploads in this session
+         * const tempUploads = await storage.find('temp-upload:');
+         * for (const [key, value] of Object.entries(tempUploads)) {
+         *   console.log('Temp upload:', key, JSON.parse(value));
+         * }
+         *
+         * // Find wizard state
+         * const wizardState = await storage.find('wizard:');
+         * ```
+         */
+        async find(prefix) {
+            return findEntries(prefix);
+        },
+    };
+}

package/dist/services/websocket-factory.d.ts

@@ -0,0 +1,46 @@
+import type { WebSocketFactory } from "@uploadista/client-core";
+/**
+ * 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 declare const createBrowserWebSocketFactory: () => WebSocketFactory;
+//# sourceMappingURL=websocket-factory.d.ts.map

package/dist/services/websocket-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-factory.d.ts","sourceRoot":"","sources":["../../src/services/websocket-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,yBAAyB,CAAC;AAsK/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,6BAA6B,QAAO,gBAE/C,CAAC"}

package/dist/services/websocket-factory.js

@@ -0,0 +1,196 @@
+/**
+ * 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 {
+    /** WebSocket is currently connecting (readyState = 0) */
+    CONNECTING = 0;
+    /** WebSocket connection is open and ready (readyState = 1) */
+    OPEN = 1;
+    /** WebSocket is closing (readyState = 2) */
+    CLOSING = 2;
+    /** WebSocket connection is closed (readyState = 3) */
+    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;
+    /** Event handler called when the connection is established */
+    onopen = null;
+    /** Event handler called when the connection is closed */
+    onclose = null;
+    /** Event handler called when an error occurs */
+    onerror = null;
+    /** Event handler called when a message is received */
+    onmessage = null;
+    native;
+    /**
+     * 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) {
+        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;
+            this.onclose?.({ code: closeEvent.code, reason: closeEvent.reason });
+        };
+        this.native.onerror = (_event) => {
+            this.onerror?.({ message: "WebSocket error" });
+        };
+        this.native.onmessage = (event) => {
+            const messageEvent = event;
+            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) {
+        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, reason) {
+        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 = () => ({
+    create: (url) => new BrowserWebSocket(url),
+});

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./upload-input";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/types/index.js

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

package/dist/types/upload-input.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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;
+//# sourceMappingURL=upload-input.d.ts.map

package/dist/types/upload-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-input.d.ts","sourceRoot":"","sources":["../../src/types/upload-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/dist/types/upload-input.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/hash-util.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare function computeblobSha256(blob: Blob): Promise<string>;
+//# sourceMappingURL=hash-util.d.ts.map

package/dist/utils/hash-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-util.d.ts","sourceRoot":"","sources":["../../src/utils/hash-util.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBnE"}

package/dist/utils/hash-util.js

@@ -0,0 +1,75 @@
+/**
+ * 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) {
+    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/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@uploadista/client-browser",
+  "type": "module",
+  "version": "0.0.3",
+  "description": "Browser client for Uploadista",
+  "license": "MIT",
+  "author": "Uploadista",
+  "exports": {
+    ".": "./src/index.ts",
+    "./flow": "./src/flow/index.ts",
+    "./upload": "./src/upload/index.ts",
+    "./framework-utils": "./src/framework-utils.ts"
+  },
+  "dependencies": {
+    "js-base64": "3.7.8",
+    "@uploadista/core": "0.0.3",
+    "@uploadista/client-core": "0.0.3"
+  },
+  "devDependencies": {
+    "vitest": "3.2.4",
+    "@uploadista/typescript-config": "0.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "format": "biome format --write ./src",
+    "lint": "biome lint --write ./src",
+    "check": "biome check --write ./src ",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:watch": "vitest --watch"
+  }
+}